Jolt driving

Target: Three.js 0.187.0 (three for the maths; the kit draws nothing) and jolt-physics 1.0.0, the wasm-compat build. Three companion files sit in this folder. Copy them into the project. They import only three, and the caller passes in the Jolt namespace it initialised:

• scripts/jolt-world.js: createJoltWorld(Jolt, options) and createHeightfieldRing(world, samplesFor, options)
• scripts/jolt-vehicle.js: class WheeledVehicle, VEHICLE_DEFAULTS, SURFACES
• scripts/jolt-towing.js: class TowHitch, TRAILER_DEFAULTS

What it is

A four-wheel vehicle driven by Jolt's own VehicleConstraint and WheeledVehicleController. Jolt solves suspension, tyre slip, weight transfer and the drivetrain. On top sits a thin handling layer, and every constant in it was settled by driving tests. It covers steering smoothing and taper, a brake pedal that reverses once the vehicle has stopped, a holding brake with hysteresis, a park pin that puts the body to sleep, friction curves per surface, a handbrake slide, extra gravity in the air, water buoyancy and drag, and a fell-through net. Around the vehicle the kit has a world with two layers, heightfield colliders only in the 3x3 chunks around the vehicle, a mesh-shape queue, body retirement on a budget, and ray casts that cannot hang. A trailer couples to it with a swing-twist joint.

When to use

• Driving games and simulations where the car should feel physical (suspension, body roll, grip loss), not arcade-on-rails.
• Large streamed terrain: colliders follow the vehicle, and the rest of the world has none.
• Use something else for a kinematic or arcade car with no real physics, for a pure flight model, or for tracked vehicles (Jolt has a TrackedVehicleController, but this kit does not cover it).

API

createJoltWorld(Jolt, options) (defaults in WORLD_DEFAULTS)

Returns { Jolt, jolt, physicsSystem, bodyInterface, layers: { NON_MOVING, MOVING }, fixedDt, step, ... }.

• step(frameDt, beforeEachStep): runs the fixed-step accumulator. beforeEachStep(dt) runs before every jolt.Step. Vehicle and trailer updates go there, never once per frame. Returns alpha for pose blending.
• createDynamicShape(shape, { position, rotation, mass, friction, restitution, angularDamping, allowSleeping, activate }): mass is overridden and inertia is calculated from the shape.
• createDynamicBox({ x, y, z, hx, hy, hz, mass, rotation?, friction = 0.8 }) and createDynamicCylinder({ x, y, z, halfHeight, radius, mass, rotation?, friction = 0.6 }): props. They are created asleep and contacts wake them.
• createStaticBox({ x, y, z, hx, hy, hz, rotation? }): uses an LRU box-shape cache.
• createStaticCompound(boxes, ox, oz): one body for a chunk's prop boxes, in a frame at (ox, 0, oz). Returns null on failure; then call createStaticBox per box.
• createStaticMeshQueued({ key, positions, indices, x, y, z, rotation?, isCancelled? }) returns a Promise of a Body. pumpMeshQueue(perFrame = 1) builds that many new shapes per call. Cached keys resolve at once. A cancelled request resolves null.
• createHeightfieldChunk({ x, z, size, cells, heights }): heights is a Float32Array of (cells+1)^2 world heights, row-major (i along +x, j along +z). It covers [x, x+size] x [z, z+size]. It throws on a wrong length or on a non-finite or out-of-range sample.
• removeBody(body) removes and destroys a body now. retireBody(body) queues it, and pumpRetired(n = 64) destroys n per call.
• castRay(from, dir, maxDist, { ignoreBody }) returns { fraction, distance, point, bodyId } or null. Non-finite rays and rays longer than maxRayLength are refused.
• boxShape(hx, hy, hz) and compoundShape(boxes, spheres, com) build shapes. They are used by the vehicle and the trailer.

createHeightfieldRing(world, samplesFor, options) (RING_DEFAULTS)

samplesFor(cx, cz) returns { heights, cells }, or null while that chunk is not ready. Chunk (cx, cz) covers [cx*size, (cx+1)*size]. The ring has these methods:

• update(x, z) (per frame): builds the chunk under the point at once, then the nearest missing chunks within radius (buildsPerFrame per call). It retires chunks beyond keepRadius.
• ensure(x, z) builds the chunk under a point now and returns true if a collider is there. has(x, z) only checks.
• remove(cx, cz) and dispose().

new WheeledVehicle(world, options) (VEHICLE_DEFAULTS)

• update(dt, input, env): call once per fixed step, inside beforeEachStep.
  • input is { throttle 0..1, brake 0..1, steer -1..1 (+1 = right), handbrake bool, reverse bool }.
  • env is { surfaceAt(x, z) -> surface name, waterLevelAt(x, z) -> y | null, groundContact bool, heightAt?, wetness 0..1 }.
  • groundContact says whether the collider under the vehicle exists (ring.ensure(x, z)). When it is false, the chassis is held on heightAt instead of falling.
• Getters: speed (horizontal m/s), speedKmh, fwdSpeed (signed along the heading, updated each step), pose ({ position, quaternion, yaw }), airborne, inWater, braking, reversing, wheelContacts[i] ({ x, y, z, grounded, surface }), renderFwd (the blended heading: use it as a chase camera's yaw source).
• applyPoseTo(object3D, wheels, alpha): call once per render frame. It sets the object's blended pose. Each wheel Object3D must be hub-centred with its axle along x. It is placed at the mount minus the suspension length, steered and spun.
• modelTransform(rawHalfWheelbase, rawAxleMidZ) returns { scale, position } for a body model hung under the posed object. The scale comes from the wheelbase and the offset puts the model at rest height.
• reset(position, yaw): upright and still. A missing position.y means heightAt + ride. flip() sets it upright in place with its heading kept. place(position, quaternion) and hold(y) are also available.
• fitChassisBox(hx, zMin, zMax) refits the collider to another body shell. towing is set by the hitch. dispose().

new TowHitch(world, tractor, trailerOptions) (TRAILER_DEFAULTS)

• place(x, z, yaw, heightAt). canAttach() and attach(), canDetach() and detach().
• update(dt, { groundSolidAt(x, z) }): once per fixed step, after the tractor's update.
• applyPoseTo(object3D, wheels, alpha): wheels is either one axle pivot or one object per wheel, as children of object3D.
• save() returns { x, y, z, qx, qy, qz, qw, attached }. restore(state, heightAt) re-attaches by itself once it can. dispose().

Usage

import initJolt from 'jolt-physics/wasm-compat';
import * as THREE from 'three/webgpu';
import { createJoltWorld, createHeightfieldRing } from './jolt-world.js';
import { WheeledVehicle } from './jolt-vehicle.js';
import { TowHitch } from './jolt-towing.js';

const Jolt = await initJolt();
const world = createJoltWorld(Jolt);
const SIZE = 256, CELLS = 256;                      // collider grid = an exact subdivision of the visual grid
const ring = createHeightfieldRing(world, (cx, cz) => terrain.samples(cx, cz, CELLS), { chunkSize: SIZE });
const heightAt = (x, z) => terrain.height(x, z);    // the same surface the heightfield samples

ring.ensure(0, 0);                                  // solid ground before the vehicle exists
const car = new WheeledVehicle(world, { spawn: { x: 0, z: 0 }, heightAt });
const tow = new TowHitch(world, car, { mass: 300 });
tow.place(0, -6, 0, heightAt);

const chassis = new THREE.Group(); scene.add(chassis);
const { scale, position } = car.modelTransform(0.84, 0.24);
bodyModel.scale.setScalar(scale); bodyModel.position.copy(position); chassis.add(bodyModel);
const env = { heightAt, surfaceAt: (x, z) => terrain.surface(x, z), waterLevelAt: (x, z) => lakes.level(x, z), groundContact: true, wetness: 0 };

function frame(dt) {
  const p = car.pose.position;
  ring.update(p.x, p.z);
  env.groundContact = ring.ensure(p.x, p.z);
  world.pumpRetired(); world.pumpMeshQueue(1);
  const input = { throttle: keys.w ? 1 : 0, brake: keys.s ? 1 : 0, steer: (keys.d ? 1 : 0) - (keys.a ? 1 : 0), handbrake: keys.space };
  const alpha = world.step(dt, (h) => { car.update(h, input, env); tow.update(h, { groundSolidAt: (x, z) => ring.has(x, z) }); });
  car.applyPoseTo(chassis, wheelMeshes, alpha);
  tow.applyPoseTo(trailerGroup, [trailerAxle], alpha);
}
// E key: tow.attached ? (tow.canDetach() && tow.detach()) : tow.attach();

Wheel meshes must be scene-level objects, not children of chassis. applyPoseTo writes world poses. Trailer wheels are the opposite: they are children of the trailer group, posed in its local frame.

How it works

• Chassis. The collider is a box whose bottom is lifted by bodyLift; the top does not move. It is wrapped in OffsetCenterOfMassShapeSettings that drops the COM by comDrop. A box's own COM sits at axle height, far too high. The drop is the main anti-roll-over lever and does not change grip. In the measured test, full lock at full throttle peaked at 60 deg of tilt without it and 14 deg with it. The body never sleeps by itself (mAllowSleeping false); the park pin puts it to sleep explicitly.
• Constraint. Each wheel is a WheelSettingsWV: suspension straight down, the spring in frequency mode, its steer angle only if steerable, and handbrake torque only on the rear wheels. The transmission is ETransmissionMode_Auto with ONE forward ratio and one reverse ratio, so it never shifts and the torque curve stays flat. Two differentials at 0.5 each make it 4WD, and there are front and rear anti-roll bars. The collision tester is VehicleCollisionTesterCastSphere (radius = half the wheel radius). Then come AddConstraint, AddStepListener(new VehicleConstraintStepListener(c)), and castObject(GetController(), WheeledVehicleController) for SetDriverInput(forward, right, brake, handBrake).
• Top speed is set by the drivetrain: wheel speed at max RPM = maxRPM x 2 pi / 60 / (gear x differential ratio, 3.42 by Jolt default) x radius, about 28 m/s here. Headless test: 0 to 89 km/h in 6 s and 102 km/h flat out. topSpeed (38 m/s) is the reference for the steering taper. Past it, the arcade drag bleeds the excess. It only engages downhill or with a stronger engine.

• Friction per surface. mLongitudinalFriction and mLateralFriction are LinearCurves (slip to friction), not scalars. The kit rebuilds them from Jolt's default points with Y scaled by the surface factors:

  • longitudinal: (0, 0), (0.06, 1.2), (0.2, 1.0) over slip ratio
  • lateral: (0, 0), (3, 1.2), (20, 1.0) over slip angle in degrees

  The friction is rewritten only when a wheel's key changes. The key is surface + wetness quarter + handbrake slide.

• Pedals. Throttle drives forward. Brake brakes while fwdSpeed > 0.3. Once stopped, a FRESH brake press reverses: releasing the pedal re-arms reverse, so holding the brake keeps the car stopped. reverse: true turns the throttle into a reverse throttle. With no pedal pressed, the holding brake engages below 0.5 m/s and releases above 1.0 m/s.
• Per step, in order:
  1. Hold the chassis if no collider is under it.
  2. Fell-through net: more than 2 m under heightAt means it is re-seated.
  3. Steering taper.
  4. Water impulses.
  5. Wheel contacts and friction keys.
  6. Driver input.
  7. Gravity factor, changed only when the airborne state changes.
  8. Handbrake assist.
  9. Top-speed drag.
  10. Park pin: zero the horizontal speed, keep only a downward settle (all of vy while towing), sleep below 0.05 m/s.
  11. Activation, only while something asks it to move.
  12. Visual wheel spin, integrated.
• Render blend. Each step stores the previous pose, spin, suspension and steer. applyPoseTo blends previous to current by alpha. Each stepped channel is blended; showing any one raw causes a hitch on frames that get 0 or 2 steps.
• Heightfields. HeightFieldShapeSettings takes mOffset (chunk corner), mScale (cell, 1, cell) and mSampleCount N. The samples are written straight into the WASM heap with new Float32Array(Jolt.HEAPF32.buffer, Jolt.getPointer(hf.mHeightSamples.data()), N*N).set(heights). The body is static on the non-moving layer with friction 1.0. Every temporary is destroyed.

Tuning: vehicle (VEHICLE_DEFAULTS)

Surfaces (SURFACES, long / lat / share of wetness): snow 1.00 / 1.00 / 0.5 (the tuned baseline), asphalt 1.05 / 1.18 / 1, wetAsphalt 0.735 / 0.73 / 0, ice 0.25 / 0.35 / 0. These four were tuned by driving. Gravel 0.95 / 0.85, dirt 0.92 / 0.90 and grass 0.80 / 0.80 (wetness 0.5) are interpolated and still need a driving test. Add entries through options.surfaces.

Tuning: world, ring, trailer

Pitfalls (each one cost a session)

• Destroy every WASM temporary (settings, Vec3, Quat, RVec3, BodyCreationSettings) after the body exists. Leaked per-chunk heightfield settings ran the Jolt heap out of memory (Aborted OOM) after minutes of streaming.
• NaN rays hang the tab. A ray built from a NaN or absurd camera position in the first boot frames sent Jolt's tree walk into an endless loop. castRay checks that the ray is finite and shorter than the length cap. Do the same for mesh vertices and indices before MeshShapeSettings, and for heightfield samples.
• MeshShapeSettings needs three arguments (VertexList, IndexedTriangleList, PhysicsMaterialList). Two arguments resolve to another overload and crash with "table index out of bounds". Check result.HasError().
• Cached shapes need their own AddRef(). The ShapeResult slot is overwritten by the next Create(). Without the ref, the shape dies with its first body and leaves a dangling pointer.
• Friction is a curve. ws.mLateralFriction = 0.5 silently does nothing. jw.GetSettings() returns the base class, so castObject it to WheelSettingsWV; that object mutates the live wheel.
• Do not detect contact with your own ground ray. Its threshold disagrees with Jolt's suspension travel and flips the air-gravity state every step, which becomes a limit cycle. Use GetWheel(i).HasContact().
• Cast a sphere for the wheels. A cylinder catches heightfield triangle edges (bounce, rocking). A ray has no width, so it drops into gaps and cannot climb kerbs.
• Heightfield sampling must match the visual surface. Make the collider grid an EXACT subdivision of the render mesh's grid, so triangle edges land on its bilinear kink lines; otherwise the collider bulges above the visible ground. The samples must include anything the wheels ride on (a road platform on an embankment). Bare terrain under an analytic road buried the wheels by up to 0.13 m on one shoulder.
• Concave terrain features must stay wider than 3-4 cells (12-16 m at a 4 m grid). Narrower gullies become vehicle traps for the mesh and the collider alike.
• A clamp on velocity is a ratchet. Keeping only the downward part of vy in the park pin lets the suspension sink but never rebound. Alone it never shows, because the body sleeps a moment later. With a trailer hitched, the joint wakes the tractor every step, and the drawbar load pushed the rear suspension down at a CONSTANT speed: 0.669 to 0.406 m in 13 s with 1100 kg, 2 mm/s with 300 kg. Fix: towing leaves vy alone, and the trailer sleeps WITH the tractor. LESSON: a slow constant-speed creep means something is clamping a velocity, not applying a force.
• Activate only on demand. Calling ActivateBody every step means a parked car never quiesces. The pin calls DeactivateBody itself.
• Teleports. After SetPositionAndRotation, reset the blend history (place does), or one frame renders the car halfway along the jump. Detach or move a trailer first. The teleport guard detaches it, but only on the next update.
• Spawn order. Build the collider under the spawn (ring.ensure) before the first step. Hold the vehicle on heightAt (groundContact: false) whenever the collider under it is missing, and keep a detached trailer asleep where groundSolidAt is false.
• slerpQuaternions(a, b) is copy(a).slerp(b). If the destination is b, nothing happens. Use a separate scratch quaternion.
• Steer sign. SetDriverInput's second argument is "right". With +Z forward and +Y up, right is -X, so a steered visual wheel turns by rotateY(-angle).
• SetShape frees the old shape. Build a fresh shape for each swap (trailer jockey on/off). Never hand back one you have already let go of.
• Trailer springs: use ESpringMode_StiffnessAndDamping. Frequency mode sizes the spring from the effective mass at the wheel, which on a light trailer is mostly roll inertia (about 66 kg for a 300 kg trailer), and the trailer sat on its bump stops.

Towing in short

The joint is a SwingTwistConstraintSettings in EConstraintSpace_WorldSpace at the ball. It is created after sliding the trailer the last centimetres onto the ball. Each body's twist axis is its OWN up and its plane axis its own forward, so zero means straight behind, whatever angle they coupled at. Twist covers +-70 deg of yaw; the normal and plane cones cover +-25 deg of pitch and roll. While hitched, the jockey sphere leaves the compound and the parking brake is released. constraint: { type: 'point' } swaps in a PointConstraintSettings (no limits; the bodies' own collision is the only jackknife stop). A drop hitch is a visual matter: hang the ball mesh on the TRACTOR at the joint. If it hangs on the trailer, its tube swings out from under the tractor in every turn. Saving: save() goes into the game save. restore() holds the trailer asleep until its ground is solid, then keeps trying attach() for 25 s of steps. Time that window from the first update, not from module load, or it expires during boot.

Performance

• Per vehicle and step: 4 wheel reads, at most 4 friction rewrites (only on a key change), a few impulses. The cost is Jolt's.
• Heightfield creation is the expensive call: about 3.8 ms per 257^2 chunk when the samples are baked elsewhere. Bake samples in a worker (a transferable Float32Array) and only copy them on the main thread. Sampling on the main thread with a road overlay cost 20-54 ms per chunk. Build at most one heightfield per frame and let the chunk under the vehicle jump the queue (ensure). A 5x5 ring instead of the 3x3 costs 25 bodies instead of 9, and the outer ring is never driven on.
• One compound per chunk for its static props instead of hundreds of boxes. Dynamic props are cheap only while asleep; the source capped them at 28 new bodies per frame, in the 3x3 only.
• Mesh shapes: a building site's 13 first-time mesh shapes built in one frame cost 67 ms. With pumpMeshQueue(1), they build on consecutive frames.
• Never destroy a ring's worth of bodies in one frame: retireBody plus pumpRetired(64). Stale colliders 2 chunks out are harmless.