@woosh/meep-engine 3.37.0 → 3.39.0

package/src/engine/physics/cloth/collider/ClothColliderIndex.d.ts

@@ -104,25 +104,16 @@ export class ClothColliderIndex {
     /**
      * The widest {@link CCR_INFLATION} any live record carries, metres.
      *
-     * A gather's margin has to cover what the narrowphase will ask for, and
-     * `cloth_contact_find` reaches `(radius + inflation) · (1 + margin)` from
-     * each particle. The gather cannot know which colliders it is about to find,
-     * so it takes the widest in the index — which is why this is here rather
-     * than derived per query.
-     *
-     * Exact after {@link advance}, and only ever raised between advances by
-     * {@link add} and {@link setSurface}. Stale-high is a wider margin; the
-     * other direction is a missed contact, so the maximum is never lowered
-     * inside a step.
+     * Diagnostic upper bound, exact after {@link advance} and only raised
+     * between advances. Contact queries use each collider's own reach instead.
      * @type {number}
      */
     max_inflation: number;
     /**
      * The furthest any live collider has moved since {@link advance}, metres.
      *
-     * The narrowphase adds each collider's own travel to its reach on top of
-     * testing the swept bounds, so the gather's margin has to carry it too or
-     * the set it hands over is smaller than the set the rows are drawn from.
+     * Diagnostic upper bound. Contact queries carry travel on each collider's
+     * leaf, so a remote outlier cannot widen every cloth's query.
      * @type {number}
      */
     max_collider_travel: number;
@@ -154,6 +145,11 @@ export class ClothColliderIndex {
      * @returns {boolean}
      */
     isLive(handle: number): boolean;
+    /**
+     * @param {number} handle
+     * @returns {number} revision of the live record
+     */
+    revisionOf(handle: number): number;
     /**
      * Roll every live record's current pose into its previous one. Called once
      * per fixed step, before any pose for this step is written.
@@ -235,9 +231,25 @@ export class ClothColliderIndex {
      * @param {number} max_z
      * @param {number} layer the querier's layer
      * @param {number} mask the querier's mask
+     * @param {boolean} [contact] include each collider's own travel and contact
+     *   inflation and conversion allowance; the caller supplies particle radius,
+     *   travel and its local-coordinate conversion allowance in the query box
+     * @returns {number} how many handles were written
+     */
+    query(out: number[], min_x: number, min_y: number, min_z: number, max_x: number, max_y: number, max_z: number, layer: number, mask: number, contact?: boolean): number;
+    /**
+     * {@link query} with the box read from an array. For a caller that queries every step: six
+     * numbers handed to a call are each boxed into a heap object wherever V8 does not inline it.
+     *
+     * @param {number[]} out grown as needed; only `[0, returned)` is valid
+     * @param {number[]|Float32Array|Float64Array} box `[min_x, min_y, min_z, max_x, max_y, max_z]`
+     * @param {number} box_offset
+     * @param {number} layer the querier's layer
+     * @param {number} mask the querier's mask
+     * @param {boolean} contact as {@link query}'s
      * @returns {number} how many handles were written
      */
-    query(out: number[], min_x: number, min_y: number, min_z: number, max_x: number, max_y: number, max_z: number, layer: number, mask: number): number;
+    queryArray(out: number[], box: number[] | Float32Array | Float64Array, box_offset: number, layer: number, mask: number, contact: boolean): number;
     #private;
 }
 //# sourceMappingURL=ClothColliderIndex.d.ts.map

package/src/engine/physics/cloth/collider/ClothColliderIndex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClothColliderIndex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderIndex.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH;IAEI;;;;;;OAMG;IACH,OAFU,YAAY,CAEM;IAE5B;;;;;OAKG;IACH,MAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;OAcG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;;OAOG;IACH,qBAFU,MAAM,CAEQ;IAmExB;;;;;;;;;;;OAWG;IACH,sCAPW,MAAM,aACN,MAAM,SACN,MAAM,QACN,MAAM,UACN,MAAM,GACJ,MAAM,CA6DlB;IAED;;;;;;;OAOG;IACH,eAHW,MAAM,GACJ,IAAI,CAoChB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,WAFa,IAAI,CA0ChB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAkFhB;IAyCD;;;;;;;;;;;;;;;OAeG;IACH,kBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAiBhB;IAED;;;;;;;;OAQG;IACH,mBALW,MAAM,YACN,MAAM,aACN,MAAM,GACJ,IAAI,CAchB;IAED;;;;;OAKG;IACH,kBALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,IAAI,CAOhB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAXW,MAAM,EAAE,SACR,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,QACN,MAAM,GACJ,MAAM,CA6DlB;;CA+FJ"}
+{"version":3,"file":"ClothColliderIndex.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/ClothColliderIndex.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH;IAEI;;;;;;OAMG;IACH,OAFU,YAAY,CAEM;IAE5B;;;;;OAKG;IACH,MAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;OAMG;IACH,qBAFU,MAAM,CAEQ;IAoFxB;;;;;;;;;;;OAWG;IACH,sCAPW,MAAM,aACN,MAAM,SACN,MAAM,QACN,MAAM,UACN,MAAM,GACJ,MAAM,CA8DlB;IAED;;;;;;;OAOG;IACH,eAHW,MAAM,GACJ,IAAI,CAoChB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAuDhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CA8BhB;IAwID;;;;;;;;;;;;;;;OAeG;IACH,kBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAmBhB;IAED;;;;;;;;OAQG;IACH,mBALW,MAAM,YACN,MAAM,aACN,MAAM,GACJ,IAAI,CAoBhB;IAED;;;;;OAKG;IACH,kBALW,MAAM,SACN,MAAM,QACN,MAAM,GACJ,IAAI,CAWhB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAdW,MAAM,EAAE,SACR,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,SACN,MAAM,QACN,MAAM,YACN,OAAO,GAGL,MAAM,CAWlB;IAED;;;;;;;;;;;OAWG;IACH,gBARW,MAAM,EAAE,OACR,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,SACN,MAAM,QACN,MAAM,WACN,OAAO,GACL,MAAM,CA6DlB;;CAyGJ"}

package/src/engine/physics/cloth/collider/ClothColliderIndex.js

@@ -17,6 +17,9 @@ import {
     CCR_META_MASK,
     CCR_META_STRIDE,
     CCR_KIND,
+    CCR_PARAM_0,
+    CCR_PARAM_1,
+    CCR_PARAM_2,
     CCR_PREV_QW,
     CCR_PREV_QX,
     CCR_PREV_QY,
@@ -33,9 +36,10 @@ import {
     CCR_TY,
     CCR_TZ
 } from "./ClothColliderRecord.js";
-import { cloth_collider_refit_bounds } from "./cloth_collider_bounds.js";
+import { cloth_collider_refit_bounds, cloth_contact_rounding } from "./cloth_collider_bounds.js";
 import { cloth_collider_pack } from "./cloth_collider_pack.js";
 import { ClothColliderKind } from "./ClothColliderKind.js";
+import { CLOTH_CONTACT_MARGIN } from "../solver/cloth_contact_find.js";
 
 /**
  * # The index of live cloth colliders
@@ -147,16 +151,8 @@ export class ClothColliderIndex {
     /**
      * The widest {@link CCR_INFLATION} any live record carries, metres.
      *
-     * A gather's margin has to cover what the narrowphase will ask for, and
-     * `cloth_contact_find` reaches `(radius + inflation) · (1 + margin)` from
-     * each particle. The gather cannot know which colliders it is about to find,
-     * so it takes the widest in the index — which is why this is here rather
-     * than derived per query.
-     *
-     * Exact after {@link advance}, and only ever raised between advances by
-     * {@link add} and {@link setSurface}. Stale-high is a wider margin; the
-     * other direction is a missed contact, so the maximum is never lowered
-     * inside a step.
+     * Diagnostic upper bound, exact after {@link advance} and only raised
+     * between advances. Contact queries use each collider's own reach instead.
      * @type {number}
      */
     max_inflation = 0;
@@ -164,9 +160,8 @@ export class ClothColliderIndex {
     /**
      * The furthest any live collider has moved since {@link advance}, metres.
      *
-     * The narrowphase adds each collider's own travel to its reach on top of
-     * testing the swept bounds, so the gather's margin has to carry it too or
-     * the set it hands over is smaller than the set the rows are drawn from.
+     * Diagnostic upper bound. Contact queries carry travel on each collider's
+     * leaf, so a remote outlier cannot widen every cloth's query.
      * @type {number}
      */
     max_collider_travel = 0;
@@ -214,6 +209,23 @@ export class ClothColliderIndex {
      */
     #node = new Uint32Array(0);
 
+    /**
+     * Each collider's speculative contact reach: its own translation travel
+     * plus inflation. Stored on the leaf instead of widening every cloth's
+     * query by the largest motion anywhere in the world.
+     * @type {Float64Array}
+     * @private
+     */
+    #reach = new Float64Array(0);
+
+    /**
+     * Changes to a handle's identity, pose, surface or filter. A placement has
+     * equal previous/current poses but must still wake cloth resting against it.
+     * @type {Uint32Array}
+     * @private
+     */
+    #revision = new Uint32Array(0);
+
     /**
      * Handles of live half-spaces, which cannot go in the tree. Empty in every
      * scene this engine has; see the class docblock.
@@ -277,6 +289,7 @@ export class ClothColliderIndex {
         this.meta[m + CCR_META_ENTITY] = entity;
 
         this.#live[handle] = 1;
+        this.#revision[handle]++;
 
         // No pose yet, and a record with an uninitialised rotation is a
         // quaternion of all zeros — which normalises to nothing and poses
@@ -362,6 +375,14 @@ export class ClothColliderIndex {
         return handle >= 0 && handle < this.count && this.#live[handle] === 1;
     }
 
+    /**
+     * @param {number} handle
+     * @returns {number} revision of the live record
+     */
+    revisionOf(handle) {
+        return this.#revision[handle];
+    }
+
     /**
      * Roll every live record's current pose into its previous one. Called once
      * per fixed step, before any pose for this step is written.
@@ -398,6 +419,14 @@ export class ClothColliderIndex {
                 this.max_inflation = table[r + CCR_INFLATION];
             }
 
+            const moved = table[r + CCR_PREV_TX] !== table[r + CCR_TX]
+                || table[r + CCR_PREV_TY] !== table[r + CCR_TY]
+                || table[r + CCR_PREV_TZ] !== table[r + CCR_TZ]
+                || table[r + CCR_PREV_QX] !== table[r + CCR_QX]
+                || table[r + CCR_PREV_QY] !== table[r + CCR_QY]
+                || table[r + CCR_PREV_QZ] !== table[r + CCR_QZ]
+                || table[r + CCR_PREV_QW] !== table[r + CCR_QW];
+
             table[r + CCR_PREV_TX] = table[r + CCR_TX];
             table[r + CCR_PREV_TY] = table[r + CCR_TY];
             table[r + CCR_PREV_TZ] = table[r + CCR_TZ];
@@ -406,6 +435,11 @@ export class ClothColliderIndex {
             table[r + CCR_PREV_QY] = table[r + CCR_QY];
             table[r + CCR_PREV_QZ] = table[r + CCR_QZ];
             table[r + CCR_PREV_QW] = table[r + CCR_QW];
+
+            if (moved) {
+                cloth_collider_refit_bounds(table, handle, CCR_STRIDE);
+                this.#refit(handle);
+            }
         }
     }
 
@@ -428,12 +462,21 @@ export class ClothColliderIndex {
      * @returns {void}
      */
     setPose(handle, tx, ty, tz, qx, qy, qz, qw) {
-        assert.ok(this.isLive(handle), `cloth collider handle ${handle} is not live`);
+        // the message is built only when the check fails: as an argument it was a string per call
+        if (!this.isLive(handle)) {
+            assert.ok(false, `cloth collider handle ${handle} is not live`);
+        }
 
         const table = this.table;
 
         const r = handle * CCR_STRIDE;
 
+        if (table[r + CCR_TX] !== tx || table[r + CCR_TY] !== ty || table[r + CCR_TZ] !== tz
+            || table[r + CCR_QX] !== qx || table[r + CCR_QY] !== qy
+            || table[r + CCR_QZ] !== qz || table[r + CCR_QW] !== qw) {
+            this.#revision[handle]++;
+        }
+
         table[r + CCR_TX] = tx;
         table[r + CCR_TY] = ty;
         table[r + CCR_TZ] = tz;
@@ -445,12 +488,37 @@ export class ClothColliderIndex {
 
         cloth_collider_refit_bounds(this.table, handle, CCR_STRIDE);
 
+        this.#refit(handle);
+    }
+
+    /**
+     * @param {number} handle
+     * @private
+     */
+    #refit(handle) {
+        const table = this.table;
+        const r = handle * CCR_STRIDE;
+
         const travel = Math.hypot(
-            tx - table[r + CCR_PREV_TX],
-            ty - table[r + CCR_PREV_TY],
-            tz - table[r + CCR_PREV_TZ]
+            table[r + CCR_TX] - table[r + CCR_PREV_TX],
+            table[r + CCR_TY] - table[r + CCR_PREV_TY],
+            table[r + CCR_TZ] - table[r + CCR_PREV_TZ]
         );
 
+        const contact_reach = travel + Math.max(0, table[r + CCR_INFLATION]) * (1 + CLOTH_CONTACT_MARGIN);
+        // The sum of the bounded primitive's dimensions bounds its radius.
+        // Include conversion error in BOTH the tree leaf and the final test;
+        // the BVH's storage slack alone is discarded by the latter.
+        const geometry = table[r + CCR_KIND] === ClothColliderKind.Plane ? 0
+            : Math.abs(table[r + CCR_PARAM_0]) + Math.abs(table[r + CCR_PARAM_1])
+                + Math.abs(table[r + CCR_PARAM_2]);
+        const local_scale = geometry + contact_reach;
+        const world_scale = local_scale
+            + Math.abs(table[r + CCR_TX]) + Math.abs(table[r + CCR_TY]) + Math.abs(table[r + CCR_TZ])
+            + Math.abs(table[r + CCR_PREV_TX]) + Math.abs(table[r + CCR_PREV_TY]) + Math.abs(table[r + CCR_PREV_TZ]);
+        const reach = contact_reach + cloth_contact_rounding(local_scale, world_scale);
+        this.#reach[handle] = reach;
+
         if (travel > this.max_collider_travel) {
             this.max_collider_travel = travel;
         }
@@ -485,12 +553,20 @@ export class ClothColliderIndex {
         // tree.
         this.#bvh.node_get_aabb(node, STORED_AABB);
 
-        if (table[r + CCR_AABB_MIN_X] >= STORED_AABB[0]
-            && table[r + CCR_AABB_MIN_Y] >= STORED_AABB[1]
-            && table[r + CCR_AABB_MIN_Z] >= STORED_AABB[2]
-            && table[r + CCR_AABB_MAX_X] <= STORED_AABB[3]
-            && table[r + CCR_AABB_MAX_Y] <= STORED_AABB[4]
-            && table[r + CCR_AABB_MAX_Z] <= STORED_AABB[5]) {
+        let contained = true;
+        let oversized = false;
+        for (let axis = 0; axis < 3; axis++) {
+            const lower = table[r + CCR_AABB_MIN_X + axis] - reach;
+            const upper = table[r + CCR_AABB_MAX_X + axis] + reach;
+            if (lower < STORED_AABB[axis] || upper > STORED_AABB[axis + 3]) contained = false;
+            // A one-step outlier must not leave a scene-sized leaf behind once
+            // motion stops. Allow ordinary jitter to keep spending the slack.
+            if (STORED_AABB[axis + 3] - STORED_AABB[axis]
+                > 2 * (upper - lower + 2 * BVH_LEAF_SLACK
+                    + (Math.abs(lower) + Math.abs(upper)) * FLOAT32_ROUNDING)) oversized = true;
+        }
+
+        if (contained && !oversized) {
             return;
         }
 
@@ -510,8 +586,8 @@ export class ClothColliderIndex {
     }
 
     /**
-     * Write a record's swept bounds into {@link FAT_AABB} with the slack the
-     * refit skip spends, and store them on the leaf.
+     * Write a record's swept bounds plus its contact reach into {@link FAT_AABB}
+     * with the slack the refit skip spends, and store them on the leaf.
      *
      * The slack is also what makes the tree's `Float32` nodes safe to hold a
      * `Float64` world, and it has two terms because one is not enough. The
@@ -536,10 +612,11 @@ export class ClothColliderIndex {
      */
     #store_fat_aabb(node, r) {
         const table = this.table;
+        const reach = this.#reach[r / CCR_STRIDE];
 
         for (let axis = 0; axis < 3; axis++) {
-            const lower = table[r + CCR_AABB_MIN_X + axis];
-            const upper = table[r + CCR_AABB_MAX_X + axis];
+            const lower = table[r + CCR_AABB_MIN_X + axis] - reach;
+            const upper = table[r + CCR_AABB_MAX_X + axis] + reach;
 
             FAT_AABB[axis] = lower - BVH_LEAF_SLACK - Math.abs(lower) * FLOAT32_ROUNDING;
             FAT_AABB[axis + 3] = upper + BVH_LEAF_SLACK + Math.abs(upper) * FLOAT32_ROUNDING;
@@ -565,7 +642,9 @@ export class ClothColliderIndex {
      * @returns {void}
      */
     placePose(handle, tx, ty, tz, qx, qy, qz, qw) {
-        assert.ok(this.isLive(handle), `cloth collider handle ${handle} is not live`);
+        if (!this.isLive(handle)) {
+            assert.ok(false, `cloth collider handle ${handle} is not live`);
+        }
 
         const r = handle * CCR_STRIDE;
 
@@ -593,6 +672,10 @@ export class ClothColliderIndex {
     setSurface(handle, friction, inflation) {
         const r = handle * CCR_STRIDE;
 
+        if (this.table[r + CCR_FRICTION] !== friction || this.table[r + CCR_INFLATION] !== inflation) {
+            this.#revision[handle]++;
+        }
+
         this.table[r + CCR_FRICTION] = friction;
         this.table[r + CCR_INFLATION] = inflation;
 
@@ -602,6 +685,8 @@ export class ClothColliderIndex {
         if (inflation > this.max_inflation) {
             this.max_inflation = inflation;
         }
+
+        this.#refit(handle);
     }
 
     /**
@@ -613,6 +698,10 @@ export class ClothColliderIndex {
     setFilter(handle, layer, mask) {
         const m = handle * CCR_META_STRIDE;
 
+        if (this.meta[m + CCR_META_LAYER] !== (layer | 0) || this.meta[m + CCR_META_MASK] !== (mask | 0)) {
+            this.#revision[handle]++;
+        }
+
         this.meta[m + CCR_META_LAYER] = layer;
         this.meta[m + CCR_META_MASK] = mask;
     }
@@ -642,15 +731,41 @@ export class ClothColliderIndex {
      * @param {number} max_z
      * @param {number} layer the querier's layer
      * @param {number} mask the querier's mask
+     * @param {boolean} [contact] include each collider's own travel and contact
+     *   inflation and conversion allowance; the caller supplies particle radius,
+     *   travel and its local-coordinate conversion allowance in the query box
+     * @returns {number} how many handles were written
+     */
+    query(out, min_x, min_y, min_z, max_x, max_y, max_z, layer, mask, contact = false) {
+        SCALAR_BOX[0] = min_x;
+        SCALAR_BOX[1] = min_y;
+        SCALAR_BOX[2] = min_z;
+        SCALAR_BOX[3] = max_x;
+        SCALAR_BOX[4] = max_y;
+        SCALAR_BOX[5] = max_z;
+
+        return this.queryArray(out, SCALAR_BOX, 0, layer, mask, contact);
+    }
+
+    /**
+     * {@link query} with the box read from an array. For a caller that queries every step: six
+     * numbers handed to a call are each boxed into a heap object wherever V8 does not inline it.
+     *
+     * @param {number[]} out grown as needed; only `[0, returned)` is valid
+     * @param {number[]|Float32Array|Float64Array} box `[min_x, min_y, min_z, max_x, max_y, max_z]`
+     * @param {number} box_offset
+     * @param {number} layer the querier's layer
+     * @param {number} mask the querier's mask
+     * @param {boolean} contact as {@link query}'s
      * @returns {number} how many handles were written
      */
-    query(out, min_x, min_y, min_z, max_x, max_y, max_z, layer, mask) {
-        QUERY_AABB[0] = min_x;
-        QUERY_AABB[1] = min_y;
-        QUERY_AABB[2] = min_z;
-        QUERY_AABB[3] = max_x;
-        QUERY_AABB[4] = max_y;
-        QUERY_AABB[5] = max_z;
+    queryArray(out, box, box_offset, layer, mask, contact) {
+        QUERY_AABB[0] = box[box_offset];
+        QUERY_AABB[1] = box[box_offset + 1];
+        QUERY_AABB[2] = box[box_offset + 2];
+        QUERY_AABB[3] = box[box_offset + 3];
+        QUERY_AABB[4] = box[box_offset + 4];
+        QUERY_AABB[5] = box[box_offset + 5];
 
         // Grow and retry: the traversal returns the TRUE overlap count and
         // drops writes past the end, so a short buffer is a resize rather than
@@ -676,9 +791,9 @@ export class ClothColliderIndex {
         for (let i = 0; i < candidate_count; i++) {
             const handle = candidates[i];
 
-            // The leaf carries slack and `Float32` rounding; the record is the
-            // exact `Float64` answer, and it is what the narrowphase will read.
-            if (this.#overlaps(handle, min_x, min_y, min_z, max_x, max_y, max_z, layer, mask)) {
+            // Raw queries use the exact record. Contact queries retain the
+            // conversion allowance needed by the solver's Float32 table.
+            if (this.#overlaps(handle, layer, mask, contact)) {
                 answer.push(handle);
             }
         }
@@ -688,7 +803,7 @@ export class ClothColliderIndex {
         for (let i = 0; i < planes.length; i++) {
             const handle = planes[i];
 
-            if (this.#overlaps(handle, min_x, min_y, min_z, max_x, max_y, max_z, layer, mask)) {
+            if (this.#overlaps(handle, layer, mask, contact)) {
                 answer.push(handle);
             }
         }
@@ -696,7 +811,7 @@ export class ClothColliderIndex {
         // Ascending handle order — see the class docblock. The wake test
         // compares element by element and the gather's overflow keeps a prefix,
         // so both read this order as meaning.
-        answer.sort(ASCENDING);
+        sort_handles(answer);
 
         for (let i = 0; i < answer.length; i++) {
             out[i] = answer[i];
@@ -707,21 +822,16 @@ export class ClothColliderIndex {
 
     /**
      * Whether a live record passes the filter and its exact swept bounds meet
-     * the box.
+     * the box being queried, {@link QUERY_AABB}.
      *
      * @param {number} handle
-     * @param {number} min_x
-     * @param {number} min_y
-     * @param {number} min_z
-     * @param {number} max_x
-     * @param {number} max_y
-     * @param {number} max_z
      * @param {number} layer
      * @param {number} mask
+     * @param {boolean} contact
      * @returns {boolean}
      * @private
      */
-    #overlaps(handle, min_x, min_y, min_z, max_x, max_y, max_z, layer, mask) {
+    #overlaps(handle, layer, mask, contact) {
         if (this.#live[handle] === 0) {
             return false;
         }
@@ -742,15 +852,24 @@ export class ClothColliderIndex {
 
         const r = handle * CCR_STRIDE;
 
-        if (table[r + CCR_AABB_MIN_X] > max_x || table[r + CCR_AABB_MAX_X] < min_x) {
+        // A plane has no finite radius with which to bound a rounded normal's
+        // displacement. Keep every filtered half-space; the gather can reject
+        // it using the solver's actual local bounds before applying its cap.
+        if (contact && table[r + CCR_KIND] === ClothColliderKind.Plane) return true;
+
+        const reach = contact ? this.#reach[handle] : 0;
+
+        const box = QUERY_AABB;
+
+        if (table[r + CCR_AABB_MIN_X] - reach > box[3] || table[r + CCR_AABB_MAX_X] + reach < box[0]) {
             return false;
         }
 
-        if (table[r + CCR_AABB_MIN_Y] > max_y || table[r + CCR_AABB_MAX_Y] < min_y) {
+        if (table[r + CCR_AABB_MIN_Y] - reach > box[4] || table[r + CCR_AABB_MAX_Y] + reach < box[1]) {
             return false;
         }
 
-        if (table[r + CCR_AABB_MIN_Z] > max_z || table[r + CCR_AABB_MAX_Z] < min_z) {
+        if (table[r + CCR_AABB_MIN_Z] - reach > box[5] || table[r + CCR_AABB_MAX_Z] + reach < box[2]) {
             return false;
         }
 
@@ -784,11 +903,15 @@ export class ClothColliderIndex {
         const meta = new Int32Array(capacity * CCR_META_STRIDE);
         const live = new Uint8Array(capacity);
         const node = new Uint32Array(capacity);
+        const reach = new Float64Array(capacity);
+        const revision = new Uint32Array(capacity);
 
         table.set(this.table);
         meta.set(this.meta);
         live.set(this.#live);
         node.set(this.#node);
+        reach.set(this.#reach);
+        revision.set(this.#revision);
 
         node.fill(NULL_NODE, this.#node.length);
 
@@ -796,6 +919,8 @@ export class ClothColliderIndex {
         this.meta = meta;
         this.#live = live;
         this.#node = node;
+        this.#reach = reach;
+        this.#revision = revision;
     }
 
 }
@@ -818,10 +943,54 @@ const BVH_LEAF_SLACK = 0.05;
 const FLOAT32_ROUNDING = 2 ** -22;
 
 /**
+ * The box being queried, `[min_x, min_y, min_z, max_x, max_y, max_z]`: what the tree is walked with
+ * and what {@link ClothColliderIndex#overlaps} tests each candidate against.
  * @type {Float64Array}
  */
 const QUERY_AABB = new Float64Array(6);
 
+/**
+ * {@link ClothColliderIndex#query}'s box, packed for {@link ClothColliderIndex#queryArray}.
+ * @type {Float64Array}
+ */
+const SCALAR_BOX = new Float64Array(6);
+
+/**
+ * Above this many handles {@link sort_handles} hands the work to `Array.prototype.sort`.
+ * @type {number}
+ */
+const INSERTION_SORT_LIMIT = 32;
+
+/**
+ * Sort handles ascending, in place. A query finds a handful, and for those an insertion sort is as
+ * fast as `Array.prototype.sort` and allocates nothing, where the built-in copies the elements into
+ * a work array of its own on every call. Both are stable, and handles are integers, so the order is
+ * the same either way.
+ * @param {number[]} handles
+ */
+function sort_handles(handles) {
+    const n = handles.length;
+
+    if (n > INSERTION_SORT_LIMIT) {
+        handles.sort(ASCENDING);
+
+        return;
+    }
+
+    for (let i = 1; i < n; i++) {
+        const handle = handles[i];
+
+        let j = i - 1;
+
+        while (j >= 0 && handles[j] > handle) {
+            handles[j + 1] = handles[j];
+            j--;
+        }
+
+        handles[j + 1] = handle;
+    }
+}
+
 /**
  * The box on its way into a leaf.
  * @type {Float64Array}

package/src/engine/physics/cloth/collider/cloth_collider_bounds.d.ts

@@ -1,3 +1,33 @@
+/**
+ * Outward error allowance when a world-space query precedes the solver's
+ * Float32 conversion. Shared by the cloth query and the collider leaf: their
+ * allowances add, just as their speculative contact reaches do.
+ *
+ * Let u = 2^-24, P bound the particle's local distance from the anchor, G the
+ * shape radius, and L the sum of the contact and motion reaches. Rounding a
+ * localized translation contributes at most u times its length; rounding both
+ * swept translations adds at most u(2|t| + travel) to the measured travel.
+ * The relative quaternion is rounded, normalized and rounded again. Its
+ * error is less than 4u, so its inverse rotation/scale displaces a point by
+ * less than 9u times its radius. Shape parameters and inflation round once.
+ * Together these are bounded by 4u|t| + 16u(G + L). For an accepted contact,
+ * |t| <= P + G + L + error; substituting bounds that error by 32u(P + G + L).
+ * We spend 64u, including outward arithmetic rounding. P and the particle
+ * reach are paid by the query, G and collider reach by the index. No world
+ * coordinate is multiplied by a Float32 epsilon.
+ *
+ * World transforms/bounds use doubles: the separate world term covers their
+ * subtraction and rotation arithmetic, including cancellation far from the
+ * origin. The absolute term covers Float32 subnormals. Assumes finite solver
+ * values and rigid unit-quaternion input poses, as the collider API does.
+ * Unbounded planes cannot use a shape-radius bound and are always candidates
+ * for a contact query (their layer/mask still applies).
+ *
+ * @param {number} local_scale nonnegative local length bound
+ * @param {number} world_scale nonnegative world arithmetic magnitude bound
+ * @returns {number} metres of outward padding
+ */
+export function cloth_contact_rounding(local_scale: number, world_scale: number): number;
 /**
  * # The swept bounds of a packed collider
  *

package/src/engine/physics/cloth/collider/cloth_collider_bounds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_collider_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_bounds.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,mDALW,YAAY,GAAC,YAAY,UACzB,MAAM,UACN,MAAM,GACJ,IAAI,CAoBhB"}
+{"version":3,"file":"cloth_collider_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/collider/cloth_collider_bounds.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oDAJW,MAAM,eACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,mDALW,YAAY,GAAC,YAAY,UACzB,MAAM,UACN,MAAM,GACJ,IAAI,CAoBhB"}