Modules, scenarios and operating days
Modules and compositions
Section titled “Modules and compositions”A big line is built from modules, after the Zusi 3 model: a module is an ordinary
LineSource whose open ends carry named boundaries — Buffer nodes at which another
module may attach:
boundaries: [(name: "nach_ost", node: 1)],A module also states where it sits and how far it reaches:
anchor: Some((lat: 52.0, lon: 10.0146, height: 100.0)),envelope: [ (lat: 51.982034, lon: 9.985418), (lat: 51.982034, lon: 10.043782), (lat: 52.017966, lon: 10.043782), (lat: 52.017966, lon: 9.985418),],A module may also say what it portrays:
year: Some(1985),fictional: false,year is the state of the line a driver is meant to find, fictional marks a module that is
invented rather than a rebuild of a real place. Nothing in the simulation reads either yet —
they are what a module says about itself. Both are optional; a module that does not care
simply leaves them out.
The anchor is the module’s place — the point the editor opens on, and the point the
envelope is built around when the module is created. The envelope is that boundary
itself, the Hüllkurve Zusi builds modules around: a closed polygon, in file order, that
says what this module covers. Everything the module owns has to lie inside it, so the ground between two modules belongs to exactly one of them and
neither shapes the other’s. A rectangle is rarely the right shape — a line follows a
valley, and the boundary is agreed where it makes operational sense — so the polygon takes
as many corners as it needs, and it has to be simple: an envelope that crosses itself has
no inside, and the rule check says so (check-envelope-crossed).
The track, its turnouts and its lineside equipment are bounded as well, but with ten metres of tolerance: a boundary is exactly where a rail meets its neighbour’s, so the last metre of track sits on the polygon, where a strict test would refuse the one click a module transition is made of.
Dragging a corner inwards afterwards does not delete anything — the editor’s rule check
reports what the envelope no longer covers (check-outside-envelope), so the choice between
moving the boundary and deleting the trees stays yours.
An empty envelope bounds nothing, which is what every line written before envelopes
reads as, and what a composition of several modules produces. A module that has none gets
one from Module → Envelope → Reset.
A composition (compositions/*.ron) chains modules into one line:
( name: "Gesamtstrecke", modules: ["example:modul_west", "example:modul_ost"],)The connection comes from the georeference. Every module is placed in real
coordinates; two boundaries that lie on the same spot (within a metre) snap together by
themselves. Building a module transition therefore means nothing more than starting your
module’s edge at the agreed coordinates of the neighbour’s boundary — no wiring, no
extra file. connections: [(("<mod>:<module>", "<boundary>"), (…, …))] states a pairing
explicitly for the rare case where positions alone cannot decide.
The route editor’s Module panel places boundaries (select a track, add one at an open end), holds the anchor and the envelope, and loads the neighbour module as a grey ghost: its track is drawn read-only and its boundary circles are snap targets, so drawing clicks near them land exactly on the agreed coordinates.
UTM zones cannot shift a transition. Module anchors are geodetic (lat/lon) and
compile into ECEF, one global frame for the whole world — there are no per-zone planar
coordinates anywhere in the line data. Modules whose source data came through different
UTM zones (say, a composition spanning the 12° E boundary between zones 32 and 33)
therefore meet to the millimetre; the metre-sized zone-seam displacement known from
Zusi’s module system has no place to come from. A test pins this
(compose::modules_from_different_utm_zones_meet_exactly). UTM appears only where
elevation data is read (DGM tiles are delivered in a zone grid) — there the app takes
one source per zone: repeat --dgm <dir> --epsg <code> for each side of the boundary.
The composition is addressed like a line: --line example:gesamtstrecke. On loading,
every index space of a module (nodes, edges, devices, sections, signals, routes —
including the indices inside magnet, signal and block marker payloads) is shifted by the
module’s offset.
Signalling across the boundary is composition data, because a module’s next is a
module-local index:
signal_links: [(("example:modul_west", 0), ("example:modul_ost", 0))],sets the first signal’s next to the second — the last signal of one module then
announces the first signal of the next, in the same update like any other chain.
Timetables and scenarios address positions module-locally. A module field on the
timetable (or per stop), and on the scenario (or per event), makes every index in it
mean “of that module”; the runtime resolves them against the composition:
// timetable/*.ron — edge 0 *of Modul Ost*, wherever the composition puts it.( number: "RB 42", module: Some("example:modul_ost"), stops: [(name: "Ostheim", edge: EdgeId(0), s: 1700.0, arrival: 240.0, departure: 300.0)],)A stop or event with its own module: overrides the file default — that is how one
timetable strings stops across many modules. Without any module, indices are those of
the (composed) line itself, as before.
Several versions of one module — other epochs, other equipment, a rebuilt station —
are simply several module files (bahnhof_1975.ron, bahnhof_2020.ron); a composition
picks one by name, so the same neighbouring modules combine with either. A scenario can
name its line or composition itself (line: Some("example:gesamtstrecke")), which is how
a timetable chains modules; --line on the command line wins.
mods/example/lines/modul_west.ron, modul_ost.ron and
compositions/gesamtstrecke.ron are a working pair to copy from;
scenarios/modulfahrt.ron plus timetable/modulfahrt.ron run across the seam with
module-local references (cargo run -p app -- --scenario example:modulfahrt).
scenarios/*.ron is a Scenario — triggers and actions, see Scenarios.
Start one with --scenario example:probefahrt.
A scenario says what stands on the line. Its consists: list is the same one an
operating day has (see Operating days below), and its order is the order the train
indices run in: player_train picks which of them the player drives, and every event’s
train: addresses the same list. mods/example/scenarios/rangierfahrt.ron is a complete
one — a light engine standing in the siding and three machines to collect from the platform
— and shows both spawn point shapes:
consists: [ (number: "Lokzug 77401", vehicles: [(vehicle: "example:br101_afb", count: 3)], at: At(edge: EdgeId(0), s: 3800.0, dir: 1)), (number: "Lz 77400", vehicles: [(vehicle: "example:br101_afb", count: 1)], at: Yard("Abstellgleis 1")),],player_train: 1,Leave consists: out and the old shape still holds: the run builds the player’s train from
the vehicle picked in the menu, and the scenario brings no traffic of its own.
A scenario gets stop scoring by referencing a timetable: timetable: Some("<mod>:<name>")
points at a timetable/*.ron of the mod (train number, category, stops with position,
arrival and departure — mods/example/timetable/probefahrt.ron is a complete one). With it
the scoring counts position error and delay per stop on top of the scenario’s own points;
without one, only the scenario points count. kind decides what the times mean:
Scenario (the default) counts seconds from the start of the run and the timetable runs
once; Daily reads them as seconds since midnight and wraps around every 24 h — the
looping all-day timetable, which an AI train follows indefinitely.
Where midnight lies — and where the sun stands — comes from the scenario’s start clock:
start: (year: 2026, month: 8, day: 15, hour: 6, minute: 45, utc_offset: 2.0),Date and local time at the start of the run; utc_offset is the local clock’s offset
from UT in hours (Germany: 1 in winter, 2 in summer). It drives the sun and moon over
the georeferenced line and anchors Daily timetables; Scenario timetables and event
triggers stay relative to the start of the run. Without the field, a run begins at
midsummer noon.
Operating days (days/*.ron)
Section titled “Operating days (days/*.ron)”A scenario is one prepared run. An operating day is the other way a line is used: the
whole timetable of a day, looping every 24 hours, out of which the player picks one
service and drives it. mods/example/days/beispieltag.ron is a complete one; start it
without the menu with
cargo run -p app -- --line example:beispielstrecke --day example:beispieltag --service 0The file names the line it belongs to, the date the day plays on by default, and its services:
( name: "Beispieltag", line: Some("example:beispielstrecke"), date: (year: 2026, month: 8, day: 15), utc_offset: 2.0, weather: Dynamic, // or Fixed(Rain) services: [ ( number: "RB 30001", category: "RB", description: "Frühzug nach Beispielstadt", vehicle: Some("example:br101_afb"), // None = what the player picked cars: 3, origin: At(edge: EdgeId(0), s: 200.0, dir: 1), // or Yard("Portal Ost") stable_at: Some("Abstellgleis 1"), // where its stock goes afterwards stable_way: DrawUp, // or SetBack, the default playable: true, // false = AI only, for the traffic stops: [ /* ScheduledStop, times in seconds since local midnight */ ], ), ], script: None, // optional scenario script running alongside the day (Scenario scripting))A service’s stops are the same ScheduledStops a timetable/*.ron holds, and they are
read as a Daily timetable: seconds since local midnight, wrapping at 24 h. A service that
leaves at 23:50 and arrives at 00:12 needs nothing said about days — write 85 800 and 720.
origin is a spawn point, and it has two shapes:
origin: At(edge: EdgeId(0), s: 200.0, dir: 1), // a place on the lineorigin: Yard("Portal Ost"), // a road of it, by nameAt is where the head of the train stands and which way it faces (dir: 1 = towards
rising s); that is also what decides which way round the consist is put on the track.
Yard names one of the line’s yards: — a stabling road, or a portal. A service
whose stock comes out of a portal is a working that started on a piece of railway nobody
has built: it appears there, runs in, and is on the line like any other train.
The other services run too. As each one’s hour comes the simulator puts its train on the line and the AI drives it; when it is over the unit is put away and the next service that needs the same stock takes it rather than a new one. Over a looping day that keeps the train count at the size of the busiest minute. Which services are out is a pure function of the clock, so a dedicated server and every client put the same trains on the line without sending anything about it; only the driving is the server’s.
stable_at names where a working leaves its stock — one of the line’s yards: (see
Shunting). A stabling road holds the unit in its siding, standing on the track with
its brakes applied where everyone can see it; a portal is the edge of the module and
swallows it altogether, which is how a working that carries on over unbuilt railway leaves
the scene. Leave the field out and the unit simply goes out of service where it terminated,
which is right for a plan whose workings are paired — the unit that arrives at ten past
forms the one that leaves at half past.
The unit is driven there: a service with a road is given a shunt move on top of its
timetable, worked once the last stop has been made, and stable_way says which way it runs
(SetBack, the default, or DrawUp for a road that lies ahead of where the working ends).
Its window stays open ten minutes instead of three to give it time. Whatever the driver
managed, the unit is placed on the road when that window closes — that placement is the
backstop, and it is what keeps the dispatching a function of the clock, because a driven
move is not one and a client and the server would otherwise end up with different trains on
the line. Getting stable_way wrong therefore costs the look of the move, not the plan.
Stock that is simply there. Both a day and a scenario may declare consists: — trains
that stand on the line from the first minute, whatever the plan does later:
consists: [ ( number: "Wagengruppe 4", vehicles: [(vehicle: "example:br101_afb", count: 1)], at: At(edge: EdgeId(1), s: 550.0, dir: -1), prepared: true, // false = a cold engine to wake up timetable: Some("example:probefahrt"), // None = it just stands there ),],A consist names its vehicles one by one, head first — “a locomotive and n coaches” is only
the commonest case of it, and a rake of vans behind a shunter is a train too. at: is the
same spawn point as a service’s origin. With a timetable the AI drives it to that
timetable; without one it stands where it was put with its brakes applied, which is what
stock in a siding does all day.
A consist may also carry a shunt job of its own, with or without a timetable:
shunt: Some(( name: "62701 ins Bw", moves: [DrawUp(Yard("Portal Ost")), Stand],)),The moves are worked in order: DrawUp(target) and SetBack(target) drive one end of the
train onto a place on the line or a road by name, Couple couples to whatever the train
stands up against, Uncouple(n) parts it behind vehicle n, and Stand finishes at a
stand. With no timetable beside it the consist is a pilot and nothing else — a movement
that exists to move stock about. With one, the job is worked after the last stop has been
made, which is what a service that puts its own unit away comes to.
Shunting: signals and routes
Section titled “Shunting: signals and routes”German practice draws a hard line between a Zugfahrt and a Rangierfahrt, and almost everything about how a movement is signalled hangs off which side of it the movement is on (Ril 408 / 301):
| Zugfahrt | Rangierfahrt | |
|---|---|---|
| Signalled by | the main signals (Hp 1 / Hp 2) | Sh 1 and nothing else |
| Track ahead | proved clear before the signal clears | may be occupied |
| Speed | the line speed | 25 km/h, on sight |
| 2000 Hz magnet | live at a signal at stop | switched off by Sh 1 |
A movement changes kind by passing a signal. Under Sh 1 it becomes a shunting movement; under a main proceed aspect it becomes a train. That is exactly how a shunt draws up to the starting signal, is given a train route, and leaves as a train — nothing switches a mode, the signal does it.
A Sperrsignal is a signal of kind Shunting. It shows Sh 0 / Sh 1 and no main aspect
at all, and Sh 0 is “Halt! Fahrverbot” — it stops a train movement as dead as a shunting
one. mods/example/signals/sperrsignal.ron is the signal type; the aspect rules read
shunting: Some(true), which the interlocking sets while a shunting route is locked there:
(kind: Signal, edge: 2, s: 20.0, facing: Backward, payload: "(signal:Some(2))"),…(kind: Shunting, system: Ks, device: 6, requires_route: true, signal_type: Some("example:sperrsignal")),A Rangierstraße is a route with kind: Shunt. It locks the points and clears Sh 1 at
its entry signal, it leaves the main signal at stop, and — unlike a Zugstraße — it may be
set into an occupied track, which is what collecting a rake that is standing there needs.
It has no overlap: a shunting movement is driven on sight, so there is nothing to run past.
routes: [ (entry: 2, exit: 0, kind: Shunt, switches: [(1, Diverging)], sections: [0]),],The route belongs to the movement that ran over it: passing the signal under Sh 1 makes it that movement’s, and it is given back when that train has cleared it. A second shunt running past the same signal takes nothing away from the first, and a route over a road that was occupied to begin with is still released — the track clear detection records which trains are on a section, not merely that something is. A route set for a movement that never came is given back after five minutes, the Zeitverschluss of a Rangierfahrstraße. The route editor writes the kind in the route form (Kind: Train route / Shunting route).
The signalman answers by himself. A movement standing in front of a Sperrsignal is given the first free shunting route out of it, which is how a unit gets out of a siding without anybody scripting it. Train routes are not set this way: which route a train takes is a decision, not a reflex.
The player may change trains. In a timetable run the driver can walk out of the door —
the AI takes the working on from the stop that is actually next — walk along the platform
into another train, and take that one over at its desk (Tab, or whatever it is rebound
to). What they take is what they are scored against from then on. A train with nothing in it
that pulls, one that is out of service, or one somebody else is driving is refused with a
reason on screen. A scenario is not part of this: its events, its scoring and its ending
all name one train, so that is the one it is driven in.
The player sets the date and the weather. Picking a service in the run list opens one
more step: the day it runs on — the plan’s date to begin with, dialled with ← / → — and
the weather, either dynamic (the day makes its own out of the date and the plan’s name:
fronts move in, the rain stops and the sun comes back, all as a function of the clock, so
a whole 24-hour day has weather in it rather than one weather) or set by hand, where the
player names one of the thirteen presets and it is placed at the start and held. A mod
picks the default with weather: Dynamic or weather: Fixed(Snow); a scenario is not
asked, because it brings its own sky.
A day whose line names a line other than the one picked is not offered — its stops are
indices into that line’s track graph. Leave line out and it is offered everywhere, which
is what the built-in Musterbahn day does.
Seasons
Section titled “Seasons”The same date paints the season, and no mod has to do anything for it: the generated
ground textures and the built-in placeholder trees turn through October and go under snow
from November to March. On top of that a mod may ship seasonal variants of its objects
(autumn_model / winter_model, see Track objects) — each with its own textures inside
the glTF, each optional. A tree mod that ships only a summer birch is complete; one that
adds a winter birch gets it spawned while the snow lies. The season is fixed at load, so a
run that drives from October into November keeps the world it started in, and the route
editor always builds in summer — which season a run shows is the scenario’s date, not the
module’s.
Scenario scripts
Section titled “Scenario scripts”A Scenario and an OperatingDay may name a script, and that script is the director
of the run: it reads the whole world through the cr API, puts trains on the line, gives AI
drivers timetables and shunt jobs, sets the player tasks, scores and ends the run — the
whole reference is Scenario scripting. Shunting tasks have no format of
their own for exactly that reason: scenarios/rangierfahrt.ron plus
scripts/rangierfahrt.lua is one written against the API.
An operating day is offered in the run picker under the line it names and under every composition that has that line as one of its modules: started there, its edge indices move by the module’s offset without the file saying so. A stop or an origin on an edge the line does not have is a warning when the run is built.
Line and scenario hooks on_load(ctx) / on_frame(ctx)
Section titled “Line and scenario hooks on_load(ctx) / on_frame(ctx)”A LineSource (and a composition) may name a script. on_load runs once when the run
starts, on_frame once per frame. A scenario’s script written in this shape before the
director existed still runs — the director builds the same ctx and reads the same answer,
at the 0.1 s marks of the simulation clock rather than every frame. The rule stays the same as everywhere else: the script
decides when, the RON says what. An event with trigger: Never waits for the script:
(name: "stalled", trigger: Never, actions: [Announcement("Report your position."), Score(points: -5, reason: "Unscheduled stop")]),function M.on_frame(ctx) if ctx.v_kmh < 1.0 and ctx.time - standing_since >= 60.0 and ctx.fired["stalled"] == nil then return { fire = { "stalled" } } -- the event's actions run endendctx: dt, time, trains, player, v_kmh, edge, s, finished, bonus, and
fired — a table of event name → firing time, so a hook does not have to remember which
events have gone off.
The answer may contain:
| field | effect |
|---|---|
fire = { "name", … } |
fires those scenario events; unknown names are logged and skipped |
message = "…", announcement = true |
a message to the player |
switch = { node = 3, position = "straight" | "diverging" } |
throws a switch |
fire is the interesting one — through it a script reaches every action the scenario format
has (switch, route, weather, score, finish) without any of them being written in Lua. The
other two are there for a line that carries behaviour without a scenario.
mods/example/scenarios/probefahrt.ron plus scripts/probefahrt.lua is the worked example.