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.
Where mods live
Section titled “Where mods live”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.
Create the mod folder
Section titled “Create the mod folder”-
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 usesmy_first_mod. -
Create the folder under that same name:
mods/my_first_mod/. The loader goes by the id in the manifest, but a.crailspackage always installs intomods/<id>/, and asset paths start with the folder name — so a folder named otherwise is a loading warning (see Troubleshooting). -
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:
idandnameare the only mandatory fields.nameis what the mod manager shows.versionis 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.authoranddescriptionare free text.dependslists the mods yours builds on. The scenario below runs on a line from theexamplemod, so it namesexample. A missing dependency is shown in the mod manager; it does not stop anything from loading.enabledis what the mod manager switches. It defaults totrue;falsekeeps 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.
How content is addressed
Section titled “How content is addressed”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.
Add a scenario
Section titled “Add a scenario”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.
-
Create
mods/my_first_mod/scenarios/. -
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.
Switch it on in the main menu
Section titled “Switch it on in the main menu”- Start the simulator without arguments —
cargo run -p appin a checkout, or thetrain-simbinary of a release. - Choose Mods on the title screen. Every installed mod is listed with its name, id and
version;
my_first_mod 0.1.0should be among them. A mod whose dependencies are missing or switched off carries the line requires: … (missing or switched off). - Select it with
↑/↓and pressEnterto switch it on or off. This writesenabledback into yourmod.ron— only that field, your comments stay — and the change applies to the next run. - 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.
- 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.
Start it from the command line
Section titled “Start it from the command line”Any run flag skips the menu, which is quicker while you iterate:
cargo run -p app -- --scenario my_first_mod:erste_fahrtcargo run -p app -- --scenario my_first_mod:erste_fahrt --loco example:br101_afbThe 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.
Where to go next
Section titled “Where to go next”- Adding a vehicle — your own locomotive or coach, with the vehicle editor.
- Building a line — track, stations and scenery in the route editor.
- Adding a signal — signal types, models and kits.
- Writing a scenario — events, scripts, timetables and operating days.
- Placing scenery — objects, buildings, vegetation.
- Packaging and publishing — testing, versioning and the
.crailspackage. - Troubleshooting — when a file does not load.
The Modding overview maps every file kind to its reference page.