@woosh/meep-engine 2.145.0 → 2.147.0

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

@@ -133,6 +133,18 @@ const prev_claimed = new Uint8Array(MAX_CONTACTS_PER_MANIFOLD);
  */
 const cand_to_prev = new Int32Array(MAX_KEPT);
 
+/**
+ * Per-candidate "already claimed" flags for {@link redetect_pair_geometry}'s
+ * 1:1 existing-contact → fresh-candidate matching. Sized to the candidate
+ * buffer capacity (64) so it covers any per-pair candidate count. Without it,
+ * several existing contacts that share one triangle's `feature_id` (the
+ * box/capsule-triangle paths emit multiple contacts per triangle) would all
+ * match the same first candidate, collapsing the manifold to duplicate witness
+ * points.
+ * @type {Uint8Array}
+ */
+const redetect_claimed = new Uint8Array(64);
+
 /**
  * Per body-pair scratch buffer for candidate contacts produced by the
  * cross-product of A's colliders × B's colliders. Sized generously for
@@ -148,6 +160,13 @@ const candidates = new Float64Array(64 * CANDIDATE_STRIDE);
  * the convex-side body, so a single concave-vs-convex pair typically
  * yields tens of triangles, not thousands. 1024 is the safety cap.
  *
+ * For a heightmap the per-cell triangle count scales O(N²) with the
+ * shape's {@link HeightMapShape3D#tessellation} (a sub-cell quad is 2
+ * triangles, and there are N×N sub-cells per sampler cell). The bounded
+ * query AABB keeps the cell count small, so a typical pair stays well
+ * inside 1024 at moderate tessellation; the silent-drop backstop below
+ * covers any overflow at extreme values.
+ *
  * If an enumerator's output would exceed this, the extra triangles are
  * silently dropped by the enumerator's bounds-check on the output
  * array — the worst case is a missed contact on a far edge of the
@@ -1606,26 +1625,91 @@ export function redetect_pair_geometry(manifolds, slot, list_a, list_b) {
 
     const data = manifolds.data_buffer;
     const slot_off = manifolds.slot_data_offset(slot);
+
+    // Match each existing contact to a DISTINCT fresh candidate. feature_id
+    // identifies the TRIANGLE, not the contact point — the box/capsule-triangle
+    // paths emit several contacts for one triangle, all sharing that triangle's
+    // single fid (a flat box-on-heightmap cell yields fids like [6,6,6,7]). A
+    // plain first-match-by-fid therefore maps every same-fid existing contact
+    // onto the SAME candidate, collapsing the manifold to duplicate witness
+    // points → a degenerate support polygon the solver can't damp (the
+    // box-on-heightmap rattle). So: gate by fid, disambiguate same-fid
+    // candidates by NEAREST previous witness (world-A) position, and claim each
+    // candidate so no two existing contacts take the same one. For the common
+    // unique-fid case (sphere/mesh: one contact per triangle) this picks that
+    // single candidate exactly once — identical to the old behaviour.
+    for (let k = 0; k < cc; k++) redetect_claimed[k] = 0;
+
     for (let j = 0; j < count; j++) {
         const off = slot_off + j * CONTACT_STRIDE;
         const fid = data[off + 13];
         if (fid === 0) continue; // no feature info to match on
+
+        // Previous witness (world-A) of this existing contact — the anchor we
+        // disambiguate same-fid candidates against.
+        const pax = data[off];
+        const pay = data[off + 1];
+        const paz = data[off + 2];
+
+        let best_k = -1;
+        let best_d2 = Infinity;
         for (let k = 0; k < cc; k++) {
+            if (redetect_claimed[k] === 1) continue;
             const co = k * CANDIDATE_STRIDE;
-            if (candidates[co + 10] === fid) {
-                // Overwrite geometry only: witnesses, normal, depth.
-                data[off]     = candidates[co];
-                data[off + 1] = candidates[co + 1];
-                data[off + 2] = candidates[co + 2];
-                data[off + 3] = candidates[co + 3];
-                data[off + 4] = candidates[co + 4];
-                data[off + 5] = candidates[co + 5];
-                data[off + 6] = candidates[co + 6];
-                data[off + 7] = candidates[co + 7];
-                data[off + 8] = candidates[co + 8];
-                data[off + 9] = candidates[co + 9];
-                break;
+            if (candidates[co + 10] !== fid) continue;
+            const dx = candidates[co]     - pax;
+            const dy = candidates[co + 1] - pay;
+            const dz = candidates[co + 2] - paz;
+            const d2 = dx * dx + dy * dy + dz * dz;
+            if (d2 < best_d2) {
+                best_d2 = d2;
+                best_k = k;
             }
         }
+
+        // Position fallback (mirrors narrowphase_step's match-and-merge). A
+        // single triangle's clipped contact count is NOT stable across sub-mm
+        // pose changes — a box straddling a cell seam can have one triangle
+        // yield 4 points one substep and 3 the next — so an existing contact can
+        // outnumber this substep's same-fid candidates. Freezing its stale
+        // witness then duplicates a sibling contact's point, leaving a
+        // degenerate (sub-dimensional) manifold. Instead, claim the nearest
+        // unclaimed candidate of ANY fid: every contact keeps a DISTINCT live
+        // witness. The fid label is left intact and re-resolved by the next
+        // once-per-step narrowphase. (At a fixed pose the same-fid match always
+        // succeeds, so this never fires for the depth-equality guards or the
+        // one-contact-per-triangle sphere/mesh paths.)
+        if (best_k === -1) {
+            for (let k = 0; k < cc; k++) {
+                if (redetect_claimed[k] === 1) continue;
+                const co = k * CANDIDATE_STRIDE;
+                const dx = candidates[co]     - pax;
+                const dy = candidates[co + 1] - pay;
+                const dz = candidates[co + 2] - paz;
+                const d2 = dx * dx + dy * dy + dz * dz;
+                if (d2 < best_d2) {
+                    best_d2 = d2;
+                    best_k = k;
+                }
+            }
+        }
+
+        if (best_k === -1) continue; // no unclaimed candidate at all this substep — keep frozen geometry
+
+        redetect_claimed[best_k] = 1;
+        const co = best_k * CANDIDATE_STRIDE;
+        // Overwrite geometry only: witnesses, normal, depth. (Count, feature
+        // ids and accumulated impulses are intentionally left untouched — see
+        // the function contract.)
+        data[off]     = candidates[co];
+        data[off + 1] = candidates[co + 1];
+        data[off + 2] = candidates[co + 2];
+        data[off + 3] = candidates[co + 3];
+        data[off + 4] = candidates[co + 4];
+        data[off + 5] = candidates[co + 5];
+        data[off + 6] = candidates[co + 6];
+        data[off + 7] = candidates[co + 7];
+        data[off + 8] = candidates[co + 8];
+        data[off + 9] = candidates[co + 9];
     }
 }

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":"AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAqGlB"}
+{"version":3,"file":"overlap_shape.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/overlap_shape.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,uFAZW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAE5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,UAErC,WAAW,GAAC,MAAM,EAAE,iBAEpB,MAAM,oBACE,MAAM,yBAAsB,OAAO,GAEzC,MAAM,CAqGlB"}

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

@@ -1,183 +1,185 @@
-import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_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 "../gjk/gjk.js";
-import { aabb_world_to_local } from "../narrowphase/decomposition/aabb_world_to_local.js";
-import { decompose_to_triangles } from "../narrowphase/decomposition/decompose_to_triangles.js";
-import { TRIANGLE_FLOAT_STRIDE } from "../narrowphase/decomposition/triangle_buffer_layout.js";
-import { PosedShape } from "../narrowphase/PosedShape.js";
-
-/**
- * Scratch state — module-scoped to avoid per-query allocation. Safe
- * because PhysicsSystem queries run on the main thread, sequentially.
- */
-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 PosedShape();
-const candidate_posed = new PosedShape();
-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.
- * 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);
-
-/**
- * Broadphase candidate buffer. Grows by doubling on overflow.
- * @type {Uint32Array}
- */
-let scratch_candidates = new Uint32Array(64);
-
-/**
- * Test what bodies overlap a convex shape placed at a given pose. Each
- * overlapping body's `body_id` is written to `output` starting at
- * `output_offset`; the function returns the number of body ids written.
- *
- * Use case: speculative physics queries for kinematic / character
- * controllers. An external system can ask "would my body collide with
- * anything if I moved it here?" without committing a tick of
- * simulation. The output is a flat list of body ids so the caller can
- * decide what to do per hit (skip, push, slide, etc.).
- *
- * The pipeline mirrors the narrowphase pair test:
- *   1. Build the query shape's world AABB.
- *   2. Pull candidates from both broadphase trees that overlap that AABB.
- *   3. For each candidate, run GJK in world frame. Convex candidates
- *      go through one GJK call; concave candidates (heightmap / mesh)
- *      go through the per-triangle decomposition path.
- *   4. Apply the optional `filter` callback (same signature as in
- *      raycast / shapeCast) before the GJK test — early-out on bodies
- *      the caller already wants to skip (themselves, allies, etc.).
- *
- * The query shape must be convex (`is_convex === true`). Concave shapes
- * are typically static terrain and not used as kinematic query
- * probes; rejecting them avoids the M×N triangle-pair cost.
- *
- * @param {PhysicsSystem} system
- * @param {AbstractShape3D} shape  query shape, convex; expressed in
- *   its own local frame
- * @param {{x:number,y:number,z:number}} position world position of the
- *   query shape
- * @param {{x:number,y:number,z:number,w:number}} rotation world rotation
- *   of the query shape (unit quaternion)
- * @param {Uint32Array|number[]} output buffer to write body_ids into.
- *   Caller is responsible for sizing it; ids past its end are dropped.
- * @param {number} output_offset float-index in output to start writing at
- * @param {(entity:number, collider:Collider)=>boolean} [filter]
- *   defaults to {@link returnTrue} (accept every candidate)
- * @returns {number} number of overlapping bodies written
- * @throws {Error} if `shape.is_convex === false`
- */
-export function overlap_shape(system, shape, position, rotation, output, output_offset, filter = returnTrue) {
-    if (shape.is_convex === false) {
-        throw new Error(`overlap_shape: query shape must be convex; received \`${shape.constructor.name}\` (is_convex=false)`);
-    }
-
-    // ── 1. Query shape's world AABB ─────────────────────────────────
-    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],
-        position.x, position.y, position.z,
-        rotation.x, rotation.y, rotation.z, rotation.w
-    );
-
-    // ── 2. Gather broadphase candidates ─────────────────────────────
-    const n_static = bvh_query_user_data_overlaps_aabb(
-        scratch_candidates, 0, system.staticBvh, world_aabb
-    );
-    const n_dynamic = bvh_query_user_data_overlaps_aabb(
-        scratch_candidates, n_static, system.dynamicBvh, world_aabb
-    );
-    const n_total = n_static + n_dynamic;
-    if (n_total === 0) return 0;
-
-    // ── 3. Set up query PosedShape (constant across candidates) ─────
-    query_posed.setup(shape, position, rotation);
-
-    // ── 4. Per-candidate narrowphase ────────────────────────────────
-    const output_capacity = output.length - output_offset;
-    let count = 0;
-    let cursor = output_offset;
-
-    for (let i = 0; i < n_total; i++) {
-        if (count >= output_capacity) break;
-
-        const body_id = scratch_candidates[i];
-        const body_idx = body_id_index(body_id);
-
-        const entity = system.entityOf(body_id);
-        if (entity < 0) continue;
-
-        const collider = system.__primary_collider(body_idx);
-        if (collider === null) continue;
-        if (!filter(entity, collider)) continue;
-
-        const candidate_tr = system.__transforms[body_idx];
-
-        let overlaps = false;
-
-        if (collider.shape.is_convex !== false) {
-            candidate_posed.setup(collider.shape, candidate_tr.position, candidate_tr.rotation);
-            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.
-            aabb_world_to_local(
-                concave_query_aabb, 0,
-                world_aabb,
-                candidate_tr.position.x, candidate_tr.position.y, candidate_tr.position.z,
-                candidate_tr.rotation.x, candidate_tr.rotation.y, candidate_tr.rotation.z, candidate_tr.rotation.w
-            );
-
-            const 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]
-            );
-
-            // Re-pose candidate as the concave body, rebinding the
-            // flyweight triangle per iteration.
-            candidate_posed.shape = triangle_shape;
-            candidate_posed.px = candidate_tr.position.x;
-            candidate_posed.py = candidate_tr.position.y;
-            candidate_posed.pz = candidate_tr.position.z;
-            candidate_posed.qx = candidate_tr.rotation.x;
-            candidate_posed.qy = candidate_tr.rotation.y;
-            candidate_posed.qz = candidate_tr.rotation.z;
-            candidate_posed.qw = 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;
-                }
-            }
-        }
-
-        if (overlaps) {
-            output[cursor] = body_id;
-            cursor++;
-            count++;
-        }
-    }
-
-    return count;
-}
+import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_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 "../gjk/gjk.js";
+import { aabb_world_to_local } from "../narrowphase/decomposition/aabb_world_to_local.js";
+import { decompose_to_triangles } from "../narrowphase/decomposition/decompose_to_triangles.js";
+import { TRIANGLE_FLOAT_STRIDE } from "../narrowphase/decomposition/triangle_buffer_layout.js";
+import { PosedShape } from "../narrowphase/PosedShape.js";
+
+/**
+ * Scratch state — module-scoped to avoid per-query allocation. Safe
+ * because PhysicsSystem queries run on the main thread, sequentially.
+ */
+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 PosedShape();
+const candidate_posed = new PosedShape();
+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);
+
+/**
+ * Broadphase candidate buffer. Grows by doubling on overflow.
+ * @type {Uint32Array}
+ */
+let scratch_candidates = new Uint32Array(64);
+
+/**
+ * Test what bodies overlap a convex shape placed at a given pose. Each
+ * overlapping body's `body_id` is written to `output` starting at
+ * `output_offset`; the function returns the number of body ids written.
+ *
+ * Use case: speculative physics queries for kinematic / character
+ * controllers. An external system can ask "would my body collide with
+ * anything if I moved it here?" without committing a tick of
+ * simulation. The output is a flat list of body ids so the caller can
+ * decide what to do per hit (skip, push, slide, etc.).
+ *
+ * The pipeline mirrors the narrowphase pair test:
+ *   1. Build the query shape's world AABB.
+ *   2. Pull candidates from both broadphase trees that overlap that AABB.
+ *   3. For each candidate, run GJK in world frame. Convex candidates
+ *      go through one GJK call; concave candidates (heightmap / mesh)
+ *      go through the per-triangle decomposition path.
+ *   4. Apply the optional `filter` callback (same signature as in
+ *      raycast / shapeCast) before the GJK test — early-out on bodies
+ *      the caller already wants to skip (themselves, allies, etc.).
+ *
+ * The query shape must be convex (`is_convex === true`). Concave shapes
+ * are typically static terrain and not used as kinematic query
+ * probes; rejecting them avoids the M×N triangle-pair cost.
+ *
+ * @param {PhysicsSystem} system
+ * @param {AbstractShape3D} shape  query shape, convex; expressed in
+ *   its own local frame
+ * @param {{x:number,y:number,z:number}} position world position of the
+ *   query shape
+ * @param {{x:number,y:number,z:number,w:number}} rotation world rotation
+ *   of the query shape (unit quaternion)
+ * @param {Uint32Array|number[]} output buffer to write body_ids into.
+ *   Caller is responsible for sizing it; ids past its end are dropped.
+ * @param {number} output_offset float-index in output to start writing at
+ * @param {(entity:number, collider:Collider)=>boolean} [filter]
+ *   defaults to {@link returnTrue} (accept every candidate)
+ * @returns {number} number of overlapping bodies written
+ * @throws {Error} if `shape.is_convex === false`
+ */
+export function overlap_shape(system, shape, position, rotation, output, output_offset, filter = returnTrue) {
+    if (shape.is_convex === false) {
+        throw new Error(`overlap_shape: query shape must be convex; received \`${shape.constructor.name}\` (is_convex=false)`);
+    }
+
+    // ── 1. Query shape's world AABB ─────────────────────────────────
+    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],
+        position.x, position.y, position.z,
+        rotation.x, rotation.y, rotation.z, rotation.w
+    );
+
+    // ── 2. Gather broadphase candidates ─────────────────────────────
+    const n_static = bvh_query_user_data_overlaps_aabb(
+        scratch_candidates, 0, system.staticBvh, world_aabb
+    );
+    const n_dynamic = bvh_query_user_data_overlaps_aabb(
+        scratch_candidates, n_static, system.dynamicBvh, world_aabb
+    );
+    const n_total = n_static + n_dynamic;
+    if (n_total === 0) return 0;
+
+    // ── 3. Set up query PosedShape (constant across candidates) ─────
+    query_posed.setup(shape, position, rotation);
+
+    // ── 4. Per-candidate narrowphase ────────────────────────────────
+    const output_capacity = output.length - output_offset;
+    let count = 0;
+    let cursor = output_offset;
+
+    for (let i = 0; i < n_total; i++) {
+        if (count >= output_capacity) break;
+
+        const body_id = scratch_candidates[i];
+        const body_idx = body_id_index(body_id);
+
+        const entity = system.entityOf(body_id);
+        if (entity < 0) continue;
+
+        const collider = system.__primary_collider(body_idx);
+        if (collider === null) continue;
+        if (!filter(entity, collider)) continue;
+
+        const candidate_tr = system.__transforms[body_idx];
+
+        let overlaps = false;
+
+        if (collider.shape.is_convex !== false) {
+            candidate_posed.setup(collider.shape, candidate_tr.position, candidate_tr.rotation);
+            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.
+            aabb_world_to_local(
+                concave_query_aabb, 0,
+                world_aabb,
+                candidate_tr.position.x, candidate_tr.position.y, candidate_tr.position.z,
+                candidate_tr.rotation.x, candidate_tr.rotation.y, candidate_tr.rotation.z, candidate_tr.rotation.w
+            );
+
+            const 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]
+            );
+
+            // Re-pose candidate as the concave body, rebinding the
+            // flyweight triangle per iteration.
+            candidate_posed.shape = triangle_shape;
+            candidate_posed.px = candidate_tr.position.x;
+            candidate_posed.py = candidate_tr.position.y;
+            candidate_posed.pz = candidate_tr.position.z;
+            candidate_posed.qx = candidate_tr.rotation.x;
+            candidate_posed.qy = candidate_tr.rotation.y;
+            candidate_posed.qz = candidate_tr.rotation.z;
+            candidate_posed.qw = 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;
+                }
+            }
+        }
+
+        if (overlaps) {
+            output[cursor] = body_id;
+            cursor++;
+            count++;
+        }
+    }
+
+    return count;
+}

package/src/engine/simulation/Ticker.d.ts

@@ -20,6 +20,20 @@ declare class Ticker {
      * @type {Clock}
      */
     readonly clock: Clock;
+    /**
+     * When `true`, ticking is suspended while the host document/tab is in the
+     * background (hidden, or stored in the back/forward cache) and resumes from
+     * the current moment once it returns to the foreground.
+     *
+     * This avoids dispatching a flood of catch-up ticks (or one huge delta) for
+     * the time spent suspended, which would otherwise destabilise the simulation.
+     *
+     * Has no effect in environments without document/visibility support (e.g.
+     * Node.js), where the relevant lifecycle events simply never fire.
+     *
+     * @type {boolean}
+     */
+    suspend_in_background: boolean;
     /**
      * Dispatches time delta in seconds since last tick
      * @readonly

package/src/engine/simulation/Ticker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ticker.d.ts","sourceRoot":"","sources":["../../../../src/engine/simulation/Ticker.js"],"names":[],"mappings":";AAIA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;OAGG;IACH,gBAFU,KAAK,CAEK;IAiBpB;;;;OAIG;IACH,iBAFU,OAAO,MAAM,CAAC,CAEF;IAUtB;;;OAGG;IACH,uBAFW,MAAM,QAgDhB;IAED,cAOC;IAED,eAQC;IAED,aAOC;;CACJ;kBArIiB,aAAa;mBADZ,oCAAoC"}
+{"version":3,"file":"Ticker.d.ts","sourceRoot":"","sources":["../../../../src/engine/simulation/Ticker.js"],"names":[],"mappings":";AAIA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;OAGG;IACH,gBAFU,KAAK,CAEK;IAEpB;;;;;;;;;;;;OAYG;IACH,uBAFU,OAAO,CAEY;IAwB7B;;;;OAIG;IACH,iBAFU,OAAO,MAAM,CAAC,CAEF;IA+GtB;;;OAGG;IACH,uBAFW,MAAM,QAyDhB;IAED,cAOC;IAED,eAQC;IAED,aAUC;;CACJ;kBA5QiB,aAAa;mBADZ,oCAAoC"}