Skip to content
Connected RailsConnected Rails

Vehicles

vehicles/*.ron is a VehicleSpec — plain data. See mods/example/vehicles/br101_afb.ron:

Field Meaning
name display name
length length over buffers [m]
mass_empty tare mass [kg]
rotating_mass_factor allowance for rotating masses (0.05 coach … 0.25 powered vehicle)
davis running resistance R = a + b·v + c·v² [N], v in m/s
brake control valve, friction pairing, default brake position, braked weight [t], forces, pressures, reservoir volumes, additional brakes
traction Curve / TapChanger / Converter / Diesel — or None; see below
coupler kind plus slack, stiffnesses, damping, breaking force — see below
adhesive_mass_fraction share of the mass on driven axles (loco 1.0, coach 0.0)
slip_protection None / SlipBrake / TractionCutback / CreepControl
gauge track gauge [m], standard gauge 1.435
v_max highest permitted running speed [km/h] — the running gear limit
axles number of axles; information only
axle_base_sum total axle base [m], sum over all bogies — basis of the curve resistance
cw_a air resistance cw·A [m²]; replaces the quadratic Davis term
curve_resistance_factor factor on the Röckl curve resistance, 1 = standard
max_payload maximum payload [kg]
tilt_angle_deg maximum tilt angle [°], 0 without tilting technology
passenger_doors vehicle has passenger doors that follow the door control
safety train protection fitted: None or De(pzb: Some(Pzb90V20), lzb: true, sifa: Some(TimeTime), train_type: O, gnt: false) — gnt: true is the tilting speed supervision, which only does anything on a vehicle whose tilt_angle_deg is above zero
afb AFB fitted: the built-in target speed controller drives the power controller toward the cab’s AFB dial and brakes like the prototype — dynamic brake first, the air brake blends in where that does not suffice; under LZB guidance the LZB’s v-soll caps the dial
doors door control the vehicle brings: None / Tb0 / Tav / UicWtb
hunting hunting −1 … 1, 0 = standard
script optional behaviour hook "<mod>:<name>"
graph optional block diagram of drive, brake and equipment — when present it is authoritative over the fields it bakes, see below
model glTF file, levels of detail, moving parts — see below

coupler.kind is what a shunter can do with the vehicle, as against how the coupler behaves once it is made. Screw is the European standard (screw coupling and side buffers), CenterBuffer the automatic head of a multiple unit, and Bar a bar inside a fixed unit. Only like couples to like, and a bar is undone in the works: a railcar cannot be put in front of a rake of freight wagons, and a unit cannot be split between two coaches that are barred together. Left out, a vehicle carries a screw coupling.

safety and doors are the equipment of the vehicle, so a train carries what its vehicles carry — the leading vehicle determines the door control. Anything left out means “not fitted”: a coach without safety has no train protection, a loco without doors gives the driver no door control. What the equipment achieves also depends on the line: the LZB needs a conductor cable, the PZB needs track magnets.

Start it with cargo run -p app -- --loco example:br101_afb, edit it with cargo run -p vehicle-editor -- mods/example/vehicles/br101_afb.ron.

Every vehicle brakes for itself — the brake pipe runs as a chain of nodes along the train, so the rear of a long freight train applies seconds after the front.

Field Meaning
valve control valve: KGp (single-release), KeGp, KeGpr (with R position), KeTm, KeL2a (second cylinder pressure stage by speed), KeL2d (by a full application)
valve_params overrides the type’s preset field by field: graduated_release, rapid_position, high_stage, high_stage_trigger, loco, response_drop, full_service_drop
kind friction pairing: Block (cast iron), Disc, CompositeK, CompositeLl, Magnetic, or Custom([(km/h, µ), …]) for your own measurements
position G / P / R; an R on a valve without an R position falls back to P
brake_weight, max_force, max_cylinder, cylinder_to_reservoir braked weight [t], force at full pressure and standstill [N], cylinder pressure [bar], volume ratio (exhaustibility) — the two forces are those of the loaded vehicle, see load_braking
load_braking load braking: None, Weighing (stepless weighing valve — throttles the cylinder pressure by mass_empty/max_payload, no figures of its own), or Changeover(empty_share: 0.4, changeover_mass_t: 40.0) for the empty/loaded lever with the anscribed braked weights
brake_weight_g, brake_weight_p, brake_weight_r the anscribed braked weight [t] of that position, where the vehicle carries one per position (G 40 / P 60 / R 71). Absent = brake_weight for all three. The R figure replaces the standard R force bonus; the G figure is a brake sheet datum only — G brakes with P’s force and differs in the transition time, which is simulated separately
apply_time_g, apply_time_p, release_time_g, release_time_p filling and release time of the brake cylinder [s], overriding the UIC figures (G 22/50 s, P and R 4 s). _p covers R as well: the changeover handle sets the timing between G and P, R differs in force
has_mg, mg_force magnetic track brake and its force [N]; it applies in position: R only — the anscribed “R + Mg” is that pair
has_direct, direct_max_cylinder direct (additional) brake of a traction unit
parking_force, spring_parking parking brake [N]; with spring_parking it is held off by air and applies by itself when the main reservoir runs empty
pilot_controlled pre-controlled cylinder: fed from the main reservoir through a relay valve, fills faster, cannot exhaust — and it is what the electrically transmitted (ep) brake acts on
supplement_brake air supplement brake: fills up whatever the dynamic brake falls short of
angleicher equalising device: makes up brake pipe leakage in lap position. Deliberately without a memory — leaving the lap position throws the set point away
aux_volume, pipe_volume, main_volume reservoir volumes [l]; main_volume 0 = no main reservoir
compressor_delivery, leakage compressor delivery and leakage [l/min of free air]

The detailed data is optional everywhere: without it the variant runs on the tractive effort hyperbola from max_force/max_power.

// The simplified model: tractive effort straight off the diagram.
traction: Some(Curve(
force: [(0.0, 200000.0), (50.0, 120000.0), (150.0, 40000.0)],
v_max: 160.0,
brake: [], // dynamic brake over speed, empty = none
ramp_time: 2.0,
)),
// Series-wound drive behind a tap changer: the characteristic follows from the
// machine equations, not from a table.
traction: Some(TapChanger(
steps: 28, max_force: 275000.0, max_power: 3620000.0, v_max: 150.0, step_time: 0.8,
motor: Some((
count: 4, resistance: 0.05, flux_constant: 0.0289,
saturation_current: 600.0, max_current: 1600.0, max_voltage: 1000.0,
field_steps: [1.0, 0.85, 0.7],
gear_ratio: 2.17, wheel_diameter: 1.25, efficiency: 0.95,
)),
dynamic_brake: None, // rheostatic brake, if the loco has one
)),
// Three-phase drive. Above `v_pullout` the effort falls with 1/v² instead of 1/v.
traction: Some(Converter(
max_force: 300000.0, max_power: 6400000.0, v_max: 220.0,
brake_force: 150000.0, brake_power: 2600000.0, ramp_time: 2.5,
v_pullout: 150.0, regenerative: true, brake_fade_kmh: 10.0,
)),
// Diesel-hydraulic: engine map plus converters that are engaged by filling them.
traction: Some(Diesel(
max_force: 235000.0, max_power: 1840000.0, v_max: 140.0,
ramp_time: 4.0, start_time: 8.0,
engine: Some((
idle_rpm: 600.0, rated_rpm: 1500.0, max_rpm: 1650.0,
torque_curve: [(600.0, 9000.0), (1000.0, 13500.0), (1500.0, 13115.0)],
// or Fill — rack instead of engine speed. droop is the sag under load.
governor: Speed(steps: 0, droop: 0.04),
inertia: 60.0, response_time: 1.0,
)),
transmission: Some((
circuits: [
(kind: Converter, ratio: 3.93, stall_ratio: 2.4, coupling_nu: 0.85,
absorption: 0.53, absorption_slope: 0.15,
shift_up_kmh: 72.0, shift_primary_kmh: 25.0),
(kind: Converter, ratio: 1.50, stall_ratio: 1.9, coupling_nu: 0.85,
absorption: 0.53, absorption_slope: 0.15,
shift_up_kmh: 0.0, shift_primary_kmh: 0.0),
],
fill_steps: 0, // 0 continuous, 1 fill/empty only, n partial filling stages
fill_time: 1.2, drain_time: 0.7, hysteresis_kmh: 10.0,
final_ratio: 1.0, wheel_diameter: 1.0, count: 1, efficiency: 0.95,
)),
hydrodynamic_brake: None,
dynamic_brake: None, // electric brake of a diesel-electric, see below
)),

absorption λ is the pump wheel’s torque coefficient at ν = 0: M_pump = λ(ν)·ω²·fill, with λ(ν) = absorption·(1 + absorption_slope·ν). Set λ so the circuit absorbs the engine’s rated torque at rated speed — λ = M_rated / ω_rated²; a slope of 0 nails a speed-governed engine to one speed parabola for the whole converter range.

shift_up_kmh and hysteresis_kmh are the change points of the original, and shift_primary_kmh is the primary influence: at the zero notch the change comes that many km/h earlier than at full power. The last circuit ignores its change-up point. fill_time and drain_time are separate because they are separate in the original — the outgoing circuit lets go before the incoming one has taken hold, and that overlap is the hole in the tractive effort at the change point. drain_time: 0.0 takes the filling time.

Everything after absorption in a circuit, plus drain_time and droop, may be left out; they default to 0, which is the behaviour of a transmission without any of them.

A diesel-electric locomotive (engine → generator → traction motors, Class 66/BR 232 style) has no hydraulic transmission; its rheostatic brake is dynamic_brake — the same record the tap changer drive uses, optional and absent by default, so existing files are untouched. A regenerative: true inside it is ignored: a diesel has no line to feed back into.

Drive, brake and equipment can also be declared as a block diagram: the vehicle is a circuit of components, and the physics follows from what is wired to what. The diagram is edited on the vehicle editor’s node canvas (chips at the top left of the centre view switch between 3D model and Block diagram; --graph on the command line starts on the diagram) and stored in the vehicle file as the optional graph field:

graph: Some((
blocks: [
(id: 0, kind: "diesel-engine", pos: (-320.0, 0.0),
params: { "max_power": Number(1840000.0), "governor": Choice("speed") }),
(id: 1, kind: "hydro-transmission", pos: (-80.0, 0.0)),
(id: 2, kind: "wheelset", pos: (160.0, 0.0),
params: { "axles": Number(4.0), "adhesive_mass_fraction": Number(1.0) }),
],
wires: [
(from: 0, from_port: "out", to: 1, to_port: "shaft"),
(from: 1, from_port: "out", to: 2, to_port: "shaft"),
],
))

A block is (id, kind, pos, params): id is a stable number the wires reference, kind a palette id (built-in, or <mod>:<preset> — see the presets below), pos the canvas position, params a map parameter id → value. Values are typed — Number(…), Bool(…), Choice("<kebab-case id>"), Text("…"), Curve([(x, y), …]), List([…]) or Circuits([…]), the last one the circuits of a hydraulic transmission in the same shape as transmission.circuits above. A missing parameter falls back to the block’s default.

Ports have domains, and only like connects to like — the editor colour- and shape-codes the pins: mechanical (rotating shaft), force (at the wheel), electrical, pneumatic, signal (control values 0 … 1), fuel, steam, water and heat. A drag between two pins wires them; a right click on the canvas adds a block, a right click on a node removes it.

When a vehicle file carries a graph, the graph is authoritative. Loading bakes it and overwrites traction, brake, safety, doors, passenger_doors, afb, slip_protection, axles, adhesive_mass_fraction, script, signal, supply, sand_rate, running_gear and — where the diagram draws bogies — axle_base_sum; every other field — mass, length, running resistance, coupler, sounds, model, … — stays hand-edited as before. A vehicle without a graph keeps working unchanged; the editor synthesises a diagram from the spec on open (blocks::from_spec) and writes it on save, so opening and saving an old file upgrades it. While you wire, the editor lists the bake findings (errors and warnings) below the palette — a click selects the offending block.

The baker recognises the drive chains of all five traction models:

Chain Bakes to
traction-curve Curve — tractive effort straight off the diagram
pantograph + main-switch + transformer + tap-changer (+ series-motor) (+ dynamic-brake) TapChanger
… + rheostat / chopper + series-parallel-switch TapChanger with starter — contactor drive
… + traction-converter + traction-motor or async-motor (+ dynamic-brake) Converter
diesel-engine + hydro-transmission (+ retarder) Diesel, diesel-hydraulic
diesel-engine + mechanical-gearbox Diesel with gearbox — diesel-mechanical
diesel-engine + hydrostatic-drive Diesel with hydrostatic
diesel-engine + generator + load-regulator (+ rectifier) + series-motor or async-motor Diesel with electric — diesel-electric
firebox + boiler + steam-cylinders (+ injector + tender) Steam

Which motor block sits behind the generator decides the type of the diesel-electric drive: series-motor is the classic DC machine, async-motor the modern inverter one. A cooling block wired to the heat pin of a motor, a rheostat or the dynamic brake gives that component a thermal model — without one it never gets hot.

One engine drives one path: a hydraulic transmission, a mechanical gearbox, a hydrostatic drive or a generator. Wiring two of them warns and the transmission wins. A shunter’s two-range gearbox is not a block of its own — it is the shunting_ratio of the transmission, and the cab’s range selector (CabControl::RoadGear) changes it at a stand.

The brake blocks map onto the BrakeSpec fields above: the control-valve carries valve type, default brake position, braked weight and load braking (the position is only the setting the changeover handle starts in — what actually brakes is BrakeState::position, set on the vehicle when the train is made up); the brake-rigging the friction pairing and its maximum force; a relay-valve is the pre-controlled cylinder (pilot_controlled; its supplement flag is the air supplement brake); the driver-brake-valve carries the equalising device; reservoirs, pipe and compressor their volumes and figures; direct-brake, parking-brake, mg-brake and wheel-slide-protection the additional brakes and the slip protection. The brake-pipe carries the medium: air or vacuum — a vacuum brake has no auxiliary reservoir and no relay valve, and its compressor is an exhauster.

The Logic group is the control wiring between the physical blocks: it computes, it does not move anything. bake compiles that part of the diagram into a SignalProgram — a flat list of operations in evaluation order — which runs once per simulation step before the drive, so what it commands takes hold in the same step the driver’s lever moved.

A value-in reads something out of the vehicle, the blocks in between compute, and a signal-out decides what the result takes hold of: power controller, brake demand, sanding, blower, or one of four free values the cab displays can read. A cruise control is three blocks — speed, set speed, pid — and a load-shedding relay is a rate-of-change and a value-switch. Blocks that feed each other in a circle are reported (bake-signal-cycle) and dropped rather than run.

The built-in palette:

Kind What it is Key parameters
Energy
battery on-board battery — the cab needs it voltage, capacity [Ah]
fuel-tank fuel supply of a diesel capacity [l]
pantograph collects power from the contact line — one block per supply system supply system (AC 15/25 kV, DC 3/1.5 kV, third rail), rise time
voltage-source stands in for the contact line where there is none voltage
diesel-engine diesel engine, optionally with the full engine map force/power/v max hyperbola, ramp and cranking time; engine map: idle/rated/overspeed rpm, torque curve, speed or fill governor with notches and droop, inertia, rack time
Drivetrain
hydro-transmission converters and couplings engaged by filling circuits, power control (filling / engine speed), fill steps, fill/drain time, hysteresis, final drive, shunting gear, wheel diameter, count, efficiency
mechanical-gearbox friction clutch and gears, no torque conversion (Köf, railbus) gear ratios, final drive, wheel diameter, efficiency, clutch torque and travel time, change time, change-up and change-down speed
hydrostatic-drive variable-displacement pump and hydraulic motor, stepless effort limit of the relief valve, efficiency, swash plate travel time
retarder hydrodynamic brake in the transmission absorption, ratio, wheel diameter, force, power, fill time, fade-out
generator main generator of a diesel-electric electrical power, efficiency, maximum voltage and current
traction-motor motor without data behind converter or generator —
series-motor series-wound motor behind the tap changer or the generator count, resistance, machine constant, saturation and maximum current, voltage, field weakening steps, gear ratio, wheel diameter, efficiency
async-motor three-phase induction motor (Kloss) count, pole pairs, rated and pull-out torque, pull-out slip, rated and maximum frequency, gear ratio, wheel diameter, efficiency
traction-curve the simplified model: effort straight off the diagram force and brake curves [km/h → N], v max, ramp time
Electric
main-switch main circuit breaker —
transformer main transformer —
rectifier generator alternating current into direct current efficiency
load-regulator holds the generator on the notch’s power travel time, blower share at idle
tap-changer tap changer feeding series-wound motors steps, step time, starting effort, power, v max
rheostat starting resistors, cut out step by step resistance steps [Ω], time per step
series-parallel-switch regroups the motors as the speed rises groupings (S→P, S→SP→P, S only, P only)
chopper continuous voltage instead of resistor steps response time
traction-converter three-phase traction converter starting effort, power, v max, ramp time, pull-out speed
dynamic-brake electric brake of the drive it hangs on force, power, fade-out speed, regenerative flag, ramp time
cooling heat store and blower of what is wired to its heat pin heat capacity, cooling, natural convection, derating and cut-out temperature, ambient
Steam
boiler water, steam and pressure water and steam space, working pressure, safety valves, heating surface, superheater
firebox grate, damper and blower grate area and capacity, burning rate, blower draught, shovelful
steam-cylinders regulator and cutoff into tractive effort count, bore, stroke, wheel diameter, longest cutoff, back pressure, efficiency, v max
injector feed water into the boiler against its pressure delivery [l/s]
tender water and coal carried along water [l], coal [kg]
Brake
compressor air supply delivery [l/min], type (compressor / exhauster)
main-reservoir main air reservoir volume [l]
driver-brake-valve the driver’s valve feeding the brake pipe equalising device (Angleicher)
brake-pipe this vehicle’s stretch of the pipe volume, leakage, medium (air / vacuum)
angle-cock parts the brake pipe end (front / rear)
air-hose couples the pipe to the neighbouring vehicle end (front / rear)
emergency-valve vents the pipe from the compartment or the cab —
limiting-valve caps the cylinder pressure whatever asked limit pressure [bar]
double-check-valve passes the higher of two pressures —
retainer-valve holds a residual pressure through the release position (off / slow / low / high)
ep-brake electropneumatic brake — applies by wire application and release rate, vents-the-pipe flag, steps
control-valve control valve reading the pipe valve type (K-GP … KE-L2d), position G/P/R, braked weight [t] (overall and per position), transition times per position, load braking (weighing / changeover)
aux-reservoir auxiliary reservoir volume [l]
relay-valve pre-controlled cylinder fed from the main reservoir supplement flag (air supplement brake)
brake-cylinder the cylinder itself maximum pressure, cylinder/reservoir volume ratio
brake-rigging puts the cylinder force onto the wheel friction pairing (block, disc, K, LL, Mg, custom curve), maximum force
direct-brake direct (additional) brake of a traction unit maximum cylinder pressure
parking-brake parking brake force, spring accumulator flag
mg-brake magnetic track brake force
wheel-slide-protection slip protection mode: slip brake / traction cutback / creep control
sander sanding gear sand rate [kg/min]
Running gear
wheelset where force meets rail axle count, adhesive mass fraction
bogie groups the axles it carries wheelbase
axle one axle — drawn out to refine the wheelset driven flag
Control
cab the driver’s desk: throttle, brake demand, direct brake, sanding, regulator, cutoff —
afb AFB in the throttle path —
Logic
value-in takes a reading out of the vehicle reading (speed, brake pipe, motor current, temperature, …)
constant a fixed number value
value-curve piecewise linear characteristic table
combine two values into one operation (sum, difference, product, smaller, larger)
clamp holds a value inside a range lower and upper limit
pid controls the actual value onto the set point proportional, integral, derivative, output limits
notch steps the output and limits its rate notches (0 = continuous), rate
rate-of-change how fast the input is changing smoothing [s]
value-switch picks one of two values, with hysteresis threshold, hysteresis
signal-out where the logic takes hold sink (power controller, brake, sanding, blower, free value 1–4)
Equipment
sifa driver’s safety device kind: time-time / time-distance / RZM
pzb intermittent train protection variant (I 54 … PZB 90 V2.0), train type O/M/U
lzb continuous train protection —
gnt tilting speed supervision — (needs tilt_angle_deg above zero on the vehicle)
doors door control system (TB0 / TAV / UIC-WTB), passenger doors flag
script the Lua behaviour hook script "<mod>:<name>"

A mod extends the palette with presets: a built-in block under a new name with new parameter defaults — a data sheet, not new physics. A mods/<id>/blocks/l620.ron holding the figures of a Voith L 620 reU2:

(
id: "l620",
name: "Voith L 620 reU2",
description: "Two-circuit hydraulic transmission of the DB class 218: starting converter and travel converter, 2 700 kW input.",
base: "hydro-transmission",
params: {
"final_ratio": Number(1.58),
"wheel_diameter": Number(1.0),
"fill_time": Number(1.2),
"hysteresis_kmh": Number(8.0),
"efficiency": Number(0.96),
"circuits": Circuits([
(kind: Converter, ratio: 3.93, stall_ratio: 2.4, coupling_nu: 0.85,
absorption: 0.53, absorption_slope: 0.15,
shift_up_kmh: 72.0, shift_primary_kmh: 20.0),
(kind: Converter, ratio: 2.05, stall_ratio: 1.9, coupling_nu: 0.9,
absorption: 0.5, absorption_slope: 0.1,
shift_up_kmh: 0.0, shift_primary_kmh: 0.0),
]),
},
)

base names the built-in block, params overrides its defaults with the same typed values a graph uses. The preset appears in the editor palette under its name, a vehicle’s graph addresses it as <mod>:<id>, and it bakes exactly like its base block with those defaults. An unknown base or a wrongly-typed parameter is a loading warning, never a crash. Behaviour beyond the built-in physics still goes through the script block — the Lua hook, as everywhere else.

Models are glTF/GLB and use the format’s own features. mods/ is registered as an asset source, so the path is stated relative to the mods directory — <mod>/assets/<file>, loaded as mods://<mod>/assets/<file>. Everything else in a mod’s assets/ directory (textures, sounds) is reachable the same way.

The example model example/assets/br101.gltf is generated by tools/gen_br101.py — a procedural BR 101 built from scratch (no third-party assets in the model, licensed like the project); re-run the script after editing it. The sounds the example vehicle’s sound table plays are the exception: recordings in assets/sounds/ — CC0 cab clicks, and driving noise of the real loco cut out of CC BY trainspotting videos and CC0 recordings — credited in THIRD_PARTY_LICENSES.md and rebuilt from their sources by tools/sounds/br101_sounds.py. The track textures in example/assets/track/ are CC0 as well — a photographed Schotter, weathered concrete and creosoted planks, credited in the same file.

model: Some((
file: "example/assets/br101.gltf",
lods: [(level: 0, distance: 150.0), (level: 1, distance: 400.0)],
// Where a passenger may sit (see People): the floor point below the pelvis in
// model space — the seat is 0.45 m above it, knees and feet in front of it — and
// which way the seat faces (0 = ahead, 180 = backwards).
seats: [(pos: (0.6, 1.25, -3.0)), (pos: (-0.6, 1.25, -3.0), yaw_deg: 180.0)],
parts: [
(node: "door_left", function: "door_left",
motion: Translate(axis: (0.0, 0.0, 1.0), metres: 0.8)),
(node: "pantograph_rear", function: "pantograph",
motion: Rotate(axis: (1.0, 0.0, 0.0), degrees: 45.0)),
(node: "gauge_speed", function: "gauge:speed",
motion: Rotate(axis: (0.0, 0.0, 1.0), degrees: -270.0)),
(node: "lamp_left", function: "lamp:left", motion: Visibility),
],
))

function is a free-form string, exactly like the lamp images of a signal: the app maps the names it knows, mods may invent their own. motion describes how the node moves as the function goes from 0 to 1 — Visibility, Rotate or Translate.

Nothing has to be prepared in Blender. The vehicle editor lists every node of the file and you bind it with one click; the binding lands in the RON, the model stays untouched. Two conventions are recognised on top of that, so that a prepared file needs no clicking:

In Blender Effect
Object name body_LOD0, body_LOD1, … “Read from node names” fills the LOD table with default distances (150 / 400 / 1000 / 4000 m)
Object name with the prefix door_, pant_, sw_, gauge_, lamp_, wheel_/axle_ suggested function plus a sensible motion
Custom property ts_function on the object exported into glTF extras and beats the name. Optional: ts_motion (rotate/translate/visibility/emissive), ts_axis ("0 0 1"), ts_amount (degrees or metres)

Custom properties are set in Blender under Object Properties → Custom Properties; the glTF exporter writes them into extras if “Include → Custom Properties” is switched on.

The simulator spawns the model in place of the placeholder body, shows the level of detail whose distance the vehicle is within, and moves the bound parts. Which functions have a value today: pantograph, door_left, door_right, gauge:speed, gauge:brake_pipe, gauge:cylinder, gauge:main_reservoir, gauge:tractive_effort, switch:throttle, switch:reverser, switch:direct_brake, switch:cab_light, switch:instrument_light, lamp:main_switch, lamp:sanding, and lamp:<indicator> for every indicator of the fitted train protection — the names the HUD prints: lamp:pzb_1000hz, lamp:pzb_500hz, lamp:pzb_befehl, lamp:sifa, lamp:lzb_ue, lamp:lzb_g, lamp:lzb_ende, lamp:lzb_b, lamp:lzb_v40, lamp:lzb_stoerung, … (a blinking indicator blinks at 1 Hz). Likewise gauge:<indicator> for the numeric ones — gauge:mfa_v_soll and gauge:mfa_v_ziel are normalised by the vehicle’s v_max (a second pointer on the speedometer dial is exactly how the MFA shows the target), and gauge:mfa_zielentfernung by 4000 m for an LED-bar style distance display. wiper sweeps a windscreen wiper according to the wiper switch. digit:<indicator>:<place> turns a node into one digit of a numeric display: its children are named 0 … 9 and the matching one is shown (place 0 = ones; leading zeros stay blank, an absent indicator goes dark). Everything else stays in its rest position until sim-core models the state (destination displays, marker lights).

Instrument backlighting is one of those parts, and it has a motion of its own: motion: Emissive does not move the node — it scales the emissive colour of your material by the value, so the node glows along a dimmer instead of popping on at half travel. Model the panel face a second time with an emissive material, put it behind the dials that stand proud of it, and bind it to switch:instrument_light:

(node: "instrument_light", function: "switch:instrument_light", motion: Emissive),

switch:instrument_light is the instrument dimmer of the cab (keys , and ., or a CabControl::InstrumentLight knob in the 3D cab); switch:cab_light is the cab lamp’s plain on/off switch (key 0) for a vehicle whose panel is simply lit or not. The colour in your material is the fully-turned-up look, so how bright a cab glows stays yours — the example loco carries instrument_light in br101.gltf. A node named …_NIGHT is the third variant, for anything that follows dusk rather than a switch (see Lit windows at night).

Terminal window
cargo run -p app -- --loco example:br101_afb --camera outside

The cab: block inside model: makes the cab operable with the mouse (plan ch. 12). It has three parts: the driver’s eye point in model space (X right, Y above the rail head, −Z ahead — where the cab camera sits), the windscreens the rain runs down, and the controls, each binding a glTF node to a simulation input:

cab: Some((
eye: (-0.55, 2.55, -6.5),
windscreen: ["windscreen_front", "windscreen_rear"],
controls: [
(node: "cab_throttle", input: Throttle,
motion: Rotate(axis: (1.0, 0.0, 0.0), degrees: 60.0)),
(node: "cab_sifa", input: Sifa,
motion: Translate(axis: (0.0, -1.0, 0.0), metres: 0.015)),
],
))

windscreen names the panes the weather works on (plan 14.1): rain gathers on them as a film and as drops, the drops run down the glass at a stand and up it above about 15 km/h, and the Wipers control clears a strip wherever its blade has just been. Three things a pane wants:

  • A node of its own. The runtime replaces the node’s material, so a pane that is one primitive of the body mesh would take the rest of the body with it.
  • UVs across and up it: u from the driver’s left edge of the pane to his right, v from its bottom to its top. u is the frame the wiper sweeps in — a pane whose UVs run the other way has its wiper clearing the wrong side.
  • A material to look through. The pane keeps whatever the model gave it and only has water added, so a nearly clear, blended, double-sided material is what a windscreen wants; tools/gen_br101.py writes one called windscreen.

wiper describes the blade on the first named pane, in the pane’s own frame, and the same numbers that pose the 3D blade (its parts entry): pivot in pane UV, length in metres, rest_degrees/sweep_degrees from the pane’s up axis towards +u. From mode and clock the glass shader reconstructs the whole sweep analytically, so the cleared arc, the bulge of pushed water at the blade’s edge, and the drawn blade can never drift apart — and the arc fills back in as fast as the rain can wet it.

Naming no pane is fine — then nothing is drawn on the glass, and the rest of the weather is unaffected. A pane without wiper collects water that nothing clears.

input is one of a closed list (the vehicle editor offers them in a dropdown): Throttle, Reverser, BrakeValve, DirectBrake, AfbTarget, Sifa, PzbAcknowledge, PzbExempt, PzbOverride, LzbTakeover, LzbEnd, LzbTest, Horn, Sanding, BrakeRelease, EngineStart, DoorReleaseLeft, DoorReleaseRight, DoorClose, ParkingBrake, EpBrake, Afb, Battery, Pantograph, MainSwitch, Compressor, TrainType, Wipers (off – interval – slow – fast), Headlights, CabLight, InstrumentLight (the instrument dimmer, continuous), and Display(0) … Display(7) — softkeys for the cab displays, read by the display(ctx) script hook.

How a control answers the mouse follows from the input, nothing is configured:

  • Push buttons (Sifa, PZB/LZB buttons, horn, sanding, …) are held while the mouse button is down and spring back on release.
  • Switches (battery, pantograph, main switch, reverser, train type switch, …) cycle to their next position on click and step without wrap on the scroll wheel.
  • Levers, valves and knobs (power controller, brake valves, AFB target, instrument dimmer) follow a drag along their on-screen direction of travel and step finely on the scroll wheel. The driver’s brake valve runs fill – release – lap – service range – emergency over its travel.

motion is the same type the moving parts use and describes the node’s travel between input 0 and 1. The whole subtree of the node takes the mouse; the hovered control glows and the HUD names it with its position. Everything also stays operable from the keyboard — the two write the same inputs. The camera looks out of eye (F1), pans with the arrow keys and looks around while the right mouse button is held. F4 stands the driver up: the eye then walks from eye through the vehicle’s box (WASD, shift runs, space jumps) and the mouse looks around by itself, so the eye point is the start of the walk, not a fixed seat. E at the side of the vehicle steps out onto the ground and back in again — an open passenger door (doors of the vehicle, ch. 9) or, on a traction unit, the cab door of a vehicle carrying cab data. Outside, the ground and the walls are the meshes themselves: what the walker stands on and what stops him comes out of a ray cast against terrain, platforms and objects, so a platform needs no collision data of its own — only a mesh at the height it is supposed to be walked at. The same ray carries him inside a vehicle: an interior with modelled floors and stairs is walked as it is drawn, and a model without one holds him on the floor its eye implies. Past the end of a vehicle he walks on into the next one of the train.

The walker wears one of the mods’ people (see People below): without a flag the first character with the Player role, in registry order, and --character picks another one — by name, or as a file from the same mods:// paths as the vehicle models:

cargo run -p app -- --camera walk --character people:f01_lena
cargo run -p app -- --camera walk --character example/models/driver.glb

The model stands in its own origin — feet at Y = 0, looking along −Z, metres, Y up, which is what the character pipeline gives. It is shown whenever the camera is not the walker’s own eye (F2, F3); in the first person it is hidden, because the eye sits inside its head and its body would otherwise be in the way of the walker’s ray casts. A model with idle and walk clips (see People below) is animated: it stands with a little life in it and walks when the walker walks, in the walk clip nearest his pace, the cycle sped up with it; a model without clips simply stands.

A screen in the cab is a texture the app renders onto a glTF node — the same idea as TSW’s render targets or MSFS’s instrument webviews, only that the content is described in the vehicle file or drawn by the vehicle’s Lua script:

displays: [
(name: "brake", node: "screen_brake", width: 192, height: 128, widgets: [
Label(x: 8.0, y: 6.0, size: 14.0, text: "HL"),
Value(x: 60.0, y: 6.0, size: 14.0, source: Quantity(BrakePipe),
decimals: 2, unit: "bar"),
Bar(x: 8.0, y: 30.0, w: 140.0, h: 10.0, source: Quantity(BrakePipe), max: 6.0),
]),
(name: "mfa", node: "screen_mfa", width: 256, height: 160),
]

Content, in order of what is easiest:

  1. Widgets — no code. Label (fixed text), Value (a number with decimals, scale and unit) and Bar (fills towards max). source is either Quantity(<sound quantity>) — everything the sound table can hear, including Control(…) positions — or Indicator("<name>"), a numeric indicator of the train protection (mfa_v_soll, mfa_v_ziel, mfa_zielentfernung, …). Coordinates are pixels from the top left; colors linear RGBA 0…1, default white.
  2. The display(ctx) script hook — for real logic: pages, nested menus, EBuLa-like screens. The vehicle’s behaviour script (the one that already has update(ctx)) adds a display function; it is called per screen with ctx.display set to the name and answers with a draw list. Returning nil hands the screen back to its widget list — so a script can drive one screen and leave the others declarative.
  3. An HTML page — for screens with real layout. html: Some("<mod>/displays/<file>.html") on the display draws it from a single HTML file with <style> and <script>, the way MSFS instruments are written — only rendered in-engine (own DOM, flexbox layout, embedded ECMAScript), not by a browser: no extra process, layout and repaint run only when the DOM actually changed, unchanged screens cost nothing. When html is set it drives the screen alone; widgets and the Lua hook are ignored for it.
display = function(ctx)
if ctx.display ~= "mfa" then return nil end
return {
{ kind = "clear", color = {0.02, 0.03, 0.02} },
{ kind = "text", x = 128, y = 10, size = 28, align = "center",
text = string.format("%.0f km/h", ctx.v_kmh) },
{ kind = "rect", x = 8, y = 50, w = 240, h = 2 },
{ kind = "line", x1 = 8, y1 = 120, x2 = 248, y2 = 120, width = 1 },
}
end

Draw kinds: clear (background), rect (filled defaults to true), line, text (align left/center/right). At most 512 commands per frame, text capped at 128 characters; a malformed entry is skipped and reported once in the mod log. ctx carries the display name and size, the driving values update(ctx) gets (v_kmh, brake_pipe, line_voltage, …), value.<indicator> / lamp.<indicator> for everything the train protection shows, and buttons[1]…buttons[8] — the held state of the Display(0)…Display(7) cab controls. Bind those to nodes next to the screen and a click in the 3D cab walks the script’s menu; edge detection is the script’s job (keep the previous state in a local).

The screen glows (emissive), so it stays readable in a dark cab. A display whose name no script answers and whose widget list is empty stays dark.

The page is ordinary HTML with one <style> and one <script> block; the supported subset is deliberately small and fully listed here. HTML: any tags (only their style matters), id, class, style, text. Live values without script: data-bind="v_kmh" replaces the element’s text every tick, data-format shapes it (printf subset %d, %s, %.Nf); data-show="lamp.lzb_ue" hides the element while the value is 0/false. Field names: the driving values of the Lua ctx (v_kmh, brake_pipe, line_voltage, …), value.<indicator> and lamp.<indicator>, time.

CSS: selectors tag, .class, #id, compounds and comma lists; properties display (flex/block/none), flex-direction, justify-content, align-items, flex-grow, gap, width/height (px/%), padding/margin, position: absolute with left/top/right/bottom, background-color, color, font-size, text-align, border: <N>px solid <color>, visibility: hidden, opacity. Colors as #hex, rgb()/rgba(), hsl()/hwb() or a named color. Text is measured in the app’s monospaced display font, so layout is deterministic.

Script API (the whole surface): document.getElementById, on elements textContent, getAttribute/setAttribute, classList.add/remove/toggle/contains, style.setProperty, hidden; the global sim with every field as a property plus sim.button(1..8); onFrame(fn) per tick and onButton(fn(index, pressed)) on every softkey edge — the same Display(0…7) cab controls the Lua hook reads, so clickable 3D softkeys drive the page. A handler that throws is disabled and reported once in the mod log; the screen keeps its last good picture. Pages tick at ~30 Hz (button edges immediately); mods/example/displays/ebula.html is a complete page to start from.

Which path for which screen: widgets for values, bars and labels (no code at all); Lua when the logic already lives in the vehicle script and the drawing is simple; HTML when the screen needs layout — headers, tables, pages, wrapped text. All three end in the same renderer and the same texture; they differ only in how the picture is described.

Modelling rules that matter for the simulation:

  • Length over buffers is the RON value, not the model — but the buffers should be drawn 1–2 cm compressed so that vehicles do not intersect in curves.
  • Origin at the vehicle centre, on the top of the rails; the vehicle runs along −Z/+Z.
  • LOD0 is the close-up model; higher levels get coarser. What is not visible from 150 m away does not belong in LOD1.

The sound table sits in the vehicle file and is maintained in the vehicle editor. An entry has three parts:

  • Trigger — what starts the sound. Loop means no trigger: the sound runs continuously and only its volume and pitch are modulated. That is the normal case for driving noise.
  • Conditions — state predicates. All of them have to hold, otherwise the sound stays silent. Brake squeal is a condition, not an event.
  • Dependencies — curves with support points that map a quantity onto volume and playback speed. factors is a list of further curves multiplied into the volume — a second quantity scaling an entry whose volume already follows a first one. The default rolling entry uses it for the track: factors: [(quantity: Roughness, points: [(0.5, 0.75), (2.0, 1.4)])] — the Roughness quantity is the roughness of the track type under the vehicle (see Track types), so jointed superstructure is audibly louder than welded rail. Rain is the same pattern for the weather — it is how hard it falls rather than whether it does, so a drizzle is not a downpour with the volume turned down — and it is the hook for a rain-on-the-roof loop, as a condition or a volume curve. Thunder goes with it: 1.0 the moment the clap arrives (distance / 343 m/s after the flash) and rolling off after it, longer the further away the strike stood, which is what a triggered thunder entry hangs on.
sounds: [
// A loop, modulated: no trigger, two curves.
(
name: "rolling",
file: "synth:rolling-mid",
trigger: Loop,
volume: Some((quantity: Speed, points: [(0.0, 0.0), (60.0, 0.55)])),
pitch: Some((quantity: Speed, points: [(0.0, 0.7), (200.0, 1.7)])),
positional: true,
),
// A loop held by conditions: heard only while slow *and* braking.
(
name: "brake-squeal",
file: "synth:squeal",
trigger: Loop,
conditions: [
(quantity: Speed, min: 3.0, max: 25.0),
(quantity: BrakeEffort, min: 10.0, max: 10000.0),
],
volume: Some((quantity: Speed, points: [(3.0, 0.0), (8.0, 0.3), (25.0, 0.0)])),
positional: true,
),
// An event: the same table, only with a trigger instead of a loop.
(
name: "rail-joint",
file: "synth:joint",
trigger: Every(quantity: Distance, interval: 30.0),
conditions: [(quantity: Speed, min: 3.0, max: 10000.0)],
volume: Some((quantity: Speed, points: [(3.0, 0.12), (120.0, 0.35)])),
positional: true,
),
]

file is a sample below the mods directory (example/assets/whine.ogg, the same path scheme as a model — WAV, OGG/Vorbis and FLAC are decoded) or one of the sources the app generates at start-up: synth:rolling-low, synth:rolling-mid, synth:rolling-high, synth:traction-low, synth:traction-mid, synth:traction-high, synth:air, synth:compressor, synth:horn, synth:buzzer, synth:squeal, synth:joint, synth:contactor. (synth:rolling and synth:traction without a band are the middle band, for tables written before there were bands.)

positional: true places the sound on the vehicle: it is attenuated by distance, stereo-placed, Doppler-shifted — which is what makes another train audible as it passes — and low-passed, more with distance (air absorbs treble long before bass) and much more while the camera sits in the cab, the cab wall. Sounds of the driver’s desk — buzzer, Sifa — set it to false so they stay at a constant place when the camera goes outside, and they are never filtered: they are in the cab with the listener.

One sound is normally several entries. A single loop stretched over a whole speed range by its playback rate drags its formants along with it and arrives at the top of the range as a toy train. Three loops whose volume windows overlap each stay near their own pitch and hand over to the next:

// Band 1 of 3: silent at a stand, full from 12 to 35 km/h, gone by 60.
(
name: "rolling-low",
file: "synth:rolling-low",
trigger: Loop,
volume: Some((quantity: Speed, points: [(0.0, 0.0), (12.0, 1.0), (35.0, 1.0), (60.0, 0.0)])),
factors: [
(quantity: Speed, points: [(0.0, 0.0), (60.0, 0.55)]),
(quantity: Roughness, points: [(0.5, 0.75), (2.0, 1.4)]),
],
pitch: Some((quantity: Speed, points: [(0.0, 0.85), (60.0, 1.25)])),
positional: true,
),
// Band 2 fades in over exactly the range band 1 fades out over.
(
name: "rolling-mid",
file: "synth:rolling-mid",
trigger: Loop,
volume: Some((quantity: Speed, points: [(35.0, 0.0), (60.0, 1.0), (95.0, 1.0), (130.0, 0.0)])),
// … same factors, pitch ramp over 35 … 130 km/h
),

Two rules make it work:

  1. Neighbours share a flank. Layer A’s fade-out (35 … 60) is layer B’s fade-in, so the windows sum to 1 right through the handover — no dip, no doubling.
  2. The window occupies the volume curve, so how loud the sound is at all goes into factors, which are multiplied in. Above, the first factor is the level over speed and the second the track roughness.

Keep each band’s pitch ramp inside roughly 0.85 … 1.3. Swap the synth: names for six recordings and nothing else about the table changes — mods/example/vehicles/br101_afb.ron is the worked example, with loops cut out of recordings of the real loco (their sources in THIRD_PARTY_LICENSES.md, the cutting in tools/sounds/br101_sounds.py). A sound with a fixed pitch — the 101’s line-side converters, which whine at 500 Hz and its harmonics whenever the main switch is closed, louder under load — is its own entry on MainSwitch with a TractiveEffort factor rather than part of a band.

The vehicle editor plays an entry: ▶ Preview on its card starts it through the editor’s own output device and puts up a slider for every quantity the entry depends on. Moving the speed slider walks the crossfade — auditioning rolling-low and then rolling-mid at the same speed is what a level step between two layers sounds like. The preview is a plain stereo bus: no distance, no cab wall, no reverb, because those belong to a place in the world and the editor has none. Volume and playback speed are shown as numbers next to the button, so a condition that mutes the entry is visible and not merely inaudible.

Triggers:

Trigger Fires
Loop never — the sound runs and is modulated
Rises(quantity: X, threshold: t) when X crosses t upwards
Falls(quantity: X, threshold: t) when X crosses t downwards
Every(quantity: X, interval: i) at every multiple of i — 30 m of Distance is a rail joint, 1 of TapChangerStep a contactor

Quantities: Speed [km/h], Distance [m], EngineRpm [1/min], TapChangerStep, Circuit, TractiveEffort [kN], BrakeEffort [kN], DynamicBrake [kN] (the electric or hydrodynamic brake alone — what the converter is heard doing while the train slows), BrakePipe [bar], BrakeCylinder [bar], AirFlow [bar/s], Slip [m/s], Throttle, Pantograph, MainSwitch, Compressor, Doors, Horn, Alert (any train protection or vigilance device demanding an operation), VigilanceAlert (the Sifa sounding), ProtectionAlert (the PZB/LZB horn — an acknowledgement due, a supervision tripped, the LZB being accepted or ended), and Control(<input>) — the position of a cab control, normalised 0 … 1 over its travel, for every input the 3D cab can bind (Control(Sifa), Control(BrakeValve), Control(Battery), …). Curves interpolate linearly between their support points and hold the last value beyond the ends.

Control is how a lever or switch gets its operating sound, and it fires no matter whether mouse, keyboard, AFB or a script moved it: Rises/Falls around a threshold for one edge, Every with the detent spacing for every notch passed — Every(quantity: Control(Battery), interval: 1.0) clicks a two-position switch on both edges with one entry, Every(quantity: Control(Reverser), interval: 0.5) on each of the three reverser positions. The example vehicle carries a block of these. (The driver’s brake valve usually needs no click — its AirFlow hiss follows from the pressures by itself.)

A table stated here replaces the generated default completely, so it has to carry everything the vehicle is to make. A vehicle without a table runs on the generated loops if it is powered, and stays silent if it is hauled — a coach that is to roll audibly writes its own entry. mods/example/vehicles/br101_afb.ron is a complete table to start from.

One sound that follows different quantities in different states is two entries with one condition each — that is how the traction loop is split into an electric case (pitch over speed, EngineRpm in 0…0) and a diesel case (pitch over EngineRpm, from 1 upwards).

Called once per frame for the train whose leading vehicle names a script. ctx is read-only; the returned table is applied to the cab controls, nil leaves the driver in charge.

ctx
dt, time frame time and simulation time [s]
v_kmh, speed_limit_kmh speed and permitted line speed [km/h]
mass_t train mass [t]
throttle, reverser, direct_brake, sanding current cab controls
afb, afb_target AFB switched on, target speed [km/h]
brake_pipe brake pipe pressure at the leading vehicle [bar]
notch, line_voltage, tractive_effort traction state
return
throttle power controller −1 … +1 (negative = dynamic brake)
direct_brake direct brake 0 … 1
sanding boolean

Values are checked when applied: non-finite numbers are ignored, the rest is clamped.

mods/example/scripts/afb.lua — a scripted AFB. sim-core brings its own (afb: true in the vehicle file); the example vehicle leaves that flag off and shows how a script replaces the built-in behaviour, here with the line speed as an additional ceiling:

local M = {}
local BAND = 10.0 -- proportional band [km/h]
function M.update(ctx)
if not ctx.afb or ctx.reverser == 0 then
return nil
end
local target = math.min(ctx.afb_target, ctx.speed_limit_kmh)
local notch = (target - ctx.v_kmh) / BAND
if notch > 1.0 then notch = 1.0 end
if notch < -1.0 then notch = -1.0 end
return { throttle = notch }
end
return M