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] |
Traction
Section titled “Traction”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.
Block diagram
Section titled “Block diagram”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.
Logic blocks
Section titled “Logic blocks”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>" |
Block presets (blocks/*.ron)
Section titled “Block presets (blocks/*.ron)”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.
Model (glTF)
Section titled “Model (glTF)”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).
cargo run -p app -- --loco example:br101_afb --camera outsideInteractive 3D cab
Section titled “Interactive 3D cab”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:
ufrom the driver’s left edge of the pane to his right,vfrom its bottom to its top.uis 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.pywrites one calledwindscreen.
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 character
Section titled “The character”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_lenacargo run -p app -- --camera walk --character example/models/driver.glbThe 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.
Displays
Section titled “Displays”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:
- Widgets — no code.
Label(fixed text),Value(a number withdecimals,scaleandunit) andBar(fills towardsmax).sourceis eitherQuantity(<sound quantity>)— everything the sound table can hear, includingControl(…)positions — orIndicator("<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. - The
display(ctx)script hook — for real logic: pages, nested menus, EBuLa-like screens. The vehicle’s behaviour script (the one that already hasupdate(ctx)) adds adisplayfunction; it is called per screen withctx.displayset to the name and answers with a draw list. Returningnilhands the screen back to its widget list — so a script can drive one screen and leave the others declarative. - 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. Whenhtmlis 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 }, }endDraw 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.
HTML displays
Section titled “HTML displays”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.
Sounds
Section titled “Sounds”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.
Loopmeans 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.
factorsis 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)])]— theRoughnessquantity is theroughnessof the track type under the vehicle (see Track types), so jointed superstructure is audibly louder than welded rail.Rainis 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.Thundergoes with it: 1.0 the moment the clap arrives (distance / 343 m/safter 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.
Layers
Section titled “Layers”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:
- 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. - 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.
Hearing it
Section titled “Hearing it”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).
Behaviour hook update(ctx)
Section titled “Behaviour hook update(ctx)”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