Building and running
Git LFS
Section titled “Git LFS”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.
Command line
Section titled “Command line”cargo nextest run --workspace # all acceptance tests (headless, no GPU; cargo-nextest)cargo test --workspace --doc # the doc tests, which nextest does not runcargo 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 devicecargo run -p app -- --screenshot shot.png --overlays # …with the F5 and F6 overlays opencargo run -p app -- --screenshot shot.png --console # …with the F8 console opencargo run -p app -- --screenshot shot.png --hud reduced # …with the display on one of its three stepscargo run -p app -- --menu --screenshot screenshots/menu.png # …of the menu insteadcargo 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 modcargo run -p app -- --line example:beispielstrecke --scenario example:probefahrtcargo run -p app -- --line example:beispielstrecke --day example:beispieltag --service 0 # a service out of a 24 h timetablecargo run -p app -- --loco example:br101_afb --camera outside # look at the vehicle modelcargo run -p app -- --loco example:br101_afb --camera walk # start on foot (F4) instead of on the seatcargo run -p app -- --loco example:br101_afb --camera fly # free dev camera — also togglable with `fly` in the F8 consolecargo 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 windowcargo 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.
Build profiles and linkers
Section titled “Build profiles and linkers”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.
Steam Audio
Section titled “Steam Audio”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.
Windows from Linux
Section titled “Windows from Linux”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.
Wayland
Section titled “Wayland”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.
Sharing build artifacts between worktrees
Section titled “Sharing build artifacts between worktrees”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.