Adding a vehicle
A vehicle is one RON file in your mod’s vehicles/ directory: physics, model binding, cab,
screens and sounds all live in it, and only real behaviour goes into Lua. This guide builds
one up in the order that gets you driving soonest: base data first, then the model, then
the cab and everything around it. The full field lists are in the
Vehicles reference; this page explains the steps.
It assumes you already have a mod with a mod.ron (see Your first mod).
The examples below use the mod id mymod.
1. Start from a working vehicle
Section titled “1. Start from a working vehicle”Copying a vehicle that already runs is faster than filling an empty one, and you get a valid file at every step.
-
A locomotive: copy the example’s BR 101 into your mod:
Terminal window mkdir -p mods/mymod/vehiclescp mods/example/vehicles/br101_afb.ron mods/mymod/vehicles/my_loco.ronbr101_afb.ron is the most complete vehicle in the repository: converter drive, PZB/LZB/Sifa, a 3D cab, three displays and a full sound table.
-
A coach or wagon, or another kind of drive: open the vehicle editor and pick File → New from template. Powered vehicles offers the BR 101 (three-phase), BR 110 (tap changer), BR 218 (diesel-hydraulic), BR 232 (diesel-electric), BR 52 (steam) and BR 648 (railcar); Hauled vehicles the Bnrz passenger coach and the Eaos freight wagon. A template brings the data only — no model, no sounds, no script — and its name ends in “(copy)” so you know which field to fill in first. Save it into
mods/mymod/vehicles/with File → Save as…. -
Change
nameto the display name you want. The file name is what addresses the vehicle:mods/mymod/vehicles/my_loco.ronbecomesmymod:my_loco(Structure of a mod).
The copied BR 101 still points at the example mod’s model (example/assets/br101.gltf),
script (example:afb) and sounds. That works as long as the example mod is installed; list
it in your manifest’s depends until you have replaced them with your own.
2. Get the base data right
Section titled “2. Get the base data right”These are the figures that decide whether the vehicle moves, stops and couples sensibly. Everything else can wait.
( name: "My Loco", length: 19.1, // length over buffers [m] mass_empty: 84000.0, // tare mass [kg] rotating_mass_factor: 0.20, // 0.05 coach … 0.25 powered vehicle davis: (a: 2200.0, b: 60.0, c: 6.5), // running resistance [N], v in m/s v_max: 220.0, // running gear limit [km/h] axles: 4, axle_base_sum: 5.3, // sum over all bogies, not the vehicle length adhesive_mass_fraction: 1.0, // loco 1.0, coach 0.0 // brake, traction, coupler …)- Brake — every vehicle needs one. The essentials are the friction pairing
kind, the braked weightbrake_weight[t], the forcemax_force[N],max_cylinder[bar] andcylinder_to_reservoir;valveandpositionpick the control valve and the default brake position. A traction unit addshas_directand usually a main reservoir (main_volume,compressor_delivery). See Brake. - Traction —
traction: Some(Curve(...))is the simplest start: tractive effort straight off a diagram.TapChanger,ConverterandDieselmodel the drive from its machine data. A hauled vehicle simply leavestractionout. See Traction. - Coupler —
couplercarries slack, stiffnesses, damping and breaking force; itskind(Screw,CenterBuffer,Bar) decides what it can be coupled to. Left out,kindis a screw coupling. - Equipment —
safety(PZB, LZB, Sifa),afb,doorsandpassenger_doors. Anything left out is “not fitted”: a coach normally haspassenger_doors: trueand nosafety, and the leading vehicle’sdoorsdecides the door control of the train.
The other fields — gauge, air resistance, tilting, hunting, payload — have sensible defaults or are described in the Vehicles reference.
3. Drive it
Section titled “3. Drive it”Once the base data loads, drive the vehicle before you touch the model:
cargo run -p app -- --loco mymod:my_locoThe simulator starts straight into a run with your vehicle. Add --line <mod>:<line> to
pick the line, for example --line example:beispielstrecke. The default keys are on
Controls and key bindings: 1–4 for battery, pantograph, main
switch and compressor, R for the reverser, W/S for the power controller, A/D for
the brake valve.
A file that does not load is a warning, never a crash: the simulator logs
vehicle mymod:my_loco not found — using the BR 101 and puts the BR 101 on the line
instead. The mod manager (F9 in a run, Mods on the main menu) lists the loading
warnings of every mod; see also Troubleshooting.
4. Open it in the vehicle editor
Section titled “4. Open it in the vehicle editor”The vehicle editor edits the same file with live checks:
cargo run -p vehicle-editor -- mods/mymod/vehicles/my_loco.roncargo run -p vehicle-editor -- mods/mymod/vehicles/my_loco.ron --graph # start on the block diagram- The left panel holds the base data (Base data, Running gear, Coupler, Running
resistance with a Suggest button for the rolling resistance, Sounds), the right
panel the model (Levels of detail, Moving parts, Cab, Displays, Nodes in the
file). The centre shows the 3D viewport with a reference body of the length over
buffers, so you see at once whether the model matches
length. - The Checks group lists errors and warnings for the whole file: a zero length or tare mass, a missing braked weight, a drive that out-pulls the rail, a part, cab control or display bound to a node the model does not have, levels of detail listed twice or out of order. Work through it until it reads “No findings.”
- Chips at the top left of the centre view switch between 3D model and Block diagram.
Two things to know before you save from the editor:
- The editor rewrites the file from the data, so comments in a hand-written file are lost. It asks before it does.
- It writes a
graphon save. A vehicle without a block diagram gets one synthesised from its fields on open, and from then on the diagram is authoritative: loading bakes it overtraction,brake,safety,doors,afb,scriptand the running gear figures. After the first save, change the drive and brake in the diagram, not in those RON fields. Mass, length, running resistance, coupler, sounds and model stay hand-editable. See Block diagram.
The full tour of the program is on the Vehicle editor page.
5. Build the 3D model
Section titled “5. Build the 3D model”Models are glTF or GLB. Follow the conventions of the example model, which
tools/gen_br101.py builds procedurally:
- Origin at the vehicle centre, on the top of the rails.
- Axes: the vehicle runs along −Z/+Z, +Y is up, the driver’s end is −Z (“ahead”).
- Units: metres.
- Buffers drawn 1–2 cm compressed, so that vehicles do not intersect in curves. The
spacing in the train comes from
length, not from the model. - Levels of detail: objects named
<something>_LOD0,_LOD1, … (body_LOD0,body_LOD1). LOD0 is the close-up model; what is not visible from 150 m does not belong in LOD1.
Put the file into your mod and point the vehicle at it. The path is relative to the
mods/ directory:
model: Some(( file: "mymod/assets/my_loco.gltf", lods: [(level: 0, distance: 150.0), (level: 1, distance: 2000.0)], parts: [ /* moving parts, see below */ ],)),In the editor, File → Import model… loads a model; a file outside mods/ is refused
(“copy the model into your mod first”). Read from node names fills the level of detail
table from the _LOD nodes.
Moving parts bind a node to a function with a motion (Visibility, Rotate,
Translate, or Emissive for a backlit panel):
(node: "pant_front", 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: -240.0)),(node: "lamp_1000hz", function: "lamp:pzb_1000hz", motion: Visibility),Nothing has to be prepared in Blender: Nodes in the file lists every node, and you bind
one with a click. A prepared file needs no clicking — node prefixes door_, pant_,
sw_, gauge_, lamp_, wheel_/axle_, or a ts_function custom property, are offered
as suggestions, and Take over all suggestions binds them in one go. The functions the
simulator evaluates (pantograph, door_left, gauge:speed, switch:throttle,
lamp:<indicator>, digit:<indicator>:<place>, wiper, …) are listed under
Model (glTF).
Check the result from outside:
cargo run -p app -- --loco mymod:my_loco --camera outside6. Make the cab interactive
Section titled “6. Make the cab interactive”The cab: block inside model: places the driver’s eye, names the windscreens and binds
glTF nodes to cab controls, so the desk works with the mouse:
cab: Some(( eye: (-0.55, 2.55, -6.5), // model space: X right, Y above rail head, -Z ahead 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_brake", input: BrakeValve, 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)), ],)),- Give every lever, button and switch a node of its own in the model. The whole subtree of the node takes the mouse.
- Set
eyewhere the driver’s head is.F1looks out of it;F4stands the driver up and walks from there. - Bind each node to an
inputfrom the closed list (Throttle,Reverser,BrakeValve,DirectBrake,Sifa,PzbAcknowledge,Horn,Battery,Pantograph,MainSwitch, …). The editor offers them in a dropdown, and the gesture follows from the input: buttons are held, switches cycle on click, levers follow a drag. motionis the node’s travel from input 0 to 1, the same type the moving parts use.- For rain and wipers, each windscreen pane needs its own node, UVs running across (
u) and up (v) the pane, and a nearly clear material. Thewiperrecord describes the blade; see Interactive 3D cab.
Everything stays operable from the keyboard as well — mouse and keys write the same inputs.
7. Add displays
Section titled “7. Add displays”A cab screen is a texture rendered onto a glTF node. The node needs UVs that map the
screen (u left to right, v top to bottom), otherwise it glows plain white. Pick the
simplest of the three content paths that does the job:
displays: [ // Widgets: no code at all. (name: "brake", node: "screen_brake", width: 160, height: 120, widgets: [ Label(x: 8.0, y: 8.0, size: 12.0, text: "HL"), Value(x: 44.0, y: 8.0, size: 12.0, source: Quantity(BrakePipe), decimals: 2, unit: "bar"), ]), // Drawn by the display(ctx) function of the vehicle's script. (name: "mfa", node: "screen_mfa", width: 256, height: 160), // An HTML page with its own layout and script. (name: "ebula", node: "screen_ebula", width: 256, height: 192, html: Some("mymod/displays/ebula.html")),],- Widgets (
Label,Value,Bar) for values and bars. - Lua — a
display(ctx)function next toupdate(ctx)in the vehicle’s script returns a draw list; returningnilhands the screen back to its widgets. - HTML — a page under your mod’s
displays/directory; ebula.html is a complete one to copy.
Softkeys are cab controls with input: Display(0) … Display(7); the Lua hook reads them
as ctx.buttons[1] … [8], an HTML page through onButton. Details:
Displays and
HTML displays.
8. Give it sounds
Section titled “8. Give it sounds”The sounds: list is the vehicle’s whole sound table. A table you write replaces the
generated default completely: leave it out and a powered vehicle runs on generated loops
while a hauled one is silent, so a coach that is to roll audibly needs its own entries.
sounds: [ ( name: "rolling-low", file: "mymod/assets/sounds/rolling-low.ogg", // WAV, OGG/Vorbis or FLAC below mods/ trigger: Loop, volume: Some((quantity: Speed, points: [(0.0, 0.0), (12.0, 1.0), (35.0, 1.0), (60.0, 0.0)])), pitch: Some((quantity: Speed, points: [(0.0, 0.85), (60.0, 1.25)])), positional: true, ),],- Start with the example’s table and swap the files for your own recordings, or use the
generated
synth:sources (synth:rolling-mid,synth:horn, …) as placeholders. - Split a sound that spans a wide speed range into layers whose volume windows share a flank, rather than one loop stretched by its pitch (Layers).
- Use
trigger: Every(quantity: Control(<input>), interval: …)orRises/Fallsfor switch and lever clicks,positional: falsefor desk sounds such as the Sifa buzzer. - Audition each entry with ▶ Preview on its card in the editor’s Sounds group; a slider appears for every quantity it depends on (Hearing it).
The triggers and quantities are listed under Sounds.
9. Add behaviour: block diagram or Lua
Section titled “9. Add behaviour: block diagram or Lua”What a table of figures cannot express is behaviour. There are two places for it:
-
Logic blocks in the block diagram —
value-in,pid,value-curve,value-switch,signal-outand friends wired on the editor’s canvas. They are compiled into the vehicle and run inside every simulation step, before the drive. A cruise control is three blocks. This is the first choice for control logic. See Logic blocks. -
A Lua script — for behaviour beyond what the blocks offer. Put it in
mods/mymod/scripts/my_loco.luaand name it in the vehicle (script: Some("mymod:my_loco"), or thescriptblock in the diagram). Itsupdate(ctx)is called once per frame for the train whose leading vehicle names it; it readsctxand returns cab controls, ornilto leave the driver in charge:local M = {}function M.update(ctx)if ctx.v_kmh > ctx.speed_limit_kmh thenreturn { throttle = 0.0 }endreturn nilendreturn MReturned values are checked: non-finite numbers are ignored, the rest is clamped. afb.lua is the worked example, with a
display(ctx)function for the MFA screen as well. See Behaviour hookupdate(ctx).
A script that raises an error is switched off after the first error and the run goes on.
10. Put it into a scenario
Section titled “10. Put it into a scenario”A scenario’s consists: list says what stands on the line; a consist names its vehicles
head first, by their <mod>:<file stem>:
consists: [ (number: "Lz 77400", vehicles: [(vehicle: "mymod:my_loco", count: 1)], at: Yard("Abstellgleis 1")), (number: "Lokzug 77401", vehicles: [(vehicle: "mymod:my_loco", count: 1), (vehicle: "mymod:my_coach", count: 3)], at: At(edge: EdgeId(0), s: 3800.0, dir: 1)),],player_train: 0,player_train picks which consist the player drives. A scenario without consists: takes
the vehicle picked in the main menu instead, so your vehicle also appears there in the
vehicle step of a free run. Start the scenario with
cargo run -p app -- --scenario mymod:<scenario>; the whole format is in
Scenarios and the walk-through in
Writing a scenario.
Next steps
Section titled “Next steps”- Vehicles reference — every field, block and quantity.
- Vehicle editor — the program in detail.
- Writing a scenario — give your vehicle something to do.
- Packaging and publishing — pack the mod and share it.
- Troubleshooting — when the vehicle does not load or behaves oddly.