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"),)],Signal models
Section titled “Signal models”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:
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.pngAspect hook aspect(ctx)
Section titled “Aspect hook aspect(ctx)”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.0local 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 nilend
return M