@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -1,4 +1,8 @@
 import { assert } from "../../../../core/assert.js";
+import { BVH, NULL_NODE } from "../../../../core/bvh2/bvh3/BVH.js";
+import {
+    bvh_query_user_data_intersects_aabb
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
 import {
     CCR_AABB_MAX_X,
     CCR_AABB_MAX_Y,
@@ -12,6 +16,7 @@ import {
     CCR_META_LAYER,
     CCR_META_MASK,
     CCR_META_STRIDE,
+    CCR_KIND,
     CCR_PREV_QW,
     CCR_PREV_QX,
     CCR_PREV_QY,
@@ -30,6 +35,7 @@ import {
 } from "./ClothColliderRecord.js";
 import { cloth_collider_refit_bounds } from "./cloth_collider_bounds.js";
 import { cloth_collider_pack } from "./cloth_collider_pack.js";
+import { ClothColliderKind } from "./ClothColliderKind.js";
 
 /**
  * # The index of live cloth colliders
@@ -41,23 +47,47 @@ import { cloth_collider_pack } from "./cloth_collider_pack.js";
  * 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
+ *
+ * This was a linear scan, on two stated grounds that were both wrong.
+ *
+ * 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.
  *
- * `AcousticOccluderIndex` puts a BVH over its bodies and this does not, for two
- * reasons that are both about what the query is.
+ * 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 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 planes, which were the third ground and are not a structure
  *
- * 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.
+ * 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
  *
@@ -67,6 +97,24 @@ import { cloth_collider_pack } from "./cloth_collider_pack.js";
  * 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
  */
@@ -96,6 +144,33 @@ export class ClothColliderIndex {
      */
     count = 0;
 
+    /**
+     * 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 = 0;
+
+    /**
+     * 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 = 0;
+
     /**
      * Retired slots, reused before the table grows. A handle is a slot index,
      * so reuse is what keeps handles dense; it also means a handle can name a
@@ -107,6 +182,15 @@ export class ClothColliderIndex {
      */
     #free_slots = [];
 
+    /**
+     * Slots retired during this step. Drained into {@link #free_slots} by
+     * {@link advance}, so a handle is never reused within the step it was
+     * retired in — see the class docblock for what that buys.
+     * @type {number[]}
+     * @private
+     */
+    #retiring = [];
+
     /**
      * `true` for a live slot.
      * @type {Uint8Array}
@@ -114,6 +198,44 @@ export class ClothColliderIndex {
      */
     #live = new Uint8Array(0);
 
+    /**
+     * The tree over every live record with a bounded AABB. User data is the
+     * handle, so a query answers in the index's own names with no indirection.
+     * @type {BVH}
+     * @private
+     */
+    #bvh = new BVH();
+
+    /**
+     * Leaf node per handle, or {@link NULL_NODE} for a slot that is dead or
+     * holds a half-space.
+     * @type {Uint32Array}
+     * @private
+     */
+    #node = 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.
+     * @type {number[]}
+     * @private
+     */
+    #planes = [];
+
+    /**
+     * Handles the tree answered with, before filtering. Grown and reused.
+     * @type {Uint32Array}
+     * @private
+     */
+    #candidates = new Uint32Array(256);
+
+    /**
+     * The filtered answer, sorted before it is handed out.
+     * @type {number[]}
+     * @private
+     */
+    #answer = [];
+
     /**
      * Add a collider. The shape is packed once, here; the pose is written by
      * {@link setPose} and must be before the first query.
@@ -162,13 +284,35 @@ export class ClothColliderIndex {
         this.table[r + CCR_QW] = 1;
         this.table[r + CCR_PREV_QW] = 1;
 
+        if (inflation > this.max_inflation) {
+            this.max_inflation = inflation;
+        }
+
+        // Identity-posed bounds, so the record is never read as garbage left by
+        // the slot's last tenant.
+        cloth_collider_refit_bounds(this.table, handle, CCR_STRIDE);
+
+        this.#node[handle] = NULL_NODE;
+
+        if (this.table[r + CCR_KIND] === ClothColliderKind.Plane) {
+            this.#planes.push(handle);
+        }
+
+        // No leaf yet, on purpose. A record has no pose until {@link setPose},
+        // and a leaf inserted here would be homed at the origin: `insert_leaf`
+        // picks a sibling by where the box *is*, so a scene's worth of records
+        // added before they are placed builds its tree out of one coincident
+        // point and then never rebuilds it — {@link BVH#node_move_aabb} refits
+        // ancestors and leaves the topology alone. Measured, 16,384 colliders
+        // added-then-placed: a root 21 deep whose every branch overlapped every
+        // query, and 128 gathers costing 128 ms instead of 0.2.
         return handle;
     }
 
     /**
-     * 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}
@@ -179,7 +323,22 @@ export class ClothColliderIndex {
         }
 
         this.#live[handle] = 0;
-        this.#free_slots.push(handle);
+        this.#retiring.push(handle);
+
+        const node = this.#node[handle];
+
+        if (node === NULL_NODE) {
+            const at = this.#planes.indexOf(handle);
+
+            if (at >= 0) {
+                this.#planes.splice(at, 1);
+            }
+        } else {
+            this.#bvh.remove_leaf(node);
+            this.#bvh.release_node(node);
+
+            this.#node[handle] = NULL_NODE;
+        }
 
         // A retired record must not be found by a query. Its bounds are emptied
         // rather than its slot compacted, because compacting would move every
@@ -209,6 +368,23 @@ export class ClothColliderIndex {
      * @returns {void}
      */
     advance() {
+        const retiring = this.#retiring;
+
+        // Everything retired during the last step has now been absent from a
+        // whole step's worth of queries, so every cloth's slot for it has gone
+        // cold and the slot can be handed out again.
+        for (let i = 0; i < retiring.length; i++) {
+            this.#free_slots.push(retiring[i]);
+        }
+
+        retiring.length = 0;
+
+        // A new step, so nothing has moved in it yet, and the inflation
+        // maximum is re-derived from what is actually live — this is the one
+        // place it can come down again after a wide collider retires.
+        this.max_collider_travel = 0;
+        this.max_inflation = 0;
+
         const table = this.table;
 
         for (let handle = 0; handle < this.count; handle++) {
@@ -218,6 +394,10 @@ export class ClothColliderIndex {
 
             const r = handle * CCR_STRIDE;
 
+            if (table[r + CCR_INFLATION] > this.max_inflation) {
+                this.max_inflation = table[r + CCR_INFLATION];
+            }
+
             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];
@@ -264,6 +444,108 @@ export class ClothColliderIndex {
         table[r + CCR_QW] = qw;
 
         cloth_collider_refit_bounds(this.table, 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]
+        );
+
+        if (travel > this.max_collider_travel) {
+            this.max_collider_travel = travel;
+        }
+
+        const node = this.#node[handle];
+
+        if (node === NULL_NODE) {
+            if (table[r + CCR_KIND] === ClothColliderKind.Plane) {
+                // A half-space is not in the tree, and its bounds are already
+                // the answer to every query that can reach it.
+                return;
+            }
+
+            // First pose: this is where the leaf gets homed, and the pose is
+            // what `insert_leaf` needs to pick a sibling worth having.
+            const fresh = this.#bvh.allocate_node();
+
+            this.#bvh.node_set_user_data(fresh, handle);
+            this.#node[handle] = fresh;
+
+            this.#store_fat_aabb(fresh, r);
+
+            this.#bvh.insert_leaf(fresh);
+
+            return;
+        }
+
+        // The refit skip, and the reason a resting character costs nothing: the
+        // stored box is the swept box plus slack, so while the swept box is
+        // still inside it the leaf already covers everything this record can be
+        // found by. Only a collider that has left its own slack touches the
+        // 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]) {
+            return;
+        }
+
+        // Re-homed, not refit. {@link BVH#node_move_aabb} grows the ancestors
+        // to cover the leaf where it now is and never asks whether it still
+        // belongs under them, so a character crossing a level drags a box
+        // through branches it has nothing to do with and every query pays for
+        // the overlap. Pulling the leaf and letting `insert_leaf` choose again
+        // is what keeps the tree worth having, and the slack is what keeps it
+        // rare: a collider moving inside its own five centimetres never gets
+        // here at all.
+        this.#bvh.remove_leaf(node);
+
+        this.#store_fat_aabb(node, r);
+
+        this.#bvh.insert_leaf(node);
+    }
+
+    /**
+     * Write a record's swept bounds 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
+     * constant covers jitter. The relative term covers the rounding
+     * {@link BVH#node_set_aabb} does on the way in: a bound can move by an ulp,
+     * and `Float32`'s ulp is a *proportion* of the magnitude — a millimetre at
+     * ten kilometres out, but **a whole metre at ten thousand**, which is well
+     * past the constant: measured, a leaf there comes back 45 cm inside its own
+     * record. A bound that rounds inward past its slack is a leaf
+     * smaller than the record it stands for, and that is a collider the tree
+     * stops answering with — silently, and only far from the origin, which is
+     * the worst shape a bug can have. Two ulps of the magnitude puts it back
+     * outside at every scale the `Float64` table is kept for.
+     *
+     * The exact test in {@link query} reads the `Float64` record, so the tree
+     * only ever has to avoid a false **negative**; being generous here costs a
+     * candidate that is then rejected.
+     *
+     * @param {number} node
+     * @param {number} r the record's slot offset
+     * @private
+     */
+    #store_fat_aabb(node, r) {
+        const table = this.table;
+
+        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];
+
+            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;
+        }
+
+        this.#bvh.node_set_aabb(node, FAT_AABB);
     }
 
     /**
@@ -313,6 +595,13 @@ export class ClothColliderIndex {
 
         this.table[r + CCR_FRICTION] = friction;
         this.table[r + CCR_INFLATION] = inflation;
+
+        // Raised now rather than at the next `advance`, because a gather
+        // between the two would otherwise reach less far than the narrowphase
+        // it is feeding.
+        if (inflation > this.max_inflation) {
+            this.max_inflation = inflation;
+        }
     }
 
     /**
@@ -356,44 +645,116 @@ export class ClothColliderIndex {
      * @returns {number} how many handles were written
      */
     query(out, min_x, min_y, min_z, max_x, max_y, max_z, layer, mask) {
-        const table = this.table;
-        const meta = this.meta;
+        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;
 
-        let found = 0;
+        // 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
+        // a silently truncated answer. Capping instead would drop the same
+        // trailing leaves every step — a permanently invisible collider rather
+        // than a slow one.
+        let candidates = this.#candidates;
 
-        for (let handle = 0; handle < this.count; handle++) {
-            if (this.#live[handle] === 0) {
-                continue;
-            }
+        let candidate_count = bvh_query_user_data_intersects_aabb(candidates, 0, this.#bvh, QUERY_AABB);
 
-            const m = handle * CCR_META_STRIDE;
+        if (candidate_count > candidates.length) {
+            candidates = new Uint32Array(candidate_count * 2);
 
-            if ((mask & meta[m + CCR_META_LAYER]) === 0) {
-                continue;
-            }
+            this.#candidates = candidates;
 
-            if ((meta[m + CCR_META_MASK] & layer) === 0) {
-                continue;
-            }
+            candidate_count = bvh_query_user_data_intersects_aabb(candidates, 0, this.#bvh, QUERY_AABB);
+        }
 
-            const r = handle * CCR_STRIDE;
+        const answer = this.#answer;
 
-            if (table[r + CCR_AABB_MIN_X] > max_x || table[r + CCR_AABB_MAX_X] < min_x) {
-                continue;
-            }
+        answer.length = 0;
 
-            if (table[r + CCR_AABB_MIN_Y] > max_y || table[r + CCR_AABB_MAX_Y] < min_y) {
-                continue;
+        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)) {
+                answer.push(handle);
             }
+        }
 
-            if (table[r + CCR_AABB_MIN_Z] > max_z || table[r + CCR_AABB_MAX_Z] < min_z) {
-                continue;
+        const planes = this.#planes;
+
+        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)) {
+                answer.push(handle);
             }
+        }
 
-            out[found++] = handle;
+        // 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);
+
+        for (let i = 0; i < answer.length; i++) {
+            out[i] = answer[i];
         }
 
-        return found;
+        return answer.length;
+    }
+
+    /**
+     * Whether a live record passes the filter and its exact swept bounds meet
+     * the box.
+     *
+     * @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
+     * @returns {boolean}
+     * @private
+     */
+    #overlaps(handle, min_x, min_y, min_z, max_x, max_y, max_z, layer, mask) {
+        if (this.#live[handle] === 0) {
+            return false;
+        }
+
+        const meta = this.meta;
+
+        const m = handle * CCR_META_STRIDE;
+
+        if ((mask & meta[m + CCR_META_LAYER]) === 0) {
+            return false;
+        }
+
+        if ((meta[m + CCR_META_MASK] & layer) === 0) {
+            return false;
+        }
+
+        const table = this.table;
+
+        const r = handle * CCR_STRIDE;
+
+        if (table[r + CCR_AABB_MIN_X] > max_x || table[r + CCR_AABB_MAX_X] < min_x) {
+            return false;
+        }
+
+        if (table[r + CCR_AABB_MIN_Y] > max_y || table[r + CCR_AABB_MAX_Y] < min_y) {
+            return false;
+        }
+
+        if (table[r + CCR_AABB_MIN_Z] > max_z || table[r + CCR_AABB_MAX_Z] < min_z) {
+            return false;
+        }
+
+        return true;
     }
 
     /**
@@ -422,14 +783,62 @@ export class ClothColliderIndex {
         const table = new Float64Array(capacity * CCR_STRIDE);
         const meta = new Int32Array(capacity * CCR_META_STRIDE);
         const live = new Uint8Array(capacity);
+        const node = new Uint32Array(capacity);
 
         table.set(this.table);
         meta.set(this.meta);
         live.set(this.#live);
+        node.set(this.#node);
+
+        node.fill(NULL_NODE, this.#node.length);
 
         this.table = table;
         this.meta = meta;
         this.#live = live;
+        this.#node = node;
     }
 
 }
+
+/**
+ * How far past a record's swept bounds its leaf is stored, metres. The same
+ * constant `compute_fat_world_aabb` spends on a rigid body, and for the same
+ * reason: a collider jittering inside its own slack must not cost a refit.
+ * @type {number}
+ */
+const BVH_LEAF_SLACK = 0.05;
+
+/**
+ * Two `Float32` ulps as a proportion of a value's magnitude — what a bound has
+ * to be widened by to survive being stored in a `Float32` leaf whatever the
+ * rounding does. `Float32` carries 23 fraction bits, so one ulp is `2^-23` of
+ * the magnitude and two is the first multiple that is unconditionally outside.
+ * @type {number}
+ */
+const FLOAT32_ROUNDING = 2 ** -22;
+
+/**
+ * @type {Float64Array}
+ */
+const QUERY_AABB = new Float64Array(6);
+
+/**
+ * The box on its way into a leaf.
+ * @type {Float64Array}
+ */
+const FAT_AABB = new Float64Array(6);
+
+/**
+ * The tree stores `Float32` bounds, so this is what reads them back.
+ * @type {Float32Array}
+ */
+const STORED_AABB = new Float32Array(6);
+
+/**
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function ASCENDING(a, b) {
+    return a - b;
+}

package/src/engine/physics/cloth/ecs/ClothColliderSerializationAdapter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * # Binary serialization for {@link ClothCollider}
+ *
+ * Five scalars, all of them authored, all of them written. §3.5's component is
+ * a marker that opts an existing `(Collider, Transform64)` into the cloth
+ * simulation, so everything it does *not* carry — geometry and friction from
+ * `Collider`, pose from `Transform64` — is already the concern of those two
+ * components' own adapters. There is nothing shared, nothing runtime and
+ * nothing to exclude: the packed record, the swept bounds and the handle are
+ * `ClothColliderIndex`'s, keyed by entity and rebuilt when
+ * `ClothColliderSystem` links the entity, exactly as `_bodyId` is rebuilt on
+ * `PhysicsSystem#link`.
+ *
+ * ## `layer` and `mask` are read back unsigned
+ *
+ * The pair carries `RigidBody` semantics (§3.5) but not `RigidBody`'s
+ * signedness: the default `mask` here is the unsigned `0xFFFFFFFF` and
+ * `ClothCollider.from` asserts `isNonNegativeInteger` on it, so the `| 0` that
+ * `RigidBodySerializationAdapter` and `ColliderSerializationAdapter` both apply
+ * would hand back `-1` and break the component's own contract.
+ * {@link ClothSerializationAdapter} has the long form of this, and the two
+ * components have to agree about it — a mask filter is evaluated between them.
+ *
+ * ## Version 0, and no upgrader
+ *
+ * A first version has no predecessor stream to upgrade from;
+ * `RigidBodySerializationUpgrader_0_1` is what a later field addition looks
+ * like. The spec's exact-size assertion is what makes a field added without the
+ * bump fail rather than silently shift every following component in a stream.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothColliderSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof ClothCollider;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {ClothCollider} value
+     */
+    serialize(buffer: BinaryBuffer, value: ClothCollider): void;
+    /**
+     *
+     * @param {BinaryBuffer} buffer
+     * @param {ClothCollider} value
+     */
+    deserialize(buffer: BinaryBuffer, value: ClothCollider): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { ClothCollider } from "./ClothCollider.js";
+//# sourceMappingURL=ClothColliderSerializationAdapter.d.ts.map

package/src/engine/physics/cloth/ecs/ClothColliderSerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClothColliderSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothColliderSerializationAdapter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;;IAEI,4BAAsB;IAGtB;;;;OAIG;IACH,uCAFW,aAAa,QASvB;IAED;;;;OAIG;IACH,yCAFW,aAAa,QAUvB;CACJ;gDArE+C,gEAAgE;8BAClF,oBAAoB"}