Skip to content
Connected RailsConnected Rails

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.

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.

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 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.

  • hide keeps 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.
  • tags adds tags to everything a pattern matches, on top of the entry’s own tags. 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.