SignalModel

Contexte d’utilisation #

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.SignalIndication
import nimby.SignalNeighbour
import nimby.SignalRuleContext
import nimby.SignalModelBuilder
import nimby.SignalModel
import nimby.signalModel
import nimby.SignalModelsBuilder
import nimby.signalMod

SignalIndication #

class SignalIndication

Indication résolue accompagnée du modèle qui l’a produite. Fournie par le SDK ; of(model) vérifie l’identité de la déclaration avant de rendre les enums typées.

SignalIndication.aspect #

val aspect: Enum<*>

Aspect de l’enum du modèle propriétaire. Utilisez of(model) pour obtenir un type précis sans conversion forcée.

SignalIndication.reason #

val reason: Enum<*>

Motif de l’enum du modèle propriétaire ; il conserve son sens dans ce modèle seulement.

SignalIndication.type #

val type: SignalType

Déclaration SignalType du modèle ayant produit cette indication, y compris son identifiant et son catalogue.

SignalIndication.drivingRule #

val drivingRule: DrivingRule?

Consigne explicitement déclarée par ce modèle pour cette indication, ou null. Aucune déduction à partir de la couleur.

SignalIndication.active #

val active: Boolean

Résultat de activeWhen du modèle pour cette indication ; true par défaut. Ne décrit pas l’occupation du canton.

SignalIndication.of #

fun <A : Enum<A>, R : Enum<R>> of(model: SignalModel<A, R>): Indication<A, R>?

Retourne les enums typées si model est exactement la déclaration propriétaire ; null sinon. Un identifiant ou un ordinal identique ne rend pas deux déclarations interchangeables.

SignalNeighbour #

class SignalNeighbour

Voisin aval résolu sur le lien du réseau de ce mod, fourni au callback rules. Ce n’est pas une recherche géométrique des signaux proches ; un mod absent ne fournit pas de voisin inventé.

SignalNeighbour.id #

val id: Long

Identifiant du signal aval correspondant à Signal.nextSignal dans ce calcul.

SignalNeighbour.indication #

val indication: SignalIndication

Indication résolue du voisin, avec l’identité de son modèle et ses enums.

SignalNeighbour.type #

val type: SignalType

Type du voisin, obtenu depuis son indication ; utile pour présenter ou distinguer les modèles sans interpréter de code numérique.

SignalNeighbour.drivingRule #

val drivingRule: DrivingRule?

Consigne publiée par la déclaration du voisin, ou null. Votre modèle décide explicitement s’il peut l’utiliser dans ses règles.

SignalNeighbour.active #

val active: Boolean

Activité de l’indication du voisin selon son propre modèle ; ne remplace ni la fraîcheur ni l’occupation du signal courant.

SignalNeighbour.of #

fun <A : Enum<A>, R : Enum<R>> of(model: SignalModel<A, R>): Indication<A, R>?

Lecture typée du voisin pour une déclaration précise ; null si le voisin appartient à un autre modèle. Traitez ce cas avec une politique explicite.

SignalRuleContext #

class SignalRuleContext

Contexte fourni à rules d’un signalModel. Réunit réglages normalisés, observation et voisin typé ; le constructeur est réservé au SDK. Retourner null demande le calcul du voisin.

SignalRuleContext.next #

val next: SignalNeighbour?

Voisin résolu portant son propre modèle, ou null au premier passage. Retourner null depuis rules demande sa résolution ; ne pas assimiler ce null à une voie libre.

SignalRuleContext.signal #

val signal: Signal

Signal normalisé : profil absent complété par les défauts, profil indisponible rendant l’observation non fraîche. La transformation ne sauvegarde aucun réglage.

SignalRuleContext.settings #

val settings: Map<String, Boolean>

Réglages effectifs normalisés du signal courant. Utilisez enabled pour les cases et NumberSetting.read pour les entiers ; une copie ne persiste rien.

SignalRuleContext.observation #

val observation: Observation

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

SignalRuleContext.block #

val block: Occupancy

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

SignalRuleContext.fresh #

val fresh: Boolean

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

SignalRuleContext.routeKnown #

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.

SignalRuleContext.approachingTrain #

val approachingTrain: Long?

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

SignalRuleContext.trainApproaching #

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.

SignalRuleContext.settingsStatus #

val settingsStatus: SettingsStatus

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

SignalRuleContext.enabled #

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.

SignalModelBuilder #

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

Déclaration reçue dans signalModel : règles, observation, réglages, ressources, rendu et conduite d’un modèle avec ses propres enums. Constructeur réservé au SDK.

SignalModelBuilder.number #

fun number(option: NumberSetting): Unit

Ajoute un réglage entier au modèle, jusqu’à quatre noms distincts. visibleWhen est vide ou nomme une case du modèle ; le SDK prend en charge son enregistrement.

SignalModelBuilder.construction #

fun construction(states: List<String>, name: String = …, kind: String = "path",
                     catalogueName: String = name, nameKey: String? = null, catalogueNameKey: String? = null,
                     size: Int = 0, left: Boolean = false): Unit

Par défaut, name reprend le titre du modèle ; catalogueName reprend name.

Déclare toutes les images dans leur ordre de catalogue et les valeurs initiales de construction. Chemins relatifs au paquet, size de 0 à 4 et left=false par défaut ; la génération ne lance pas le jeu.

SignalModelBuilder.observeApproach #

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.

SignalModelBuilder.approachBlocks #

var approachBlocks: Int

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

SignalModelBuilder.observeApproach #

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.

SignalModelBuilder.checkbox #

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.

SignalModelBuilder.action #

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.

SignalModelBuilder.rules #

fun rules(block: SignalRuleContext.() -> 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.

SignalModelBuilder.evaluate #

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.

SignalModelBuilder.evaluate #

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

Calcul isolé facultatif recevant l’aspect aval déjà décodé dans les enums de ce modèle. Observation.next doit être son ordinal local valide. En réseau, utilisez le voisin portant son modèle dans rules.

SignalModelBuilder.migrateSettings #

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.

SignalModelBuilder.prepareObservation #

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.

SignalModelBuilder.allowForcedAspect #

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.

SignalModelBuilder.images #

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.

SignalModelBuilder.animatedImages #

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.

SignalModelBuilder.appearance #

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.

SignalModelBuilder.driving #

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.

SignalModelBuilder.faults #

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.

SignalModelBuilder.activeWhen #

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.

SignalModelBuilder.aspectNames #

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.

SignalModelBuilder.reasonNames #

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é.

SignalModel #

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

Modèle déclaré par signalModel, avec ses propres enums et callbacks. Réutilisez la même instance pour signal(model) et next.of(model). Déclarer le modèle ne charge pas la partie.

SignalModel.type #

val type: SignalType

Déclaration finale du modèle, comprenant réglages, portée d’approche, actions et ressources. Utilisable dans les tests sans accéder au jeu.

signalModel #

inline fun <reified A : Enum<A>, reified R : Enum<R>> signalModel(
    id: String, title: String, textures: String, fallback: Indication<A, R>,
    invalidNetwork: Indication<A, R> = fallback, noinline block: SignalModelBuilder<A, R>.() -> Unit
): SignalModel<A, R>

Déclare un modèle indépendant avec ses enums d’aspect et de motif. rules et une sélection d’images sont obligatoires. Choisissez un repli prudent ; invalidNetwork vaut fallback si omis.

signalModel #

inline fun <reified A : Enum<A>, reified R : Enum<R>> signalModel(
    type: SignalType, fallback: Indication<A, R>, invalidNetwork: Indication<A, R> = fallback,
    noinline block: SignalModelBuilder<A, R>.() -> Unit
): SignalModel<A, R>

Déclare un modèle indépendant à partir d’un SignalType partagé avec les tests ou un éditeur. Le bloc complète règles, images et autres rôles ; les replis appartiennent aux enums de ce modèle.

SignalModelsBuilder #

class SignalModelsBuilder

Composition d’un mod avec plusieurs signalModel indépendants. Le SDK fournit ce builder à signalMod ; aucun vocabulaire ou lien métier entre modèles n’est inventé.

SignalModelsBuilder.options #

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.

SignalModelsBuilder.prepareNetwork #

fun prepareNetwork(block: (List<Signal>) -> List<Signal>): Unit

Déclare une préparation pure des réglages effectifs de tout le réseau. Préservez ordre, identités, liens, types et observations ; le SDK vérifie ce contrat. Aucune persistance.

SignalModelsBuilder.metadata #

fun metadata(author: String, description: String, name: String? = null): Unit

Déclare les informations du mod pour les listes et fiches du jeu. description et name acceptent tr ; l’identité et la version proviennent du manifeste.

SignalModelsBuilder.maximumLineSpeed #

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.

SignalModelsBuilder.diagnosticFile #

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.

SignalModelsBuilder.signal #

fun signal(model: SignalModel<*, *>): Unit

Ajoute une déclaration indépendante à ce paquet. Chaque modèle conserve ses enums, son catalogue et ses callbacks ; identifiants et catalogues doivent rester distincts.

SignalModelsBuilder.drivingPlan #

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.

signalMod #

fun signalMod(id: String, title: String, block: SignalModelsBuilder.() -> Unit): SignallingMod

Assemble 1 à 16 modèles indépendants avec identité explicite. Pour un projet généré, préférez signalMod(modInfo) afin de ne pas dupliquer mod.json.