Référence
TrainObservation
Copies de trains, services, lignes et arrêts accessibles dans les callbacks.
Contexte d’utilisation
| Module | Package | Source SDK |
|---|---|---|
| Kotlin/Native | nimby | kotlin/src/nimby/TrainObservation.kt |
API publique du SDK 0.9.0-alpha.2. Chaque entrée donne la signature Kotlin et son contrat : sens de la valeur, conditions d’utilisation et effets à connaître. Choisissez les imports du module indiqué ci-dessus.
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.LinePlanChoisir la lecture et interpréter les résultats
Dans un mod, utiliser ToolContext.trains(query). Dans une application JVM, utiliser game.trains.snapshot(query = query) ; sélectionner un train demande aussi son plan de ligne. Une requête groupe tous les trains : ne pas créer une capture par train. La lecture de l’horloge et la lecture ciblée d’un train sont séparées.
| Option TrainQuery | Par défaut | Données demandées |
|---|---|---|
| includeService | true | État, service et affectation observés. |
| includeLocations | true | Positions et références de localisation nécessaires. |
| includeCharacteristics | false | Profils du matériel configuré et actuel. |
| includeTimetables | false | Informations d’horaires disponibles ; implique includeService. |
| includeTags | false | Tags déclarés et références pour leur héritage ; implique includeLines. |
| includePassengers | false | Occupants observés, distincts de la capacité. |
| includeLines | false | Catalogue des lignes, y compris celles sans train affecté. |
| includeComposition | false | Véhicules ordonnés des compositions configurée et actuelle et modèles référencés. |
| Valeur | Unité et contrat |
|---|---|
| Train.speedMps / Train.speedKmh | Vitesse actuelle. Native : une mesure indisponible reste null. JVM : vérifier aussi speedDefaulted avant d’interpréter une valeur de secours comme une mesure. |
| maximumSpeedMps / maximumSpeedKmh | Vitesse maximale du matériel, en m/s ou km/h ; distincte de la vitesse actuelle et de la limite de voie. |
| lengthM / emptyMassKg / maximumAccelerationMps2 | Mètres, kilogrammes, mètres par seconde carrée. |
| powerW / tractiveForceN | Watts et newtons. |
| passengers / passengerCapacity / carCount | Occupants, capacité et nombre de véhicules : trois quantités distinctes. |
| configured / current / composition | Profils indépendants, sans remplacement des valeurs absentes. Composition null : inconnue ou non demandée ; liste vide : composition observée vide. |
| predictedArrivalDelayUs / predictedArrivalDelaySeconds | Estimation signée, en microsecondes ou secondes ; négative pour une arrivée prévue en avance. Ni âge d’échéance ni priorité. |
| arrivalOffsetSeconds / departureOffsetSeconds | Offsets validés, en secondes depuis l’origine du plan de ligne. Ne pas les convertir en date absolue d’un train. |
| arrivalTimeUs / departureTimeUs / dispatchRetryTimeUs | Microsecondes depuis l’origine de simulation, pas depuis 1970. Utiliser les helpers de calendrier ; une date reste null si l’origine est inconnue. |
| capturedAtMillis / ageMillis | Heure UTC de l’ordinateur / âge monotone lors de la copie ; distincts du calendrier du jeu. |
Les identifiants typés sont opaques. TimetableShiftId est unique seulement avec son TimetableId. LineType distingue uniquement Depot et Other ; aucune catégorie voyageurs/fret n’est inférée. Un nom d’horaire indisponible reste null. Les tags sont des libellés, sans priorité automatique ; un héritage incomplet ou cyclique reste inconnu. VehicleModel.nameEnglish conserve le nom anglais du catalogue.
TrainVehicle décrit un véhicule dans une composition. Le type nimby.Vehicle utilisé par le calcul de conduite est un autre contrat. Ne pas mélanger les classes homonymes des packages nimby et fr.nimby.sdk.
GameInstant
data class GameInstant(val utcSeconds: Long, val microsecond: Int = 0)Instant UTC du calendrier du jeu, à la microseconde. Années 1 à 9999 ; microsecond vaut de 0 à 999999. Aucune lecture du jeu lors des conversions.
GameInstant.utcSeconds
val utcSeconds: LongSecondes UTC depuis 1970 dans le calendrier du jeu ; peuvent être négatives.
GameInstant.microsecond
val microsecond: Int = 0Fraction de la seconde entre 0 et 999999.
GameInstant.dateTime
fun dateTime(): GameDateTimeConvertit les secondes en date/heure UTC du jeu ; la fraction microsecond n’appartient pas au GameDateTime retourné.
TrainState
enum class TrainState {
Unknown,
Driving,
StationStop,
TimedStop,
Depot,
DispatchWait,
SignalWait,
Mothballed,
NotPresent,
Other
}État de service observé. null signifie indisponible ; Unknown et Other sont des résultats observés, pas une absence de donnée.
TrainState.Unknown
UnknownLe jeu rapporte un état indéterminé.
TrainState.Driving
DrivingÉtat de conduite rapporté ; ne prouve pas une vitesse strictement positive.
TrainState.StationStop
StationStopArrêt en gare rapporté.
TrainState.TimedStop
TimedStopArrêt temporisé rapporté.
TrainState.Depot
DepotÉtat de dépôt rapporté.
TrainState.DispatchWait
DispatchWaitAttente de départ/dispatch rapportée.
TrainState.SignalWait
SignalWaitAttente de signal rapportée ; ce champ ne décrit pas à lui seul la règle du signal.
TrainState.Mothballed
MothballedTrain remisé hors exploitation selon l’état rapporté.
TrainState.NotPresent
NotPresentTrain rapporté non présent ; à distinguer d’un objet absent de la capture.
TrainState.Other
OtherÉtat observé non représenté par une autre valeur connue de cette enum.
TrainAlert
enum class TrainAlert {
None,
LineClosed,
NoPath,
InvalidOrders,
Collision,
SignalWait,
ScheduleClosed,
DispatchTracksOccupied,
NoServices,
ServicesAlreadyAssigned,
Other
}Alerte observée du train. null signifie indisponible ; None signifie qu’aucune alerte n’est rapportée. Une alerte n’est pas une priorité.
TrainAlert.None
NoneAucune alerte rapportée.
TrainAlert.LineClosed
LineClosedLigne fermée rapportée.
TrainAlert.NoPath
NoPathAbsence de chemin rapportée.
TrainAlert.InvalidOrders
InvalidOrdersOrdres invalides rapportés.
TrainAlert.Collision
CollisionCollision rapportée par le jeu.
TrainAlert.SignalWait
SignalWaitAlerte d’attente à un signal.
TrainAlert.ScheduleClosed
ScheduleClosedHoraire fermé rapporté.
TrainAlert.DispatchTracksOccupied
DispatchTracksOccupiedVoies de dispatch occupées selon le jeu.
TrainAlert.NoServices
NoServicesAucun service disponible selon le jeu.
TrainAlert.ServicesAlreadyAssigned
ServicesAlreadyAssignedServices déjà affectés selon le jeu.
TrainAlert.Other
OtherAutre code d’alerte observé, non représenté par les valeurs connues.
Station
data class Station(val id: Long, val name: String?)Gare jointe dans une observation de train ou de plan de ligne. Un nom absent ne prouve pas que la gare n’existe pas.
Station.id
val id: LongValeur opaque à comparer et transmettre telle quelle ; ne pas la découper ni la réutiliser dans une autre partie.
Station.name
val name: String?Nom observé ; null si indisponible.
Station.stationId
val stationId: StationIdMême identité sous le type StationId.
Line
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)Ligne observée dans un service ou le catalogue. Les informations de parent et de tags sont disponibles seulement lorsqu’elles ont été demandées et validées.
Line.id
val id: LongValeur opaque à comparer et transmettre telle quelle ; ne pas la découper ni la réutiliser dans une autre partie.
Line.name
val name: String?Nom observé de la ligne ; null si indisponible.
Line.isDepot
val isDepot: Boolean?true : dépôt ; false : autre type observé ; null : classification inconnue.
Line.parentLineId
val parentLineId: LineId? = nullIdentité du parent ; interpréter null avec parentInformationAvailable.
Line.lineId
val lineId: LineIdMême identité sous le type LineId.
Line.type
val type: LineType?Classification dérivée de isDepot : Depot, Other ou null.
TrainPosition
data class TrainPosition(val trackId: Long, val fraction: Double, val direction: Int?, val station: Station?)Position copiée d’un train sur une voie. La fraction décrit la position longitudinale, pas une distance en mètres ni une réservation.
TrainPosition.trackId
val trackId: LongValeur opaque à comparer et transmettre telle quelle ; ne pas la découper ni la réutiliser dans une autre partie.
TrainPosition.fraction
val fraction: DoublePosition entre 0 et 1 selon l’origine de la voie.
TrainPosition.direction
val direction: Int?+1 de A vers B, -1 de B vers A ; null si inconnu.
TrainPosition.station
val station: Station?Gare jointe à la voie de position ; null si aucune jointure exploitable.
TrainPosition.track
val track: TrackIdIdentité de la voie sous le type TrackId.
TrainAssignment
data class TrainAssignment(val scheduleId: Long?, val shiftId: Long?, val orderIndex: Int?)Affectation observée d’un train à un horaire, un service et un ordre. N’annonce pas un prochain passage calculé.
TrainAssignment.scheduleId
val scheduleId: Long?Identité opaque de l’horaire affecté ; null si indisponible.
TrainAssignment.shiftId
val shiftId: Long?Clé de service dans scheduleId ; ne pas la comparer seule entre horaires.
TrainAssignment.orderIndex
val orderIndex: Int?Indice d’ordre observé à partir de zéro ; null si indisponible.
TrainAssignment.timetable
val timetable: Timetable?Horaire construit depuis scheduleId, avec son identité seulement ; null si scheduleId manque.
TrainAssignment.shift
val shift: TimetableShiftId?Identité composée disponible seulement si horaire et clé de service sont connus.
TrainServiceTimes
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?,
)Échéances actives et temps restants observés. Une durée peut être disponible sans origine de calendrier. Les conversions conservent null ; aucune date future n’est extrapolée.
TrainServiceTimes.gameEpochSeconds
val gameEpochSeconds: Long?Origine UTC du calendrier de simulation, en secondes depuis 1970 ; null si inconnue.
TrainServiceTimes.gameTimeUs
val gameTimeUs: Long?Compteur observé en microsecondes depuis l’origine de simulation ; pas une date Unix.
TrainServiceTimes.arrivalTimeUs
val arrivalTimeUs: Long?Échéance active d’arrivée en microsecondes depuis l’origine de simulation ; optionnelle.
TrainServiceTimes.departureTimeUs
val departureTimeUs: Long?Échéance active de départ en microsecondes depuis l’origine de simulation ; optionnelle.
TrainServiceTimes.dispatchRetryTimeUs
val dispatchRetryTimeUs: Long?Échéance de nouvelle tentative de dispatch, en microsecondes depuis l’origine de simulation.
TrainServiceTimes.arrivalRemainingSeconds
val arrivalRemainingSeconds: Double?Secondes restantes jusqu’à l’échéance d’arrivée ; peuvent être négatives. Ne représentent pas le retard commercial prévu.
TrainServiceTimes.departureRemainingSeconds
val departureRemainingSeconds: Double?Secondes restantes jusqu’à l’échéance de départ, bornées à zéro ; null si inconnues.
TrainServiceTimes.dispatchRetryRemainingSeconds
val dispatchRetryRemainingSeconds: Double?Secondes restantes avant une nouvelle tentative de dispatch, bornées à zéro ; null si inconnues.
TrainServiceTimes.observedAt
val observedAt: GameInstant?Compteur observé converti en calendrier UTC du jeu ; null si l’origine ou le compteur manque, ou si la conversion dépasse la plage.
TrainServiceTimes.arrival
val arrival: GameInstant?Date UTC de l’échéance active d’arrivée. null si la conversion est impossible ; ce n’est pas nécessairement l’horaire commercial.
TrainServiceTimes.departure
val departure: GameInstant?Date UTC de l’échéance active de départ. null si la conversion est impossible ; ce n’est pas nécessairement l’horaire commercial.
TrainServiceTimes.dispatchRetry
val dispatchRetry: GameInstant?Date UTC de nouvelle tentative de dispatch ; pas une heure commerciale de départ. null si non convertible.
TrainService
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,
)Service observé d’un train, avec état, lieux et échéances indépendamment optionnels. La gare de position, le lieu de service et l’arrêt ciblé ne sont pas interchangeables.
TrainService.state
val state: TrainState?État de service ; null signifie indisponible, différent de TrainState.Unknown.
TrainService.alert
val alert: TrainAlert?Alerte observée, optionnelle ; None est une observation sans alerte.
TrainService.onNetwork
val onNetwork: Boolean?Présence sur le réseau rapportée ; null si inconnue. Ne prouve aucune autorisation de mouvement.
TrainService.locationTrackId
val locationTrackId: Long?Voie du lieu de service observé ; peut différer de la voie de position.
TrainService.locationStation
val locationStation: TrainStation?Gare du lieu de service observé ; absence de jointure ne prouve pas l’absence de gare.
TrainService.line
val line: TrainLine?Ligne du service ; null si indisponible.
TrainService.stopTrackId
val stopTrackId: Long?Voie de l’arrêt actuellement ciblé ; null si inconnue.
TrainService.stopStation
val stopStation: TrainStation?Gare de l’arrêt ciblé, si résolue.
TrainService.stopIndex
val stopIndex: Int?Indice de l’arrêt courant dans la ligne, à partir de zéro ; null si inconnu.
TrainService.times
val times: TrainServiceTimesÉchéances du service ; chaque valeur garde sa disponibilité propre.
Train
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,
)Fiche copiée d’un train. Les groupes de TrainQuery déterminent les données optionnelles ; les données inconnues restent null, sans lecture implicite.
Train.id
val id: LongValeur opaque à comparer et transmettre telle quelle ; ne pas la découper ni la réutiliser dans une autre partie.
Train.name
val name: StringNom du train dans cette observation ; ne remplace pas son identité.
Train.position
val position: TrainPosition?Position copiée si observable ; null si absente ou indisponible.
Train.speedMps
val speedMps: Double?Vitesse mesurée en mètres par seconde ; null si inconnue ou remplacée par une valeur de secours.
Train.speedDefaulted
val speedDefaulted: BooleanIndique une vitesse de secours du jeu. Ce cas laisse la vitesse mesurée inconnue ; il ne prouve pas un arrêt.
Train.passengers
val passengers: Int?Occupants observés, seulement si demandés ; null ne vaut pas zéro.
Train.assignment
val assignment: TrainAssignment?Affectation observée ; null si indisponible ou non demandée.
Train.service
val service: TrainService?Service observé, éventuellement partiel : une lecture de localisation peut fournir présence et lieux sans état de service. Les options du callback peuvent aussi avoir été cumulées. null indique qu’aucune partie utilisable n’a été fournie.
Train.predictedArrivalDelayUs
val predictedArrivalDelayUs: Long? = nullRetard d’arrivée estimé par le jeu, en microsecondes signées ; négatif pour une arrivée prévue en avance. null si inconnu. Ce n’est ni l’âge d’une échéance ni une priorité.
Train.configured
val configured: TrainCharacteristics? = nullProfil configuré/acheté du train, demandé explicitement. Indépendant du matériel actuel : ses valeurs ne remplacent pas celles qui manquent dans current.
Train.current
val current: TrainCharacteristics? = nullCaractéristiques de la composition actuelle, si observables et demandées. Ne pas les remplacer par le profil configuré.
Train.trainId
val trainId: TrainIdMême identité sous le type TrainId.
Train.speedKmh
val speedKmh: Double?Vitesse mesurée convertie en km/h ; null reste null.
Train.predictedArrivalDelaySeconds
val predictedArrivalDelaySeconds: Double?Même estimation d’arrivée, convertie de microsecondes en secondes ; conserve le signe et null.
TrainSnapshot
class TrainSnapshotCopie de trains obtenue par ToolContext.trains. Conservable après le callback ; les recherches lisent uniquement cette copie. Valide les données séparément, sans figer un tick de simulation.
TrainSnapshot.worldId
val worldId: StringIdentité du monde observé, à conserver avec sa génération pour identifier la portée des données.
TrainSnapshot.generation
val generation: LongGénération observée de la partie. Invalider les données dérivées lorsqu’elle change, même si la même sauvegarde est rechargée.
TrainSnapshot.capturedAtMillis
val capturedAtMillis: LongHorodatage UTC de l’ordinateur, en millisecondes depuis 1970. Il ne mesure pas le temps simulé.
TrainSnapshot.ageMillis
val ageMillis: LongÂge monotone de la capture au moment de la copie, en millisecondes ; ne se met pas à jour ensuite.
TrainSnapshot.clock
val clock: ToolClock?Horloge simulée observée ; null si indisponible.
TrainSnapshot.trains
val trains: List<TrainObservation>Trains copiés selon la requête ; leurs champs facultatifs reflètent les groupes demandés.
TrainSnapshot.vehicleModels
val vehicleModels: List<VehicleModel>? = nullModèles référencés par les compositions demandées ; null si non demandés ou indisponibles.
TrainSnapshot.get
operator fun get(id: Long): TrainObservation?Recherche indexée dans les trains copiés ; null si cet identifiant n’y figure pas. Aucune nouvelle observation.
TrainSnapshot.get
operator fun get(id: TrainId): Train?Même recherche locale avec un identifiant typé ; null si absent de cette capture.
TrainSnapshot.lines
val lines: List<Line>?Catalogue des lignes demandé, même sans train affecté ; null si inconnu ou non demandé.
TrainSnapshot.line
fun line(id: LineId): Line?Ligne du catalogue copié ; null si absente, indisponible ou non demandée.
TrainSnapshot.tag
fun tag(id: TagId): Tag?Tag du catalogue copié ; null si absent, indisponible ou non demandé.
Stop
data class Stop(val index: Int, val trackId: Long, val station: Station?,
val arrivalOffsetSeconds: Int?, val departureOffsetSeconds: Int?)Arrêt ou waypoint du plan de ligne. Peut être hors gare ; les offsets restent relatifs au plan.
Stop.index
val index: IntIndice d’arrêt à partir de zéro dans le plan de ligne.
Stop.trackId
val trackId: LongValeur opaque à comparer et transmettre telle quelle ; ne pas la découper ni la réutiliser dans une autre partie.
Stop.station
val station: Station?Gare jointe, si disponible ; un waypoint peut être hors gare.
Stop.arrivalOffsetSeconds
val arrivalOffsetSeconds: Int?Offset d’arrivée en secondes depuis l’origine du plan ; null si inconnu. Pas une date absolue du train.
Stop.departureOffsetSeconds
val departureOffsetSeconds: Int?Offset de départ en secondes depuis l’origine du plan ; null si inconnu.
Stop.track
val track: TrackIdIdentité typée de la voie de l’arrêt.
Stop.plannedDwellSeconds
val plannedDwellSeconds: Long?departureOffsetSeconds moins arrivalOffsetSeconds, en secondes ; null si un offset manque.
LinePlan
data class LinePlan(val trainId: Long, val line: Line, val stops: List<Stop>,
val worldId: String, val generation: Long, val capturedAtMillis: Long)Plan complet de la ligne associée au train dans cette capture, obtenu par ToolContext.linePlan. Peut contenir des arrêts hors de la course partielle du train.
LinePlan.trainId
val trainId: LongValeur opaque à comparer et transmettre telle quelle ; ne pas la découper ni la réutiliser dans une autre partie.
LinePlan.line
val line: LineLigne observée associée au train.
LinePlan.stops
val stops: List<Stop>Arrêts du plan complet, dans leur ordre ; ne pas les convertir directement en prochains passages du train.
LinePlan.worldId
val worldId: StringIdentité du monde observé, à conserver avec sa génération pour identifier la portée des données.
LinePlan.generation
val generation: LongGénération observée de la partie. Invalider les données dérivées lorsqu’elle change, même si la même sauvegarde est rechargée.
LinePlan.capturedAtMillis
val capturedAtMillis: LongHorodatage UTC de l’ordinateur, en millisecondes depuis 1970. Il ne mesure pas le temps simulé.
LinePlan.train
val train: TrainIdIdentité typée du train qui a servi à demander ce plan.