Vehicle feel on a heightfield, for diorama racing and trail games. One small, fixed-step model for two wheels (a dirt bike) and four (a Jeep, a truck, a buggy, a car): throttle, brake (and reverse), steering that tightens less at speed, grip and drift (the tyres hold a sideways slide only up to grip, a handbrake input lets the rear go), a spring and damper per wheel so the body pitches, rolls, squats and dives with the ground under each wheel, airtime off a lip, and a landing that is judged: a bike that lands nose or tail too far off the slope, or a car that rolls past crashRoll, crashes. - The ground is anything with sample(x, z, out) (out = [height, nx, ny, nz], returns a surface kind): @fzlt/core/terrain is one, and its painted kinds can change the grip (surfaces). - Deterministic: the same inputs from the same start give the same path, bit for bit. The model uses only + − × ÷, square roots and its own polynomial sine and arctangent (the builtins may differ in the last bit between browsers), so two players replaying the same inputs agree. - Suspension: each wheel samples the ground on its own and has its own spring (stiffness or hz, progressive), damper (damping compressing, rebound extending), travel and a bump stop; the body heaves, pitches and rolls on the sum of the spring loads with its own inertia, so a big drop compresses the springs, rebounds and settles (a long-travel buggy: travel 0.5 or more, soft and progressive, more rebound than compression damping). - Outputs for drawing: pos and rot (diorama's order: [roll, yaw, pitch]) for the body, per wheel comp (how far its spring is pushed in) and press (the same, 0..1 of the travel), spin (radians) and contact, bodyPitch and bodyRoll (the lean on the springs), stroke (the most any spring is in: 1 is the bump stop), the front wheels' steerAngle, and dust (0..1: how hard the tyres throw dirt, spray or sand) for an emitter. - Drift: the handbrake input lets the rear go (the grip drops to drift, the tail swings out by swing, the slide is held under slide radians and counter-steer catches it; letting go hands recover of the sideways speed back as forward speed). drift (0..1) says how hard it is drifting right now, slide the body's angle to its travel, chain the drift score so far (∫ drift dt); a chain that ends banks as drive:drift (v: its score; b: 1 when a crash or a spin-out broke it). spinOut(rate, secs) spins it round with no control for a moment. - Contact between vehicles: touch(a, b, opts) (or touchAll(list, opts), every pair in order) pushes two hulls apart (a box from hull [half length, half width], or a circle: one radius) by their mass and bounces their velocities along the contact normal; onHit(a, b, hit) gets the impulse in hit (touchHit: [impulse, nx, nz, depth, x, z], the normal from a to b), so a game can spin out a drifting car it rams. - chase(cam, target, opts, dt) eases a diorama camera behind and above anything with pos and yaw (cosmetic: it uses the builtin maths; pass snap for reduced motion). - Rollback: state is every byte the model carries from step to step (one buffer); save(dst) and load(src) copy it out and back, so a game can rewind and replay a car bit for bit. Zero allocation per step, also with several vehicles in one process (typed arrays; locals; one class for every vehicle, its model in module functions, so a loop over cars keeps one call target). Speeds are world units per second, angles radians.
const v = drive(t, { kind: "bike" }); // or "car": four springs, rollovers
v.reset(-9, 8, 0);
e.add({ step(_, dt) { v.set(throttle, brake, steer, drift); if (v.step(dt)) e.busy(); chase(d.cam, v, follow, dt); } });
car.pos.set(v.pos); car.rot.set(v.rot); // body pose; v.comp, v.spin, v.steerAngle for the wheels
// long travel: drive(t, { travel: 0.6, stiffness: 70, progressive: 1.2, rebound: 0.85 }); v.press[i], v.bodyRoll
if (v.crashed) v.reset(x, z, yaw); // a nose-down landing; v.dust scales an emitter
score += v.drift * dt; // handbrake drifts (drift input 1); drive:drift banks each chain
touchAll(cars, { onHit: (a, b) => b.drift > 0.3 && b.spinOut(7, 1.2) }); // ram a drifter: it spins
API
Every export with its signature, parameters, return type, doc comment and status flag, generated at build time from the published type declarations of v0.27.0 by the TypeScript compiler. For AI agents: the whole API as plain text.
DriveGround interface ALPHA
What drive needs from the ground: height and normal under (x, z); the return is a surface kind.
Options for drive(): the vehicle's shape, its feel and its limits. Defaults by kind.
export interface DriveOptions {
/** "car" (four wheels, default) or "bike" (two in line, leans into turns, rear-wheel drive). */
kind?: "car" | "bike";
/** Wheel offsets from the body's centre, [forward, right, …] (car: ±0.75 × ±0.5; bike: ±0.6 × 0). */
wheels?: ArrayLike<number>;
/** Wheel radius (car 0.28, bike 0.32). */
radius?: number;
/** Spring length at full stretch, from the body's origin to the wheel centre (car 0.3, bike 0.35). */
rest?: number;
/** Spring travel before the bump stop (car 0.24, bike 0.3; a long-travel buggy or trophy truck 0.5 or more). */
travel?: number;
/** Bounce frequency of the springs, Hz (default 2.2). */
hz?: number;
/** The spring rate instead of `hz`: the whole vehicle's, per unit mass, 1/s² (the sag is gravity / stiffness;
* default (2π · 2.2)² ≈ 191). */
stiffness?: number;
/** Progressive springs: the rate grows by this share times (compression / travel)² (default 0: linear; 1 is
* twice as stiff at full travel, soft over small bumps and firm on a big landing). */
progressive?: number;
/** Damping ratio of the springs while they compress (default 0.75). */
damping?: number;
/** Damping ratio while they extend (default `damping`): more holds the body down after a landing instead of a bounce. */
rebound?: number;
/** The bump stop past `travel`: its rate as a multiple of the spring's (default 10). */
bump?: number;
/** Body inertia for pitch and roll, a multiple of the springs' match (same bounce as heave): one number, or
* [pitch, roll] (default 1; more pitches and rolls slower and further). */
inertia?: number | ArrayLike<number>;
/** How fast a wheel off the ground drops to full droop, units / s (default Infinity: at once; drawing only). */
droop?: number;
/** Gravity, units / s² (default 20). */
gravity?: number;
/** Acceleration at full throttle from a standstill (car 10, bike 12). */
accel?: number;
/** Top speed on the flat (car 16, bike 18): throttle's pull fades to 0 there. */
top?: number;
/** Braking deceleration (default 22). */
brake?: number;
/** Top speed backwards (brake held at a stop; default 5). */
reverse?: number;
/** Rolling drag with no pedal, units / s² (default 2.5). */
coast?: number;
/** Sideways grip, in g (car 1, bike 1.15): the most sideways acceleration the tyres hold. */
grip?: number;
/** Rear grip left at the full handbrake / drift input (default 0.4). */
drift?: number;
/** How far the tail swings out on the handbrake: the turn tightens by 1 + swing (default 1). */
swing?: number;
/** Most slide angle (body to travel) a drift holds before the swing stops, radians (default 0.8). */
slide?: number;
/** Share of the sideways speed the tyres hand back as forward speed coming out of a drift (default 0.35). */
recover?: number;
/** For `touch`: mass (car 1, bike 0.5). */
mass?: number;
/** For `touch`: the hull, [half length, half width] (a box; default the wheels plus their radius), or one radius (a circle). */
hull?: number | ArrayLike<number>;
/** Most steering, as a wheel angle (car 0.6, bike 0.7). */
steer?: number;
/** Speed at which steering is down to half (default 12). */
steerFall?: number;
/** Centre of mass height over the springs: squat, dive and body roll (car 0.35, bike 0.3). */
cg?: number;
/** Bike: most lean into a turn (default 0.9). */
lean?: number;
/** Pitch control in the air, rad / s² at full throttle (nose up) or brake (nose down) (car 2, bike 6). */
airPitch?: number;
/** A landing (or a moment on the ground) this far off the slope's pitch crashes (car 1, bike 0.65). */
crashPitch?: number;
/** Off the slope's roll by this much crashes: a rollover (car 1.1; bikes do not check). */
crashRoll?: number;
/** Landing faster than this downward crashes (default 30). */
crashDrop?: number;
/** Grip multiplier per ground kind: surfaces[k] for kind k (default 1). */
surfaces?: ArrayLike<number>;
/** Steps per `step()` (default 2: the springs stay stable at 60 Hz). */
substeps?: number;
/** An event ring: `drive:air`, `drive:land` (v: how far off the slope), `drive:crash`, `drive:drift`
* (v: the chain's score; b: 1 when broken), with `id` as a. */
events?: DriveEvents;
/** The id events carry (default 0). */
id?: number;
}
Drive type ALPHA
What drive returns.
export type Drive = Ride;
drive function ALPHA
A vehicle on ground: set input (or set), step(dt) from the engine's step, draw from pos, rot, comp.
export interface TouchOptions {
/** Bounce along the normal, 0 (dead) .. 1 (elastic) (default 0.3). */
bounce?: number;
/** Two bodies further apart than this in height pass (one in the air over the other; default 1). */
height?: number;
/** Called on each contact, after the push: `hit` is `touchHit`. */
onHit?: (a: Drive, b: Drive, hit: Float64Array) => void;
}
touch function ALPHA
Push vehicles a and b apart if their hulls overlap (box against box, box against circle, circle against circle, on the ground plane) by their masses, and bounce their velocities along the contact normal. Deterministic (no builtin trig: the headings' cosines come from the model). True on a contact.
export declare function touchAll(list: ArrayLike<Drive>, o?: TouchOptions): number;
ChaseOptions interface ALPHA
Options for chase: where the camera sits behind its target and how fast it follows.
export interface ChaseOptions {
/** Distance from the target (default 9). */
dist?: number;
/** Look-down angle (default 0.45). */
pitch?: number;
/** Aim this far over the target (default 0.6). */
lift?: number;
/** Aim ahead by this many seconds of the target's velocity (default 0.25; needs `vel`). */
ahead?: number;
/** Turn from straight behind (radians; default 0). */
side?: number;
/** Follow rate, 1/s (default 4): higher is tighter. */
rate?: number;
/** Turn rate, 1/s (default 2.5). */
turn?: number;
/** Jump straight there (reduced motion, a respawn). */
snap?: boolean;
}
chase function ALPHA
Ease diorama camera cam behind and above target (pos [x, y, z], yaw, optional vel) over dt seconds; returns true while it still moves (settle-friendly).