Skip to content
Connected RailsConnected Rails

Testing and distribution

Terminal window
cargo test -p mod-runtime # loads mods/, parses everything, runs the hooks
cargo run -p app -- --line example:beispielstrecke --loco example:br101_afb --frames 120
cargo run -p app -- --line example:beispielstrecke --scenario example:probefahrt
cargo run -p vehicle-editor -- mods/example/vehicles/br101_afb.ron
cargo run -p route-editor -- mods/example/lines/beispielstrecke.ron

Loading warnings and script errors go to the log with a mod: prefix.

A mod travels as a .crails package: a plain zip of the mod directory with its own extension. Build one with the simulator itself:

Terminal window
train-sim --pack mods/my_mod # writes my_mod-<version>.crails here
train-sim --pack mods/my_mod --out dist/my_mod.crails

The members sit under one folder named after the mod id (my_mod/mod.ron, my_mod/vehicles/…); hidden files (.git, editor swap files) and older .crails packages lying in the directory stay out, symbolic links are followed, and every member carries the same fixed timestamp, so the same directory always packs to the same bytes. A Git LFS pointer anywhere in the tree stops the pack — run git lfs pull first, or the package ships placeholders where the models are. A zip made by hand works too, as long as mod.ron is at its root or in exactly one top-level folder.

Players install a package in one of three ways, all of which unpack into mods/:

  • Drop the .crails onto the game window. On the main menu the mod manager opens, the package is unpacked in the background and the mod is in the list once it is done. Dropped during a run it waits — the F9 panel says so — and is installed when you return to the main menu, because an update must not swap the files the run is still loading from.
  • Open it with the game (train-sim my_mod-1.0.0.crails, which is what a double click does once the extension is associated): the menu opens on the mod manager and installs it. If there is no mods/ in the working directory but one beside the binary, the game changes to the binary’s directory first — a file association starts it wherever the file was.
  • train-sim --install a.crails b.crails installs and exits — for scripts. Packages named beside --dedicated or a run flag (--line, …) are installed before the server or the run starts; all three report on stderr.

What the installer checks:

  • Same id means update. An installed mod with the same id is replaced, wherever its directory is and whatever it is called; whether it was switched on survives the update. A new mod is installed switched on into mods/<id>/.
  • Same id, different mod is refused. If the installed copy carries a filebase uuid, the package has to carry the same one; otherwise nothing is touched. A directory mods/<id>/ that holds no mod with that id is not overwritten either.
  • Nothing leaves the mod directory. Absolute paths, .., drive letters, symbolic links, names Windows cannot store (CON, a?.lua, a trailing dot) and two members that would land on the same file (a/b and a/./b, or A/B) refuse the whole package. Unpacking stops beyond 16 GiB or 200 000 files.
  • Never half installed. The package is unpacked into a hidden mods/.<dir>.crails-new/ first (the loader skips directories starting with a dot), its mod.ron is read back, and only then is it swapped in; if anything fails the old version stays where it was. Should the game die in the middle of a swap, the next start puts the old version back.

Mods are local content: in multiplayer the server and every client need the same mods installed — a client does not download them from the server. A server turns a client away whose mods differ from its own — missing, switched off, another version, the same version with edited *.ron/*.lua files, or a mod the server does not run at all — and the client’s mod manager lists the differences (Multiplayer). Models, textures and sounds are not compared.

Your mod is yours. RON data, assets and Lua scripts that use the documented interfaces are not derivative works of the game — see the mod exception at the top of LICENSE. Ship them closed-source, sell them, pick any licence you like; no obligation to publish sources.

The EUPL only applies once you distribute the game itself, a modified copy of it, or native code linked against its crates.

Die Modellpresets für Zusatzsignale, die DB/DR-Kompatibilitätsmatrix und die historischen Signalbilder sind in FORMSIGNAL_ZUSATZSIGNALE.md dokumentiert.