Skip to content
Connected RailsConnected Rails

Signals

The interlocking stays country-neutral: it computes the situation of a signal, the signal type maps it to an aspect. The first matching rule wins, an empty when: () matches everything. Signals are evaluated in signalling order — next_stop/next_slow see the following signal’s final aspect, rule table included, from the same update.

when
clear all guarded sections are clear
route a route is locked at this signal
route_target this is the destination of a requested, locked or occupied route
shunting an outgoing shunting route is set
diverging the locked route leads over a diverging path
next_stop the following main signal shows stop
next_slow the following main signal shows slow speed
show
main Stop, Proceed, ProceedSlow, Substitute, DarkLight
distant ExpectStop, ExpectProceed, ExpectSlow, DarkLight
speed Zs3 speed indicator [km/h]

lamps is a list of free-form strings for the presentation — your own assets decide what they look like. mods/example/signals/ks_main.ron:

(
name: "Ks combination signal", // optional, the library's card title (file name otherwise)
system: Ks,
rules: [
(when: (clear: Some(false)), show: (main: Some(Stop)), lamps: ["red"]),
(when: (diverging: Some(true)),
show: (main: Some(ProceedSlow), distant: Some(ExpectStop), speed: Some(40.0)),
lamps: ["yellow", "zs3_4"]),
(when: (next_stop: Some(true)),
show: (main: Some(Proceed), distant: Some(ExpectStop)), lamps: ["yellow"]),
(when: (), show: (main: Some(Proceed), distant: Some(ExpectProceed)), lamps: ["green"]),
],
script: None,
tags: ["ks", "main-signal"], // optional, for the library's search and filters (see Tags)
)

A line references the type by name. Every signal placement also carries its operational designation and the interlocking which controls it:

signals: [(
designation: "24P3",
interlocking: "Lf",
kind: Main,
system: Ks,
device: 1,
guarded: [0],
signal_type: Some("example:ks_main"),
)],

A signal type maps situations to lamp images; a signal model gives them geometry. Models are assemblies after the Zusi pattern: shared glTF parts — mast, screen, indicator — chained by mount points, so a screen drawn once hangs on a mast here and under a bridge there. signal_models/*.ron:

(
name: "Ks main signal · mast", // optional, the library's card title (file name otherwise)
parts: [
(file: "example/assets/sig_mast.gltf"), // root
(file: "example/assets/sig_schirm_ks.gltf", mount: Some((0, "mp_schirm"))),
(file: "example/assets/sig_zs3.gltf", mount: Some((1, "mp_top"))),
],
lamps: [
(lamp: "red", part: 1, node: "lamp_red"),
(lamp: "zs3_4", part: 2, node: "zs3_4"),
],
tags: ["ks", "mast", "zs3"], // optional, for the library's search and filters (see Tags)
)

A part without mount stands at the device position; every other part hangs off a named node of another part. lamps binds the free-form lamp-image strings of the signal type to glTF nodes: the node is visible while its string is in the current lamp image and hidden otherwise — a Zs3 digit is a lamp like any other, and a script’s lamps (the Zs1 below) lights them the same way.

Selectable construction kits. signal_kits/*.ron defines bases and modules referencing these model fragments. Each socket specifies (part, node), explicit accepts module IDs, a default and whether it is required. Modules can carry further sockets. A root may set signal_type, kind and system. references attaches prototype evidence to a module. See the complete format and H/V example.

The two editors divide the work the way Zusi does. The signal editor authors the kit: it creates a kit in a mod (or the mod itself), adds modules — a base form is a mast with its head, an attachment a Zs board or a hood — edits each module’s parts, lamp and motion bindings and LODs, declares the sockets a module offers and which modules they accept, maps the material variants per surface condition, and previews a module alone or fitted to any base of the kit through the very assembly the simulator runs. Its check report lists what the route editor would refuse, and every edit is undoable (Ctrl+Z / Ctrl+Shift+Z). The route editor consumes the kit: the library lists every base form, placing one puts the naked signal on the track (required sockets only), and the kit dialog that opens with it fits or removes modules socket by socket, changes the mast (compatible fittings come along) and sets the surface condition — at any later time from the signal’s panel as well. Copy and paste (Ctrl+C / Ctrl+V) duplicate a signal with its whole assembly and fittings a step further along the track; only next, the guarded sections and the routes are dropped.

SignalModel.construction retains the kit recipe. A route signal can save it together with the resolved geometry in assembled_model: Some((...)); this overrides named-model lookup in the route editor and simulator. Both fields are optional for existing content. Tag fragment models signal-kit-module to keep them out of whole-signal placement cards. The H/V migration additionally hides legacy-hv-catalogue research combinations while retaining their loading support.

Models may also declare preview_aspects: {"hp0": ["lamp_red"], "hp0_sh1": ["lamp_red", "sh1"]}. These named lamp tests appear in the signal editor and drive --aspect captures; they do not replace operational aspect rules. A lamp binding may declare aliases: ["zs8"] when several commands use one physical surface. flashing_lamps: ["zs8"] selects 1 Hz flashing for that command while other aliases remain steady. A steady command wins if both are active. Still-image preview captures hold the on phase deliberately.

An optional fitting_layout supplies model-space clearances for route-owned designation plates and additional units, for example:

fitting_layout: Some((designation: (0.0, 1.45, -0.12), front_z: 0.08,
equipment_top: 6.60, left_x: -1.0, right_x: 1.0)),

Dimensions are metres. equipment_top starts the downward side stacks; designation_size: Some((width, height)) optionally overrides the default 285 × 300 mm plate, for example for a small plate on a historical optical case. left_x and right_x keep them clear of the model’s heads. Without this metadata, existing semaphore and generic layouts remain in use. built-in:zs1 (and the corresponding tags for other Zs units) suppresses duplicate per-placement geometry while preserving its operational equipment metadata.

The generated H/V light-signal catalogue includes modular early, standard and compact construction reconstructions. Its reference status is documented separately from functional signal-image validation.

Moving parts — semaphore signals. motions binds a lamp-image string to a node that travels instead of switching: while the string is in the lamp image the node moves to full travel, without it back to rest. The default profile: Linear covers generic mechanisms. profile: Semaphore(...) drives an arm upwards with finite acceleration, then lets it fall back under gravity and rebound with diminishing height at its mechanical stop. seconds is the driven raising time, fall_seconds the free return from full travel, and rebound the coefficient of restitution (0 = no bounce). The small physics steps are independent of the render frame rate. The strings name the moved elements, so an aspect that moves two arms lists two of them (signals/hv_form.ron + signal_models/form_hp.ron):

motions: [
(lamp: "fluegel1", node: "fluegel1",
motion: Rotate(axis: (0.0, 0.0, 1.0), degrees: 45.0), seconds: 1.8,
profile: Semaphore(fall_seconds: 0.75, rebound: 0.36)),
(lamp: "fluegel2", node: "fluegel2",
motion: Rotate(axis: (0.0, 0.0, 1.0), degrees: -45.0), seconds: 1.8,
profile: Semaphore(fall_seconds: 0.85, rebound: 0.34)),
]

motion takes the same Rotate/Translate/Visibility as vehicle parts; one binding per node. Rest pose (travel 0) is the stop position.

For a rigid operating rod, an optional rod: Some((...)) on a rotation binding solves the linkage instead of rotating the whole rod around the input shaft. crank_pin is the input joint and slider the other joint in the node’s rest coordinates. Without follower_pivot, the latter travels on a vertical guide. With follower_pivot: Some((x, y, z)), it follows a circular output lever while preserving the rod length. follower_axis optionally gives that shaft’s axis; otherwise it is parallel to the input axis. follower_only: true moves the output lever itself around its fixed bearing. A second linkage stage can use driver: Some((crank_pin: (...), follower_pin: (...), pivot: (...))) to take its input from the first output lever. The example Hp, Vr and Sh models contain complete bindings, including every LOD.

A lamp behind a moving shutter or colour filter can additionally specify motion_gates: [(node: "blende1_LOD0", min: 0.96, max: 1.04)]. Each referenced motion must be in the lamp’s part and within its inclusive travel interval before the lamp is shown. All gates must pass, and the lamp-image string must still be active. Missing or invalid motion values keep the lamp dark. An empty gate list preserves ordinary lamp behaviour. This prevents a semaphore’s target colour from appearing before its filter reaches the optical axis.

The example mod also ships the full-size German mechanical family: Hp masts at 6/8/10/12/14 m nominal height from rail underside to upper blade pivot in lattice and narrow construction (one or two arms, long or shortened), Vr discs at 2.76/4.87/5.37 m (two or three aspects), and low/high Sh rotating-disc signals. Complete DB pale-green and iron-grey catalogues plus historical painted-mast and negative-blade examples make 188 base geometries. Another 42 coupled Hp models have a single drive, one equalising lever and a diagonal coupling rod, for a total of 230 geometries. The 14-m Hp models are historical special-height variants; later installation principles preferred at most 12 m. The distant-signal subset also covers gas or modern LED night signs, attached or freestanding Ne 2 boards, green or iron-grey masts and three decreasing geometry LODs. The generated example:formsignal_showcase line places every model in one row. Gas and LED Vorsignale both have moving colour filters in front of fixed lanterns. The selectors rotate about their mast bearings through approximately 52.3 degrees: the left green pane moves down, the right one up. Vr 2 moves only the right selector. The gas cylinders remain on their service lift during an aspect change; LED variants have no gas cylinders. Mast rods, equalising levers and drive wheels are separate moving assemblies. The night-sign surfaces follow the actual selector positions. Their embedded PBR maps, macro weathering and matching catalogue files are rebuilt with python tools/gen_form_signals.py; the researched dimensions, scope and naming are listed in mods/example/FORMSIGNALE.md.

Reflective sheeting. A glTF material can opt into the shared simulator/preview coating with material-level extras:

{"connected_rails":{"retroreflective":"ra2-white"}}

ra2-yellow selects the yellow coefficient table. Apply this only to the sheet face; keep backs, hardware and lamp optics on their own materials. Black areas of a face texture suppress the return, and alpha cutouts retain their shape. The coating uses incident lights, source/view angles, attenuation and shadow maps; it adds no emission. Existing PBR textures remain in use. See the H/V material review for coefficient sources, validation and remaining limits.

Levels of detail. An optional lods table switches nodes named <name>_LOD<level> by camera distance, exactly like vehicles: coarsest last, beyond the last distance the LOD nodes disappear; nodes without the suffix are every level’s furniture. Empty = the whole assembly at every distance.

lods: [(level: 0, distance: 200.0), (level: 1, distance: 2500.0)]

Which model a signal wears: model: Some("<mod>:<name>") on the signal type is the default; model on the signal placement in the line overrides it per signal. A signal without either gets a placeholder mast whose light follows the aspect.

Model conventions: origin at the foot on rail-top height, +Y up, the face towards the approaching driver looks along +Z. Mount points are empty nodes named mp_*; lamp nodes conventionally lamp_<image> (their material carries the lit look, e.g. an emissive factor — switching is pure visibility). The signal editor (trainsim-signal-editor) edits these as the modules of a construction kit: parts, mount points and lamp bindings with suggestions from these names, sockets towards other modules, and a lamp test in its preview. A single model file can still be opened on its own (File › Open model file…).

Per-placement designation plates and subsidiary signals

Section titled “Per-placement designation plates and subsidiary signals”

designation is rendered onto a real plate at runtime, so A, N1 and every other placement can share the same mast model. It uses a bundled DIN-style condensed font, not letter meshes. The plate follows the 285 × 300 mm field: a location prefix in a long name is stacked over the operational name (24 over P3) inside that one field instead of widening the plate. interlocking is operational metadata and is not painted onto the mast. Both fields are edited in the route editor and the checker reports either one missing.

addons describes only equipment physically carried by this signal. A dense but valid example is:

addons: (
zs1: Some(ThreeLights),
zs2: Some(["K", "S"]),
zs3: Some((values: [4, 6], construction: Light)),
zs6: Some(Form),
zs12: true,
)

The editor offers the prototype constructions rather than arbitrary geometry:

field selectable construction / value
zs1 ThreeLights (A) or BlinkingLight
zs2, zs2v one identifying letter per route-dependent value; several values share the fitted dot-matrix display
zs3, zs3v fixed Form board with one code, or a Light display with several codes (1 … 16; ×10 km/h)
zs6 Form board or Light strip
zs7 three yellow lights in a V
zs8 ThreeLights (flashing A) or LightStrip
zs12 fixed M board
zs13 fixed Form board or Light display
zs103 historical DV-301 board with six white diamonds

Main-signal fittings are accepted on Main/Combined, advance indicators on Distant/Combined. Zs 13 cannot be combined with a Zs 3 code 1, 2 or 3. Zs 1 and Zs 8 in A form share one three-lamp housing when both are fitted; likewise light-strip Zs 6 and Zs 8 share their physical display. Light faces listen to zs1, zs2_K, zs2v_K, zs3_4, zs3v_4, zs6, zs7, zs8 and zs13; where a display has only one possible value the generic zs2/zs3/zs2v/zs3v alias works too. Form boards, Zs 12 and Zs 103 are permanently visible.

Zs 9 and Zs 10 are deliberately not in addons: Zs 9 stands before the applicable light main signal, while Zs 10 is a separate signal inside the points area. Modelling either as mast furniture would create a placement the signal book does not permit.

The dedicated line example:zusatzsignal_showcase places every fitting, both shared housings, form/light alternatives, multi-value displays and combined examples in one row. A reproducible front overview is:

Terminal window
cargo run -p app -- --line example:zusatzsignal_showcase --loco example:br101_afb \
--camera fly --fly 0,18,280 --look 0,5,458 --hud off \
--window 1920x1080 --frames 70 --screenshot /tmp/zusatzsignal-showcase.png

Runs after the rule table and sees its result. nil keeps that result.

ctx
signal, time signal index and simulation time [s]
clear, route, route_target, diverging, next_stop, next_slow the situation, as above
main, distant, shunt, speed what the table decided ("stop", "proceed", "proceed_slow", "substitute", "dark"; "expect_stop", "expect_proceed", "expect_slow", "kennlicht"; Sh "stop"/"proceed"/"kennlicht")

The return table takes the same main, distant, shunt, speed and lamps.

"kennlicht" requests temporary operational deactivation in any of the three aspect fields. The older main-aspect spelling "dark" has the same meaning. Supply only the model’s single white-light channel in lamps; for example, an equipped H/V main head uses {main="kennlicht", lamps={"kennlicht"}}, and an equipped distant head uses {distant="kennlicht", lamps={"vr_marker"}}. This state persists through fixed simulation steps until the hook returns a normal aspect for that signal’s function. Signal hooks run in signalling order, so upstream announcements see the final scripted indication of the next active main signal. Kennlicht imposes no speed restriction of its own and does not change the movement kind. Other restrictions and always-active magnets remain. A deactivated signal cannot serve as flank protection; an existing flank lock rejects a scripted deactivation request. Track locks do not support Kennlicht.

mods/example/scripts/zs1.lua — the substitute signal, a case that needs memory:

local M = {}
local DELAY = 180.0
local at_stop_since = {}
function M.aspect(ctx)
if ctx.main ~= "stop" then
at_stop_since[ctx.signal] = nil
return nil
end
local since = at_stop_since[ctx.signal]
if since == nil then
at_stop_since[ctx.signal] = ctx.time
return nil
end
if ctx.time - since >= DELAY then
return { main = "substitute", speed = 40.0, lamps = { "red", "zs1" } }
end
return nil
end
return M