@woosh/meep-engine 2.141.0 → 2.143.0

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

@@ -0,0 +1,187 @@
+/**
+ * # Local-frame ray ↔ primitive intersections (raycast narrowphase)
+ *
+ * Each function intersects a ray, **expressed in the shape's local frame**,
+ * against a canonical primitive at the origin (sphere at the origin; box
+ * axis-aligned spanning `[-h, +h]`; capsule along the local Y axis). They
+ * return the hit distance `t` along the ray (`Infinity` on a miss) and write
+ * the **local** outward surface normal (unit) into `outNormal[0..2]`.
+ *
+ * The ray-narrowphase dispatch transforms the world ray into the body's local
+ * frame once (rotate by the inverse body rotation — a unit direction stays
+ * unit, so `t` is preserved), calls the matching primitive, then rotates the
+ * returned local normal back to world. Keeping the primitives canonical lets
+ * the box and capsule tests be axis-aligned (cheap slab / cylinder math) and
+ * shares a single transform across them.
+ *
+ * Conventions:
+ *  - the ray direction is unit length (the caller guarantees it);
+ *  - the first surface crossing at or after the origin within `tMax` is
+ *    returned; a ray starting inside the shape returns its exit crossing;
+ *  - the normal is the geometric outward surface normal at the hit.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Ray vs a sphere of radius `r` centred at the local origin.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} r  sphere radius
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_sphere_local(outNormal, ox, oy, oz, dx, dy, dz, tMax, r) {
+    // |o + t·d|² = r², d unit → t² + 2(o·d)t + (|o|² − r²) = 0.
+    const b = ox * dx + oy * dy + oz * dz;
+    const c = ox * ox + oy * oy + oz * oz - r * r;
+    const disc = b * b - c;
+    if (disc < 0) return Infinity;
+    const sq = Math.sqrt(disc);
+    let t = -b - sq;             // near root (entry)
+    if (t < 0) t = -b + sq;      // origin inside the sphere → far root (exit)
+    if (t < 0 || t > tMax) return Infinity;
+    const inv = 1 / r;
+    outNormal[0] = (ox + dx * t) * inv;
+    outNormal[1] = (oy + dy * t) * inv;
+    outNormal[2] = (oz + dz * t) * inv;
+    return t;
+}
+
+/**
+ * Ray vs an axis-aligned box spanning `[-hx,hx] × [-hy,hy] × [-hz,hz]` at the
+ * local origin (the canonical pose of {@link BoxShape3D}). Slab method, with
+ * the entry (or, origin-inside, exit) face's outward normal.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} hx @param {number} hy @param {number} hz  half-extents
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_box_local(outNormal, ox, oy, oz, dx, dy, dz, tMax, hx, hy, hz) {
+    let tmin = -Infinity, tmax = Infinity;
+    let enterAxis = 0, enterSign = 0, exitAxis = 0, exitSign = 0;
+
+    // X slab.
+    if (dx !== 0) {
+        const inv = 1 / dx;
+        let tn = (-hx - ox) * inv, tf = (hx - ox) * inv, nsign = -1;
+        if (tn > tf) { const tmp = tn; tn = tf; tf = tmp; nsign = 1; }
+        if (tn > tmin) { tmin = tn; enterAxis = 0; enterSign = nsign; }
+        if (tf < tmax) { tmax = tf; exitAxis = 0; exitSign = -nsign; }
+    } else if (ox < -hx || ox > hx) {
+        return Infinity;
+    }
+    // Y slab.
+    if (dy !== 0) {
+        const inv = 1 / dy;
+        let tn = (-hy - oy) * inv, tf = (hy - oy) * inv, nsign = -1;
+        if (tn > tf) { const tmp = tn; tn = tf; tf = tmp; nsign = 1; }
+        if (tn > tmin) { tmin = tn; enterAxis = 1; enterSign = nsign; }
+        if (tf < tmax) { tmax = tf; exitAxis = 1; exitSign = -nsign; }
+    } else if (oy < -hy || oy > hy) {
+        return Infinity;
+    }
+    // Z slab.
+    if (dz !== 0) {
+        const inv = 1 / dz;
+        let tn = (-hz - oz) * inv, tf = (hz - oz) * inv, nsign = -1;
+        if (tn > tf) { const tmp = tn; tn = tf; tf = tmp; nsign = 1; }
+        if (tn > tmin) { tmin = tn; enterAxis = 2; enterSign = nsign; }
+        if (tf < tmax) { tmax = tf; exitAxis = 2; exitSign = -nsign; }
+    } else if (oz < -hz || oz > hz) {
+        return Infinity;
+    }
+
+    if (tmax < tmin || tmax < 0) return Infinity;
+
+    let t, axis, sign;
+    if (tmin >= 0) { t = tmin; axis = enterAxis; sign = enterSign; }
+    else { t = tmax; axis = exitAxis; sign = exitSign; } // origin inside the box
+
+    if (t > tMax) return Infinity;
+    outNormal[0] = 0; outNormal[1] = 0; outNormal[2] = 0;
+    outNormal[axis] = sign;
+    return t;
+}
+
+/**
+ * Ray vs a capsule along the local Y axis: a cylinder of radius `r` over
+ * `y ∈ [−hh, hh]` capped by hemispheres of radius `r` at `(0, ±hh, 0)` — the
+ * canonical pose of {@link CapsuleShape3D} (`hh = height/2`). Tests the
+ * infinite cylinder (clamped to the segment) and the two cap spheres, taking
+ * the nearest valid crossing.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} r   capsule radius
+ * @param {number} hh  half-height of the cylindrical section (`height/2`)
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_capsule_local(outNormal, ox, oy, oz, dx, dy, dz, tMax, r, hh) {
+    let best = Infinity;
+    let nx = 0, ny = 0, nz = 0;
+    const r2 = r * r;
+    const inv_r = 1 / r;
+
+    // --- Cylinder side (infinite cylinder about Y, projected to XZ). ---
+    const a = dx * dx + dz * dz;
+    if (a > 1e-12) {
+        const b = ox * dx + oz * dz;
+        const c = ox * ox + oz * oz - r2;
+        const disc = b * b - a * c;
+        if (disc >= 0) {
+            const sq = Math.sqrt(disc);
+            const inv_a = 1 / a;
+            // Both roots; the smaller non-negative one whose hit lies on the
+            // cylindrical section is the side contact.
+            const roots = (-b - sq) * inv_a;
+            const rootf = (-b + sq) * inv_a;
+            for (let i = 0; i < 2; i++) {
+                const t = i === 0 ? roots : rootf;
+                if (t < 0 || t >= best || t > tMax) continue;
+                const y = oy + dy * t;
+                if (y < -hh || y > hh) continue; // off the cylinder, onto a cap
+                best = t;
+                const px = ox + dx * t, pz = oz + dz * t;
+                nx = px * inv_r; ny = 0; nz = pz * inv_r;
+                break; // roots is the nearer; if it qualified we're done
+            }
+        }
+    }
+
+    // --- Cap spheres at (0, ±hh, 0), each valid only on its outer hemisphere. ---
+    for (let cap = 0; cap < 2; cap++) {
+        const cy = cap === 0 ? hh : -hh;
+        const oyc = oy - cy;
+        const bb = ox * dx + oyc * dy + oz * dz;
+        const cc = ox * ox + oyc * oyc + oz * oz - r2;
+        const disc = bb * bb - cc;
+        if (disc < 0) continue;
+        const sq = Math.sqrt(disc);
+        const tn = -bb - sq, tf = -bb + sq;
+        for (let i = 0; i < 2; i++) {
+            const t = i === 0 ? tn : tf;
+            if (t < 0 || t >= best || t > tMax) continue;
+            const hy = oy + dy * t;
+            // Only the hemisphere beyond the segment end belongs to this cap.
+            if (cap === 0 ? hy < hh : hy > -hh) continue;
+            best = t;
+            nx = (ox + dx * t) * inv_r;
+            ny = (hy - cy) * inv_r;
+            nz = (oz + dz * t) * inv_r;
+            break;
+        }
+    }
+
+    if (best === Infinity) return Infinity;
+    outNormal[0] = nx; outNormal[1] = ny; outNormal[2] = nz;
+    return best;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * @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: AbstractShape3D, position: {
+    x: number;
+    y: number;
+    z: number;
+}, rotation: ArrayLike<number>, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, outNormal: Float64Array | Vector3): number;
+//# sourceMappingURL=refine_ray_concave.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refine_ray_concave.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/refine_ray_concave.js"],"names":[],"mappings":"AAsCA;;;;;;;;;GASG;AACH,qEARW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAC5B,UAAU,MAAM,CAAC,MACjB,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,aACN,YAAY,UAAQ,GAClB,MAAM,CAkGlB"}

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

@@ -0,0 +1,145 @@
+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;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Refine a broadphase ray hit against a body's true shape geometry.
+ *
+ * Transforms the world ray into the shape's local frame once (rotate by the
+ * inverse body rotation — a unit direction stays unit, so the hit distance is
+ * preserved), runs the matching canonical primitive ({@link ray_shapes}), and
+ * rotates the returned local normal back to world. Spheres are
+ * rotation-invariant, so they only need the translation.
+ *
+ * Handles the convex primitives (sphere / box / capsule). Concave shapes
+ * (mesh / heightmap) and arbitrary composite convex shapes return
+ * {@link RAY_REFINE_UNSUPPORTED} — the concave path is wired in separately, and
+ * composites fall back to the broadphase AABB hit (no regression).
+ *
+ * @param {AbstractShape3D} shape
+ * @param {{x:number,y:number,z:number}} position  body world position
+ * @param {ArrayLike<number>} rotation  body world 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 a
+ *   finite hit
+ * @returns {number} hit distance, `Infinity` on a refined miss, or
+ *   {@link RAY_REFINE_UNSUPPORTED} when the shape has no exact ray test here
+ */
+export function refine_ray_hit(shape: AbstractShape3D, position: {
+    x: number;
+    y: number;
+    z: number;
+}, rotation: ArrayLike<number>, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, outNormal: Float64Array | Vector3): number;
+/**
+ * Sentinel returned by {@link refine_ray_hit} for a shape it has no exact ray
+ * test for (composite / arbitrary convex). The caller should keep the
+ * broadphase AABB result for that leaf rather than treat it as a miss.
+ * Distinct from `Infinity` (a refined miss) and any finite hit distance.
+ * @type {number}
+ */
+export const RAY_REFINE_UNSUPPORTED: number;
+//# sourceMappingURL=refine_ray_hit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refine_ray_hit.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/refine_ray_hit.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iEAVW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAC5B,UAAU,MAAM,CAAC,MACjB,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,aACN,YAAY,UAAQ,GAElB,MAAM,CAsClB;AAzED;;;;;;GAMG;AACH,qCAFU,MAAM,CAEyB"}

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

@@ -0,0 +1,78 @@
+import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { ray_sphere_local, ray_box_local, ray_capsule_local } from "./ray_shapes.js";
+import { refine_ray_concave } from "./refine_ray_concave.js";
+
+/**
+ * Sentinel returned by {@link refine_ray_hit} for a shape it has no exact ray
+ * test for (composite / arbitrary convex). The caller should keep the
+ * broadphase AABB result for that leaf rather than treat it as a miss.
+ * Distinct from `Infinity` (a refined miss) and any finite hit distance.
+ * @type {number}
+ */
+export const RAY_REFINE_UNSUPPORTED = -1;
+
+const lo = new Float64Array(3); // ray origin in shape-local frame
+const ld = new Float64Array(3); // ray direction in shape-local frame
+const ln = new Float64Array(3); // surface normal in shape-local frame
+
+/**
+ * Refine a broadphase ray hit against a body's true shape geometry.
+ *
+ * Transforms the world ray into the shape's local frame once (rotate by the
+ * inverse body rotation — a unit direction stays unit, so the hit distance is
+ * preserved), runs the matching canonical primitive ({@link ray_shapes}), and
+ * rotates the returned local normal back to world. Spheres are
+ * rotation-invariant, so they only need the translation.
+ *
+ * Handles the convex primitives (sphere / box / capsule). Concave shapes
+ * (mesh / heightmap) and arbitrary composite convex shapes return
+ * {@link RAY_REFINE_UNSUPPORTED} — the concave path is wired in separately, and
+ * composites fall back to the broadphase AABB hit (no regression).
+ *
+ * @param {AbstractShape3D} shape
+ * @param {{x:number,y:number,z:number}} position  body world position
+ * @param {ArrayLike<number>} rotation  body world 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 a
+ *   finite hit
+ * @returns {number} hit distance, `Infinity` on a refined miss, or
+ *   {@link RAY_REFINE_UNSUPPORTED} when the shape has no exact ray test here
+ */
+export function refine_ray_hit(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
+    if (shape.isSphereShape3D === true) {
+        // Rotation-invariant: translate into the sphere's frame; the local
+        // normal is already the world normal.
+        return ray_sphere_local(outNormal, ox - position.x, oy - position.y, oz - position.z, dx, dy, dz, tMax, shape.radius);
+    }
+
+    if (shape.isBoxShape3D === true || shape.isCapsuleShape3D === true) {
+        const qx = rotation[0], qy = rotation[1], qz = rotation[2], qw = rotation[3];
+        // World → local: rotate by the inverse (conjugate) body rotation.
+        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);
+
+        let t;
+        if (shape.isBoxShape3D === true) {
+            const h = shape.half_extents;
+            t = ray_box_local(ln, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, h.x, h.y, h.z);
+        } else {
+            t = ray_capsule_local(ln, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, shape.radius, shape.height * 0.5);
+        }
+        if (t === Infinity) return Infinity;
+
+        // Local normal → world: rotate by the body rotation.
+        v3_quat3_apply(outNormal, 0, ln[0], ln[1], ln[2], qx, qy, qz, qw);
+        return t;
+    }
+
+    // Concave (mesh / heightmap): triangle decomposition.
+    if (shape.is_convex === false) {
+        return refine_ray_concave(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal);
+    }
+
+    // Arbitrary composite convex (TransformedShape3D / UnionShape3D / …):
+    // no exact ray test yet — caller falls back to the broadphase AABB hit.
+    return RAY_REFINE_UNSUPPORTED;
+}

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

@@ -1,12 +1,13 @@
 /**
- * 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.
+ * Closed-form contact generation for two spheres positioned in world space.
+ * Returns whether the spheres overlap. On overlap, `out` is populated with
+ * `[nx, ny, nz, depth]` where the normal (unit length) 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.
+ * Each sphere's radius is passed explicitly (`radius_a` / `radius_b`) — the
+ * caller reads it from the shape (`SphereShape3D.radius`; 1 for the
+ * {@link UnitSphereShape3D} special case). 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.

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

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

@@ -1,12 +1,13 @@
 /**
- * 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.
+ * Closed-form contact generation for two spheres positioned in world space.
+ * Returns whether the spheres overlap. On overlap, `out` is populated with
+ * `[nx, ny, nz, depth]` where the normal (unit length) 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.
+ * Each sphere's radius is passed explicitly (`radius_a` / `radius_b`) — the
+ * caller reads it from the shape (`SphereShape3D.radius`; 1 for the
+ * {@link UnitSphereShape3D} special case). 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.

package/src/engine/physics/queries/raycast.d.ts

@@ -1,19 +1,21 @@
 /**
  * Raycast against both broadphase trees (static + dynamic) of a
- * {@link PhysicsSystem}, filling `result` with the nearest hit and returning
- * `true` on hit, `false` on miss.
+ * {@link PhysicsSystem}, refined against each candidate's true shape geometry.
+ * Fills `result` with the nearest hit and returns `true` on hit, `false` on
+ * miss. `result.t` is the exact surface distance and `result.normal` the true
+ * surface normal for sphere / box / capsule / mesh / heightmap colliders;
+ * composite convex shapes (no exact ray test yet) fall back to the broadphase
+ * AABB hit + AABB-face normal.
  *
- * Hit normal is the AABB face normal — exact for AABB-shaped colliders,
- * a stable approximation for general convex shapes (an upcoming narrowphase
- * refinement pass will replace this with the true shape normal at the same
- * call site, no API change).
+ * Multi-collider bodies resolve their primary (first-attached) collider — the
+ * BVH leaf encodes only `body_id`; per-collider rays need the leaf user-data to
+ * carry the collider index (future work).
  *
  * @param {PhysicsSystem} system
  * @param {Ray3} ray  origin + unit direction + `tMax`
  * @param {PhysicsSurfacePoint} result  populated on hit; untouched on miss
- * @param {(entity:number, collider:Collider)=>boolean} [filter] mandatory in
- *   contract; defaults to {@link returnTrue} (accept everything). Called once
- *   per BVH leaf that crosses the ray.
+ * @param {(entity:number, collider:Collider)=>boolean} [filter] called once per
+ *   crossing leaf; defaults to {@link returnTrue}.
  * @returns {boolean} true on hit, false on miss
  */
 export function raycast(system: PhysicsSystem, ray: Ray3, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider) => boolean): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"raycast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/raycast.js"],"names":[],"mappings":"AA2HA;;;;;;;;;;;;;;;;;GAiBG;AACH,yGALmB,MAAM,yBAAsB,OAAO,GAGzC,OAAO,CA6GnB"}
+{"version":3,"file":"raycast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/raycast.js"],"names":[],"mappings":"AA2IA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,yGAJmB,MAAM,yBAAsB,OAAO,GAEzC,OAAO,CAwCnB"}