TrainObservation — SDK 0.9 — Wiki NimbyRails France

Usage context

Module	Package	SDK source
Kotlin/Native	nimby	kotlin/src/nimby/TrainObservation.kt

Public API for SDK 0.9.0-alpha.2. Each entry provides the Kotlin signature and its contract: what the value means, conditions of use and effects to understand. Choose imports from the module shown above.

Imports on this page

import nimby.GameInstant
import nimby.TrainState
import nimby.TrainAlert
import nimby.Station
import nimby.Line
import nimby.TrainPosition
import nimby.TrainAssignment
import nimby.TrainServiceTimes
import nimby.TrainService
import nimby.Train
import nimby.TrainSnapshot
import nimby.Stop
import nimby.LinePlan

Choose a read and interpret its results

In a mod, use ToolContext.trains(query). In a JVM application, use game.trains.snapshot(query = query); selecting a train also requests its line plan. One query batches all trains: do not create a snapshot per train. Clock reads and targeted single-train reads are separate.

TrainQuery option	Default	Requested data
includeService	true	Observed state, service and assignment.
includeLocations	true	Positions and required location references.
includeCharacteristics	false	Configured and current material profiles.
includeTimetables	false	Available timetable information; implies includeService.
includeTags	false	Declared tags and inheritance references; implies includeLines.
includePassengers	false	Observed occupants, distinct from capacity.
includeLines	false	Line catalog, including lines with no assigned train.
includeComposition	false	Ordered vehicles of configured and current compositions and referenced models.

Value	Unit and contract
Train.speedMps / Train.speedKmh	Current speed. Native: an unavailable measurement remains null. JVM: also check speedDefaulted before treating a fallback value as a measurement.
maximumSpeedMps / maximumSpeedKmh	Material maximum speed, in m/s or km/h; distinct from current speed and the track speed limit.
lengthM / emptyMassKg / maximumAccelerationMps2	Metres, kilograms, metres per second squared.
powerW / tractiveForceN	Watts and newtons.
passengers / passengerCapacity / carCount	Occupants, capacity and vehicle count: three distinct quantities.
configured / current / composition	Independent profiles, without filling missing values from one another. Null composition: unknown or unrequested; empty list: observed empty composition.
predictedArrivalDelayUs / predictedArrivalDelaySeconds	Signed estimate in microseconds or seconds; negative for predicted early arrival. Neither deadline age nor priority.
arrivalOffsetSeconds / departureOffsetSeconds	Validated offsets in seconds from the line-plan origin. Do not convert them into a train’s absolute date.
arrivalTimeUs / departureTimeUs / dispatchRetryTimeUs	Microseconds from the simulation origin, not 1970. Use calendar helpers; dates remain null when the origin is unknown.
capturedAtMillis / ageMillis	Computer UTC time / monotonic age when copying; distinct from the game calendar.

Typed identifiers are opaque. TimetableShiftId is unique only together with its TimetableId. LineType distinguishes only Depot and Other; no passenger/freight category is inferred. An unavailable timetable name remains null. Tags are labels without automatic priority; incomplete or cyclic inheritance remains unknown. VehicleModel.nameEnglish retains the English catalog name.

TrainVehicle describes a vehicle within a composition. The nimby.Vehicle type used in driving calculations is a different contract. Do not mix identically named classes from nimby and fr.nimby.sdk.

GameInstant

nimby · class

data class GameInstant(val utcSeconds: Long, val microsecond: Int = 0)

UTC instant in the game calendar, at microsecond precision. Years 1 through 9999; microsecond ranges from 0 to 999999. Conversions do not read the game.

GameInstant.utcSeconds

nimby · val

val utcSeconds: Long

UTC seconds since 1970 in the game calendar; may be negative.

GameInstant.microsecond

nimby · val

val microsecond: Int = 0

Fraction of the second between 0 and 999999.

GameInstant.dateTime

nimby · fun

fun dateTime(): GameDateTime

Converts seconds into game UTC date/time; the microsecond fraction is not part of the returned GameDateTime.

TrainState

nimby · class

enum class TrainState {
    Unknown,
    Driving,
    StationStop,
    TimedStop,
    Depot,
    DispatchWait,
    SignalWait,
    Mothballed,
    NotPresent,
    Other
}

Observed service state. null means unavailable; Unknown and Other are observed results, not missing data.

TrainState.Unknown

nimby · enum-entry

Unknown

The game reports an undetermined state.

TrainState.Driving

nimby · enum-entry

Driving

Reported driving state; does not prove strictly positive speed.

TrainState.StationStop

nimby · enum-entry

StationStop

Reported station stop.

TrainState.TimedStop

nimby · enum-entry

TimedStop

Reported timed stop.

TrainState.Depot

nimby · enum-entry

Depot

Reported depot state.

TrainState.DispatchWait

nimby · enum-entry

DispatchWait

Reported dispatch wait.

TrainState.SignalWait

nimby · enum-entry

SignalWait

Reported signal wait; this field alone does not describe the signal rule.

TrainState.Mothballed

nimby · enum-entry

Mothballed

Train mothballed according to the reported state.

TrainState.NotPresent

nimby · enum-entry

NotPresent

Train reported as not present; distinct from an object missing from the snapshot.

TrainState.Other

nimby · enum-entry

Other

Observed state not represented by another known enum value.

TrainAlert

nimby · class

enum class TrainAlert {
    None,
    LineClosed,
    NoPath,
    InvalidOrders,
    Collision,
    SignalWait,
    ScheduleClosed,
    DispatchTracksOccupied,
    NoServices,
    ServicesAlreadyAssigned,
    Other
}

Observed train alert. null means unavailable; None means no reported alert. An alert is not a priority.

TrainAlert.None

nimby · enum-entry

None

No reported alert.

TrainAlert.LineClosed

nimby · enum-entry

LineClosed

Reported closed line.

TrainAlert.NoPath

nimby · enum-entry

NoPath

Reported missing path.

TrainAlert.InvalidOrders

nimby · enum-entry

InvalidOrders

Reported invalid orders.

TrainAlert.Collision

nimby · enum-entry

Collision

Collision reported by the game.

TrainAlert.SignalWait

nimby · enum-entry

SignalWait

Signal-wait alert.

TrainAlert.ScheduleClosed

nimby · enum-entry

ScheduleClosed

Reported closed schedule.

TrainAlert.DispatchTracksOccupied

nimby · enum-entry

DispatchTracksOccupied

Dispatch tracks occupied according to the game.

TrainAlert.NoServices

nimby · enum-entry

NoServices

No services available according to the game.

TrainAlert.ServicesAlreadyAssigned

nimby · enum-entry

ServicesAlreadyAssigned

Services already assigned according to the game.

TrainAlert.Other

nimby · enum-entry

Other

Other observed alert code, not represented by known values.

Station

nimby · class

data class Station(val id: Long, val name: String?)

Station joined into a train or line-plan observation. A missing name does not prove the station does not exist.

Station.id

nimby · val

val id: Long

Opaque value to compare and pass unchanged; do not decode it or reuse it in another game.

Station.name

nimby · val

val name: String?

Observed name; null when unavailable.

Station.stationId

nimby · val

val stationId: StationId

The same identity as a StationId.

Line

nimby · class

data class Line(val id: Long, val name: String?, val isDepot: Boolean?, val parentLineId: LineId? = null,
                val parentInformationAvailable: Boolean = false, val declaredTags: List<Tag>? = null)

Line observed in a service or catalogue. Parent and tag information is available only when requested and validated.

Line.id

nimby · val

val id: Long

Opaque value to compare and pass unchanged; do not decode it or reuse it in another game.

Line.name

nimby · val

val name: String?

Observed line name; null when unavailable.

Line.isDepot

nimby · val

val isDepot: Boolean?

true: depot; false: another observed type; null: unknown classification.

Line.parentLineId

nimby · val

val parentLineId: LineId? = null

Parent identity; interpret null together with parentInformationAvailable.

Line.parentInformationAvailable

nimby · val

val parentInformationAvailable: Boolean = false

true: parent information was observed, including no parent. false: an absent parent remains unknown.

Line.declaredTags

nimby · val

val declaredTags: List<Tag>? = null

Tags declared directly on this object, without implicit inheritance. null: unavailable or unrequested; empty list: no observed declared tags.

Line.lineId

nimby · val

val lineId: LineId

The same identity as a LineId.

Line.type

nimby · val

val type: LineType?

Classification derived from isDepot: Depot, Other or null.

TrainPosition

nimby · class

data class TrainPosition(val trackId: Long, val fraction: Double, val direction: Int?, val station: Station?)

Copied train position on a track. The fraction describes longitudinal position, not a distance in metres or a reservation.

TrainPosition.trackId

nimby · val

val trackId: Long

Opaque value to compare and pass unchanged; do not decode it or reuse it in another game.

TrainPosition.fraction

nimby · val

val fraction: Double

Position between 0 and 1 relative to the track origin.

TrainPosition.direction

nimby · val

val direction: Int?

+1 from A to B, -1 from B to A; null when unknown.

TrainPosition.station

nimby · val

val station: Station?

Station joined to the position track; null when no usable join exists.

TrainPosition.track

nimby · val

val track: TrackId

Track identity as a TrackId.

TrainAssignment

nimby · class

data class TrainAssignment(val scheduleId: Long?, val shiftId: Long?, val orderIndex: Int?)

Observed train assignment to a timetable, shift and order. Does not announce a calculated next passing time.

TrainAssignment.scheduleId

nimby · val

val scheduleId: Long?

Opaque assigned timetable identity; null when unavailable.

TrainAssignment.shiftId

nimby · val

val shiftId: Long?

Shift key within scheduleId; do not compare it alone across timetables.

TrainAssignment.orderIndex

nimby · val

val orderIndex: Int?

Observed zero-based order index; null when unavailable.

TrainAssignment.timetable

nimby · val

val timetable: Timetable?

Timetable built from scheduleId, with identity only; null if scheduleId is missing.

TrainAssignment.shift

nimby · val

val shift: TimetableShiftId?

Composite identity available only when timetable and shift key are known.

TrainServiceTimes

nimby · class

data class TrainServiceTimes(
    val gameEpochSeconds: Long?, val gameTimeUs: Long?,
    val arrivalTimeUs: Long?, val departureTimeUs: Long?, val dispatchRetryTimeUs: Long?,
    val arrivalRemainingSeconds: Double?, val departureRemainingSeconds: Double?, val dispatchRetryRemainingSeconds: Double?,
)

Observed active deadlines and remaining times. A duration can be available without a calendar origin. Conversions preserve null; no future date is extrapolated.

TrainServiceTimes.gameEpochSeconds

nimby · val

val gameEpochSeconds: Long?

UTC simulation-calendar origin in seconds since 1970; null when unknown.

TrainServiceTimes.gameTimeUs

nimby · val

val gameTimeUs: Long?

Observed counter in microseconds from the simulation origin; not a Unix date.

TrainServiceTimes.arrivalTimeUs

nimby · val

val arrivalTimeUs: Long?

Optional active arrival deadline in microseconds from the simulation origin.

TrainServiceTimes.departureTimeUs

nimby · val

val departureTimeUs: Long?

Optional active departure deadline in microseconds from the simulation origin.

TrainServiceTimes.dispatchRetryTimeUs

nimby · val

val dispatchRetryTimeUs: Long?

Dispatch-retry deadline in microseconds from the simulation origin.

TrainServiceTimes.arrivalRemainingSeconds

nimby · val

val arrivalRemainingSeconds: Double?

Seconds remaining to the arrival deadline; may be negative. Not predicted commercial delay.

TrainServiceTimes.departureRemainingSeconds

nimby · val

val departureRemainingSeconds: Double?

Seconds remaining to the departure deadline, clamped to zero; null when unknown.

TrainServiceTimes.dispatchRetryRemainingSeconds

nimby · val

val dispatchRetryRemainingSeconds: Double?

Seconds remaining before a dispatch retry, clamped to zero; null when unknown.

TrainServiceTimes.observedAt

nimby · val

val observedAt: GameInstant?

Observed counter converted to the game UTC calendar; null if origin/counter is missing or conversion is out of range.

TrainServiceTimes.arrival

nimby · val

val arrival: GameInstant?

UTC date of the active arrival deadline. null if conversion is impossible; not necessarily the commercial timetable.

TrainServiceTimes.departure

nimby · val

val departure: GameInstant?

UTC date of the active departure deadline. null if conversion is impossible; not necessarily the commercial timetable.

TrainServiceTimes.dispatchRetry

nimby · val

val dispatchRetry: GameInstant?

UTC dispatch-retry date; not a commercial departure time. null when not convertible.

TrainService

nimby · class

data class TrainService(
    val state: TrainState?, val alert: TrainAlert?, val hidden: Boolean?, val onNetwork: Boolean?,
    val locationTrackId: Long?, val locationStation: TrainStation?, val line: TrainLine?,
    val stopTrackId: Long?, val stopStation: TrainStation?, val stopIndex: Int?, val times: TrainServiceTimes,
)

Observed train service, with independently optional state, locations and deadlines. Position station, service location and target stop are not interchangeable.

TrainService.state

nimby · val

val state: TrainState?

Service state; null means unavailable, unlike TrainState.Unknown.

TrainService.alert

nimby · val

val alert: TrainAlert?

Optional observed alert; None is an observation without an alert.

TrainService.hidden

nimby · val

val hidden: Boolean?

Hidden visibility reported by the game; null when unknown.

TrainService.onNetwork

nimby · val

val onNetwork: Boolean?

Reported network presence; null when unknown. Does not prove movement permission.

TrainService.locationTrackId

nimby · val

val locationTrackId: Long?

Track of the observed service location; may differ from the position track.

TrainService.locationStation

nimby · val

val locationStation: TrainStation?

Station of the observed service location; a missing join does not prove no station exists.

TrainService.line

nimby · val

val line: TrainLine?

Service line; null when unavailable.

TrainService.stopTrackId

nimby · val

val stopTrackId: Long?

Track of the currently targeted stop; null when unknown.

TrainService.stopStation

nimby · val

val stopStation: TrainStation?

Station of the target stop, when resolved.

TrainService.stopIndex

nimby · val

val stopIndex: Int?

Zero-based current stop index in the line; null when unknown.

TrainService.times

nimby · val

val times: TrainServiceTimes

Service deadlines; each value retains its own availability.

Train

nimby · class

data class Train(
    val id: Long, val name: String, val position: TrainPosition?, val speedMps: Double?,
    val speedDefaulted: Boolean, val passengers: Int?, val assignment: TrainAssignment?, val service: TrainService?,
    val declaredTags: List<Tag>? = null, val predictedArrivalDelayUs: Long? = null,
    val configured: TrainCharacteristics? = null, val current: TrainCharacteristics? = null,
)

Copied train record. TrainQuery groups determine optional data; unknown values remain null, without implicit reads.

Train.id

nimby · val

val id: Long

Opaque value to compare and pass unchanged; do not decode it or reuse it in another game.

Train.name

nimby · val

val name: String

Train name in this observation; does not replace its identity.

Train.position

nimby · val

val position: TrainPosition?

Copied position when observable; null when absent or unavailable.

Train.speedMps

nimby · val

val speedMps: Double?

Measured speed in metres per second; null when unknown or replaced with a fallback.

Train.speedDefaulted

nimby · val

val speedDefaulted: Boolean

Indicates a fallback game speed. Measured speed remains unknown in this case; it does not prove a stop.

Train.passengers

nimby · val

val passengers: Int?

Observed occupants, only when requested; null does not mean zero.

Train.assignment

nimby · val

val assignment: TrainAssignment?

Observed assignment; null when unavailable or unrequested.

Train.service

nimby · val

val service: TrainService?

Observed service, possibly partial: a location read can supply presence and places without service state. Callback options may also have accumulated. null indicates that no usable part was supplied.

Train.declaredTags

nimby · val

val declaredTags: List<Tag>? = null

Tags declared directly on this object, without implicit inheritance. null: unavailable or unrequested; empty list: no observed declared tags.

Train.predictedArrivalDelayUs

nimby · val

val predictedArrivalDelayUs: Long? = null

Game-estimated arrival delay in signed microseconds; negative means predicted early arrival. null when unknown. Neither a deadline’s age nor a priority.

Train.configured

nimby · val

val configured: TrainCharacteristics? = null

Explicitly requested configured/purchased train profile. Independent of current material: its values do not replace missing current values.

Train.current

nimby · val

val current: TrainCharacteristics? = null

Characteristics of the current composition, when observable and requested. Do not substitute the configured profile.

Train.trainId

nimby · val

val trainId: TrainId

The same identity as a TrainId.

Train.speedKmh

nimby · val

val speedKmh: Double?

Measured speed converted to km/h; null remains null.

Train.predictedArrivalDelaySeconds

nimby · val

val predictedArrivalDelaySeconds: Double?

The same arrival estimate converted from microseconds to seconds; preserves its sign and null.

TrainSnapshot

nimby · class

class TrainSnapshot

Train copy obtained from ToolContext.trains. Retainable after the callback; lookups read only this copy. Data is validated separately without freezing a simulation tick.

TrainSnapshot.worldId

nimby · val

val worldId: String

Observed world identity; retain it with its generation to identify the scope of the data.

TrainSnapshot.generation

nimby · val

val generation: Long

Observed game generation. Invalidate derived data when it changes, even when reloading the same save.

TrainSnapshot.capturedAtMillis

nimby · val

val capturedAtMillis: Long

Computer UTC timestamp in milliseconds since 1970. It does not measure simulation time.

TrainSnapshot.ageMillis

nimby · val

val ageMillis: Long

Monotonic snapshot age when copied, in milliseconds; does not update afterwards.

TrainSnapshot.clock

nimby · val

val clock: ToolClock?

Observed simulation clock; null when unavailable.

TrainSnapshot.trains

nimby · val

val trains: List<TrainObservation>

Trains copied according to the query; optional fields reflect requested groups.

TrainSnapshot.vehicleModels

nimby · val

val vehicleModels: List<VehicleModel>? = null

Models referenced by requested compositions; null when unrequested or unavailable.

TrainSnapshot.get

nimby · fun

operator fun get(id: Long): TrainObservation?

Indexed lookup in copied trains; null if the identity is absent. No new observation.

TrainSnapshot.get

nimby · fun

operator fun get(id: TrainId): Train?

The same local lookup with a typed identity; null when absent from this snapshot.

TrainSnapshot.lines

nimby · val

val lines: List<Line>?

Requested line catalogue, including lines without assigned trains; null when unknown or unrequested.

TrainSnapshot.tags

nimby · val

val tags: List<Tag>?

Requested tag catalogue; null when unknown or unrequested.

TrainSnapshot.line

nimby · fun

fun line(id: LineId): Line?

Line from the copied catalogue; null when absent, unavailable or unrequested.

TrainSnapshot.tag

nimby · fun

fun tag(id: TagId): Tag?

Tag from the copied catalogue; null when absent, unavailable or unrequested.

TrainSnapshot.tagsForLine

nimby · fun

fun tagsForLine(id: LineId): List<Tag>?

Combines declared tags from the line and its parents without duplicates. null if a link is unknown, cyclic or out of bounds; empty list only for known inheritance without tags.

Stop

nimby · class

data class Stop(val index: Int, val trackId: Long, val station: Station?,
                         val arrivalOffsetSeconds: Int?, val departureOffsetSeconds: Int?)

Stop or waypoint in a line plan. May be outside a station; offsets remain relative to the plan.

Stop.index

nimby · val

val index: Int

Zero-based stop index in the line plan.

Stop.trackId

nimby · val

val trackId: Long

Opaque value to compare and pass unchanged; do not decode it or reuse it in another game.

Stop.station

nimby · val

val station: Station?

Joined station, when available; a waypoint can be outside stations.

Stop.arrivalOffsetSeconds

nimby · val

val arrivalOffsetSeconds: Int?

Arrival offset in seconds from the plan origin; null when unknown. Not an absolute train date.

Stop.departureOffsetSeconds

nimby · val

val departureOffsetSeconds: Int?

Departure offset in seconds from the plan origin; null when unknown.

Stop.track

nimby · val

val track: TrackId

Typed identity of the stop track.

Stop.plannedDwellSeconds

nimby · val

val plannedDwellSeconds: Long?

departureOffsetSeconds minus arrivalOffsetSeconds, in seconds; null if either offset is missing.

LinePlan

nimby · class

data class LinePlan(val trainId: Long, val line: Line, val stops: List<Stop>,
                    val worldId: String, val generation: Long, val capturedAtMillis: Long)

Complete plan of the line associated with the train in this snapshot, obtained from ToolContext.linePlan. May contain stops outside the train’s partial run.

LinePlan.trainId

nimby · val

val trainId: Long

Opaque value to compare and pass unchanged; do not decode it or reuse it in another game.

LinePlan.line

nimby · val

val line: Line

Observed line associated with the train.

LinePlan.stops

nimby · val

val stops: List<Stop>

Stops in the full plan, in order; do not convert them directly into the train’s next passing times.

LinePlan.worldId

nimby · val

val worldId: String

Observed world identity; retain it with its generation to identify the scope of the data.

LinePlan.generation

nimby · val

val generation: Long

Observed game generation. Invalidate derived data when it changes, even when reloading the same save.

LinePlan.capturedAtMillis

nimby · val

val capturedAtMillis: Long

Computer UTC timestamp in milliseconds since 1970. It does not measure simulation time.

LinePlan.train

nimby · val

val train: TrainId

Typed identity of the train used to request this plan.