Skip to content
Connected RailsConnected Rails

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.

Copying a vehicle that already runs is faster than filling an empty one, and you get a valid file at every step.

  1. A locomotive: copy the example’s BR 101 into your mod:

    Terminal window
    mkdir -p mods/mymod/vehicles
    cp mods/example/vehicles/br101_afb.ron mods/mymod/vehicles/my_loco.ron

    br101_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.

  2. 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….

  3. Change name to the display name you want. The file name is what addresses the vehicle: mods/mymod/vehicles/my_loco.ron becomes mymod: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.

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 weight brake_weight [t], the force max_force [N], max_cylinder [bar] and cylinder_to_reservoir; valve and position pick the control valve and the default brake position. A traction unit adds has_direct and 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, Converter and Diesel model the drive from its machine data. A hauled vehicle simply leaves traction out. See Traction.
  • Coupler — coupler carries slack, stiffnesses, damping and breaking force; its kind (Screw, CenterBuffer, Bar) decides what it can be coupled to. Left out, kind is a screw coupling.
  • Equipment — safety (PZB, LZB, Sifa), afb, doors and passenger_doors. Anything left out is “not fitted”: a coach normally has passenger_doors: true and no safety, and the leading vehicle’s doors decides 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.

Once the base data loads, drive the vehicle before you touch the model:

Terminal window
cargo run -p app -- --loco mymod:my_loco

The 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.

The vehicle editor edits the same file with live checks:

Terminal window
cargo run -p vehicle-editor -- mods/mymod/vehicles/my_loco.ron
cargo 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 graph on 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 over traction, brake, safety, doors, afb, script and 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.

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:

Terminal window
cargo run -p app -- --loco mymod:my_loco --camera outside

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)),
],
)),
  1. Give every lever, button and switch a node of its own in the model. The whole subtree of the node takes the mouse.
  2. Set eye where the driver’s head is. F1 looks out of it; F4 stands the driver up and walks from there.
  3. Bind each node to an input from 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.
  4. motion is the node’s travel from input 0 to 1, the same type the moving parts use.
  5. 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. The wiper record describes the blade; see Interactive 3D cab.

Everything stays operable from the keyboard as well — mouse and keys write the same inputs.

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 to update(ctx) in the vehicle’s script returns a draw list; returning nil hands 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.

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,
),
],
  1. 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.
  2. 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).
  3. Use trigger: Every(quantity: Control(<input>), interval: …) or Rises/Falls for switch and lever clicks, positional: false for desk sounds such as the Sifa buzzer.
  4. 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.

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-out and 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.lua and name it in the vehicle (script: Some("mymod:my_loco"), or the script block in the diagram). Its update(ctx) is called once per frame for the train whose leading vehicle names it; it reads ctx and returns cab controls, or nil to leave the driver in charge:

    local M = {}
    function M.update(ctx)
    if ctx.v_kmh > ctx.speed_limit_kmh then
    return { throttle = 0.0 }
    end
    return nil
    end
    return M

    Returned 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 hook update(ctx).

A script that raises an error is switched off after the first error and the run goes on.

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.