TrainTypes · Kotlin/JVM

Usage context #

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.

import fr.nimby.sdk.TrainQuery
import fr.nimby.sdk.TrainId
import fr.nimby.sdk.LineId
import fr.nimby.sdk.StationId
import fr.nimby.sdk.TrackId
import fr.nimby.sdk.TimetableId
import fr.nimby.sdk.TimetableShiftId
import fr.nimby.sdk.TagId
import fr.nimby.sdk.VehicleModelId
import fr.nimby.sdk.LineType
import fr.nimby.sdk.Timetable
import fr.nimby.sdk.Tag
import fr.nimby.sdk.Line
import fr.nimby.sdk.TrainMetadata
import fr.nimby.sdk.Stop
import fr.nimby.sdk.TrainCharacteristics
import fr.nimby.sdk.VehicleModel
import fr.nimby.sdk.TrainVehicle

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.

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.

TrainQuery #

data class TrainQuery(val includeService: Boolean = true, val includeLocations: Boolean = true,
    val includeCharacteristics: Boolean = false, val includeTimetables: Boolean = false,
    val includeTags: Boolean = false, val includePassengers: Boolean = false, val includeLines: Boolean = false,
    val includeComposition: Boolean = false)

Options for a train read. Request only the groups you need; options select data, not a subset of trains.

TrainQuery.includeService #

val includeService: Boolean = true

Requests train state and service. Enabled by default; timetables also imply this read.

TrainQuery.includeLocations #

val includeLocations: Boolean = true

Requests location data and related stations/tracks. Enabled by default. Timetables also imply these data; false does not guarantee their absence from a covering snapshot.

TrainQuery.includeCharacteristics #

val includeCharacteristics: Boolean = false

Requests configured and current material characteristics separately. Disabled by default.

TrainQuery.includeTimetables #

val includeTimetables: Boolean = false

Requests available assignments and timetable data; implies service and track/station data even when includeLocations is false. Does not invent names or future passing times.

TrainQuery.includeTags #

val includeTags: Boolean = false

Requests train tags and the tag/line catalogue needed for joins; implies includeLines.

TrainQuery.includePassengers #

val includePassengers: Boolean = false

Requests occupant count; independent of material capacity.

TrainQuery.includeLines #

val includeLines: Boolean = false

Requests the line catalogue, including lines without assigned trains. Does not request tags by itself.

TrainQuery.includeComposition #

val includeComposition: Boolean = false

Requests ordered vehicles and referenced models for configured and current compositions. The groups remain optional.

TrainId #

data class TrainId(val value: Long)

Typed train identity copied from the game. Its type prevents joins between different objects; it encodes no business category for the mod.

TrainId.value #

val value: Long

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

LineId #

data class LineId(val value: Long)

Typed line identity copied from the game. Its type prevents joins between different objects; it encodes no business category for the mod.

LineId.value #

val value: Long

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

StationId #

data class StationId(val value: Long)

Typed station identity copied from the game. Its type prevents joins between different objects; it encodes no business category for the mod.

StationId.value #

val value: Long

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

TrackId #

data class TrackId(val value: Long)

Typed track identity copied from the game. Its type prevents joins between different objects; it encodes no business category for the mod.

TrackId.value #

val value: Long

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

TimetableId #

data class TimetableId(val value: Long)

Typed timetable identity copied from the game. Its type prevents joins between different objects; it encodes no business category for the mod.

TimetableId.value #

val value: Long

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

TimetableShiftId #

data class TimetableShiftId(val timetableId: TimetableId, val value: Long)

Identity of a shift within its timetable. The value alone is not unique: compare timetableId and value together.

TimetableShiftId.timetableId #

val timetableId: TimetableId

Timetable to which this shift belongs.

TimetableShiftId.value #

val value: Long

Opaque shift key, unique only within timetableId.

TagId #

data class TagId(val value: Long)

Typed tag identity copied from the game. Its type prevents joins between different objects; it encodes no business category for the mod.

TagId.value #

val value: Long

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

VehicleModelId #

data class VehicleModelId(val value: Long)

Typed vehicle model identity copied from the game. Its type prevents joins between different objects; it encodes no business category for the mod.

VehicleModelId.value #

val value: Long

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

LineType #

enum class LineType {
    Depot,
    Other
}

Classification limited to depot lines and other lines; no passenger/freight category is inferred.

LineType.Depot #

Depot

Line identified as a depot line.

LineType.Other #

Other

Observed non-depot line; its commercial category is not determined.

Timetable #

data class Timetable(val id: TimetableId, val name: String? = null)

Timetable identified from a train assignment. This type does not contain a complete passing schedule.

Timetable.id #

val id: TimetableId

Identity of the observed timetable.

Timetable.name #

val name: String? = null

The SDK currently exposes timetable identity without resolving its name; null is not an empty name.

Tag #

data class Tag(val id: TagId, val name: String?)

Classification label. Compare its identity; its name can change. No tag triggers automatic priority or regulation.

Tag.id #

val id: TagId

Tag identity, independent of its label.

Tag.name #

val name: String?

Observed name, possibly absent; do not use it as a stable key.

Line #

data class Line(val id: LineId, val name: String?, val type: LineType?, val parentId: LineId?,
                val parentInformationAvailable: Boolean, val declaredTags: List<Tag>?)

Line in the rich catalogue. Parent and tag information is independent of its name; no commercial category is inferred.

Line.id #

val id: LineId

Typed line identity.

Line.name #

val name: String?

Optional observed name; not a join key.

Line.type #

val type: LineType?

Depot or Other when classification is known; null otherwise.

Line.parentId #

val parentId: LineId?

Parent identity; check parentInformationAvailable before interpreting null.

Line.parentInformationAvailable #

val parentInformationAvailable: Boolean

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

Line.declaredTags #

val declaredTags: List<Tag>?

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

TrainMetadata #

data class TrainMetadata(val trainId: TrainId, val predictedArrivalDelayUs: Long?, val declaredTags: List<Tag>? = null,
                         val configured: TrainCharacteristics? = null, val current: TrainCharacteristics? = null)

Explicitly requested train metadata: arrival estimate, tags and material profiles. Each group retains its availability.

TrainMetadata.trainId #

val trainId: TrainId

Typed train identity to join within the same snapshot.

TrainMetadata.predictedArrivalDelayUs #

val predictedArrivalDelayUs: Long?

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

TrainMetadata.declaredTags #

val declaredTags: List<Tag>? = null

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

TrainMetadata.configured #

val configured: TrainCharacteristics? = null

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

TrainMetadata.current #

val current: TrainCharacteristics? = null

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

TrainMetadata.predictedArrivalDelaySeconds #

val predictedArrivalDelaySeconds: Double?

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

Stop #

typealias Stop = LineStop

Another name for LineStop, with the same relative-offset contract.

TrainCharacteristics #

data class TrainCharacteristics(val maximumSpeedMps: Double?, val lengthM: Double?, val emptyMassKg: Double?,
    val passengerCapacity: Int?, val carCount: Int?, val maximumAccelerationMps2: Double?, val powerW: Double?, val tractiveForceN: Double?,
    val composition: List<TrainVehicle>? = null)

Copied material-profile characteristics in SI units. Each field can be unknown independently; neither current speed nor priority.

TrainCharacteristics.maximumSpeedMps #

val maximumSpeedMps: Double?

Optional material speed limit in metres per second; distinct from measured speed and track limit.

TrainCharacteristics.lengthM #

val lengthM: Double?

Material length in metres; null when not established.

TrainCharacteristics.emptyMassKg #

val emptyMassKg: Double?

Empty mass in kilograms; does not represent loaded mass.

TrainCharacteristics.passengerCapacity #

val passengerCapacity: Int?

Optional passenger capacity of this profile; distinct from current occupants.

TrainCharacteristics.carCount #

val carCount: Int?

Optional vehicle count of this profile; do not infer capacity or length from this count alone.

TrainCharacteristics.maximumAccelerationMps2 #

val maximumAccelerationMps2: Double?

Declared maximum acceleration in metres per second squared; not measured acceleration.

TrainCharacteristics.powerW #

val powerW: Double?

Optional declared power in watts; not observed electrical consumption.

TrainCharacteristics.tractiveForceN #

val tractiveForceN: Double?

Optional declared tractive force in newtons.

TrainCharacteristics.composition #

val composition: List<TrainVehicle>? = null

Vehicles in observed order. null: unknown or unrequested; empty list: observed empty composition. Repeated models are significant.

TrainCharacteristics.maximumSpeedKmh #

val maximumSpeedKmh: Double?

maximumSpeedMps multiplied by 3.6; null remains null.

VehicleModel #

data class VehicleModel(val id: VehicleModelId, val code: String?, val nameEnglish: String?, val sourceName: String?)

Model referenced by a composition. The catalogue is limited to observed models; it does not classify trains as passenger or freight.

VehicleModel.id #

val id: VehicleModelId

Vehicle-model identity.

VehicleModel.code #

val code: String?

Optional observed model code.

VehicleModel.nameEnglish #

val nameEnglish: String?

English catalogue name; does not automatically follow the tool language.

VehicleModel.sourceName #

val sourceName: String?

Optional model-source name reported by the catalogue.

TrainVehicle #

data class TrainVehicle(val index: Int, val model: VehicleModel)

A vehicle at a specific position in a composition; several vehicles may share the same model.

TrainVehicle.index #

val index: Int

Zero-based position in the observed composition.

TrainVehicle.model #

val model: VehicleModel

Model associated with this vehicle; its labels can remain unknown.

TrainVehicle.modelId #

val modelId: VehicleModelId

Model identity, equal to model.id.