Skip to content
Connected RailsConnected Rails

Adding a signal

A signal in Connected Rails has three layers, and each one is a file of its own:

Layer File Answers
Signal type signals/*.ron Which aspect and which lamp images does the signal show in each situation?
Signal model or kit signal_models/*.ron, signal_kits/*.ron What does it look like, and which glTF node lights up for which lamp image?
Placement the line’s devices and signals Where does it stand, what does it guard and announce, and which magnets belong to it?

The interlocking is country-neutral. It works out the situation of a signal, and the signal type turns that into an aspect. The worked example on this page is the Ks main signal of the example mod: ks_main.ron with the model ks_mast.ron, placed on beispielstrecke.ron.

A signal type is a rule table. The first rule whose when matches wins, and an empty when: () matches everything, so it goes last. show is the aspect the interlocking and the train protection see. lamps is a list of free-form strings that your model turns into geometry. Here is mods/example/signals/ks_main.ron, shortened:

(
name: "Ks combination signal",
system: Ks,
rules: [
// Hp 0: the block ahead is occupied or the route is not locked.
(when: (clear: Some(false)), show: (main: Some(Stop)), lamps: ["red"]),
// Ks 2 with Zs 3: diverging route, 40 km/h.
(when: (diverging: Some(true)),
show: (main: Some(ProceedSlow), distant: Some(ExpectStop), speed: Some(40.0)),
lamps: ["yellow", "zs3_4"]),
// Ks 2: proceed, expect stop at the next signal.
(when: (next_stop: Some(true)),
show: (main: Some(Proceed), distant: Some(ExpectStop)), lamps: ["yellow"]),
// Ks 1: proceed, the next signal shows proceed as well.
(when: (), show: (main: Some(Proceed), distant: Some(ExpectProceed)), lamps: ["green"]),
],
script: None,
model: Some("example:ks_mast"), // default 3D model, a placement may override it
tags: ["ks", "main-signal"],
)

Save it in your own mod as signals/<name>.ron. It is then addressed as <mod>:<name>. The when conditions (clear, route, route_target, shunting, diverging, next_stop, next_slow) and the show values are listed in the signals reference. Give the type a name, because the route editor’s library shows it on the card.

A rule table needs no geometry. A signal type without a model and without a model on the placement gets a placeholder mast whose light follows the aspect. That is enough to test the logic before any modelling.

The example mod has two smaller tables worth reading. gleissperre.ron is a track lock with two rules and the lamp images sperre_auf and sperre_ab. formsperrsignal.ron is a shunting signal.

2. Add an aspect hook if the table is not enough

Section titled “2. Add an aspect hook if the table is not enough”

Anything that needs memory or a timer goes into Lua. The hook runs after the rule table and sees its result; returning nil keeps it. ks_main_zs1.ron is the same Ks table with one change:

script: Some("example:zs1"),

example:zs1 is mods/example/scripts/zs1.lua. It shows the substitute signal Zs 1 after the signal has been at stop for three minutes:

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

The hook can light lamp images the table never uses (zs1 here). The model only has to bind them. The complete ctx and return table are in Aspect hook aspect(ctx).

A signal model is put together from shared glTF parts, so a screen modelled once can hang on a mast in one place and under a bridge in another. The example’s three parts are generated by tools/gen_signal_parts.py and show the conventions:

File Nodes
example/assets/sig_mast.gltf mast_LOD0, mast_LOD1, mount point mp_schirm
example/assets/sig_schirm_ks.gltf schirm, lamp_red, lamp_green, lamp_yellow, lamp_zs1, mount point mp_top
example/assets/sig_zs3.gltf board, the digit zs3_4
  • Put the origin at the foot, at rail-top height. +Y is up, and the face that the approaching driver sees looks along +Z.
  • Mount points are empty nodes named mp_*.
  • Lamp nodes are conventionally named lamp_<image>. A lamp is shown or hidden as a whole, so its material carries the lit look, for example an emissive factor.
  • <name>_LOD<n> nodes switch by camera distance. Nodes without the suffix appear at every level.

Semaphore arms, filters and track-lock shoes move instead of switching. They are bound as motions; see Signal models.

mods/example/signal_models/ks_mast.ron chains the parts and binds the lamp images of the signal type to nodes:

(
name: "Ks combination signal · mast",
parts: [
(file: "example/assets/sig_mast.gltf"), // #0 at the signal position
(file: "example/assets/sig_schirm_ks.gltf", mount: Some((0, "mp_schirm"))), // #1 on the mast
(file: "example/assets/sig_zs3.gltf", mount: Some((1, "mp_top"))), // #2 on the screen
],
lamps: [
(lamp: "red", part: 1, node: "lamp_red"),
(lamp: "green", part: 1, node: "lamp_green"),
(lamp: "yellow", part: 1, node: "lamp_yellow"),
(lamp: "zs1", part: 1, node: "lamp_zs1"),
(lamp: "zs3_4", part: 2, node: "zs3_4"),
],
lods: [(level: 0, distance: 200.0), (level: 1, distance: 2500.0)],
tags: ["ks", "mast", "zs3"],
)

A node is visible while its string is in the current lamp image. Every lamp string the signal type or its script uses needs a binding here, or nothing lights up for it.

You do not have to type this by hand. Open the file in the signal editor with File › Open model file…, or:

Terminal window
cargo run -p signal-editor -- mods/example/signal_models/ks_mast.ron

Use Add part… for each glTF file and pick its Mount (part and mp_* node). Take over all suggestions binds every lamp_<x> and zs* node, and Read from node names fills the LOD table. The lamp test then lights each string in the viewport, so missing bindings show up before you place anything. Save writes the file back.

Link the model to the type with model: Some("<mod>:<model>") in the signal type. A placement can still override it.

If your signal family has many variants, such as mast heights, heads, Zs boards or surface conditions, build a signal kit instead of one model per combination. Start it with File › New kit… in the signal editor. Each piece becomes a module with its own fragment in signal_models/. A base form names its signal type, kind and system. Sockets on the base’s mount points list the attachments they accept. The editor’s test assembly and its check show what the route editor will build. The example mod’s hv.ron, form.ron and ks_siemens.ron are complete kits. The format is described in Signal models and the H/V kit notes. The workflow is in the signal editor page.

Open the line in the route editor and open the Library (Ctrl+Space):

  • Signal types lists complete signals. A click arms Place device with that type and its default model.
  • Signal kits lists the base forms. A click arms Place device with the bare signal, and after placement the kit dialog opens so you can fit heads and boards socket by socket.

Click the track where the signal stands. Placing a signal armed from the library also creates its signal table entry: the device is only a position, and the entry is what the interlocking reads. A signal device placed without a type or model gets its entry from Create signal entry in the selection panel. Fill the entry in there:

Field Meaning
Signal designation The operational name, painted on the mast’s plate (20, 24P3). The editor starts with S<n>
Interlocking The interlocking that controls it (Bks)
Kind, System Main, distant, combined, shunting or track lock; H/V, Ks or Hl
Announces For a distant signal: the main signal it repeats
Needs a route The signal stays at stop until a route is set from it. Station signals need it, block signals do not
Diverging speed The speed of the diverging route (Zs 3). Without it the signal shows no speed indicator
Guards sections The sections that must be clear
Signal type, 3D model The type, and an optional model that overrides the type’s default

Then lay out the routes from it (Find routes or the Interlocking panel; see Lines). In the file, the result for the example’s Ks main signal and its distant signal is:

devices: [
// ...
(kind: Signal, edge: 0, s: 2000.0, lateral_offset: 3.0, payload: "(signal:Some(0))"),
// ...
(kind: Signal, edge: 0, s: 1000.0, lateral_offset: 3.0, payload: "(signal:Some(3))"),
],
signals: [
(designation: "20", interlocking: "Bks", kind: Main, system: Ks,
device: 1, guarded: [0], signal_type: Some("example:ks_main")),
// ...
(designation: "v20", interlocking: "Bks", kind: Distant, system: Ks,
device: 9, next: Some(0), guarded: []),
],

device points into the device table, and the device’s signal payload points back into the signal table. The distant signal v20 has no type and no model, so it draws the placeholder mast. Its next: Some(0) makes it show expect stop while signal 20 is at stop.

Place each magnet with Place device (device kind PZB magnet). It starts as an unlinked 1000 Hz magnet. Set Construction and Frequency in the selection panel, then use the Link PZB magnet tool: click the magnet, then the signal that controls it. An unlinked magnet is always active. The example line equips its Ks main signal the usual way:

// 1000 Hz at the distant signal, active while it announces a restriction.
(kind: Magnet, edge: 0, s: 1000.0, payload: "(frequency:Hz1000,signal:Some(3),activation:WhenRestrictive)"),
// 500 Hz 250 m before the main signal, 2000 Hz at the signal itself.
(kind: Magnet, edge: 0, s: 1750.0, payload: "(frequency:Hz500,signal:Some(0),activation:WhenStop)"),
(kind: Magnet, edge: 0, s: 2000.0, payload: "(frequency:Hz2000,signal:Some(0),activation:WhenStop)"),

signal refers to the signal table, not the device table. The 1000 Hz magnet is linked to the distant signal, because WhenRestrictive asks the linked signal for its distant indication. A main signal at stop announces nothing; it is the restriction. The route editor’s Checks list flags the usual gaps, such as a distant signal without its 1000 Hz magnet or a main signal without its magnet. Fix what it lists before you save. The designation and the interlocking are checked as well.

Start the line and drive up to the signal:

Terminal window
cargo run -p app -- --line example:beispielstrecke

Things to watch for:

  • The aspect. Each situation of your table should appear: stop while the block ahead is occupied, the slow aspect over a diverging route, the distant aspect ahead of a main signal at stop. A signal type with no matching rule shows stop.
  • The lamps. Every lamp image lights its node. A string without a binding stays dark without any error, so compare against the signal editor’s lamp test.
  • The magnets. PZB should react at the distant signal and in front of the main signal while it shows stop, and stay quiet when it shows proceed.
  • The script. A Lua error switches the script off after the first error and the run continues with the table alone, so a hook that never fires is worth checking in the log.