Testing and distribution
Testing
Section titled “Testing”cargo test -p mod-runtime # loads mods/, parses everything, runs the hookscargo run -p app -- --line example:beispielstrecke --loco example:br101_afb --frames 120cargo run -p app -- --line example:beispielstrecke --scenario example:probefahrtcargo run -p vehicle-editor -- mods/example/vehicles/br101_afb.roncargo run -p route-editor -- mods/example/lines/beispielstrecke.ronLoading warnings and script errors go to the log with a mod: prefix.
Distribution
Section titled “Distribution”A mod travels as a .crails package: a plain zip of the mod directory with its own
extension. Build one with the simulator itself:
train-sim --pack mods/my_mod # writes my_mod-<version>.crails heretrain-sim --pack mods/my_mod --out dist/my_mod.crailsThe 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
.crailsonto 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 nomods/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.crailsinstalls and exits — for scripts. Packages named beside--dedicatedor 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
idis 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 intomods/<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 directorymods/<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/banda/./b, orA/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), itsmod.ronis 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.
Licensing your mod
Section titled “Licensing your mod”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.