@series-inc/rundot-syncplay 5.23.0-beta.7 → 5.23.0

package/dist/cjs/math.js

@@ -7,9 +7,39 @@ function createDeterministicMath(fixedScale = 1_000, minFixed = DEFAULT_MIN_FIXE
     if (!Number.isInteger(fixedScale) || fixedScale <= 0) {
         throw new Error('fixedScale must be a positive integer');
     }
+    if (fixedScale % 4 !== 0) {
+        // The trig/angle code uses exact quarter- and half-turns (fixedScale/4,
+        // fixedScale/2) as integer angle values.
+        throw new Error('fixedScale must be divisible by 4');
+    }
     if (!Number.isInteger(minFixed) || !Number.isInteger(maxFixed) || minFixed >= maxFixed) {
         throw new Error('fixed range must be integer min < max');
     }
+    const mulFixed = (a, b) => Math.trunc((a * b) / fixedScale);
+    // Odd 5th-order minimax sine over a quarter turn (racing-ugc coefficients,
+    // generalized off its hardcoded ONE=1000 to fixedScale).
+    function sinQuarter(xTurns) {
+        const q = fixedScale / 4;
+        const u = Math.trunc((xTurns * fixedScale) / q); // fixed in [0, fixedScale]
+        const u2 = mulFixed(u, u);
+        const u3 = mulFixed(u2, u);
+        const u5 = mulFixed(u3, u2);
+        return (mulFixed(Math.round(1.5707963 * fixedScale), u) +
+            mulFixed(Math.round(-0.6459641 * fixedScale), u3) +
+            mulFixed(Math.round(0.0796926 * fixedScale), u5));
+    }
+    function sinTurnsImpl(turns) {
+        const q = fixedScale / 4;
+        const t = ((turns % fixedScale) + fixedScale) % fixedScale;
+        const c = (v) => (v < -fixedScale ? -fixedScale : v > fixedScale ? fixedScale : v);
+        if (t < q)
+            return normalizeZero(c(sinQuarter(t)));
+        if (t < 2 * q)
+            return normalizeZero(c(sinQuarter(2 * q - t)));
+        if (t < 3 * q)
+            return normalizeZero(c(-sinQuarter(t - 2 * q)));
+        return normalizeZero(c(-sinQuarter(fixedScale - t)));
+    }
     return {
         fixedScale,
         minFixed,
@@ -83,13 +113,207 @@ function createDeterministicMath(fixedScale = 1_000, minFixed = DEFAULT_MIN_FIXE
             }
             return Math.trunc(value / engine) * engine;
         },
+        sqrt(value) {
+            assertFixed(value);
+            if (value < 0) {
+                throw new Error(`DeterministicMath.sqrt: negative ${value}`);
+            }
+            if (value === 0) {
+                return 0;
+            }
+            const n = value * fixedScale; // ≤ ~2.1e12 < 2^53 for in-range inputs
+            let x = n;
+            let y = Math.trunc((x + 1) / 2);
+            while (y < x) {
+                x = y;
+                y = Math.trunc((x + Math.trunc(n / x)) / 2);
+            }
+            return saturate(x, minFixed, maxFixed);
+        },
+        abs(value) {
+            assertFixed(value);
+            return saturate(value < 0 ? -value : value, minFixed, maxFixed);
+        },
+        sign(value) {
+            assertFixed(value);
+            return value > 0 ? fixedScale : value < 0 ? -fixedScale : 0;
+        },
+        min(a, b) {
+            assertFixed(a);
+            assertFixed(b);
+            return a < b ? a : b;
+        },
+        max(a, b) {
+            assertFixed(a);
+            assertFixed(b);
+            return a > b ? a : b;
+        },
+        lerp(a, b, t) {
+            assertFixed(a);
+            assertFixed(b);
+            assertFixed(t);
+            return saturate(a + Math.trunc(((b - a) * t) / fixedScale), minFixed, maxFixed);
+        },
+        mod(a, b) {
+            assertFixed(a);
+            assertFixed(b);
+            if (b === 0) {
+                throw new Error('DeterministicMath.mod: modulus 0');
+            }
+            const r = a % b;
+            return r !== 0 && r < 0 !== b < 0 ? r + b : r;
+        },
+        inverseLerp(a, b, v) {
+            assertFixed(a);
+            assertFixed(b);
+            assertFixed(v);
+            if (a === b) {
+                return 0;
+            }
+            return saturate(Math.trunc(((v - a) * fixedScale) / (b - a)), minFixed, maxFixed);
+        },
+        remap(inMin, inMax, outMin, outMax, v) {
+            return this.lerp(outMin, outMax, this.inverseLerp(inMin, inMax, v));
+        },
+        smoothstep(edge0, edge1, x) {
+            const t = this.clamp(this.inverseLerp(edge0, edge1, x), 0, fixedScale);
+            const t2 = Math.trunc((t * t) / fixedScale);
+            const t3 = Math.trunc((t2 * t) / fixedScale);
+            return saturate(3 * t2 - 2 * t3, minFixed, maxFixed);
+        },
+        log2Fixed(value) {
+            assertFixed(value);
+            if (value <= 0) {
+                throw new Error(`DeterministicMath.log2Fixed: non-positive ${value}`);
+            }
+            // value = mant * 2^e, mant in [1,2). e via integer scan on value/scale.
+            let e = 0;
+            let v = value;
+            const one = fixedScale;
+            while (v >= 2 * one) {
+                v = Math.trunc(v / 2);
+                e += 1;
+            }
+            while (v < one) {
+                v = v * 2;
+                e -= 1;
+            }
+            const f = v - one; // fixed fractional in [0, one)
+            // Cubic through the origin and the octave boundary (P(1)=1) fitting
+            // log2(1+f) over [0,1): a·f − b·f² + c·f³. Interpolated so mant→2 maps
+            // exactly to the next octave; ≤~2e-3 poly error before truncation.
+            const c1 = Math.round(1.4273 * fixedScale);
+            const c2 = Math.round(0.6018 * fixedScale);
+            const c3 = Math.round(0.1745 * fixedScale);
+            const poly = mulFixed(f, c1 - mulFixed(f, c2 - mulFixed(f, c3)));
+            return e * fixedScale + poly;
+        },
+        log(value) {
+            assertFixed(value);
+            if (value <= 0) {
+                throw new Error(`DeterministicMath.log: non-positive ${value}`);
+            }
+            const LN2 = Math.round(0.6931472 * fixedScale);
+            return saturate(Math.trunc((this.log2Fixed(value) * LN2) / fixedScale), minFixed, maxFixed);
+        },
+        exp(value) {
+            assertFixed(value);
+            // exp(x) = 2^(x/ln2). y = x/ln2 (fixed). yi integer part, yf in [0,1).
+            const INV_LN2 = Math.round(1.4426950 * fixedScale);
+            const y = Math.trunc((value * INV_LN2) / fixedScale);
+            let yi = Math.trunc(y / fixedScale);
+            let yf = y - yi * fixedScale;
+            if (yf < 0) {
+                yf += fixedScale;
+                yi -= 1;
+            }
+            const b1 = Math.round(0.6931472 * fixedScale);
+            const b2 = Math.round(0.2401596 * fixedScale);
+            const b3 = Math.round(0.0521416 * fixedScale);
+            let result = fixedScale + mulFixed(yf, b1 + mulFixed(yf, b2 + mulFixed(yf, b3))); // 2^yf fixed
+            if (yi >= 0) {
+                for (let i = 0; i < yi; i += 1) {
+                    result = saturate(result * 2, minFixed, maxFixed);
+                }
+            }
+            else {
+                for (let i = 0; i < -yi; i += 1) {
+                    result = Math.trunc(result / 2);
+                }
+            }
+            return saturate(result, minFixed, maxFixed);
+        },
         sinTurns(turns) {
             assertFixed(turns);
-            return trigLookup(turns, fixedScale, 'sin');
+            return sinTurnsImpl(turns);
         },
         cosTurns(turns) {
             assertFixed(turns);
-            return trigLookup(turns, fixedScale, 'cos');
+            return sinTurnsImpl(turns + fixedScale / 4);
+        },
+        tanTurns(turns) {
+            assertFixed(turns);
+            return this.div(this.sinTurns(turns), this.cosTurns(turns));
+        },
+        atan2(y, x) {
+            assertFixed(y);
+            assertFixed(x);
+            if (x === 0 && y === 0) {
+                return 0;
+            }
+            const ax = x < 0 ? -x : x;
+            const ay = y < 0 ? -y : y;
+            const swap = ay > ax;
+            const z = this.div(swap ? ax : ay, swap ? ay : ax);
+            const K1 = this.toFixed(Math.PI / 4);
+            const K2 = this.toFixed(0.2447);
+            const K3 = this.toFixed(0.0663);
+            const atanRad = this.add(this.mul(K1, z), this.mul(this.mul(z, this.sub(fixedScale, z)), this.add(K2, this.mul(K3, z))));
+            let turn = this.mul(atanRad, this.toFixed(1 / (2 * Math.PI)));
+            if (swap) {
+                turn = this.sub(fixedScale / 4, turn);
+            }
+            let full;
+            if (x >= 0 && y >= 0) {
+                full = turn;
+            }
+            else if (x < 0 && y >= 0) {
+                full = this.sub(fixedScale / 2, turn);
+            }
+            else if (x < 0 && y < 0) {
+                full = this.add(fixedScale / 2, turn);
+            }
+            else {
+                full = this.sub(fixedScale, turn);
+            }
+            return ((full % fixedScale) + fixedScale) % fixedScale;
+        },
+        wrapTurns(t) {
+            assertFixed(t);
+            return ((t % fixedScale) + fixedScale) % fixedScale;
+        },
+        angleDeltaTurns(a, b) {
+            assertFixed(a);
+            assertFixed(b);
+            const half = fixedScale / 2;
+            let d = (((b - a) % fixedScale) + fixedScale) % fixedScale;
+            if (d >= half) {
+                d -= fixedScale;
+            }
+            return d;
+        },
+        turnsToRadians(t) {
+            assertFixed(t);
+            return saturate(Math.trunc((t * this.toFixed(2 * Math.PI)) / fixedScale), minFixed, maxFixed);
+        },
+        radiansToTurns(r) {
+            assertFixed(r);
+            return saturate(Math.trunc((r * fixedScale) / this.toFixed(2 * Math.PI)), minFixed, maxFixed);
+        },
+        hypot(x, y) {
+            assertFixed(x);
+            assertFixed(y);
+            return this.sqrt(saturate(this.mul(x, x) + this.mul(y, y), minFixed, maxFixed));
         },
         vec2(x, y) {
             assertFixed(x);
@@ -102,6 +326,66 @@ function createDeterministicMath(fixedScale = 1_000, minFixed = DEFAULT_MIN_FIXE
                 y: saturate(a.y + b.y, minFixed, maxFixed),
             };
         },
+        vec2Sub(a, b) {
+            return { x: this.saturatingSub(a.x, b.x), y: this.saturatingSub(a.y, b.y) };
+        },
+        vec2Scale(v, s) {
+            assertFixed(v.x);
+            assertFixed(v.y);
+            assertFixed(s);
+            return { x: this.mul(v.x, s), y: this.mul(v.y, s) };
+        },
+        vec2Dot(a, b) {
+            return saturate(this.mul(a.x, b.x) + this.mul(a.y, b.y), minFixed, maxFixed);
+        },
+        vec2Cross(a, b) {
+            return saturate(this.mul(a.x, b.y) - this.mul(a.y, b.x), minFixed, maxFixed);
+        },
+        vec2LengthSq(v) {
+            return saturate(this.mul(v.x, v.x) + this.mul(v.y, v.y), minFixed, maxFixed);
+        },
+        vec2Length(v) {
+            return this.hypot(v.x, v.y);
+        },
+        vec2DistanceSq(a, b) {
+            return this.vec2LengthSq(this.vec2Sub(a, b));
+        },
+        vec2Distance(a, b) {
+            return this.hypot(this.saturatingSub(a.x, b.x), this.saturatingSub(a.y, b.y));
+        },
+        vec2Normalize(v) {
+            const len = this.hypot(v.x, v.y);
+            return len === 0 ? { x: 0, y: 0 } : { x: this.div(v.x, len), y: this.div(v.y, len) };
+        },
+        vec2Perp(v) {
+            assertFixed(v.x);
+            assertFixed(v.y);
+            return { x: this.saturatingSub(0, v.y), y: v.x };
+        },
+        vec2Negate(v) {
+            assertFixed(v.x);
+            assertFixed(v.y);
+            return { x: this.saturatingSub(0, v.x), y: this.saturatingSub(0, v.y) };
+        },
+        vec2Rotate(v, turns) {
+            assertFixed(v.x);
+            assertFixed(v.y);
+            assertFixed(turns);
+            const c = this.cosTurns(turns);
+            const s = this.sinTurns(turns);
+            return {
+                x: this.saturatingSub(this.mul(v.x, c), this.mul(v.y, s)),
+                y: this.saturatingAdd(this.mul(v.x, s), this.mul(v.y, c)),
+            };
+        },
+        vec2FromAngleTurns(turns, length) {
+            assertFixed(turns);
+            assertFixed(length);
+            return { x: this.mul(this.cosTurns(turns), length), y: this.mul(this.sinTurns(turns), length) };
+        },
+        vec2AngleTurns(v) {
+            return this.atan2(v.y, v.x);
+        },
         vec2Lerp(a, b, t) {
             assertFixed(t);
             return {
@@ -109,14 +393,68 @@ function createDeterministicMath(fixedScale = 1_000, minFixed = DEFAULT_MIN_FIXE
                 y: normalizeZero(a.y + Math.trunc(((b.y - a.y) * t) / fixedScale)),
             };
         },
+        vec3(x, y, z) {
+            assertFixed(x);
+            assertFixed(y);
+            assertFixed(z);
+            return { x, y, z };
+        },
+        vec3Add(a, b) {
+            return {
+                x: saturate(a.x + b.x, minFixed, maxFixed),
+                y: saturate(a.y + b.y, minFixed, maxFixed),
+                z: saturate(a.z + b.z, minFixed, maxFixed),
+            };
+        },
+        vec3Sub(a, b) {
+            return {
+                x: this.saturatingSub(a.x, b.x),
+                y: this.saturatingSub(a.y, b.y),
+                z: this.saturatingSub(a.z, b.z),
+            };
+        },
+        vec3Scale(v, s) {
+            assertFixed(s);
+            return { x: this.mul(v.x, s), y: this.mul(v.y, s), z: this.mul(v.z, s) };
+        },
+        vec3Dot(a, b) {
+            return saturate(this.mul(a.x, b.x) + this.mul(a.y, b.y) + this.mul(a.z, b.z), minFixed, maxFixed);
+        },
+        vec3Cross(a, b) {
+            return {
+                x: this.sub(this.mul(a.y, b.z), this.mul(a.z, b.y)),
+                y: this.sub(this.mul(a.z, b.x), this.mul(a.x, b.z)),
+                z: this.sub(this.mul(a.x, b.y), this.mul(a.y, b.x)),
+            };
+        },
+        vec3LengthSq(v) {
+            return saturate(this.mul(v.x, v.x) + this.mul(v.y, v.y) + this.mul(v.z, v.z), minFixed, maxFixed);
+        },
+        vec3Length(v) {
+            return this.sqrt(this.vec3LengthSq(v));
+        },
+        vec3Distance(a, b) {
+            return this.vec3Length(this.vec3Sub(a, b));
+        },
+        vec3Normalize(v) {
+            const len = this.vec3Length(v);
+            return len === 0 ? { x: 0, y: 0, z: 0 } : { x: this.div(v.x, len), y: this.div(v.y, len), z: this.div(v.z, len) };
+        },
+        vec3Lerp(a, b, t) {
+            assertFixed(t);
+            return { x: this.lerp(a.x, b.x, t), y: this.lerp(a.y, b.y, t), z: this.lerp(a.z, b.z, t) };
+        },
+        vec3Negate(v) {
+            return { x: this.saturatingSub(0, v.x), y: this.saturatingSub(0, v.y), z: this.saturatingSub(0, v.z) };
+        },
         quatFromYawTurns(turns) {
             assertFixed(turns);
             const halfTurns = Math.trunc(turns / 2);
             return {
                 x: 0,
                 y: 0,
-                z: normalizeZero(trigLookup(halfTurns, fixedScale, 'sin')),
-                w: normalizeZero(trigLookup(halfTurns, fixedScale, 'cos')),
+                z: normalizeZero(sinTurnsImpl(halfTurns)),
+                w: normalizeZero(sinTurnsImpl(halfTurns + fixedScale / 4)),
             };
         },
         quatLerp(a, b, t) {
@@ -141,17 +479,6 @@ function assertFixed(value) {
 function saturate(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
-function trigLookup(turns, fixedScale, op) {
-    const normalized = ((turns % fixedScale) + fixedScale) % fixedScale;
-    const quadrant = Math.trunc((normalized * 4) / fixedScale) % 4;
-    const offset = normalized - Math.trunc((quadrant * fixedScale) / 4);
-    const ramp = Math.trunc((offset * fixedScale * 4) / fixedScale);
-    const sin = quadrant === 0 ? ramp : quadrant === 1 ? fixedScale - ramp : quadrant === 2 ? -ramp : -fixedScale + ramp;
-    if (op === 'sin') {
-        return normalizeZero(sin);
-    }
-    return trigLookup(normalized + Math.trunc(fixedScale / 4), fixedScale, 'sin');
-}
 function normalizeZero(value) {
     return Object.is(value, -0) ? 0 : value;
 }

package/dist/cjs/movement3d.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stepDeterministicKcc3D = stepDeterministicKcc3D;
+exports.stepDeterministicCarry3D = stepDeterministicCarry3D;
 exports.runDeterministicKcc3DFilterForceFixture = runDeterministicKcc3DFilterForceFixture;
 exports.runDeterministicKcc3DCallbackFilterFixture = runDeterministicKcc3DCallbackFilterFixture;
 exports.runDeterministicKcc3DCrowdFixture = runDeterministicKcc3DCrowdFixture;
@@ -8,6 +9,7 @@ exports.runDeterministicKcc3DAdversarialFixture = runDeterministicKcc3DAdversari
 exports.runDeterministicKcc3DGeometryFixture = runDeterministicKcc3DGeometryFixture;
 const canonical_js_1 = require("./canonical.js");
 const physics3d_js_1 = require("./physics3d.js");
+const physics3d_shared_js_1 = require("./physics3d-shared.js");
 function stepDeterministicKcc3D(body, input, world, options) {
     let next = applyProcessors(body, input, options.frame, options.processors ?? []);
     const events = [];
@@ -82,6 +84,9 @@ function stepDeterministicKcc3D(body, input, world, options) {
         coyoteFrames = 0;
         events.push(next.grounded ? 'jump' : 'coyote-jump');
     }
+    // The KCC's intended (pre-slide) horizontal position and velocity — push
+    // impulses are computed here because the slide blocks the KCC off the body.
+    const pushCandidate = { x, z, vx, vz };
     if (options.physics !== undefined) {
         const resolved = resolvePhysicsSlide3D(options.physics, next, { x, y, z, vx, vz }, new Set(options.ignoredPhysicsBodyIds ?? []), options.frame, options.collisionFilters ?? []);
         physicsQueryCount += resolved.queryCount;
@@ -96,6 +101,37 @@ function stepDeterministicKcc3D(body, input, world, options) {
             events.push(resolved.swept ? 'physics-sweep' : resolved.slid ? 'physics-slide' : 'physics-correction');
         }
     }
+    const geometryForInteraction = normalizeKccGeometry3D(next);
+    let physicsImpulses = [];
+    // Stand on a dynamic body directly beneath the feet: attach as a platform and
+    // inherit its per-frame delta (its velocity), mirroring the kinematic path.
+    if (options.physics !== undefined && options.standOnDynamicBodies === true && vy <= 0) {
+        const ground = dynamicGroundUnderKcc(options.physics, x, y, z, geometryForInteraction, new Set(options.ignoredPhysicsBodyIds ?? []));
+        if (ground !== undefined) {
+            y = ground.topY;
+            vy = 0;
+            grounded = true;
+            platformId = ground.bodyId;
+            // Carry the rider with the crate this frame (position delta) AND inherit its
+            // velocity, mirroring the kinematic moving-platform path — otherwise the
+            // rider lags one frame and slides off a moving crate.
+            x += ground.deltaX;
+            z += ground.deltaZ;
+            vx += ground.deltaX;
+            vz += ground.deltaZ;
+            events.push('stand-on-dynamic');
+            if (ground.deltaX !== 0 || ground.deltaZ !== 0) {
+                events.push('platform-velocity-transfer');
+            }
+        }
+    }
+    // Push the dynamic bodies the KCC walked into this frame.
+    if (options.physics !== undefined && (options.maxPushImpulse ?? 0) > 0) {
+        physicsImpulses = computeKccPushImpulses(options.physics, pushCandidate.x, y, pushCandidate.z, { vx: pushCandidate.vx, vz: pushCandidate.vz }, geometryForInteraction, options.maxPushImpulse ?? 0, new Set(options.ignoredPhysicsBodyIds ?? []));
+        if (physicsImpulses.length > 0) {
+            events.push('push-dynamic');
+        }
+    }
     const boundsCorrection = clampBodyToBounds({ x, y, z, vx, vy, vz, grounded, coyoteFrames, jumpBufferFrames, platformId }, world);
     if (boundsCorrection.corrected) {
         correctionCount += boundsCorrection.corrections;
@@ -114,9 +150,202 @@ function stepDeterministicKcc3D(body, input, world, options) {
         physicsQueryCount,
         collisionFilterCalls,
         collisionFilterRejectedHits,
-        checksum: (0, canonical_js_1.defaultChecksum)({ body: finalBody, events, correctionCount, physicsQueryCount, collisionFilterCalls, collisionFilterRejectedHits }),
+        physicsImpulses,
+        checksum: (0, canonical_js_1.defaultChecksum)({ body: finalBody, events, correctionCount, physicsQueryCount, collisionFilterCalls, collisionFilterRejectedHits, physicsImpulses }),
     };
 }
+const KCC_PUSH_MASS = 1;
+/** Dynamic physics bodies the KCC capsule overlaps at (x,y,z), sorted by id. */
+function overlappingDynamicBodies(physics, x, y, z, geometry, ignoredBodyIds) {
+    const query = {
+        shape: { type: 'capsule', radius: geometry.radius + geometry.skinWidth, halfHeight: geometry.halfHeight },
+        x,
+        y,
+        z,
+        hitStatics: false,
+        hitDynamics: true,
+        hitKinematics: false,
+    };
+    const hitIds = new Set((0, physics3d_js_1.overlapDeterministicPhysics3D)(physics, query));
+    return physics.bodies
+        .filter((body) => body.kind === 'dynamic' && hitIds.has(body.id) && !ignoredBodyIds.has(body.id))
+        .sort((left, right) => compareStrings(left.id, right.id));
+}
+function computeKccPushImpulses(physics, x, y, z, velocity, geometry, maxPushImpulse, ignoredBodyIds) {
+    const impulses = [];
+    for (const body of overlappingDynamicBodies(physics, x, y, z, geometry, ignoredBodyIds)) {
+        // push along the horizontal direction from the KCC toward the body, scaled
+        // by the KCC's horizontal speed, capped by maxPushImpulse.
+        const toBodyX = body.x - x;
+        const toBodyZ = body.z - z;
+        const dirLen = deterministicKccSqrtLength(toBodyX, toBodyZ);
+        const dirX = dirLen === 0 ? (velocity.vx >= 0 ? 1 : -1) : toBodyX / dirLen;
+        const dirZ = dirLen === 0 ? 0 : toBodyZ / dirLen;
+        const speedIntoBody = Math.max(0, velocity.vx * dirX + velocity.vz * dirZ);
+        if (speedIntoBody === 0) {
+            continue;
+        }
+        const magnitude = Math.min(speedIntoBody * KCC_PUSH_MASS, maxPushImpulse);
+        impulses.push({
+            bodyId: body.id,
+            impulse: { x: dirX * magnitude, y: 0, z: dirZ * magnitude },
+            point: { x: body.x, y, z: body.z },
+        });
+    }
+    return impulses;
+}
+function deterministicKccSqrtLength(dx, dz) {
+    const squared = dx * dx + dz * dz;
+    if (squared <= 0) {
+        return 0;
+    }
+    let estimate = 1;
+    let magnitude = squared;
+    while (magnitude >= 4) {
+        magnitude /= 4;
+        estimate *= 2;
+    }
+    if (magnitude > 1) {
+        estimate *= 2;
+    }
+    for (let iteration = 0; iteration < 8; iteration += 1) {
+        estimate = (estimate + squared / estimate) / 2;
+    }
+    return estimate;
+}
+/**
+ * World-space Y half-extent of a ground body's top surface, honoring full
+ * quaternion orientation (the feet probe is orientation-aware, so the snap height
+ * must be too, or a tilted prop would float/sink). Spheres are orientation
+ * invariant; box/capsule project their local extents onto world +Y.
+ */
+/**
+ * World-space top-surface Y of a body directly under the point (x,z), or
+ * undefined if (x,z) is outside the body's horizontal footprint (so a KCC beside
+ * a body — a side/wall contact — is not treated as standing on it). Compound
+ * bodies resolve per child, so an L-shaped prop reports the flat part's height
+ * when the KCC is over the flat part, not the tallest child's.
+ */
+function groundContactTopAt(body, x, z) {
+    const q = body.orientation ?? { x: 0, y: 0, z: 0, w: 1 };
+    const shape = body.shape;
+    if (shape.type === 'box' || shape.type === 'sphere' || shape.type === 'capsule') {
+        const ext = primitiveHalfExtent(shape, (0, physics3d_shared_js_1.quatToMat3)(q));
+        if (Math.abs(x - body.x) > ext.x || Math.abs(z - body.z) > ext.z) {
+            return undefined;
+        }
+        return body.y + ext.y;
+    }
+    if (shape.type === 'compound') {
+        let top;
+        for (const child of shape.children) {
+            const center = { x: body.x, y: body.y, z: body.z };
+            const worldOffset = (0, physics3d_shared_js_1.rotatePointByQuat)(q, child.offset);
+            const childCenterX = center.x + worldOffset.x;
+            const childCenterZ = center.z + worldOffset.z;
+            const childQ = (0, physics3d_shared_js_1.quatMultiply)(q, (0, physics3d_shared_js_1.quaternionFromQuarterTurns)(child.quarterTurns ?? { x: 0, y: 0, z: 0 }));
+            const childExt = primitiveHalfExtent(child.shape, (0, physics3d_shared_js_1.quatToMat3)(childQ));
+            if (Math.abs(x - childCenterX) > childExt.x || Math.abs(z - childCenterZ) > childExt.z) {
+                continue;
+            }
+            const childTop = center.y + worldOffset.y + childExt.y;
+            top = top === undefined ? childTop : Math.max(top, childTop);
+        }
+        return top;
+    }
+    return undefined; // mesh: static-only, not a stand-on platform
+}
+/** World half-extents (x,y,z) of a primitive shape under rotation matrix `m`. */
+function primitiveHalfExtent(shape, m) {
+    if (shape.type === 'sphere') {
+        return { x: shape.radius, y: shape.radius, z: shape.radius };
+    }
+    if (shape.type === 'box') {
+        return {
+            x: Math.abs(m[0]) * shape.halfX + Math.abs(m[1]) * shape.halfY + Math.abs(m[2]) * shape.halfZ,
+            y: Math.abs(m[3]) * shape.halfX + Math.abs(m[4]) * shape.halfY + Math.abs(m[5]) * shape.halfZ,
+            z: Math.abs(m[6]) * shape.halfX + Math.abs(m[7]) * shape.halfY + Math.abs(m[8]) * shape.halfZ,
+        };
+    }
+    // capsule: segment along local Y, spherical caps radius r
+    return {
+        x: Math.abs(m[1]) * shape.halfHeight + shape.radius,
+        y: Math.abs(m[4]) * shape.halfHeight + shape.radius,
+        z: Math.abs(m[7]) * shape.halfHeight + shape.radius,
+    };
+}
+/** A dynamic body directly under the KCC feet, with its per-frame delta. */
+function dynamicGroundUnderKcc(physics, x, y, z, geometry, ignoredBodyIds) {
+    const feetY = y - geometry.halfHeight - geometry.skinWidth;
+    const probe = {
+        shape: { type: 'sphere', radius: geometry.radius },
+        x,
+        y: feetY,
+        z,
+        hitStatics: false,
+        hitDynamics: true,
+        hitKinematics: false,
+    };
+    const hitIds = new Set((0, physics3d_js_1.overlapDeterministicPhysics3D)(physics, probe));
+    // The KCC must stand OVER the body's horizontal footprint, not beside it —
+    // otherwise walking into a crate's side (a feet-level overlap with a body whose
+    // top towers above the feet) would vault the capsule onto the top.
+    const grounds = physics.bodies
+        .filter((body) => body.kind === 'dynamic' && hitIds.has(body.id) && !ignoredBodyIds.has(body.id))
+        .map((body) => ({ body, top: groundContactTopAt(body, x, z) }))
+        .filter((candidate) => candidate.top !== undefined)
+        .sort((left, right) => right.top - left.top || compareStrings(left.body.id, right.body.id));
+    const ground = grounds[0];
+    if (ground === undefined) {
+        return undefined;
+    }
+    return {
+        bodyId: ground.body.id,
+        topY: ground.top + geometry.halfHeight + geometry.skinWidth,
+        deltaX: ground.body.vx,
+        deltaZ: ground.body.vz,
+    };
+}
+const CARRY_GRAB_MAX_FORCE = 40;
+/**
+ * Drive a `grab` joint target from a carrier pose (the pick-up/carry/throw loop).
+ * While held, returns the grab joint pointing at a hold point ahead of the
+ * carrier; on release, returns a throw impulse (carrier velocity + throw
+ * strength along forward).
+ */
+function stepDeterministicCarry3D(carry, carrierPose) {
+    const forwardLen = deterministicKccSqrtLength3(carrierPose.forwardX, carrierPose.forwardY, carrierPose.forwardZ);
+    const fx = forwardLen === 0 ? 0 : carrierPose.forwardX / forwardLen;
+    const fy = forwardLen === 0 ? 0 : carrierPose.forwardY / forwardLen;
+    const fz = forwardLen === 0 ? 0 : carrierPose.forwardZ / forwardLen;
+    if (carry.released === true) {
+        return {
+            throwImpulse: {
+                bodyId: carry.bodyId,
+                impulse: {
+                    x: carrierPose.vx + fx * carry.throwStrength,
+                    y: carrierPose.vy + fy * carry.throwStrength,
+                    z: carrierPose.vz + fz * carry.throwStrength,
+                },
+            },
+        };
+    }
+    return {
+        joint: {
+            id: `carry-${carry.bodyId}`,
+            type: 'grab',
+            body: carry.bodyId,
+            anchor: { x: 0, y: 0, z: 0 },
+            targetX: carrierPose.x + fx * carry.holdDistance,
+            targetY: carrierPose.y + fy * carry.holdDistance,
+            targetZ: carrierPose.z + fz * carry.holdDistance,
+            maxForce: CARRY_GRAB_MAX_FORCE,
+        },
+    };
+}
+function deterministicKccSqrtLength3(dx, dy, dz) {
+    return deterministicKccSqrtLength(deterministicKccSqrtLength(dx, dy), dz);
+}
 function runDeterministicKcc3DFilterForceFixture() {
     const first = runKcc3DFilterForceCases();
     const second = runKcc3DFilterForceCases();