Mod structure
Connected Rails is built for mods: your own locomotives, your own signals, your own lines.
mods/example/ is a working reference — copying it is the fastest way to start.
Data and behaviour are separate
Section titled “Data and behaviour are separate”The bulk of a locomotive is declaration, not script: masses, running resistance, brake equipment, tractive effort curve, later model paths, sounds and cab layout. All of that is RON — validated while loading, diffable, editable without programming.
Lua only covers real behaviour, the things a table cannot express: tap changer logic, AFB, start-up procedures, the choice of a signal aspect that depends on time or memory. That keeps roughly 80 % of every mod declarative, checkable and safe.
Structure of a mod
Section titled “Structure of a mod”mods/<id>/mod.ron manifest /vehicles/*.ron VehicleSpec /lines/*.ron LineSource — a line, or a module with `boundaries` /compositions/*.ron Composition — modules chained into one line /scenarios/*.ron Scenario /timetable/*.ron Timetable — referenced by a scenario for stop scoring /days/*.ron OperatingDay — a whole day of services, looping every 24 h /jobs/*.ron ShuntJob — a shunt job a scenario script hands an AI driver /signals/*.ron SignalType /signal_models/*.ron SignalModel — glTF parts on mount points, lamp bindings /signal_kits/*.ron signal kits of the signal editor: modules, parts, sockets /track_types/*.ron TrackType — superstructure: texture, speed limit, roughness, reverb /objects/*.ron track and scenery objects: a model plus its pose relative to the track /blocks/*.ron block presets for the vehicle editor's palette /characters/*.ron CharacterSpec — a person model: the walker's body, the passengers /scripts/*.lua behaviour /assets/… models, textures, sounds — as `mods://<id>/assets/…`Asset paths are written relative to mods/ and so start with the mod’s folder name.
Name the folder after the mod’s id: a .crails package always installs into
mods/<id>/, and a mod whose folder is named differently loses its assets there — the
loader warns about such a folder.
Everything is addressed as "<mod>:<file stem>" — mods/example/vehicles/br101_afb.ron
becomes example:br101_afb. Two mods may therefore use the same file names.
mod.ron:
( id: "example", uuid: "01939f5e-6c7a-7c3a-9d2b-1f4a8e5b2c10", // optional, from the mod website name: "Example Mod", version: "0.1.0", author: "Connected Rails", description: "Reference mod: a vehicle with an AFB script, two signal types with a 3D signal model, and a line.", depends: [], enabled: true,)Only id and name are mandatory. depends lists mods that have to be loaded first;
enabled: false skips the mod without deleting it. An optional library block says what
the route editor’s library lists of the mod and tags whole groups of files at once — see
The library.
The uuid is the mod’s identity across installations. The Connected Rails filebase assigns
it on the first upload and shows it to the author; copy it into the manifest so later uploads and
catalogue dependencies can be matched even when another author has used the same id. Without a
uuid the simulator still loads the mod — a hand-written mod simply has none.
Each entry of depends is either the plain mod id (the old form) or a record with uuid and a
semver requirement. The record is what the filebase and the simulator check; the plain id
stays valid for local mods:
depends: [ "example", // just the id (id: "wolfsburg", uuid: "0193…", version: ">=1.18.0"), // identity + version],Requirements use the usual semver operators (>=, >, <=, <, =, ^, ~, *). A
violated requirement, a uuid that does not belong to the installed mod, or a dependency without a
version is a warning in the mod manager, never a loading error.
The mod manager lives on the main menu (start the simulator without arguments): every
installed mod with its version, whether it is switched on, which of its dependencies are
missing, and the loading warnings. ↑/↓ pick a mod, Enter switches it on or off — that writes
enabled back into its mod.ron (only that field; comments in the file survive) and takes
effect when the run starts. F9 opens the same list in the simulator; a toggle there only
takes effect after a restart, because reloading mid-run would mean rebuilding line, trains
and interlocking.
Nothing is fatal. A broken file produces a warning, everything else still loads. A script that raises an error is switched off after the first error and the run continues. A signal type without a matching rule shows stop.
Scenery objects, signal types, signal models and track types each take a tags list — free
words the mod author picks, which the route editor’s library (content drawer) searches:
tags: ["mast", "catenary", "epoch-4"],The field is optional and defaults to empty; a mod without tags loses nothing but the search.
Tags are lower case, words joined by hyphens — the signal editor normalises what is typed
(Epoch 4 becomes epoch-4), and the library normalises again when it reads a hand-written
file, so Mast and mast are one tag and not two.
Most tags are free: there is no registry, and what a line builder searches for is what the
mods around them happen to agree on — the kind of thing (main-signal, catenary,
platform), the region, the state of the model (lod0, wip). Two prefixes are a fixed
vocabulary and become filters of their own in the library, because they are the questions
every line builder asks:
| Tag | Library filter | Values |
|---|---|---|
epoch-<n> |
Epoch | epoch-1 … epoch-6 (the railway epochs I–VI) |
operator-<name> |
Operator | operator-db, operator-dr, operator-drg, … |
Give an entry every epoch it fits (epoch-4, epoch-5). Use one name per operator across
its history — operator-db for the Deutsche Bundesbahn and DB AG alike, as the epoch already
says which — or the filter splits into two entries for one railway. An entry without any epoch tag
passes every epoch filter — a tree or a buffer stop belongs to all of them — so tagging is
something to add where it helps, never a duty; the same goes for the operator. The signal
editor offers the epochs as six toggles under the tag field.
A tag names the entry, not the placement: a mast tagged epoch-4 stays that mast wherever a
line puts it. Nothing in the simulator reads tags — they exist for finding things in the
editor, and adding one can never change how a run behaves.
One tag does more than filter a list. The route editor’s imagery detection
(Detecting from the aerial imagery) places objects by tag: a model’s class list names
car, and the editor drops a random object tagged car from the installed mods wherever
it found one in the photograph. So a mod full of lorries becomes what a lorry detector
places by carrying the tag its ai.ron entry names, and nothing else has to be written on
either side. Tag what should be placed automatically, and leave the tag off the entry that
should not — a wreck, a museum piece, the one that is already standing somewhere by hand.
Trees are tagged the same way and planted rather than placed. A model class marked
kind: Tree names a tag like any other — laubbaum, nadelbaum, strauch on the shipped
mods/trees — and every entry carrying it is a species the detection may plant where it
read a crown. What it plants there is a row in the module’s own tree list, so a tree mod
needs nothing beyond the tags it already carries for the forest brush.
Give those entries a footprint. One tag holds more than one size of thing —
lorry in mods/cars is a 4.82 m Transporter and a 6.30 m Sprinter, laubbaum in
mods/trees is everything from a nine-metre crown to an eighteen-metre one — and the
detection measures every find it makes. With the sizes stated it will not put the Sprinter in a
space that has room for the Transporter; without them it picks between the two by
coin, and half the vans in a car park stand a metre and a half out of their bays. The
choice among what does fit stays the random-but-stable one, so a row of spaces is still a
row of different cars.
The library
Section titled “The library”The route editor’s library lists every entry of every installed mod. A mod decides
two things about its entries there in its mod.ron, by path instead of file by file:
library: ( // Kept out of the list — still loaded, still usable by lines and kits. hide: ["signal_models/form_*"], // Added to the tags of every entry whose path matches. tags: { "signals/ks_*": ["epoch-5", "epoch-6", "operator-db"], "signal_kits/ks_siemens/*": ["epoch-5", "epoch-6", "operator-db"], "track_types/b70*": ["epoch-4", "epoch-5", "epoch-6", "operator-db"], },),A path is the file’s folder and name inside the mod, without .ron: objects/oak,
signals/ks_main, track_types/b70. A base form of a signal kit is one level deeper,
signal_kits/<kit>/<base>. * stands for any run of characters. So one line covers a
family of five thousand generated files, and changing it needs no generator run — the
example mod hides its pre-built form signal combinations this way, because its
“Mechanical signals” kit is how a builder places those.
hidekeeps entries out of the list. They still load, and every line, kit or signal type that names one keeps working. The library says how many each category keeps out (“Hidden: 437”) and Show hidden lists them, marked as hidden — so an author can still check that a file loaded. Use it for building blocks, generated variants and demo-only entries.tagsadds tags to everything a pattern matches, on top of the entry’s owntags. It is the easy way to give a whole family its epochs and operator.
Give every listed signal type and signal model a name — without one its card carries the
file name, and hv_1969_exit_6_1m_mast_zs3-form_n10 is not something a builder reads. Put a
no-break space (U+00A0) between a number and its unit so a card never breaks the line
between them. The signal editor has the field for loose models; a kit module is named in its
kit.
Both only concern the editor; a run never reads them. Kit modules — the parts a kit
assembles signals from, tagged signal-kit-module by the signal editor — are not entries
at all and never appear, hidden or not.