SignalMod

Usage context

Module	Package	SDK source
Kotlin/Native	nimby	kotlin/src/nimby/SignalMod.kt

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.

Imports on this 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 and reason typed by the model’s two enums. The aspect describes the selected state; the reason explains why. Ordinals used by test recipes remain local: append new values at the end.

Indication.aspect

nimby · val

val aspect: A

Value from this model’s aspect enum. The mod explicitly associates the aspect with appearance and driving behaviour.

Indication.reason

nimby · val

val reason: R

Value from this model’s reason enum. Two indications with the same aspect may have different reasons and permissions.

SignalModDsl

nimby · class

annotation class SignalModDsl

Kotlin signalling-DSL annotation limiting nested implicit receivers. Has no in-game effect; use the builder functions.

SignalContext

nimby · class

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

Context for the shared-enum SignalModBuilder declaration. For new independent models, use SignalRuleContext. The SDK supplies this context; its properties trigger no game reads.

SignalContext.next

nimby · val

val next: Indication<A, R>?

Neighbour indication in the mod’s shared enums, or null before resolution. Returning null from rules asks the SDK to resolve the downstream link.

SignalContext.signal

nimby · val

val signal: Signal

Working signal copy with approach validation. Check settingsStatus: a checkbox default does not prove the profile was readable.

SignalContext.observation

nimby · val

val observation: Observation

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

SignalContext.block

nimby · val

val block: Occupancy

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

SignalContext.fresh

nimby · val

val fresh: Boolean

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

SignalContext.routeKnown

nimby · val

val routeKnown: Boolean

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

SignalContext.approachingTrain

nimby · val

val approachingTrain: Long?

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

SignalContext.trainApproaching

nimby · val

val trainApproaching: Boolean

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

SignalContext.settingsStatus

nimby · val

val settingsStatus: SettingsStatus

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

SignalContext.enabled

nimby · fun

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.

SignalDefinition

nimby · class

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

Type declaration in the shared-enum DSL. Supplied by SignalModBuilder.signal; for an independent model, use signalModel and SignalModelBuilder.

SignalDefinition.observeApproach

nimby · var

var observeApproach: Boolean

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

SignalDefinition.approachBlocks

nimby · var

var approachBlocks: Int

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

SignalDefinition.observeApproach

nimby · fun

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.

SignalDefinition.checkbox

nimby · fun

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.

SignalDefinition.rules

nimby · fun

fun rules(block: SignalContext<A, R>.() -> 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.

SignalDefinition.action

nimby · fun

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.

SignalDefinition.evaluate

nimby · fun

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.

SignalDefinition.migrateSettings

nimby · fun

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.

SignalDefinition.prepareObservation

nimby · fun

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.

SignalDefinition.allowForcedAspect

nimby · fun

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.

SignalModBuilder

nimby · class

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

Signalling DSL with enums shared by every type in the mod. For independent families, prefer SignalModelsBuilder and signalModel; the SDK creates this builder.

SignalModBuilder.options

nimby · fun

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.

SignalModBuilder.maximumLineSpeed

nimby · var

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.

SignalModBuilder.diagnosticFile

nimby · var

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

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

SignalModBuilder.signal

nimby · fun

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

Adds a type to the shared-enum DSL with explicit identifier, title and catalogue. The block defines its checkboxes and rules; image and driving functions are shared by the builder.

SignalModBuilder.signal

nimby · fun

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

Adds an existing SignalType declaration to the shared-enum DSL, useful when sharing it with tests. Complete its rules in the block.

SignalModBuilder.images

nimby · fun

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.

SignalModBuilder.animatedImages

nimby · fun

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.

SignalModBuilder.appearance

nimby · fun

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.

SignalModBuilder.driving

nimby · fun

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.

SignalModBuilder.faults

nimby · fun

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.

SignalModBuilder.activeWhen

nimby · fun

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.

SignalModBuilder.aspectNames

nimby · fun

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.

SignalModBuilder.reasonNames

nimby · fun

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

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

SignalModBuilder.drivingPlan

nimby · fun

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.

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

Builds a mod whose models all share the same enums. fallback handles unknown calculation; invalidNetwork handles absent or cyclic dependencies. For new independent models, prefer signalModel followed by signalMod(modInfo).