Signal editor
cargo run -p signal-editor # start page: new or installed kitcargo run -p signal-editor -- mods/example/signal_kits/hv.ron # open a kitcargo run -p signal-editor -- mods/example/signal_models/ks_mast.ron # open a single signal modelThe 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.
What it is for
Section titled “What it is for”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.
Starting a kit
Section titled “Starting a kit”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/, usinga-z,0-9,_and-) and a mod name. A new mod gets a minimalmod.ronand the directoriessignal_kits/,signal_models/,signals/andassets/. - 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 kit panel
Section titled “The kit panel”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,#1and 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 putsmp_*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 outsidemods/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. ALOD<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 unboundlamp_<x>node to the image<x>and everyzs*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.
Single model files
Section titled “Single model files”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.
Viewport
Section titled “Viewport”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.
From kit to signal
Section titled “From kit to signal”Once the kit is saved, the route editor offers it:
- 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.
- 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.
- 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.
Command line
Section titled “Command line”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 |
cargo run -p signal-editor -- --kit example:hv --base kit_hv_1951_exit_6_1m_mast \ --export-model /tmp/hv_exit.roncargo run -p signal-editor -- mods/example/signal_models/ks_mast.ron \ --lamps red --screenshot /tmp/ks_red.png