Wheels and vehicles

Two components. wheel, on a child entity of a dynamic body, is one raycast wheel: a spring, a damper and a tyre pushing that body. vehicle, on the body, composes the wheels under it into a drivable car (or van, or kart) that the input actions drive with no script. A wheel with no vehicle over it is driven by a behaviour through ctx.wheel — a cart, a trailer, a robot on wheels. This file is the one place their units, axes and sign conventions are written down; if a comment elsewhere disagrees with it, this file is right.

---

0. A car from primitives

A box for the body with the vehicle component on it, and four child entities, each a cylinder mesh with a wheel component:

{ "id": "car", "name": "car", "tags": ["player"], "transform": { "position": [0, 0.05, 0], "rotation": [0, 0, 0, 1], "scale": [1, 1, 1] },
  "components": [
    { "type": "mesh", "asset": "cube" },
    { "type": "collider", "shape": "box", "size": [1.8, 1.45, 4.7], "center": [0, 0.87, 0] },
    { "type": "rigidbody", "kind": "dynamic" },
    { "type": "vehicle", "preset": "sedan" }
  ] },
{ "id": "car-wheel-fl", "name": "car-wheel-fl", "tags": [], "parent": "car",
  "transform": { "position": [-0.775, 0.32, -1.4], "rotation": [0, 0, 0.7071, 0.7071], "scale": [0.64, 0.22, 0.64] },
  "components": [{ "type": "mesh", "asset": "cylinder" }, { "type": "wheel" }] }

(and the same for car-wheel-fr at [0.775, 0.32, -1.4], car-wheel-rl and car-wheel-rr at z = 1.4), with "cube" and "cylinder" declared in assets as { "kind": "glb", "path": "builtin:cube" } and builtin:cylinder. The built-in cylinder is 0.5 m in radius and 1 m tall along Y, so a wheel of radius 0.32 and width 0.22 is scale [0.64, 0.22, 0.64] turned 90° about Z. What that gets you:

• The wheel entity is the wheel. Its position is where the wheel's centre sits at rest, and the way its -Z points (after its rotation) is the way it rolls; its own scale is only its mesh's. The vehicle finds every wheel below its body, in scene order; list them in the vehicle's wheels only to choose an order or a subset.
• It drives with no script. Every tick the engine reads the input actions throttle, brake, steer and handbrake — from the keyboard, a pad, or POST /input — so declare them in meta.input: throttle and brake as buttons (or axis1), steer as one axis1 (["A", "D", "Left", "Right"]). steer +1 (D) turns right. brake held at a standstill reverses. An action the active context does not bind reads 0 — while a menu owns input, the car sits still.
• The wheel entities are drawn where the simulation has the wheels: moved with the suspension, turned by the steering and spun about their own axle as the car rolls, on top of the rotation you gave them. A wheel modelled in parts beside an empty mount names them in its visuals (§2).
• The preset sets everything else — mass, the wheels' size, springs and roles, engine, brakes, tyres, steering lock. sedan, suv, pickup, van (§3). The preset's wheel on the same corner fills each wheel (§3); a field on the wheel component wins. The box above is the one the sedan preset was tuned against. Override any vehicle field: "steering": { "maxAngle": 0.5 }, "chassis": { "mass": 1300 }.
• The chassis mass is the vehicle's, whatever the rigidbody's mass says: the springs and the drive are tuned against it.
• It is the player if the scene names no spawn { for: "player" } and has no controller: device input and an entity-less POST /input go to it.
• A chase camera is the engine's own third-person rig, from the game's behaviour: ctx.camera.follow(ctx.entity) and ctx.camera.set("third-person", { distance: 7, pitch: -0.25, eyeHeight: 1.2, recenterDelay: 0, lookAhead: 0.3 }). recenterDelay: 0 swings the view back behind the car as it turns.
• A behaviour reads it through ctx.vehicle (speed, steer, gear, wheelsOnGround; §6), and a tester through GET /entities?fields=vehicle (§7).

To drive it from a script instead — an AI car, a cutscene — set "input": "script" and call ctx.vehicle.drive({ throttle, brake, steer }) (§6).

A cart from bare wheels

Leave the vehicle off and give each wheel a radius: the wheels hold the body up on their springs, and a behaviour drives them.

{ "id": "cart", "name": "cart", "tags": [], "transform": { "position": [0, 0, 0], "rotation": [0, 0, 0, 1], "scale": [1, 1, 1] },
  "components": [
    { "type": "collider", "shape": "box", "size": [1, 0.3, 1.6], "center": [0, 0.5, 0] },
    { "type": "rigidbody", "kind": "dynamic", "mass": 200 },
    { "type": "script", "module": "cart" }
  ] },
{ "id": "front-left", "name": "front-left", "tags": [], "parent": "cart",
  "transform": { "position": [-0.5, 0.25, -0.6], "rotation": [0, 0, 0, 1], "scale": [1, 1, 1] },
  "components": [{ "type": "wheel", "radius": 0.25 }] }

update(ctx) {
  for (const w of ctx.body!.wheels) {
    w.setMotorTorque(40)                                       // N·m, held until the next call
    if (w.entity.id.startsWith("front-")) w.setSteer(0.1)      // radians, positive right
  }
}

A trailer is the same thing on a joint to the car that pulls it.

---

1. Units, axes and signs

SI throughout. Metres, kilograms, seconds, newtons, newton-metres, radians, radians per second. No degrees, no millimetres, no pounds.

The two exceptions are both at a boundary, and both are deliberate:

• Engine speed is rpm where a person or an agent writes or reads it — the torque curve, idleRpm, redlineRpm, telemetry. Inside the solver it is rad/s. Nothing in between.
• Slip angle is radians, not degrees, even though degrees are what tyre data sheets use. peakSlipAngle: 0.15 is about 8.6°.

Axes. Right-handed, Y up, -Z forward, +X right: the engine's own convention (docs/CONVENTIONS.md), the way a camera, a controller and lookAt all face. A car's front wheels are at negative z.

Signs.

The one that gets got wrong twice

A wheel entity's position is the wheel's CENTRE AT REST — the suspension sitting at restLength — composed through any entities between it and its body (an axle entity is fine), in the body's frame, in metres, before the body's scale, exactly like a collider's center.

It is not the suspension's attachment point. The solver derives that itself as position + up * suspension.restLength. This spelling was chosen because it is what a model file hands you (the wheel node's translation) and what an author sees in a DCC tool.

A wheel rolls along its composed -Z, flattened onto the body's floor. A cylinder turned 90° about Z to lie on its side still rolls along -Z; a wheel turned about Y rolls that way, and its steering adds to that.

Where the origin sits

Every preset is written assuming the entity origin is at ground level — a base-centred asset, which is what the importer produces with baseCenter: true. Two useful consequences follow, and the validation rules lean on both:

• A wheel's position.y is exactly its radius.
• The chassis collider's own min.y is the vehicle's ground clearance.

You do not have to author this way. If you do not, the geometric rules still work — they compare wheels against the collider, not against zero — but the numbers stop being readable at a glance.

---

2. The component

{
  "type": "vehicle",
  "preset": "suv",
  "chassis": { "mass": 2400 }
}

Name a preset and override what differs, or write every part out. A component with neither is vehicle-invalid.

Two fields are about the game rather than the car, and one is about which wheels:

The entity must also carry a rigidbody of kind dynamic and a non-trigger collider. The vehicle is that body; the collider is its bodywork, and it is what the geometric rules measure wheels against. Without them you get vehicle-needs-dynamic-body.

Every field is optional. That is forced rather than lax: a preset override has to be able to say chassis: { mass: 2400 } and nothing else, so a required centerOfMass would make that unspellable. Completeness is a rule on the resolved vehicle, not a shape requirement.

Full field-by-field descriptions with units live in packages/contract/src/schema.ts and are carried through to schema.json and the rustdoc on crates/contract/src/gen.rs, so an agent reads them wherever it is standing. What follows is the shape and the units, not a second copy of those descriptions.

chassis

The wheel component

On its own entity, below the body it carries. Every field is optional; what fills a missing one is, in order, the vehicle preset's wheel on the same corner (under a vehicle with a preset), then the default in the last column.

The wheel's id is its entity's id: the telemetry key, and what wheels lists. Where it is (its centre at rest) and which way it rolls come from its transform (§1), never from a field.

A wheel drawn from more than one entity: visuals

The wheel entity is drawn turning, so the simplest wheel is a cylinder mesh on the wheel entity itself. A kart built from primitives, or one cut from a model, often has the wheel in parts beside an empty mount: a tyre, a hub cap on its outside face, a brake disc. Name those in the wheel's visuals:

{ "id": "wheel-fl", "parent": "kart", "transform": { "position": [-0.42, 0.14, -0.55], ... },
  "components": [{ "type": "wheel", "visuals": ["tyre-fl", "hub-fl"] }] },
{ "id": "tyre-fl", "parent": "kart", "transform": { "position": [-0.42, 0.14, -0.55], "rotation": [0, 0, 0.7071, 0.7071], ... },
  "components": [{ "type": "mesh", "asset": "cylinder" }] }

Every tick each visual takes the wheel's own motion: it drops and rises with the suspension, turns with the steering, and spins about the wheel's axle through the wheel's centre. That motion is applied on top of the pose the scene gave the visual, so its rotation and scale are kept. A hub cap 0.14 m outboard of the tyre stays on the turned axle, and a part off the axle orbits it.

• By id, never by name. Nothing is matched from a name like wheel-fl or tyre. A prefab's ids are rewritten on expansion and on ctx.world.spawn({ prefab }) exactly as vehicle.wheels is (kart-1/tyre-fl).
• What a visual may be (wheel-invalid otherwise, at visuals/<k>): an entity in the scene, below the same dynamic body as its wheel, without a rigidbody of its own. It may not be the wheel or anything above it. It may not be below the wheel either, because a child already turns with its parent and would be turned twice. And one entity turns with one wheel only.
• Cost. A wheel with no visuals costs nothing extra. Each visual is one pose write per tick, and up to 32 poses per vehicle (wheels and visuals together) are written without allocating. Past that the rest are not drawn turning, which never affects the simulation.
• A part that should steer but not spin, such as a mudguard or a caliper, is not covered yet; parent it to an unspinning mount of its own.

The suspension, the roles, and what each number means:

Fractions rather than flags is the point: rear-wheel drive, an AWD split and torque vectoring are all one field, and adding a sixth wheel needs no new concept — it is one more entity.

There is no assumption of four wheels, and a wheel's role comes from its fractions, not from its index.

drivetrain

Wheel torque is engine torque × gear × finalDrive.

brakes, tyres, aero, assists

drift

An optional drift object makes a vehicle slide on demand, the way an arcade racer does. Absent, the feature does not exist: the vehicle drives bit for bit as it did before it was added and the feature costs nothing. Present, the handbrake input is the drift button (it applies no brake torque any more). Holding it while the speed is at least minSpeed and the steering is at least minSteer starts a drift in the steer's direction; releasing it, or slowing below 60% of minSpeed, ends it.

The charge is the time spent sliding at or above chargeMinAngle; on release the highest tier it reached starts its boost (the extra top speed fades over the last 30% of the duration). A game reads the state from ctx.vehicle (§6) to drive sparks and sounds.

aero, assists and steering are the parts that are never required. For aero and assists, absent means none of either. For steering, and for tyres.rollingResistance and the three drivetrain shift fields, absent means the documented default above — a vehicle that says nothing about steering still steers. Defaults are applied once, at resolution, so a solver never invents one of its own and two solvers cannot disagree about what "absent" meant.

model

arcade (the default when absent) or simulation. A scene names parts, never a solver's internals, so changing this field changes nothing else.

Today both run the arcade model (§4). The simulation model — engine speed through the gearbox, a differential, a slip-curve tyre with load sensitivity, the assists — has its pure parts in crates/vehicles (drivetrain.rs, tyre.rs) and is being moved onto the same raycast wheel; until it lands, a simulation vehicle drives exactly as an arcade one with the same parts, and nothing pretends otherwise. tyres.peakSlipRatio, loadSensitivity and the assists are read by nothing until then; tyres.peakSlipAngle, muLong, muLat and rollingResistance are read now.

---

3. Presets

Five presets ship as data in crates/vehicles/presets/: the road classes sedan, suv, pickup, van, and kart, a small light arcade vehicle with drift (see "drift" in §2). kart: 180 kg, 1.1 m wheelbase, 0.14 m wheels, 0.1 m of short stiff suspension, tyres with μ about 1.5, 0.5 rad of quick steering lock, about 26 m/s flat out, and a drift block with three boost tiers.

These are plausible round numbers for a class. They are not any real vehicle's published figures, and must not be presented as such. Reference targets for real vehicles are a separate, sourced thing and are not in this repo yet.

The chassis collider each preset assumes

Three of the validation rules measure wheels and the centre of mass against the entity's own collider, so a preset is only meaningful beside one. These are the boxes the presets were tuned against, and fixtures/contract/valid/vehicle.json is all four of them in one scene, regenerated and revalidated by pnpm gen:fixtures:

A markedly different collider is fine — just expect the geometric warnings to have opinions about it.

How a preset resolves

preset first, then the component's own fields over the top:

• Objects merge field by field. chassis: { mass: 2400 } keeps the preset's centerOfMass and inertia.
• gears and torqueCurve are replaced whole, never merged element-wise. Interpolating between two curves would be a third engine, not an override.
• The wheels are the scene's wheel entities; the preset's wheels are defaults by corner. A wheel ahead of the body's origin (z < 0) is a front wheel, one at x < 0 a left one; each takes the preset wheel on its corner (else one on its axle) for every field it leaves out. So three wheels, six, or a kart's four at a different track are all just entities, and a preset still sizes them.
• A component with no preset resolves to itself and must be complete on its own; its wheels fall back to the wheel defaults (§2).

The presets are the source of truth in crates/vehicles/presets/*.json. pnpm gen:rust reads them, and emits packages/contract/vehicle-presets.json (committed bytes both languages agree with), packages/contract/src/vehicle-presets.ts and VEHICLE_PRESETS_JSON in crates/contract/src/gen.rs — the same arrangement input-default.json has, so the two mirrors cannot drift.

---

4. How it drives

A raycast wheel, on the physics forces API. Each tick, before the physics step, each wheel casts one ray down from its suspension's hard point (position + up * restLength), ignoring the chassis and anything riding on it. Where the ray lands gives the spring's length; the spring and damper give the wheel's load; the tyre turns that load into grip — a drive or brake force along the wheel, a cornering force across it (rising with slip angle to peakSlipAngle, then held), both inside the friction ellipse muLong/muLat × load. Every force goes to the chassis with add_force_at_point, exactly as a behaviour's ctx.body.addForceAtPoint would, and acts on the step that follows. A grip force is never more than would stop its slide in one tick, which is what holds a parked car still instead of letting it shiver.

Arcade. The drivetrain collapses into one drive force: the engine's peak torque through first gear and the final drive, fading once the engine's peak power runs out, and none past the speed where the engine reaches its redline in top gear (topSpeed). Reverse is weaker and slower. Brake torque becomes brake force at the tyre, split front and rear by bias. Steering is rate-limited by steering.rate and its lock shrinks with speed by steering.speedReduction.

The grip cap is measured at the contact patch. "What would stop the slide in one tick" is the body's mass as the patch feels it: a push at the ground, below the centre of mass, also turns the body, so a light, tall body gives way at a fraction of its mass. The cap uses that effective mass, split over the wheels on the ground. Measured by the mass alone, a 200 kg cart turning and braking overshot its slide a little more every tick and rolled over.

A standalone wheel (no vehicle over it) is the same raycast wheel with nobody between it and a behaviour: it holds the motor torque, brake torque and steer angle a behaviour last set, and its forces turn the body about its real centre of mass. A curve tyre spins its wheel on its own, in a fixed 8 sub-steps a tick, so torque past the grip spins it up and brake past it locks it; a clamp tyre rolls at road speed. The arcade vehicle always runs its wheels on clamp.

What the physics backend is asked for: a filtered raycast, the body's pose, velocity and mass properties, and add_force_at_point — nothing a behaviour cannot ask for too. So wheels add nothing to the physics checkpoint. Their own few numbers — a vehicle's smoothed steering and telemetry history, each wheel's spin — ride in the app's checkpoint beside the solver's bytes (opaque version 2 when a scene has vehicles, 3 when it has standalone wheels), so a snapshot restored mid-turn replays the uninterrupted run bit for bit. CCD is on for every chassis.

A hot reload re-resolves every vehicle and wheel from the new document, whichever entity the edit touched: a wheel given a new radius is re-tuned in place, still spinning; a wheel moved, added or removed rebuilds its body's wheels on the body as it stands.

What a model consumes is never the raw component, which is all optional:

let vehicle = argus_contract::vehicle::resolve(&scene.entities, body)?;   // ResolvedVehicle
let wheel = argus_contract::vehicle::resolve_wheel(&scene.entities, i)?;   // ResolvedWheel, standalone

ResolvedVehicle has no Option on it except chassis.inertia and each wheel's spin inertia; each ResolvedWheel carries its mount position and its rolling direction forward. resolve succeeds only on a vehicle that passes every error-severity rule; its error carries the same RuleCode the validator would have reported. TypeScript has the same functions: resolveVehicle(scene, body) and resolveWheel(scene, i).

---

5. Validation rules

Seven codes, mirrored byte for byte in packages/contract/src/rules.ts and crates/contract/src/rules.rs. Each covers one kind of problem and the message names the exact field; the fixtures under fixtures/contract/invalid/vehicle-*.json and wheel-*.json hold one case of each kind.

One code no validator ever emits

vehicle-capability-absent (warning) is reported by the runtime at load, not by validateScene: a build of the engine compiled without the vehicles capability loads the scene and tells you the vehicle is not there, rather than ignoring the component in silence.

It is a rule code, and not a channel of its own, because these strings are the vocabulary every layer uses to report scene problems — the critic included — and a second vocabulary would just be a second place to look. But a scene has to validate identically everywhere or the schema stops being one contract, so both mirrors resolve and validate a vehicle component exactly the same way whether or not the binary in front of them can run one. CODES_NOT_EMITTED_BY_VALIDATION in codes.ts (and RuleCode::NOT_EMITTED_BY_VALIDATION in codes.rs) names it, so the "every code has a fixture" test can subtract it by name instead of being loosened.

Why the others are warnings and not errors: parseScene throws on errors only, so a hard error is a scene the critic never gets to see, let alone offer a fix for, and a car whose wheels are placed a little outside its box still drives. This follows the resolution packages/contract/src/codes.ts already records for dynamic-needs-collider.

What the geometric rules actually compare

All three need the entity's own collider and stay silent without one, or when it is a trimesh or hulls — the contract holds no mesh data, and an asset's bounds are in the file's units before the import transform, which these mirrors deliberately do not apply. A missing collider is reported by vehicle-needs-dynamic-body instead.

The collider's local AABB, before scale: a box is center ± size/2, a sphere is center ± radius, a capsule is center ± (radius, height/2, radius).

• Outside the chassis — the wheel centre must lie inside that AABB widened by radius on every axis, and by a further width on x only, because a track wider than the bodywork is normal on a real car while a wheel a metre past the bumper is not.
• Travel past the clearance — clearance is colliderMin.y − (position.y − radius): how far the chassis can drop before its collider reaches the contact patch. Fires when travel exceeds it.
• Centre of mass above the roof — centerOfMass.y above colliderMax.y.

Every rule judges the resolved vehicle, so a bad number inside a preset is caught at the scene that uses it. A violation points at what the author can edit: a wheel's position at its entity's transform, a wheel's own field at its wheel component, and a value that came from the preset at the preset field.

---

6. Driving input, and ctx.vehicle

input: "auto" (the default) reads four actions by these names, from the vehicle's own input — which is the player's when the car is the player (§0):

The built-in map (a scene with no meta.input) has none of them, so a driving scene declares them in its own meta.input, usually in its gameplay context.

input: "script" reads nothing; a behaviour drives it:

update(ctx) {
  const v = ctx.vehicle!
  v.drive({ throttle: v.speed < 12 ? 1 : 0, steer: 0.3 })   // held until the next drive
}

ctx.vehicle is present while the entity is a running vehicle and null otherwise: drive({ throttle, brake, steer, handbrake }) (steer +1 right; values clamped; a NaN throws vehicle.not-finite), reset() (back on its wheels, upright and still, where every wheel last touched the ground), and input, speed (m/s, negative reversing), steerAngle (the wheels' angle, radians, positive right like the action), throttle, brake, gear (1 or -1) and wheelsOnGround. On a vehicle with a drift block (§2), also drifting (a drift is held), driftAngle (radians, positive right, 0 when not drifting; its magnitude is how sideways it travels), driftCharge (seconds of boost-earning slide), driftTier (0 none, 1.. the boost tier the charge has reached) and boosting (a drift boost is pushing); all false or 0 on any other vehicle. (API since 0.6.0). drive on an auto vehicle changes nothing and is counted on GET /perf → unwired.vehicle_ignored.

ctx.wheel

On a wheel entity's own behaviour, ctx.wheel is its wheel; from the body's behaviour, ctx.body.wheels lists every wheel on the body and ctx.vehicle.wheels the vehicle's. Each is:

• Writes, held until the next call: setMotorTorque(nm) (positive rolls it forward), setBrakeTorque(nm) (0 or more), setSteer(radians) (positive right). A NaN throws wheel.not-finite. On a wheel of an input: "script" vehicle, each field written takes that wheel over from the vehicle's command until the vehicle's next ctx.vehicle.drive — torque vectoring, one wheel spun up. A wheel of an auto vehicle ignores all three, counted on GET /perf → unwired.vehicle_ignored: the engine sets every wheel from the actions each tick.
• Reads: drivenBy ("script" or "vehicle"), grounded, contact ({ point, normal, entity }, null in the air), slip ({ long, lat }: slip ratio, 0 on a clamp tyre, and slip angle in radians), rpm, load (N on the spring), compression (0 at rest length or longer, 1 at the bump stop), steerAngle (positive right), motorTorque, brakeTorque, radius, and entity.

Wheels and pedals (the input devices) are a later milestone. When that lands, the extension goes in three places: GamepadBinding gains raw axis spellings, InputAction gains invert, range, curve and a device selector, and axis_of in crates/app/src/input/gamepad.rs stops dropping Axis::Unknown.

---

7. What a tester reads

GET /entities?fields=vehicle keeps each entity's vehicle block (and its id); only a running vehicle has one:

{ "id": "car", "vehicle": {
    "input": "auto",
    "actions": { "throttle": { "action": "throttle", "kind": "button" },
                 "brake": { "action": "brake", "kind": "button" },
                 "steer": { "action": "steer", "kind": "axis1" } },
    "speed": 8.2, "forward": [0.27, 0.0, -0.96], "steerAngle": 0.21,
    "maxSteer": 0.6, "wheelbase": 2.8, "minTurnRadius": 4.37, "brakeDecel": 8.7, "topSpeed": 80.1,
    "throttle": 1.0, "brake": 0.0, "gear": 1, "wheelsOnGround": 4 } }

• input says who owns the movement: auto, the engine from the actions (a behaviour's ctx.vehicle.drive is ignored); script, a behaviour (holds on the actions move nothing).
• actions names each role's action with its kind, only where the scene's gameplay context binds it; a role left out reads 0.
• speed is along forward (the car's -Z), after this tick's step. steerAngle is the wheels' angle now, positive right like the steer action; maxSteer is full lock at a standstill.
• minTurnRadius is the tightest circle at its speed now (wheelbase / tan(lock), with the lock the steering's speed reduction leaves): what a path follower needs to know whether a turn can be made. brakeDecel is what full brake gives on the level, for stopping on a mark.

A tester drives it only through POST /input holds of the named actions — the same path a player's keys take — and a lockstep run is deterministic.

---

8. Deferred, said out loud

The simulation model on the raycast wheel (§2 model). Applying chassis.inertia and the centre of mass to the body itself (needs a mass-properties setter on the physics backend). A driving-scenario battery in the critic (0-60, braking distance, skidpad) and argus vehicle setup from an imported model. Force feedback. Damage and deformation. Tracked and two-wheeled vehicles. A full Pacejka tyre. AI traffic. Anything networked.

A behaviour's ctx.world.spawn of a body with wheels: the clone is not in the document, so its wheels are not composed or driven until the next reload; a vehicle cloned that way is refused with the contract's no-wheels message.

Counter-steering rear axles are also not expressible: steerable is 0..1, so a rear axle cannot turn the other way. Widening that range is the additive change to make when it is wanted.