# Ravenhall Tractor 1.0.0

A free, game-ready American long-hood conventional semi tractor (6x4, 72-inch-class sleeper) at real-world
scale with PBR materials, for Unity, Unreal Engine, Godot, Blender, three.js, Babylon.js or anything that
reads glTF 2.0 (or OBJ as a static fallback). It is only the model: no scripts, no scene, no environment.

Licence: **CC BY 4.0**. Use it for anything, commercial or not, and credit it where your project lists
credits (credits screen, about page, README or site footer):

    Ravenhall Tractor by Cozu (https://cozu.xyz/assets/ravenhall-tractor), CC BY 4.0

On a web page, link it:

    <a href="https://cozu.xyz/assets/ravenhall-tractor">Ravenhall Tractor</a> by <a href="https://cozu.xyz">Cozu</a>, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>

"Ravenhall" and its logos are fictional. See `LICENSE.txt`. More free assets: https://cozu.xyz

![Ravenhall tractor](previews/hero.png)

## Files

| File | Triangles | Draw calls | Size | Use |
|---|---:|---:|---:|---|
| `ravenhall_tractor.glb` | 230,163 | 80 | 11.2 MB | LOD0: close-ups, hero shots, cinematics; textures up to 1024 px |
| `ravenhall_tractor_lod1.glb` | 60,816 | 83 | 4.7 MB | LOD1: normal gameplay distance (about 20-50 m), textures up to 1024 px |
| `ravenhall_tractor_lod2.glb` | 19,125 | 73 | 3.3 MB | LOD2: mid distance (about 50-120 m), textures up to 1024 px, small parts folded into the palette |
| `ravenhall_tractor_lod3.glb` | 8,858 | 23 | 0.6 MB | LOD3: far (120 m+), one palette material plus the lamps, proxy wheels; link nodes kept but empty (out of sight under the truck) |
| `ravenhall_tractor_rigged.glb` | 230,163 | 26 | 13.2 MB | LOD0 as one skinned mesh, one bone per node (Unreal Chaos vehicles, any skeleton-based vehicle system). The links are skinned to the parts they join, so they follow with no constraints |
| `ravenhall_tractor_rigged_lod1.glb` .. `_lod3.glb` | as LOD1-3 | | 9.4 MB total | the same skeleton skinned to LOD1-3, for importing as LODs of the skeletal mesh |
| `ravenhall_tractor_collision.glb` | - | - | 0.02 MB | convex hulls for the body (cab, sleeper, hood, chassis, each at most 250 triangles) and a box per mirror |
| `ravenhall_tractor_collision_wheels.glb` | - | - | 0.03 MB | wheel cylinders, only for parked props and wrecks (driven vehicles use wheel colliders / raycasts instead) |
| `ravenhall_tractor_web.glb` | 60,816 | 83 | 2.4 MB | for web pages: LOD1 geometry with EXT_meshopt_compression and WebP textures (EXT_texture_webp); positions and node transforms are left uncompressed, so pivots match the other files. three.js needs `GLTFLoader.setMeshoptDecoder(MeshoptDecoder)`; Babylon.js and model-viewer decode it built in. In Unity, Unreal and Godot use the LOD1 file instead |
| `obj/` | 230,163 | - | - | Wavefront OBJ + MTL + textures: static fallback, one object per node but no pivots, no baked occlusion and no lamp glow; the palette is split into one plain material per finish; normal maps as `map_Bump`. Unreal imports OBJ in centimetres: set the import scale to 100 |
| `spec.json` | | | | all numbers below in machine-readable form |
| `previews/` | | | | renders |

Every GLB embeds its textures and passes the Khronos glTF Validator with 0 errors. The only warnings say
tangents are not stored; engines generate MikkTSpace tangents on import, which is what the normal maps expect.

Triangles no camera can see are left out of every file: the parts of pieces sunk inside other pieces, and
the facing sidewalls inside each dual-tyre pair. They were found by rendering the model from thousands of
cameras: far away from every direction, close up all round and below, on the ground under the chassis, and
inside the cab and sleeper (for cockpit cameras). The body only counts as hidden behind other body parts, and
each wheel or suspension part only behind itself, so no steering angle, wheel spin or suspension travel
uncovers a gap. Skin weights are stored as normalized 8-bit values (core glTF 2.0).

All LOD files share the same node names, pivots and origin, so an LOD group can swap them freely.
Suggested screen-height switch points: LOD0 above 50 %, LOD1 above 20 %, LOD2 above 7 %, LOD3 below.

## Scale, axes, origin

- Units: metres. 9.31 m long, 2.96 m wide over the mirrors, 4.08 m tall at the stack tips.
- Axes (glTF standard): **+Y up, the front of the truck faces +Z, its left (driver) side is +X.**
  Unity, Unreal, Godot and Blender convert this on import. Unreal's Chaos vehicles expect the front on +X:
  check the imported orientation and rotate the mesh 90 degrees in the import options if needed.
- Origin: on the ground (tyre contact plane, y = 0), centred under the truck's footprint. It is identical in every file.
- Tyres are modelled round (unloaded) so they can spin. 11R22.5 on 22.5 x 8.25 steel wheels, radius 0.523 m.

## Hierarchy

```
ravenhall_tractor (root, origin on the ground under the footprint centre)
    +-- body  [0, 0, 0]  124,218 tris
    +-- glass  [0, 0, 0]  187 tris
    +-- lights  [0, 0, 0]  5,088 tris
    +-- steering_wheel  [0.5, 2.28, 1.96]  896 tris
    +-- pitman_arm  [0.55, 0.9, 4.27]  80 tris
        +-- link_drag_link  [0.52, 0.72, 4.27]  286 tris  -> aims at target_drag_link
    +-- axle_front  [0, 0.523, 3.78]  1,012 tris
        +-- knuckle_front_left  [0.9, 0.523, 3.78]  788 tris
            +-- wheel_front_left  [1.03, 0.523, 3.78]  9,981 tris
            +-- link_tie_rod  [0.8675, 0.443, 3.58]  132 tris  -> aims at target_tie_rod
            +-- target_drag_link  (empty)
        +-- knuckle_front_right  [-0.9, 0.523, 3.78]  500 tris
            +-- wheel_front_right  [-1.03, 0.523, 3.78]  9,953 tris
            +-- target_tie_rod  (empty)
        +-- link_shock_front_left_lower  [0.53, 0.543, 3.92]  168 tris  -> aims at link_shock_front_left_upper
        +-- link_shock_front_right_lower  [-0.53, 0.543, 3.92]  168 tris  -> aims at link_shock_front_right_upper
        +-- target_spring_front_left  (empty)
        +-- target_spring_front_right  (empty)
    +-- axle_rear1  [0, 0.523, -2.62]  1,096 tris
        +-- wheel_rear1_left  [0.9475, 0.523, -2.62]  17,744 tris
        +-- wheel_rear1_right  [-0.9475, 0.523, -2.62]  17,285 tris
        +-- link_interaxle_shaft  [0, 0.56, -2.84]  84 tris  -> aims at target_interaxle_shaft
        +-- link_shock_rear1_left_lower  [0.47, 0.47, -2.75]  168 tris  -> aims at link_shock_rear1_left_upper
        +-- link_shock_rear1_right_lower  [-0.47, 0.47, -2.75]  168 tris  -> aims at link_shock_rear1_right_upper
        +-- target_arm_rear1_left  (empty)
        +-- target_torque_rod_rear1_left  (empty)
        +-- target_arm_rear1_right  (empty)
        +-- target_torque_rod_rear1_right  (empty)
        +-- target_driveshaft  (empty)
    +-- axle_rear2  [0, 0.523, -3.94]  1,097 tris
        +-- wheel_rear2_left  [0.9475, 0.523, -3.94]  17,301 tris
        +-- wheel_rear2_right  [-0.9475, 0.523, -3.94]  17,283 tris
        +-- link_shock_rear2_left_lower  [0.47, 0.47, -4.07]  168 tris  -> aims at link_shock_rear2_left_upper
        +-- link_shock_rear2_right_lower  [-0.47, 0.47, -4.07]  168 tris  -> aims at link_shock_rear2_right_upper
        +-- target_arm_rear2_left  (empty)
        +-- target_torque_rod_rear2_left  (empty)
        +-- target_arm_rear2_right  (empty)
        +-- target_torque_rod_rear2_right  (empty)
        +-- target_interaxle_shaft  (empty)
    +-- link_arm_rear1_left  [0.5, 0.44, -1.84]  86 tris  -> aims at target_arm_rear1_left
        +-- link_bellows_rear1_left_lower  [0.45, 0.49, -2.94]  76 tris  -> aims at link_bellows_rear1_left_upper
    +-- link_arm_rear1_right  [-0.5, 0.44, -1.84]  84 tris  -> aims at target_arm_rear1_right
        +-- link_bellows_rear1_right_lower  [-0.45, 0.49, -2.94]  76 tris  -> aims at link_bellows_rear1_right_upper
    +-- link_arm_rear2_left  [0.5, 0.44, -3.16]  86 tris  -> aims at target_arm_rear2_left
        +-- link_bellows_rear2_left_lower  [0.45, 0.49, -4.26]  76 tris  -> aims at link_bellows_rear2_left_upper
    +-- link_arm_rear2_right  [-0.5, 0.44, -3.16]  84 tris  -> aims at target_arm_rear2_right
        +-- link_bellows_rear2_right_lower  [-0.45, 0.49, -4.26]  76 tris  -> aims at link_bellows_rear2_right_upper
    +-- link_bellows_rear1_left_upper  [0.45, 0.785, -2.94]  240 tris  -> aims at link_bellows_rear1_left_lower
    +-- link_bellows_rear1_right_upper  [-0.45, 0.785, -2.94]  240 tris  -> aims at link_bellows_rear1_right_lower
    +-- link_bellows_rear2_left_upper  [0.45, 0.785, -4.26]  240 tris  -> aims at link_bellows_rear2_left_lower
    +-- link_bellows_rear2_right_upper  [-0.45, 0.785, -4.26]  240 tris  -> aims at link_bellows_rear2_right_lower
    +-- link_driveshaft  [0, 0.6249, -0.96]  84 tris  -> aims at target_driveshaft
    +-- link_shock_front_left_upper  [0.525, 0.92, 4.02]  188 tris  -> aims at link_shock_front_left_lower
    +-- link_shock_front_right_upper  [-0.525, 0.92, 4.02]  188 tris  -> aims at link_shock_front_right_lower
    +-- link_shock_rear1_left_upper  [0.47, 0.8, -2.72]  188 tris  -> aims at link_shock_rear1_left_lower
    +-- link_shock_rear1_right_upper  [-0.47, 0.8, -2.72]  188 tris  -> aims at link_shock_rear1_right_lower
    +-- link_shock_rear2_left_upper  [0.47, 0.8, -4.04]  188 tris  -> aims at link_shock_rear2_left_lower
    +-- link_shock_rear2_right_upper  [-0.47, 0.8, -4.04]  188 tris  -> aims at link_shock_rear2_right_lower
    +-- link_spring_front_left_aft  [0.42, 0.771, 3.08]  228 tris  -> aims at target_spring_front_left
    +-- link_spring_front_left_fwd  [0.42, 0.771, 4.48]  228 tris  -> aims at target_spring_front_left
    +-- link_spring_front_right_aft  [-0.42, 0.771, 3.08]  228 tris  -> aims at target_spring_front_right
    +-- link_spring_front_right_fwd  [-0.42, 0.771, 4.48]  228 tris  -> aims at target_spring_front_right
    +-- link_torque_rod_rear1_left  [0.36, 0.69, -1.92]  104 tris  -> aims at target_torque_rod_rear1_left
    +-- link_torque_rod_rear1_right  [-0.36, 0.69, -1.92]  104 tris  -> aims at target_torque_rod_rear1_right
    +-- link_torque_rod_rear2_left  [0.36, 0.69, -3.24]  104 tris  -> aims at target_torque_rod_rear2_left
    +-- link_torque_rod_rear2_right  [-0.36, 0.69, -3.24]  104 tris  -> aims at target_torque_rod_rear2_right
    +-- center_of_mass  (empty)
    +-- socket_headlamp_left  (empty)
    +-- socket_headlamp_right  (empty)
    +-- socket_fifth_wheel  (empty)
    +-- socket_taillamp_left  (empty)
    +-- socket_taillamp_right  (empty)
    +-- socket_exhaust_left  (empty)
    +-- socket_exhaust_right  (empty)
    +-- socket_worklamp  (empty)
```

| Node | Parent | Position (x, y, z) | What it is for |
|---|---|---|---|
| `body` | root | 0, 0, 0 | everything that does not move: cab, sleeper, hood, frame, tanks, springs, interior |
| `glass` | root | 0, 0, 0 | all windows, alpha-blended and double-sided (separate so engines can sort or swap it; keeps Nanite on body) |
| `lights` | root | 0, 0, 0 | all lamp lenses and bulbs, one material per light function (see Lights) |
| `steering_wheel` | root | 0.5, 2.28, 1.96 | turns about its local Z axis (the steering column, tilted at rest); about 18:1 to the road wheels, 4 to 4.5 turns lock to lock |
| `pitman_arm` | root | 0.55, 0.9, 4.27 | steering box output arm: rotate about local X by -1.12 x the left knuckle's steer angle (keeps the drag link on its ball) |
| `axle_front` | root | 0, 0.523, 3.78 | beam axle (I-beam, spring pads); rises and rolls with the front suspension, carries both knuckles |
| `knuckle_front_left` | axle_front | 0.9, 0.523, 3.78 | pivot on the kingpin, 0.13 m inboard of the wheel centre; rotate about local Y to steer (wheel, steering arm and brake go with it) |
| `wheel_front_left` | knuckle_front_left | 1.03, 0.523, 3.78 | wheel: spins about local X |
| `knuckle_front_right` | axle_front | -0.9, 0.523, 3.78 | as above, right side |
| `wheel_front_right` | knuckle_front_right | -1.03, 0.523, 3.78 | wheel: spins about local X |
| `axle_rear1` | root | 0, 0.523, -2.62 | first drive axle (housing, differential, brake chambers); rises and rolls, carries its two dual-wheel nodes |
| `wheel_rear1_left` | axle_rear1 | 0.9475, 0.523, -2.62 | wheel: spins about local X |
| `wheel_rear1_right` | axle_rear1 | -0.9475, 0.523, -2.62 | wheel: spins about local X |
| `axle_rear2` | root | 0, 0.523, -3.94 | second drive axle, same as above |
| `wheel_rear2_left` | axle_rear2 | 0.9475, 0.523, -3.94 | wheel: spins about local X |
| `wheel_rear2_right` | axle_rear2 | -0.9475, 0.523, -3.94 | wheel: spins about local X |
| `link_arm_rear1_left` | root | 0.5, 0.44, -1.84 | rigid link: keep local +Z aimed at `target_arm_rear1_left` |
| `link_arm_rear1_right` | root | -0.5, 0.44, -1.84 | rigid link: keep local +Z aimed at `target_arm_rear1_right` |
| `link_arm_rear2_left` | root | 0.5, 0.44, -3.16 | rigid link: keep local +Z aimed at `target_arm_rear2_left` |
| `link_arm_rear2_right` | root | -0.5, 0.44, -3.16 | rigid link: keep local +Z aimed at `target_arm_rear2_right` |
| `link_bellows_rear1_left_lower` | link_arm_rear1_left | 0.45, 0.49, -2.94 | air spring piston on the trailing arm (the two halves telescope): keep local +Z aimed at `link_bellows_rear1_left_upper` |
| `link_bellows_rear1_left_upper` | root | 0.45, 0.785, -2.94 | air spring bellows on the frame (the two halves telescope): keep local +Z aimed at `link_bellows_rear1_left_lower` |
| `link_bellows_rear1_right_lower` | link_arm_rear1_right | -0.45, 0.49, -2.94 | air spring piston on the trailing arm (the two halves telescope): keep local +Z aimed at `link_bellows_rear1_right_upper` |
| `link_bellows_rear1_right_upper` | root | -0.45, 0.785, -2.94 | air spring bellows on the frame (the two halves telescope): keep local +Z aimed at `link_bellows_rear1_right_lower` |
| `link_bellows_rear2_left_lower` | link_arm_rear2_left | 0.45, 0.49, -4.26 | air spring piston on the trailing arm (the two halves telescope): keep local +Z aimed at `link_bellows_rear2_left_upper` |
| `link_bellows_rear2_left_upper` | root | 0.45, 0.785, -4.26 | air spring bellows on the frame (the two halves telescope): keep local +Z aimed at `link_bellows_rear2_left_lower` |
| `link_bellows_rear2_right_lower` | link_arm_rear2_right | -0.45, 0.49, -4.26 | air spring piston on the trailing arm (the two halves telescope): keep local +Z aimed at `link_bellows_rear2_right_upper` |
| `link_bellows_rear2_right_upper` | root | -0.45, 0.785, -4.26 | air spring bellows on the frame (the two halves telescope): keep local +Z aimed at `link_bellows_rear2_right_lower` |
| `link_drag_link` | pitman_arm | 0.52, 0.72, 4.27 | rigid link: keep local +Z aimed at `target_drag_link` |
| `link_driveshaft` | root | 0, 0.6249, -0.96 | rigid link: keep local +Z aimed at `target_driveshaft` |
| `link_interaxle_shaft` | axle_rear1 | 0, 0.56, -2.84 | rigid link: keep local +Z aimed at `target_interaxle_shaft` |
| `link_shock_front_left_lower` | axle_front | 0.53, 0.543, 3.92 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_front_left_upper` |
| `link_shock_front_left_upper` | root | 0.525, 0.92, 4.02 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_front_left_lower` |
| `link_shock_front_right_lower` | axle_front | -0.53, 0.543, 3.92 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_front_right_upper` |
| `link_shock_front_right_upper` | root | -0.525, 0.92, 4.02 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_front_right_lower` |
| `link_shock_rear1_left_lower` | axle_rear1 | 0.47, 0.47, -2.75 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear1_left_upper` |
| `link_shock_rear1_left_upper` | root | 0.47, 0.8, -2.72 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear1_left_lower` |
| `link_shock_rear1_right_lower` | axle_rear1 | -0.47, 0.47, -2.75 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear1_right_upper` |
| `link_shock_rear1_right_upper` | root | -0.47, 0.8, -2.72 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear1_right_lower` |
| `link_shock_rear2_left_lower` | axle_rear2 | 0.47, 0.47, -4.07 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear2_left_upper` |
| `link_shock_rear2_left_upper` | root | 0.47, 0.8, -4.04 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear2_left_lower` |
| `link_shock_rear2_right_lower` | axle_rear2 | -0.47, 0.47, -4.07 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear2_right_upper` |
| `link_shock_rear2_right_upper` | root | -0.47, 0.8, -4.04 | shock absorber half (the two halves telescope): keep local +Z aimed at `link_shock_rear2_right_lower` |
| `link_spring_front_left_aft` | root | 0.42, 0.771, 3.08 | rigid link: keep local +Z aimed at `target_spring_front_left` |
| `link_spring_front_left_fwd` | root | 0.42, 0.771, 4.48 | rigid link: keep local +Z aimed at `target_spring_front_left` |
| `link_spring_front_right_aft` | root | -0.42, 0.771, 3.08 | rigid link: keep local +Z aimed at `target_spring_front_right` |
| `link_spring_front_right_fwd` | root | -0.42, 0.771, 4.48 | rigid link: keep local +Z aimed at `target_spring_front_right` |
| `link_tie_rod` | knuckle_front_left | 0.8675, 0.443, 3.58 | rigid link: keep local +Z aimed at `target_tie_rod` |
| `link_torque_rod_rear1_left` | root | 0.36, 0.69, -1.92 | rigid link: keep local +Z aimed at `target_torque_rod_rear1_left` |
| `link_torque_rod_rear1_right` | root | -0.36, 0.69, -1.92 | rigid link: keep local +Z aimed at `target_torque_rod_rear1_right` |
| `link_torque_rod_rear2_left` | root | 0.36, 0.69, -3.24 | rigid link: keep local +Z aimed at `target_torque_rod_rear2_left` |
| `link_torque_rod_rear2_right` | root | -0.36, 0.69, -3.24 | rigid link: keep local +Z aimed at `target_torque_rod_rear2_right` |

The tree follows the real running gear: beam axles carry the wheels, the front axle carries steering
knuckles that pivot on the kingpins, and the parts that join a moving axle to the frame (springs, shocks,
trailing arms, torque rods, tie rod, drag link, driveshafts) are separate `link_*` nodes. Wheel, knuckle and
axle nodes have no rotation at rest; each link is rotated so its local +Z points at its target, and the
steering wheel is tilted with its column. To animate it each frame:

1. **Spin:** rotate each `wheel_*` about its local X by distance travelled / wheel radius. Each dual pair on a hub is one node.
2. **Steer:** rotate `knuckle_front_left` / `_right` about local Y by the steer angle (inner wheel more than the outer one;
   Ackermann: cot(outer) - cot(inner) = 1.80 / 7.06). The wheel swings round the kingpin
   as on the real truck. Rotate `pitman_arm` about its local X by -1.12 x the left knuckle's angle.
3. **Suspension:** for each axle, move it up by the average of its two wheels' compression and roll it about
   local Z by atan((left - right) / track). Its wheels (and knuckles) follow.
4. **Links:** turn every `link_*` node so its local +Z points at the node named in its glTF `extras.aim_at`
   (a `target_*` empty on the moving part, or the matching shock or air spring half). Parents before children, so the
   tie rod (a child of the left knuckle) and the inter-axle shaft (a child of the first rear axle) come after
   their parents. Rigid links stay within 24 mm of their length over
   80 mm of travel and 40 degrees of lock; the two halves of each shock and rear air spring telescope.
   **The rigged files need none of this:** there each link is skinned to the two parts it joins and follows them.
   For the node-tree files: Unity, an Aim Constraint per link (aim vector 0, 0, 1; world up 0, 1, 0, but 0, 0, 1 for
   the `link_shock_*` and `link_bellows_*` halves, which point almost straight up). Godot: `look_at(target.global_position, up, true)`
   in `_process` (the third argument makes +Z the front; same up rule as Unity). Blender: a Damped Track
   constraint, track axis -Y (the importer turns glTF's local +Z into Blender's local -Y). three.js: `link.lookAt(targetWorldPosition)` (three.js aims +Z for non-camera
   objects). If you skip this step the links stay at their rest pose: hard to see at small travel, but the
   shocks and driveshaft come off their mounts at full travel.
5. **Steering wheel:** rotate `steering_wheel` about local Z by about 18 times the road-wheel angle (4 to 4.5 turns lock to lock).

Do not let a vehicle system pose the wheel nodes or bones itself (Unity's `GetWorldPose` copied onto the wheel,
Unreal's Wheel Controller node). The wheels are children of the knuckles and axles, so the steer and lift
would be applied twice, and a wheel turned about its own centre cuts into the axle end past about 20 degrees.
Read the steer angle, compression and spin from the vehicle system and apply them as in steps 1 to 3.

### Link targets

Each `target_*` is an empty parented to the moving part a link ends on:

| Target | Parent |
|---|---|
| `target_spring_front_left` | `axle_front` |
| `target_spring_front_right` | `axle_front` |
| `target_drag_link` | `knuckle_front_left` |
| `target_tie_rod` | `knuckle_front_right` |
| `target_arm_rear1_left` | `axle_rear1` |
| `target_torque_rod_rear1_left` | `axle_rear1` |
| `target_arm_rear1_right` | `axle_rear1` |
| `target_torque_rod_rear1_right` | `axle_rear1` |
| `target_driveshaft` | `axle_rear1` |
| `target_arm_rear2_left` | `axle_rear2` |
| `target_torque_rod_rear2_left` | `axle_rear2` |
| `target_arm_rear2_right` | `axle_rear2` |
| `target_torque_rod_rear2_right` | `axle_rear2` |
| `target_interaxle_shaft` | `axle_rear2` |

### Sockets (empty nodes)

| Socket | Position (x, y, z) |
|---|---|
| `center_of_mass` | 0, 1, 0.744 |
| `socket_headlamp_left` | 0.9, 1.174, 4.464 |
| `socket_headlamp_right` | -0.9, 1.174, 4.464 |
| `socket_fifth_wheel` | 0, 1.27, -3.02 |
| `socket_taillamp_left` | 0.68, 0.96, -4.67 |
| `socket_taillamp_right` | -0.68, 0.96, -4.67 |
| `socket_exhaust_left` | 0.8, 3.96, -1.07 |
| `socket_exhaust_right` | -0.8, 3.96, -1.07 |
| `socket_worklamp` | 0, 2.55, -0.91 |

Light and exhaust sockets are oriented so their local **-Z axis points along the beam / exhaust flow**
(the glTF and Godot light convention). In Unity a Light shines along +Z: add it as a child rotated 180
degrees about Y. In Unreal a light shines along +X: rotate it -90 degrees about Z (yaw).
`socket_fifth_wheel` is the trailer coupling point (top of the plate at the kingpin lock).
`center_of_mass` is a suggested centre of mass for vehicle physics (see below).

## Driving it: vehicle data

These are starting points for a bobtail (no trailer) tractor. Values per wheel node.

| Quantity | Value |
|---|---|
| Mass | 9,000 kg (57 % on the steer axle) |
| Centre of mass | 0, 1, 0.744 (node `center_of_mass`) |
| Wheel radius | 0.523 m |
| Wheelbase (steer axle to tandem centre) | 7.06 m |
| Tandem axle spacing | 1.32 m |
| Track, front / rear dual centres | 2.06 m / 1.90 m |
| Static load per wheel node | front 25.2 kN, rear dual pair 9.5 kN |
| Spring rate (1.4 Hz ride) | front 198 kN/m, rear 75 kN/m |
| Damper (about 35 % critical) | front 15.8 kN s/m, rear 6.0 kN s/m |
| Upward travel (jounce) before anything touches | front 70 mm, rear 110 mm |
| Steering lock | real trucks about 40 degrees inner. The model clears 50 inner / 42 outer at ride height, and 40 degrees inner with full suspension travel (170 mm to spare): use 40 as the game's lock |

Measured with `tools/fitcheck.py` on LOD0. Tyres: the wheel's own geometry revolved about its axle and raised
with its axle against everything else. Axles: the axle with its knuckles, links and shocks posed as in the
steps above, raised until any of it meets the frame or body. Steering: both knuckles turned with Ackermann
geometry, pitman arm and links following.

| Wheel | Radius m | Width m | Tyre room upward |
|---|---:|---:|---:|
| `wheel_front_left` | 0.523 | 0.410 | 300 mm |
| `wheel_front_right` | 0.523 | 0.410 | 300 mm |
| `wheel_rear1_left` | 0.523 | 0.635 | 110 mm |
| `wheel_rear1_right` | 0.523 | 0.635 | 110 mm |
| `wheel_rear2_left` | 0.523 | 0.635 | 110 mm |
| `wheel_rear2_right` | 0.523 | 0.635 | 110 mm |

| Axle | Axle travel upward | First part to touch | Usable (axle and its tyres) |
|---|---:|---|---:|
| `axle_front` | 70 mm | `axle_front` | 70 mm |
| `axle_rear1` | 110 mm | `link_bellows_rear1_right_lower` | 110 mm |
| `axle_rear2` | 110 mm | `link_bellows_rear2_left_lower` | 110 mm |

Engine defaults are made for cars and will not hold a 9-tonne truck:

- **Unity** (WheelCollider): Unity has no built-in glTF importer; add the glTFast package
  (`com.unity.cloud.gltfast`), then drop the GLB into Assets. Set the Rigidbody mass to 9000, centre of mass from `center_of_mass`.
  Per collider: radius 0.523, suspension distance 0.14 (front) / 0.22 (rear), target position 0.5,
  spring 198,473 (front) / 74,863 (rear) N/m, damper 15,794 / 5,957 N s/m, wheel mass 120 (front) / 240 (dual pair).
  Place each collider at its wheel node's centre raised by 0.070 m (front) / 0.110 m (rear): the wheel
  rests at the target position, half the suspension distance below the collider, which puts it back on the node.
  Each frame read the collider's `steerAngle`, its compression (from `GetGroundHit` or the world pose height,
  minus the rest height) and the spin (`rpm`), and apply them as in steps 1 to 3; do not copy `GetWorldPose`
  onto the wheel nodes.
- **Unreal Engine 5** (Chaos Wheeled Vehicle): import `ravenhall_tractor_rigged.glb` (tick Use Full Precision
  UVs: some tiling textures run past the range 16-bit UVs hold exactly). Bones are named like the nodes above.
  In the generated Physics Asset keep one body on `root` and delete any bodies on wheel, knuckle and axle bones.
  In the Animation Blueprint do not use the Wheel Controller node (it moves the wheel bones, which already
  follow the knuckles and axles). Instead read each wheel's `GetSteerAngle`, `GetSuspensionOffset` and
  `GetRotationAngle` from the vehicle movement component and apply them with Transform (Modify) Bone nodes:
  steer to the knuckle bones (local Y in glTF terms), offset and roll to the axle bones, spin only to the wheel
  bones. The links are skinned and follow by themselves.
  Wheel radius 52.3 cm, width 30 cm (front) / 66 cm (rear dual pair),
  suspension max raise 7 cm front / 11 cm rear, max drop 10 cm. Mass 9000 kg.
- **Godot 4** (VehicleBody3D): mass 9000, center_of_mass_mode custom from `center_of_mass`. Godot's
  suspension force is stiffness x compression x body mass, so each axle needs its own stiffness. Per
  VehicleWheel3D: wheel_radius 0.523, wheel_rest_length 0.15, suspension_travel 0.15,
  suspension_stiffness 40 (front) / 15 (rear), damping_compression 2.4 / 0.9,
  damping_relaxation 3.3 / 1.2, suspension_max_force 60000 / 30000 (the default 6000
  cannot hold this truck up). Both axles then sag 70 mm under load, so place each VehicleWheel3D at its wheel
  node's centre raised by 0.08 m. Keep the visual nodes where they are and drive them from the wheels'
  rotation, steering and suspension values as in steps 1 to 3. The raycast wheel can drop the full
  suspension_travel below rest and rise by up to it, more than the model has room for: clamp the offset you
  give the axles to between -0.10 m and +0.070 m (front) / +0.110 m (rear).
- **Blender**: File > Import > glTF 2.0. The hierarchy, pivots and materials come in as they are. Blender is
  Z-up, so every local axis named in these notes changes: glTF local +Y is Blender local +Z, and glTF local +Z is
  Blender local -Y (steer the knuckles about local Z, spin the steering wheel about local -Y, aim links with -Y).
- **three.js**: load the GLB; nodes are found by name (`getObjectByName('wheel_front_left')`). The web file needs
  a meshopt decoder (see Files). Use the GLB, not the OBJ: three.js's MTLLoader reads `map_Bump` as a height map.
- **Babylon.js**: `SceneLoader.ImportMeshAsync('', path, 'ravenhall_tractor.glb', scene)`; nodes by
  `scene.getTransformNodeByName(...)`. The loader adds a `__root__` node that converts to Babylon's left-handed
  space: animate the named nodes' local transforms (the axes in these notes) and leave `__root__` alone.

## Lights

Lamps ship switched off (no emissive), so the truck looks right in daylight. Each light function has its
own material, in every LOD including LOD3, so switching one on is one emissive change.

Two material variants (`KHR_materials_variants`) hold the switched-on looks: `lights_running` (headlamps,
running strip, tails, markers; stop/turn lamps at tail strength) and `lights_all` (every lamp at full).
Blender (glTF Variants panel) and model-viewer (`variant-name`) switch them with no code; three.js, Babylon.js
and Unity glTFast read the extension and switch through their APIs (a few lines). Elsewhere swap materials by
name: each lamp material `<name>` has `<name>_on` and `<name>_running` twins in the file. The switched-on values
are also stored in each light material's glTF `extras` (`emissive_on`, linear RGB, and `emissive_strength_on`,
for `KHR_materials_emissive_strength`; engine units vary, so treat them as relative). Use a material instance
per truck so one truck's brake lights do not light every copy.

| Material | Lamps | Emissive colour (linear) | Strength |
|---|---|---|---|
| `ravenhall_light_headlamp` | headlamp bulbs (low/high) | 1, 0.93, 0.82 | 40 |
| `ravenhall_light_drl` | daytime running strip above the headlamps | 1, 0.95, 0.88 | 10 |
| `ravenhall_light_turn_left` | front left turn signal (amber) | 1, 0.35, 0 | 12, blink 1.5 Hz |
| `ravenhall_light_turn_right` | front right turn signal (amber) | 1, 0.35, 0 | 12, blink 1.5 Hz |
| `ravenhall_light_stop_turn_left` | rear left stop / turn (red, outer) | 1, 0.02, 0.01 | tail 2, stop 10, blink 1.5 Hz |
| `ravenhall_light_stop_turn_right` | rear right stop / turn (red, outer) | 1, 0.02, 0.01 | tail 2, stop 10, blink 1.5 Hz |
| `ravenhall_light_tail` | rear tail lamps (red, inner) | 1, 0.02, 0.01 | 3 |
| `ravenhall_light_reverse` | reverse lamps (white) | 1, 1, 1 | 12 |
| `ravenhall_light_marker_amber` | cab, visor, bumper, sleeper and fender marker lamps | 1, 0.35, 0 | 4 |
| `ravenhall_light_marker_red` | rear marker and ID lamps | 1, 0.02, 0.01 | 4 |
| `ravenhall_light_work` | work lamp on the sleeper back, aimed at the deck | 1, 0.97, 0.92 | 25 |

## Materials

Flat-colour parts (chrome, stainless, rubber, chassis black, plastics, interior and so on) share one
material, `ravenhall_palette`: a 128 x 128 base colour texture plus a matching metal/rough texture, with one
8 x 8 texel block per finish and the parts' UVs at the centre of their block. That keeps the body at a
handful of draw calls. Textured parts keep their own materials. LOD1 uses the same palette; LOD2
(`ravenhall_palette_lod2`) and LOD3 (`ravenhall_palette_lod3`) fold more parts in and have their own, so
material remapping by name never mixes them up.

Ambient occlusion is baked per vertex into `COLOR_0` on the chassis, running gear, trim and wheels (not on
the painted panels). three.js, Babylon.js, Unity glTFast and Godot multiply it into the base colour
automatically. In Unreal, multiply Vertex Color into Base Color in the material; Blender imports it as a
colour attribute you can multiply in the same way. Wheels carry only their own occlusion, so it stays right
while they spin and steer.

| Material | Triangles (LOD0) | Textures | Notes |
|---|---:|---|---|
| `ravenhall_brushed_aluminium` | 819 | normalMap,roughnessMap | opaque |
| `ravenhall_conspicuity_tape` | 6 | map | opaque, two-sided |
| `ravenhall_diamond_plate` | 104 | normalMap | opaque |
| `ravenhall_door_decal` | 4 | map,roughnessMap | mask, two-sided, clearcoat |
| `ravenhall_emblem` | 6 | map,roughnessMap | mask, two-sided, clearcoat |
| `ravenhall_heat_shield` | 244 | map | mask, two-sided |
| `ravenhall_mudflap` | 4 | map | opaque, two-sided |
| `ravenhall_paint_candy_red` | 9,427 | - | opaque, clearcoat |
| `ravenhall_palette` | 190,065 | map,roughnessMap | opaque |
| `ravenhall_plate` | 2 | map | opaque, two-sided |
| `ravenhall_radiator_core` | 16 | map,normalMap | opaque |
| `ravenhall_tape_white` | 8 | - | opaque, two-sided |
| `ravenhall_glass` | 77 | - | blend 0.3, two-sided |
| `ravenhall_lens_clear` | 110 | - | blend 0.25, two-sided |
| `ravenhall_tire` | 24,183 | map,normalMap | opaque |

Palette finishes (base colour sRGB, metalness, roughness):

| Finish | Colour | Metal | Rough |
|---|---|---:|---:|
| shut_line | #020202 | 0 | 0.9 |
| chrome | #c6c8ca | 1 | 0.03 |
| radiator | #1e1f21 | 0 | 0.55 |
| rubber | #242424 | 0 | 0.86 |
| chassis_black | #1a1a1c | 0 | 0.32 |
| reflector | #c8cacc | 1 | 0.05 |
| black_plastic | #1e1e20 | 0 | 0.5 |
| tread | #1e1e1e | 0 | 0.9 |
| wheel_aluminium | #e8e9ea | 1 | 0.05 |
| gunmetal | #2a2b2d | 0 | 0.4 |
| stainless | #d2d6da | 1 | 0.16 |
| airbag | #222222 | 0 | 0.8 |
| fifth_wheel | #161411 | 0 | 0.18 |
| pinstripe_gold | #c9973c | 0 | 0.3 |
| interior | #4a4541 | 0 | 0.85 |
| interior_trim | #2e2b28 | 0 | 0.7 |
| seat_leather | #553e2e | 0 | 0.55 |
| curtain | #34322f | 0 | 0.95 |
| mirror_glass | #d0d2d4 | 1 | 0.02 |
| soot | #050505 | 0 | 1 |
| polished_aluminium | #e6e8ea | 1 | 0.11 |
| def_tank | #d8d8d2 | 0 | 0.6 |
| def_cap | #1c4fb8 | 0 | 0.45 |
| coil_line_red | #c41a1a | 0 | 0.32 |
| tag_red | #a01414 | 0 | 0.45 |
| coil_line_blue | #1d4fbf | 0 | 0.32 |
| tag_blue | #14307f | 0 | 0.45 |
| coil_line_green | #2a6e2a | 0 | 0.32 |

The paint is a deep red base under a clear coat (`KHR_materials_clearcoat`). The base's own reflection is
turned down with `KHR_materials_specular`, since on real paint it sits under the clear layer. Engines that
read neither extension (some Unity pipelines, Godot) get the base alone, which is glossy on its own
(roughness 0.22). The paint has no normal maps. Normal maps elsewhere use the OpenGL /
glTF convention (green up). Glass is alpha-blended with no transmission extension, so it renders the same
everywhere. All textures are power-of-two. No tangents are stored: Unity, Unreal, Godot and Blender generate
MikkTSpace tangents on import, and three.js and Babylon.js build a tangent frame in the shader. The normal maps
here are procedural detail, not bakes that depend on one basis, so either way is correct.
The brushed aluminium falls back to plain metal where `KHR_materials_anisotropy` is not supported.

## Collision

`ravenhall_tractor_collision.glb` holds four convex hulls (`collision_cab`, `collision_sleeper`,
`collision_hood`, `collision_chassis`), each at most 250 triangles (inside Unity's 255-triangle convex limit),
plus a box round each mirror head (`collision_mirror_*`), in the same space as the model. They import as
ordinary meshes: hide or remove their renderers once they are colliders. Behind the sleeper nothing in the hulls stands above the fifth wheel plate,
so a coupled trailer does not overlap them (the exhaust stacks are left out of the hulls). Use them as convex colliders: Unity MeshCollider with Convex on, Unreal
simple collision (or rename to `UCX_<mesh>_00` before an FBX round trip), Godot ConvexPolygonShape3D (or add
the `-convcolonly` suffix to the node names before import). For a driven vehicle, wheels are handled by the
vehicle system, so do not add the wheel cylinders from `ravenhall_tractor_collision_wheels.glb`.

## Notes and limits

- No FBX is included. To make one: import the GLB in Blender and export FBX (Apply Transform off,
  Forward -Z, Up Y, "Add Leaf Bones" off for the rigged file).
- No animations are included on purpose: wheel spin, steering and suspension are driven by the game,
  and the node tree above is set up for that.
- The cab interior is a simple shell with seats, dash and steering wheel, made to look right through the
  windows, not for a first-person cockpit camera.
- No dirt or wear is baked in, so you can weather it to suit your game.
- Made procedurally with three.js, exported with three.js GLTFExporter, simplified with meshoptimizer,
  validated with the Khronos glTF Validator. Textures are procedural or generated for this model.
