ToolContext

Contexte d’utilisation

Module	Package	Source SDK
Kotlin/Native	nimby	kotlin/src/nimby/ToolContext.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.

Imports de cette page

import nimby.ToolTrack
import nimby.ToolJunction
import nimby.ToolSignal
import nimby.ToolNetwork
import nimby.SignalPosition
import nimby.ConstructionState
import nimby.ConstructionResult
import nimby.ToolButton
import nimby.ToolNumberInput
import nimby.LogLevel
import nimby.ToolContext

Contexte, unités et opérations

Le contexte est prêt à utiliser dans service et onTick. Il appartient au callback courant : conservez les valeurs copiées et les tickets, jamais ce contexte. Le SDK refuse les appels après le retour du callback.

Valeur	Contrat
ToolTrack.lengthM	Mètres, optionnel ; null impose d’arrêter le parcours.
SignalPosition.fraction	Fraction native strictement entre 0 et 1 pour une pose.
SignalPosition.direction	Sens natif -1 ou 1 ; distinct du sens visuel de certains modèles.
ConstructionResult.reason	Code de refus du pont natif ; à conserver dans le journal.
ToolButton	Identifiant, libellé, état activé ; au maximum 12 boutons par panneau.
ToolNumberInput	Champ entier saisissable au clavier : id, label, value, minimum, maximum, enabled. Sélection, effacement et collage sont possibles. Un texte vide, incomplet ou hors limites reste un brouillon local et bloque les commandes ; seul un entier valide est transmis au mod. Quatre champs maximum, avec des identifiants distincts de ceux des boutons.
SignalActionRequest.value	Nouvelle valeur entière pour une édition de champ (action contient son id) ; null pour un bouton. Une édition bloque les boutons jusqu’à la republication du panneau.
showPanel	Message UTF-8 limité à 256 octets ; remplace l’action qui a ouvert l’outil.

ToolTrack

nimby · class

data class ToolTrack(val id: Long, val linkA: Long?, val linkB: Long?, val lengthM: Double?)

Géométrie copiée d’une voie pour un outil. lengthM peut être indisponible ; utilisez topology pour des raccordements typés et arrêtez un parcours inconnu.

ToolTrack.id

nimby · val

val id: Long

Identifiant de voie dans cette partie. Conserver avec worldId et generation de la copie, sans le traiter comme un index de liste.

ToolTrack.linkA

nimby · val

val linkA: Long?

Identifiant du raccord observé côté A, ou null si indisponible. Utilisez ToolTopology pour vérifier un raccord réciproque exploitable.

ToolTrack.linkB

nimby · val

val linkB: Long?

Identifiant du raccord observé côté B, ou null si indisponible. null ne prouve pas que la voie se termine ici.

ToolTrack.lengthM

nimby · val

val lengthM: Double?

Longueur observée finie et strictement positive, en mètres, ou null. Ne remplacez pas null par une longueur calculée approximativement pour une pose.

ToolJunction

nimby · class

data class ToolJunction(val branchTrack: Long, val mainTrack: Long, val fraction: Double, val mainDirection: Int, val branchDirection: Int)

Raccordement copié d’une branche à une voie principale, avec position et orientations. Ne définit pas une branche actuellement autorisée ; ToolTopology évite de choisir une route implicitement.

ToolJunction.branchTrack

nimby · val

val branchTrack: Long

Identifiant de la voie de branche de ce raccordement, distinct de mainTrack.

ToolJunction.mainTrack

nimby · val

val mainTrack: Long

Identifiant de la voie principale portant la position fraction.

ToolJunction.fraction

nimby · val

val fraction: Double

Position du raccord sur la voie principale, de 0 à 1 depuis A vers B. Multiplier par sa longueur donne une distance depuis A.

ToolJunction.mainDirection

nimby · val

val mainDirection: Int

Orientation observée de la voie principale au raccord, −1 ou +1. Ce signe ne choisit pas la route à suivre ; utilisez les connexions de ToolTopology.

ToolJunction.branchDirection

nimby · val

val branchDirection: Int

Orientation observée de la branche, −1 ou +1. ToolTopology s’en sert pour reconnaître son extrémité d’aiguille ; aucun trajet n’est autorisé par cette valeur.

ToolSignal

nimby · class

data class ToolSignal(val id: Long, val track: Long, val fraction: Double, val direction: Int, val kind: Int)

Signal copié avec voie, position et modèle. Utilisez travelDirection pour le sens des trains et placementAt pour copier l’orientation correctement.

ToolSignal.id

nimby · val

val id: Long

Identifiant du signal dans la copie, à revalider dans une nouvelle lecture avant une construction.

ToolSignal.track

nimby · val

val track: Long

Identifiant de la voie portant le signal. Recherchez sa longueur avec topology.track(track).

ToolSignal.fraction

nimby · val

val fraction: Double

Position du signal sur la voie, de 0 à 1 depuis A vers B. Une position destinée à la pose doit être strictement intérieure.

ToolSignal.direction

nimby · val

val direction: Int

Orientation stockée du signal, dépendante de son modèle. Ne l’utilisez pas comme sens des trains ; préférez travelDirection.

ToolSignal.kind

nimby · val

val kind: Int

Type observé du signal fourni pour les données de la copie. Ne codez pas de conversion de sens à partir de ce nombre : placementAt la prend en charge.

ToolSignal.travelDirection

nimby · val

val travelDirection: Int

Sens normalisé des trains : +1 de A vers B, −1 de B vers A. Lève une exception si l’orientation de la copie est invalide.

ToolSignal.placementAt

nimby · fun

fun placementAt(trackId: Long, fraction: Double, travelDirection: Int = this.travelDirection): SignalPosition

Construit la position d’une copie du signal source, en convertissant le sens des trains pour son modèle. Exige une voie valide, une fraction finie strictement entre 0 et 1 et un sens ±1. Même valeur pour aperçu et pose.

ToolNetwork

nimby · class

data class ToolNetwork(val worldId: String, val generation: Long, val tracks: List<ToolTrack>, val junctions: List<ToolJunction>, val signals: List<ToolSignal>)

Copie de travail des voies, aiguilles et signaux d’une session. Les listes restent consultables après le callback ; elles ne prouvent pas que le monde est encore inchangé.

ToolNetwork.worldId

nimby · val

val worldId: String

Identité du monde dont proviennent toutes les listes de cette copie.

ToolNetwork.generation

nimby · val

val generation: Long

Génération de session de la copie. Abandonnez un plan si elle ne correspond plus au contexte actif.

ToolNetwork.tracks

nimby · val

val tracks: List<ToolTrack>

Voies copiées ; chacune peut avoir une longueur inconnue. Préparez topology une fois pour les recherches répétées.

ToolNetwork.junctions

nimby · val

val junctions: List<ToolJunction>

Raccordements d’aiguilles copiés, y compris ceux à l’intérieur d’une voie. Les ignorer peut faire traverser une aiguille au planificateur.

ToolNetwork.signals

nimby · val

val signals: List<ToolSignal>

Signaux présents dans la lecture. Une liste copiée n’est pas une autorisation de construire entre eux.

SignalPosition

nimby · class

data class SignalPosition(val trackId: Long, val fraction: Double, val direction: Int)

Position proposée pour un aperçu ou une pose. Préférez source.placementAt(...) pour convertir le sens selon le modèle ; le constructeur seul n’effectue pas de validation du jeu.

SignalPosition.trackId

nimby · val

val trackId: Long

Voie cible issue du réseau relu. Elle doit encore exister au moment de la commande.

SignalPosition.fraction

nimby · val

val fraction: Double

Position cible strictement entre 0 et 1 depuis A vers B pour la pose ; ni extrémité ni distance en mètres.

SignalPosition.direction

nimby · val

val direction: Int

Orientation attendue par le modèle source. Obtenez-la via placementAt plutôt qu’en recopiant aveuglément travelDirection.

ConstructionState

nimby · class

enum class ConstructionState {
    Ready,
    Applied,
    Undone,
    Rejected,
    Partial,
    Pending
}

Étape ou résultat d’une opération suivie par ticket. Distinguez préparation, attente et résultat terminal ; un délai ne signifie jamais que rien n’a été posé.

ConstructionState.Ready

nimby · enum-entry

Ready

Ticket préparé, sans création. Capturez ensuite le réseau et validez le plan avant une confirmation explicite.

ConstructionState.Applied

nimby · enum-entry

Applied

Commande appliquée. Inspectez createdIds et canUndo ; une nouvelle action ne doit pas répéter cette pose.

ConstructionState.Undone

nimby · enum-entry

Undone

Annulation de l’opération effectuée. Terminez son suivi et présentez ce résultat au joueur.

ConstructionState.Rejected

nimby · enum-entry

Rejected

Opération refusée. Présentez le motif et invalidez la confirmation ; ne transformez pas le refus en nouvelle tentative automatique.

ConstructionState.Partial

nimby · enum-entry

Partial

Résultat incomplet avec effets possibles. Inspectez createdIds, reason et canUndo ; ne présumez ni succès complet ni absence de modification.

ConstructionState.Pending

nimby · enum-entry

Pending

Résultat encore en attente. Conservez le ticket original et utilisez pollConstruction ; ne soumettez pas une nouvelle commande.

ConstructionResult

nimby · class

data class ConstructionResult(val state: ConstructionState, val token: Long, val createdIds: List<Long>, val reason: Int, val canUndo: Boolean)

Résultat copié d’une préparation, pose, annulation ou interrogation de ticket. Consultez state avant les autres champs ; une opération incertaine continue d’être suivie sur son ticket.

ConstructionResult.state

nimby · val

val state: ConstructionState

Étape ou issue de l’opération. Pending exige un suivi ; Partial exige un examen des effets obtenus.

ConstructionResult.token

nimby · val

val token: Long

Ticket opaque à conserver pour createSignals, pollConstruction et undoConstruction. Un ticket nul n’est pas une préparation exploitable.

ConstructionResult.createdIds

nimby · val

val createdIds: List<Long>

Identifiants des signaux créés rapportés par l’opération. Une liste vide doit être interprétée avec state, jamais seule comme preuve d’absence d’effet.

ConstructionResult.reason

nimby · val

val reason: Int

Code de diagnostic du résultat à conserver dans les journaux. Ne le présentez pas comme une enum métier déduite de sa valeur.

ConstructionResult.canUndo

nimby · val

val canUndo: Boolean

Indique qu’une annulation SDK était disponible lors de la réponse. L’historique peut changer ensuite ; undoConstruction peut encore refuser.

ToolButton

nimby · class

data class ToolButton(val id: String, val label: String, val enabled: Boolean = true)

Bouton temporaire d’un panneau ou d’une fenêtre. Son libellé n’exécute aucune action ; le handler traite l’identifiant reçu. Sa suppression ne modifie pas les réglages persistants des signaux.

ToolButton.id

nimby · val

val id: String

Identifiant technique transmis dans action au clic, distinct des autres boutons et champs du formulaire.

ToolButton.label

nimby · val

val label: String

Texte affiché sur le bouton ; accepte tr. Gardez id stable lorsque ce texte change.

ToolButton.enabled

nimby · val

val enabled: Boolean = true

false désactive le bouton dans le formulaire publié. Le handler doit aussi revalider l’état local avant toute mutation.

ToolNumberInput

nimby · class

data class ToolNumberInput(val id: String, val label: String, val value: Int,
    val minimum: Int, val maximum: Int, val enabled: Boolean = true)

Champ entier temporaire avec valeur et bornes explicites. Un panneau envoie chaque édition valide dans request.value ; une fenêtre envoie tous les champs au clic. Un brouillon invalide bloque les commandes.

ToolNumberInput.id

nimby · val

val id: String

Clé du champ dans action ou ToolWindowEvent.values, distincte des autres contrôles du formulaire.

ToolNumberInput.label

nimby · val

val label: String

Libellé du champ entier, affiché avec la saisie ; accepte tr.

ToolNumberInput.value

nimby · val

val value: Int

Entier proposé lors de la publication du formulaire. Doit appartenir à minimum..maximum ; une republication doit respecter le brouillon validé de l’outil.

ToolNumberInput.minimum

nimby · val

val minimum: Int

Borne inférieure incluse de la saisie. Doit être inférieure ou égale à maximum.

ToolNumberInput.maximum

nimby · val

val maximum: Int

Borne supérieure incluse de la saisie ; la valeur publiée et les éditions acceptées doivent la respecter.

ToolNumberInput.enabled

nimby · val

val enabled: Boolean = true

false rend la saisie non modifiable dans ce formulaire ; ne supprime pas la valeur de l’état local de l’outil.

LogLevel

nimby · class

enum class LogLevel {
    Info,
    Warning,
    Error
}

Niveau de gravité d’un message écrit par ToolContext.log. Choisissez le niveau selon le résultat métier et évitez de répéter un message à chaque tick.

LogLevel.Info

nimby · enum-entry

Info

Événement de fonctionnement normal, par exemple une opération terminée ou un changement de phase.

LogLevel.Warning

nimby · enum-entry

Warning

Situation inhabituelle dont l’outil peut rendre compte sans la classer comme une erreur définitive.

LogLevel.Error

nimby · enum-entry

Error

Échec à diagnostiquer. Gardez le message utile et borné ; écrire un journal peut lui-même être temporairement refusé.

nimby · class

class ToolContext

Accès au jeu fourni uniquement pendant un callback de l’outil. Ne conservez ni ce contexte ni une fermeture qui le capture. Les valeurs copiées, identifiants de session et tickets peuvent être conservés pour le callback suivant.

ToolContext.worldId

nimby · val

val worldId: String

Identité de la partie active pour cet appel. Comparez-la à celle du plan ou de l’événement avant de réutiliser des données.

ToolContext.generation

nimby · val

val generation: Long

Génération de session active pour cet appel. Un changement invalide les plans et les présentations de l’ancienne génération.

ToolContext.log

nimby · fun

fun log(message: String, level: LogLevel = LogLevel.Info): Unit

Écrit un message persistant de 1 à 4096 octets UTF-8, sans caractère nul. Ne pas journaliser de secrets ni chaque tick ; traiter un éventuel refus sans boucle de diagnostics.

ToolContext.clock

nimby · fun

fun clock(): ToolClock

Lit uniquement calendrier et temps simulé, sans capturer le réseau. Utilisez cette lecture légère pour un affichage d’heure ; le résultat copié ne se met pas à jour tout seul.

ToolContext.trains

nimby · fun

fun trains(query: TrainQuery = TrainQuery()): TrainSnapshot

Lit les groupes de données demandés pour les trains. Réutilise une lecture du même callback si elle couvre la requête ; un besoin supplémentaire déclenche une lecture élargie. Les copies restent lisibles après le callback.

ToolContext.linePlan

nimby · fun

fun linePlan(trainId: Long): TrainLinePlan?

Lit le plan complet de la ligne du train identifié, ou null si absent/instable. Les horaires sont des offsets, pas des dates commerciales absolues. Réutilisé dans le callback ; network renouvelle la lecture.

ToolContext.linePlan

nimby · fun

fun linePlan(train: TrainId): LinePlan?

Même lecture de plan avec un identifiant de train typé. Retourne LinePlan ou null lorsque le plan est absent/instable ; ne déduit pas la date d’une circulation.

ToolContext.changeTime

nimby · fun

fun changeTime(utcSeconds: Long, recalculateTrains: Boolean = false): ToolTimeChange

Change le calendrier UTC, années 1 à 9999, en conservant la fraction de seconde. Par défaut, conserve positions et délais relatifs. recalculateTrains peut déplacer des trains et coûter de l’argent : choix explicite requis. Après erreur incertaine, relire plutôt que rejouer.

ToolContext.changeTime

nimby · fun

fun changeTime(date: GameDateTime, recalculateTrains: Boolean = false): ToolTimeChange

Convertit la date validée en secondes UTC puis applique changeTime. Même mutation et même nécessité de relire après un résultat incertain ; calculer la date seul ne changeait pas la partie.

ToolContext.showWindow

nimby · fun

fun showWindow(request: ToolWindowEvent, message: String, buttons: List<ToolButton>, inputs: List<ToolNumberInput> = emptyList()): Unit

Publie le formulaire de la fenêtre ayant produit l’événement, dans la même session : jusqu’à 12 boutons et 8 entiers, IDs distincts. Valeurs envoyées ensemble au clic ; 4096 octets UTF-8 par chaîne sans caractère nul, et 8192 au total.

ToolContext.network

nimby · fun

fun network(): ToolNetwork

Capture une nouvelle copie de voies, aiguilles et signaux ; invalide les lectures de trains réutilisées dans ce contexte sans les relire immédiatement. À appeler après prepareConstruction pour calculer le plan à confirmer, pas à chaque renouvellement d’aperçu.

ToolContext.prepareConstruction

nimby · fun

fun prepareConstruction(sourceSignal: Long): ConstructionResult

Prépare un ticket pour copier le signal source, sans poser de signal. Faire ensuite une nouvelle capture et valider les positions. Une commande d’édition ou un changement de session peut invalider ce ticket.

ToolContext.showSignalPreview

nimby · fun

fun showSignalPreview(request: SignalActionRequest, positions: List<SignalPosition>): Unit

Publie jusqu’à 64 positions avec le modèle source, sans construction. Renouveler pendant l’usage : expiration après deux secondes. Visible pendant l’édition de la source ; couches et cadrage restent applicables. Un refus Busy ne renouvelle pas l’ancien aperçu et interdit une confirmation locale.

ToolContext.clearSignalPreview

nimby · fun

fun clearSignalPreview(): Unit

Demande le retrait de l’aperçu de l’outil, sans annuler une construction. En cas de Busy, révoquez immédiatement la confirmation locale puis retentez le nettoyage dans un callback ultérieur.

ToolContext.createSignals

nimby · fun

fun createSignals(ticket: Long, sourceSignal: Long, positions: List<SignalPosition>): ConstructionResult

Soumet une seule fois 1 à 64 positions distinctes avec ticket préparé et signal source. Validez une nouvelle capture contre le plan approuvé avant l’appel. Pending ou erreur incertaine impose de suivre le même ticket, jamais de rejouer la pose.

ToolContext.undoConstruction

nimby · fun

fun undoConstruction(ticket: Long): ConstructionResult

Demande explicitement l’annulation du ticket lorsque canUndo le permet. L’historique peut avoir changé ; un refus reste possible. Marquez l’opération en attente avant l’appel et suivez son résultat sans la répéter.

ToolContext.pollConstruction

nimby · fun

fun pollConstruction(ticket: Long): ConstructionResult

Interroge le ticket non nul original sans resoumettre la commande. Continuez pendant Pending, même si le panneau est fermé. Un ticket devenu indisponible ne prouve pas une absence d’effet.

ToolContext.showPanel

nimby · fun

fun showPanel(request: SignalActionRequest, message: String, buttons: List<ToolButton>, inputs: List<ToolNumberInput> = emptyList()): Unit

Remplace l’action d’origine par un panneau temporaire : jusqu’à 12 boutons et 4 entiers, IDs distincts. Chaque chaîne doit respecter 256 caractères et 256 octets UTF-8, sans caractère nul. Utilisez la requête de la même session. Un refus de présentation ne valide pas les anciens clics ; les réglages persistants du signal ne sont pas modifiés.