@woosh/meep-engine 2.152.0 → 2.154.0

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

@@ -1,145 +1,152 @@
-import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
-import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
-import { mesh_enumerate_triangles } from "./decomposition/mesh_enumerate_triangles.js";
-import { heightmap_enumerate_triangles } from "./decomposition/heightmap_enumerate_triangles.js";
-
-/**
- * # Ray vs a concave shape (mesh / heightmap)
- *
- * Refines a ray hit against a non-convex collider by triangle decomposition,
- * mirroring the contact narrowphase's concave path. Working in the shape's
- * local frame:
- *   1. clip the ray to the shape's local bounding box (a quick reject, and a
- *      finite query segment even when `tMax` is unbounded);
- *   2. enumerate the triangles overlapping that segment's AABB
- *      (`mesh_enumerate_triangles` / `heightmap_enumerate_triangles`);
- *   3. two-sided Möller–Trumbore each, keeping the nearest crossing;
- *   4. return its distance and the world surface normal (the triangle's
- *      geometric normal, oriented to face the ray).
- *
- * The triangle scratch grows on saturation and is bounded by {@link MAX_TRIS}
- * (a ray crossing more triangles than that in one mesh is not a realistic
- * raycast — it would mean skewering a 65k-triangle mesh lengthwise).
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-const lo = new Float64Array(3); // ray origin, shape-local
-const ld = new Float64Array(3); // ray direction, shape-local
-const bounds = new Float64Array(6); // shape local AABB
-
-const INITIAL_TRIS = 1024;
-const MAX_TRIS = 1 << 16;
-let tri_buf = new Float64Array(INITIAL_TRIS * TRIANGLE_FLOAT_STRIDE);
-
-const EPS = 1e-12;
-const AABB_FATTEN = 1e-5; // guards triangles whose AABB just abuts the segment
-
-/**
- * @param {AbstractShape3D} shape  a concave shape (`is_convex === false`)
- * @param {{x:number,y:number,z:number}} position
- * @param {ArrayLike<number>} rotation  body rotation quaternion (x,y,z,w)
- * @param {number} ox @param {number} oy @param {number} oz  ray origin (world)
- * @param {number} dx @param {number} dy @param {number} dz  ray dir (world, unit)
- * @param {number} tMax
- * @param {Float64Array|Vector3} outNormal  world surface normal, written on hit
- * @returns {number} hit distance, or `Infinity` on miss
- */
-export function refine_ray_concave(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
-    const qx = rotation[0], qy = rotation[1], qz = rotation[2], qw = rotation[3];
-    // World → local (inverse body rotation; unit dir stays unit → t preserved).
-    v3_quat3_apply(lo, 0, ox - position.x, oy - position.y, oz - position.z, -qx, -qy, -qz, qw);
-    v3_quat3_apply(ld, 0, dx, dy, dz, -qx, -qy, -qz, qw);
-    const lox = lo[0], loy = lo[1], loz = lo[2];
-    const ldx = ld[0], ldy = ld[1], ldz = ld[2];
-
-    // Clip the local ray to the shape's local AABB → segment [tEnter, tExit].
-    shape.compute_bounding_box(bounds);
-    let tEnter = 0, tExit = tMax;
-    if (ldx > EPS || ldx < -EPS) {
-        const inv = 1 / ldx;
-        let t1 = (bounds[0] - lox) * inv, t2 = (bounds[3] - lox) * inv;
-        if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
-        if (t1 > tEnter) tEnter = t1;
-        if (t2 < tExit) tExit = t2;
-    } else if (lox < bounds[0] || lox > bounds[3]) return Infinity;
-    if (ldy > EPS || ldy < -EPS) {
-        const inv = 1 / ldy;
-        let t1 = (bounds[1] - loy) * inv, t2 = (bounds[4] - loy) * inv;
-        if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
-        if (t1 > tEnter) tEnter = t1;
-        if (t2 < tExit) tExit = t2;
-    } else if (loy < bounds[1] || loy > bounds[4]) return Infinity;
-    if (ldz > EPS || ldz < -EPS) {
-        const inv = 1 / ldz;
-        let t1 = (bounds[2] - loz) * inv, t2 = (bounds[5] - loz) * inv;
-        if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
-        if (t1 > tEnter) tEnter = t1;
-        if (t2 < tExit) tExit = t2;
-    } else if (loz < bounds[2] || loz > bounds[5]) return Infinity;
-    if (tExit < tEnter) return Infinity; // ray misses the shape's AABB entirely
-
-    // Query AABB = bbox of the clipped local segment.
-    const sax = lox + ldx * tEnter, say = loy + ldy * tEnter, saz = loz + ldz * tEnter;
-    const sbx = lox + ldx * tExit, sby = loy + ldy * tExit, sbz = loz + ldz * tExit;
-    const qminx = (sax < sbx ? sax : sbx) - AABB_FATTEN;
-    const qminy = (say < sby ? say : sby) - AABB_FATTEN;
-    const qminz = (saz < sbz ? saz : sbz) - AABB_FATTEN;
-    const qmaxx = (sax > sbx ? sax : sbx) + AABB_FATTEN;
-    const qmaxy = (say > sby ? say : sby) + AABB_FATTEN;
-    const qmaxz = (saz > sbz ? saz : sbz) + AABB_FATTEN;
-
-    const enumerate = shape.isHeightMapShape3D === true ? heightmap_enumerate_triangles : mesh_enumerate_triangles;
-    let cap = (tri_buf.length / TRIANGLE_FLOAT_STRIDE) | 0;
-    let count = enumerate(tri_buf, 0, shape, qminx, qminy, qminz, qmaxx, qmaxy, qmaxz);
-    while (count === cap && cap < MAX_TRIS) {
-        cap = cap * 2 < MAX_TRIS ? cap * 2 : MAX_TRIS;
-        tri_buf = new Float64Array(cap * TRIANGLE_FLOAT_STRIDE);
-        count = enumerate(tri_buf, 0, shape, qminx, qminy, qminz, qmaxx, qmaxy, qmaxz);
-    }
-
-    // Two-sided Möller–Trumbore over the candidates; keep the nearest.
-    let best = tMax;
-    let found = false;
-    let nx = 0, ny = 0, nz = 0;
-    for (let i = 0; i < count; i++) {
-        const o = i * TRIANGLE_FLOAT_STRIDE;
-        const ax = tri_buf[o], ay = tri_buf[o + 1], az = tri_buf[o + 2];
-        const e1x = tri_buf[o + 3] - ax, e1y = tri_buf[o + 4] - ay, e1z = tri_buf[o + 5] - az;
-        const e2x = tri_buf[o + 6] - ax, e2y = tri_buf[o + 7] - ay, e2z = tri_buf[o + 8] - az;
-
-        const px = ldy * e2z - ldz * e2y, py = ldz * e2x - ldx * e2z, pz = ldx * e2y - ldy * e2x;
-        const det = e1x * px + e1y * py + e1z * pz;
-        if (det < EPS && det > -EPS) continue; // ray parallel to the triangle
-        const invDet = 1 / det;
-
-        const tvx = lox - ax, tvy = loy - ay, tvz = loz - az;
-        const u = (tvx * px + tvy * py + tvz * pz) * invDet;
-        if (u < 0 || u > 1) continue;
-
-        const wx = tvy * e1z - tvz * e1y, wy = tvz * e1x - tvx * e1z, wz = tvx * e1y - tvy * e1x;
-        const v = (ldx * wx + ldy * wy + ldz * wz) * invDet;
-        if (v < 0 || u + v > 1) continue;
-
-        const t = (e2x * wx + e2y * wy + e2z * wz) * invDet;
-        if (t < 0 || t >= best) continue;
-
-        best = t;
-        found = true;
-        // Geometric normal e1 × e2 (local, unnormalised).
-        nx = e1y * e2z - e1z * e2y;
-        ny = e1z * e2x - e1x * e2z;
-        nz = e1x * e2y - e1y * e2x;
-    }
-
-    if (!found) return Infinity;
-
-    // Normalise, orient to face the ray, then rotate the local normal to world.
-    let nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
-    if (nl === 0) nl = 1;
-    nx /= nl; ny /= nl; nz /= nl;
-    if (nx * ldx + ny * ldy + nz * ldz > 0) { nx = -nx; ny = -ny; nz = -nz; }
-    v3_quat3_apply(outNormal, 0, nx, ny, nz, qx, qy, qz, qw);
-    return best;
-}
+import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
+import { mesh_enumerate_triangles } from "./decomposition/mesh_enumerate_triangles.js";
+import { heightmap_enumerate_triangles } from "./decomposition/heightmap_enumerate_triangles.js";
+
+/**
+ * # Ray vs a concave shape (mesh / heightmap)
+ *
+ * Refines a ray hit against a non-convex collider by triangle decomposition,
+ * mirroring the contact narrowphase's concave path. Working in the shape's
+ * local frame:
+ *   1. clip the ray to the shape's local bounding box (a quick reject, and a
+ *      finite query segment even when `tMax` is unbounded);
+ *   2. enumerate the triangles overlapping that segment's AABB
+ *      (`mesh_enumerate_triangles` / `heightmap_enumerate_triangles`);
+ *   3. two-sided Möller–Trumbore each, keeping the nearest crossing;
+ *   4. return its distance and the world surface normal (the triangle's
+ *      geometric normal, oriented to face the ray).
+ *
+ * The triangle scratch grows on saturation and is bounded by {@link MAX_TRIS}
+ * (a ray crossing more triangles than that in one mesh is not a realistic
+ * raycast — it would mean skewering a 65k-triangle mesh lengthwise).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const lo = new Float64Array(3); // ray origin, shape-local
+const ld = new Float64Array(3); // ray direction, shape-local
+const bounds = new Float64Array(6); // shape local AABB
+
+const INITIAL_TRIS = 1024;
+const MAX_TRIS = 1 << 16;
+let tri_buf = new Float64Array(INITIAL_TRIS * TRIANGLE_FLOAT_STRIDE);
+
+const EPS = 1e-12;
+const AABB_FATTEN = 1e-5; // guards triangles whose AABB just abuts the segment
+
+/**
+ * @param {AbstractShape3D} shape  a concave shape (`is_convex === false`)
+ * @param {{x:number,y:number,z:number}} position
+ * @param {ArrayLike<number>} rotation  body rotation quaternion (x,y,z,w)
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (world)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (world, unit)
+ * @param {number} tMax
+ * @param {Float64Array|Vector3} outNormal  world surface normal, written on hit
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function refine_ray_concave(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
+    const qx = rotation[0], qy = rotation[1], qz = rotation[2], qw = rotation[3];
+    // World → local (inverse body rotation; unit dir stays unit → t preserved).
+    v3_quat3_apply(lo, 0, ox - position.x, oy - position.y, oz - position.z, -qx, -qy, -qz, qw);
+    v3_quat3_apply(ld, 0, dx, dy, dz, -qx, -qy, -qz, qw);
+    const lox = lo[0], loy = lo[1], loz = lo[2];
+    const ldx = ld[0], ldy = ld[1], ldz = ld[2];
+
+    // Clip the local ray to the shape's local AABB → segment [tEnter, tExit].
+    shape.compute_bounding_box(bounds);
+    let tEnter = 0, tExit = tMax;
+    if (ldx > EPS || ldx < -EPS) {
+        const inv = 1 / ldx;
+        let t1 = (bounds[0] - lox) * inv, t2 = (bounds[3] - lox) * inv;
+        if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
+        if (t1 > tEnter) tEnter = t1;
+        if (t2 < tExit) tExit = t2;
+    } else if (lox < bounds[0] || lox > bounds[3]) return Infinity;
+    if (ldy > EPS || ldy < -EPS) {
+        const inv = 1 / ldy;
+        let t1 = (bounds[1] - loy) * inv, t2 = (bounds[4] - loy) * inv;
+        if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
+        if (t1 > tEnter) tEnter = t1;
+        if (t2 < tExit) tExit = t2;
+    } else if (loy < bounds[1] || loy > bounds[4]) return Infinity;
+    if (ldz > EPS || ldz < -EPS) {
+        const inv = 1 / ldz;
+        let t1 = (bounds[2] - loz) * inv, t2 = (bounds[5] - loz) * inv;
+        if (t1 > t2) { const s = t1; t1 = t2; t2 = s; }
+        if (t1 > tEnter) tEnter = t1;
+        if (t2 < tExit) tExit = t2;
+    } else if (loz < bounds[2] || loz > bounds[5]) return Infinity;
+    if (tExit < tEnter) return Infinity; // ray misses the shape's AABB entirely
+
+    // Query AABB = bbox of the clipped local segment.
+    const sax = lox + ldx * tEnter, say = loy + ldy * tEnter, saz = loz + ldz * tEnter;
+    const sbx = lox + ldx * tExit, sby = loy + ldy * tExit, sbz = loz + ldz * tExit;
+    const qminx = (sax < sbx ? sax : sbx) - AABB_FATTEN;
+    const qminy = (say < sby ? say : sby) - AABB_FATTEN;
+    const qminz = (saz < sbz ? saz : sbz) - AABB_FATTEN;
+    const qmaxx = (sax > sbx ? sax : sbx) + AABB_FATTEN;
+    const qmaxy = (say > sby ? say : sby) + AABB_FATTEN;
+    const qmaxz = (saz > sbz ? saz : sbz) + AABB_FATTEN;
+
+    const enumerate = shape.isHeightMapShape3D === true ? heightmap_enumerate_triangles : mesh_enumerate_triangles;
+    let cap = (tri_buf.length / TRIANGLE_FLOAT_STRIDE) | 0;
+    // The enumerators return the TRUE overlap count, which can EXCEED the buffer
+    // capacity (writes past the end are silently dropped). So the grow trigger is
+    // `count > cap` (not `=== cap`): regrow whenever the true count overflowed.
+    let count = enumerate(tri_buf, 0, shape, qminx, qminy, qminz, qmaxx, qmaxy, qmaxz);
+    while (count > cap && cap < MAX_TRIS) {
+        cap = cap * 2 < MAX_TRIS ? cap * 2 : MAX_TRIS;
+        tri_buf = new Float64Array(cap * TRIANGLE_FLOAT_STRIDE);
+        count = enumerate(tri_buf, 0, shape, qminx, qminy, qminz, qmaxx, qmaxy, qmaxz);
+    }
+    // If the true count still exceeds MAX_TRIS, only `cap` triangles were written;
+    // clamp so the consume loop never reads undefined past the buffer (which would
+    // poison `best` with NaN). Dropping the overflow is the documented MAX_TRIS bound.
+    const n_tris = count < cap ? count : cap;
+
+    // Two-sided Möller–Trumbore over the candidates; keep the nearest.
+    let best = tMax;
+    let found = false;
+    let nx = 0, ny = 0, nz = 0;
+    for (let i = 0; i < n_tris; i++) {
+        const o = i * TRIANGLE_FLOAT_STRIDE;
+        const ax = tri_buf[o], ay = tri_buf[o + 1], az = tri_buf[o + 2];
+        const e1x = tri_buf[o + 3] - ax, e1y = tri_buf[o + 4] - ay, e1z = tri_buf[o + 5] - az;
+        const e2x = tri_buf[o + 6] - ax, e2y = tri_buf[o + 7] - ay, e2z = tri_buf[o + 8] - az;
+
+        const px = ldy * e2z - ldz * e2y, py = ldz * e2x - ldx * e2z, pz = ldx * e2y - ldy * e2x;
+        const det = e1x * px + e1y * py + e1z * pz;
+        if (det < EPS && det > -EPS) continue; // ray parallel to the triangle
+        const invDet = 1 / det;
+
+        const tvx = lox - ax, tvy = loy - ay, tvz = loz - az;
+        const u = (tvx * px + tvy * py + tvz * pz) * invDet;
+        if (u < 0 || u > 1) continue;
+
+        const wx = tvy * e1z - tvz * e1y, wy = tvz * e1x - tvx * e1z, wz = tvx * e1y - tvy * e1x;
+        const v = (ldx * wx + ldy * wy + ldz * wz) * invDet;
+        if (v < 0 || u + v > 1) continue;
+
+        const t = (e2x * wx + e2y * wy + e2z * wz) * invDet;
+        if (t < 0 || t >= best) continue;
+
+        best = t;
+        found = true;
+        // Geometric normal e1 × e2 (local, unnormalised).
+        nx = e1y * e2z - e1z * e2y;
+        ny = e1z * e2x - e1x * e2z;
+        nz = e1x * e2y - e1y * e2x;
+    }
+
+    if (!found) return Infinity;
+
+    // Normalise, orient to face the ray, then rotate the local normal to world.
+    let nl = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    if (nl === 0) nl = 1;
+    nx /= nl; ny /= nl; nz /= nl;
+    if (nx * ldx + ny * ldy + nz * ldz > 0) { nx = -nx; ny = -ny; nz = -nz; }
+    v3_quat3_apply(outNormal, 0, nx, ny, nz, qx, qy, qz, qw);
+    return best;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"sphere_box_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_box_contact.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CA8EnB"}
+{"version":3,"file":"sphere_box_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_box_contact.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAuFnB"}

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

@@ -1,123 +1,132 @@
-import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
-import { v3_quat3_apply_inverse } from "../../../core/geom/vec3/v3_quat3_apply_inverse.js";
-
-/**
- * Scratch for the world→box-local rotation of the sphere centre at the
- * top of {@link sphere_box_contact}. 3 floats; allocation-free.
- * @type {Float64Array}
- */
-const scratch_local = new Float64Array(3);
-
-/**
- * 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
-    v3_quat3_apply_inverse(scratch_local, 0, sx - bx, sy - by, sz - bz, bqx, bqy, bqz, bqw);
-    const lx = scratch_local[0];
-    const ly = scratch_local[1];
-    const lz = scratch_local[2];
-
-    // 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*
-
-    // World normal (box → sphere).
-    v3_quat3_apply(out, 0, nlx, nly, nlz, bqx, bqy, bqz, bqw);
-    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.
-    v3_quat3_apply(out, 7, clx, cly, clz, bqx, bqy, bqz, bqw);
-    out[7] += bx;
-    out[8] += by;
-    out[9] += bz;
-
-    return true;
-}
+import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { v3_quat3_apply_inverse } from "../../../core/geom/vec3/v3_quat3_apply_inverse.js";
+
+/**
+ * Scratch for the world→box-local rotation of the sphere centre at the
+ * top of {@link sphere_box_contact}. 3 floats; allocation-free.
+ * @type {Float64Array}
+ */
+const scratch_local = new Float64Array(3);
+
+/**
+ * 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
+    v3_quat3_apply_inverse(scratch_local, 0, sx - bx, sy - by, sz - bz, bqx, bqy, bqz, bqw);
+    const lx = scratch_local[0];
+    const ly = scratch_local[1];
+    const lz = scratch_local[2];
+
+    // Step 2: closest point on the box to the sphere centre, in body frame.
+    // `let` because the interior branch snaps the point onto the chosen face
+    // (when the centre is inside the box the clamp leaves it AT the centre).
+    let clx = lx < -hx ? -hx : (lx > hx ? hx : lx);
+    let cly = ly < -hy ? -hy : (ly > hy ? hy : ly);
+    let 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).
+        // Snap the clamped point onto the chosen face so the world box contact
+        // point (out[7..9], written below) lies on the box SURFACE and is
+        // consistent with the reported normal/depth — not left at the interior
+        // sphere centre (which the clamp produced for an inside centre).
+        if (dx_face <= dy_face && dx_face <= dz_face) {
+            nlx = lx >= 0 ? 1 : -1; nly = 0; nlz = 0;
+            dist = -dx_face;
+            clx = lx >= 0 ? hx : -hx;
+        } else if (dy_face <= dz_face) {
+            nlx = 0; nly = ly >= 0 ? 1 : -1; nlz = 0;
+            dist = -dy_face;
+            cly = ly >= 0 ? hy : -hy;
+        } else {
+            nlx = 0; nly = 0; nlz = lz >= 0 ? 1 : -1;
+            dist = -dz_face;
+            clz = lz >= 0 ? hz : -hz;
+        }
+    }
+
+    // Step 3: rotate normal and surface point back to world. v_world = q · v · q*
+
+    // World normal (box → sphere).
+    v3_quat3_apply(out, 0, nlx, nly, nlz, bqx, bqy, bqz, bqw);
+    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.
+    v3_quat3_apply(out, 7, clx, cly, clz, bqx, bqy, bqz, bqw);
+    out[7] += bx;
+    out[8] += by;
+    out[9] += bz;
+
+    return true;
+}

package/src/engine/physics/queries/overlap_shape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAqGlB"}
+{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAoGlB"}

package/src/engine/physics/queries/overlap_shape.js

@@ -100,13 +100,19 @@ export function overlap_shape(system, shape, position, rotation, output, output_
     );
 
     // ── 2. Gather broadphase candidates ─────────────────────────────
-    const n_static = bvh_query_user_data_overlaps_aabb(
-        scratch_candidates, 0, system.staticBvh, world_aabb
-    );
-    const n_dynamic = bvh_query_user_data_overlaps_aabb(
-        scratch_candidates, n_static, system.dynamicBvh, world_aabb
-    );
-    const n_total = n_static + n_dynamic;
+    // The BVH query returns the TRUE overlap count and silently drops writes past
+    // the buffer end, so an undersized buffer would leave the read loop pulling
+    // `undefined` (garbage body ids) and silently MISS real overlaps. Grow by
+    // doubling and re-query until both static + dynamic fit (queries are
+    // deterministic, so this converges in one resize).
+    let n_static, n_dynamic, n_total;
+    for (;;) {
+        n_static = bvh_query_user_data_overlaps_aabb(scratch_candidates, 0, system.staticBvh, world_aabb);
+        n_dynamic = bvh_query_user_data_overlaps_aabb(scratch_candidates, n_static, system.dynamicBvh, world_aabb);
+        n_total = n_static + n_dynamic;
+        if (n_total <= scratch_candidates.length) break;
+        scratch_candidates = new Uint32Array(Math.max(n_total, scratch_candidates.length * 2));
+    }
     if (n_total === 0) return 0;
 
     // ── 3. Set up query PosedShape (constant across candidates) ─────
@@ -154,16 +160,9 @@ export function overlap_shape(system, shape, position, rotation, output, output_
                 concave_query_aabb[3], concave_query_aabb[4], concave_query_aabb[5]
             );
 
-            // Re-pose candidate as the concave body, rebinding the
-            // flyweight triangle per iteration.
-            candidate_posed.shape = triangle_shape;
-            candidate_posed.px = candidate_tr.position.x;
-            candidate_posed.py = candidate_tr.position.y;
-            candidate_posed.pz = candidate_tr.position.z;
-            candidate_posed.qx = candidate_tr.rotation.x;
-            candidate_posed.qy = candidate_tr.rotation.y;
-            candidate_posed.qz = candidate_tr.rotation.z;
-            candidate_posed.qw = candidate_tr.rotation.w;
+            // Re-pose candidate as the concave body (the flyweight triangle is
+            // rebound per iteration below; setup only stores the shape reference).
+            candidate_posed.setup(triangle_shape, candidate_tr.position, candidate_tr.rotation);
 
             for (let t = 0; t < tri_count; t++) {
                 triangle_shape.bind(triangle_buffer, t * TRIANGLE_FLOAT_STRIDE);