@jgengine/core 0.10.0 → 0.12.0

package/dist/physics/kinematicVehicle.js

@@ -2,34 +2,129 @@ 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);
+    const clampMove = options.clampMove;
     let x = options.position?.[0] ?? 0;
     let y = options.position?.[1] ?? 0;
     let z = options.position?.[2] ?? 0;
     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)];
     }
     return {
-        tick(dt, axis) {
+        tick(dt, axis, modifiers) {
+            const topSpeed = tuning.topSpeed * (modifiers?.topSpeedScale ?? 1);
+            const engineAccel = tuning.engineAccel * (modifiers?.accelScale ?? 1);
+            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, tuning.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 < tuning.topSpeed)
-                accel += axis.throttle * tuning.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 * tuning.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;
@@ -38,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);
@@ -52,15 +177,58 @@ export function createKinematicVehicle(tuning, options = {}) {
                 vx *= dragDamp;
                 vz *= dragDamp;
             }
-            x += vx * dt;
-            z += vz * dt;
+            const toX = x + vx * dt;
+            const toZ = z + vz * dt;
+            if (clampMove !== undefined && dt > 0) {
+                const allowed = clampMove([x, z], [toX, toZ]);
+                vx = (allowed[0] - x) / dt;
+                vz = (allowed[1] - z) / dt;
+                x = allowed[0];
+                z = allowed[1];
+            }
+            else {
+                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,
                 forwardSpeed: vx * fx + vz * fz,
-                lateralSpeed: keptLateral * dragDamp,
+                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 }),
@@ -76,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

@@ -2,6 +2,12 @@ export interface PhysicsBounds {
     min: readonly [number, number, number];
     max: readonly [number, number, number];
 }
+/**
+ * Simulation fidelity intent: `low` (cheap — many bodies, loose stacks, forgiving sleep), `standard`
+ * (default), `high` (tight stacks, accurate joints, worth the extra solver work). Sets the solver
+ * knobs below to a matched preset; an individual knob left explicit always wins over the preset.
+ */
+export type PhysicsPrecision = "low" | "standard" | "high";
 export interface PhysicsWorldConfig {
     /** Maximum bodies the SoA buffers can hold. Fixed at construction; no reallocation later. */
     capacity: number;
@@ -9,8 +15,8 @@ export interface PhysicsWorldConfig {
     bounds: PhysicsBounds;
     /** Downward acceleration applied to awake bodies each substep. Default -20. */
     gravity?: number;
-    /** Broadphase cell edge; tune to ≈ small-body diameter. Default 1. */
-    cellSize?: number;
+    /** Simulation fidelity intent. Default "standard" — see {@link PhysicsPrecision}. */
+    precision?: PhysicsPrecision;
     /** Fixed substep length in seconds. Default 1/60. */
     fixedDt?: number;
     /** Cap on substeps per `step()` — bounds catch-up work, drops the rest. Default 4. */
@@ -23,21 +29,27 @@ export interface PhysicsWorldConfig {
     friction?: number;
     /** Per-second linear velocity damping (physical energy bleed so piles settle and sleep). Default 0.2. */
     linearDamping?: number;
-    /** Sequential-impulse velocity iterations per substep (higher = more stable stacks). Default 4. */
+    /** Speed at or below which a body counts as still. Default 0.08. */
+    sleepLinearVelocity?: number;
+    /** Maximum simultaneous joints the constraint buffers can hold. Default 256. */
+    jointCapacity?: number;
+    /**
+     * @deprecated Advanced escape hatch — tune only when profiling shows the broadphase grid is the
+     * bottleneck; most games never set this. Broadphase cell edge; ideally ≈ small-body diameter.
+     * Default 1.
+     */
+    cellSize?: number;
+    /** @deprecated Advanced escape hatch — prefer `precision`. Sequential-impulse velocity iterations per substep (higher = more stable stacks). */
     solverIterations?: number;
-    /** Baumgarte positional-correction fraction per substep, 0..1. Default 0.2. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Baumgarte positional-correction fraction per substep, 0..1. */
     correctionFactor?: number;
-    /** Penetration tolerated before correction kicks in. Default 0.005. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Penetration tolerated before correction kicks in. Default 0.005. */
     slop?: number;
-    /** Speed at or below which a body counts as still. Default 0.08. */
-    sleepLinearVelocity?: number;
-    /** Consecutive still substeps before a body sleeps. Default 30. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Consecutive still substeps before a body sleeps. */
     sleepThresholdSteps?: number;
-    /** Approach speed a contact must exceed to wake a sleeping body (resting contacts don't). Default 0.5. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Approach speed a contact must exceed to wake a sleeping body (resting contacts don't). */
     wakeThreshold?: number;
-    /** Maximum simultaneous joints the constraint buffers can hold. Default 256. */
-    jointCapacity?: number;
-    /** Baumgarte fraction applied to hard-joint positional error per iteration, 0..1. Default 0.5. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Baumgarte fraction applied to hard-joint positional error per iteration, 0..1. */
     jointCorrection?: number;
 }
 export interface PhysicsStats {
@@ -187,6 +199,7 @@ export declare class PhysicsWorld {
     private jFreeCount;
     private jointHigh;
     private jointActiveCount;
+    private readonly anchorScratch;
     private readonly bodyFree;
     private bodyFreeCount;
     private bodyHigh;
@@ -226,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;
@@ -256,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;
 }