@woosh/meep-engine 2.141.0 → 2.142.0

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.isUnitSphereShape3D === 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, 1);
+    }
+
+    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/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"}

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

@@ -8,42 +8,67 @@ import {
 } from "../../../core/bvh2/bvh3/BVH.js";
 import { returnTrue } from "../../../core/function/returnTrue.js";
 import { aabb3_near_distance_to_intersection_ray_segment } from "../../../core/geom/3d/aabb/aabb3_near_distance_to_intersection_ray_segment.js";
+import { refine_ray_hit, RAY_REFINE_UNSUPPORTED } from "../narrowphase/refine_ray_hit.js";
 
 const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
 
 /**
- * Walk a single BVH along a ray and update the running nearest hit.
+ * Reusable nearest-hit accumulator + scratch. Module-scoped so {@link raycast}
+ * doesn't allocate per call; the physics step is single-threaded so contention
+ * isn't a concern.
+ * @type {{best_t:number, best_body:number}}
+ */
+const acc = { best_t: Infinity, best_body: 0 };
+const best_normal = new Float64Array(3); // winning hit's world normal
+const cand_normal = new Float64Array(3); // per-leaf candidate normal
+
+/**
+ * Outward AABB-face normal at a hit point — the fallback normal for a leaf
+ * whose shape has no exact ray test (composite convex). The hit point is
+ * projected into the AABB's normalised local space (centre = 0, faces = ±1);
+ * the dominant component's axis is the entry face and its sign the outward
+ * normal.
+ */
+function aabb_face_normal(out, min_x, min_y, min_z, max_x, max_y, max_z, hx, hy, hz) {
+    const cx = (min_x + max_x) * 0.5;
+    const cy = (min_y + max_y) * 0.5;
+    const cz = (min_z + max_z) * 0.5;
+    const px = (hx - cx) * 2 / (max_x - min_x);
+    const py = (hy - cy) * 2 / (max_y - min_y);
+    const pz = (hz - cz) * 2 / (max_z - min_z);
+    const apx = px < 0 ? -px : px;
+    const apy = py < 0 ? -py : py;
+    const apz = pz < 0 ? -pz : pz;
+    if (apx >= apy && apx >= apz) { out[0] = px >= 0 ? 1 : -1; out[1] = 0; out[2] = 0; }
+    else if (apy >= apz) { out[0] = 0; out[1] = py >= 0 ? 1 : -1; out[2] = 0; }
+    else { out[0] = 0; out[1] = 0; out[2] = pz >= 0 ? 1 : -1; }
+}
+
+/**
+ * Walk a single BVH along a ray, refining each crossing leaf against its true
+ * shape geometry and keeping the nearest confirmed hit.
  *
- * Hit refinement is broadphase-only: the returned `t` is the distance to
- * the inflated leaf AABB. Narrowphase shape refinement is a follow-up.
+ * Pruning stays on the *inflated leaf AABB* entry distance `t_near`: a shape
+ * hit is always at or beyond its tight AABB entry, which is at or beyond the
+ * inflated-AABB entry, so a subtree whose AABB entry is past the current best
+ * cannot contain a closer hit. A leaf whose ray crosses the fat AABB but misses
+ * the true shape contributes nothing — the correctness gain over broadphase.
  *
- * @param {BVH} bvh
- * @param {number} root
- * @param {number} ox
- * @param {number} oy
- * @param {number} oz
- * @param {number} dx
- * @param {number} dy
- * @param {number} dz
- * @param {number} inv_dx
- * @param {number} inv_dy
- * @param {number} inv_dz
+ * @param {BVH} bvh @param {number} root
+ * @param {PhysicsSystem} system
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (unit)
+ * @param {number} inv_dx @param {number} inv_dy @param {number} inv_dz
  * @param {number} max_distance
- * @param {{best_t:number, best_body:number, best_node:number, best_bvh:BVH|null}} acc
- * @param {(body_id:number)=>boolean} test  per-leaf filter
+ * @param {(entity:number, collider:Collider)=>boolean} filter
  */
 function bvh_raycast_nearest(
-    bvh, root,
-    ox, oy, oz,
-    dx, dy, dz,
+    bvh, root, system,
+    ox, oy, oz, dx, dy, dz,
     inv_dx, inv_dy, inv_dz,
-    max_distance,
-    acc,
-    test
+    max_distance, filter
 ) {
-    if (root === NULL_NODE) {
-        return;
-    }
+    if (root === NULL_NODE) return;
 
     const float32 = bvh.__data_float32;
     const uint32 = bvh.__data_uint32;
@@ -66,181 +91,105 @@ function bvh_raycast_nearest(
         );
 
         // No intersection or this subtree can't beat the best known hit — prune.
-        if (t_near >= acc.best_t) {
-            continue;
-        }
+        if (t_near >= acc.best_t) continue;
 
         const child_1 = uint32[address + COLUMN_CHILD_1];
         if (child_1 !== NULL_NODE) {
             stack[pointer++] = uint32[address + COLUMN_CHILD_2];
             stack[pointer++] = child_1;
-        } else {
-            const body_id = uint32[address + COLUMN_USER_DATA];
-            if (test(body_id)) {
+            continue;
+        }
+
+        // Leaf — refine against the true shape.
+        const body_id = uint32[address + COLUMN_USER_DATA];
+        const entity = system.entityOf(body_id);
+        if (entity < 0) continue; // unlinked concurrently
+        const idx = system.__index_of(body_id);
+        const collider = system.__primary_collider(idx);
+        if (collider === null) continue;
+        if (!filter(entity, collider)) continue;
+
+        const tr = system.__transforms[idx];
+        const refined = refine_ray_hit(
+            collider.shape, tr.position, tr.rotation,
+            ox, oy, oz, dx, dy, dz, acc.best_t, cand_normal
+        );
+
+        if (refined === RAY_REFINE_UNSUPPORTED) {
+            // No exact ray test for this shape — keep the broadphase AABB hit.
+            if (t_near < acc.best_t) {
                 acc.best_t = t_near;
                 acc.best_body = body_id;
-                acc.best_node = node;
-                acc.best_bvh = bvh;
+                aabb_face_normal(best_normal,
+                    float32[address], float32[address + 1], float32[address + 2],
+                    float32[address + 3], float32[address + 4], float32[address + 5],
+                    ox + dx * t_near, oy + dy * t_near, oz + dz * t_near);
             }
+        } else if (refined < acc.best_t) { // a refined miss is Infinity → never wins
+            acc.best_t = refined;
+            acc.best_body = body_id;
+            best_normal[0] = cand_normal[0];
+            best_normal[1] = cand_normal[1];
+            best_normal[2] = cand_normal[2];
         }
     }
 
     stack.pointer = stack_top;
 }
 
-/**
- * Reusable nearest-hit accumulator. Module-scoped so {@link raycast} doesn't
- * allocate per call. The physics step is single-threaded so contention isn't
- * a concern.
- * @type {{best_t:number, best_body:number, best_node:number, best_bvh:BVH|null}}
- */
-const acc = { best_t: Infinity, best_body: 0, best_node: 0, best_bvh: null };
-
-/**
- * Reusable closure bound to the current system + user filter so we don't
- * allocate a new function object per call. Re-wired at the top of each
- * {@link raycast} invocation. The BVH traversal sees a stable identity
- * which helps V8 keep the call site monomorphic.
- *
- * Carries state via the module-scoped `bound_*` slots below.
- * @type {(body_id:number)=>boolean}
- */
-const bound_test = (body_id) => {
-    const system = bound_system;
-    const entity = system.entityOf(body_id);
-    if (entity < 0) return false;
-    // v1 limitation: when a multi-collider body's BVH leaf is hit, we pass
-    // the body's primary (first-attached) collider rather than the specific
-    // collider the ray actually crossed. Sufficient for entity-level
-    // filtering; per-collider filtering needs the BVH user_data scheme to
-    // encode collider index too — future work.
-    const collider = system.__primary_collider(system.__index_of(body_id));
-    return bound_filter(entity, collider);
-};
-
-let bound_system = null;
-let bound_filter = returnTrue;
-
 /**
  * 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, ray, result, filter = returnTrue) {
-    const ox = ray.origin_x;
-    const oy = ray.origin_y;
-    const oz = ray.origin_z;
-    const dx = ray.direction_x;
-    const dy = ray.direction_y;
-    const dz = ray.direction_z;
+    const ox = ray.origin_x, oy = ray.origin_y, oz = ray.origin_z;
+    const dx = ray.direction_x, dy = ray.direction_y, dz = ray.direction_z;
     const max_distance = ray.tMax;
 
     acc.best_t = max_distance;
     acc.best_body = 0;
-    acc.best_node = 0;
-    acc.best_bvh = null;
+    best_normal[0] = 0; best_normal[1] = 0; best_normal[2] = 0;
 
-    bound_system = system;
-    bound_filter = filter;
-
-    const inv_dx = 1 / dx;
-    const inv_dy = 1 / dy;
-    const inv_dz = 1 / dz;
+    const inv_dx = 1 / dx, inv_dy = 1 / dy, inv_dz = 1 / dz;
 
     bvh_raycast_nearest(
-        system.staticBvh, system.staticBvh.root,
-        ox, oy, oz,
-        dx, dy, dz,
-        inv_dx, inv_dy, inv_dz,
-        max_distance,
-        acc, bound_test
+        system.staticBvh, system.staticBvh.root, system,
+        ox, oy, oz, dx, dy, dz, inv_dx, inv_dy, inv_dz, max_distance, filter
     );
-
     bvh_raycast_nearest(
-        system.dynamicBvh, system.dynamicBvh.root,
-        ox, oy, oz,
-        dx, dy, dz,
-        inv_dx, inv_dy, inv_dz,
-        max_distance,
-        acc, bound_test
+        system.dynamicBvh, system.dynamicBvh.root, system,
+        ox, oy, oz, dx, dy, dz, inv_dx, inv_dy, inv_dz, max_distance, filter
     );
 
-    if (acc.best_bvh === null || acc.best_t >= max_distance) {
-        return false;
-    }
+    // Any hit updates best_t to strictly below max_distance (both the refined
+    // and AABB-fallback paths require t < current best); a miss leaves it at
+    // max_distance. This is body_id-agnostic — the first body packs to id 0.
+    if (acc.best_t >= max_distance) return false;
 
     const entity = system.entityOf(acc.best_body);
-    if (entity < 0) {
-        // Body was unlinked concurrently; treat as a miss.
-        return false;
-    }
+    if (entity < 0) return false; // body unlinked concurrently → treat as miss
 
-    // Hit position in world space.
     const t = acc.best_t;
-    const hx = ox + dx * t;
-    const hy = oy + dy * t;
-    const hz = oz + dz * t;
-
-    // AABB face normal at the hit point. Read the best leaf's AABB back from
-    // its BVH; project the hit point into the AABB's normalised local space
-    // (centre = 0, faces = ±1); the dominant component is the entry-face
-    // axis, its sign gives the outward normal.
-    const bvh = acc.best_bvh;
-    const node_address = acc.best_node * ELEMENT_WORD_COUNT;
-    const f32 = bvh.__data_float32;
-    const aabb_min_x = f32[node_address];
-    const aabb_min_y = f32[node_address + 1];
-    const aabb_min_z = f32[node_address + 2];
-    const aabb_max_x = f32[node_address + 3];
-    const aabb_max_y = f32[node_address + 4];
-    const aabb_max_z = f32[node_address + 5];
-
-    const cx = (aabb_min_x + aabb_max_x) * 0.5;
-    const cy = (aabb_min_y + aabb_max_y) * 0.5;
-    const cz = (aabb_min_z + aabb_max_z) * 0.5;
-    // Multiplicative inverse of the half-extent saves one divide per axis.
-    // A degenerate AABB (zero extent on an axis) is impossible for live BVH
-    // leaves — physics shapes always have non-zero bounding extent.
-    const inv_half_x = 2 / (aabb_max_x - aabb_min_x);
-    const inv_half_y = 2 / (aabb_max_y - aabb_min_y);
-    const inv_half_z = 2 / (aabb_max_z - aabb_min_z);
-
-    const px = (hx - cx) * inv_half_x;
-    const py = (hy - cy) * inv_half_y;
-    const pz = (hz - cz) * inv_half_z;
-
-    const apx = px < 0 ? -px : px;
-    const apy = py < 0 ? -py : py;
-    const apz = pz < 0 ? -pz : pz;
-
-    let nx, ny, nz;
-    if (apx >= apy && apx >= apz) {
-        nx = px >= 0 ? 1 : -1; ny = 0; nz = 0;
-    } else if (apy >= apz) {
-        nx = 0; ny = py >= 0 ? 1 : -1; nz = 0;
-    } else {
-        nx = 0; ny = 0; nz = pz >= 0 ? 1 : -1;
-    }
-
-    // Fill result. Direct typed-array writes — Vector3 extends Float32Array,
-    // and there are no observers subscribed to a query-result vector.
     const rp = result.position;
     const rn = result.normal;
-    rp[0] = hx; rp[1] = hy; rp[2] = hz;
-    rn[0] = nx; rn[1] = ny; rn[2] = nz;
+    rp[0] = ox + dx * t; rp[1] = oy + dy * t; rp[2] = oz + dz * t;
+    rn[0] = best_normal[0]; rn[1] = best_normal[1]; rn[2] = best_normal[2];
     result.t = t;
     result.entity = entity;
     result.body_id = acc.best_body;