@jgengine/core 0.11.0 → 0.12.0

package/dist/physics/flightDynamics.js

@@ -0,0 +1,165 @@
+import { uniformGravity } from "./gravityField.js";
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+const length = (v) => Math.hypot(v[0], v[1], v[2]);
+function axes(rotation) {
+    const [pitch, yaw, roll] = rotation;
+    const sp = Math.sin(pitch);
+    const cp = Math.cos(pitch);
+    const sy = Math.sin(yaw);
+    const cy = Math.cos(yaw);
+    const sr = Math.sin(roll);
+    const cr = Math.cos(roll);
+    const forward = [sy * cp, sp, cy * cp];
+    const flatRight = [cy, 0, -sy];
+    const flatUp = [-sy * sp, cp, -cy * sp];
+    return {
+        forward,
+        right: [flatRight[0] * cr + flatUp[0] * sr, flatUp[1] * sr, flatRight[2] * cr + flatUp[2] * sr],
+        up: [-flatRight[0] * sr + flatUp[0] * cr, flatUp[1] * cr, -flatRight[2] * sr + flatUp[2] * cr],
+    };
+}
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function wrapAngle(value) {
+    let angle = value;
+    while (angle > Math.PI)
+        angle -= Math.PI * 2;
+    while (angle < -Math.PI)
+        angle += Math.PI * 2;
+    return angle;
+}
+/** Six-degree-of-freedom arcade flight model for fixed-wing, helicopter, and VTOL aircraft.
+ * @capability flight-dynamics simulate fixed-wing, helicopter, and VTOL aircraft
+ */
+export function createAircraftDynamics(tuning, options = {}) {
+    let position = [...(options.position ?? [0, 0, 0])];
+    let velocity = [...(options.velocity ?? [0, 0, 0])];
+    let rotation = [...(options.rotation ?? [0, 0, 0])];
+    let angular = [0, 0, 0];
+    let rotor = 0;
+    let lastVerticalSpeed = velocity[1];
+    const gravity = Math.abs(tuning.gravity ?? 9.81);
+    const gravityField = options.gravityField ?? uniformGravity([0, -gravity, 0]);
+    const windAt = options.wind ?? (() => [0, 0, 0]);
+    const groundAt = options.groundHeight ?? (() => 0);
+    return {
+        tick(dt, input) {
+            const stepDt = clamp(dt, 0, 0.05);
+            const wind = windAt(position);
+            const gravityVector = gravityField.sample(position);
+            const gravityMagnitude = Math.max(0.001, length(gravityVector));
+            const relative = [velocity[0] - wind[0], velocity[1] - wind[1], velocity[2] - wind[2]];
+            const airspeed = length(relative);
+            const basis = axes(rotation);
+            const forwardSpeed = dot(relative, basis.forward);
+            const rightSpeed = dot(relative, basis.right);
+            const upSpeed = dot(relative, basis.up);
+            const angleOfAttack = Math.atan2(-upSpeed, Math.max(0.01, Math.abs(forwardSpeed)));
+            const speedAuthority = clamp(airspeed / Math.max(1, tuning.stallSpeed), 0.12, 1);
+            const rotorTarget = tuning.kind === "fixedWing" ? 0 : clamp(input.collective ?? input.throttle, 0, 1);
+            const rotorResponse = Math.max(0.01, tuning.rotorResponse ?? 3.5);
+            rotor += (rotorTarget - rotor) * (1 - Math.exp(-rotorResponse * stepDt));
+            const vectoring = tuning.kind === "vtol" ? clamp(input.vectoring ?? 1, 0, 1) : tuning.kind === "rotorcraft" ? 1 : 0;
+            const transition = tuning.kind === "vtol"
+                ? clamp(Math.max(vectoring, 1 - airspeed / Math.max(1, tuning.vtolTransitionSpeed ?? 32)), 0, 1)
+                : vectoring;
+            const controlAuthority = transition + (1 - transition) * speedAuthority;
+            const rates = tuning.controls;
+            const targets = [
+                clamp(input.pitch, -1, 1) * rates.pitch * controlAuthority,
+                clamp(input.yaw, -1, 1) * rates.yaw * controlAuthority,
+                clamp(input.roll, -1, 1) * rates.roll * controlAuthority,
+            ];
+            const response = 1 - Math.exp(-Math.max(0, rates.response) * stepDt);
+            angular[0] += (targets[0] - angular[0]) * response;
+            angular[1] += (targets[1] - angular[1]) * response;
+            angular[2] += (targets[2] - angular[2]) * response;
+            const damping = Math.max(0, 1 - rates.damping * stepDt);
+            angular[0] *= damping;
+            angular[1] *= damping;
+            angular[2] *= damping;
+            const stability = clamp(rates.stability * stepDt, 0, 1);
+            if (Math.abs(input.pitch) < 0.05)
+                angular[0] += -rotation[0] * stability;
+            if (Math.abs(input.roll) < 0.05)
+                angular[2] += -rotation[2] * stability;
+            rotation[0] = clamp(rotation[0] + angular[0] * stepDt, -Math.PI * 0.49, Math.PI * 0.49);
+            rotation[1] = wrapAngle(rotation[1] + angular[1] * stepDt);
+            rotation[2] = wrapAngle(rotation[2] + angular[2] * stepDt);
+            const updated = axes(rotation);
+            const throttle = clamp(input.throttle, 0, 1);
+            const afterburner = 1 + clamp(input.afterburner ?? 0, 0, 1) * ((tuning.afterburnerMultiplier ?? 1) - 1);
+            const thrustAccel = tuning.maxThrust * throttle * afterburner / Math.max(0.01, tuning.mass);
+            const hoverAccel = (tuning.hoverThrust ?? gravity * tuning.mass * 1.08) * rotor / Math.max(0.01, tuning.mass);
+            const ground = groundAt(position[0], position[2]);
+            const clearance = Math.max(0, position[1] - ground);
+            const groundEffectHeight = Math.max(0.1, tuning.groundEffectHeight ?? 8);
+            const groundEffect = transition > 0 ? 1 + clamp(1 - clearance / groundEffectHeight, 0, 1) * 0.18 : 1;
+            const liftFraction = clamp((Math.abs(forwardSpeed) / Math.max(0.1, tuning.stallSpeed)) ** 2, 0, 1.35);
+            const stallAngle = Math.PI * 0.22;
+            const aoaEfficiency = clamp(1 - Math.max(0, Math.abs(angleOfAttack) - stallAngle) / (Math.PI * 0.3), 0.08, 1);
+            const wingLift = tuning.lift * liftFraction * aoaEfficiency * (1 - transition);
+            const rotorLift = hoverAccel * groundEffect * transition;
+            const forwardThrust = thrustAccel * (1 - transition * 0.82);
+            const cyclicForward = transition * hoverAccel * Math.sin(rotation[0]) * 0.75;
+            const cyclicSide = -transition * hoverAccel * Math.sin(rotation[2]) * 0.75;
+            const dragScale = tuning.drag * (1 + clamp(input.airbrake ?? 0, 0, 1) * 4);
+            const speedRatio = airspeed / Math.max(1, tuning.maxSpeed);
+            const dragAccel = dragScale * airspeed * (1 + speedRatio * speedRatio);
+            const invAir = airspeed > 0.001 ? 1 / airspeed : 0;
+            velocity[0] += (updated.forward[0] * (forwardThrust + cyclicForward) + updated.right[0] * cyclicSide + updated.up[0] * wingLift - relative[0] * invAir * dragAccel - updated.right[0] * rightSpeed * tuning.sideDrag + updated.up[0] * rotorLift + gravityVector[0]) * stepDt;
+            velocity[1] += (updated.forward[1] * (forwardThrust + cyclicForward) + updated.right[1] * cyclicSide + updated.up[1] * wingLift - relative[1] * invAir * dragAccel - updated.right[1] * rightSpeed * tuning.sideDrag + updated.up[1] * rotorLift + gravityVector[1]) * stepDt;
+            velocity[2] += (updated.forward[2] * (forwardThrust + cyclicForward) + updated.right[2] * cyclicSide + updated.up[2] * wingLift - relative[2] * invAir * dragAccel - updated.right[2] * rightSpeed * tuning.sideDrag + updated.up[2] * rotorLift + gravityVector[2]) * stepDt;
+            const newSpeed = length(velocity);
+            if (newSpeed > tuning.maxSpeed * afterburner && newSpeed > 0) {
+                const scale = tuning.maxSpeed * afterburner / newSpeed;
+                velocity[0] *= scale;
+                velocity[1] *= scale;
+                velocity[2] *= scale;
+            }
+            position[0] += velocity[0] * stepDt;
+            position[1] += velocity[1] * stepDt;
+            position[2] += velocity[2] * stepDt;
+            const floor = ground + (tuning.groundClearance ?? 0.6);
+            let grounded = false;
+            if (position[1] < floor) {
+                position[1] = floor;
+                if (velocity[1] < 0)
+                    velocity[1] *= -0.08;
+                velocity[0] *= 0.985;
+                velocity[2] *= 0.985;
+                grounded = true;
+            }
+            const verticalAcceleration = stepDt > 0 ? (velocity[1] - lastVerticalSpeed) / stepDt : 0;
+            lastVerticalSpeed = velocity[1];
+            return {
+                position: [...position],
+                velocity: [...velocity],
+                rotation: [...rotation],
+                forwardSpeed,
+                airspeed,
+                verticalSpeed: velocity[1],
+                angleOfAttack,
+                liftFraction,
+                stalled: transition < 0.5 && (Math.abs(forwardSpeed) < tuning.stallSpeed || aoaEfficiency < 0.35),
+                grounded,
+                gForce: (verticalAcceleration - gravityVector[1]) / gravityMagnitude,
+            };
+        },
+        pose: () => ({ position: [...position], rotation: [...rotation] }),
+        velocity: () => [...velocity],
+        resetTo(nextPosition, nextRotation = [0, 0, 0]) {
+            position = [...nextPosition];
+            velocity = [0, 0, 0];
+            rotation = [...nextRotation];
+            angular = [0, 0, 0];
+            rotor = 0;
+            lastVerticalSpeed = 0;
+        },
+        setVelocity(nextVelocity) {
+            velocity = [...nextVelocity];
+            lastVerticalSpeed = velocity[1];
+        },
+    };
+}

package/dist/physics/gravityField.d.ts

@@ -0,0 +1,25 @@
+/** Three-dimensional acceleration vector sampled from a gravity field. */
+export type GravityVector = readonly [number, number, number];
+/** Position-dependent gravity source used by movement and vehicle simulations. */
+export interface GravityField {
+    sample(position: GravityVector): GravityVector;
+}
+/** Center, strength, and falloff for radial gravity. */
+export interface PointGravityOptions {
+    center: GravityVector;
+    strength: number;
+    falloff?: "constant" | "inverseSquare";
+    minRadius?: number;
+}
+/** Constant vector gravity for ordinary worlds, space stations, and sideways-gravity levels.
+ * @capability gravity-field sample configurable uniform, radial, or combined gravity
+ */
+export declare function uniformGravity(vector?: GravityVector): GravityField;
+/** Radial gravity toward one center, with optional inverse-square falloff for planetary worlds.
+ * @capability gravity-field sample configurable uniform, radial, or combined gravity
+ */
+export declare function pointGravity(options: PointGravityOptions): GravityField;
+/** Adds several gravity sources into one field.
+ * @capability gravity-field sample configurable uniform, radial, or combined gravity
+ */
+export declare function combineGravity(fields: readonly GravityField[]): GravityField;

package/dist/physics/gravityField.js

@@ -0,0 +1,41 @@
+/** Constant vector gravity for ordinary worlds, space stations, and sideways-gravity levels.
+ * @capability gravity-field sample configurable uniform, radial, or combined gravity
+ */
+export function uniformGravity(vector = [0, -9.81, 0]) {
+    return { sample: () => vector };
+}
+/** Radial gravity toward one center, with optional inverse-square falloff for planetary worlds.
+ * @capability gravity-field sample configurable uniform, radial, or combined gravity
+ */
+export function pointGravity(options) {
+    const minRadius = Math.max(0.001, options.minRadius ?? 1);
+    return {
+        sample(position) {
+            const dx = options.center[0] - position[0];
+            const dy = options.center[1] - position[1];
+            const dz = options.center[2] - position[2];
+            const distance = Math.max(minRadius, Math.hypot(dx, dy, dz));
+            const scale = options.falloff === "inverseSquare" ? options.strength / (distance * distance) : options.strength;
+            return [dx / distance * scale, dy / distance * scale, dz / distance * scale];
+        },
+    };
+}
+/** Adds several gravity sources into one field.
+ * @capability gravity-field sample configurable uniform, radial, or combined gravity
+ */
+export function combineGravity(fields) {
+    return {
+        sample(position) {
+            let x = 0;
+            let y = 0;
+            let z = 0;
+            for (const field of fields) {
+                const vector = field.sample(position);
+                x += vector[0];
+                y += vector[1];
+                z += vector[2];
+            }
+            return [x, y, z];
+        },
+    };
+}

package/dist/physics/kinematicVehicle.d.ts

@@ -12,6 +12,77 @@ export interface KinematicVehicleTuning {
     handbrakeGrip: number;
     /** Forward-speed decay per second when coasting (sleds, boats); default `0`. */
     rollingResistance?: number;
+    /** Optional higher-fidelity powertrain. Omit to preserve the direct arcade acceleration model. */
+    powertrain?: KinematicPowertrainTuning;
+    /** Optional bicycle-model steering with speed-sensitive lock and smoothed rack response. */
+    steering?: KinematicSteeringTuning;
+    /** Optional aerodynamic drag/downforce and electronic driver assists. */
+    dynamics?: KinematicDynamicsTuning;
+    /**
+     * Optional mass-and-force chassis layer (#1051). When present it supersedes `engineAccel`/`brakeAccel`
+     * with force/mass dynamics — a tire friction budget, lateral weight transfer, and engine braking — so
+     * vehicles of different mass, drive/brake force, and center-of-gravity drive measurably differently.
+     * Omit to preserve the direct arcade acceleration model exactly.
+     */
+    chassis?: KinematicChassisTuning;
+}
+/**
+ * Mass-and-force chassis layer (#1051); when present it supersedes `engineAccel`/`brakeAccel` with
+ * force/mass dynamics. Drive/brake become forces divided by `massKg`, a per-tick tire friction budget
+ * (`tireGrip` * grip curve * surface * downforce * m * g) is split lateral-first then longitudinal so
+ * hard slides and launches saturate, and `comHeight`/`trackWidth` set weight-transfer washout and body
+ * lean. Coasting decelerates from physical road load, not a per-vehicle constant: rolling resistance
+ * `μ_rr · m · g` always, plus engine braking `ENGINE_BRAKE_FRACTION · engineForce` routed through the
+ * current gear (so it strengthens as the car downshifts) whenever the throttle is lifted and a
+ * `powertrain` is configured. All fields are required; omit the whole block for the legacy model.
+ */
+export interface KinematicChassisTuning {
+    /** Total vehicle mass, kg (1200 compact … 11000 bus); divides every drive/brake force into accel. */
+    massKg: number;
+    /** Peak drive force at the wheels, N — scaled by the powertrain torque curve and throttle. Also sets engine-braking magnitude. */
+    engineForce: number;
+    /** Peak service-brake force, N; still modulated by the existing ABS logic. */
+    brakeForce: number;
+    /** Peak tire friction coefficient μ on an ideal surface (~0.9 street, 1.1 sport, 0.7 bus). */
+    tireGrip: number;
+    /** Center-of-mass height, m (0.45 sports car … 1.4 bus); drives weight transfer and body lean. */
+    comHeight: number;
+    /** Lateral wheel spacing (track width), m; larger resists lateral weight transfer. */
+    trackWidth: number;
+}
+/** Data-first gearbox and torque-curve tuning for a kinematic ground vehicle. */
+export interface KinematicPowertrainTuning {
+    idleRpm: number;
+    redlineRpm: number;
+    shiftUpRpm: number;
+    shiftDownRpm: number;
+    shiftSeconds: number;
+    finalDrive: number;
+    wheelRadius: number;
+    gears: readonly number[];
+    torqueCurve: GripCurve;
+}
+/** Bicycle-model steering settings; all angles are radians. */
+export interface KinematicSteeringTuning {
+    wheelbase: number;
+    maxAngle: number;
+    highSpeedAngle: number;
+    highSpeedAt: number;
+    response: number;
+    yawDamping?: number;
+}
+/** Aerodynamic and electronic-assist settings layered over tire grip. */
+export interface KinematicDynamicsTuning {
+    aerodynamicDrag?: number;
+    downforce?: number;
+    tractionControl?: number;
+    abs?: number;
+    stabilityControl?: number;
+    bodyPitchFactor?: number;
+    bodyRollFactor?: number;
+    maxBodyPitch?: number;
+    maxBodyRoll?: number;
+    attitudeResponse?: number;
 }
 export interface KinematicVehicleOptions {
     position?: readonly [number, number, number];
@@ -51,6 +122,22 @@ export interface KinematicVehicleStep {
     slip: number;
     /** The `surfaceFriction` sample used this tick (`< 1` = off the ideal surface). */
     surface: number;
+    /** One-based forward gear, or `0` while reversing/neutral. */
+    gear: number;
+    rpm: number;
+    steerAngle: number;
+    yawRate: number;
+    longitudinalAcceleration: number;
+    tractionLimited: boolean;
+    absActive: boolean;
+    /**
+     * Demanded drive force exceeded the tire friction budget left after cornering this tick — a
+     * traction-limited launch (#1051). Always `false` without a `chassis` block; distinct from
+     * `tractionLimited`, which stays owned by the traction-control assist.
+     */
+    wheelspin: boolean;
+    bodyPitch: number;
+    bodyRoll: number;
 }
 /**
  * The pure-kinematic arcade car every racing game hand-rolled (#282.1): steer-yaw scaled by speed,

package/dist/physics/kinematicVehicle.js

@@ -2,6 +2,7 @@ import { steerYaw } from "../movement/steering.js";
 import { DEFAULT_GRIP_CURVE, sampleGripCurve } from "./vehicleBody.js";
 export function createKinematicVehicle(tuning, options = {}) {
     const grip = tuning.grip ?? DEFAULT_GRIP_CURVE;
+    const chassis = tuning.chassis;
     const rollingResistance = tuning.rollingResistance ?? 0;
     const surfaceFriction = options.surfaceFriction ?? (() => 1);
     const dragAt = options.dragAt ?? (() => 0);
@@ -12,6 +13,14 @@ export function createKinematicVehicle(tuning, options = {}) {
     let heading = options.heading ?? 0;
     let vx = 0;
     let vz = 0;
+    let gearIndex = 0;
+    let rpm = tuning.powertrain?.idleRpm ?? 0;
+    let shiftRemaining = 0;
+    let steerAngle = 0;
+    let yawRate = 0;
+    let previousForwardSpeed = 0;
+    let bodyPitch = 0;
+    let bodyRoll = 0;
     function forward() {
         return [Math.sin(heading), Math.cos(heading)];
     }
@@ -22,18 +31,100 @@ export function createKinematicVehicle(tuning, options = {}) {
             const turnRate = tuning.turnRate * (modifiers?.turnRateScale ?? 1);
             const [fx0, fz0] = forward();
             const speed = vx * fx0 + vz * fz0;
-            const steerScale = Math.min(1, Math.abs(speed) / tuning.turnSpeedRef);
-            const direction = speed >= 0 ? 1 : -1;
-            heading = steerYaw(heading, axis.steer * steerScale * direction, turnRate, dt);
+            if (tuning.steering === undefined) {
+                const steerScale = Math.min(1, Math.abs(speed) / tuning.turnSpeedRef);
+                const direction = speed >= 0 ? 1 : -1;
+                heading = steerYaw(heading, axis.steer * steerScale * direction, turnRate, dt);
+                yawRate = dt > 0 ? -axis.steer * steerScale * direction * turnRate : 0;
+                steerAngle = axis.steer;
+            }
+            else {
+                const steering = tuning.steering;
+                const speedBlend = Math.min(1, Math.abs(speed) / Math.max(0.001, steering.highSpeedAt));
+                const lock = steering.maxAngle + (steering.highSpeedAngle - steering.maxAngle) * speedBlend;
+                const targetAngle = axis.steer * lock * (modifiers?.turnRateScale ?? 1);
+                const response = 1 - Math.exp(-Math.max(0, steering.response) * Math.max(0, dt));
+                steerAngle += (targetAngle - steerAngle) * response;
+                const targetYaw = Math.abs(speed) < 0.05 ? 0 : -(speed / Math.max(0.1, steering.wheelbase)) * Math.tan(steerAngle);
+                const yawResponse = 1 - Math.exp(-Math.max(0, steering.yawDamping ?? 10) * Math.max(0, dt));
+                yawRate += (targetYaw - yawRate) * yawResponse;
+                heading += yawRate * dt;
+            }
             const [fx, fz] = forward();
             let accel = 0;
-            if (axis.throttle > 0 && speed < topSpeed)
-                accel += axis.throttle * engineAccel;
+            let tractionLimited = false;
+            let absActive = false;
+            let wheelspin = false;
+            // Powertrain state tracks wheel speed EVERY tick (not just under throttle): the engine keeps
+            // spinning with the wheels, so rpm, gear and downshifts stay live while coasting or braking. That
+            // is what makes engine braking below gear-dependent. Drive torque itself is still applied only on
+            // throttle; `gearLeverage` (current ratio / top-gear ratio) is `1` in top gear and grows in the
+            // low gears the car downshifts into as it slows.
+            let torqueFactor = 1;
+            let gearLeverage = 1;
+            if (tuning.powertrain !== undefined) {
+                const powertrain = tuning.powertrain;
+                shiftRemaining = Math.max(0, shiftRemaining - dt);
+                const ratio = powertrain.gears[Math.min(gearIndex, powertrain.gears.length - 1)] ?? 1;
+                const topGearRatio = powertrain.gears[powertrain.gears.length - 1] ?? ratio;
+                gearLeverage = topGearRatio > 0 ? Math.min(ENGINE_BRAKE_MAX_LEVERAGE, ratio / topGearRatio) : 1;
+                const wheelRpm = Math.abs(speed) / Math.max(0.01, powertrain.wheelRadius) * 60 / (Math.PI * 2);
+                rpm = Math.max(powertrain.idleRpm, Math.min(powertrain.redlineRpm, wheelRpm * ratio * powertrain.finalDrive));
+                if (shiftRemaining <= 0 && rpm >= powertrain.shiftUpRpm && gearIndex < powertrain.gears.length - 1) {
+                    gearIndex += 1;
+                    shiftRemaining = powertrain.shiftSeconds;
+                }
+                else if (shiftRemaining <= 0 && rpm <= powertrain.shiftDownRpm && gearIndex > 0) {
+                    gearIndex -= 1;
+                    shiftRemaining = powertrain.shiftSeconds;
+                }
+                const normalizedRpm = (rpm - powertrain.idleRpm) / Math.max(1, powertrain.redlineRpm - powertrain.idleRpm);
+                const torque = sampleGripCurve(powertrain.torqueCurve, normalizedRpm);
+                torqueFactor = torque * (shiftRemaining > 0 ? 0.32 : 1);
+            }
+            if (axis.throttle > 0 && speed < topSpeed) {
+                accel += chassis === undefined
+                    ? axis.throttle * engineAccel * torqueFactor
+                    : (axis.throttle * chassis.engineForce * (modifiers?.accelScale ?? 1) * torqueFactor) / chassis.massKg;
+            }
             if (axis.brake > 0) {
-                if (speed > 0.2)
-                    accel -= axis.brake * tuning.brakeAccel;
-                else if (speed > -tuning.reverseSpeed)
-                    accel -= axis.brake * engineAccel;
+                if (speed > 0.2) {
+                    const abs = tuning.dynamics?.abs ?? 0;
+                    const brakeScale = Math.max(0.15, 1 - abs * Math.max(0, Math.abs(speed) / Math.max(1, topSpeed) - 0.72));
+                    absActive = brakeScale < 0.999;
+                    accel -= chassis === undefined
+                        ? axis.brake * tuning.brakeAccel * brakeScale
+                        : (axis.brake * chassis.brakeForce * brakeScale) / chassis.massKg;
+                }
+                else if (speed > -tuning.reverseSpeed) {
+                    accel -= chassis === undefined
+                        ? axis.brake * engineAccel
+                        : (axis.brake * chassis.engineForce * (modifiers?.accelScale ?? 1)) / chassis.massKg;
+                }
+            }
+            const traction = tuning.dynamics?.tractionControl ?? 0;
+            if (traction > 0 && Math.abs(speed) > 0.5) {
+                const lateral = Math.abs(-vx * fz + vz * fx);
+                const excess = Math.max(0, lateral / (Math.abs(speed) + 1) - 0.18);
+                if (excess > 0) {
+                    accel *= Math.max(0.2, 1 - excess * traction * 3);
+                    tractionLimited = true;
+                }
+            }
+            // Coast resistance for the mass-and-force chassis (#1051) — derived from the vehicle's own weight,
+            // gravity, and gearing, never a flat "brake force" constant. Two weight-based terms:
+            //   • rolling resistance  F = μ_rr · m · g                    (always, the road-load floor)
+            //   • engine braking      F = μ_eb · m · g · gearLeverage     (throttle lifted, in gear)
+            // Engine braking is routed through the CURRENT gear, so it strengthens as the car downshifts toward
+            // a stop — exactly like lifting off in a real drivetrain. Both are forces (∝ m·g) whose per-mass
+            // deceleration is weight-independent and gear-scaled; the per-tick decel is capped so coasting can
+            // never push the car backwards.
+            if (chassis !== undefined && dt > 0 && Math.abs(speed) > 1e-4) {
+                let resistDecel = ROLLING_RESISTANCE_COEFFICIENT * GRAVITY;
+                if (axis.throttle <= 0 && tuning.powertrain !== undefined) {
+                    resistDecel += ENGINE_BRAKE_COEFFICIENT * GRAVITY * gearLeverage;
+                }
+                accel -= Math.sign(speed) * Math.min(resistDecel, Math.abs(speed) / dt);
             }
             vx += fx * accel * dt;
             vz += fz * accel * dt;
@@ -42,11 +133,41 @@ export function createKinematicVehicle(tuning, options = {}) {
             const surface = surfaceFriction(x, z);
             const slip = Math.abs(lateralSpeed) / (Math.abs(forwardSpeed) + 1);
             const handbrakeFactor = 1 - axis.handbrake * (1 - tuning.handbrakeGrip);
-            const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor;
+            const downforce = 1 + (tuning.dynamics?.downforce ?? 0) * Math.min(1, Math.abs(forwardSpeed) / Math.max(1, topSpeed));
+            const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor * downforce;
             const keep = Math.max(0, 1 - gripValue * tuning.gripStrength * dt);
-            const keptLateral = lateralSpeed * keep;
+            const stability = tuning.dynamics?.stabilityControl ?? 0;
+            let keptLateral = lateralSpeed * keep * Math.max(0, 1 - stability * Math.abs(axis.steer) * dt);
+            if (chassis !== undefined) {
+                // Friction budget (#1051): total tire force F = μeff * m * g, with μeff = tireGrip * gripValue
+                // (grip curve * surface * handbrake * downforce). Lateral load transfer (|centripetal accel| *
+                // comHeight / (trackWidth * g), capped ~0.6) shrinks the lateral share so tall/narrow chassis wash
+                // out earlier. Lateral consumes its capped share first; only the remainder feeds drive/brake.
+                const capacity = chassis.tireGrip * gripValue * chassis.massKg * GRAVITY;
+                const transfer = Math.min(0.6, (Math.abs(yawRate * forwardSpeed) * chassis.comHeight) / (Math.max(0.1, chassis.trackWidth) * GRAVITY));
+                const lateralCapacity = capacity * (1 - 0.5 * transfer);
+                const reductionWanted = lateralSpeed - keptLateral;
+                const maxReduction = dt > 0 ? (lateralCapacity * dt) / chassis.massKg : 0;
+                let reductionActual = reductionWanted;
+                if (Math.abs(reductionWanted) > maxReduction) {
+                    reductionActual = Math.sign(reductionWanted) * maxReduction;
+                    keptLateral = lateralSpeed - reductionActual;
+                }
+                const lateralForceUsed = dt > 0 ? (chassis.massKg * Math.abs(reductionActual)) / dt : 0;
+                const remainingLong = Math.max(0, capacity - lateralForceUsed);
+                if (chassis.massKg * Math.abs(accel) > remainingLong) {
+                    const actualAccel = (Math.sign(accel) * remainingLong) / chassis.massKg;
+                    forwardSpeed -= (accel - actualAccel) * dt;
+                    if (accel > 0 && axis.throttle > 0)
+                        wheelspin = true;
+                }
+            }
             if (rollingResistance > 0)
                 forwardSpeed *= Math.max(0, 1 - rollingResistance * dt);
+            const aerodynamicDrag = tuning.dynamics?.aerodynamicDrag ?? 0;
+            if (aerodynamicDrag > 0) {
+                forwardSpeed *= 1 / (1 + aerodynamicDrag * Math.abs(forwardSpeed) * dt);
+            }
             vx = fx * forwardSpeed - fz * keptLateral;
             vz = fz * forwardSpeed + fx * keptLateral;
             const drag = dragAt(x, z);
@@ -69,6 +190,28 @@ export function createKinematicVehicle(tuning, options = {}) {
                 x = toX;
                 z = toZ;
             }
+            // Rest snap (#1051): parked with no throttle/brake/handbrake and sub-threshold motion → exact zero,
+            // killing residual creep and jitter. Zeroing previousForwardSpeed keeps the stop free of a pitch spike.
+            if (chassis !== undefined &&
+                axis.throttle <= 0 &&
+                axis.brake <= 0 &&
+                axis.handbrake <= 0 &&
+                Math.abs(vx * fx + vz * fz) < 0.2 &&
+                Math.abs(-vx * fz + vz * fx) < 0.2) {
+                vx = 0;
+                vz = 0;
+                forwardSpeed = 0;
+                previousForwardSpeed = 0;
+            }
+            const longitudinalAcceleration = dt > 0 ? (forwardSpeed - previousForwardSpeed) / dt : 0;
+            previousForwardSpeed = forwardSpeed;
+            const attitudeResponse = 1 - Math.exp(-Math.max(0, tuning.dynamics?.attitudeResponse ?? 7) * Math.max(0, dt));
+            // comHeight scales brake dive / throttle squat and cornering lean (#1051); `1` without a chassis.
+            const comScale = chassis !== undefined ? chassis.comHeight : 1;
+            const targetPitch = clampSigned(-longitudinalAcceleration * (tuning.dynamics?.bodyPitchFactor ?? 0) * comScale, tuning.dynamics?.maxBodyPitch ?? 0.12);
+            const targetRoll = clampSigned(-yawRate * forwardSpeed * (tuning.dynamics?.bodyRollFactor ?? 0) * comScale, tuning.dynamics?.maxBodyRoll ?? 0.16);
+            bodyPitch += (targetPitch - bodyPitch) * attitudeResponse;
+            bodyRoll += (targetRoll - bodyRoll) * attitudeResponse;
             return {
                 position: [x, y, z],
                 heading,
@@ -76,6 +219,16 @@ export function createKinematicVehicle(tuning, options = {}) {
                 lateralSpeed: -vx * fz + vz * fx,
                 slip,
                 surface,
+                gear: speed < -0.2 ? 0 : gearIndex + 1,
+                rpm,
+                steerAngle,
+                yawRate,
+                longitudinalAcceleration,
+                tractionLimited,
+                absActive,
+                wheelspin,
+                bodyPitch,
+                bodyRoll,
             };
         },
         pose: () => ({ position: [x, y, z], heading }),
@@ -91,6 +244,35 @@ export function createKinematicVehicle(tuning, options = {}) {
             heading = nextHeading;
             vx = 0;
             vz = 0;
+            gearIndex = 0;
+            rpm = tuning.powertrain?.idleRpm ?? 0;
+            shiftRemaining = 0;
+            steerAngle = 0;
+            yawRate = 0;
+            previousForwardSpeed = 0;
+            bodyPitch = 0;
+            bodyRoll = 0;
         },
     };
 }
+/** Gravitational acceleration, m/s², for the chassis friction budget and weight-transfer ratio (#1051). */
+const GRAVITY = 9.81;
+/**
+ * Tyre rolling-resistance coefficient μ_rr (#1051). The always-present coast force is `μ_rr · m · g`
+ * (the road-load floor) — a little high vs. a real ~0.013 tyre so a lifted-off car settles to a stop
+ * in a game-reasonable distance rather than gliding for tens of seconds.
+ */
+const ROLLING_RESISTANCE_COEFFICIENT = 0.03;
+/**
+ * Engine-braking drag as a weight fraction (#1051): the lift-off force is `μ_eb · m · g` routed through
+ * the current gear (`ratio / top-gear ratio`, capped by {@link ENGINE_BRAKE_MAX_LEVERAGE}). Like rolling
+ * resistance it scales with the vehicle's own weight and gravity — not a per-car constant — so every car
+ * settles with a consistent, firm lift-off deceleration that grows as it downshifts toward a stop, while
+ * always staying well short of the service brakes.
+ */
+const ENGINE_BRAKE_COEFFICIENT = 0.11;
+/** Cap on low-gear engine-braking leverage so lifting off never bites as hard as the brake pedal. */
+const ENGINE_BRAKE_MAX_LEVERAGE = 2.5;
+function clampSigned(value, magnitude) {
+    return Math.max(-Math.abs(magnitude), Math.min(Math.abs(magnitude), value));
+}

package/dist/physics/physicsWorld.d.ts

@@ -199,6 +199,7 @@ export declare class PhysicsWorld {
     private jFreeCount;
     private jointHigh;
     private jointActiveCount;
+    private readonly anchorScratch;
     private readonly bodyFree;
     private bodyFreeCount;
     private bodyHigh;
@@ -238,6 +239,13 @@ export declare class PhysicsWorld {
     /** Move a joint's local anchor offset on A (world axes, no rotation applied by the solver). */
     setJointAnchorA(id: number, x: number, y: number, z: number): void;
     setJointRest(id: number, restLength: number): void;
+    /**
+     * Gather joint `id`'s two world anchor points into {@link anchorScratch} as [ax,ay,az,bx,by,bz]
+     * (A's local offset added to body A's centre, or world-origin when A is unset; B likewise, treating
+     * `anchorB` as a world point when B is unset). The single definition shared by {@link jointDistance},
+     * {@link readJointSegments}, and {@link solveJoints}.
+     */
+    private anchorWorld;
     private jointDistance;
     /** Write [ax,ay,az,bx,by,bz] world endpoints per active joint into `out`; returns the joint count. */
     readJointSegments(out: Float32Array): number;
@@ -268,10 +276,28 @@ export declare class PhysicsWorld {
     getStats(): PhysicsStats;
     private substep;
     private constrainBounds;
+    /**
+     * Walk every broadphase cell body `i`'s AABB overlaps, invoking `visit(cell)` once per cell. The
+     * cell-range math (six `cellCoord` calls plus the row-major triple loop) lives here so the count
+     * and scatter passes of {@link buildGrid} share one definition. `visit` is a caller-hoisted closure
+     * (created once per `buildGrid`, not per body) so the hot loop stays allocation-free.
+     */
+    private forEachBodyCell;
     private buildGrid;
     private cellOf;
     private solve;
     private resolve;
+    /**
+     * Apply an axial velocity impulse `jn` along unit axis (nX,nY,nZ) to a joint's two bodies: body A
+     * recoils (−) and body B advances (+), each scaled by its inverse mass. A world anchor (body index
+     * < 0) is skipped. Scalar args only — no allocation on the joint hot path.
+     */
+    private applyAxialImpulse;
+    /**
+     * Positional (Baumgarte) twin of {@link applyAxialImpulse}: nudge the joint's two bodies along
+     * (nX,nY,nZ) by `corr` — body A advances (+), body B recoils (−), each scaled by its inverse mass.
+     */
+    private applyAxialCorrection;
     private solveJoints;
     private updateSleep;
 }