@jgengine/core 0.18.1 → 0.21.0

package/dist/physics/vehicleDynamics.js

@@ -0,0 +1,737 @@
+import { sampleGripCurve } from "./vehicleBody.js";
+const GRAVITY = 9.81;
+const AIR_DENSITY = 1.225;
+/** Below this speed slip angles use it as the longitudinal reference, avoiding the atan singularity at rest. */
+const SLIP_REFERENCE_SPEED = 2;
+const DEFAULT_SUBSTEP = 1 / 240;
+function tireShape(tire) {
+    const slide = Math.min(0.999, Math.max(0.01, tire.slideGrip));
+    const c = 1 + (2 / Math.PI) * Math.acos(slide);
+    const b = Math.tan(Math.PI / (2 * c)) / Math.max(0.005, tire.peakSlipAngle);
+    return { b, c };
+}
+function lateralCurve(shape, alpha) {
+    return Math.sin(shape.c * Math.atan(shape.b * alpha));
+}
+/**
+ * Creates a {@link VehicleDynamics}.
+ * @capability vehicle-dynamics force-based car handling — tires, load transfer, drivetrain, assists — tuned with physical numbers
+ */
+export function createVehicleDynamics(initialTuning, options = {}) {
+    let tuning = initialTuning;
+    let frontShape = tireShape(tuning.front);
+    let rearShape = tireShape(tuning.rear ?? tuning.front);
+    const surfaceFriction = options.surfaceFriction ?? (() => 1);
+    const clampMove = options.clampMove;
+    const spawnGround = options.position?.[1] ?? 0;
+    const groundAt = options.groundHeight ?? (() => spawnGround);
+    const state = freshState(tuning, options.position ?? [0, 0, 0], options.heading ?? 0);
+    settleOnGround();
+    /** Spawn resting on the terrain: pitch, roll and height fitted to the ground under the four wheels. */
+    function settleOnGround() {
+        const suspension = tuning.suspension;
+        if (suspension === undefined)
+            return;
+        const L = Math.max(0.5, tuning.wheelbase);
+        const a = L * (1 - clamp01(tuning.frontWeight));
+        const b = L - a;
+        const half = Math.max(0.15, tuning.trackWidth / 2);
+        const [fx, fz] = forwardOf(state.heading);
+        const ground = (along, lat) => groundAt(state.x + fx * along - fz * lat, state.z + fz * along + fx * lat);
+        const fl = ground(a, -half);
+        const fr = ground(a, half);
+        const rl = ground(-b, -half);
+        const rr = ground(-b, half);
+        const front = (fl + fr) / 2;
+        const rear = (rl + rr) / 2;
+        state.bodyPitch = -Math.atan2(front - rear, L);
+        state.bodyRoll = Math.atan2((fr + rr) / 2 - (fl + rl) / 2, 2 * half);
+        state.y = rear + (front - rear) * (b / L) + suspension.rideHeight;
+        state.vy = 0;
+        state.pitchRate = 0;
+        state.rollRate = 0;
+        const sags = staticSags(tuning, suspension);
+        for (let i = 0; i < 4; i += 1)
+            state.compression[i] = sags[i];
+    }
+    function baseHeight() {
+        return tuning.suspension === undefined ? state.y : state.y - tuning.suspension.rideHeight;
+    }
+    function tick(dt, input, modifiers) {
+        const maxSub = Math.max(1 / 2000, tuning.maxSubstep ?? DEFAULT_SUBSTEP);
+        const steps = dt > 0 ? Math.max(1, Math.ceil(dt / maxSub - 1e-9)) : 0;
+        const h = steps > 0 ? dt / steps : 0;
+        const telemetry = emptyTelemetry();
+        const surface = surfaceFriction(state.x, state.z);
+        telemetry.airborne = state.airborne;
+        for (let i = 0; i < steps; i += 1)
+            substep(h, input, modifiers, surface, telemetry);
+        if (steps === 0)
+            substep(0, input, modifiers, surface, telemetry);
+        const [fx, fz] = forwardOf(state.heading);
+        const forwardSpeed = state.vx * fx + state.vz * fz;
+        const lateralSpeed = -state.vx * fz + state.vz * fx;
+        return {
+            position: [state.x, baseHeight(), state.z],
+            heading: state.heading,
+            forwardSpeed,
+            lateralSpeed,
+            yawRate: state.yawRate,
+            steerAngle: -state.steerAngle,
+            sideslip: telemetry.sideslip,
+            slipAngleFront: telemetry.slipFront,
+            slipAngleRear: telemetry.slipRear,
+            frontSaturation: telemetry.satFront,
+            rearSaturation: telemetry.satRear,
+            lateralAccel: state.lateralAccel,
+            longitudinalAccel: state.longitudinalAccel,
+            frontLoad: telemetry.loadFront,
+            rearLoad: telemetry.loadRear,
+            surface,
+            gear: state.reversing ? -1 : state.gearIndex + 1,
+            rpm: state.rpm,
+            engineLoad: telemetry.engineLoad,
+            wheelspin: telemetry.wheelspin,
+            wheelLock: telemetry.wheelLock,
+            absActive: telemetry.abs,
+            tractionLimited: telemetry.traction,
+            stabilityActive: telemetry.stability,
+            bodyPitch: state.bodyPitch,
+            bodyRoll: state.bodyRoll,
+            airOffset: tuning.suspension === undefined ? 0 : Math.max(0, baseHeight() - groundAt(state.x, state.z)),
+            airborne: state.airborne,
+            landingSpeed: telemetry.landingSpeed,
+            wheelLoads: telemetry.wheelLoads,
+            lean: tuning.lean === undefined ? 0 : balanceLean(state.lateralAccel),
+            wheelie: telemetry.wheelie,
+            stoppie: telemetry.stoppie,
+        };
+    }
+    function substep(h, input, modifiers, surface, out) {
+        const t = tuning;
+        const m = t.massKg;
+        const L = Math.max(0.5, t.wheelbase);
+        const a = L * (1 - clamp01(t.frontWeight));
+        const b = L - a;
+        const iz = Math.max(1, (t.yawInertiaIndex ?? 1) * m * a * b);
+        const heading = state.heading;
+        const [fx, fz] = forwardOf(heading);
+        const u = state.vx * fx + state.vz * fz;
+        const v = -state.vx * fz + state.vz * fx;
+        const r = state.yawRate;
+        const speed = Math.hypot(state.vx, state.vz);
+        const throttle = clamp01(input.throttle);
+        const brakeInput = clamp01(input.brake);
+        const handbrake = clamp01(input.handbrake);
+        const steerInput = Math.max(-1, Math.min(1, input.steer)) * (modifiers?.steerScale ?? 1);
+        if (t.reverseOnBrake ?? true) {
+            if (!state.reversing && brakeInput > 0.1 && throttle <= 0.05 && u < 0.5)
+                state.reversing = true;
+            else if (state.reversing && (throttle > 0.1 || u > 0.5))
+                state.reversing = false;
+        }
+        const wantReverseDrive = state.reversing && brakeInput > 0;
+        // Rack: requested angle is in "heading-positive" sign, the opposite of AxisInput.steer.
+        const steering = t.steering;
+        const lockBlend = Math.min(1, Math.abs(u) / Math.max(0.1, steering.highSpeedAt));
+        const lock = steering.maxAngle + (steering.highSpeedAngle - steering.maxAngle) * lockBlend;
+        const sideslipNow = Math.abs(u) > 1 ? Math.atan2(v, Math.abs(u)) : 0;
+        // Caster: the wheels trail the velocity, so at `selfAlign` they steer into a slide by that share of β.
+        const align = (steering.selfAlign ?? 0) * -sideslipNow * Math.sign(u || 1);
+        let target = Math.max(-steering.maxAngle, Math.min(steering.maxAngle, -steerInput * lock + align));
+        const leanTuning = t.lean;
+        if (leanTuning !== undefined) {
+            // A rider cannot hold more lean than the tires can balance: tan(lean) is the lateral g it needs.
+            const gripLean = Math.atan(t.front.peakGrip * surface * (modifiers?.gripScale ?? 1));
+            const wanted = steerInput * Math.min(leanTuning.maxLean, gripLean);
+            const leanStep = Math.max(0, leanTuning.leanRate) * h;
+            const leanChange = Math.max(-leanStep, Math.min(leanStep, wanted - state.lean));
+            state.lean += leanChange;
+            const speed = Math.abs(u);
+            const direct = leanTuning.directSteerBelow ?? 3;
+            // Balanced turn: the lean sets the yaw rate the bike should hold (g·tan(lean)/v). The bar is that turn's
+            // geometric angle plus a trim the rider feeds back from the yaw error, which covers the tire slip.
+            const wantedYaw = (-GRAVITY * Math.tan(state.lean)) / Math.max(speed, 1) * Math.sign(u || 1);
+            if (speed >= direct)
+                state.leanTrim += (wantedYaw - r) * 3 * h;
+            else
+                state.leanTrim = 0;
+            const trimLimit = Math.min(steering.maxAngle, t.front.peakSlipAngle * 1.5);
+            state.leanTrim = Math.max(-trimLimit, Math.min(trimLimit, state.leanTrim));
+            const geometric = Math.atan((L * wantedYaw) / Math.max(speed, 1));
+            const counter = h > 0 ? ((leanTuning.countersteer ?? 0.012) * leanChange) / h : 0;
+            const blend = Math.min(1, speed / Math.max(0.1, direct));
+            target = Math.max(-steering.maxAngle, Math.min(steering.maxAngle, (geometric + state.leanTrim + counter) * blend + -steerInput * steering.maxAngle * (1 - blend) + align));
+        }
+        const toward = target - state.steerAngle;
+        const returning = Math.sign(toward) !== Math.sign(state.steerAngle) && state.steerAngle !== 0;
+        const rate = returning ? (steering.returnRate ?? steering.rate) : steering.rate;
+        const maxMove = Math.max(0, rate) * h;
+        state.steerAngle += Math.max(-maxMove, Math.min(maxMove, toward));
+        const delta = state.steerAngle;
+        const aero = t.aero;
+        const q = 0.5 * AIR_DENSITY * u * u;
+        const downforce = q * (aero?.downforceArea ?? 0);
+        const downFront = aero?.downforceFront ?? 0.45;
+        const weight = m * GRAVITY;
+        const rsf = t.rollStiffnessFront ?? 0.5;
+        const suspension = t.suspension;
+        let loadFront;
+        let loadRear;
+        let transferFront;
+        let transferRear;
+        let grounded = true;
+        let slopeLong = 0;
+        let slopeLat = 0;
+        if (suspension === undefined) {
+            const transferLong = (m * state.longitudinalAccel * t.comHeight) / L;
+            const rawFront = weight * (b / L) - transferLong + downforce * downFront;
+            const rawRear = weight * (a / L) + transferLong + downforce * (1 - downFront);
+            if (rawFront <= 0)
+                out.wheelie = true;
+            if (rawRear <= 0)
+                out.stoppie = true;
+            loadFront = Math.max(0, rawFront);
+            loadRear = Math.max(0, rawRear);
+            // A single-track vehicle leans instead of shifting load across an axle.
+            const transferLat = t.lean !== undefined ? 0 : (m * Math.abs(state.lateralAccel) * t.comHeight) / Math.max(0.3, t.trackWidth);
+            transferFront = transferLat * rsf;
+            transferRear = transferLat * (1 - rsf);
+        }
+        else {
+            const wheel = springForces(suspension, a, b, h, rsf);
+            loadFront = wheel[0] + wheel[1];
+            loadRear = wheel[2] + wheel[3];
+            transferFront = Math.abs(wheel[0] - wheel[1]) / 2;
+            transferRear = Math.abs(wheel[2] - wheel[3]) / 2;
+            grounded = loadFront + loadRear > 0;
+            out.wheelLoads = [wheel[0], wheel[1], wheel[2], wheel[3]];
+            if (grounded) {
+                // Gravity along the terrain: the tires hold the car to the surface, so the downhill share acts in-plane.
+                const e = 0.5;
+                const gx = (groundAt(state.x + e, state.z) - groundAt(state.x - e, state.z)) / (2 * e);
+                const gz = (groundAt(state.x, state.z + e) - groundAt(state.x, state.z - e)) / (2 * e);
+                const norm = Math.sqrt(1 + gx * gx + gz * gz);
+                const worldX = (-weight * gx) / norm;
+                const worldZ = (-weight * gz) / norm;
+                slopeLong = worldX * fx + worldZ * fz;
+                slopeLat = -worldX * fz + worldZ * fx;
+            }
+        }
+        const sens = t.loadSensitivity ?? 0.2;
+        const gripScale = surface * (modifiers?.gripScale ?? 1);
+        const muFront = t.front.peakGrip * gripScale * loadSensitivityFactor(transferFront, loadFront, sens);
+        const rearTire = t.rear ?? t.front;
+        const muRear = rearTire.peakGrip * gripScale * loadSensitivityFactor(transferRear, loadRear, sens);
+        const capFront = muFront * loadFront;
+        const hbGrip = 1 - handbrake * (1 - (t.handbrakeGrip ?? 0.35));
+        const capRear = muRear * loadRear;
+        // Axle-point velocities in the car frame: front sits `a` ahead, rear `b` behind.
+        const uF = u;
+        const vF = v - a * r;
+        const vR = v + b * r;
+        const cosD = Math.cos(delta);
+        const sinD = Math.sin(delta);
+        const wheelLong = uF * cosD - vF * sinD;
+        const wheelLat = uF * sinD + vF * cosD;
+        const slipFront = Math.atan2(wheelLat, Math.max(SLIP_REFERENCE_SPEED, Math.abs(wheelLong)));
+        const slipRear = Math.atan2(vR, Math.max(SLIP_REFERENCE_SPEED, Math.abs(u)));
+        let drive = driveForce(throttle, wantReverseDrive ? brakeInput : 0, u, h, out) * (modifiers?.driveScale ?? 1);
+        // A governor cuts drive like a limiter: forcing speed down after the fact would leave full drive
+        // consuming the tire budget, and a car pinned at its cap could not turn.
+        if (t.speedLimit !== undefined && drive > 0)
+            drive *= clamp01((t.speedLimit - u) / 0.5);
+        let brakeTotal = 0;
+        if (!wantReverseDrive && brakeInput > 0 && Math.abs(u) > 0.05)
+            brakeTotal = brakeInput * t.brakeForce * (modifiers?.brakeScale ?? 1);
+        const brakeFrontShare = t.brakeFront ?? 0.65;
+        const assists = t.assists;
+        const driveFrontShare = clamp01(t.driveFront);
+        let longFront = drive * driveFrontShare;
+        let longRear = drive * (1 - driveFrontShare);
+        let brakeF = brakeTotal * brakeFrontShare;
+        let brakeR = brakeTotal * (1 - brakeFrontShare);
+        // ABS and TC act on combined slip like the real systems: the longitudinal limit is what the friction
+        // ellipse leaves after the cornering force the axle is already asking for.
+        const frontLatUse = Math.abs(lateralCurve(frontShape, slipFront));
+        const rearLatUse = Math.abs(lateralCurve(rearShape, slipRear)) * hbGrip;
+        const longRoomFront = capFront * Math.sqrt(Math.max(0, 1 - frontLatUse * frontLatUse));
+        const longRoomRear = capRear * Math.sqrt(Math.max(0, 1 - rearLatUse * rearLatUse));
+        const abs = assists?.abs ?? 0;
+        if (abs > 0) {
+            const limitFront = longRoomFront * (1 - 0.2 * abs);
+            const limitRear = longRoomRear * (1 - 0.2 * abs);
+            if (brakeF > limitFront) {
+                brakeF = limitFront + (brakeF - limitFront) * (1 - abs);
+                out.abs = true;
+            }
+            if (brakeR > limitRear) {
+                brakeR = limitRear + (brakeR - limitRear) * (1 - abs);
+                out.abs = true;
+            }
+        }
+        const tc = assists?.tractionControl ?? 0;
+        if (tc > 0) {
+            const limitFront = longRoomFront * (1 - 0.35 * tc);
+            const limitRear = longRoomRear * (1 - 0.35 * tc);
+            if (Math.abs(longFront) > limitFront) {
+                longFront = Math.sign(longFront) * (limitFront + (Math.abs(longFront) - limitFront) * (1 - tc));
+                out.traction = true;
+            }
+            if (Math.abs(longRear) > limitRear) {
+                longRear = Math.sign(longRear) * (limitRear + (Math.abs(longRear) - limitRear) * (1 - tc));
+                out.traction = true;
+            }
+        }
+        // Pitch-over limits: the front lifts once m·ax·h exceeds its static moment (weight·b plus aero), the rear
+        // under braking once it exceeds weight·a. Springs overshoot that static limit as the body pitches, so a
+        // sprung vehicle also backs off in proportion to how light the axle already is.
+        const antiWheelie = assists?.antiWheelie ?? 0;
+        const driveSum = longFront + longRear;
+        if (antiWheelie > 0 && driveSum > 0 && u >= 0) {
+            const lightFront = suspension === undefined ? 1 : clamp01(loadFront / (0.3 * weight * (b / L)));
+            const liftDrive = ((weight * b + downforce * downFront * L) / t.comHeight) * (1 - 0.15 * antiWheelie) * lightFront;
+            if (driveSum > liftDrive) {
+                const scale = (liftDrive + (driveSum - liftDrive) * (1 - antiWheelie)) / driveSum;
+                longFront *= scale;
+                longRear *= scale;
+                out.traction = true;
+            }
+        }
+        const antiStoppie = assists?.antiStoppie ?? 0;
+        const brakeSum = brakeF + brakeR;
+        if (antiStoppie > 0 && brakeSum > 0) {
+            const lightRear = suspension === undefined ? 1 : clamp01(loadRear / (0.3 * weight * (a / L)));
+            const liftBrake = ((weight * a + downforce * (1 - downFront) * L) / t.comHeight) * (1 - 0.15 * antiStoppie) * lightRear;
+            if (brakeSum > liftBrake) {
+                const scale = (liftBrake + (brakeSum - liftBrake) * (1 - antiStoppie)) / brakeSum;
+                brakeF *= scale;
+                brakeR *= scale;
+                out.abs = true;
+            }
+        }
+        const direction = Math.sign(u) || 1;
+        // A locked rear (handbrake) drags at sliding friction and gives up most of its cornering force.
+        const hbDrag = handbrake * capRear * rearTire.slideGrip * 0.9;
+        let fxFront = longFront - direction * brakeF;
+        let fxRear = longRear - direction * (brakeR + hbDrag);
+        const front = combine(fxFront, capFront, frontShape, slipFront, 1, out, "front", Math.abs(longFront) > 0);
+        const rear = combine(fxRear, capRear, rearShape, slipRear, hbGrip, out, "rear", Math.abs(longRear) > 0);
+        fxFront = front.fx;
+        fxRear = rear.fx;
+        let fyFront = front.fy;
+        let fyRear = rear.fy;
+        // Cap lateral forces so one substep cannot push an axle's slip velocity past zero at low speed.
+        if (h > 0) {
+            const mFront = m * (b / L);
+            const mRear = m * (a / L);
+            const maxFront = (mFront * Math.abs(wheelLat)) / h;
+            const maxRear = (mRear * Math.abs(vR)) / h;
+            if (Math.abs(fyFront) > maxFront)
+                fyFront = Math.sign(fyFront) * maxFront;
+            if (Math.abs(fyRear) > maxRear)
+                fyRear = Math.sign(fyRear) * maxRear;
+        }
+        // Car-frame forces (x forward, y along the lateral axis used by `v`).
+        const frontLat = fyFront * cosD - fxFront * sinD;
+        let forceLong = fxFront * cosD + fyFront * sinD + fxRear + (modifiers?.thrust ?? 0) + slopeLong;
+        const forceLat = frontLat + fyRear + slopeLat;
+        const drag = q * (aero?.dragArea ?? 0) * Math.sign(u);
+        const rollingLoad = suspension === undefined ? weight : loadFront + loadRear;
+        const rolling = (aero?.rollingResistance ?? 0.015) * rollingLoad * Math.sign(u) * Math.min(1, Math.abs(u) / 0.5);
+        forceLong -= drag + rolling;
+        // Lateral force ahead of the CG yaws the heading negative in this frame, force behind it positive.
+        let yawMoment = -a * frontLat + b * fyRear;
+        const stab = assists?.stability ?? 0;
+        if (stab > 0 && grounded && Math.abs(u) > 3) {
+            const allowed = assists?.maxSideslip ?? 0.2;
+            const excess = Math.abs(sideslipNow) - allowed;
+            if (excess > 0) {
+                yawMoment += -Math.sign(sideslipNow) * Math.sign(u) * stab * excess * 4 * iz * Math.max(1, Math.abs(r) + 1);
+                yawMoment += -stab * r * iz * 0.6 * Math.min(1, excess * 4);
+                out.stability = true;
+            }
+        }
+        let du = forceLong / m - r * v;
+        const dv = forceLat / m + r * u;
+        // Brakes and rolling resistance cannot reverse the car inside one substep (a slope can).
+        if (h > 0 && throttle <= 0 && !wantReverseDrive && (modifiers?.thrust ?? 0) === 0 && slopeLong === 0) {
+            const next = u + du * h;
+            if (Math.sign(next) !== Math.sign(u) && u !== 0)
+                du = -u / h;
+        }
+        const dr = yawMoment / iz;
+        let nu = u + du * h;
+        let nv = v + dv * h;
+        let nr = r + dr * h;
+        const slopePull = Math.hypot(slopeLong, slopeLat);
+        const holds = slopePull <= (aero?.rollingResistance ?? 0.015) * weight * 2 || brakeInput > 0 || handbrake > 0;
+        if (h > 0 && grounded && holds && speed < 0.3 && throttle <= 0 && brakeInput <= 0 && Math.abs(modifiers?.thrust ?? 0) === 0) {
+            nu *= Math.max(0, 1 - 6 * h);
+            nv *= Math.max(0, 1 - 6 * h);
+            nr *= Math.max(0, 1 - 6 * h);
+        }
+        // Near rest, held brakes grip statically: they cancel motion up to what the braked axles can hold,
+        // so a car parks on a slope instead of creeping at whatever speed a damped slide settles to.
+        if (h > 0 && grounded && Math.abs(nu) < 0.5 && !wantReverseDrive && throttle <= 0) {
+            const holdForce = handbrake * capRear * rearTire.slideGrip + brakeInput * Math.min(t.brakeForce, capFront + capRear);
+            const hold = (holdForce / m) * h;
+            if (hold > 0)
+                nu = Math.abs(nu) <= hold ? 0 : nu - Math.sign(nu) * hold;
+        }
+        const reverseCap = t.reverseSpeed ?? 8;
+        if (nu < -reverseCap)
+            nu = -reverseCap;
+        state.heading = heading + nr * h;
+        const [nfx, nfz] = forwardOf(state.heading);
+        let nvx = nfx * nu - nfz * nv;
+        let nvz = nfz * nu + nfx * nv;
+        const toX = state.x + nvx * h;
+        const toZ = state.z + nvz * h;
+        if (clampMove !== undefined && h > 0) {
+            const allowed = clampMove([state.x, state.z], [toX, toZ]);
+            nvx = (allowed.motion?.[0] ?? allowed[0] - state.x) / h;
+            nvz = (allowed.motion?.[1] ?? allowed[1] - state.z) / h;
+            state.x = allowed[0];
+            state.z = allowed[1];
+        }
+        else {
+            state.x = toX;
+            state.z = toZ;
+        }
+        state.vx = nvx;
+        state.vz = nvz;
+        state.yawRate = nr;
+        const response = suspension === undefined ? 1 - Math.exp(-(t.suspensionResponse ?? 8) * h) : 1;
+        const accelLong = h > 0 ? du + r * v : 0;
+        const accelLat = h > 0 ? dv - r * u : 0;
+        state.longitudinalAccel += (accelLong - state.longitudinalAccel) * response;
+        // The rider's lean is the displayed roll, so it keeps the roll lag springs would otherwise supply.
+        const responseLat = t.lean !== undefined ? 1 - Math.exp(-(t.suspensionResponse ?? 8) * h) : response;
+        state.lateralAccel += (accelLat - state.lateralAccel) * responseLat;
+        if (suspension === undefined) {
+            const rollK = t.rollStiffness ?? (m * GRAVITY * t.comHeight) / 0.05;
+            const pitchK = t.pitchStiffness ?? (m * GRAVITY * t.comHeight) / 0.035;
+            state.bodyRoll = t.lean !== undefined ? -balanceLean(state.lateralAccel) : (m * state.lateralAccel * t.comHeight) / rollK;
+            state.bodyPitch = (-m * state.longitudinalAccel * t.comHeight) / pitchK;
+        }
+        else {
+            if (!grounded && t.air !== undefined)
+                steerInAir(t.air, input, modifiers?.air, h);
+            integrateBody(suspension, a, b, h, downforce, grounded, out);
+        }
+        out.sideslip = Math.abs(nu) > 1 ? Math.atan2(nv, Math.abs(nu)) : 0;
+        out.slipFront = slipFront;
+        out.slipRear = slipRear;
+        out.loadFront = loadFront;
+        out.loadRear = loadRear;
+    }
+    const corner = [0, 0, 0, 0];
+    /** Spring + damper + anti-roll force at each corner from the current body pose; updates stored compression. */
+    function springForces(suspension, a, b, h, rsf) {
+        const t = tuning;
+        const half = Math.max(0.15, t.trackWidth / 2);
+        const [fx, fz] = forwardOf(state.heading);
+        const sags = staticSags(t, suspension);
+        // A leaning single-track vehicle rolls about its tire contacts, so its lean never compresses one side's springs.
+        const roll = t.lean !== undefined ? 0 : state.bodyRoll;
+        for (let i = 0; i < 4; i += 1) {
+            const along = i < 2 ? a : -b;
+            const lat = i % 2 === 0 ? -half : half;
+            const px = state.x + fx * along - fz * lat;
+            const pz = state.z + fz * along + fx * lat;
+            const attach = state.y - Math.sin(state.bodyPitch) * along + Math.sin(roll) * lat;
+            const c = groundAt(px, pz) + suspension.rideHeight + sags[i] - attach;
+            const rate = h > 0 ? (c - state.compression[i]) / h : 0;
+            state.compression[i] = c;
+            let force = 0;
+            if (c > 0) {
+                const damping = rate >= 0 ? suspension.damperRate : (suspension.reboundRate ?? suspension.damperRate * 1.5);
+                force = suspension.springRate * c + damping * rate;
+                // The bump stop is stiff and lossy: it stops the travel without handing the landing back as a bounce.
+                if (c > suspension.travel)
+                    force += suspension.springRate * 20 * (c - suspension.travel) + Math.max(0, rate) * suspension.damperRate * 6;
+            }
+            corner[i] = Math.max(0, force);
+        }
+        const antiRoll = t.lean !== undefined ? 0 : (suspension.antiRoll ?? 0);
+        if (antiRoll > 0) {
+            for (let axle = 0; axle < 2; axle += 1) {
+                const left = axle * 2;
+                if (corner[left] <= 0 || corner[left + 1] <= 0)
+                    continue;
+                const share = axle === 0 ? rsf : 1 - rsf;
+                const shift = (antiRoll * share * state.bodyRoll) / (2 * half);
+                corner[left] = Math.max(0, corner[left] + shift);
+                corner[left + 1] = Math.max(0, corner[left + 1] - shift);
+            }
+        }
+        return corner;
+    }
+    function steerInAir(air, input, explicit, h) {
+        const pitch = clampUnit(explicit?.pitch ?? clamp01(input.throttle) - clamp01(input.brake));
+        const yaw = clampUnit(explicit?.yaw ?? input.steer);
+        const roll = clampUnit(explicit?.roll ?? 0);
+        const damping = air.damping ?? 1.5;
+        const maxRate = air.maxRate ?? 5.5;
+        state.pitchRate = driveRate(state.pitchRate, pitch * air.pitchAccel, damping, maxRate, h);
+        state.yawRate = driveRate(state.yawRate, -yaw * air.yawAccel, damping, maxRate, h);
+        state.rollRate = driveRate(state.rollRate, roll * air.rollAccel, damping, maxRate, h);
+    }
+    /** Heave, pitch and roll from the corner forces found this substep plus the tires' inertial moments. */
+    function integrateBody(suspension, a, b, h, downforce, grounded, out) {
+        const t = tuning;
+        const m = t.massKg;
+        const half = Math.max(0.15, t.trackWidth / 2);
+        let lift = 0;
+        let pitchMoment = 0;
+        let rollMoment = 0;
+        for (let i = 0; i < 4; i += 1) {
+            const along = i < 2 ? a : -b;
+            const lat = i % 2 === 0 ? -half : half;
+            lift += corner[i];
+            pitchMoment -= corner[i] * along;
+            rollMoment += corner[i] * lat;
+        }
+        if (grounded) {
+            pitchMoment -= m * state.longitudinalAccel * t.comHeight;
+            rollMoment += m * state.lateralAccel * t.comHeight;
+        }
+        const pitchInertia = Math.max(1, (suspension.pitchInertiaIndex ?? 0.9) * m * a * b);
+        const rollInertia = Math.max(1, 0.6 * m * half * half);
+        state.vy += ((lift - downforce) / m - GRAVITY) * h;
+        state.y += state.vy * h;
+        state.pitchRate += (pitchMoment / pitchInertia) * h;
+        state.rollRate += (rollMoment / rollInertia) * h;
+        state.bodyPitch += state.pitchRate * h;
+        state.bodyRoll += state.rollRate * h;
+        if (t.lean !== undefined) {
+            state.bodyRoll = -balanceLean(state.lateralAccel);
+            state.rollRate = 0;
+        }
+        if (state.airborne && grounded)
+            out.landingSpeed = Math.max(out.landingSpeed, -state.vy);
+        state.airborne = !grounded;
+        if (!grounded)
+            state.airTime += h;
+        else if (state.vy <= 0.5) {
+            // Still-compressed springs right after a jump read as ground contact; only a settled car has landed.
+            state.jumpsUsed = 0;
+            state.airTime = 0;
+        }
+    }
+    function driveForce(throttle, reverse, u, h, out) {
+        const pt = tuning.powertrain;
+        if (pt.kind === "direct") {
+            out.engineLoad = Math.max(throttle, reverse);
+            if (reverse > 0)
+                return -reverse * pt.maxForce * (pt.reverseScale ?? 0.5);
+            if (throttle <= 0)
+                return Math.abs(u) > 0.2 ? -Math.sign(u) * (pt.coastForce ?? pt.maxForce * 0.08) : 0;
+            const powerLimited = pt.maxPower / Math.max(1, Math.abs(u));
+            return throttle * Math.min(pt.maxForce, powerLimited);
+        }
+        state.shiftRemaining = Math.max(0, state.shiftRemaining - h);
+        const eff = pt.efficiency ?? 0.85;
+        const ratio = state.reversing ? pt.reverseGear : (pt.gears[state.gearIndex] ?? 1);
+        const wheelRpm = (Math.abs(u) / Math.max(0.05, pt.wheelRadius)) * (60 / (2 * Math.PI));
+        const coupled = wheelRpm * ratio * pt.finalDrive;
+        const pedal = Math.max(throttle, reverse);
+        const launch = pt.launchRpm ?? pt.idleRpm + (pt.redlineRpm - pt.idleRpm) * 0.35;
+        const slipRpm = pt.idleRpm + (launch - pt.idleRpm) * pedal;
+        const targetRpm = Math.min(pt.redlineRpm, Math.max(coupled, slipRpm, pt.idleRpm));
+        const rpmResponse = 1 - Math.exp(-18 * h);
+        state.rpm += (targetRpm - state.rpm) * rpmResponse;
+        if (!state.reversing && state.shiftRemaining <= 0) {
+            if (coupled >= pt.shiftUpRpm && state.gearIndex < pt.gears.length - 1 && pedal > 0) {
+                state.gearIndex += 1;
+                state.shiftRemaining = pt.shiftSeconds;
+            }
+            else if (coupled <= pt.shiftDownRpm && state.gearIndex > 0) {
+                state.gearIndex -= 1;
+                state.shiftRemaining = pt.shiftSeconds;
+            }
+        }
+        const normalized = (state.rpm - pt.idleRpm) / Math.max(1, pt.redlineRpm - pt.idleRpm);
+        const limiter = coupled >= pt.redlineRpm ? 0 : 1;
+        const shifting = state.shiftRemaining > 0 ? 0.2 : 1;
+        const toWheel = (ratio * pt.finalDrive * eff) / Math.max(0.05, pt.wheelRadius);
+        out.engineLoad = pedal * limiter * shifting;
+        if (pedal > 0) {
+            const torque = pt.peakTorque * sampleGripCurve(pt.torqueCurve, normalized) * pedal * limiter * shifting;
+            return (reverse > 0 ? -1 : 1) * torque * toWheel;
+        }
+        if (Math.abs(u) < 0.5)
+            return 0;
+        return -Math.sign(u) * (pt.engineBrakeTorque ?? pt.peakTorque * 0.12) * toWheel;
+    }
+    return {
+        tick,
+        pose: () => ({ position: [state.x, baseHeight(), state.z], heading: state.heading }),
+        velocity: () => [state.vx, state.vz],
+        scaleVelocity(factor) {
+            state.vx *= factor;
+            state.vz *= factor;
+            state.yawRate *= factor;
+        },
+        jump() {
+            const jump = tuning.jump;
+            if (jump === undefined || tuning.suspension === undefined)
+                return false;
+            if (!state.airborne && state.jumpsUsed === 0) {
+                state.vy = Math.max(state.vy, 0) + jump.speed;
+                state.jumpsUsed = 1;
+                return true;
+            }
+            const count = jump.count ?? 1;
+            const inWindow = state.airTime <= (jump.window ?? Number.POSITIVE_INFINITY);
+            if (state.jumpsUsed >= count || !inWindow)
+                return false;
+            // An air jump always takes off from a first jump (or a ledge) and counts as one used either way.
+            state.jumpsUsed = Math.max(state.jumpsUsed, 1) + 1;
+            state.vy = Math.max(state.vy, 0) + jump.speed;
+            return true;
+        },
+        applyAngularImpulse(pitch, yaw, roll) {
+            state.pitchRate += pitch;
+            state.yawRate += yaw;
+            state.rollRate += roll;
+        },
+        applyImpulse(dvx, dvz, dvy = 0) {
+            state.vx += dvx;
+            state.vz += dvz;
+            if (tuning.suspension !== undefined)
+                state.vy += dvy;
+        },
+        retune(next) {
+            tuning = next;
+            frontShape = tireShape(next.front);
+            rearShape = tireShape(next.rear ?? next.front);
+            if (next.powertrain.kind === "gearbox") {
+                state.gearIndex = Math.min(state.gearIndex, next.powertrain.gears.length - 1);
+            }
+        },
+        tuning: () => tuning,
+        snapshot: () => ({ ...state, compression: [...state.compression] }),
+        restore(next) {
+            Object.assign(state, next, { compression: [...next.compression] });
+        },
+        resetTo(position, heading) {
+            Object.assign(state, freshState(tuning, position, heading));
+            settleOnGround();
+        },
+    };
+}
+function emptyTelemetry() {
+    return {
+        sideslip: 0,
+        slipFront: 0,
+        slipRear: 0,
+        satFront: 0,
+        satRear: 0,
+        loadFront: 0,
+        loadRear: 0,
+        engineLoad: 0,
+        wheelspin: false,
+        wheelLock: false,
+        abs: false,
+        traction: false,
+        stability: false,
+        airborne: false,
+        landingSpeed: 0,
+        wheelLoads: [0, 0, 0, 0],
+        wheelie: false,
+        stoppie: false,
+    };
+}
+/** Static spring compression at each corner that holds the car level at `rideHeight`. */
+function staticSags(tuning, suspension) {
+    const front = clamp01(tuning.frontWeight);
+    const perFront = (tuning.massKg * GRAVITY * front) / 2 / Math.max(1, suspension.springRate);
+    const perRear = (tuning.massKg * GRAVITY * (1 - front)) / 2 / Math.max(1, suspension.springRate);
+    return [perFront, perFront, perRear, perRear];
+}
+/**
+ * Friction ellipse for one axle: longitudinal demand is clamped to the budget first, then lateral force gets
+ * what is left. Driving or braking hard therefore costs cornering grip on that axle, which is what turns
+ * throttle into power oversteer on a RWD car and brake into rotation on corner entry.
+ */
+function combine(demandX, capacity, shape, slip, lateralScale, out, axle, driven) {
+    if (capacity <= 0)
+        return { fx: 0, fy: 0 };
+    let fx = demandX;
+    if (Math.abs(fx) > capacity) {
+        fx = Math.sign(fx) * capacity;
+        if (driven && demandX > 0)
+            out.wheelspin = true;
+        else
+            out.wheelLock = true;
+    }
+    const remaining = Math.sqrt(Math.max(0, 1 - (fx / capacity) ** 2));
+    const fy = -capacity * lateralScale * remaining * lateralCurve(shape, slip);
+    const saturation = Math.max(Math.hypot(fx, fy) / capacity, Math.abs(slip) / peakAngle(shape));
+    if (axle === "front")
+        out.satFront = Math.max(out.satFront, saturation);
+    else
+        out.satRear = Math.max(out.satRear, saturation);
+    return { fx, fy };
+}
+function peakAngle(shape) {
+    return Math.tan(Math.PI / (2 * shape.c)) / shape.b;
+}
+function loadSensitivityFactor(transfer, load, sensitivity) {
+    if (load <= 0)
+        return 1;
+    const ratio = Math.min(1, transfer / load);
+    return Math.max(0.5, 1 - sensitivity * ratio * ratio);
+}
+function forwardOf(heading) {
+    return [Math.sin(heading), Math.cos(heading)];
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function freshState(tuning, position, heading) {
+    return {
+        x: position[0],
+        y: position[1],
+        z: position[2],
+        heading,
+        vx: 0,
+        vz: 0,
+        yawRate: 0,
+        steerAngle: 0,
+        gearIndex: 0,
+        reversing: false,
+        shiftRemaining: 0,
+        rpm: tuning.powertrain.kind === "gearbox" ? tuning.powertrain.idleRpm : 0,
+        longitudinalAccel: 0,
+        lateralAccel: 0,
+        bodyPitch: 0,
+        bodyRoll: 0,
+        vy: 0,
+        pitchRate: 0,
+        rollRate: 0,
+        compression: [0, 0, 0, 0],
+        airborne: false,
+        lean: 0,
+        leanTrim: 0,
+        jumpsUsed: 0,
+        airTime: 0,
+    };
+}
+/** The lean that balances a lateral acceleration: a bike leans until gravity's moment matches the corner's. */
+function balanceLean(lateralAccel) {
+    return Math.atan(lateralAccel / GRAVITY);
+}
+function clampUnit(value) {
+    return Math.max(-1, Math.min(1, value));
+}
+/** Angular rate driven by input acceleration and slowed by damping, capped at `maxRate` only while input pushes past it. */
+function driveRate(rate, accel, damping, maxRate, h) {
+    let next = rate + (accel - damping * rate) * h;
+    if (Math.abs(next) > maxRate && Math.sign(accel) === Math.sign(next) && Math.abs(next) > Math.abs(rate)) {
+        next = Math.sign(next) * Math.max(maxRate, Math.abs(rate));
+    }
+    return next;
+}