Packaging and publishing
A mod is ready to hand out when it loads without warnings, says which version it is and what
it needs, and travels as one .crails file. This guide goes through those steps in order. The
full rules of the package format and the installer are in
Testing and distribution.
Test the mod
Section titled “Test the mod”-
Load it with nothing else changed. Start the simulator without arguments, open Mods, and check that your mod is listed, switched on, without a requires: … line, and that Warnings: below the list names none of your files. The page shows the first few entries; the terminal has all of them, each prefixed with
mod:. -
Run every piece of content once from the command line, so each reference is actually resolved:
Terminal window cargo run -p app -- --scenario my_mod:my_scenariocargo run -p app -- --line my_mod:my_line --loco my_mod:my_locoA name that does not resolve is not an error — the run falls back (to the BR 101, to the example line) and logs it, e.g.
vehicle my_mod:my_loco not found — using the BR 101. So read the log rather than trusting that the run started. -
Open the files in the editors. The vehicle editor’s Checks section and the route editor’s rule check (Findings in the status bar) flag what loading alone accepts but that will not work — see Troubleshooting.
-
In a checkout, run the loader test. It loads every mod under
mods/, including yours, and fails on any loading warning other than a missing Git LFS object:Terminal window cargo test -p mod-runtime
More test invocations, including the editors, are in Testing and distribution.
Set the version and the requirements
Section titled “Set the version and the requirements”-
Give
versiona semver number (1.0.0) and raise it with every release. The installer treats a package with the sameidas an update of the installed mod, and the mod manager reports Updated … from 1.0.0 to 1.1.0. A version that is not semver makes every version requirement on your mod fail with a warning. -
Name every mod you use in
depends. If your scenario runs onexample:beispielstreckeor your line uses a track type of another mod, that mod belongs in the list. For local use the plain id is enough:depends: ["example"], -
State versions where it matters. The record form carries the dependency’s filebase
uuidand a semver requirement, and that is what the filebase and the simulator check:depends: ["example",(id: "wolfsburg", uuid: "0193…", version: ">=1.18.0"),],A violated requirement, a uuid that belongs to another mod, or a dependency without a version is a warning in the mod manager, never a loading error.
-
Copy your
uuidinto the manifest once the Connected Rails filebase has assigned one on your first upload. From then on the installer only replaces an installed mod with the same id if the uuids agree, so another author’s mod of the same id cannot overwrite yours.
The fields are described in Mod structure.
Pack it as .crails
Section titled “Pack it as .crails”A .crails package is a zip of the mod directory. The simulator builds it:
-
If the mod lives in a Git repository with Git LFS, fetch the real files first:
Terminal window git lfs pullA pointer file anywhere in the mod stops the pack (
… is a Git LFS pointer — run git lfs pull first), because the package would otherwise ship placeholders. -
Pack it:
Terminal window train-sim --pack mods/my_mod # writes my_mod-<version>.crails heretrain-sim --pack mods/my_mod --out dist/my_mod.crailscargo run -p app -- --pack mods/my_mod # the same from a checkoutIt prints the id, the version, the number of files and the size. Hidden files and older
.crailsfiles in the directory are left out, and the same directory always packs to the same bytes. -
Install the package once yourself before you hand it out — into a copy of the game, or after moving your working folder out of
mods/:Terminal window train-sim --install dist/my_mod.crailsDropping the file onto the game window or opening it with the game does the same. Then repeat the test above on the installed copy. A package installs into
mods/<id>/, which is why the loader warns about a mod folder not named after its id (Troubleshooting).
What the installer refuses and how it updates safely is listed under Distribution.
Multiplayer: the same mods on every machine
Section titled “Multiplayer: the same mods on every machine”Mods are not downloaded from a server. Every player installs them, and a server admits a
client only if both run exactly the same set of enabled mods. It compares, per mod, the id,
the version, the filebase uuid and a digest of the *.ron and *.lua files; models,
textures and sounds are not compared. A client is turned away when a mod is:
- missing or switched off on the client,
- switched on on the client but not run by the server,
- a different mod under the same id (another uuid),
- another version, or the same version with edited data files.
The refused client’s menu opens on Mods with that list. For you as an author this means: raise the version for every change you hand out, even a one-line fix. Two players with “1.0.0” but different files are refused as having an edited copy, which is harder to sort out than a version number.
How joining works in full is in Multiplayer.
Choose a licence
Section titled “Choose a licence”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. You may ship them closed, sell them, or put them under any licence; the EUPL only applies to the game itself, modified copies of it, and native code linked against its crates. Details: Licensing your mod.
What you do have to respect are the licences of anything you did not make yourself: a CC BY
model, texture or sound needs its credit. The shipped mods record the source and licence of
such files beside the content, for example mods/trees/LICENSES.md.