@series-inc/rundot-syncplay 5.23.0 → 5.24.0-beta.0

package/dist/cjs/physics3d-stacking.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDeterministicTower3DScenario = runDeterministicTower3DScenario;
+exports.runDeterministicPyramid3DScenario = runDeterministicPyramid3DScenario;
+exports.runDeterministicMassRatio3DScenario = runDeterministicMassRatio3DScenario;
+exports.runDeterministicKickRecovery3DScenario = runDeterministicKickRecovery3DScenario;
+exports.runDeterministicStackingSuite3D = runDeterministicStackingSuite3D;
+const canonical_js_1 = require("./canonical.js");
+const physics3d_js_1 = require("./physics3d.js");
+const STACK_GRAVITY_Y = -0.02;
+function stackFloor() {
+    return {
+        id: 'floor', kind: 'static', x: 0, y: -1, z: 0, vx: 0, vy: 0, vz: 0,
+        shape: { type: 'box', halfX: 40, halfY: 1, halfZ: 40 }, layer: 1, mask: 1,
+        material: { friction: 10, restitution: 0 },
+    };
+}
+function stackBox(id, x, y, mass, half) {
+    return {
+        id, kind: 'dynamic', x, y, z: 0, vx: 0, vy: 0, vz: 0,
+        orientation: { x: 0, y: 0, z: 0, w: 1 },
+        shape: { type: 'box', halfX: half, halfY: 1, halfZ: half }, layer: 1, mask: 1,
+        material: { friction: 8, restitution: 0 }, mass,
+    };
+}
+// Tilt is reported as the up-axis dot product (1 = upright): no Math.acos —
+// transcendentals are banned in src/ by the static determinism checker. Tests
+// convert degree thresholds to cosines (1° → 0.99985, 3° → 0.99863).
+function bodyUpDot(body) {
+    /* istanbul ignore next -- every dynamic scenario body is authored with an orientation. */
+    const q = body.orientation ?? { x: 0, y: 0, z: 0, w: 1 };
+    return 1 - 2 * (q.x * q.x + q.z * q.z);
+}
+function runScenario(spec) {
+    const runOnce = (bodies) => {
+        let world = (0, physics3d_js_1.createDeterministicPhysicsWorld3D)(bodies);
+        const snapshotFrame = Math.floor(spec.frames / 2);
+        let snapshot = world;
+        for (let frame = 0; frame < spec.frames; frame += 1) {
+            if (frame === snapshotFrame) {
+                snapshot = (0, canonical_js_1.cloneCanonical)(world);
+            }
+            if (spec.impulseAt !== undefined && frame === spec.impulseAt.frame) {
+                world = (0, physics3d_js_1.applyDeterministicImpulse3D)(world, spec.impulseAt.bodyId, spec.impulseAt.impulse, spec.impulseAt.point);
+            }
+            world = (0, physics3d_js_1.stepDeterministicPhysicsWorld3D)(world, { gravityY: STACK_GRAVITY_Y, computeChecksum: false }).world;
+        }
+        return { world, snapshot, snapshotFrame };
+    };
+    const main = runOnce(spec.bodies);
+    // rollback: resume from the mid-run snapshot and replay the identical suffix
+    let restored = main.snapshot;
+    for (let frame = main.snapshotFrame; frame < spec.frames; frame += 1) {
+        if (spec.impulseAt !== undefined && frame === spec.impulseAt.frame) {
+            restored = (0, physics3d_js_1.applyDeterministicImpulse3D)(restored, spec.impulseAt.bodyId, spec.impulseAt.impulse, spec.impulseAt.point);
+        }
+        restored = (0, physics3d_js_1.stepDeterministicPhysicsWorld3D)(restored, { gravityY: STACK_GRAVITY_Y, computeChecksum: false }).world;
+    }
+    const permuted = runOnce([...spec.bodies].reverse());
+    const dyn = main.world.bodies.filter((body) => body.kind === 'dynamic');
+    let minUpDot = 1;
+    let maxXZDrift = 0;
+    let sleepingBodies = 0;
+    const initialById = new Map(spec.bodies.map((body) => [body.id, body]));
+    for (const body of dyn) {
+        const initial = initialById.get(body.id);
+        minUpDot = Math.min(minUpDot, bodyUpDot(body));
+        maxXZDrift = Math.max(maxXZDrift, Math.abs(body.x - initial.x), Math.abs(body.z - initial.z));
+        sleepingBodies += body.sleeping === true ? 1 : 0;
+    }
+    const topBody = dyn.find((body) => body.id === spec.topBodyId);
+    const topYError = Math.abs(topBody.y - spec.expectedY.get(spec.topBodyId));
+    const sortedByExpected = [...spec.expectedY.entries()].sort((l, r) => l[1] - r[1]).map(([id]) => id);
+    const finalYById = new Map(dyn.map((body) => [body.id, body.y]));
+    let verticalOrderPreserved = true;
+    for (let index = 1; index < sortedByExpected.length; index += 1) {
+        const below = finalYById.get(sortedByExpected[index - 1]);
+        const above = finalYById.get(sortedByExpected[index]);
+        verticalOrderPreserved = verticalOrderPreserved && above > below;
+    }
+    const details = (0, physics3d_js_1.contactDetailsDeterministicPhysics3D)(main.world);
+    const maxPenetration = details.reduce((max, contact) => Math.max(max, contact.penetration), 0);
+    const checksum = (0, canonical_js_1.defaultChecksum)(main.world);
+    return {
+        scenario: spec.scenario,
+        frames: spec.frames,
+        dynamicBodies: dyn.length,
+        minUpDot,
+        maxPenetration,
+        maxXZDrift,
+        topYError,
+        sleepingBodies,
+        verticalOrderPreserved,
+        checksum,
+        rollbackEquivalent: checksum === (0, canonical_js_1.defaultChecksum)(restored),
+        stableUnderAuthoringOrderPermutation: checksum === (0, canonical_js_1.defaultChecksum)(permuted.world),
+    };
+}
+function runDeterministicTower3DScenario(layers = 15, frames = 900) {
+    const bodies = [stackFloor(), ...Array.from({ length: layers }, (_, layer) => stackBox(`t${String(layer).padStart(2, '0')}`, 0, 1 + layer * 2, 1, 1))];
+    const expectedY = new Map(Array.from({ length: layers }, (_, layer) => [`t${String(layer).padStart(2, '0')}`, 1 + layer * 2]));
+    return runScenario({ scenario: `tower-${layers}`, bodies, frames, expectedY, topBodyId: `t${String(layers - 1).padStart(2, '0')}` });
+}
+function runDeterministicPyramid3DScenario(base = 10, frames = 600) {
+    const bodies = [stackFloor()];
+    const expectedY = new Map();
+    let id = 0;
+    let topId = '';
+    for (let layer = 0; layer < base; layer += 1) {
+        const count = base - layer;
+        for (let column = 0; column < count; column += 1) {
+            const bodyId = `p${String(id).padStart(3, '0')}`;
+            bodies.push(stackBox(bodyId, (column - (count - 1) / 2) * 2.05, 1 + layer * 2, 1, 1));
+            expectedY.set(bodyId, 1 + layer * 2);
+            topId = bodyId;
+            id += 1;
+        }
+    }
+    return runScenario({ scenario: `pyramid-${base}`, bodies, frames, expectedY, topBodyId: topId });
+}
+function runDeterministicMassRatio3DScenario(ratio = 50, frames = 900) {
+    const bodies = [
+        stackFloor(),
+        stackBox('b0', 0, 1, 1, 1), stackBox('b1', 0, 3, 1, 1), stackBox('b2', 0, 5, 1, 1),
+        stackBox('heavy', 0, 7.2, ratio, 1.5),
+    ];
+    const expectedY = new Map([['b0', 1], ['b1', 3], ['b2', 5], ['heavy', 7.2]]);
+    return runScenario({ scenario: `mass-ratio-${ratio}`, bodies, frames, expectedY, topBodyId: 'heavy' });
+}
+/**
+ * `impulseFrame` past the mid-run snapshot puts the kick inside the *replayed*
+ * suffix, so rollback equivalence proves the impulse is re-applied rather than
+ * merely baked into the snapshot.
+ */
+function runDeterministicKickRecovery3DScenario(layers = 8, frames = 900, impulseFrame = 400) {
+    const bodies = [stackFloor(), ...Array.from({ length: layers }, (_, layer) => stackBox(`t${layer}`, 0, 1 + layer * 2, 1, 1))];
+    const expectedY = new Map(Array.from({ length: layers }, (_, layer) => [`t${layer}`, 1 + layer * 2]));
+    return runScenario({
+        scenario: `kick-recovery-${layers}`,
+        bodies,
+        frames,
+        impulseAt: { frame: impulseFrame, bodyId: 't3', impulse: { x: 0.2, y: 0, z: 0 }, point: { x: 0, y: 7, z: 0 } },
+        expectedY,
+        topBodyId: `t${layers - 1}`,
+    });
+}
+function runDeterministicStackingSuite3D() {
+    return [
+        runDeterministicTower3DScenario(),
+        runDeterministicPyramid3DScenario(),
+        runDeterministicMassRatio3DScenario(),
+        runDeterministicKickRecovery3DScenario(),
+    ];
+}

package/dist/cjs/physics3d-toi.js

@@ -0,0 +1,251 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__toiInternals = void 0;
+exports.toiProxyOf = toiProxyOf;
+exports.gjkCoreDistance = gjkCoreDistance;
+exports.conservativeToi = conservativeToi;
+const physics3d_shared_js_1 = require("./physics3d-shared.js");
+/**
+ * Build a TOI proxy for a solver shape at (pos, q). Returns null for shapes GJK does
+ * not handle here (mesh, compound) — the caller then leaves the body to the discrete
+ * solver (no TOI clamp).
+ */
+function toiProxyOf(shape, pos, q) {
+    if (shape.kind === 'box') {
+        const h = shape.half;
+        const verts = [];
+        for (const sx of [-h.x, h.x]) {
+            for (const sy of [-h.y, h.y]) {
+                for (const sz of [-h.z, h.z]) {
+                    verts.push((0, physics3d_shared_js_1.addVec3)(pos, (0, physics3d_shared_js_1.rotatePointByQuat)(q, { x: sx, y: sy, z: sz })));
+                }
+            }
+        }
+        return { verts, radius: 0 };
+    }
+    if (shape.kind === 'sphere') {
+        return { verts: [pos], radius: shape.radius };
+    }
+    if (shape.kind === 'capsule') {
+        const axis = (0, physics3d_shared_js_1.rotatePointByQuat)(q, { x: 0, y: shape.halfHeight, z: 0 });
+        return { verts: [(0, physics3d_shared_js_1.addVec3)(pos, axis), (0, physics3d_shared_js_1.subVec3)(pos, axis)], radius: shape.radius };
+    }
+    if (shape.kind === 'hull') {
+        return { verts: shape.data.vertices.map((v) => (0, physics3d_shared_js_1.addVec3)(pos, (0, physics3d_shared_js_1.rotatePointByQuat)(q, v))), radius: 0 };
+    }
+    return null;
+}
+function support(verts, dir) {
+    let best = 0;
+    let bestDot = (0, physics3d_shared_js_1.dotVec3)(verts[0], dir);
+    for (let i = 1; i < verts.length; i += 1) {
+        const d = (0, physics3d_shared_js_1.dotVec3)(verts[i], dir);
+        if (d > bestDot) {
+            bestDot = d;
+            best = i;
+        }
+    }
+    return best;
+}
+/** Closest point of a 1–4 vertex simplex (their `w`) to the origin, with barycentric weights. */
+function closestToOrigin(s) {
+    if (s.length === 1) {
+        return { point: s[0].w, keep: [0], bary: [1] };
+    }
+    if (s.length === 2) {
+        return segmentClosest(s[0].w, s[1].w, [0, 1]);
+    }
+    if (s.length === 3) {
+        return triangleClosest(s[0].w, s[1].w, s[2].w, [0, 1, 2]);
+    }
+    return tetraClosest(s[0].w, s[1].w, s[2].w, s[3].w);
+}
+function segmentClosest(a, b, idx) {
+    const ab = (0, physics3d_shared_js_1.subVec3)(b, a);
+    const t = -(0, physics3d_shared_js_1.dotVec3)(a, ab);
+    const denom = (0, physics3d_shared_js_1.dotVec3)(ab, ab);
+    if (t <= 0 || denom === 0) {
+        return { point: a, keep: [idx[0]], bary: [1] };
+    }
+    if (t >= denom) {
+        return { point: b, keep: [idx[1]], bary: [1] };
+    }
+    const u = t / denom;
+    return { point: (0, physics3d_shared_js_1.addVec3)(a, (0, physics3d_shared_js_1.scaleVec3)(ab, u)), keep: [idx[0], idx[1]], bary: [1 - u, u] };
+}
+// Closest point of triangle (a,b,c) to the origin (Ericson RTCD, specialized to p=0),
+// returning barycentric weights over the retained vertices.
+function triangleClosest(a, b, c, idx) {
+    const ab = (0, physics3d_shared_js_1.subVec3)(b, a);
+    const ac = (0, physics3d_shared_js_1.subVec3)(c, a);
+    const ap = (0, physics3d_shared_js_1.scaleVec3)(a, -1);
+    const d1 = (0, physics3d_shared_js_1.dotVec3)(ab, ap);
+    const d2 = (0, physics3d_shared_js_1.dotVec3)(ac, ap);
+    if (d1 <= 0 && d2 <= 0) {
+        return { point: a, keep: [idx[0]], bary: [1] };
+    }
+    const bp = (0, physics3d_shared_js_1.scaleVec3)(b, -1);
+    const d3 = (0, physics3d_shared_js_1.dotVec3)(ab, bp);
+    const d4 = (0, physics3d_shared_js_1.dotVec3)(ac, bp);
+    if (d3 >= 0 && d4 <= d3) {
+        return { point: b, keep: [idx[1]], bary: [1] };
+    }
+    const vc = d1 * d4 - d3 * d2;
+    if (vc <= 0 && d1 >= 0 && d3 <= 0) {
+        const v = d1 / (d1 - d3);
+        return { point: (0, physics3d_shared_js_1.addVec3)(a, (0, physics3d_shared_js_1.scaleVec3)(ab, v)), keep: [idx[0], idx[1]], bary: [1 - v, v] };
+    }
+    const cp = (0, physics3d_shared_js_1.scaleVec3)(c, -1);
+    const d5 = (0, physics3d_shared_js_1.dotVec3)(ab, cp);
+    const d6 = (0, physics3d_shared_js_1.dotVec3)(ac, cp);
+    if (d6 >= 0 && d5 <= d6) {
+        return { point: c, keep: [idx[2]], bary: [1] };
+    }
+    const vb = d5 * d2 - d1 * d6;
+    if (vb <= 0 && d2 >= 0 && d6 <= 0) {
+        const w = d2 / (d2 - d6);
+        return { point: (0, physics3d_shared_js_1.addVec3)(a, (0, physics3d_shared_js_1.scaleVec3)(ac, w)), keep: [idx[0], idx[2]], bary: [1 - w, w] };
+    }
+    const va = d3 * d6 - d5 * d4;
+    if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) {
+        const w = (d4 - d3) / (d4 - d3 + (d5 - d6));
+        const bc = (0, physics3d_shared_js_1.subVec3)(c, b);
+        return { point: (0, physics3d_shared_js_1.addVec3)(b, (0, physics3d_shared_js_1.scaleVec3)(bc, w)), keep: [idx[1], idx[2]], bary: [1 - w, w] };
+    }
+    const denom = 1 / (va + vb + vc);
+    const v = vb * denom;
+    const w = vc * denom;
+    return {
+        point: (0, physics3d_shared_js_1.addVec3)(a, (0, physics3d_shared_js_1.addVec3)((0, physics3d_shared_js_1.scaleVec3)(ab, v), (0, physics3d_shared_js_1.scaleVec3)(ac, w))),
+        keep: [idx[0], idx[1], idx[2]],
+        bary: [1 - v - w, v, w],
+    };
+}
+function outsidePlane(p, a, b, c, d) {
+    const ab = (0, physics3d_shared_js_1.subVec3)(b, a);
+    const ac = (0, physics3d_shared_js_1.subVec3)(c, a);
+    const n = { x: ab.y * ac.z - ab.z * ac.y, y: ab.z * ac.x - ab.x * ac.z, z: ab.x * ac.y - ab.y * ac.x };
+    const signP = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(p, a), n);
+    const signD = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(d, a), n);
+    return signP * signD < 0;
+}
+// Closest point of tetrahedron (a,b,c,d) to the origin (Ericson RTCD, specialized to p=0).
+function tetraClosest(a, b, c, d) {
+    const origin = { x: 0, y: 0, z: 0 };
+    let best = { point: origin, keep: [0, 1, 2, 3], bary: [0, 0, 0, 0] };
+    let bestDist2 = Infinity;
+    let anyOutside = false;
+    const faces = [
+        [0, 1, 2, 3],
+        [0, 2, 3, 1],
+        [0, 3, 1, 2],
+        [1, 3, 2, 0],
+    ];
+    const verts = [a, b, c, d];
+    for (const [i0, i1, i2, i3] of faces) {
+        if (outsidePlane(origin, verts[i0], verts[i1], verts[i2], verts[i3])) {
+            anyOutside = true;
+            const res = triangleClosest(verts[i0], verts[i1], verts[i2], [i0, i1, i2]);
+            const dist2 = (0, physics3d_shared_js_1.dotVec3)(res.point, res.point);
+            if (dist2 < bestDist2) {
+                bestDist2 = dist2;
+                best = res;
+            }
+        }
+    }
+    if (!anyOutside) {
+        return { point: origin, keep: [0, 1, 2, 3], bary: [0, 0, 0, 0] };
+    }
+    return best;
+}
+const GJK_MAX_ITERS = 24;
+const GJK_EPS = 1e-10;
+/** GJK closest distance between two convex cores (proxy vertices, ignoring radii). */
+function gjkCoreDistance(vertsA, vertsB) {
+    let dir = (0, physics3d_shared_js_1.subVec3)(vertsA[0], vertsB[0]);
+    if ((0, physics3d_shared_js_1.dotVec3)(dir, dir) < GJK_EPS) {
+        dir = { x: 1, y: 0, z: 0 };
+    }
+    const mink = (d) => {
+        const a = vertsA[support(vertsA, d)];
+        const b = vertsB[support(vertsB, (0, physics3d_shared_js_1.scaleVec3)(d, -1))];
+        return { w: (0, physics3d_shared_js_1.subVec3)(a, b), a };
+    };
+    let simplex = [mink((0, physics3d_shared_js_1.scaleVec3)(dir, -1))];
+    let closest = simplex[0].w;
+    for (let iter = 0; iter < GJK_MAX_ITERS; iter += 1) {
+        const res = closestToOrigin(simplex);
+        closest = res.point;
+        const dist2 = (0, physics3d_shared_js_1.dotVec3)(closest, closest);
+        if (dist2 < GJK_EPS) {
+            return { distance: 0, normal: { x: 0, y: 0, z: 0 }, overlap: true };
+        }
+        simplex = res.keep.map((i) => simplex[i]);
+        const searchDir = (0, physics3d_shared_js_1.scaleVec3)(closest, -1);
+        const v = mink(searchDir);
+        // No further progress toward the origin ⇒ `closest` is the nearest point.
+        if ((0, physics3d_shared_js_1.dotVec3)(v.w, searchDir) - (0, physics3d_shared_js_1.dotVec3)(closest, searchDir) < GJK_EPS) {
+            break;
+        }
+        /* istanbul ignore next -- a repeated support vertex makes the progress test above zero, so this cycle guard never fires first. */
+        if (simplex.some((s) => (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(s.w, v.w), (0, physics3d_shared_js_1.subVec3)(s.w, v.w)) < GJK_EPS)) {
+            break;
+        }
+        simplex.push(v);
+    }
+    const dist = (0, physics3d_shared_js_1.solverSqrt)((0, physics3d_shared_js_1.dotVec3)(closest, closest));
+    /* istanbul ignore next -- a zero `closest` returns early as an overlap, so `dist` is positive here. */
+    const inv = dist > 0 ? -1 / dist : 0;
+    return { distance: dist, normal: (0, physics3d_shared_js_1.scaleVec3)(closest, inv), overlap: false };
+}
+const TOI_MAX_ITERS = 20;
+const TOI_OVERLAP = { overlapping: true };
+/**
+ * Linear conservative-advancement time-of-impact: how far the `fast` proxy may translate
+ * along unit `dir` (up to `maxDist`) before its surface first touches the stationary
+ * `target` proxy (within `targetSep`), plus the contact normal. Returns `ToiOverlap` if
+ * they already touch at the step start (the discrete solver owns a touching pair, but the
+ * caller must not advance the fast body *past* it), or undefined if they never touch
+ * within `maxDist` (a clean graze / miss).
+ */
+function conservativeToi(fast, dirX, dirY, dirZ, maxDist, target, targetSep) {
+    const dir = { x: dirX, y: dirY, z: dirZ };
+    const radiusSum = fast.radius + target.radius;
+    let s = 0;
+    // Fallback contact normal (opposes motion) until a GJK normal is captured.
+    let hitNormal = { x: -dirX, y: -dirY, z: -dirZ };
+    for (let iter = 0; iter < TOI_MAX_ITERS; iter += 1) {
+        const moved = fast.verts.map((v) => ({ x: v.x + dirX * s, y: v.y + dirY * s, z: v.z + dirZ * s }));
+        const gjk = gjkCoreDistance(target.verts, moved);
+        if (gjk.overlap) {
+            // A corner/edge closest feature gives a slightly off-axis normal, so a step can
+            // overshoot a hair into overlap; `s` is still a valid first contact (penetration
+            // below the advancement step). An overlap at s=0 means already touching at the
+            // start — a blocker the caller must not advance past.
+            return s <= 0 ? TOI_OVERLAP : { distance: s, normal: hitNormal };
+        }
+        const sep = gjk.distance - radiusSum;
+        if (sep <= targetSep) {
+            return s <= 0 ? TOI_OVERLAP : { distance: s, normal: gjk.normal };
+        }
+        hitNormal = gjk.normal;
+        // The target is `sep` away in every direction, so advancing the sweep by `sep`
+        // along `dir` can never cross it (fully conservative — no overshoot even when the
+        // closest feature is a corner giving an off-axis normal). Bail early if the sweep
+        // is moving away from the contact (grazing / separating).
+        if (-(0, physics3d_shared_js_1.dotVec3)(dir, gjk.normal) <= GJK_EPS) {
+            return undefined;
+        }
+        s += sep;
+        if (s >= maxDist) {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Simplex sub-routines, exposed for direct testing. GJK only ever builds a
+ * simplex whose closest feature is interior, so the endpoint/vertex clamps
+ * inside these are unreachable through `gjkCoreDistance` alone.
+ */
+exports.__toiInternals = { segmentClosest, triangleClosest, tetraClosest };

package/dist/cjs/physics3d-vehicle.js

@@ -10,9 +10,12 @@ exports.runDeterministicVehicle3DFixture = runDeterministicVehicle3DFixture;
  * stateless controller reads the chassis pose/velocity from the world, casts
  * each wheel, computes spring-damper suspension + friction-circle tire
  * impulses, and returns them for the game to apply via
- * `applyDeterministicImpulse3D` before the next physics step. v1 is specified
- * against static ground: the controller emits chassis-only impulses (no
- * moving-ground relative velocity, no reaction impulse on the ground body).
+ * `applyDeterministicImpulse3D` before the next physics step. Suspension travel
+ * and tire slip are measured relative to the contacted ground body's surface
+ * velocity (v + ω×r), so moving platforms drag the car; every chassis impulse
+ * against a *dynamic* ground body emits an equal-and-opposite reaction on it
+ * (Newton's third law). Static/kinematic ground absorbs the reaction. The flat
+ * ground-normal assumption is unchanged.
  */
 const canonical_js_1 = require("./canonical.js");
 const math_js_1 = require("./math.js");
@@ -131,13 +134,18 @@ function castWheel(world, chassis, wheel) {
     // No exclude-id query knob exists; post-filter the distance-sorted hits.
     const hit = hits.find((candidate) => candidate.bodyId !== chassis.id);
     if (hit === undefined) {
-        return { grounded: false, compression: 0, groundFriction: 0, anchor, suspensionUp };
+        return { grounded: false, compression: 0, groundFriction: 0, groundVelAtPoint: { x: 0, y: 0, z: 0 }, anchor, suspensionUp };
     }
     const groundBody = (0, physics3d_js_1.deterministicPhysicsBodyById3D)(world, hit.bodyId);
     // hit.distance <= restLength + radius (the ray's maxDistance), so the raw
     // compression is never negative — only the maxTravel clamp is needed.
     const rawCompression = wheel.suspensionRestLength - (hit.distance - wheel.radius);
     const compression = (0, physics3d_shared_js_1.quantizeDistance)(rawCompression > wheel.suspensionMaxTravel ? wheel.suspensionMaxTravel : rawCompression);
+    // Ground-surface velocity at the contact point (v + ω×r); a moving conveyor or
+    // floating raft drags/reacts through it. Static ground contributes nothing.
+    const groundVelAtPoint = groundBody.kind === 'static'
+        ? { x: 0, y: 0, z: 0 }
+        : (0, physics3d_shared_js_1.addVec3)({ x: groundBody.vx, y: groundBody.vy, z: groundBody.vz }, (0, physics3d_shared_js_1.crossVec3)(groundBody.angularVel ?? { x: 0, y: 0, z: 0 }, (0, physics3d_shared_js_1.subVec3)(hit.point, { x: groundBody.x, y: groundBody.y, z: groundBody.z })));
     return {
         grounded: compression > 0,
         compression,
@@ -145,6 +153,8 @@ function castWheel(world, chassis, wheel) {
         point: hit.point,
         normal: hit.normal,
         groundFriction: groundBody.material?.friction ?? 0,
+        groundKind: groundBody.kind,
+        groundVelAtPoint,
         anchor,
         suspensionUp,
     };
@@ -173,8 +183,14 @@ function stepDeterministicVehicle3D(vehicle, input, world, options = {}) {
         chassisVel = (0, physics3d_shared_js_1.addVec3)(chassisVel, (0, physics3d_shared_js_1.scaleVec3)(impulseVec, invMass));
         angularVel = (0, physics3d_shared_js_1.addVec3)(angularVel, (0, physics3d_shared_js_1.mulMat3Vec)(invInertiaWorld, (0, physics3d_shared_js_1.crossVec3)((0, physics3d_shared_js_1.subVec3)(point, chassisPos), impulseVec)));
     };
-    /** Quantize and emit an impulse; returns the quantized impulse (undefined if it rounds to zero). */
-    const emitImpulse = (impulseVec, point) => {
+    /**
+     * Quantize and emit an impulse on the chassis; returns the quantized impulse
+     * (undefined if it rounds to zero). When `reactionBodyId` is set (a dynamic
+     * ground body), emits the equal-and-opposite reaction on it — Newton's third
+     * law so a conveyor/raft feels the car. Reaction entries are NOT fed through
+     * `applyDelta` (that tracks only the chassis's internal velocity state).
+     */
+    const emitImpulse = (impulseVec, point, reactionBodyId) => {
         const quantized = {
             x: (0, physics3d_shared_js_1.quantizeDistance)(impulseVec.x),
             y: (0, physics3d_shared_js_1.quantizeDistance)(impulseVec.y),
@@ -184,6 +200,9 @@ function stepDeterministicVehicle3D(vehicle, input, world, options = {}) {
             return undefined;
         }
         impulses.push({ bodyId: vehicle.chassisId, impulse: quantized, point });
+        if (reactionBodyId !== undefined) {
+            impulses.push({ bodyId: reactionBodyId, impulse: { x: -quantized.x, y: -quantized.y, z: -quantized.z }, point });
+        }
         return quantized;
     };
     // Phase A — suspension for every wheel before any tire force, so tire slip is
@@ -196,11 +215,13 @@ function stepDeterministicVehicle3D(vehicle, input, world, options = {}) {
             return 0;
         }
         const anchorVel = (0, physics3d_shared_js_1.addVec3)(chassisVel, (0, physics3d_shared_js_1.crossVec3)(angularVel, (0, physics3d_shared_js_1.subVec3)(contact.anchor, chassisPos)));
-        const compressionVelocity = -(0, physics3d_shared_js_1.dotVec3)(anchorVel, contact.suspensionUp);
+        // Compression rate is measured relative to the ground surface velocity so a
+        // moving platform doesn't read as spurious suspension travel.
+        const compressionVelocity = -(0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(anchorVel, contact.groundVelAtPoint), contact.suspensionUp);
         const rawForce = wheel.stiffness * contact.compression + wheel.damping * compressionVelocity;
         const suspensionForce = rawForce > 0 ? rawForce : 0;
         const suspensionImpulseMag = suspensionForce * dt;
-        const emitted = emitImpulse((0, physics3d_shared_js_1.scaleVec3)(contact.normal, suspensionImpulseMag), contact.point);
+        const emitted = emitImpulse((0, physics3d_shared_js_1.scaleVec3)(contact.normal, suspensionImpulseMag), contact.point, contact.groundKind === 'dynamic' ? contact.bodyId : undefined);
         if (emitted !== undefined) {
             applyDelta(emitted, contact.point);
         }
@@ -247,6 +268,8 @@ function stepDeterministicVehicle3D(vehicle, input, world, options = {}) {
             effLateralMass: effectiveMassAt(invMass, invInertiaWorld, leverArm, sideDir),
             effForwardMass: effectiveMassAt(invMass, invInertiaWorld, leverArm, forwardDir),
             maxTireImpulse: ((wheel.grip * contact.groundFriction) / 10) * suspensionImpulseMag,
+            groundVelAtPoint: contact.groundVelAtPoint,
+            reactionBodyId: contact.groundKind === 'dynamic' ? contact.bodyId : undefined,
             longitudinal: 0,
             lateral: 0,
             // brake + rolling resistance oppose the forward speed, spent from a fixed
@@ -258,7 +281,9 @@ function stepDeterministicVehicle3D(vehicle, input, world, options = {}) {
     }
     for (let iteration = 0; iteration < TIRE_ITERATIONS; iteration += 1) {
         for (const tire of tireStates) {
-            const contactVel = (0, physics3d_shared_js_1.addVec3)(chassisVel, (0, physics3d_shared_js_1.crossVec3)(angularVel, (0, physics3d_shared_js_1.subVec3)(tire.tirePoint, chassisPos)));
+            // Slip is measured against the ground surface velocity so a conveyor drags
+            // the car and tire forces react back onto a dynamic ground body.
+            const contactVel = (0, physics3d_shared_js_1.subVec3)((0, physics3d_shared_js_1.addVec3)(chassisVel, (0, physics3d_shared_js_1.crossVec3)(angularVel, (0, physics3d_shared_js_1.subVec3)(tire.tirePoint, chassisPos))), tire.groundVelAtPoint);
             const forwardSpeed = (0, physics3d_shared_js_1.dotVec3)(contactVel, tire.forwardDir);
             const lateralSpeed = (0, physics3d_shared_js_1.dotVec3)(contactVel, tire.sideDir);
             if (iteration === 0) {
@@ -289,7 +314,7 @@ function stepDeterministicVehicle3D(vehicle, input, world, options = {}) {
         }
     }
     for (const tire of tireStates) {
-        emitImpulse((0, physics3d_shared_js_1.addVec3)((0, physics3d_shared_js_1.scaleVec3)(tire.forwardDir, tire.longitudinal), (0, physics3d_shared_js_1.scaleVec3)(tire.sideDir, tire.lateral)), tire.tirePoint);
+        emitImpulse((0, physics3d_shared_js_1.addVec3)((0, physics3d_shared_js_1.scaleVec3)(tire.forwardDir, tire.longitudinal), (0, physics3d_shared_js_1.scaleVec3)(tire.sideDir, tire.lateral)), tire.tirePoint, tire.reactionBodyId);
     }
     const wheels = vehicle.wheels.map((wheel, index) => {
         const contact = contacts[index];