Skip to content
Connected RailsConnected Rails

Your first mod

This guide builds the smallest useful mod: a folder with a manifest and one scenario that runs on the example line. Nothing in it needs a programming language, and every step can be checked in the simulator straight away.

A mod is a directory below mods/. The simulator looks for mods/ in the working directory it is started from; if there is none there but one beside the binary, it uses that one. In a checkout of the repository that is mods/ at the repository root, next to the shipped mods (example, trees, people, cars, …).

The loader reads every directory below mods/ that holds a mod.ron. Directories whose name starts with a dot are skipped, and so is a directory without a manifest. The folder layout inside a mod — vehicles/, lines/, scenarios/, scripts/, assets/, … — is listed in Mod structure.

  1. Pick an id. It is how every other file refers to your mod, and it has to work as a folder name on every system: ASCII letters, digits, -, _ and ., at most 64 characters, not starting with a dot. This guide uses my_first_mod.

  2. Create the folder under that same name: mods/my_first_mod/. The loader goes by the id in the manifest, but a .crails package always installs into mods/<id>/, and asset paths start with the folder name — so a folder named otherwise is a loading warning (see Troubleshooting).

  3. Write mods/my_first_mod/mod.ron:

    (
    id: "my_first_mod",
    name: "My First Mod",
    version: "0.1.0",
    author: "Your Name",
    description: "A short test run on the example line.",
    depends: ["example"],
    enabled: true,
    )

What the fields do:

  • id and name are the only mandatory fields. name is what the mod manager shows.
  • version is a semver version (0.1.0, 1.2.3). Other mods state requirements against it, and the packager puts it into the file name, so give it one from the start.
  • author and description are free text.
  • depends lists the mods yours builds on. The scenario below runs on a line from the example mod, so it names example. A missing dependency is shown in the mod manager; it does not stop anything from loading.
  • enabled is what the mod manager switches. It defaults to true; false keeps the mod installed but unread.

The optional uuid, the detailed depends form with version requirements and the library block are described in Mod structure; you need none of them for a first mod.

Compare with the manifest of the example mod, mods/example/mod.ron.

Every file of a mod is known as "<mod id>:<file stem>". A file mods/my_first_mod/scenarios/erste_fahrt.ron becomes my_first_mod:erste_fahrt; mods/example/lines/beispielstrecke.ron is example:beispielstrecke. Two mods may therefore use the same file names without clashing, and a reference into another mod is simply that mod’s id in front of the name. These names are what the command line flags, the menu and other files (a scenario’s line, a consist’s vehicle) use.

A scenario is a list of events: a trigger and what happens when it fires. It is the simplest piece of content that is worth starting, because it can reuse a line and a vehicle that already exist.

  1. Create mods/my_first_mod/scenarios/.

  2. Write mods/my_first_mod/scenarios/erste_fahrt.ron:

    (
    name: "Erste Fahrt",
    description: "Pull away and stop at the main signal at km 2.0.",
    // Local date and time at the start of the run.
    start: (year: 2026, month: 8, day: 15, hour: 9, minute: 0, utc_offset: 2.0),
    player_train: 0,
    events: [
    (
    name: "welcome",
    trigger: Time(2.0),
    actions: [Message("Proceed to the main signal at km 2.0.")],
    ),
    (
    name: "arrived",
    trigger: TrainStopped(train: 0, edge: EdgeId(0), s: 1980.0, radius: 60.0),
    actions: [
    Score(points: 20, reason: "Stopped at the signal"),
    Finish(success: true, reason: "First run complete"),
    ],
    ),
    ],
    // The line from the example mod — the reason for `depends: ["example"]`.
    line: Some("example:beispielstrecke"),
    )

The file is a trimmed copy of mods/example/scenarios/probefahrt.ron, which adds a script and a timetable on top. The scenario names its line but brings no train of its own, so the menu asks for a vehicle; a scenario can also place its own trains with consists. Every field, trigger and action is in Scenarios and timetable runs and Modules, scenarios and operating days.

  1. Start the simulator without arguments — cargo run -p app in a checkout, or the train-sim binary of a release.
  2. Choose Mods on the title screen. Every installed mod is listed with its name, id and version; my_first_mod 0.1.0 should be among them. A mod whose dependencies are missing or switched off carries the line requires: … (missing or switched off).
  3. Select it with ↑/↓ and press Enter to switch it on or off. This writes enabled back into your mod.ron — only that field, your comments stay — and the change applies to the next run.
  4. Below the list, Content: counts what the enabled mods contribute, and Warnings: lists what failed to load. If your scenario file has a mistake, it shows up here.
  5. Go back with Esc, choose Drive, and find Erste Fahrt under the example line’s route. Pick a vehicle and start the run.

In a run, F9 opens the same list; a toggle there only takes effect after a restart. The menu itself is described in Main menu and settings.

Any run flag skips the menu, which is quicker while you iterate:

Terminal window
cargo run -p app -- --scenario my_first_mod:erste_fahrt
cargo run -p app -- --scenario my_first_mod:erste_fahrt --loco example:br101_afb

The scenario names its line, so --line is not needed; given, --line wins over the scenario’s line. With a release binary the flags are the same: train-sim --scenario my_first_mod:erste_fahrt. All flags are in Building and running.

Watch the terminal: loading warnings are logged with a mod: prefix, and a name that does not resolve says so (scenario my_first_mod:erste_fahrt not found). See Troubleshooting when something does not appear.

The Modding overview maps every file kind to its reference page.