Skip to content
Connected RailsConnected Rails

Signal editor

Terminal window
cargo run -p signal-editor # start page: new or installed kit
cargo run -p signal-editor -- mods/example/signal_kits/hv.ron # open a kit
cargo run -p signal-editor -- mods/example/signal_models/ks_mast.ron # open a single signal model

The binary is trainsim-signal-editor. Run it from the directory that holds mods/, the same place you run the simulator from. The editor reads and writes the mods below it, and it addresses part files relative to that mods/ directory, the same way the simulator loads them.

The signal editor builds signal construction kits. The work is split between two editors the way Zusi splits it:

  • The signal editor builds the kit. That means the modules of a signalling system, the sockets the modules offer each other, and each module’s glTF parts, mount points, lamp and motion bindings and levels of detail. A base form is a module that is placed on the track as a whole signal, usually a mast with its head. An attachment hangs in a socket of another module, like a Zs board, a second head or a hood.
  • The route editor builds signals from the kit. You place a base form, then fit attachments socket by socket in its kit dialog (see From kit to signal).

Finished signals are therefore not assembled in this program. It creates kits, for example a whole new signalling system, and extends them, for example with a new mast or a new Zs board. The formats it writes are described in the signals reference. For a walk from a signal type to a signal on a line, see the guide Adding a signal.

What Where
A kit mods/<mod>/signal_kits/<file>.ron; the kit’s id is <mod>:<file>
A module’s geometry and bindings (its fragment) mods/<mod>/signal_models/<module>.ron, a SignalModel
Part files anywhere in a mod, stored as <mod>/assets/<file>.gltf relative to mods/
Language choice %APPDATA%\Connected Rails\signal-editor.ron on Windows, $XDG_CONFIG_HOME or ~/.config elsewhere

At startup the editor reads every enabled mod’s signal_models/, signal_kits/ and the names of its signals/ types. Kit › Reload installed mods reads them again after files were changed outside the editor.

A kit opened from disk has to lie in a signal_kits/ directory of a mod. Save (Ctrl+S) writes the kit file and every fragment of the same mod that has changed. A fragment that belongs to another mod is referenced and never written; saving reports it. The kit file is rewritten from its data on every save, so comments written into it by hand do not survive.

A new module gets the tag signal-kit-module, which keeps it out of the route editor’s whole-signal cards. A mast or a board on its own is a module, not a signal.

With nothing open, the panel offers New kit…, Open kit… and Open model file…, the list of installed kits with an Open button each, and the files that failed to load.

File › New kit… (Ctrl+N) asks for:

  • Mod: an installed mod, or New mod… with a mod id (a directory below mods/, using a-z, 0-9, _ and -) and a mod name. A new mod gets a minimal mod.ron and the directories signal_kits/, signal_models/, signals/ and assets/.
  • File name: the kit file’s name without .ron.
  • Name: shown in the route editor. A localisation key the mod ships works too.

The new kit stays unsaved until the first Save.

Menu Entries
File New kit… (Ctrl+N), Open kit… (Ctrl+O), Open model file…, Save (Ctrl+S), Save as… (single model files only), Close, Quit
Edit Undo (Ctrl+Z), Redo (Ctrl+Y or Ctrl+Shift+Z)
Kit New module…, Duplicate module…, Remove module, Reload installed mods
View Language (remembered between runs)
Help Mouse controls, model conventions, the kit workflow, About

The panel on the left is a column of sections. The kit sections come first. When a module is selected, its own sections follow.

Kit. The name of the kit, its id, its file, and how many base forms and attachments it has.

Modules. Base forms and attachments in two lists, filtered by id or name. New module… asks for:

  • an id (a-z, 0-9, _ and -). Sockets and saved routes refer to it, so it cannot be changed later, and it is also the fragment’s file name.
  • a name
  • whether it is a base form
  • where its parts come from: nothing (you add parts afterwards), a copy of another module of the kit, or an installed signal model from any mod

Duplicate module… opens the same dialog, pre-filled as a copy. Remove module takes the module out of the kit and out of every socket’s accepted list and default. Its model file stays on disk.

Module. The selected module’s id, model, name and the Base form switch. A base form also names its Signal type (the rule table the placed signal takes its aspects from), its Kind (main, distant, combined, shunting, track lock) and its System (H/V, Ks, Hl). An attachment shows which sockets accept it, or warns that none does yet. Prototype references is a list of links to the evidence behind the module.

Sockets. A socket is a mount node (mp_…) on one of this module’s parts, together with the list of modules that may hang there. Each socket has:

Field Meaning
Name Shown in the kit dialog. A localisation key works too
Part, Mount node Where the attachment hangs
Accepts Only these modules can be fitted here. Compatibility is set by hand and never guessed from matching node names
Default Fitted when the base is placed with defaults. A required socket needs one
Required The route editor cannot leave the socket empty
Restore default in old routes A route saved before this socket existed gets the default. Use it when equipment moves out of a mast into a socket of its own

Surface conditions. For New, Maintained, Weathered and Heavily weathered, the file that replaces each part. The geometry and node names of a replacement must match the original.

The module’s model. These sections edit the fragment itself. A single model file opened on its own shows the same sections:

  • Tags: free-form tags for the library, including the epoch tags.
  • Parts: one card per glTF file, numbered #0, #1 and so on. Use … to pick another file and × to remove a part. Mount places the part at the signal position or on a mount point of another part. The node list puts mp_* nodes first and leaves out parts that would mount below themselves. Removing a part also removes the bindings that used it and renumbers the rest. A file outside mods/ is refused: copy it into your mod first.
  • Levels of detail: Read from node names fills the table from <name>_LOD<n> nodes with default distances. A LOD<n> chip shows that level in the viewport.
  • Motions: moving nodes for semaphore arms and shoes, with lamp image, part, node, motion (rotate, move, visibility), travel time and profile (linear or mechanical semaphore with fall time and rebound). Rod linkages are edited here as well.
  • Lamps: one card per binding of a lamp-image string to a node of a part. The node list puts lamp_* nodes first, and a node the loaded file does not have turns red. Take over all suggestions binds every unbound lamp_<x> node to the image <x> and every zs* node to its own name.
  • Subsidiary signals: the Zs fittings the model physically carries, with a warning for an invalid selection.

Preview. Show puts the module in the viewport by itself (module alone) or as a test assembly on one of the kit’s bases (on …). The test assembly is built by the same code the route editor and the simulator use. When the selected module changes, the test assembly follows it onto the same base.

Lamp test. One toggle per lamp image of the model, motion strings included, so toggling a semaphore string swings its arm. All off clears them. Named lamp tests from the model’s preview_aspects appear as chips above the toggles. Preview designation draws a name plate the way the simulator draws a placement’s designation. Leave it empty to hide the plate. The lamp test works without starting the simulator.

Check. The problems the route editor would refuse, for example a kit without a base, an unknown model, a socket without a mount node or accepted modules, a default the socket does not accept, or a required socket without a default. It updates after every edit.

File › Open model file… opens one signal_models/*.ron outside any kit. Use it for a model that a signal type names directly with model:. The panel then shows the model’s Name (what the route editor’s library calls it), the model sections above, and the lamp test. Save writes back to the file, and Save as… writes it somewhere else.

Hold the right mouse button to rotate the camera around the signal and use the wheel to zoom. The model conventions are listed under Help: origin at the foot, +Y up, the front facing the driver along +Z, mount points as empty mp_… nodes.

Every edit can be undone, up to 64 steps. Consecutive frames of one drag count as one step. Undo restores the kit, its fragments and the selected module. The preview (lit lamps, the LOD shown, the test base) is not part of the history. While a text field has focus, Ctrl+Z is the field’s own undo.

Once the kit is saved, the route editor offers it:

  1. The library’s Signal kits category lists every base form of every installed kit. A click arms the Place device tool with the naked signal: the base with its required sockets only, plus the type, kind and system the base names.
  2. A click on a track places it and creates its signal table entry, and the kit dialog opens. Choose the base and mast first, then decide for each socket what is fitted there, or nothing, and set the surface condition. Every valid change goes straight into the signal.
  3. The signal’s panel reopens the dialog later (Construction kit…). Return to named model drops the kit assembly, and the signal falls back to its type’s model or a named model. A signal without a kit can be built from one with Build from kit….

The route saves the recipe together with the resolved geometry in the signal’s assembled_model. If you remove a module, routes that fitted it cannot assemble until they are changed.

For review tooling and reproducible pictures, the editor takes these flags in addition to a kit or model file:

Flag Effect
--kit MOD:KIT --base MODULE Open the kit with a test assembly on that base
--attach SOCKET=MODULE, --detach SOCKET Fit or empty a socket of that assembly. Nested sockets are written parent::child
--aging new|maintained|weathered|heavy The surface condition of the assembly
--export-model PATH Write the assembled SignalModel to PATH and exit
--aspect NAME, --lamps a,b Light a named lamp test, or the given lamp images
--lod N, --designation TEXT Show that level of detail, draw that name plate
--screenshot FILE, --frames N, --render-only Capture the viewport and exit
--view, --focus, --background, --target-node, --isolate-target, --from-aspect, --motion-time, --bounds-json Camera, framing and motion settings for captures
Terminal window
cargo run -p signal-editor -- --kit example:hv --base kit_hv_1951_exit_6_1m_mast \
--export-model /tmp/hv_exit.ron
cargo run -p signal-editor -- mods/example/signal_models/ks_mast.ron \
--lamps red --screenshot /tmp/ks_red.png