SignalMod

Contexte d’utilisation

Module	Package	Source SDK
Kotlin/Native	nimby	kotlin/src/nimby/SignalMod.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.Indication
import nimby.SignalModDsl
import nimby.SignalContext
import nimby.SignalDefinition
import nimby.SignalModBuilder
import nimby.signalMod

Indication

nimby · class

data class Indication<A : Enum<A>, R : Enum<R>>(val aspect: A, val reason: R)

Aspect et motif typés par deux enums du modèle. L’aspect décrit l’état choisi ; le motif explique pourquoi. Les ordinaux utilisés dans des recettes restent locaux : ajoutez de nouvelles valeurs à la fin.

Indication.aspect

nimby · val

val aspect: A

Valeur de l’enum d’aspects de ce modèle. Le mod associe explicitement cet aspect à une apparence et à une conduite.

Indication.reason

nimby · val

val reason: R

Valeur de l’enum de motifs de ce modèle. Deux indications du même aspect peuvent avoir des motifs et permissions différents.

SignalModDsl

nimby · class

annotation class SignalModDsl

Annotation Kotlin du DSL de signalisation qui limite les récepteurs implicites imbriqués. Aucune action en jeu ; utilisez les fonctions des builders.

SignalContext

nimby · class

class SignalContext<A : Enum<A>, R : Enum<R>>

Contexte de la déclaration à enums communes SignalModBuilder. Pour de nouveaux modèles indépendants, utilisez SignalRuleContext. Le SDK fournit ce contexte ; aucune lecture de jeu n’est déclenchée par ses propriétés.

SignalContext.next

nimby · val

val next: Indication<A, R>?

Indication du voisin dans les enums communes du mod, ou null avant résolution. Retourner null depuis rules demande au SDK de résoudre le lien aval.

SignalContext.signal

nimby · val

val signal: Signal

Copie de travail du signal avec validation de l’approche. Vérifiez settingsStatus : un défaut de case ne prouve pas que le profil était lisible.

SignalContext.observation

nimby · val

val observation: Observation

Observation de la valeur signal de ce contexte. Consulter fresh et routeKnown avant toute déduction de voie libre.

SignalContext.block

nimby · val

val block: Occupancy

Occupation physique du canton dans cette observation ; Unknown doit avoir une branche explicite dans les règles.

SignalContext.fresh

nimby · val

val fresh: Boolean

Fraîcheur de l’observation du contexte, après validation de l’approche. false appelle la politique de repli du mod.

SignalContext.routeKnown

nimby · val

val routeKnown: Boolean

Indique si le parcours observé est connu. Une valeur vraie ne prouve pas qu’il est libre ni réservé à un train.

SignalContext.approachingTrain

nimby · val

val approachingTrain: Long?

Identifiant validé d’une approche fraîche ; null si aucune approche utilisable. Ne pas conserver comme preuve de réservation.

SignalContext.trainApproaching

nimby · val

val trainApproaching: Boolean

true lorsqu’une tête de train est observée en approche avec des données fraîches. Ne signifie ni canton libre ni autorisation de franchissement.

SignalContext.settingsStatus

nimby · val

val settingsStatus: SettingsStatus

Statut du profil de réglages conservé dans le contexte, même lorsque des valeurs par défaut sont utilisées.

SignalContext.enabled

nimby · fun

fun enabled(option: Checkbox): Boolean

Lit cette case avec son défaut si la clé manque. Refuse une déclaration de case appartenant à un autre modèle ; le défaut ne remplace pas le contrôle de settingsStatus.

SignalDefinition

nimby · class

class SignalDefinition<A : Enum<A>, R : Enum<R>>

Déclaration d’un type dans le DSL à enums communes. Fournie par SignalModBuilder.signal ; pour un modèle indépendant, utilisez signalModel et SignalModelBuilder.

SignalDefinition.observeApproach

nimby · var

var observeApproach: Boolean

Active l’observation d’approche pour ce type ; false par défaut. Préférez observeApproach(blocks) pour choisir aussi sa portée.

SignalDefinition.approachBlocks

nimby · var

var approachBlocks: Int

Nombre de cantons amont à observer, de 1 à 16. N’a d’effet que si observeApproach est activé.

SignalDefinition.observeApproach

nimby · fun

fun observeApproach(blocks: Int): Unit

Active la détection d’approche et fixe sa portée de 1 à 16 cantons amont. Le parcours ne choisit aucune branche arbitraire ; le mod décide ensuite de l’ouverture.

SignalDefinition.checkbox

nimby · fun

fun checkbox(name: String, label: String, description: String = "", defaultValue: Boolean = false,
                 onlyWhenEnabled: Boolean = false): Checkbox

Enregistre une case propre au modèle et renvoie sa déclaration à utiliser avec enabled. Nom stable ; libellé et aide acceptent tr. onlyWhenEnabled convient aux avertissements à acquitter.

SignalDefinition.rules

nimby · fun

fun rules(block: SignalContext<A, R>.() -> Indication<A, R>?): Unit

Déclare la règle pure obligatoire. Retournez une indication pour conclure localement, ou null pour demander le voisin. Un lien manquant ou un cycle sans décision locale utilise invalidNetwork.

SignalDefinition.action

nimby · fun

fun action(id: String, label: String, whenMod: String, service: String): Unit

Ajoute un bouton facultatif lié à un fournisseur et un service. Jusqu’à 16 identifiants uniques par modèle ; aucun appel au service lors de la déclaration.

SignalDefinition.evaluate

nimby · fun

fun evaluate(block: (Map<String, Boolean>, Observation) -> Indication<A, R>): Unit

Déclare un calcul isolé facultatif pour diagnostics et tests. Ne résout pas le réseau ; le calcul en partie utilise rules et ses liens observés.

SignalDefinition.migrateSettings

nimby · fun

fun migrateSettings(block: (Map<String, Boolean>) -> Map<String, Boolean>): Unit

Convertit les clés réellement enregistrées lors du chargement du profil. Retournez les nouvelles clés ; le SDK complétera les défauts manquants après ce callback pur.

SignalDefinition.prepareObservation

nimby · fun

fun prepareObservation(block: (Signal) -> Signal): Unit

Déclare une préparation pure du signal observé avant ses règles. Ne lit pas le jeu et ne persiste pas les valeurs ; préservez le sens et la validité des observations.

SignalDefinition.allowForcedAspect

nimby · fun

fun allowForcedAspect(block: (A) -> Indication<A, R>?): Unit

Autorise explicitement des indications pour les recettes en jeu. Le callback choisit le motif avec l’aspect, ou null pour refuser. Sans déclaration, tous les forçages sont refusés.

SignalModBuilder

nimby · class

class SignalModBuilder<A : Enum<A>, R : Enum<R>>

DSL de signalisation à enums partagées par tous les types du mod. Pour des familles indépendantes, préférez SignalModelsBuilder et signalModel ; le SDK crée ce builder.

SignalModBuilder.options

nimby · fun

fun options(vararg values: ModOption<*>): Unit

Enregistre une ou plusieurs préférences globales ; plusieurs appels ajoutent des options. Refuse les identifiants dupliqués et plus de 64 options, raccourcis de fenêtres compris. Conservez les objets déclarés pour lire leur value.

SignalModBuilder.maximumLineSpeed

nimby · var

var maximumLineSpeed: Boolean = false

Remplace le plafond de marche lié à l’horaire par le maximum du matériel, sous réserve des limites de voie et cibles de freinage. false par défaut ; portée plus large que les seuls signaux du mod.

SignalModBuilder.diagnosticFile

nimby · var

var diagnosticFile: String = "nimby-kotlin-faults.jsonl"

Nom du journal de défauts du mod ; nimby-kotlin-faults.jsonl par défaut. Choisir un nom propre au projet facilite les diagnostics.

SignalModBuilder.signal

nimby · fun

fun signal(id: String, title: String, textures: String, block: SignalDefinition<A, R>.() -> Unit): Unit

Ajoute un type au DSL à enums communes avec identifiant, titre et catalogue explicites. Le bloc définit ses cases et ses règles ; les fonctions d’image et conduite sont communes au builder.

SignalModBuilder.signal

nimby · fun

fun signal(type: SignalType, block: SignalDefinition<A, R>.() -> Unit): Unit

Ajoute une déclaration SignalType déjà construite au DSL à enums communes, utile pour la partager avec les tests. Complétez ses règles dans le bloc.

SignalModBuilder.images

nimby · fun

fun images(block: (Indication<A, R>) -> String): Unit

Associe chaque indication à un chemin d’image fixe déclaré dans construction.states. Remplace une éventuelle déclaration appearance précédente ; le choix ne crée aucune consigne de conduite.

SignalModBuilder.animatedImages

nimby · fun

fun animatedImages(block: (Indication<A, R>, Long, Long) -> String): Unit

Sélection d’image par callback recevant indication, temps simulé et demi-période en ms. Pour un clignotement à deux images, préférez appearance avec blink afin de laisser le SDK gérer la phase.

SignalModBuilder.appearance

nimby · fun

fun appearance(block: (Indication<A, R>) -> SignalAnimation): Unit

Décrit l’affichage de chaque indication avec steady ou blink. Déclarez aussi tous les chemins dans le catalogue ; la pause et l’accélération suivent l’horloge simulée.

SignalModBuilder.driving

nimby · fun

fun driving(block: (Indication<A, R>) -> DrivingRule?): Unit

Associe l’indication complète à une consigne explicite, idéalement avec AutomaticDriving. null signifie aucune consigne fournie ; la couleur n’accorde aucune permission.

SignalModBuilder.faults

nimby · fun

fun faults(block: (Indication<A, R>) -> Boolean): Unit

Choisit quelles indications apparaissent comme défauts dans les diagnostics. false par défaut ; ce classement ne remplace pas votre règle de repli.

SignalModBuilder.activeWhen

nimby · fun

fun activeWhen(block: (Indication<A, R>) -> Boolean): Unit

Choisit si une indication est activement gérée. true par défaut ; permet de distinguer un modèle désactivé d’un signal fermé mais actif.

SignalModBuilder.aspectNames

nimby · fun

fun aspectNames(block: (A) -> String): Unit

Déclare les libellés d’aspects pour les diagnostics. Sans callback, le nom de la valeur d’enum est utilisé ; ce texte ne change pas l’aspect.

SignalModBuilder.reasonNames

nimby · fun

fun reasonNames(block: (R) -> String): Unit

Déclare les libellés de motifs pour expliquer les décisions. Sans callback, le nom de l’enum est utilisé.

SignalModBuilder.drivingPlan

nimby · fun

fun drivingPlan(block: (Vehicle, DrivingSettings, DrivingInput, List<Constraint>) -> DrivingPlan): Unit

Déclare un calcul de planification sur matériel, paramètres, situation et contraintes copiés. Renvoie un DrivingPlan consultatif ; ne remplace pas les DrivingRule de conduite en partie.

nimby · fun

inline fun <reified A : Enum<A>, reified R : Enum<R>> signalMod(
    id: String, title: String, fallback: Indication<A, R>,
    invalidNetwork: Indication<A, R> = fallback,
    noinline block: SignalModBuilder<A, R>.() -> Unit
): SignallingMod

Construit un mod dont tous les modèles partagent les mêmes enums. fallback traite le calcul inconnu ; invalidNetwork les dépendances absentes ou cycliques. Pour de nouveaux modèles indépendants, préférez signalModel puis signalMod(modInfo).