NRF GuideRéférence
ToolContext
Lire le réseau, préparer une pose, publier des boutons et écrire dans le journal depuis un outil.
Contexte d’utilisation
| Module | Package | Source SDK |
|---|---|---|
| Kotlin/Native | nimby | kotlin/src/nimby/ToolContext.kt |
Signatures extraites de la version 0.8.0-alpha.1. Les paramètres, leurs valeurs par défaut et les propriétés de constructeur sont conservés. Les corps des méthodes ne font pas partie de cette référence.
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. |
| showPanel | Message UTF-8 limité à 256 octets ; remplace l’action qui a ouvert l’outil. |
ToolTrack
data class ToolTrack(val id: Long, val linkA: Long?, val linkB: Long?, val lengthM: Double?)Géométrie observée pour un outil. Une longueur absente interrompt le parcours.
ToolJunction
data class ToolJunction(val branchTrack: Long, val mainTrack: Long, val fraction: Double, val mainDirection: Int, val branchDirection: Int)ToolSignal
data class ToolSignal(val id: Long, val track: Long, val fraction: Double, val direction: Int, val kind: Int)ToolNetwork
data class ToolNetwork(val worldId: String, val generation: Long, val tracks: List<ToolTrack>, val junctions: List<ToolJunction>, val signals: List<ToolSignal>)SignalPosition
data class SignalPosition(val trackId: Long, val fraction: Double, val direction: Int)ConstructionState
enum class ConstructionState {
Ready, Applied, Undone, Rejected, Partial, Pending
}ConstructionResult
data class ConstructionResult(val state: ConstructionState, val token: Long, val createdIds: List<Long>, val reason: Int, val canUndo: Boolean)ToolButton
data class ToolButton(val id: String, val label: String, val enabled: Boolean = true)Contrôles temporaires de l'outil dans le panneau du signal sélectionné. Leur retrait ne modifie pas les cases persistantes du mod de signalisation.
LogLevel
enum class LogLevel {
Info, Warning, Error
}ToolContext
class ToolContextAccès valable uniquement pendant un callback de l'outil, sur son worker. Garder les données copiées est permis ; conserver le contexte ne l'est pas. La construction est expérimentale et exige le pont Windows correspondant. Construction réservée au SDK : utilisez la fonction de création ou le contexte fourni.
ToolContext.worldId
val worldId: StringToolContext.generation
val generation: LongToolContext.log
fun log(message: String, level: LogLevel = LogLevel.Info)Journal persistant commun aux mods ; ne pas y écrire de secrets.
ToolContext.network
fun network(): ToolNetworkNouvelle capture après prepareConstruction, jamais une topologie cachée.
ToolContext.prepareConstruction
fun prepareConstruction(sourceSignal: Long): ConstructionResultToolContext.createSignals
fun createSignals(ticket: Long, sourceSignal: Long, positions: List<SignalPosition>): ConstructionResultEn cas de Pending, appeler pollConstruction avec le même ticket. Ne pas refaire createSignals : une réponse incertaine peut masquer une pose réelle.
ToolContext.undoConstruction
fun undoConstruction(ticket: Long): ConstructionResultToolContext.pollConstruction
fun pollConstruction(ticket: Long): ConstructionResultToolContext.showPanel
fun showPanel(request: SignalActionRequest, message: String, buttons: List<ToolButton>)Remplace seulement l'action à l'origine de [request] par ces contrôles. Les clics suivants arrivent au même service avec l'id du bouton dans action.