Skip to content
Connected RailsConnected Rails

Scenarios and timetable runs

A scenario is a RON file of events — triggers plus actions:

(
name: "Regionalbahn nach Musterstadt",
start: (year: 2026, month: 8, day: 15, hour: 6, minute: 45, utc_offset: 2.0),
player_train: 0,
events: [
(name: "abfahrt", trigger: Time(5.0),
actions: [Announcement("RE 4711, Abfahrt frei.")]),
(name: "regen", trigger: After(event: "abfahrt", delay: 60.0),
actions: [SetWeather(Rain), Message("Regen setzt ein.")]),
(name: "ziel", trigger: TrainStopped(train: 0, edge: EdgeId(2), s: 2600.0, radius: 50.0),
actions: [Finish(success: true, reason: "Musterstadt erreicht")]),
],
)

Scored are timetable adherence, stopping accuracy, emergency brake applications, speed limit violations and traction energy; the HUD shows messages and the score. A scenario gets its timetable by reference (timetable: Some("<mod>:<name>"), a timetable/*.ron in the mod) — without one, only the scenario’s own points count. A timetable is either kind: Scenario (times from the start of the run, runs once) or kind: Daily (times as seconds since midnight, wrapping around every 24 h). start: sets date and local time of the run (default: midsummer noon) — it anchors Daily timetables, puts the sun and moon where they belong for the georeferenced line, and paints the season: meadows turn through October, ground and trees go under snow from November to March. The sky those two stand in is a scattering model, not a gradient: Rayleigh and Mie through the look-up tables of Hillaire’s technique, so noon is blue, sunset is red and a valley twenty kilometres off lies in haze, all of it out of the sun’s elevation alone. Behind them stand the real stars — the naked-eye HYG catalogue, held in equatorial coordinates and turned by the latitude and the sidereal time, so the pole star sits at the latitude’s altitude and everything rises four minutes earlier each night. The moon is a disk half a degree wide, lit from where the sun really is, which is where its phase comes from. --time 22:30 and --date 2026-01-15 move the clock of a run for a screenshot. A mod’s track object may bring its own autumn_model/winter_model glTF — optional, and whatever it leaves out keeps the year-round model. SetWeather(Clear | Cloudy | Overcast | Fog | Drizzle | Rain | Storm | Thunderstorm | Sleet | Snow | Blizzard | Hail | Frost) moves the weather there over five minutes — a front, not a switch. Every preset is a set of physical numbers (cover, cloud base, precipitation rate, wind, sight, temperature, thunder), and everything downstream reads those rather than the name: volumetric clouds and their shadows, the haze in the atmosphere, the rain and snow around the camera, and the water and snow that gather on the ground and decide what the wheels find on the rail. A scenario can also start in a weather (weather: Rain beside its start), and --weather snow places one for a screenshot; in a normal run the same flag lets the front move in over five minutes — a first drizzle, single drops on the glass, the rail greasy before wet. --wipers 2 starts with them running. SetRail(Dry | Wet | Slippery) still sets the rail by hand — leaves and sanded rail have no weather to come from — and holds until the weather next changes. From the driver’s seat the rain is on the glass too: a vehicle names its panes in cab: (windscreen: [...]), and the wiper clears the strip its blade has just crossed.

Besides the scenarios a line can be driven out of its operating day: the whole timetable of a day, looping every 24 hours, out of which the player takes one service.

(
name: "Beispieltag",
line: Some("example:beispielstrecke"),
date: (year: 2026, month: 8, day: 15),
weather: Dynamic, // or Fixed(Rain)
services: [
(
number: "RB 30001", category: "RB",
vehicle: Some("example:br101_afb"), 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 after
stops: [ /* times in seconds since local midnight */ ],
),
],
)

The times are wall clock and wrap at midnight — a service leaving at 23:50 and arriving at 00:12 needs nothing said about days. The run starts two minutes before the service departs, and the whole plan runs around it: as each other service’s hour comes the simulator puts its train on the line and the AI drives it, and when it is over the unit is put away — onto the stabling road the service names (stable_at, one of the line’s yards:) where it stands braked in its siding, out through a portal where that is what the road is, or simply out of service at the terminus where the plan names none. The AI drives it there: a working with a road gets a shunt move on top of its timetable, and 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 — the driven move is for the look of it, the placement is the guarantee, and it is what keeps the whole thing a function of the clock so that a dedicated server and every client put the same trains on the line without sending anything about it. The next service that needs the same stock takes that unit rather than a new one.

Where trains come from. A spawn point is either a place on the line (At(edge: …, s: …, dir: …)) or one of its roads by name (Yard("Portal Ost")). A portal is the edge of the modelled railway: a service whose stock comes out of one started on a piece of line nobody has built, and one that ends at a portal carries on over it and is gone. Both a timetable and a scenario may also declare consists: — trains that simply stand there from the first minute, each naming its vehicles head first, driven to a timetable where they have one and left braked where they have not. Each stretch of vehicles may name its livery and its load — (vehicle: "example:fals", count: 12, variant: Some(1), load: Some(0)), indices into the vehicle’s variants and loads. They are part of the consist, so on a multiplayer server they are what every client builds: a player’s own menu has no say over them, and neither has --variant. For a scenario that list is also what its events address: its order is the order the train indices run in, and player_train picks which of them is the player’s. mods/example/scenarios/rangierfahrt.ron is a shunting scenario built out of exactly that — a light engine in the siding, three machines to collect at km 3.8, and Insert to couple — with its story told by a script.

Scenario scripts. Events and triggers cover a run that is a list of moments. Anything more — a shunting task in five steps, a dispatcher who reacts to what the driver does, a pilot that comes out of the portal once the rake is coupled, a train that breaks down at a time drawn by dice — is a Lua scenario script the scenario or the day names (script: Some("<mod>:<name>")). It reads the whole world, puts trains on the line, gives AI drivers timetables and shunt jobs, sets tasks the HUD lists under the journey, scores and ends the run; Scenario scripting is the reference. In multiplayer it runs on the server, and the clients apply what it decided.

Zugfahrt and Rangierfahrt are two different movements, and the simulator draws the line where German practice draws it (Ril 408 / 301). A train movement carries a number, is signalled by the main signals, is only let onto track that has been proved clear, and runs at the line speed. A shunting movement carries none, is let past by Sh 1 and by nothing else — Hp 1 has said nothing to it — may be let into an occupied track, which is the whole point of shunting, and runs on sight at 25 km/h; the 2000 Hz magnet of a signal showing Sh 1 is switched off, because otherwise every shunting movement past a signal at stop would be tripped. A Rangierstraße locks the points and clears Sh 1 while leaving the main signal at stop, and it belongs to the movement that ran over it: it is given back when that train has cleared it, so a second shunt past the same signal takes nothing away from the first, and a route over a road that was occupied to begin with is released all the same.

A movement changes kind by passing a signal. Under Sh 1 it becomes a shunting movement, under a main proceed aspect a train — so a shunt draws up to the starting signal, is given a train route, and leaves as a train, with nothing switching a mode anywhere. A movement standing in front of a Sperrsignal is given the first free shunting route out of it by itself, which is how a unit gets out of a siding without a script.

You can get out. A driver is responsible for one train at a time, or for none — and that, not where they happen to be standing, is what decides who is on the levers: the AI drives every train it has a driver for except that one. Walk out of the door and the working is handed over — the AI takes it on from the stop that is actually next, and a train with no working at all is secured where it stands rather than driven away. Walk along the platform, through the door of another train, and sit down at its desk: Tab takes it over, and Tab again gives it back. The refusals are said out loud rather than swallowed — not from the platform, not a train that is out of service, not a rake with nothing in it that pulls, not one somebody else is driving, and in a scenario not any train but the scenario’s own, because its events and its ending name that one. Whatever working is taken is the one that is scored from then on. Over the network it is a wish the server grants or refuses; nobody takes a train from under another driver.

Two things are the player’s, and they are the reason picking a service opens one more page:

  • The date. The plan’s own to begin with, dialled a day at a time. It decides the season the ground and the trees wear and where the sun stands at the hour the service leaves — the same 06:15 out of Beispielbach is a summer morning in August and a night run in January.
  • The weather. Either dynamic, where the day makes its own out of the date and the plan’s name — two octaves of noise walk a ladder of presets, so fronts move in, the rain stops and the sky clears again over the hours, and a 24-hour timetable has weather in it rather than one weather — or set by hand, where one of the thirteen presets is named, placed at the start with its wet or snowed-on ground, and held. The generated day is a pure function of (seed, clock), seeded out of the content, so the same service on the same date brings the same sky on every machine.

Your working ends, the next one is offered. When the player’s service has made its last stop, the plan says what they could drive next: the soonest playable service within three hours that leaves from the station they are standing at — failing that, the soonest anywhere. The offer stands under the journey; F10 books it, and when its train is put out at its origin the player is taken to its desk and the old unit goes back to the AI. A day’s script can offer a different one (cr.offer_working).

On a composition. A day — or a scenario — written for one line is offered under that line and under every composition that has it as one of its modules; started there, its indices move by the module’s offset. A stop or an origin on an edge the line does not have is a warning when the run is built, rather than a stop the AI drives past forever.

--day <mod>:<name> --service <n> takes a service without the menu, --date moves the date with it, and --weather still overrides the sky for a screenshot. Operating days documents the file format; mods/example/days/beispieltag.ron is a complete one, and the built-in Musterbahn ships an hourly day of its own so the picker has something to offer with no mods installed.