@woosh/meep-engine 3.37.0 → 3.39.0

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

@@ -20,33 +20,37 @@
  * is `TypedArray.prototype.set`, which silently writes nothing.
  *
  * Field layout chosen to match what gameplay code typically needs:
- *   - `position` — world-space point on the surface
- *   - `normal` — surface normal at that point (broadphase queries return
- *     the AABB face normal as an approximation; narrowphase-refined queries
- *     would return the true shape normal at the same call site)
- *   - `t` — distance along the input ray, sphere-cast, etc. Useful when the
- *     caller wants to interpolate or step along the query primitive
- *     (`origin + t·direction` reconstructs the hit point exactly without
- *     reading `position`, which the deferred-execution physics events bus
- *     would otherwise need to copy).
+ *   - `position` — `origin + t·direction`: for a raycast the world point on
+ *     the surface it struck; for a shape cast the swept shape's own centre (its
+ *     origin) at first contact, NOT a point on the surface
+ *   - `normal` — the struck surface's outward normal there
+ *   - `t` — distance along the input ray or sweep. Useful when the caller
+ *     wants to interpolate or step along the query primitive
+ *     (`origin + t·direction` reconstructs `position` exactly without
+ *     reading it, which the deferred-execution physics events bus would
+ *     otherwise need to copy).
  *   - `entity` — entity id that owns the hit body
  *   - `body_id` — packed body id (index << 8 | generation); stale after the
  *     body is unlinked, so prefer `entity` for any cross-frame retention.
+ *   - `collider_entity` — entity that owns the struck collider: the body's
+ *     own for a single-collider body, the child's for a compound body's child
+ *   - `triangle` — for a concave collider (mesh, heightmap), the triangle
+ *     struck; `-1` for any other
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export class PhysicsSurfacePoint {
     /**
-     * World-space point on the hit surface.
+     * `origin + t·direction` of the query: for a raycast, the world point on
+     * the struck surface; for a shape cast, the swept shape's centre (its
+     * origin) at first contact, which is not on the surface.
      * @readonly
      * @type {Float64Array}
      */
     readonly position: Float64Array;
     /**
-     * Surface normal at {@link position}, unit length. For broadphase-only
-     * queries this is the AABB face normal (axis-aligned), which is exact
-     * for AABB-shaped colliders and a stable approximation otherwise.
+     * Outward normal of the struck surface at the contact, unit length.
      * @readonly
      * @type {Float64Array}
      */
@@ -70,6 +74,21 @@ export class PhysicsSurfacePoint {
      * @type {number}
      */
     body_id: number;
+    /**
+     * Entity that owns the struck collider — the one {@link entity}'s body
+     * attached it under: the body's own entity for a collider on it, the child
+     * entity for a compound body's collider on a child. `-1` if none.
+     * @type {number}
+     */
+    collider_entity: number;
+    /**
+     * For a concave collider (a mesh or a heightmap), the index of the struck
+     * triangle in its shape's triangulation — for a `MeshShape3D`, triangle
+     * `triangle` of its `indices`, `indices[3·triangle .. 3·triangle + 2]`;
+     * `-1` for any other collider.
+     * @type {number}
+     */
+    triangle: number;
     /**
      * Reset to a "no hit" state. Optional — the query convention is that the
      * fields are only meaningful when the call returns `true`, so callers

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

@@ -1 +1 @@
-{"version":3,"file":"PhysicsSurfacePoint.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/PhysicsSurfacePoint.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;IAEI;;;;OAIG;IACH,mBAFU,YAAY,CAES;IAE/B;;;;;;OAMG;IACH,iBAFU,YAAY,CAEO;IAE7B;;;;;OAKG;IACH,GAFU,MAAM,CAEV;IAEN;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,SAFU,MAAM,CAEH;IAEb;;;;;;OAMG;IACH,cAQC;IAGL;;;;OAIG;IACH,gCAFU,OAAO,CAEkC;CAPlD"}
+{"version":3,"file":"PhysicsSurfacePoint.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/PhysicsSurfacePoint.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IAEI;;;;;;OAMG;IACH,mBAFU,YAAY,CAES;IAE/B;;;;OAIG;IACH,iBAFU,YAAY,CAEO;IAE7B;;;;;OAKG;IACH,GAFU,MAAM,CAEV;IAEN;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,SAFU,MAAM,CAEH;IAEb;;;;;OAKG;IACH,iBAFU,MAAM,CAEK;IAErB;;;;;;OAMG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;;OAMG;IACH,cAUC;IAGL;;;;OAIG;IACH,gCAFU,OAAO,CAEkC;CAPlD"}

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

@@ -20,18 +20,22 @@
  * is `TypedArray.prototype.set`, which silently writes nothing.
  *
  * Field layout chosen to match what gameplay code typically needs:
- *   - `position` — world-space point on the surface
- *   - `normal` — surface normal at that point (broadphase queries return
- *     the AABB face normal as an approximation; narrowphase-refined queries
- *     would return the true shape normal at the same call site)
- *   - `t` — distance along the input ray, sphere-cast, etc. Useful when the
- *     caller wants to interpolate or step along the query primitive
- *     (`origin + t·direction` reconstructs the hit point exactly without
- *     reading `position`, which the deferred-execution physics events bus
- *     would otherwise need to copy).
+ *   - `position` — `origin + t·direction`: for a raycast the world point on
+ *     the surface it struck; for a shape cast the swept shape's own centre (its
+ *     origin) at first contact, NOT a point on the surface
+ *   - `normal` — the struck surface's outward normal there
+ *   - `t` — distance along the input ray or sweep. Useful when the caller
+ *     wants to interpolate or step along the query primitive
+ *     (`origin + t·direction` reconstructs `position` exactly without
+ *     reading it, which the deferred-execution physics events bus would
+ *     otherwise need to copy).
  *   - `entity` — entity id that owns the hit body
  *   - `body_id` — packed body id (index << 8 | generation); stale after the
  *     body is unlinked, so prefer `entity` for any cross-frame retention.
+ *   - `collider_entity` — entity that owns the struck collider: the body's
+ *     own for a single-collider body, the child's for a compound body's child
+ *   - `triangle` — for a concave collider (mesh, heightmap), the triangle
+ *     struck; `-1` for any other
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -39,16 +43,16 @@
 export class PhysicsSurfacePoint {
 
     /**
-     * World-space point on the hit surface.
+     * `origin + t·direction` of the query: for a raycast, the world point on
+     * the struck surface; for a shape cast, the swept shape's centre (its
+     * origin) at first contact, which is not on the surface.
      * @readonly
      * @type {Float64Array}
      */
     position = new Float64Array(3);
 
     /**
-     * Surface normal at {@link position}, unit length. For broadphase-only
-     * queries this is the AABB face normal (axis-aligned), which is exact
-     * for AABB-shaped colliders and a stable approximation otherwise.
+     * Outward normal of the struck surface at the contact, unit length.
      * @readonly
      * @type {Float64Array}
      */
@@ -76,6 +80,23 @@ export class PhysicsSurfacePoint {
      */
     body_id = -1;
 
+    /**
+     * Entity that owns the struck collider — the one {@link entity}'s body
+     * attached it under: the body's own entity for a collider on it, the child
+     * entity for a compound body's collider on a child. `-1` if none.
+     * @type {number}
+     */
+    collider_entity = -1;
+
+    /**
+     * For a concave collider (a mesh or a heightmap), the index of the struck
+     * triangle in its shape's triangulation — for a `MeshShape3D`, triangle
+     * `triangle` of its `indices`, `indices[3·triangle .. 3·triangle + 2]`;
+     * `-1` for any other collider.
+     * @type {number}
+     */
+    triangle = -1;
+
     /**
      * Reset to a "no hit" state. Optional — the query convention is that the
      * fields are only meaningful when the call returns `true`, so callers
@@ -91,6 +112,8 @@ export class PhysicsSurfacePoint {
         this.t = 0;
         this.entity = -1;
         this.body_id = -1;
+        this.collider_entity = -1;
+        this.triangle = -1;
     }
 }
 

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

@@ -0,0 +1,27 @@
+/**
+ * Whether a convex shape at a world pose overlaps another shape at its world pose: one GJK test
+ * when the other is convex, one per triangle near the convex when it is concave (a heightmap or a
+ * mesh), the first overlapping triangle deciding. {@link overlap_shape} makes this test against
+ * each collider of a candidate body, so a caller holding a body the query reported can ask which of
+ * the body's colliders it was and get the query's own answer.
+ *
+ * A concave shape is a surface here — a convex wholly behind one of its triangles, touching none,
+ * does not overlap it — as it is in the overlap query. One wrapped in a rigid TransformedShape3D is
+ * that surface at the composed pose.
+ *
+ * The poses are read by index. A Transform64's `translation` and `rotation` getters build a new
+ * view on every read, so a caller testing many colliders copies their scalars into arrays of its
+ * own rather than passing those.
+ *
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} convex_shape
+ *   in its local frame; must be convex
+ * @param {ArrayLike<number>} convex_position world position, as [x, y, z]
+ * @param {ArrayLike<number>} convex_rotation world rotation, a unit quaternion as [x, y, z, w]
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} other_shape
+ *   in its local frame; convex or concave
+ * @param {ArrayLike<number>} other_position world position, as [x, y, z]
+ * @param {ArrayLike<number>} other_rotation world rotation, a unit quaternion as [x, y, z, w]
+ * @returns {boolean}
+ */
+export function convex_overlaps_shape(convex_shape: import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D, convex_position: ArrayLike<number>, convex_rotation: ArrayLike<number>, other_shape: import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D, other_position: ArrayLike<number>, other_rotation: ArrayLike<number>): boolean;
+//# sourceMappingURL=convex_overlaps_shape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"convex_overlaps_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/convex_overlaps_shape.js"],"names":[],"mappings":"AAmDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,oDAVW,OAAO,gDAAgD,EAAE,eAAe,mBAExE,UAAU,MAAM,CAAC,mBACjB,UAAU,MAAM,CAAC,eACjB,OAAO,gDAAgD,EAAE,eAAe,kBAExE,UAAU,MAAM,CAAC,kBACjB,UAAU,MAAM,CAAC,GACf,OAAO,CA8FnB"}

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

@@ -0,0 +1,169 @@
+import { assert } from "../../../core/assert.js";
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { aabb3_transform_oriented_inverse } from "../../../core/geom/3d/aabb/aabb3_transform_oriented_inverse.js";
+import { gjk } from "../../../core/geom/3d/gjk/gjk.js";
+import { PosedShape3D } from "../../../core/geom/3d/shape/PosedShape3D.js";
+import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
+import { decompose_to_triangles } from "../narrowphase/decomposition/decompose_to_triangles.js";
+import { TRIANGLE_FLOAT_STRIDE } from "../narrowphase/decomposition/triangle_buffer_layout.js";
+import { rigid_subject_pose } from "../narrowphase/rigid_subject_pose.js";
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+
+/**
+ * Module scratch: one query at a time, on the main thread, like the other physics queries.
+ */
+const local_aabb = new Float64Array(6);
+const world_aabb = new Float64Array(6);
+const other_local_aabb = new Float64Array(6);
+const simplex = new Float64Array(12);
+
+const convex_posed = new PosedShape3D();
+const other_posed = new PosedShape3D();
+const triangle = new Triangle3D();
+
+/** The world pose of the mesh or heightmap a rigid TransformedShape3D wraps ({@link rigid_subject_pose}). */
+const subject_pose = new Transform64();
+
+/**
+ * Most triangles of a concave shape one test enumerates, the bound on {@link triangle_buffer}: the
+ * same as the narrowphase's per-pair limit, for the same reason — the count is the convex's
+ * footprint over the surface's triangle density. Under the overlap query's old fixed 1,024 the drop
+ * was not "a far edge": enumeration runs in index (mesh) or row (heightmap) order, so a sphere
+ * pressed into a finely meshed floor was tested only against the rows before its contact patch and
+ * reported no overlap, on every query.
+ * @type {number}
+ */
+const MAX_TRIANGLES = 1 << 16;
+
+/**
+ * Concave triangle scratch. Grows by doubling (enumerating again once) up to
+ * {@link MAX_TRIANGLES}; the high-water mark is kept.
+ * @type {Float64Array}
+ */
+let triangle_buffer = new Float64Array(1024 * TRIANGLE_FLOAT_STRIDE);
+
+/**
+ * Whether a test against more than {@link MAX_TRIANGLES} triangles has been reported (once per
+ * process).
+ * @type {boolean}
+ */
+let triangle_overflow_reported = false;
+
+/**
+ * Whether a convex shape at a world pose overlaps another shape at its world pose: one GJK test
+ * when the other is convex, one per triangle near the convex when it is concave (a heightmap or a
+ * mesh), the first overlapping triangle deciding. {@link overlap_shape} makes this test against
+ * each collider of a candidate body, so a caller holding a body the query reported can ask which of
+ * the body's colliders it was and get the query's own answer.
+ *
+ * A concave shape is a surface here — a convex wholly behind one of its triangles, touching none,
+ * does not overlap it — as it is in the overlap query. One wrapped in a rigid TransformedShape3D is
+ * that surface at the composed pose.
+ *
+ * The poses are read by index. A Transform64's `translation` and `rotation` getters build a new
+ * view on every read, so a caller testing many colliders copies their scalars into arrays of its
+ * own rather than passing those.
+ *
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} convex_shape
+ *   in its local frame; must be convex
+ * @param {ArrayLike<number>} convex_position world position, as [x, y, z]
+ * @param {ArrayLike<number>} convex_rotation world rotation, a unit quaternion as [x, y, z, w]
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} other_shape
+ *   in its local frame; convex or concave
+ * @param {ArrayLike<number>} other_position world position, as [x, y, z]
+ * @param {ArrayLike<number>} other_rotation world rotation, a unit quaternion as [x, y, z, w]
+ * @returns {boolean}
+ */
+export function convex_overlaps_shape(
+    convex_shape, convex_position, convex_rotation,
+    other_shape, other_position, other_rotation
+) {
+    assert.notEqual(convex_shape.is_convex, false, 'convex_shape must be convex');
+
+    convex_posed.setup_components(
+        convex_shape,
+        convex_position[0], convex_position[1], convex_position[2],
+        convex_rotation[0], convex_rotation[1], convex_rotation[2], convex_rotation[3]
+    );
+
+    if (other_shape.is_convex !== false) {
+        other_posed.setup_components(
+            other_shape,
+            other_position[0], other_position[1], other_position[2],
+            other_rotation[0], other_rotation[1], other_rotation[2], other_rotation[3]
+        );
+        return gjk(simplex, convex_posed, other_posed);
+    }
+
+    // A mesh or heightmap a rigid TransformedShape3D wraps is that surface at the composed pose, as the
+    // narrowphase collides it. A wrapper that scales is not unwrapped, and has no enumerator, here as
+    // there.
+    let concave = other_shape;
+    let px = other_position[0], py = other_position[1], pz = other_position[2];
+    let qx = other_rotation[0], qy = other_rotation[1], qz = other_rotation[2], qw = other_rotation[3];
+    while (concave.isTransformedShape3D === true && rigid_subject_pose(subject_pose, concave, px, py, pz, qx, qy, qz, qw)) {
+        concave = concave.subject;
+        px = subject_pose.translation_x; py = subject_pose.translation_y; pz = subject_pose.translation_z;
+        qx = subject_pose.rotation_x; qy = subject_pose.rotation_y; qz = subject_pose.rotation_z; qw = subject_pose.rotation_w;
+    }
+
+    // Concave: the convex's world box, taken into the other shape's frame, picks the triangles.
+    convex_shape.compute_bounding_box(local_aabb);
+    aabb3_transform_oriented(
+        world_aabb, 0,
+        local_aabb[0], local_aabb[1], local_aabb[2],
+        local_aabb[3], local_aabb[4], local_aabb[5],
+        convex_position[0], convex_position[1], convex_position[2],
+        convex_rotation[0], convex_rotation[1], convex_rotation[2], convex_rotation[3]
+    );
+    aabb3_transform_oriented_inverse(
+        other_local_aabb, 0,
+        world_aabb,
+        px, py, pz,
+        qx, qy, qz, qw
+    );
+
+    // The enumerator returns the TRUE count and drops writes past the buffer: grow and enumerate
+    // again, deterministic so once suffices.
+    let count = decompose_to_triangles(
+        triangle_buffer, 0, concave,
+        other_local_aabb[0], other_local_aabb[1], other_local_aabb[2],
+        other_local_aabb[3], other_local_aabb[4], other_local_aabb[5]
+    );
+    let capacity = triangle_buffer.length / TRIANGLE_FLOAT_STRIDE;
+    if (count > capacity && capacity < MAX_TRIANGLES) {
+        capacity = Math.min(MAX_TRIANGLES, Math.max(count, capacity * 2));
+        triangle_buffer = new Float64Array(capacity * TRIANGLE_FLOAT_STRIDE);
+        count = decompose_to_triangles(
+            triangle_buffer, 0, concave,
+            other_local_aabb[0], other_local_aabb[1], other_local_aabb[2],
+            other_local_aabb[3], other_local_aabb[4], other_local_aabb[5]
+        );
+    }
+    if (count > capacity) {
+        if (!triangle_overflow_reported) {
+            triangle_overflow_reported = true;
+            console.warn(
+                `convex_overlaps_shape: the convex overlaps ${count} triangles of a`
+                + ` ${concave.constructor.name}; it is tested against ${capacity} and not the rest.`
+            );
+        }
+        count = capacity;
+    }
+
+    // One flyweight triangle, rebound per iteration, posed as the concave shape.
+    other_posed.setup_components(
+        triangle,
+        px, py, pz,
+        qx, qy, qz, qw
+    );
+
+    for (let t = 0; t < count; t++) {
+        triangle.bind(triangle_buffer, t * TRIANGLE_FLOAT_STRIDE);
+        if (gjk(simplex, convex_posed, other_posed)) {
+            return true;
+        }
+    }
+
+    return false;
+}

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

@@ -1 +1 @@
-{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,UAErB,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,WACN,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,KAAG,OAAO,GAEzC,MAAM,CA+IlB"}
+{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AAuDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW,MAAM,EAAE,GAAC,YAAY,YAErB,MAAM,EAAE,GAAC,YAAY,UAErB,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,WACN,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,KAAG,OAAO,GAEzC,MAAM,CAclB"}

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

@@ -1,13 +1,9 @@
+import { assert } from "../../../core/assert.js";
 import { bvh_query_user_data_intersects_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
 import { returnTrue } from "../../../core/function/returnTrue.js";
 import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
-import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
 import { body_id_index } from "../body/BodyStorage.js";
-import { gjk } from "../../../core/geom/3d/gjk/gjk.js";
-import { aabb3_transform_oriented_inverse } from "../../../core/geom/3d/aabb/aabb3_transform_oriented_inverse.js";
-import { decompose_to_triangles } from "../narrowphase/decomposition/decompose_to_triangles.js";
-import { TRIANGLE_FLOAT_STRIDE } from "../narrowphase/decomposition/triangle_buffer_layout.js";
-import { PosedShape3D } from "../../../core/geom/3d/shape/PosedShape3D.js";
+import { convex_overlaps_shape } from "./convex_overlaps_shape.js";
 
 /**
  * Scratch state — module-scoped to avoid per-query allocation. Safe
@@ -15,28 +11,10 @@ import { PosedShape3D } from "../../../core/geom/3d/shape/PosedShape3D.js";
  */
 const local_aabb = new Float64Array(6);
 const world_aabb = new Float64Array(6);
-const concave_query_aabb = new Float64Array(6);
-const simplex_buf = new Float64Array(12);
 
-const query_posed = new PosedShape3D();
-const candidate_posed = new PosedShape3D();
-const triangle_shape = new Triangle3D();
-
-/**
- * Maximum triangles a concave candidate can emit per overlap pair.
- * Same rationale as the narrowphase's `MAX_TRIANGLES_PER_PAIR`: the
- * broadphase has already bounded the query AABB to the query shape's
- * envelope, so a single candidate typically yields tens of triangles
- * (a heightmap's count scales O(N²) with its `tessellation`, still
- * inside the buffer for a bounded query at moderate tessellation).
- * Excess triangles are dropped by the enumerator's bounds check —
- * worst case is a missed overlap on a far edge of the candidate's
- * geometry, recovered next query.
- * @type {number}
- */
-const MAX_TRIANGLES_PER_PAIR = 1024;
-
-const triangle_buffer = new Float64Array(MAX_TRIANGLES_PER_PAIR * TRIANGLE_FLOAT_STRIDE);
+/** The pose of the candidate collider being tested, as [x, y, z] and [x, y, z, w]. */
+const candidate_position = new Float64Array(3);
+const candidate_rotation = new Float64Array(4);
 
 /**
  * Broadphase candidate buffer. Grows by doubling on overflow.
@@ -63,6 +41,18 @@ let scratch_seen = new Int32Array(64);
  */
 let seen_stamp = 0;
 
+/**
+ * Whether an {@link overlap_shape} is in progress. Its candidates and stamps
+ * are module state, so an overlap started from inside one — from its filter —
+ * would overwrite the outer's half-finished scan (it reported none of the
+ * bodies it overlapped).
+ * @type {boolean}
+ */
+let overlap_running = false;
+
+const NESTED_OVERLAP = 'overlap_shape: called from inside an overlap, from its filter. An overlap keeps its working'
+    + ' state in module scratch, so it cannot run inside another; a raycast or a shapeCast can.';
+
 /**
  * Test what bodies overlap a convex shape placed at a given pose. Each
  * overlapping body's `body_id` is written to `output` starting at
@@ -104,6 +94,31 @@ let seen_stamp = 0;
  * @throws {Error} if `shape.is_convex === false`
  */
 export function overlap_shape(system, shape, position, rotation, output, output_offset, filter = returnTrue) {
+    assert.ok(!overlap_running, NESTED_OVERLAP);
+
+    overlap_running = true;
+    try {
+        return overlap_shape_bodies(system, shape, position, rotation, output, output_offset, filter);
+    } finally {
+        // also on the way out of a throw — a filter's own error, or the assert
+        // above in an overlap the filter started — so the next one is not refused
+        overlap_running = false;
+    }
+}
+
+/**
+ * {@link overlap_shape}, unguarded.
+ *
+ * @param {PhysicsSystem} system
+ * @param {AbstractShape3D} shape
+ * @param {number[]|Float64Array} position
+ * @param {number[]|Float64Array} rotation
+ * @param {Uint32Array|number[]} output
+ * @param {number} output_offset
+ * @param {(entity:number, collider:Collider)=>boolean} filter
+ * @returns {number}
+ */
+function overlap_shape_bodies(system, shape, position, rotation, output, output_offset, filter) {
     if (shape.is_convex === false) {
         throw new Error(`overlap_shape: query shape must be convex; received \`${shape.constructor.name}\` (is_convex=false)`);
     }
@@ -134,14 +149,7 @@ export function overlap_shape(system, shape, position, rotation, output, output_
     }
     if (n_total === 0) return 0;
 
-    // ── 3. Set up query PosedShape3D (constant across candidates) ─────
-    query_posed.setup_components(
-        shape,
-        position[0], position[1], position[2],
-        rotation[0], rotation[1], rotation[2], rotation[3]
-    );
-
-    // ── 4. Per-candidate narrowphase ────────────────────────────────
+    // ── 3. Per-candidate narrowphase ────────────────────────────────
     const output_capacity = output.length - output_offset;
     let count = 0;
     let cursor = output_offset;
@@ -188,51 +196,21 @@ export function overlap_shape(system, shape, position, rotation, output, output_
             const collider = entry.collider;
             if (!filter(entity, collider)) continue;
 
+            // One GJK for a convex collider, one per nearby triangle for a concave one. The pose is
+            // copied out as scalars: a Transform64's translation / rotation getters make a new view
+            // on every read.
             const candidate_tr = entry.transform;
-
-            if (collider.shape.is_convex !== false) {
-                candidate_posed.setup_components(
-                    collider.shape,
-                    candidate_tr.translation_x, candidate_tr.translation_y, candidate_tr.translation_z,
-                    candidate_tr.rotation_x, candidate_tr.rotation_y, candidate_tr.rotation_z, candidate_tr.rotation_w
-                );
-                overlaps = gjk(simplex_buf, query_posed, candidate_posed);
-            } else {
-                // Concave candidate: project the query's world AABB into
-                // the candidate's body-local frame, decompose to triangles,
-                // run per-triangle GJK until one overlap is found.
-                aabb3_transform_oriented_inverse(
-                    concave_query_aabb, 0,
-                    world_aabb,
-                    candidate_tr.translation_x, candidate_tr.translation_y, candidate_tr.translation_z,
-                    candidate_tr.rotation_x, candidate_tr.rotation_y, candidate_tr.rotation_z, candidate_tr.rotation_w
-                );
-
-                let tri_count = decompose_to_triangles(
-                    triangle_buffer, 0, collider.shape,
-                    concave_query_aabb[0], concave_query_aabb[1], concave_query_aabb[2],
-                    concave_query_aabb[3], concave_query_aabb[4], concave_query_aabb[5]
-                );
-                // TRUE count may exceed the buffer (overflow writes dropped) —
-                // clamp so the per-triangle GJK never binds past the end.
-                if (tri_count > MAX_TRIANGLES_PER_PAIR) tri_count = MAX_TRIANGLES_PER_PAIR;
-
-                // Re-pose candidate as the concave body (the flyweight triangle is
-                // rebound per iteration below; setup only stores the shape reference).
-                candidate_posed.setup_components(
-                    triangle_shape,
-                    candidate_tr.translation_x, candidate_tr.translation_y, candidate_tr.translation_z,
-                    candidate_tr.rotation_x, candidate_tr.rotation_y, candidate_tr.rotation_z, candidate_tr.rotation_w
-                );
-
-                for (let t = 0; t < tri_count; t++) {
-                    triangle_shape.bind(triangle_buffer, t * TRIANGLE_FLOAT_STRIDE);
-                    if (gjk(simplex_buf, query_posed, candidate_posed)) {
-                        overlaps = true;
-                        break;
-                    }
-                }
-            }
+            candidate_position[0] = candidate_tr.translation_x;
+            candidate_position[1] = candidate_tr.translation_y;
+            candidate_position[2] = candidate_tr.translation_z;
+            candidate_rotation[0] = candidate_tr.rotation_x;
+            candidate_rotation[1] = candidate_tr.rotation_y;
+            candidate_rotation[2] = candidate_tr.rotation_z;
+            candidate_rotation[3] = candidate_tr.rotation_w;
+            overlaps = convex_overlaps_shape(
+                shape, position, rotation,
+                collider.shape, candidate_position, candidate_rotation
+            );
         }
 
         if (overlaps) {

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

@@ -16,15 +16,21 @@
  * 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: 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":"AA8LA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,gGAJW,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,KAAG,OAAO,GAEzC,OAAO,CAwCnB"}
+{"version":3,"file":"raycast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/raycast.js"],"names":[],"mappings":"AA6QA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,gGALW,CAAC,MAAM,EAAC,MAAM,EAAE,QAAQ,UAAS,KAAG,OAAO,GAGzC,OAAO,CAgBnB"}