@woosh/meep-engine 2.138.19 → 2.139.0

package/src/engine/physics/narrowphase/narrowphase_step.js

@@ -0,0 +1,382 @@
+import { body_id_index } from "../body/BodyStorage.js";
+import { expanding_polytope_algorithm } from "../gjk/expanding_polytope_algorithm.js";
+import { gjk } from "../gjk/gjk.js";
+import { box_box_manifold, BOX_BOX_OUT_LENGTH } from "./box_box_manifold.js";
+import {
+    CAPSULE_BOX_CONTACT_STRIDE,
+    CAPSULE_BOX_MAX_CONTACTS,
+    capsule_box_multi_contacts,
+    capsule_capsule_contact,
+    capsule_sphere_contact,
+} from "./capsule_contacts.js";
+import { PosedShape } from "./PosedShape.js";
+import { sphere_box_contact } from "./sphere_box_contact.js";
+import { sphere_sphere_contact } from "./sphere_sphere_contact.js";
+
+const posed_a = new PosedShape();
+const posed_b = new PosedShape();
+
+const simplex_buf = new Float32Array(12);
+const simplex_a = simplex_buf.subarray(0, 3);
+const simplex_b = simplex_buf.subarray(3, 6);
+const simplex_c = simplex_buf.subarray(6, 9);
+const simplex_d = simplex_buf.subarray(9, 12);
+
+const epa_result = new Float64Array(3);
+const sphere_result = new Float64Array(4);
+const closed_form_result = new Float64Array(10);
+const box_manifold_result = new Float64Array(BOX_BOX_OUT_LENGTH);
+const capsule_box_multi_result = new Float64Array(CAPSULE_BOX_MAX_CONTACTS * CAPSULE_BOX_CONTACT_STRIDE);
+
+/**
+ * Candidate-contact stride: wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth.
+ * @type {number}
+ */
+const CANDIDATE_STRIDE = 10;
+
+/**
+ * Maximum number of contacts emitted into the per-pair manifold after the
+ * reduction step. Mirrors {@link MAX_CONTACTS_PER_MANIFOLD} in ManifoldStore.
+ * @type {number}
+ */
+const MAX_KEPT = 4;
+
+/**
+ * Per body-pair scratch buffer for candidate contacts produced by the
+ * cross-product of A's colliders × B's colliders. Sized generously for
+ * typical compound bodies (each collider-pair contributes 1..4 contacts;
+ * 64 covers up to 4 colliders per body × 4 colliders × 4 contacts = 64).
+ * @type {Float64Array}
+ */
+const candidates = new Float64Array(64 * CANDIDATE_STRIDE);
+
+/**
+ * Append one contact to the candidate buffer. Returns the new count.
+ *
+ * @param {number} count
+ * @param {number} wax
+ * @param {number} way
+ * @param {number} waz
+ * @param {number} wbx
+ * @param {number} wby
+ * @param {number} wbz
+ * @param {number} nx
+ * @param {number} ny
+ * @param {number} nz
+ * @param {number} depth
+ * @returns {number}
+ */
+function append_contact(count, wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth) {
+    if (count * CANDIDATE_STRIDE >= candidates.length) return count;
+    const off = count * CANDIDATE_STRIDE;
+    candidates[off]     = wax; candidates[off + 1] = way; candidates[off + 2] = waz;
+    candidates[off + 3] = wbx; candidates[off + 4] = wby; candidates[off + 5] = wbz;
+    candidates[off + 6] = nx;  candidates[off + 7] = ny;  candidates[off + 8] = nz;
+    candidates[off + 9] = depth;
+    return count + 1;
+}
+
+function swap_candidate(i, j) {
+    if (i === j) return;
+    const oi = i * CANDIDATE_STRIDE;
+    const oj = j * CANDIDATE_STRIDE;
+    for (let k = 0; k < CANDIDATE_STRIDE; k++) {
+        const t = candidates[oi + k];
+        candidates[oi + k] = candidates[oj + k];
+        candidates[oj + k] = t;
+    }
+}
+
+/**
+ * Reduce an in-place candidate list to at most {@link MAX_KEPT} entries:
+ *   1. Move the deepest to slot 0.
+ *   2. For each subsequent slot, pick the remaining candidate whose minimum
+ *      distance to the already-kept set is largest (approximates max-area).
+ *
+ * @param {number} n
+ * @returns {number} kept count, in [0, min(n, MAX_KEPT)]
+ */
+function reduce_candidates(n) {
+    if (n <= MAX_KEPT) return n;
+
+    // Move deepest to slot 0.
+    let deepest_idx = 0;
+    let deepest_val = candidates[9];
+    for (let i = 1; i < n; i++) {
+        const d = candidates[i * CANDIDATE_STRIDE + 9];
+        if (d > deepest_val) { deepest_val = d; deepest_idx = i; }
+    }
+    swap_candidate(0, deepest_idx);
+
+    for (let k = 1; k < MAX_KEPT; k++) {
+        let best_score = -1;
+        let best_i = -1;
+        for (let i = k; i < n; i++) {
+            let min_d2 = Infinity;
+            for (let j = 0; j < k; j++) {
+                const dx = candidates[i * CANDIDATE_STRIDE]     - candidates[j * CANDIDATE_STRIDE];
+                const dy = candidates[i * CANDIDATE_STRIDE + 1] - candidates[j * CANDIDATE_STRIDE + 1];
+                const dz = candidates[i * CANDIDATE_STRIDE + 2] - candidates[j * CANDIDATE_STRIDE + 2];
+                const d2 = dx * dx + dy * dy + dz * dz;
+                if (d2 < min_d2) min_d2 = d2;
+            }
+            if (min_d2 > best_score) { best_score = min_d2; best_i = i; }
+        }
+        swap_candidate(k, best_i);
+    }
+    return MAX_KEPT;
+}
+
+/**
+ * Run pairwise narrowphase for one (colliderA, colliderB) tuple — dispatches
+ * by shape type and appends 0..K contacts to the candidate buffer. Returns
+ * the new candidate count.
+ *
+ * @param {number} count
+ * @param {Collider} colA
+ * @param {Transform} trA
+ * @param {Collider} colB
+ * @param {Transform} trB
+ * @returns {number}
+ */
+function dispatch_pair(count, colA, trA, colB, trB) {
+    const shapeA = colA.shape;
+    const shapeB = colB.shape;
+    const isSphereA = shapeA.isUnitSphereShape3D === true;
+    const isSphereB = shapeB.isUnitSphereShape3D === true;
+    // isBoxShape3D covers both UnitCubeShape3D (fixed 0.5) and BoxShape3D
+    // (arbitrary half-extents). Both expose `half_extents` as a Vector3.
+    const isBoxA    = shapeA.isBoxShape3D        === true;
+    const isBoxB    = shapeB.isBoxShape3D        === true;
+    const isCapsuleA = shapeA.isCapsuleShape3D   === true;
+    const isCapsuleB = shapeB.isCapsuleShape3D   === true;
+
+    // sphere-sphere
+    if (isSphereA && isSphereB) {
+        const ok = sphere_sphere_contact(
+            sphere_result,
+            trA.position.x, trA.position.y, trA.position.z,
+            trB.position.x, trB.position.y, trB.position.z,
+            1, 1
+        );
+        if (!ok) return count;
+        const nx = sphere_result[0], ny = sphere_result[1], nz = sphere_result[2];
+        return append_contact(count,
+            trA.position.x - nx, trA.position.y - ny, trA.position.z - nz,
+            trB.position.x + nx, trB.position.y + ny, trB.position.z + nz,
+            nx, ny, nz, sphere_result[3]);
+    }
+
+    // sphere ↔ box
+    if ((isSphereA && isBoxB) || (isBoxA && isSphereB)) {
+        const sphereTr = isSphereA ? trA : trB;
+        const boxTr    = isSphereA ? trB : trA;
+        const boxShape = isSphereA ? shapeB : shapeA;
+        const bh = boxShape.half_extents;
+        const ok = sphere_box_contact(
+            closed_form_result,
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1,
+            boxTr.position.x, boxTr.position.y, boxTr.position.z,
+            boxTr.rotation.x, boxTr.rotation.y, boxTr.rotation.z, boxTr.rotation.w,
+            bh.x, bh.y, bh.z
+        );
+        if (!ok) return count;
+        let nx = closed_form_result[0], ny = closed_form_result[1], nz = closed_form_result[2];
+        const depth = closed_form_result[3];
+        const wsx = closed_form_result[4], wsy = closed_form_result[5], wsz = closed_form_result[6];
+        const wbx = closed_form_result[7], wby = closed_form_result[8], wbz = closed_form_result[9];
+        if (isSphereA) {
+            return append_contact(count, wsx, wsy, wsz, wbx, wby, wbz, nx, ny, nz, depth);
+        } else {
+            return append_contact(count, wbx, wby, wbz, wsx, wsy, wsz, -nx, -ny, -nz, depth);
+        }
+    }
+
+    // box-box multi-point
+    if (isBoxA && isBoxB) {
+        const ah = shapeA.half_extents;
+        const bh = shapeB.half_extents;
+        const ok = box_box_manifold(
+            box_manifold_result,
+            trA.position.x, trA.position.y, trA.position.z,
+            trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w,
+            ah.x, ah.y, ah.z,
+            trB.position.x, trB.position.y, trB.position.z,
+            trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w,
+            bh.x, bh.y, bh.z
+        );
+        if (!ok) return count;
+        const nx = box_manifold_result[0], ny = box_manifold_result[1], nz = box_manifold_result[2];
+        const cc = box_manifold_result[3] | 0;
+        for (let k = 0; k < cc; k++) {
+            const base = 4 + k * 7;
+            count = append_contact(count,
+                box_manifold_result[base],     box_manifold_result[base + 1], box_manifold_result[base + 2],
+                box_manifold_result[base + 3], box_manifold_result[base + 4], box_manifold_result[base + 5],
+                nx, ny, nz,
+                box_manifold_result[base + 6]);
+        }
+        return count;
+    }
+
+    // capsule-capsule
+    if (isCapsuleA && isCapsuleB) {
+        const a_shape = colA.shape, b_shape = colB.shape;
+        const ok = capsule_capsule_contact(
+            closed_form_result,
+            trA.position.x, trA.position.y, trA.position.z,
+            trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w,
+            a_shape.radius, a_shape.height * 0.5,
+            trB.position.x, trB.position.y, trB.position.z,
+            trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w,
+            b_shape.radius, b_shape.height * 0.5
+        );
+        if (!ok) return count;
+        return append_contact(count,
+            closed_form_result[4], closed_form_result[5], closed_form_result[6],
+            closed_form_result[7], closed_form_result[8], closed_form_result[9],
+            closed_form_result[0], closed_form_result[1], closed_form_result[2],
+            closed_form_result[3]);
+    }
+
+    // capsule ↔ sphere
+    if ((isCapsuleA && isSphereB) || (isSphereA && isCapsuleB)) {
+        const capsuleTr = isCapsuleA ? trA : trB;
+        const capsuleShape = isCapsuleA ? colA.shape : colB.shape;
+        const sphereTr    = isCapsuleA ? trB : trA;
+        const ok = capsule_sphere_contact(
+            closed_form_result,
+            capsuleTr.position.x, capsuleTr.position.y, capsuleTr.position.z,
+            capsuleTr.rotation.x, capsuleTr.rotation.y, capsuleTr.rotation.z, capsuleTr.rotation.w,
+            capsuleShape.radius, capsuleShape.height * 0.5,
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1
+        );
+        if (!ok) return count;
+        let nx = closed_form_result[0], ny = closed_form_result[1], nz = closed_form_result[2];
+        const depth = closed_form_result[3];
+        const cap_x = closed_form_result[4], cap_y = closed_form_result[5], cap_z = closed_form_result[6];
+        const sph_x = closed_form_result[7], sph_y = closed_form_result[8], sph_z = closed_form_result[9];
+        if (isCapsuleA) {
+            return append_contact(count, cap_x, cap_y, cap_z, sph_x, sph_y, sph_z, nx, ny, nz, depth);
+        } else {
+            return append_contact(count, sph_x, sph_y, sph_z, cap_x, cap_y, cap_z, -nx, -ny, -nz, depth);
+        }
+    }
+
+    // capsule ↔ box (multi-point — 1 closest-segment + up to 2 cap-centres)
+    if ((isCapsuleA && isBoxB) || (isBoxA && isCapsuleB)) {
+        const capsuleTr = isCapsuleA ? trA : trB;
+        const capsuleShape = isCapsuleA ? shapeA : shapeB;
+        const boxTr       = isCapsuleA ? trB : trA;
+        const boxShape    = isCapsuleA ? shapeB : shapeA;
+        const bh = boxShape.half_extents;
+        const cc = capsule_box_multi_contacts(
+            capsule_box_multi_result,
+            capsuleTr.position.x, capsuleTr.position.y, capsuleTr.position.z,
+            capsuleTr.rotation.x, capsuleTr.rotation.y, capsuleTr.rotation.z, capsuleTr.rotation.w,
+            capsuleShape.radius, capsuleShape.height * 0.5,
+            boxTr.position.x, boxTr.position.y, boxTr.position.z,
+            boxTr.rotation.x, boxTr.rotation.y, boxTr.rotation.z, boxTr.rotation.w,
+            bh.x, bh.y, bh.z
+        );
+        if (cc === 0) return count;
+        // multi_result layout per contact: cap_x/y/z (A side), box_x/y/z (B side), nx/ny/nz, depth.
+        for (let k = 0; k < cc; k++) {
+            const o = k * CAPSULE_BOX_CONTACT_STRIDE;
+            const cap_x = capsule_box_multi_result[o];
+            const cap_y = capsule_box_multi_result[o + 1];
+            const cap_z = capsule_box_multi_result[o + 2];
+            const box_x = capsule_box_multi_result[o + 3];
+            const box_y = capsule_box_multi_result[o + 4];
+            const box_z = capsule_box_multi_result[o + 5];
+            const nx    = capsule_box_multi_result[o + 6];
+            const ny    = capsule_box_multi_result[o + 7];
+            const nz    = capsule_box_multi_result[o + 8];
+            const depth = capsule_box_multi_result[o + 9];
+            if (isCapsuleA) {
+                count = append_contact(count, cap_x, cap_y, cap_z, box_x, box_y, box_z, nx, ny, nz, depth);
+            } else {
+                count = append_contact(count, box_x, box_y, box_z, cap_x, cap_y, cap_z, -nx, -ny, -nz, depth);
+            }
+        }
+        return count;
+    }
+
+    // GJK + EPA fallback for everything else.
+    posed_a.setup(colA.shape, trA.position, trA.rotation);
+    posed_b.setup(colB.shape, trB.position, trB.rotation);
+    if (!gjk(simplex_buf, posed_a, posed_b)) return count;
+    expanding_polytope_algorithm(
+        epa_result, 0,
+        simplex_a, simplex_b, simplex_c, simplex_d,
+        posed_a, posed_b
+    );
+    const ex = epa_result[0], ey = epa_result[1], ez = epa_result[2];
+    const depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
+    // Reject zero-depth (touching), negative (impossible), and NaN/Inf
+    // (degenerate EPA exit) results. `!(depth > 0)` flips for NaN too.
+    if (!(depth > 0) || !Number.isFinite(depth)) return count;
+    const inv = 1 / depth;
+    return append_contact(count,
+        trA.position.x, trA.position.y, trA.position.z,
+        trB.position.x, trB.position.y, trB.position.z,
+        -ex * inv, -ey * inv, -ez * inv,
+        depth);
+}
+
+/**
+ * For every pair in `pair_list`, do a cross-product over A's collider list ×
+ * B's collider list, accumulate candidate contacts, reduce to ≤4, and write
+ * to the manifold slot.
+ *
+ * @param {PairList} pair_list
+ * @param {ManifoldStore} manifolds
+ * @param {PhysicsSystem} system supplies per-body collider lists + transforms
+ */
+export function narrowphase_step(pair_list, manifolds, system) {
+    const count = pair_list.count;
+    const lists = system.__body_collider_lists;
+
+    for (let i = 0; i < count; i++) {
+        const idA = pair_list.get_a(i);
+        const idB = pair_list.get_b(i);
+        const idxA = body_id_index(idA);
+        const idxB = body_id_index(idB);
+
+        const list_a = lists[idxA];
+        const list_b = lists[idxB];
+        const slot = manifolds.find(idA, idB);
+
+        if (list_a === undefined || list_b === undefined
+            || list_a.length === 0 || list_b.length === 0) {
+            manifolds.clear_contacts(slot);
+            continue;
+        }
+
+        let cand_count = 0;
+        const la_len = list_a.length;
+        const lb_len = list_b.length;
+        for (let a = 0; a < la_len; a++) {
+            const ea = list_a[a];
+            for (let b = 0; b < lb_len; b++) {
+                const eb = list_b[b];
+                cand_count = dispatch_pair(cand_count, ea.collider, ea.transform, eb.collider, eb.transform);
+            }
+        }
+
+        manifolds.clear_contacts(slot);
+        if (cand_count === 0) continue;
+
+        const kept = reduce_candidates(cand_count);
+        for (let k = 0; k < kept; k++) {
+            const off = k * CANDIDATE_STRIDE;
+            manifolds.set_contact(
+                slot, k,
+                candidates[off],     candidates[off + 1], candidates[off + 2],
+                candidates[off + 3], candidates[off + 4], candidates[off + 5],
+                candidates[off + 6], candidates[off + 7], candidates[off + 8],
+                candidates[off + 9]
+            );
+        }
+    }
+}

package/src/engine/physics/narrowphase/sphere_box_contact.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Closed-form contact generation for a unit sphere vs. an oriented box.
+ *
+ * Algorithm: transform the sphere centre into the box's body frame, clamp it
+ * to the box's half-extents to get the closest surface point in body space,
+ * measure the distance, and (when overlapping) rotate the resulting normal
+ * and surface point back into world.
+ *
+ * Singular cases:
+ *  - If the sphere centre is inside the box (distance == 0 in body frame),
+ *    the closest-face vector is undefined; we pick the smallest-overlap face
+ *    direction as a deterministic tie-break.
+ *
+ * Output convention (mirrors {@link sphere_sphere_contact}): the normal in
+ * `out[0..2]` points from the box surface toward the sphere centre; `out[3]`
+ * is the (positive) penetration depth; `out[4..6]` is the world-space contact
+ * point on the sphere's surface; `out[7..9]` is the world-space contact point
+ * on the box's surface.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} sx sphere centre x
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} radius
+ * @param {number} bx box centre x
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bqx box rotation quaternion x
+ * @param {number} bqy
+ * @param {number} bqz
+ * @param {number} bqw
+ * @param {number} hx box half-extent x (body frame)
+ * @param {number} hy
+ * @param {number} hz
+ * @returns {boolean} true if overlap
+ */
+export function sphere_box_contact(out: number[] | Float64Array, sx: number, sy: number, sz: number, radius: number, bx: number, by: number, bz: number, bqx: number, bqy: number, bqz: number, bqw: number, hx: number, hy: number, hz: number): boolean;
+//# sourceMappingURL=sphere_box_contact.d.ts.map

package/src/engine/physics/narrowphase/sphere_box_contact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sphere_box_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_box_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wCAjBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,UACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CA+FnB"}

package/src/engine/physics/narrowphase/sphere_box_contact.js

@@ -0,0 +1,130 @@
+/**
+ * Closed-form contact generation for a unit sphere vs. an oriented box.
+ *
+ * Algorithm: transform the sphere centre into the box's body frame, clamp it
+ * to the box's half-extents to get the closest surface point in body space,
+ * measure the distance, and (when overlapping) rotate the resulting normal
+ * and surface point back into world.
+ *
+ * Singular cases:
+ *  - If the sphere centre is inside the box (distance == 0 in body frame),
+ *    the closest-face vector is undefined; we pick the smallest-overlap face
+ *    direction as a deterministic tie-break.
+ *
+ * Output convention (mirrors {@link sphere_sphere_contact}): the normal in
+ * `out[0..2]` points from the box surface toward the sphere centre; `out[3]`
+ * is the (positive) penetration depth; `out[4..6]` is the world-space contact
+ * point on the sphere's surface; `out[7..9]` is the world-space contact point
+ * on the box's surface.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} sx sphere centre x
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} radius
+ * @param {number} bx box centre x
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bqx box rotation quaternion x
+ * @param {number} bqy
+ * @param {number} bqz
+ * @param {number} bqw
+ * @param {number} hx box half-extent x (body frame)
+ * @param {number} hy
+ * @param {number} hz
+ * @returns {boolean} true if overlap
+ */
+export function sphere_box_contact(
+    out,
+    sx, sy, sz, radius,
+    bx, by, bz,
+    bqx, bqy, bqz, bqw,
+    hx, hy, hz
+) {
+    // Step 1: bring the sphere centre into box-local space via the conjugate
+    // quaternion. v_local = q* · (s - b) · q
+    const dx = sx - bx, dy = sy - by, dz = sz - bz;
+
+    // Apply conjugate (-qx,-qy,-qz, qw) to (dx,dy,dz,0):
+    const cx = -bqx, cy = -bqy, cz = -bqz;
+    const tx0 = bqw * dx + cy * dz - cz * dy;
+    const ty0 = bqw * dy + cz * dx - cx * dz;
+    const tz0 = bqw * dz + cx * dy - cy * dx;
+    const tw0 = -cx * dx - cy * dy - cz * dz;
+    // Then multiply by c* = (qx,qy,qz,qw) (the original quaternion):
+    const lx = tx0 * bqw + tw0 * bqx + ty0 * bqz - tz0 * bqy;
+    const ly = ty0 * bqw + tw0 * bqy + tz0 * bqx - tx0 * bqz;
+    const lz = tz0 * bqw + tw0 * bqz + tx0 * bqy - ty0 * bqx;
+
+    // Step 2: closest point on the box to the sphere centre, in body frame.
+    const clx = lx < -hx ? -hx : (lx > hx ? hx : lx);
+    const cly = ly < -hy ? -hy : (ly > hy ? hy : ly);
+    const clz = lz < -hz ? -hz : (lz > hz ? hz : lz);
+
+    const inside = clx === lx && cly === ly && clz === lz;
+
+    let nlx, nly, nlz, dist;
+    if (!inside) {
+        // Centre is outside the box: normal is from clamped point toward centre.
+        const ex = lx - clx, ey = ly - cly, ez = lz - clz;
+        const dist_sqr = ex * ex + ey * ey + ez * ez;
+        if (dist_sqr >= radius * radius) {
+            return false;
+        }
+        dist = Math.sqrt(dist_sqr);
+        if (dist > 0) {
+            const inv = 1 / dist;
+            nlx = ex * inv; nly = ey * inv; nlz = ez * inv;
+        } else {
+            // Centre lies exactly on a face — pick +X as a tie-break.
+            nlx = 1; nly = 0; nlz = 0;
+        }
+    } else {
+        // Centre is inside the box. Closest face is the one we're nearest to.
+        // Compute the per-axis "distance to face" (positive); pick min.
+        const dx_face = hx - Math.abs(lx);
+        const dy_face = hy - Math.abs(ly);
+        const dz_face = hz - Math.abs(lz);
+
+        // Pick smallest depth-to-face; ties broken X > Y > Z (deterministic).
+        if (dx_face <= dy_face && dx_face <= dz_face) {
+            nlx = lx >= 0 ? 1 : -1; nly = 0; nlz = 0;
+            dist = -dx_face;
+        } else if (dy_face <= dz_face) {
+            nlx = 0; nly = ly >= 0 ? 1 : -1; nlz = 0;
+            dist = -dy_face;
+        } else {
+            nlx = 0; nly = 0; nlz = lz >= 0 ? 1 : -1;
+            dist = -dz_face;
+        }
+    }
+
+    // Step 3: rotate normal and surface point back to world. v_world = q · v · q*
+    function rotate_to_world(out_arr, off, vx, vy, vz) {
+        const ix = bqw * vx + bqy * vz - bqz * vy;
+        const iy = bqw * vy + bqz * vx - bqx * vz;
+        const iz = bqw * vz + bqx * vy - bqy * vx;
+        const iw = -bqx * vx - bqy * vy - bqz * vz;
+        out_arr[off]     = ix * bqw + iw * (-bqx) + iy * (-bqz) - iz * (-bqy);
+        out_arr[off + 1] = iy * bqw + iw * (-bqy) + iz * (-bqx) - ix * (-bqz);
+        out_arr[off + 2] = iz * bqw + iw * (-bqz) + ix * (-bqy) - iy * (-bqx);
+    }
+
+    // World normal (box → sphere).
+    rotate_to_world(out, 0, nlx, nly, nlz);
+    const nx = out[0], ny = out[1], nz = out[2];
+    out[3] = radius - dist;
+
+    // World contact on sphere = sphere_center - normal * radius.
+    out[4] = sx - nx * radius;
+    out[5] = sy - ny * radius;
+    out[6] = sz - nz * radius;
+
+    // World contact on box: rotate the local-space clamped point to world, plus box centre.
+    rotate_to_world(out, 7, clx, cly, clz);
+    out[7] += bx;
+    out[8] += by;
+    out[9] += bz;
+
+    return true;
+}

package/src/engine/physics/narrowphase/sphere_sphere_contact.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Closed-form contact generation for two unit spheres positioned in world
+ * space. Returns whether the spheres overlap. On overlap, `out` is populated
+ * with `[nx, ny, nz, depth]` where the normal points from B toward A and
+ * `depth` is the positive penetration distance.
+ *
+ * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
+ * scaling on the body's transform is irrelevant under our "no scale on
+ * physics transforms" assumption.
+ *
+ * Centres-coincident is a singular case for the general normal but is
+ * resolved here by picking +X as a deterministic tie-break direction.
+ *
+ * @param {number[]|Float64Array} out length >= 4
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} radius_a
+ * @param {number} radius_b
+ * @returns {boolean} true if spheres overlap
+ */
+export function sphere_sphere_contact(out: number[] | Float64Array, ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius_a: number, radius_b: number): boolean;
+//# sourceMappingURL=sphere_sphere_contact.d.ts.map

package/src/engine/physics/narrowphase/sphere_sphere_contact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sphere_sphere_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_sphere_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,2CAXW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA4BnB"}

package/src/engine/physics/narrowphase/sphere_sphere_contact.js

@@ -0,0 +1,51 @@
+/**
+ * Closed-form contact generation for two unit spheres positioned in world
+ * space. Returns whether the spheres overlap. On overlap, `out` is populated
+ * with `[nx, ny, nz, depth]` where the normal points from B toward A and
+ * `depth` is the positive penetration distance.
+ *
+ * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
+ * scaling on the body's transform is irrelevant under our "no scale on
+ * physics transforms" assumption.
+ *
+ * Centres-coincident is a singular case for the general normal but is
+ * resolved here by picking +X as a deterministic tie-break direction.
+ *
+ * @param {number[]|Float64Array} out length >= 4
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} radius_a
+ * @param {number} radius_b
+ * @returns {boolean} true if spheres overlap
+ */
+export function sphere_sphere_contact(out, ax, ay, az, bx, by, bz, radius_a, radius_b) {
+    const dx = ax - bx;
+    const dy = ay - by;
+    const dz = az - bz;
+    const dist_sqr = dx * dx + dy * dy + dz * dz;
+
+    const sum = radius_a + radius_b;
+    if (dist_sqr >= sum * sum) {
+        return false;
+    }
+
+    const dist = Math.sqrt(dist_sqr);
+    if (dist > 0) {
+        const inv = 1 / dist;
+        out[0] = dx * inv;
+        out[1] = dy * inv;
+        out[2] = dz * inv;
+    } else {
+        // Centres coincide. Pick +X deterministically (no RNG); penetration is
+        // the full sum of radii.
+        out[0] = 1;
+        out[1] = 0;
+        out[2] = 0;
+    }
+    out[3] = sum - dist;
+    return true;
+}