Skip to content
Connected RailsConnected Rails

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.

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

  2. 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_scenario
    cargo run -p app -- --line my_mod:my_line --loco my_mod:my_loco

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

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

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

  1. Give version a semver number (1.0.0) and raise it with every release. The installer treats a package with the same id as 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.

  2. Name every mod you use in depends. If your scenario runs on example:beispielstrecke or 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"],
  3. State versions where it matters. The record form carries the dependency’s filebase uuid and 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.

  4. Copy your uuid into 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.

A .crails package is a zip of the mod directory. The simulator builds it:

  1. If the mod lives in a Git repository with Git LFS, fetch the real files first:

    Terminal window
    git lfs pull

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

  2. Pack it:

    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
    cargo run -p app -- --pack mods/my_mod # the same from a checkout

    It prints the id, the version, the number of files and the size. Hidden files and older .crails files in the directory are left out, and the same directory always packs to the same bytes.

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

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

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.