@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,74 +1,74 @@
-/**
- * In-place reduction of a strided contact-candidate buffer to at most `maxKept`
- * points:
- *   1. keep the deepest candidate (penetration depth at lane `depth_lane`) in
- *      slot 0;
- *   2. then greedily pick the candidate whose MINIMUM squared distance to the
- *      already-kept set is largest (farthest-point sampling) — a behaviour-
- *      preserving max-spread approximation that avoids degenerate near-coincident
- *      manifolds.
- *
- * The contact position is lanes 0,1,2 of each `stride`-float record; the buffer
- * is reordered in place and the caller reads the first `maxKept` records.
- *
- * Shared by {@link box_box_manifold} / {@link convex_convex_manifold} (stride 4,
- * depth lane 3), {@link box_triangle_contact} (stride 7, depth lane 6) and the
- * narrowphase dispatcher's pair-candidate buffer (stride 13, depth lane 9 —
- * lanes 10..12 are feature id / friction / restitution). Each previously
- * carried its own byte-identical copy.
- *
- * `depth_lane` is deliberately REQUIRED, not defaulted to `stride - 1`: the
- * candidate layouts genuinely differ (the dispatcher's lane 12 is RESTITUTION),
- * and a stride-derived default is exactly the trap that would silently rank
- * contacts by the wrong lane (REVIEW_003 E2).
- *
- * @param {Float64Array} buf  strided candidate buffer
- * @param {number} n          input candidate count
- * @param {number} stride     floats per candidate
- * @param {number} maxKept    maximum candidates to keep
- * @param {number} depth_lane lane within each record holding penetration depth
- * @returns {number} kept count = min(n, maxKept)
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function reduce_manifold_contacts(buf, n, stride, maxKept, depth_lane) {
-    if (n <= maxKept) return n;
-
-    // Deepest into slot 0.
-    let deepest_idx = 0;
-    let deepest_val = buf[depth_lane];
-    for (let i = 1; i < n; i++) {
-        const v = buf[i * stride + depth_lane];
-        if (v > deepest_val) { deepest_val = v; deepest_idx = i; }
-    }
-    if (deepest_idx !== 0) swap(buf, stride, 0, deepest_idx);
-
-    // Greedy farthest-point for the remaining slots.
-    for (let k = 1; k < maxKept; 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 = buf[i * stride] - buf[j * stride];
-                const dy = buf[i * stride + 1] - buf[j * stride + 1];
-                const dz = buf[i * stride + 2] - buf[j * 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; }
-        }
-        if (best_i !== k) swap(buf, stride, k, best_i);
-    }
-    return maxKept;
-}
-
-function swap(buf, stride, a, b) {
-    const ao = a * stride, bo = b * stride;
-    for (let k = 0; k < stride; k++) {
-        const t = buf[ao + k];
-        buf[ao + k] = buf[bo + k];
-        buf[bo + k] = t;
-    }
-}
+/**
+ * In-place reduction of a strided contact-candidate buffer to at most `maxKept`
+ * points:
+ *   1. keep the deepest candidate (penetration depth at lane `depth_lane`) in
+ *      slot 0;
+ *   2. then greedily pick the candidate whose MINIMUM squared distance to the
+ *      already-kept set is largest (farthest-point sampling) — a behaviour-
+ *      preserving max-spread approximation that avoids degenerate near-coincident
+ *      manifolds.
+ *
+ * The contact position is lanes 0,1,2 of each `stride`-float record; the buffer
+ * is reordered in place and the caller reads the first `maxKept` records.
+ *
+ * Shared by {@link box_box_manifold} / {@link convex_convex_manifold} (stride 4,
+ * depth lane 3), {@link box_triangle_contact} (stride 7, depth lane 6) and the
+ * narrowphase dispatcher's pair-candidate buffer (stride 13, depth lane 9 —
+ * lanes 10..12 are feature id / friction / restitution). Each previously
+ * carried its own byte-identical copy.
+ *
+ * `depth_lane` is deliberately REQUIRED, not defaulted to `stride - 1`: the
+ * candidate layouts genuinely differ (the dispatcher's lane 12 is RESTITUTION),
+ * and a stride-derived default is exactly the trap that would silently rank
+ * contacts by the wrong lane (REVIEW_003 E2).
+ *
+ * @param {Float64Array} buf  strided candidate buffer
+ * @param {number} n          input candidate count
+ * @param {number} stride     floats per candidate
+ * @param {number} maxKept    maximum candidates to keep
+ * @param {number} depth_lane lane within each record holding penetration depth
+ * @returns {number} kept count = min(n, maxKept)
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function reduce_manifold_contacts(buf, n, stride, maxKept, depth_lane) {
+    if (n <= maxKept) return n;
+
+    // Deepest into slot 0.
+    let deepest_idx = 0;
+    let deepest_val = buf[depth_lane];
+    for (let i = 1; i < n; i++) {
+        const v = buf[i * stride + depth_lane];
+        if (v > deepest_val) { deepest_val = v; deepest_idx = i; }
+    }
+    if (deepest_idx !== 0) swap(buf, stride, 0, deepest_idx);
+
+    // Greedy farthest-point for the remaining slots.
+    for (let k = 1; k < maxKept; 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 = buf[i * stride] - buf[j * stride];
+                const dy = buf[i * stride + 1] - buf[j * stride + 1];
+                const dz = buf[i * stride + 2] - buf[j * 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; }
+        }
+        if (best_i !== k) swap(buf, stride, k, best_i);
+    }
+    return maxKept;
+}
+
+function swap(buf, stride, a, b) {
+    const ao = a * stride, bo = b * stride;
+    for (let k = 0; k < stride; k++) {
+        const t = buf[ao + k];
+        buf[ao + k] = buf[bo + k];
+        buf[bo + k] = t;
+    }
+}

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

@@ -1,16 +1,17 @@
 /**
  * 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.
+ * 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), dispatches on the shape, and rotates
+ * the returned local normal back to world.
  *
- * 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).
+ * Exact for every shape the engine defines: the convex primitives (sphere / box / capsule / cylinder /
+ * convex hull / triangle / point), the concave ones (mesh / heightmap) by triangle decomposition, and
+ * the three wrappers ({@link PosedShape3D} / `TransformedShape3D` / `UnionShape3D`) by recursion into
+ * what they wrap. Only a shape from outside that set — a subclass defined by a consumer of the library
+ * — returns {@link RAY_REFINE_UNSUPPORTED}, for which the caller falls back to the shape's tight AABB.
+ * That fallback is an OVER-estimate of the solid: a ray crossing the box but missing the shape reports
+ * a phantom hit on the box, so it is a last resort and not a design.
  *
  * @param {AbstractShape3D} shape
  * @param {{x:number,y:number,z:number}} position  body world position
@@ -34,8 +35,8 @@ export function refine_ray_hit(shape: AbstractShape3D, position: {
 }, 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.
+ * test for. 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}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"refine_ray_hit.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/refine_ray_hit.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iEAdW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAC5B,UAAU,MAAM,CAAC,MACjB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QACN,MAAM,aACN,YAAY,UAAQ,GAElB,MAAM,CAsClB;AA7ED;;;;;;GAMG;AACH,qCAFU,MAAM,CAEyB"}
+{"version":3,"file":"refine_ray_hit.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/refine_ray_hit.js"],"names":[],"mappings":"AA6NA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iEAdW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAC5B,UAAU,MAAM,CAAC,MACjB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QACN,MAAM,aACN,YAAY,UAAQ,GAElB,MAAM,CA4BlB;AAzQD;;;;;;GAMG;AACH,qCAFU,MAAM,CAEyB"}

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

@@ -1,14 +1,18 @@
 import { box3_raycast } from "../../../core/geom/3d/box/box3_raycast.js";
 import { capsule_raycast } from "../../../core/geom/3d/capsule/capsule_raycast.js";
+import { convex_polyhedron3_raycast } from "../../../core/geom/3d/polyhedron/convex_polyhedron3_raycast.js";
+import { cylinder3_raycast } from "../../../core/geom/3d/cylinder/cylinder3_raycast.js";
+import { point3_raycast } from "../../../core/geom/3d/point/point3_raycast.js";
 import { sphere_raycast } from "../../../core/geom/3d/sphere/sphere_raycast.js";
+import { tri3_raycast } from "../../../core/geom/3d/triangle/tri3_raycast.js";
 import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
 import { v3_quaternion_apply_inverse } from "../../../core/geom/vec3/v3_quaternion_apply_inverse.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.
+ * test for. 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}
  */
@@ -18,19 +22,217 @@ 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
 
+/** Identity pose for delegating a ray that is ALREADY in the shape's frame. */
+const LOCAL_ORIGIN = { x: 0, y: 0, z: 0 };
+const LOCAL_IDENTITY = [0, 0, 0, 1];
+
+/**
+ * Ray ↔ shape in the shape's OWN frame — the dispatch every entry point below funnels into.
+ *
+ * Each branch is exact: a closed-form primitive for the convex leaves, the triangle decomposition for
+ * the concave ones, and a recursion for the three wrappers, which re-frame the ray into their
+ * subject's space and map the answer back. A shape the dispatch does not recognise (a subclass from
+ * outside the engine) returns {@link RAY_REFINE_UNSUPPORTED}.
+ *
+ * `outNormal` is threaded straight through the recursion instead of being buffered per level, which
+ * is safe — and is what makes the union's accumulator work — because every branch honours the family
+ * convention: **a miss returns `Infinity` and leaves `outNormal` untouched.** So when a union hands
+ * each child the best distance so far as its `tMax`, a child that writes the normal is exactly a child
+ * that won, and a child that loses cannot corrupt the standing answer.
+ *
+ * @param {AbstractShape3D} shape
+ * @param {number} ox  ray origin x (shape-local)
+ * @param {number} oy  ray origin y (shape-local)
+ * @param {number} oz  ray origin z (shape-local)
+ * @param {number} dx  ray dir x (shape-local, unit)
+ * @param {number} dy  ray dir y (shape-local, unit)
+ * @param {number} dz  ray dir z (shape-local, unit)
+ * @param {number} tMax
+ * @param {Float64Array} outNormal shape-local surface normal, written on a finite hit
+ * @returns {number} hit distance, `Infinity` on a miss, or {@link RAY_REFINE_UNSUPPORTED}
+ */
+function refine_ray_local(shape, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
+    if (shape.isSphereShape3D === true) {
+        return sphere_raycast(outNormal, 0, ox, oy, oz, dx, dy, dz, tMax, shape.radius);
+    }
+
+    if (shape.isBoxShape3D === true) {
+        const h = shape.half_extents;
+        return box3_raycast(outNormal, 0, ox, oy, oz, dx, dy, dz, tMax, h.x, h.y, h.z);
+    }
+
+    if (shape.isCapsuleShape3D === true) {
+        return capsule_raycast(outNormal, 0, ox, oy, oz, dx, dy, dz, tMax, shape.radius, shape.height * 0.5);
+    }
+
+    if (shape.isConvexHullShape3D === true) {
+        return convex_polyhedron3_raycast(
+            outNormal, 0, ox, oy, oz, dx, dy, dz, tMax,
+            shape.face_planes, shape.face_plane_count
+        );
+    }
+
+    if (shape.isCylinderShape3D === true) {
+        return cylinder3_raycast(outNormal, 0, ox, oy, oz, dx, dy, dz, tMax, shape.radius, shape.height * 0.5);
+    }
+
+    if (shape.isTriangle3D === true) {
+        const b = shape.buffer;
+        const o = shape.offset;
+        return tri3_raycast(
+            outNormal, 0, ox, oy, oz, dx, dy, dz, tMax,
+            b[o], b[o + 1], b[o + 2],
+            b[o + 3], b[o + 4], b[o + 5],
+            b[o + 6], b[o + 7], b[o + 8]
+        );
+    }
+
+    if (shape.isPointShape3D === true) {
+        return point3_raycast(outNormal, 0, ox, oy, oz, dx, dy, dz, tMax);
+    }
+
+    if (shape.isPosedShape3D === true) {
+        return refine_ray_posed(shape, ox, oy, oz, dx, dy, dz, tMax, outNormal);
+    }
+
+    if (shape.isTransformedShape3D === true) {
+        return refine_ray_transformed(shape, ox, oy, oz, dx, dy, dz, tMax, outNormal);
+    }
+
+    if (shape.isUnionShape3D === true) {
+        return refine_ray_union(shape, ox, oy, oz, dx, dy, dz, tMax, outNormal);
+    }
+
+    if (shape.isMeshShape3D === true || shape.isHeightMapShape3D === true) {
+        // Already in the shape's frame, so the pose it would transform by is the identity — which its
+        // quaternion round trip reproduces exactly, no drift.
+        return refine_ray_concave(
+            shape, LOCAL_ORIGIN, LOCAL_IDENTITY,
+            ox, oy, oz, dx, dy, dz, tMax, outNormal
+        );
+    }
+
+    return RAY_REFINE_UNSUPPORTED;
+}
+
+/**
+ * {@link PosedShape3D}: a rigid pose around a subject. The inverse rotation preserves unit length, so
+ * the subject's hit distance is the wrapper's unchanged and only the normal needs rotating back.
+ */
+function refine_ray_posed(shape, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
+    const qx = shape.qx, qy = shape.qy, qz = shape.qz, qw = shape.qw;
+
+    // `lo` / `ld` are shared with every level of this recursion, so what they hold is live only until it
+    // is read out on the next two lines — the call below hands them to the level beneath.
+    v3_quaternion_apply_inverse(lo, 0, ox - shape.px, oy - shape.py, oz - shape.pz, qx, qy, qz, qw);
+    v3_quaternion_apply_inverse(ld, 0, dx, dy, dz, qx, qy, qz, qw);
+    const sox = lo[0], soy = lo[1], soz = lo[2];
+    const sdx = ld[0], sdy = ld[1], sdz = ld[2];
+
+    const t = refine_ray_local(shape.shape, sox, soy, soz, sdx, sdy, sdz, tMax, outNormal);
+    if (t === Infinity || t === RAY_REFINE_UNSUPPORTED) return t;
+
+    v3_quaternion_apply(outNormal, 0, outNormal[0], outNormal[1], outNormal[2], qx, qy, qz, qw);
+
+    return t;
+}
+
+/**
+ * {@link TransformedShape3D}: an arbitrary affine transform around a subject.
+ *
+ * The inverse matrix carries the ray into the subject's frame, where the direction is no longer unit —
+ * a scaled shape stretches distance along the ray — so it is renormalised and the scale factor is
+ * carried on both `tMax` (into the subject) and the returned distance (back out). The normal is the
+ * one quantity that does NOT transform by the matrix: it maps by the inverse TRANSPOSE, which is what
+ * keeps a normal perpendicular to its surface under non-uniform scale.
+ *
+ * PRECONDITION: the transform is invertible. A singular matrix has no inverse for the class to have
+ * cached, and the ray it produces is degenerate.
+ */
+function refine_ray_transformed(shape, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
+    const inverse = shape.inverse_transform;
+
+    // Column-major affine: point transform (with translation), then direction (linear part only).
+    const sox = inverse[0] * ox + inverse[4] * oy + inverse[8] * oz + inverse[12];
+    const soy = inverse[1] * ox + inverse[5] * oy + inverse[9] * oz + inverse[13];
+    const soz = inverse[2] * ox + inverse[6] * oy + inverse[10] * oz + inverse[14];
+
+    const sdx = inverse[0] * dx + inverse[4] * dy + inverse[8] * dz;
+    const sdy = inverse[1] * dx + inverse[5] * dy + inverse[9] * dz;
+    const sdz = inverse[2] * dx + inverse[6] * dy + inverse[10] * dz;
+
+    // How much longer one unit of wrapper-space travel is in subject space.
+    const scale = Math.sqrt(sdx * sdx + sdy * sdy + sdz * sdz);
+    const inv_scale = 1 / scale;
+
+    const t = refine_ray_local(
+        shape.subject,
+        sox, soy, soz,
+        sdx * inv_scale, sdy * inv_scale, sdz * inv_scale,
+        tMax * scale,
+        outNormal
+    );
+    if (t === Infinity || t === RAY_REFINE_UNSUPPORTED) return t;
+
+    // Inverse transpose: (M⁻¹)ᵀ · n, then renormalise — non-uniform scale does not preserve length.
+    const nx = outNormal[0], ny = outNormal[1], nz = outNormal[2];
+    const wx = inverse[0] * nx + inverse[1] * ny + inverse[2] * nz;
+    const wy = inverse[4] * nx + inverse[5] * ny + inverse[6] * nz;
+    const wz = inverse[8] * nx + inverse[9] * ny + inverse[10] * nz;
+
+    const inv_length = 1 / Math.sqrt(wx * wx + wy * wy + wz * wz);
+    outNormal[0] = wx * inv_length;
+    outNormal[1] = wy * inv_length;
+    outNormal[2] = wz * inv_length;
+
+    return t * inv_scale;
+}
+
+/**
+ * {@link UnionShape3D}: the nearest hit across the children, all of which share the union's frame.
+ *
+ * Each child is handed the best distance found so far as its `tMax`, so a child can only return a
+ * finite distance by beating every child before it — which is also what makes it safe for the children
+ * to write straight into `outNormal`.
+ *
+ * A child the dispatch cannot answer exactly poisons the whole union: reporting the nearest of the
+ * children we *could* answer would be a hit that is confidently too far, which is worse than admitting
+ * the union is unsupported and letting the caller fall back to its bounding box.
+ */
+function refine_ray_union(shape, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
+    const children = shape.children;
+    const count = children.length;
+
+    let best = tMax;
+    let found = false;
+
+    for (let i = 0; i < count; i++) {
+        const t = refine_ray_local(children[i], ox, oy, oz, dx, dy, dz, best, outNormal);
+
+        if (t === RAY_REFINE_UNSUPPORTED) return RAY_REFINE_UNSUPPORTED;
+        if (t === Infinity) continue;
+
+        best = t;
+        found = true;
+    }
+
+    return found ? best : Infinity;
+}
+
 /**
  * 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.
+ * 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), dispatches on the shape, and rotates
+ * the returned local normal back to world.
  *
- * 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).
+ * Exact for every shape the engine defines: the convex primitives (sphere / box / capsule / cylinder /
+ * convex hull / triangle / point), the concave ones (mesh / heightmap) by triangle decomposition, and
+ * the three wrappers ({@link PosedShape3D} / `TransformedShape3D` / `UnionShape3D`) by recursion into
+ * what they wrap. Only a shape from outside that set — a subclass defined by a consumer of the library
+ * — returns {@link RAY_REFINE_UNSUPPORTED}, for which the caller falls back to the shape's tight AABB.
+ * That fallback is an OVER-estimate of the solid: a ray crossing the box but missing the shape reports
+ * a phantom hit on the box, so it is a last resort and not a design.
  *
  * @param {AbstractShape3D} shape
  * @param {{x:number,y:number,z:number}} position  body world position
@@ -54,32 +256,22 @@ export function refine_ray_hit(shape, position, rotation, ox, oy, oz, dx, dy, dz
         return sphere_raycast(outNormal, 0, 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_quaternion_apply_inverse(lo, 0, ox - position.x, oy - position.y, oz - position.z, qx, qy, qz, qw);
-        v3_quaternion_apply_inverse(ld, 0, dx, dy, dz, qx, qy, qz, qw);
-
-        let t;
-        if (shape.isBoxShape3D === true) {
-            const h = shape.half_extents;
-            t = box3_raycast(ln, 0, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, h.x, h.y, h.z);
-        } else {
-            t = capsule_raycast(ln, 0, 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_quaternion_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) {
+    if (shape.isMeshShape3D === true || shape.isHeightMapShape3D === true) {
+        // Concave: the triangle decomposition does its own world → local step, so going through the
+        // local dispatch would transform the ray twice.
         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;
+    const qx = rotation[0], qy = rotation[1], qz = rotation[2], qw = rotation[3];
+    // World → local: rotate by the inverse (conjugate) body rotation.
+    v3_quaternion_apply_inverse(lo, 0, ox - position.x, oy - position.y, oz - position.z, qx, qy, qz, qw);
+    v3_quaternion_apply_inverse(ld, 0, dx, dy, dz, qx, qy, qz, qw);
+
+    const t = refine_ray_local(shape, lo[0], lo[1], lo[2], ld[0], ld[1], ld[2], tMax, ln);
+    if (t === Infinity || t === RAY_REFINE_UNSUPPORTED) return t;
+
+    // Local normal → world: rotate by the body rotation.
+    v3_quaternion_apply(outNormal, 0, ln[0], ln[1], ln[2], qx, qy, qz, qw);
+
+    return t;
 }

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

@@ -1,52 +1,52 @@
-/**
- * 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.
- *
- * 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.
- *
- * @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;
-}
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @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;
+}