Skip to content
Connected RailsConnected Rails

Building and running

The binary assets of the mods — the character models in mods/people/assets/, the tree sheets and buffers in mods/trees/assets/, sounds — are stored with Git LFS (see .gitattributes). Install it once per machine before cloning (git lfs install; Arch: pacman -S git-lfs, or mise use -g git-lfs), and a clone fetches them by itself; a clone made without it holds pointer files instead, which git lfs pull replaces. The mod loader recognises a pointer where a model should be and says so on the mod manager page rather than failing the glTF parse.

Terminal window
cargo nextest run --workspace # all acceptance tests (headless, no GPU; cargo-nextest)
cargo test --workspace --doc # the doc tests, which nextest does not run
cargo run -p app # start the simulator (main menu: drive, mods, settings, quit)
cargo run -p app -- --frames 120 # rendering smoke test (CI)
cargo run -p app -- --screenshot screenshots/hud.png # capture an image and exit (always silent)
cargo run -p app -- --mute # run without opening an audio device
cargo run -p app -- --screenshot shot.png --overlays # …with the F5 and F6 overlays open
cargo run -p app -- --screenshot shot.png --console # …with the F8 console open
cargo run -p app -- --screenshot shot.png --hud reduced # …with the display on one of its three steps
cargo run -p app -- --menu --screenshot screenshots/menu.png # …of the menu instead
cargo run -p app -- --screenshot night.png --time 22:30 --date 2026-01-15 # …at another hour of another day
cargo run -p app -- --line example:beispielstrecke --loco example:br101_afb # from a mod
cargo run -p app -- --line example:beispielstrecke --scenario example:probefahrt
cargo run -p app -- --line example:beispielstrecke --day example:beispieltag --service 0 # a service out of a 24 h timetable
cargo run -p app -- --loco example:br101_afb --camera outside # look at the vehicle model
cargo run -p app -- --loco example:br101_afb --camera walk # start on foot (F4) instead of on the seat
cargo run -p app -- --loco example:br101_afb --camera fly # free dev camera — also togglable with `fly` in the F8 console
cargo run -p app -- --camera walk --character people:f01_lena # a body of your choice (seen from F2/F3)
TRAINSIM_SERVER_PASSWORD=geheim cargo run -p app -- --dedicated 27015 # dedicated server, no window
cargo run -p app -- --connect 127.0.0.1:27015 # join one: server page, then lobby

--screenshot is available in the editors as well; --frames N sets after how many frames the capture happens (60 frames ≈ 1 s of simulation time).

Any run flag skips the main menu; see Main menu and settings.

For a faster edit-compile-run loop, add --features dev to any of the four binaries (app, route-editor, vehicle-editor, signal-editor). It links Bevy as a shared library, which cuts the relink after a code change. The first build with the flag recompiles Bevy, and the resulting binary needs the Bevy DLL next to it — so use it for development only, never for a release. Builds also use the toolchain’s own rust-lld linker on Windows and mold on Linux (pacman -S mold, apt-get install mold, or the release tarball’s bin/ on PATH — see .cargo/config.toml), dependencies compile at opt-level = 3 while the workspace itself stays at 1, and --release adds thin LTO with a single codegen unit. Release binaries for x86_64 additionally build with -C target-cpu=x86-64-v3 (see .forgejo/workflows/release.yml) — needs an Intel/AMD CPU from ~2013+ (Haswell/Zen+); for a local release-equivalent build set RUSTFLAGS="-C target-cpu=x86-64-v3 -C link-arg=-fuse-ld=mold" yourself.

The simulator’s sound is placed by Steam Audio (bevy_audionimbus). Its build script downloads Steam Audio’s native library (an archive of about 180 MB, unpacked to some 600 MB) into its build directory — once per profile and target, so a debug, a release and a Windows build each fetch it — and binds its header with bindgen, so clang and libclang have to be installed (pacman -S clang, apt-get install clang libclang-dev) and the first build needs network access. Only x86_64 Linux and Windows are supported by that download. The library is linked dynamically: cargo run and cargo nextest find it by themselves, a release ships it next to the executable, and a binary started by hand out of target/ needs its directory on the library path — on Linux export LD_LIBRARY_PATH=$(dirname "$(find target/debug/build -path '*audionimbus-sys*/out/lib/libphonon.so' -print -quit)"), on Windows the same directory (phonon.dll) on PATH.

A Windows build does not need Windows: with clang, lld and llvm installed and the x86_64-pc-windows-msvc target added, cargo install --locked cargo-xwin and then cargo xwin build --target x86_64-pc-windows-msvc fetch Microsoft’s CRT and SDK (accepting their licence) and build the .exe files, icons included; with wine installed, eval "$(cargo xwin env --target x86_64-pc-windows-msvc)" followed by cargo nextest run --workspace --target x86_64-pc-windows-msvc runs the tests and cargo test --workspace --target x86_64-pc-windows-msvc --doc the doc tests in the same shell (what CI does; cargo xwin test works too, but it builds into differently fingerprinted artifacts, so mixing the two rebuilds everything). Install cargo-xwin from source rather than taking its release binary — that one is linked against musl and takes twenty minutes instead of one to unpack the SDK.

On Linux the four programs run natively on Wayland: winit picks Wayland whenever WAYLAND_DISPLAY or WAYLAND_SOCKET is set and falls back to X11 (or XWayland) otherwise.

Several worktrees on one machine can share their intermediate artifacts, so dependencies compile once per machine: a .cargo/config.toml in a directory above the worktrees (nothing lands in the repo) sets build.build-dir to one shared directory and [unstable] checksum-freshness = true, and a rust-toolchain.toml next to it pins nightly. The checksum fingerprints are what makes sharing safe — with mtimes, stable Cargo takes a worktree whose files are older than another worktree’s build for fresh and runs the wrong binary. Measured: a fresh worktree builds and runs app --features dev in 54 s instead of 366 s, recompiling only the workspace crates; builds in different worktrees take turns on the build-dir lock. sccache as build.rustc-wrapper also works across worktrees but gains little here (366 s → 351 s): serde_core and thiserror include! build-script output from OUT_DIR, so their crate hash carries the build-dir path and every crate above them — most of Bevy — misses in another directory.