TrainServices — SDK 0.9 — Wiki NimbyRails France

Usage context

Module	Package	SDK source
Kotlin/JVM	fr.nimby.sdk	kotlin-client/src/main/kotlin/fr/nimby/sdk/TrainServices.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 fr.nimby.sdk.TrainState
import fr.nimby.sdk.TrainAlert
import fr.nimby.sdk.TrainRecord

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.

TrainState

fr.nimby.sdk · 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

fr.nimby.sdk · enum-entry

Unknown

The game reports an undetermined state.

TrainState.Driving

fr.nimby.sdk · enum-entry

Driving

Reported driving state; does not prove strictly positive speed.

TrainState.StationStop

fr.nimby.sdk · enum-entry

StationStop

Reported station stop.

TrainState.TimedStop

fr.nimby.sdk · enum-entry

TimedStop

Reported timed stop.

TrainState.Depot

fr.nimby.sdk · enum-entry

Depot

Reported depot state.

TrainState.DispatchWait

fr.nimby.sdk · enum-entry

DispatchWait

Reported dispatch wait.

TrainState.SignalWait

fr.nimby.sdk · enum-entry

SignalWait

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

TrainState.Mothballed

fr.nimby.sdk · enum-entry

Mothballed

Train mothballed according to the reported state.

TrainState.NotPresent

fr.nimby.sdk · enum-entry

NotPresent

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

TrainState.Other

fr.nimby.sdk · enum-entry

Other

Observed state not represented by another known enum value.

TrainAlert

fr.nimby.sdk · 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

fr.nimby.sdk · enum-entry

None

No reported alert.

TrainAlert.LineClosed

fr.nimby.sdk · enum-entry

LineClosed

Reported closed line.

TrainAlert.NoPath

fr.nimby.sdk · enum-entry

NoPath

Reported missing path.

TrainAlert.InvalidOrders

fr.nimby.sdk · enum-entry

InvalidOrders

Reported invalid orders.

TrainAlert.Collision

fr.nimby.sdk · enum-entry

Collision

Collision reported by the game.

TrainAlert.SignalWait

fr.nimby.sdk · enum-entry

SignalWait

Signal-wait alert.

TrainAlert.ScheduleClosed

fr.nimby.sdk · enum-entry

ScheduleClosed

Reported closed schedule.

TrainAlert.DispatchTracksOccupied

fr.nimby.sdk · enum-entry

DispatchTracksOccupied

Dispatch tracks occupied according to the game.

TrainAlert.NoServices

fr.nimby.sdk · enum-entry

NoServices

No services available according to the game.

TrainAlert.ServicesAlreadyAssigned

fr.nimby.sdk · enum-entry

ServicesAlreadyAssigned

Services already assigned according to the game.

TrainAlert.Other

fr.nimby.sdk · enum-entry

Other

Other observed alert code, not represented by known values.

TrainRecord

fr.nimby.sdk · class

data class TrainRecord(val train: Train, val service: Service?, val details: TrainDetails?,
                       val positionStation: Station?, val locationStation: Station?, val stopStation: Station?,
                       val metadata: TrainMetadata? = null, val line: Line? = null)

Joined train view within a snapshot. Missing records remain null; an unresolved station does not prove a train is outside stations.

TrainRecord.train

fr.nimby.sdk · val

val train: Train

Basic train observation.

TrainRecord.service

fr.nimby.sdk · val

val service: Service?

Service joined by train identity, when available.

TrainRecord.details

fr.nimby.sdk · val

val details: TrainDetails?

Assignment/occupants joined by train identity, when available.

TrainRecord.positionStation

fr.nimby.sdk · val

val positionStation: Station?

Station of the geometric position track, when resolved.

TrainRecord.locationStation

fr.nimby.sdk · val

val locationStation: Station?

Service-location station when resolved; may differ from positionStation.

TrainRecord.stopStation

fr.nimby.sdk · val

val stopStation: Station?

Target-stop station when resolved; not necessarily current position.

TrainRecord.metadata

fr.nimby.sdk · val

val metadata: TrainMetadata? = null

Rich metadata for the same train, when requested and available.

TrainRecord.line

fr.nimby.sdk · val

val line: Line? = null

Service line joined from the requested catalogue.