SignalModel

Usage context #

Public API for SDK 0.9.0-alpha.2. Each entry provides the Kotlin signature and its contract: what the value means, conditions of use and effects to understand. Choose imports from the module shown above.

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

Resolved indication accompanied by the model that produced it. Supplied by the SDK; of(model) checks declaration identity before returning typed enums.

SignalIndication.aspect #

val aspect: Enum<*>

Aspect from the owning model’s enum. Use of(model) to obtain an exact type without an unchecked cast.

SignalIndication.reason #

val reason: Enum<*>

Reason from the owning model’s enum; its meaning belongs to that model only.

SignalIndication.type #

val type: SignalType

SignalType declaration of the model that produced this indication, including its identifier and catalogue.

SignalIndication.drivingRule #

val drivingRule: DrivingRule?

Rule explicitly declared by this model for this indication, or null. Nothing is inferred from colour.

SignalIndication.active #

val active: Boolean

Result of the model’s activeWhen for this indication; defaults to true. Does not describe block occupancy.

SignalIndication.of #

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

Returns typed enums if model is exactly the owning declaration; otherwise null. Matching identifiers or ordinals do not make two declarations interchangeable.

SignalNeighbour #

class SignalNeighbour

Downstream neighbour resolved along this mod’s network link, supplied to rules. It is not a geometric search for nearby signals; an absent mod does not supply an invented neighbour.

SignalNeighbour.id #

val id: Long

Downstream signal ID corresponding to Signal.nextSignal in this calculation.

SignalNeighbour.indication #

val indication: SignalIndication

Resolved neighbour indication, including its model identity and enums.

SignalNeighbour.type #

val type: SignalType

Neighbour type obtained from its indication; useful for presenting or distinguishing models without interpreting a numeric code.

SignalNeighbour.drivingRule #

val drivingRule: DrivingRule?

Rule supplied by the neighbour declaration, or null. Your model explicitly decides whether to use it in its rules.

SignalNeighbour.active #

val active: Boolean

Activity of the neighbour indication according to its own model; replaces neither freshness nor occupancy of the current signal.

SignalNeighbour.of #

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

Typed neighbour reading for an exact declaration; null if the neighbour belongs to another model. Handle that case with an explicit policy.

SignalRuleContext #

class SignalRuleContext

Context supplied to a signalModel’s rules. Combines normalized settings, observation and typed neighbour; construction is reserved for the SDK. Returning null requests neighbour calculation.

SignalRuleContext.next #

val next: SignalNeighbour?

Resolved neighbour carrying its own model, or null on the first pass. Returning null from rules requests resolution; do not equate this null with a clear track.

SignalRuleContext.signal #

val signal: Signal

Normalized signal: an absent profile uses defaults, and an unavailable profile makes the observation stale. The transformation saves no settings.

SignalRuleContext.settings #

val settings: Map<String, Boolean>

Normalized effective settings of the current signal. Use enabled for checkboxes and NumberSetting.read for integers; a copy persists nothing.

SignalRuleContext.observation #

val observation: Observation

Observation from this context’s signal value. Check fresh and routeKnown before concluding that a track is clear.

SignalRuleContext.block #

val block: Occupancy

Physical block occupancy in this observation; rules need an explicit branch for Unknown.

SignalRuleContext.fresh #

val fresh: Boolean

Freshness of the context observation after approach validation. false calls for the mod’s fallback policy.

SignalRuleContext.routeKnown #

val routeKnown: Boolean

Indicates whether the observed route is known. true does not prove it clear or reserved for a train.

SignalRuleContext.approachingTrain #

val approachingTrain: Long?

Validated ID of a fresh approach; null when no usable approach exists. Do not retain it as evidence of reservation.

SignalRuleContext.trainApproaching #

val trainApproaching: Boolean

true when a train head is observed approaching with fresh data. Means neither a clear block nor permission to pass.

SignalRuleContext.settingsStatus #

val settingsStatus: SettingsStatus

Settings-profile status retained in the context, even when default values are used.

SignalRuleContext.enabled #

fun enabled(option: Checkbox): Boolean

Reads this checkbox, using its default when the key is missing. Rejects a checkbox declaration belonging to another model; the default does not replace checking settingsStatus.

SignalModelBuilder #

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

Declaration supplied inside signalModel: rules, observation, settings, resources, rendering and driving for a model with its own enums. Construction is reserved for the SDK.

SignalModelBuilder.number #

fun number(option: NumberSetting): Unit

Adds an integer setting to the model, up to four distinct names. visibleWhen is empty or names a checkbox in the model; the SDK handles its saved representation.

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

By default, name uses the model title; catalogueName uses name.

Declares all images in catalogue order and initial construction settings. Paths are package-relative, size ranges from 0 to 4 and left defaults to false; generation does not launch the game.

SignalModelBuilder.observeApproach #

var observeApproach: Boolean

Enables approach observation for this type; defaults to false. Prefer observeApproach(blocks) to choose its range as well.

SignalModelBuilder.approachBlocks #

var approachBlocks: Int

Number of upstream blocks to observe, from 1 to 16. Has an effect only when observeApproach is enabled.

SignalModelBuilder.observeApproach #

fun observeApproach(blocks: Int): Unit

Enables approach detection and sets its range to 1 through 16 upstream blocks. Traversal chooses no arbitrary branch; the mod then decides whether to open.

SignalModelBuilder.checkbox #

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

Registers a model-local checkbox and returns its declaration for enabled. Keep its name stable; label and help accept tr. onlyWhenEnabled suits acknowledgement warnings.

SignalModelBuilder.action #

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

Adds an optional button tied to a provider and service. Up to 16 unique IDs per model; declaring it does not call the service.

SignalModelBuilder.rules #

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

Declares the required pure rule. Return an indication to conclude locally, or null to request the neighbour. A missing link or cycle without a local decision uses invalidNetwork.

SignalModelBuilder.evaluate #

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

Declares an optional isolated calculation for diagnostics and tests. Does not resolve a network; in-game calculation uses rules and observed links.

SignalModelBuilder.evaluate #

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

Optional isolated calculation receiving the downstream aspect already decoded in this model’s enums. Observation.next must be its valid local ordinal. In a network, use the model-carrying neighbour in rules.

SignalModelBuilder.migrateSettings #

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

Converts actually saved keys when loading the profile. Return the new keys; the SDK fills missing defaults after this pure callback.

SignalModelBuilder.prepareObservation #

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

Declares pure preparation of the observed signal before its rules. Does not read the game or persist values; preserve observation meaning and validity.

SignalModelBuilder.allowForcedAspect #

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

Explicitly permits indications for in-game test recipes. The callback chooses the reason together with the aspect, or null to reject. Without this declaration, all forcing is rejected.

SignalModelBuilder.images #

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

Maps each indication to a steady image path declared in construction.states. Replaces an earlier appearance declaration; selection creates no driving rule.

SignalModelBuilder.animatedImages #

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

Image-selection callback receiving indication, simulation time and half-period in ms. For a two-image blink, prefer appearance with blink so the SDK handles the phase.

SignalModelBuilder.appearance #

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

Describes each indication’s appearance with steady or blink. Also declare all paths in the catalogue; pause and acceleration follow simulation time.

SignalModelBuilder.driving #

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

Maps the complete indication to an explicit rule, preferably through AutomaticDriving. null means no rule supplied; colour grants no permission.

SignalModelBuilder.faults #

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

Selects which indications appear as faults in diagnostics. Defaults to false; this classification does not replace your fallback rule.

SignalModelBuilder.activeWhen #

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

Selects whether an indication is actively managed. Defaults to true; distinguishes a disabled model from a closed but active signal.

SignalModelBuilder.aspectNames #

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

Declares aspect labels for diagnostics. Without a callback, the enum value’s name is used; this text does not change the aspect.

SignalModelBuilder.reasonNames #

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

Declares reason labels explaining decisions. Without a callback, the enum name is used.

SignalModel #

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

Model declared through signalModel, with its own enums and callbacks. Reuse the same instance for signal(model) and next.of(model). Declaring a model does not load the game.

SignalModel.type #

val type: SignalType

Final model declaration, including settings, approach range, actions and resources. Usable in tests without game access.

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>

Declares an independent model with its aspect and reason enums. rules and image selection are required. Choose a conservative fallback; invalidNetwork defaults to fallback.

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>

Declares an independent model from a SignalType shared with tests or an editor. The block completes rules, images and other roles; fallbacks belong to this model’s enums.

SignalModelsBuilder #

class SignalModelsBuilder

Composition of a mod with multiple independent signalModel declarations. The SDK supplies this builder to signalMod; no vocabulary or domain relationship between models is invented.

SignalModelsBuilder.options #

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

Registers one or more global preferences; multiple calls append options. Rejects duplicate IDs and more than 64 options including window shortcuts. Keep the declared objects to read their value.

SignalModelsBuilder.prepareNetwork #

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

Declares pure preparation of effective settings across the network. Preserve order, identities, links, types and observations; the SDK checks this contract. No persistence occurs.

SignalModelsBuilder.metadata #

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

Declares mod information for the game’s lists and details. description and name accept tr; identity and version come from the manifest.

SignalModelsBuilder.maximumLineSpeed #

var maximumLineSpeed: Boolean = false

Replaces the timetable cruising ceiling with the rolling-stock maximum, subject to track limits and braking targets. Defaults to false; its scope is broader than this mod’s signals alone.

SignalModelsBuilder.diagnosticFile #

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

Mod fault-log filename; defaults to nimby-kotlin-faults.jsonl. Choosing a project-specific name helps diagnostics.

SignalModelsBuilder.signal #

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

Adds an independent declaration to this package. Each model retains its enums, catalogue and callbacks; identifiers and catalogues must remain distinct.

SignalModelsBuilder.drivingPlan #

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

Declares a planning calculation over copied vehicle, settings, situation and constraints. Returns an advisory DrivingPlan; does not replace in-game DrivingRule values.

signalMod #

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

Assembles 1 to 16 independent models with an explicit identity. For a generated project, prefer signalMod(modInfo) to avoid duplicating mod.json.