@woosh/meep-engine 3.25.0 → 3.27.0

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

@@ -8,23 +8,47 @@
  * deliberately **not** the physics BVH, because `ColliderObserverSystem` skips
  * colliders with no owning body and a character's bone colliders have none.
  *
- * ## Why a linear scan and not a BVH
+ * ## A tree, and the argument that used to stand here
  *
- * `AcousticOccluderIndex` puts a BVH over its bodies and this does not, for two
- * reasons that are both about what the query is.
+ * This was a linear scan, on two stated grounds that were both wrong.
  *
- * The query here is one AABB overlap per cloth per step against a set that is a
- * character's bones — twenty or so, and never the whole world, because a
- * `ClothCollider` is an opt-in marker rather than every collider in the scene.
- * A tree over twenty leaves that all move every frame costs more to keep than
- * to skip.
+ * The first was that the set is "a character's bones — twenty or so, and never
+ * the whole world". That number came from `MEASUREMENTS.md` §41, which counted
+ * the colliders **overlapping one garment** in a six-character scene. That is a
+ * narrowphase input, and it was used to size a structure that holds every
+ * `ClothCollider` in the world. The index is queried once per cloth per step,
+ * so a scan is `clothes × colliders` per step in an engine that is built to
+ * carry far more of both.
  *
- * And a {@link PlaneShape3D} has an **unbounded** AABB, which a BVH cannot hold
- * — every refit would grow the root to infinity and every query would visit
- * everything. A linear scan holds an infinity without complaint, because
- * `min ≤ other_max` is still an answer when one side is `Infinity`. If a scene
- * ever wants thousands of cloth colliders, the shape of the fix is a BVH over
- * the bounded ones with the planes kept in a short list beside it.
+ * The second was that a tree over leaves that all move every frame costs more
+ * to keep than to skip. `PhysicsSystem` keeps two dynamic {@link BVH}s over
+ * bodies that all move every frame, and `compute_fat_world_aabb` is why it is
+ * cheap: a leaf stores a box fattened past the tight one, and is only refit
+ * when the tight box escapes it. {@link setPose} does the same, so a resting
+ * character pays a containment test per bone per step and no tree traffic at
+ * all.
+ *
+ * ## The planes, which were the third ground and are not a structure
+ *
+ * A {@link PlaneShape3D} has an unbounded AABB, and a leaf holding one would
+ * grow every ancestor to infinity and make the tree answer every query with
+ * everything. That much is true. What it is not is a reason for anything: a
+ * half-space is constructed in exactly one place in this engine — the JSON
+ * shape adapter — and no scene builds one. So planes are kept out of the tree
+ * in {@link #planes} and appended to every answer, which is the correct result
+ * for a volume that overlaps every box, and which costs a loop over an array
+ * that is empty in every scene anyone has run.
+ *
+ * ## The answer is sorted, and that is load-bearing
+ *
+ * A scan answers in ascending handle order for free. A tree answers in
+ * traversal order, which changes as the tree rebalances even when the set does
+ * not — and `cloth_colliders_moved` compares the gathered keys **element by
+ * element** against the last step's, so a reshuffle of an unchanged set would
+ * wake every sleeping cloth in the scene. {@link cloth_gather_colliders} also
+ * keeps the first `CLOTH_COLLIDER_SLOTS` of an overflow, so the order decides
+ * which colliders a crowded cloth loses. Sorting restores both properties
+ * exactly as the scan had them.
  *
  * ## The previous pose is the index's, not the caller's
  *
@@ -34,6 +58,24 @@
  * written. A collider that has just been added has both poses equal, so its
  * first step sweeps nothing — which is right: it did not move, it appeared.
  *
+ * ## A retired slot is cold before it is warm again
+ *
+ * A handle is a slot index, so it is reused — and a cloth's warm-started
+ * contacts are keyed on it, dropped when the handle stops being found. That
+ * contract only holds if the handle *is* absent for a step: retire a collider
+ * and add another in the same tick, and the slot is popped immediately, the new
+ * surface is indexable as the old one, and a particle settled on the old floor
+ * carries its multiplier and a friction anchor in a frame that no longer exists
+ * straight onto the new one. Measured: lambda 0.0981 and the old anchor,
+ * unchanged across the swap.
+ *
+ * So {@link remove} retires into a list that {@link advance} drains, one step
+ * later. Every cloth has by then stepped against an index the handle was not in
+ * — which is exactly what makes its slot cold — and the cost is one slot held
+ * back for one step. A generation word beside the handle would do the same job
+ * and would have to be threaded through the per-cloth table, the key array and
+ * the warm-start scan; this is the same guarantee for a `push` and a `for`.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -59,6 +101,31 @@ export class ClothColliderIndex {
      * @type {number}
      */
     count: number;
+    /**
+     * 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.
+     * @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.
+     * @type {number}
+     */
+    max_collider_travel: number;
     /**
      * Add a collider. The shape is packed once, here; the pose is written by
      * {@link setPose} and must be before the first query.
@@ -73,9 +140,9 @@ export class ClothColliderIndex {
      */
     add(shape: AbstractShape3D, friction: number, inflation: number, layer: number, mask: number, entity: number): number;
     /**
-     * Retire a handle. Its slot is reused by the next {@link add}, and any
-     * cloth holding warm-started contacts against it drops them on its next
-     * step because the handle it remembers no longer names the same collider.
+     * Retire a handle. Its slot is reused from the **next** {@link advance}
+     * onwards, and any cloth holding warm-started contacts against it drops
+     * them on its next step because the handle it remembers is no longer found.
      *
      * @param {number} handle
      * @returns {void}

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":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH;IAEI;;;;;;OAMG;IACH,OAFU,YAAY,CAEM;IAE5B;;;;;OAKG;IACH,MAFU,UAAU,CAEK;IAEzB;;;;OAIG;IACH,OAFU,MAAM,CAEN;IAoBV;;;;;;;;;;;OAWG;IACH,sCAPW,MAAM,aACN,MAAM,SACN,MAAM,QACN,MAAM,UACN,MAAM,GACJ,MAAM,CAuClB;IAED;;;;;;;OAOG;IACH,eAHW,MAAM,GACJ,IAAI,CAqBhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAqBhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAVW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAmBhB;IAED;;;;;;;;;;;;;;;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,CAOhB;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,CAyClB;;CAsCJ"}
+{"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"}