@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -5,12 +5,14 @@ import {
     ELEMENT_WORD_COUNT,
     NULL_NODE,
 } from "../../../core/bvh2/bvh3/BVH.js";
+import { assert } from "../../../core/assert.js";
 import { SCRATCH_UINT32_TRAVERSAL_STACK } from "../../../core/collection/SCRATCH_UINT32_TRAVERSAL_STACK.js";
 import { returnTrue } from "../../../core/function/returnTrue.js";
 import { aabb3_ray_segment_entry_distance } from "../../../core/geom/3d/aabb/aabb3_ray_segment_entry_distance.js";
 import { body_id_index } from "../body/BodyStorage.js";
 import { is_sensor } from "../ecs/is_sensor.js";
 import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { refine_ray_concave_hit_feature } from "../narrowphase/refine_ray_concave.js";
 import { RAY_REFINE_UNSUPPORTED, refine_ray_hit } from "../narrowphase/refine_ray_hit.js";
 
 const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
@@ -19,16 +21,58 @@ const stack = SCRATCH_UINT32_TRAVERSAL_STACK;
 const scratch_tight_local = new Float64Array(6);
 const scratch_tight_world = new Float64Array(6);
 
+/**
+ * The collider's pose as the arrays {@link refine_ray_hit} takes, copied out of its transform: reading
+ * a Transform64's `translation` or `rotation` builds a fresh view on every read. Filled right before
+ * the call and not held across the filter, which may run a query of its own.
+ */
+const scratch_collider_position = new Float64Array(3);
+const scratch_collider_rotation = new Float64Array(4);
+
 /**
  * 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}}
+ * @type {{best_t:number, best_body:number, best_collider_entity:number, best_triangle:number}}
  */
-const acc = { best_t: Infinity, best_body: 0 };
+const acc = { best_t: Infinity, best_body: 0, best_collider_entity: -1, best_triangle: -1 };
 const best_normal = new Float64Array(3); // winning hit's world normal
 const cand_normal = new Float64Array(3); // per-leaf candidate normal
 
+/**
+ * "Already tested in this query" stamps, indexed by body index. Every collider
+ * of a body owns a separate broadphase leaf carrying that body's id, and the
+ * first of them the ray reaches tests all of the body's colliders, so the rest
+ * would only repeat it — a ray along a row of K children asked the filter, and
+ * tested, every collider K times. Stamped rather than cleared so the cost
+ * stays O(1) per query; the same scheme as `overlap_shape`'s.
+ * @type {Int32Array}
+ */
+let scratch_seen = new Int32Array(64);
+
+/**
+ * Stamp written into {@link scratch_seen} by the query in progress. Starts
+ * at 1 so a freshly zeroed (or freshly grown) slot never reads as seen.
+ * @type {number}
+ */
+let seen_stamp = 0;
+
+/**
+ * Whether a {@link raycast} is in progress. Its accumulator, its stamps and its
+ * hit are module state, so a raycast started from inside one — from its filter
+ * — would overwrite the outer's half-finished answer.
+ *
+ * The refusal is an assert, and a consumer's production build strips asserts:
+ * there nothing refuses it, and the outer raycast answers wrong without a word
+ * — measured, a ray whose filter cast another ray named entity 8 at t 1.5,
+ * where the truth is entity 1 at t 2.5.
+ * @type {boolean}
+ */
+let raycast_running = false;
+
+const NESTED_RAYCAST = 'raycast: called from inside a raycast, from its filter. A raycast keeps its working state'
+    + ' in module scratch, so it cannot run inside another; a shapeCast or an overlap can.';
+
 /**
  * Outward AABB-face normal at a hit point — the fallback normal for a leaf
  * whose shape has no exact ray test (only a shape defined outside the engine).
@@ -119,13 +163,29 @@ function bvh_raycast_nearest(
 
         // Leaf — refine against the true shape.
         const body_id = uint32[address + COLUMN_USER_DATA];
+        const idx = body_id_index(body_id);
+
+        if (idx >= scratch_seen.length) {
+            // Preserve the stamps already written this query.
+            const grown = new Int32Array(Math.max(idx + 1, scratch_seen.length * 2));
+            grown.set(scratch_seen);
+            scratch_seen = grown;
+        }
+        // Another leaf of a body already tested: every collider of it was.
+        if (scratch_seen[idx] === seen_stamp) continue;
+        scratch_seen[idx] = seen_stamp;
+
         const entity = system.entityOf(body_id);
         if (entity < 0) continue; // unlinked concurrently
-        const idx = body_id_index(body_id);
         const rb = system.__bodies[idx];
         const colliders = system.__body_collider_lists[idx];
         if (colliders === undefined) continue;
 
+        // The filter may run a query of its own, and every query walks this same
+        // stack from its live pointer: publish this frame first, or that query
+        // starts on top of the nodes still pending here and overwrites them.
+        stack.pointer = pointer;
+
         // Every collider carries its OWN world transform: a compound body's
         // collider can live on a child entity metres from the body's pose, and
         // the leaf that got us here was built and refit from that transform.
@@ -140,8 +200,17 @@ function bvh_raycast_nearest(
             if (!filter(entity, collider)) continue;
 
             const tr = entry.transform;
+
+            scratch_collider_position[0] = tr.translation_x;
+            scratch_collider_position[1] = tr.translation_y;
+            scratch_collider_position[2] = tr.translation_z;
+            scratch_collider_rotation[0] = tr.rotation_x;
+            scratch_collider_rotation[1] = tr.rotation_y;
+            scratch_collider_rotation[2] = tr.rotation_z;
+            scratch_collider_rotation[3] = tr.rotation_w;
+
             const refined = refine_ray_hit(
-                collider.shape, tr.translation, tr.rotation,
+                collider.shape, scratch_collider_position, scratch_collider_rotation,
                 ox, oy, oz, dx, dy, dz, acc.best_t, cand_normal
             );
 
@@ -170,6 +239,8 @@ function bvh_raycast_nearest(
                 if (tight_t < acc.best_t) { // Infinity on miss — pad-only crossings drop out
                     acc.best_t = tight_t;
                     acc.best_body = body_id;
+                    acc.best_collider_entity = entry.entity;
+                    acc.best_triangle = -1;
                     aabb_face_normal(best_normal,
                         scratch_tight_world[0], scratch_tight_world[1], scratch_tight_world[2],
                         scratch_tight_world[3], scratch_tight_world[4], scratch_tight_world[5],
@@ -178,6 +249,14 @@ function bvh_raycast_nearest(
             } else if (refined < acc.best_t) { // a refined miss is Infinity → never wins
                 acc.best_t = refined;
                 acc.best_body = body_id;
+                acc.best_collider_entity = entry.entity;
+                // A mesh or heightmap collider is refined by its triangles, and the
+                // last one to hit is this one. (Wrapped in another shape, it is not
+                // named: a wrapper may test more than one subject.)
+                const shape = collider.shape;
+                acc.best_triangle = shape.isMeshShape3D === true || shape.isHeightMapShape3D === true
+                    ? refine_ray_concave_hit_feature() - 1
+                    : -1;
                 best_normal[0] = cand_normal[0];
                 best_normal[1] = cand_normal[1];
                 best_normal[2] = cand_normal[2];
@@ -206,18 +285,49 @@ function bvh_raycast_nearest(
  * nearest solid surface behind it. This is the only behaviour — a query that
  * wants to find trigger volumes uses an overlap query, not a ray.
  *
- * 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).
+ * Every collider of a multi-collider body is tested, each at its own pose, and
+ * the result names the one struck: `result.collider_entity` is the entity that
+ * owns it, and `result.triangle` the triangle of a mesh or heightmap collider
+ * (`-1` otherwise, and for one wrapped in another shape).
+ *
+ * The filter may run a shapeCast or an overlap of its own, but not another
+ * raycast: a raycast keeps its working state in module scratch, and one started
+ * from its filter is refused by an assert.
  *
  * @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] called once per
- *   crossing leaf; defaults to {@link returnTrue}.
+ *   collider of each body whose broadphase leaves the ray crosses, however many
+ *   of those leaves it crosses; defaults to {@link returnTrue}.
  * @returns {boolean} true on hit, false on miss
  */
 export function raycast(system, ray, result, filter = returnTrue) {
+    assert.ok(!raycast_running, NESTED_RAYCAST);
+
+    raycast_running = true;
+    const stack_entry = stack.pointer;
+    try {
+        return raycast_nearest(system, ray, result, filter);
+    } finally {
+        // also on the way out of a throw — a filter's own error, or the assert
+        // above in a query the filter started — so the next query is not refused
+        // and the stack is left as found
+        raycast_running = false;
+        stack.pointer = stack_entry;
+    }
+}
+
+/**
+ * {@link raycast}, unguarded.
+ *
+ * @param {PhysicsSystem} system
+ * @param {Ray3} ray
+ * @param {PhysicsSurfacePoint} result
+ * @param {(entity:number, collider:Collider)=>boolean} filter
+ * @returns {boolean}
+ */
+function raycast_nearest(system, ray, result, filter) {
     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;
@@ -226,6 +336,14 @@ export function raycast(system, ray, result, filter = returnTrue) {
     acc.best_body = 0;
     best_normal[0] = 0; best_normal[1] = 0; best_normal[2] = 0;
 
+    // Fresh stamp for this query; wrap back to a cleared table before the
+    // counter could collide with a stamp left behind by an older query.
+    seen_stamp++;
+    if (seen_stamp >= 0x7FFFFFFF) {
+        scratch_seen.fill(0);
+        seen_stamp = 1;
+    }
+
     const inv_dx = 1 / dx, inv_dy = 1 / dy, inv_dz = 1 / dz;
 
     bvh_raycast_nearest(
@@ -240,7 +358,11 @@ export function raycast(system, ray, result, filter = returnTrue) {
     // 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;
+    // Asked as "a hit is below the reach" rather than "a miss is not", so that
+    // a reach that is not a number reaches nothing: NaN fails every comparison,
+    // and a NaN best_t used to read as a hit on whatever body the walk last
+    // looked at — a box 100 m off the ray's line.
+    if (!(acc.best_t < max_distance)) return false;
 
     const entity = system.entityOf(acc.best_body);
     if (entity < 0) return false; // body unlinked concurrently → treat as miss
@@ -253,6 +375,8 @@ export function raycast(system, ray, result, filter = returnTrue) {
     result.t = t;
     result.entity = entity;
     result.body_id = acc.best_body;
+    result.collider_entity = acc.best_collider_entity;
+    result.triangle = acc.best_triangle;
 
     return true;
 }

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

@@ -11,35 +11,46 @@
  *      stretched along `ray.direction * ray.tMax`.
  *   2. Query both broadphase BVHs (static + dynamic) for leaves whose
  *      AABB overlaps the swept volume.
- *   3. For each candidate, bisect the [0, best_t] interval for the
- *      smallest `t` at which the swept shape overlaps the candidate's
- *      collider. GJK on each midpoint.
+ *   3. For each candidate, advance the swept shape toward the candidate's
+ *      collider by conservative advancement on the GJK distance (see
+ *      `advance_to_contact`) for the smallest `t` at which it touches and
+ *      goes on into it, within [0, best_t). A concave collider (mesh,
+ *      heightmap) is a surface, not the solid its hull encloses: it is
+ *      swept as the set of its triangles under the swept AABB, each one a
+ *      convex candidate under the same rules.
  *
- * Picking `best_t` (rather than always running the full [0, tMax]
- * bisection) is the early-termination optimisation: once we have a
- * hit at some t, no later candidate can produce a smaller TOI by
- * being checked at its full [0, tMax] interval.
+ * Searching only [0, best_t) (rather than always the full [0, tMax]) is the
+ * early-termination optimisation: once we have a hit at some t, no later
+ * candidate can produce a smaller TOI by being checked over the rest.
  *
  * Output on hit:
  *   - `result.t` — sweep distance to impact (in the same units as
  *     `ray.direction`'s magnitude; for a unit-direction ray, this is
- *     metres).
+ *     metres). The swept shape there is still apart from what it struck
+ *     — by about {@link ADVANCE_TARGET}, or within the bracket search's
+ *     resolution when that found it — so a caller can place a body there.
  *   - `result.position` — `ray.origin + t * ray.direction`, i.e. the
  *     centre of the swept shape at the moment of first contact. NOT
- *     a point on the target's surface; that would need narrowphase
- *     refinement which the broadphase-only architecture doesn't have
- *     wired up yet.
+ *     a point on the target's surface.
  *   - `result.normal` — target surface's outward normal at the kiss
- *     point (unit length), recovered by running MPR against the
- *     just-overlapping configuration at the TOI. A pair that is exactly
- *     tangent there carries no MTV to read, so a second probe nudged
- *     toward the target's centre supplies one; `-ray.direction` remains
- *     the last-resort fallback if both degenerate. See the
- *     contact-normal recovery block near the end of the function.
+ *     point (unit length): the separating direction advancement stopped
+ *     on, or a triangle face's own normal. A cast blocked where it starts
+ *     reads it off by MPR, and a pair exactly tangent there carries no MTV
+ *     to read, so a second probe nudged toward the target's centre
+ *     supplies one; `-ray.direction` remains the last-resort fallback if
+ *     both degenerate. See the contact-normal block near the end of the
+ *     function.
  *   - `result.entity` / `result.body_id` — the hit body.
+ *   - `result.collider_entity` — the entity owning the struck collider (a
+ *     compound body's child's own); `result.triangle` — the struck triangle of
+ *     a mesh or heightmap collider, `-1` for any other.
  *
  * Output on miss: untouched; same convention as `raycast`.
  *
+ * The filter may run a raycast or an overlap of its own, but not another cast:
+ * a cast keeps its working state in module scratch, and one started from its
+ * filter is refused by an assert.
+ *
  * @param {PhysicsSystem} system
  * @param {Ray3|{origin_x:number,origin_y:number,origin_z:number,direction_x:number,direction_y:number,direction_z:number,tMax:number}} ray
  *   origin + unit direction + `tMax`. Only the named accessors are read, so a
@@ -49,27 +60,31 @@
  * @param {ArrayLike<number>} rotation  the orientation the shape is held at for
  *   the whole sweep, read BY INDEX as `[x, y, z, w]` and taken to be a unit
  *   quaternion (it is neither normalised nor validated here — a non-unit one
- *   silently returns wrong answers). A `Transform64`'s `rotation` (a
- *   `Float64Array` view — what the CCD pass hands in), a `Quaternion`
+ *   silently returns wrong answers). A retained `Float64Array` (what the CCD
+ *   pass hands in: the body's orientation copied out of its Transform64, whose
+ *   `rotation` accessor allocates a view per read), a `Quaternion`
  *   (`Float64Array`-backed) and a plain `[x, y, z, w]` array all satisfy that;
  *   an `{x, y, z, w}` object does NOT — its components read as `undefined`,
  *   the swept AABB comes out NaN, and every cast then misses silently
  * @param {PhysicsSurfacePoint} result  populated on hit; untouched on miss
  * @param {(entity:number, collider:Collider, body_id:number)=>boolean} [filter]
- *   mandatory in contract; defaults to {@link returnTrue}. Receives the
- *   candidate body's entity, primary collider, and packed body id (the id
- *   distinguishes bodies when colliders live on child entities)
+ *   mandatory in contract; defaults to {@link returnTrue}. Called once per
+ *   collider of each candidate body, with the body's entity, that collider,
+ *   and the packed body id (the id distinguishes bodies when colliders live on
+ *   child entities)
  * @param {boolean} [skip_initial_overlaps=false] how a candidate ALREADY
  *   overlapping the swept shape at `t = 0` is treated. `false` (kinematic
  *   "can I move?" semantics): targets are solid, so the cast is blocked where
- *   it stands — report a hit at `t = 0`. The one exception is a convex target
+ *   it stands — report a hit at `t = 0`. The one exception is a target
  *   the shape merely TOUCHES (no depth beyond {@link CONTACT_EPSILON}): a
  *   tangency blocks only a sweep driving into it, and otherwise steps aside so
  *   the scan can reach real blockers. `true` (CCD semantics): such a candidate
  *   is a resting / sliding contact the discrete solver already owns, NOT a
  *   tunnelling threat — skip it and keep scanning the remaining candidates for
  *   real blockers along the sweep. Either way, one contact at the start of the
- *   sweep must never blind the cast to every other obstacle.
+ *   sweep must never blind the cast to every other obstacle. For a concave
+ *   target all of this is decided per TRIANGLE: a shape touching or resting
+ *   in one triangle of a mesh is still stopped by another one ahead of it.
  * @returns {boolean}
  */
 export function shape_cast(system: PhysicsSystem, ray: Ray3 | {
@@ -81,4 +96,20 @@ export function shape_cast(system: PhysicsSystem, ray: Ray3 | {
     direction_z: number;
     tMax: number;
 }, shape: AbstractShape3D, rotation: ArrayLike<number>, result: PhysicsSurfacePoint, filter?: (entity: number, collider: Collider, body_id: number) => boolean, skip_initial_overlaps?: boolean): boolean;
+/**
+ * Support point, in world space, of what the last successful {@link shape_cast}
+ * struck — the convex collider, or for a concave collider the one triangle the
+ * hit was on — along the world direction in `direction[direction_offset .. +2]`, under
+ * {@link AbstractShape3D#support}'s contract.
+ *
+ * For a caller that needs the struck surface's own geometry at the contact
+ * (the CCD pass places its impulse where the two facing features overlap).
+ * Valid until the next cast; meaningless before any cast has hit.
+ *
+ * @param {Float64Array} out receives the point
+ * @param {number} out_offset
+ * @param {Float64Array|number[]} direction
+ * @param {number} direction_offset
+ */
+export function shape_cast_struck_support(out: Float64Array, out_offset: number, direction: Float64Array | number[], direction_offset: number): void;
 //# sourceMappingURL=shape_cast.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"shape_cast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/shape_cast.js"],"names":[],"mappings":"AAoPA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,uDA/BW,OAAK;IAAC,QAAQ,EAAC,MAAM,CAAC;IAAA,QAAQ,EAAC,MAAM,CAAC;IAAA,QAAQ,EAAC,MAAM,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,IAAI,EAAC,MAAM,CAAA;CAAC,oCAK3H,UAAU,MAAM,CAAC,wCASjB,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,EAAE,OAAO,EAAC,MAAM,KAAG,OAAO,0BAI3D,OAAO,GAWL,OAAO,CAyUnB"}
+{"version":3,"file":"shape_cast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/shape_cast.js"],"names":[],"mappings":"AA03DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,uDAnCW,OAAK;IAAC,QAAQ,EAAC,MAAM,CAAC;IAAA,QAAQ,EAAC,MAAM,CAAC;IAAA,QAAQ,EAAC,MAAM,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,IAAI,EAAC,MAAM,CAAA;CAAC,oCAK3H,UAAU,MAAM,CAAC,wCAUjB,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,EAAE,OAAO,EAAC,MAAM,KAAG,OAAO,0BAK3D,OAAO,GAaL,OAAO,CAanB;AA8aD;;;;;;;;;;;;;;GAcG;AACH,+CALW,YAAY,cACZ,MAAM,aACN,YAAY,GAAC,MAAM,EAAE,oBACrB,MAAM,QAIhB"}