@jgengine/core 0.18.1 → 0.21.0

package/dist/physics/kinematicVehicle.js

@@ -1,5 +1,10 @@
 import { steerYaw } from "../movement/steering.js";
 import { DEFAULT_GRIP_CURVE, sampleGripCurve } from "./vehicleBody.js";
+/**
+ * Arcade ground-vehicle sim (car, kart, bike) with throttle, brake, steer, drift and retunable handling.
+ *
+ * @capability kinematic-vehicle arcade car/kart driving physics with throttle, brake, steer and retunable handling
+ */
 export function createKinematicVehicle(initialTuning, options = {}) {
     // Mutable so `retune` can swap the whole block without disturbing the integrator's state; every
     // read below is per-tick rather than captured at construction for the same reason.
@@ -231,8 +236,8 @@ export function createKinematicVehicle(initialTuning, options = {}) {
             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;
+                vx = (allowed.motion?.[0] ?? allowed[0] - x) / dt;
+                vz = (allowed.motion?.[1] ?? allowed[1] - z) / dt;
                 x = allowed[0];
                 z = allowed[1];
             }
@@ -309,6 +314,16 @@ export function createKinematicVehicle(initialTuning, options = {}) {
         retune(next) {
             tuning = next;
         },
+        snapshot: () => ({
+            x, y, z, heading, vx, vz, gearIndex, rpm, shiftRemaining, steerAngle, yawRate,
+            previousForwardSpeed, bodyPitch, bodyRoll, airOffset, verticalVelocity,
+        }),
+        restore(state) {
+            ({
+                x, y, z, heading, vx, vz, gearIndex, rpm, shiftRemaining, steerAngle, yawRate,
+                previousForwardSpeed, bodyPitch, bodyRoll, airOffset, verticalVelocity,
+            } = state);
+        },
         resetTo(position, nextHeading) {
             x = position[0];
             y = position[1];

package/dist/physics/physicsBackend.d.ts

@@ -52,6 +52,10 @@ export interface BodyDesc {
     mask?: number;
     /** Continuous collision detection for fast small bodies (bullets, thrown props). */
     ccd?: boolean;
+    /** Per-second linear velocity damping on this body (air drag, water); default `0`. */
+    linearDamping?: number;
+    /** Per-second angular velocity damping on this body; default `0`. Ignored by rotation-free backends. */
+    angularDamping?: number;
     asleep?: boolean;
     userData?: unknown;
 }
@@ -170,6 +174,14 @@ export interface PhysicsBackend {
     setVelocity(handle: BodyHandle, velocity: PhysicsVec3): void;
     setAngularVelocity(handle: BodyHandle, angularVelocity: PhysicsVec3): void;
     applyImpulse(handle: BodyHandle, impulse: PhysicsVec3, point?: PhysicsVec3): void;
+    /**
+     * Apply a world-space force, N, over the next {@link step} only (thrust, wind, buoyancy, a tow rope). Call it
+     * every tick the force should act. A `point` off the centre of mass also applies torque on rotation backends.
+     * Pending forces are not part of a snapshot.
+     */
+    applyForce(handle: BodyHandle, force: PhysicsVec3, point?: PhysicsVec3): void;
+    /** Apply a world-space torque, N·m, over the next {@link step} only; a no-op on rotation-free backends. */
+    applyTorque(handle: BodyHandle, torque: PhysicsVec3): void;
     /** Move a kinematic body so the solver sees its velocity over the next step (platforms, doors, hands). */
     setKinematicTarget(handle: BodyHandle, position: PhysicsVec3, rotation?: PhysicsQuat): void;
     wake(handle: BodyHandle): void;

package/dist/physics/physicsBackendConformance.js

@@ -109,6 +109,40 @@ export function runPhysicsBackendConformance(create, harness) {
         const later = backend.addBody({ shape: { kind: "sphere", radius: 0.3 }, position: [2, 2, 2] });
         expect(later).not.toBe(crate);
     });
+    test("applyForce accelerates at F/m for one step and then stops acting", () => {
+        const backend = create();
+        const held = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [0, 20, 0], mass: 2 });
+        const once = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [10, 20, 0], mass: 2 });
+        backend.applyForce(once, [4, 0, 0]);
+        for (let i = 0; i < 60; i += 1) {
+            backend.applyForce(held, [4, 0, 0]);
+            backend.step(1 / 60);
+        }
+        expect(backend.body(held).velocity[0]).toBeGreaterThan(1.6);
+        expect(backend.body(held).velocity[0]).toBeLessThan(2.2);
+        expect(backend.body(once).velocity[0]).toBeGreaterThan(0.02);
+        expect(backend.body(once).velocity[0]).toBeLessThan(0.05);
+    });
+    test("linear damping bleeds a body's speed faster than an undamped twin", () => {
+        const backend = create();
+        const damped = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [0, 30, 0], velocity: [10, 0, 0], linearDamping: 1.5 });
+        const free = backend.addBody({ shape: { kind: "sphere", radius: 0.5 }, position: [0, 30, 20], velocity: [10, 0, 0] });
+        settle(backend, 1);
+        expect(backend.body(damped).velocity[0]).toBeLessThan(backend.body(free).velocity[0] * 0.5);
+    });
+    test("applyTorque spins a body on rotation backends and is harmless elsewhere", () => {
+        const backend = create();
+        const wheel = backend.addBody({ shape: { kind: "box", halfExtents: [0.5, 0.5, 0.5] }, position: [0, 30, 0] });
+        for (let i = 0; i < 30; i += 1) {
+            backend.applyTorque(wheel, [0, 2, 0]);
+            backend.step(1 / 60);
+        }
+        const spin = backend.body(wheel).angularVelocity[1];
+        if (backend.capabilities.rotation)
+            expect(spin).toBeGreaterThan(0.1);
+        else
+            expect(spin).toBe(0);
+    });
     test("capabilities describe the backend", () => {
         const backend = create();
         expect(backend.capabilities.shapes.length).toBeGreaterThan(1);

package/dist/physics/physicsWorldBackend.d.ts

@@ -21,6 +21,7 @@ interface SavedBody {
     position: [number, number, number];
     velocity: [number, number, number];
     sleeping: boolean;
+    linearDamping?: number;
 }
 /** Serializable backend state: every live body and joint, with handles preserved. */
 export interface PhysicsWorldBackendState {

package/dist/physics/physicsWorldBackend.js

@@ -1,5 +1,10 @@
 import { IDENTITY_QUAT, isIdentityQuat, shapeHalfExtents, } from "./physicsBackend.js";
 import { PhysicsWorld } from "./physicsWorld.js";
+/** Exact touching is not overlap; account for the same few-ulp face rounding as shapecast. */
+function axisOverlaps(center, bodyCenter, combinedHalf) {
+    const tolerance = Number.EPSILON * 8 * Math.max(1, Math.abs(center), Math.abs(bodyCenter - combinedHalf), Math.abs(bodyCenter + combinedHalf));
+    return combinedHalf - Math.abs(bodyCenter - center) > tolerance;
+}
 const ALL_LAYERS = 0xffffffff;
 const CAPABILITIES = {
     rotation: false,
@@ -132,6 +137,8 @@ export function createPhysicsWorldBackend(options) {
             half,
             kinematicVelocity: [0, 0, 0],
             kinematicTarget: null,
+            linearDamping: desc.linearDamping ?? 0,
+            force: [0, 0, 0],
         });
         handleOfIndex.set(index, handle);
         masses.set(handle, desc.mass ?? 1);
@@ -248,6 +255,17 @@ export function createPhysicsWorldBackend(options) {
             const invMass = world.invMass[i];
             world.setVelocity(i, world.velX[i] + impulse[0] * invMass, world.velY[i] + impulse[1] * invMass, world.velZ[i] + impulse[2] * invMass);
         },
+        applyForce(handle, force) {
+            const rec = record(handle);
+            if (rec.kind !== "dynamic")
+                return;
+            rec.force[0] += force[0];
+            rec.force[1] += force[1];
+            rec.force[2] += force[2];
+        },
+        applyTorque(handle) {
+            record(handle);
+        },
         setKinematicTarget(handle, position) {
             const rec = record(handle);
             rec.kinematicTarget = [position[0], position[1], position[2]];
@@ -288,6 +306,24 @@ export function createPhysicsWorldBackend(options) {
                 world.setPosition(i, target[0], target[1], target[2]);
                 rec.kinematicTarget = null;
             }
+            for (const rec of records.values()) {
+                if (rec.kind !== "dynamic")
+                    continue;
+                const f = rec.force;
+                const i = rec.index;
+                if (f[0] !== 0 || f[1] !== 0 || f[2] !== 0) {
+                    const scale = world.invMass[i] * dt;
+                    world.setVelocity(i, world.velX[i] + f[0] * scale, world.velY[i] + f[1] * scale, world.velZ[i] + f[2] * scale);
+                    world.wake(i);
+                    f[0] = 0;
+                    f[1] = 0;
+                    f[2] = 0;
+                }
+                if (rec.linearDamping > 0) {
+                    const keep = Math.max(0, 1 - rec.linearDamping * dt);
+                    world.setVelocity(i, world.velX[i] * keep, world.velY[i] * keep, world.velZ[i] * keep);
+                }
+            }
             world.step(dt);
         },
         raycast(desc) {
@@ -377,6 +413,17 @@ export function createPhysicsWorldBackend(options) {
                         least === 2 ? -1 : least === 3 ? 1 : 0,
                         least === 4 ? -1 : least === 5 ? 1 : 0,
                     ];
+                    // Expanding an AABB by a capsule's half-height can round exact floor contact inside
+                    // by a few ulps. Keep entering contacts and real penetration, but allow departing or
+                    // tangent motion through this numerical touch so it cannot mask a later wall/ceiling.
+                    const faceScale = least < 2
+                        ? Math.max(1, Math.abs(ox), Math.abs(minX), Math.abs(maxX))
+                        : least < 4
+                            ? Math.max(1, Math.abs(oy), Math.abs(minY), Math.abs(maxY))
+                            : Math.max(1, Math.abs(oz), Math.abs(minZ), Math.abs(maxZ));
+                    const touchTolerance = Number.EPSILON * 8 * faceScale;
+                    if (motionLen > 0 && pens[least] <= touchTolerance && mx * normal[0] + my * normal[1] + mz * normal[2] >= 0)
+                        continue;
                 }
                 else {
                     if (!(motionLen > 0))
@@ -406,11 +453,11 @@ export function createPhysicsWorldBackend(options) {
                 if (!bodyMatches(rec, desc.mask, desc.exclude, handle))
                     continue;
                 const i = rec.index;
-                if (Math.abs(world.posX[i] - desc.position[0]) >= rec.half[0] + half[0])
+                if (!axisOverlaps(desc.position[0], world.posX[i], rec.half[0] + half[0]))
                     continue;
-                if (Math.abs(world.posY[i] - desc.position[1]) >= rec.half[1] + half[1])
+                if (!axisOverlaps(desc.position[1], world.posY[i], rec.half[1] + half[1]))
                     continue;
-                if (Math.abs(world.posZ[i] - desc.position[2]) >= rec.half[2] + half[2])
+                if (!axisOverlaps(desc.position[2], world.posZ[i], rec.half[2] + half[2]))
                     continue;
                 out.push(handle);
             }
@@ -437,6 +484,7 @@ export function createPhysicsWorldBackend(options) {
                     position: [world.posX[i], world.posY[i], world.posZ[i]],
                     velocity: [world.velX[i], world.velY[i], world.velZ[i]],
                     sleeping: world.isSleeping(i),
+                    ...(rec.linearDamping > 0 ? { linearDamping: rec.linearDamping } : {}),
                 });
             }
             return {
@@ -465,6 +513,7 @@ export function createPhysicsWorldBackend(options) {
                     layers: body.layers,
                     mask: body.mask,
                     userData: body.userData,
+                    ...(body.linearDamping === undefined ? {} : { linearDamping: body.linearDamping }),
                 }, body.sleeping);
             }
             for (const joint of saved.joints) {

package/dist/physics/spatialGrid.d.ts

@@ -36,6 +36,6 @@ export declare class SpatialGrid {
     rebuild(count: number, xs: Float32Array, zs: Float32Array): void;
     /** Fill `out` with every entity within `radius` of (x,z); returns the hit count (capped at `out.length`). */
     queryCircle(x: number, z: number, radius: number, out: Int32Array): number;
-    /** Invoke `cb(a, b)` once for each unordered pair within `maxDistance` (mutual separation/overlap). */
+    /** Invoke `cb(a, b)` once for each unordered pair within finite, nonnegative `maxDistance`, including distances larger than `cellSize`. */
     forEachPair(maxDistance: number, cb: (a: number, b: number) => void): void;
 }

package/dist/physics/spatialGrid.js

@@ -103,25 +103,24 @@ export class SpatialGrid {
         }
         return n;
     }
-    /** Invoke `cb(a, b)` once for each unordered pair within `maxDistance` (mutual separation/overlap). */
+    /** Invoke `cb(a, b)` once for each unordered pair within finite, nonnegative `maxDistance`, including distances larger than `cellSize`. */
     forEachPair(maxDistance, cb) {
+        if (!Number.isFinite(maxDistance) || maxDistance < 0) {
+            throw new RangeError("SpatialGrid: maxDistance must be finite and nonnegative");
+        }
         const xs = this.xs;
         const zs = this.zs;
         if (xs === null || zs === null)
             return;
         const d2 = maxDistance * maxDistance;
         const nx = this.nx;
-        const nz = this.nz;
         for (let i = 0; i < this.entityCount; i += 1) {
-            const c = this.cellOfBody[i];
-            const cz = (c / nx) | 0;
-            const cx = c - cz * nx;
             const x = xs[i];
             const z = zs[i];
-            const z0 = cz > 0 ? cz - 1 : cz;
-            const z1 = cz < nz - 1 ? cz + 1 : cz;
-            const x0 = cx > 0 ? cx - 1 : cx;
-            const x1 = cx < nx - 1 ? cx + 1 : cx;
+            const z0 = this.cellZ(z - maxDistance);
+            const z1 = this.cellZ(z + maxDistance);
+            const x0 = this.cellX(x - maxDistance);
+            const x1 = this.cellX(x + maxDistance);
             for (let gz = z0; gz <= z1; gz += 1) {
                 const rowBase = gz * nx;
                 for (let gx = x0; gx <= x1; gx += 1) {

package/dist/physics/vehicleBackendLink.d.ts

@@ -0,0 +1,49 @@
+import type { BodyHandle, PhysicsBackend, PhysicsVec3 } from "./physicsBackend.js";
+/** Options for {@link createVehicleBackendLink}. */
+export interface VehicleBackendLinkOptions {
+    /** Chassis collision box half extents, m (width/2, height/2, length/2), heading along +z. */
+    halfExtents: PhysicsVec3;
+    /** Gap kept between the box bottom and the car's base height, so the cast never scrapes the ground (default `0.1`). */
+    clearance?: number;
+    /** Collision layer bitmask of the chassis body (default `1`). */
+    layers?: number;
+    /** Layers the chassis body collides with and shoves in the solver (default all). */
+    mask?: number;
+    /** Layers that stop the car in `clampMove` (default all). Leave props off it so the car shoves them instead of stopping. */
+    blockMask?: number;
+    /** Contact normals steeper than this `y` count as ground, not walls, and never block (default `0.7`). */
+    groundNormalY?: number;
+}
+/** The pose fields {@link VehicleBackendLink.sync} reads; any vehicle step (`VehicleDynamicsStep`, `KinematicVehicleStep`) fits. */
+export interface VehicleLinkPose {
+    position: readonly [number, number, number];
+    heading: number;
+    bodyPitch?: number;
+    bodyRoll?: number;
+}
+/** A wall the last clamped move ran into. */
+export interface VehicleLinkHit {
+    body: BodyHandle;
+    normal: PhysicsVec3;
+    /** Metres of this move the wall absorbed; divide by `dt` for the impact speed. */
+    blocked: number;
+}
+/** A vehicle sim's presence in a physics backend: a kinematic chassis that shoves props, and a wall-aware move clamp. */
+export interface VehicleBackendLink {
+    readonly body: BodyHandle;
+    /** Pass as the sim's `clampMove` option: sweeps the chassis box and stops at walls, sliding along them. */
+    clampMove(from: readonly [number, number], to: readonly [number, number]): readonly [number, number];
+    /** Move the kinematic chassis to the sim's pose; call after each sim tick, before the backend steps. */
+    sync(pose: VehicleLinkPose): void;
+    /** The wall the most recent `clampMove` hit, or `null`. */
+    lastHit(): VehicleLinkHit | null;
+    dispose(): void;
+}
+/**
+ * Puts a vehicle sim (`createVehicleDynamics`, `createKinematicVehicle`) into a {@link PhysicsBackend} world without
+ * handing its handling to the rigid-body solver: the sim still owns grip and balance, while a kinematic chassis box
+ * follows it so Rapier or `PhysicsWorld` props get shoved, and `clampMove` sweeps that box so walls and parked cars
+ * stop it and it slides along them.
+ * @capability vehicle-backend-link collide a vehicle sim with a physics backend — shove props, stop at walls, slide along them
+ */
+export declare function createVehicleBackendLink(backend: PhysicsBackend, options: VehicleBackendLinkOptions): VehicleBackendLink;

package/dist/physics/vehicleBackendLink.js

@@ -0,0 +1,102 @@
+/** Yaw about +y (heading), then pitch about the car's x, then roll about its z, as a quaternion. */
+function poseQuat(heading, pitch, roll) {
+    const hy = heading / 2;
+    const hp = pitch / 2;
+    const hr = roll / 2;
+    const cy = Math.cos(hy);
+    const sy = Math.sin(hy);
+    const cp = Math.cos(hp);
+    const sp = Math.sin(hp);
+    const cr = Math.cos(hr);
+    const sr = Math.sin(hr);
+    return [
+        cy * sp * cr + sy * cp * sr,
+        sy * cp * cr - cy * sp * sr,
+        cy * cp * sr - sy * sp * cr,
+        cy * cp * cr + sy * sp * sr,
+    ];
+}
+/**
+ * Puts a vehicle sim (`createVehicleDynamics`, `createKinematicVehicle`) into a {@link PhysicsBackend} world without
+ * handing its handling to the rigid-body solver: the sim still owns grip and balance, while a kinematic chassis box
+ * follows it so Rapier or `PhysicsWorld` props get shoved, and `clampMove` sweeps that box so walls and parked cars
+ * stop it and it slides along them.
+ * @capability vehicle-backend-link collide a vehicle sim with a physics backend — shove props, stop at walls, slide along them
+ */
+export function createVehicleBackendLink(backend, options) {
+    const half = options.halfExtents;
+    const clearance = options.clearance ?? 0.1;
+    const groundNormalY = options.groundNormalY ?? 0.7;
+    const shape = { kind: "box", halfExtents: half };
+    const pose = { baseY: 0, heading: 0, pitch: 0, roll: 0 };
+    const hit = { active: false, value: { body: -1, normal: [0, 0, 0], blocked: 0 } };
+    const body = backend.addBody({
+        shape,
+        kind: "kinematic",
+        position: [0, half[1] + clearance, 0],
+        layers: options.layers ?? 1,
+        ...(options.mask === undefined ? {} : { mask: options.mask }),
+    });
+    function sweep(x, z, dx, dz) {
+        return backend.shapecast({
+            shape,
+            position: [x, pose.baseY + half[1] + clearance, z],
+            rotation: poseQuat(pose.heading, 0, 0),
+            motion: [dx, 0, dz],
+            exclude: body,
+            ...(options.blockMask === undefined ? {} : { mask: options.blockMask }),
+        });
+    }
+    return {
+        body,
+        clampMove(from, to) {
+            hit.active = false;
+            let x = from[0];
+            let z = from[1];
+            let dx = to[0] - x;
+            let dz = to[1] - z;
+            for (let pass = 0; pass < 2; pass += 1) {
+                const length = Math.hypot(dx, dz);
+                if (length < 1e-9)
+                    break;
+                const found = sweep(x, z, dx, dz);
+                if (found === null || found.normal[1] > groundNormalY) {
+                    x += dx;
+                    z += dz;
+                    break;
+                }
+                const travel = Math.max(0, found.toi - 0.02 / length);
+                x += dx * travel;
+                z += dz * travel;
+                const nx = found.normal[0];
+                const nz = found.normal[2];
+                const flat = Math.hypot(nx, nz) || 1;
+                const restX = dx * (1 - travel);
+                const restZ = dz * (1 - travel);
+                const into = (restX * nx + restZ * nz) / flat;
+                hit.active = true;
+                hit.value = { body: found.body, normal: [nx / flat, 0, nz / flat], blocked: Math.abs(into) };
+                dx = restX - (into * nx) / flat;
+                dz = restZ - (into * nz) / flat;
+            }
+            return [x, z];
+        },
+        sync(next) {
+            pose.baseY = next.position[1];
+            pose.heading = next.heading;
+            pose.pitch = next.bodyPitch ?? 0;
+            pose.roll = next.bodyRoll ?? 0;
+            const center = [next.position[0], next.position[1] + half[1] + clearance, next.position[2]];
+            const rotation = poseQuat(pose.heading, pose.pitch, pose.roll);
+            backend.setKinematicTarget(body, center, rotation);
+            // A resting prop sleeps, and a kinematic body moved by target does not wake it on every backend.
+            for (const touched of backend.overlap({ shape, position: center, rotation, exclude: body }))
+                backend.wake(touched);
+        },
+        lastHit: () => (hit.active ? hit.value : null),
+        dispose() {
+            if (backend.hasBody(body))
+                backend.removeBody(body);
+        },
+    };
+}