Car Geometry

A Car definition places itself on the track with length, truckSeparation, and optionally bolsterInsetFront and bolsterInsetRear. These fields determine where the body is drawn and where the couplers end up.

All of them are in meters, measured along the car’s centerline. length runs between the two coupler pivots — the points the couplers swing about, just inside the ends of the body — rather than the bodywork itself. Two coupled cars stand with their facing pivots 1 m apart.

Symmetric cars

Most cars are symmetric, with both trucks the same distance in from the ends. Author length and truckSeparation, and the game centers the truck pair within the length.

The car above is the Southern class SU boxcar (rr/xm-sou-class-su-36ft), 11.3 m between pivots on 8.1 m truck centers:

{
  "truckSeparation": 8.13,
  "length": 11.3
}

Cars with bolster insets

Setting bolsterInsetFront or bolsterInsetRear to a non-zero value places the trucks directly rather than centering them. Each inset is the distance from that end’s coupler pivot to that truck’s center. Use it for a car whose trucks are not centered within its length, such as a locomotive with a longer nose than tail.

In this mode length is derived rather than authored: any value already in the definition is overwritten with the sum of the other three fields.

length = bolsterInsetFront + truckSeparation + bolsterInsetRear

An example with a 4 m nose ahead of the front truck and 2 m of tail behind the rear one:

{
  "truckSeparation": 8.0,
  "bolsterInsetFront": 4.0,
  "bolsterInsetRear": 2.0,
  "length": 14.0
}

The F7A (rr/ld-f7a) is real pack data with a smaller, less round difference: its front overhang reaches 0.25 m further past the front truck than its rear overhang reaches past the rear one — bolsterInsetFront 2.75, truckSeparation 9.144, bolsterInsetRear 2.5, for a length of 14.394. Its B unit (rr/ld-f7b) uses equal insets of 2.5: bolster insets can position a symmetric car explicitly instead of relying on the centered default.

Write the derived length into the definition anyway, as the F7A does, so the file reports the same number the game uses.

Body positioning

The body is positioned with its origin midway between the trucks, not at the middle of the length. When the insets differ those are two different points, and the body origin sits toward the end with the shorter inset by half the difference between them:

centerOffset = (bolsterInsetFront - bolsterInsetRear) / 2

That is 1.0 m for the 4 m / 2 m example above and 0.125 m for the F7A. Each coupler pivot is placed at length / 2 from the body origin, offset by centerOffset, which lands both of them where the insets say. The consequence for modeling is that the origin of the model must sit midway between the trucks.

Minimum and fallback values

Authored geometry is forced into range as each car is set up:

Situation	Result
Either bolster inset is non-zero	length is recomputed from the insets and truckSeparation
length under 1 m (and no insets)	length becomes 1 m
truckSeparation under 1 m	truckSeparation becomes half the length

A car definition with no geometry authored at all ends up 1 m long on 0.5 m truck centers. A car riding on what looks like a single point is usually missing these fields entirely.

Steam locomotives

Steam locomotive definitions do not use truckSeparation or the bolster insets, and the Definition Editor hides those fields. A steam locomotive is positioned from its ends and its wheelsets instead.

positionHead and positionTail are the coupler pivots, in meters from the model origin, measured positive toward the front. length is the distance between them and cannot be authored: a value written into the definition has no effect.

wheelsets lists the wheels the locomotive rides on, authored front to rear. Validation warns when the list is out of order, since the wheelsets are walked in list order while the locomotive is positioned along the track. Each entry holds:

• offset — the center of the wheelset, in meters from the origin.
• length — the wheelbase. 0 means a single axle; otherwise the outer axles sit at offset ± length / 2.
• diameter — wheel diameter in meters. It drives the rolling animation, and on the main driver group it also feeds tractive effort and the equipment stats.
• numberOfAxles — how many axles the entry stands for.
• animation — the wheel rotation clip.
• transform — the transform of a pilot or trailing truck, rewritten every frame to hold its wheels on the railhead. Drivers are parented to the body and leave this unset. Parenting a component inside a wheelset transform is a validation error, because the component would then follow the wheels instead of the body.

mainDriverIndex names the driving wheelset within that list. It is the reference the locomotive’s curve capability is measured from; an index that does not resolve falls back to a generic default.

The locomotive is supported on its outermost wheelsets, which take the place of a car’s trucks. The two support points are their outer edges, offset + length / 2 at the front and offset - length / 2 at the rear, so a multi-axle driver group spans a real distance rather than collapsing to a point. The outermost pair is chosen by offset, which keeps a long driver group from displacing a small leading wheel authored ahead of it.

The locomotive in the photo is a 2-6-2 (rr/ls-262-g16) with three wheelsets: a single leading axle, a three-axle driver group on a 2.79 m wheelbase, and a single trailing axle.

{
  "positionHead": 4.5,
  "positionTail": -3.65,
  "mainDriverIndex": 1,
  "wheelsets": [
    {
      "offset": 3.58137,
      "diameter": 0.62,
      "numberOfAxles": 1,
      "animation": { "clipName": "Pilot" },
      "transform": { "path": ["engine", "Pilot"] }
    },
    {
      "offset": 0.126959,
      "length": 2.794,
      "diameter": 1.12,
      "numberOfAxles": 3,
      "animation": { "clipName": "Drivers" },
      "transform": null
    },
    {
      "offset": -3.65763,
      "diameter": 0.62,
      "numberOfAxles": 1,
      "animation": { "clipName": "Trailing" },
      "transform": { "path": ["engine", "Trailing"] }
    }
  ]
}

Tenders

A tender is an ordinary Car definition with its own length and truckSeparation, coupled behind the locomotive. The locomotive’s tenders field lists the ones it can be paired with, and each pairing’s drawbarDistance sets the gap between the two frames; 0 falls back to the standard coupler separation, which is the 1 m gap in the photo above.

Articulated locomotives

An ArticulatedSteamLocomotive adds engineSets, each with its own wheelsets and a pivotOffset. Those wheelsets are measured from the origin as pivotOffset + offset and are considered alongside the main frame’s when the outermost pair is chosen, so an articulated locomotive can be supported on an engine set rather than on the wheels of its own frame.