@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -23,37 +23,120 @@
  *
  * ## The query box
  *
- * The cloth's own particle bounds, fattened by how far a contact reaches, and
- * then by how far the solver will let a particle travel in one step. The second
- * term is what stops a fast cloth outrunning its own broadphase within the step
- * it was gathered for; it is the velocity clamp of §7 P1 read as a distance,
- * which is the quantity it was built out of.
+ * The cloth's own particle bounds, fattened by exactly what
+ * `cloth_contact_find` will reach for — no more, because a broadphase that is
+ * wider than its narrowphase is collecting colliders it will then throw away.
+ * {@link cloth_gather_reach} is that quantity and carries the derivation.
+ *
+ * It used to be the velocity clamp of §7 P1 read as a distance. That was wrong
+ * in both directions at once. The clamp is `4 · shortest_row · substeps ·
+ * iterations`, which for a rope of 10 cm links at 2 × 4 is **3.2 m** a step —
+ * so the box was fattened by metres to catch motion measured in centimetres,
+ * and a garment in a crowd collected every bone in the street and overflowed
+ * its table. `cloth_contact_find`'s own docblock had already worked out that
+ * this clamp is "about 154 m/s … three orders of magnitude" past real cloth
+ * speed and stopped using it (§54); the gather kept it. And being enormous, it
+ * hid the fact that it was also **missing** two terms the narrowphase does
+ * reach with — collider inflation and the collider's own travel — so a wide
+ * enough inflation was a row the gather never handed over.
+ *
+ * ## Where the table lives, and why it stopped growing
+ *
+ * In `ClothState`'s single buffer, {@link CLOTH_COLLIDER_SLOTS} records of it,
+ * which is §12's own layout. M2 grew a per-instance array instead, because the
+ * size is a property of the world rather than of the cloth — still true, and
+ * still not the deciding argument. M5's worker steps the cloth out of shared
+ * memory, and an array that can be replaced mid-run is memory the worker would
+ * have to be told about again before it could be named. A fixed region makes the
+ * two systems read the same bytes by construction.
+ *
+ * A cloth whose broadphase returns more than the capacity keeps the first
+ * {@link CLOTH_COLLIDER_SLOTS} the index hands back and says so once. That is
+ * arbitrary among the overflow — the index answers in its own order — which is
+ * why it warns rather than trusting a rule it does not have, and why the
+ * capacity is set well clear of what a scene reaches. `MEASUREMENTS.md` §41 is
+ * what the library's garments actually reach, and the answer is that they reach
+ * whatever the characters around them carry.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
+/**
+ * How far past its own particles a cloth has to look, metres.
+ *
+ * The gather has one job the solver depends on: the set it hands over must
+ * contain every collider `cloth_contact_find` would draw a row against. So the
+ * margin is that function's own reach, maximised over the things the gather
+ * cannot yet know — which collider, and which particle:
+ *
+ *     (radius + inflation) · (1 + CLOTH_CONTACT_MARGIN)   the contact itself
+ *   + collider travel                                     §20, the collider's approach
+ *   + |v| · dt                                            §54, the particle's own
+ *
+ * The radius term is added by {@link cloth_gather_colliders}, which knows the
+ * cloth's `contact_radius`; this supplies the rest. Inflation and collider
+ * travel come from the index as maxima over every live record, because the
+ * gather has not queried yet and so cannot know which records it will get.
+ *
+ * **The velocity is read before the step and the narrowphase reads it after
+ * `damp`**, which only ever scales it down — so this is an upper bound on the
+ * travel the rows are actually discovered with, not an estimate of it. That
+ * ordering is what makes a margin this tight safe; if a step ever gains speed
+ * before `cloth_contact_find`, this stops being a bound and the term has to
+ * carry the acceleration too.
+ *
+ * @param {ClothState} state
+ * @param {ClothColliderIndex} index
+ * @param {number} dt fixed step, seconds
+ * @returns {number} metres
+ */
+export function cloth_gather_reach(state: ClothState, index: ClothColliderIndex, dt: number): number;
 /**
  * Query the index and rewrite the overlapping colliders into the cloth's frame.
  *
- * @param {ClothInstance} instance filled in place — `collider_table`,
- *   `collider_key` and `collider_count`
+ * @param {ClothInstance} instance read for its anchor pose and filter; its
+ *   state's `collider_table`, `collider_key` and `collider_count` are filled
  * @param {ClothColliderIndex} index
- * @param {number} reach how far a particle may travel this step, metres
+ * @param {number} reach how far past its particles the cloth has to look,
+ *   metres — {@link cloth_gather_reach}
  * @returns {number} how many colliders were gathered
  */
 export function cloth_gather_colliders(instance: ClothInstance, index: ClothColliderIndex, reach: number): number;
 /**
- * Whether any collider overlapping this cloth moved between the previous step
- * and this one — §7 P5's "wake on collider motion", asked without waking.
+ * Whether the colliders overlapping this cloth have changed since the step it
+ * last took — §7 P5's "wake on collider motion", asked without waking.
  *
  * A sleeping cloth is not stepped and not written back, so something has to
- * notice when the world it was resting against moves. This is that something,
- * and it is a broadphase query plus a pose comparison: cheaper than a step by
+ * notice when the world it was resting against changes. This is that something,
+ * and it is a broadphase query plus two comparisons: cheaper than a step by
  * three orders of magnitude, which is what makes sleep worth having at all.
  *
+ * **Two comparisons, and the set is the one M2 did not have.** A pose
+ * comparison answers "did anything move", and `ClothColliderSystem#link`
+ * *places* a new collider rather than posing it — previous equals current — so
+ * a sphere spawned around a sleeping rope is a collider that has not moved.
+ * Measured: the rope slept through it and stayed asleep three hundred steps
+ * later with four of its six links inside. A handle appearing in the gathered
+ * set, or leaving it, is a change to the world the cloth went to sleep in
+ * whatever the poses say, and it costs one integer compare per record.
+ *
+ * The query uses the reach the cloth's last *step* gathered with, so the two
+ * sets are answers to the same question. A set built at zero margin against one
+ * built at a step's travel would differ for reasons that are about the margin.
+ *
  * @param {ClothInstance} instance
  * @param {ClothColliderIndex} index
  * @returns {boolean}
  */
 export function cloth_colliders_moved(instance: ClothInstance, index: ClothColliderIndex): boolean;
+/**
+ * Record the set this cloth is about to step against, so the next wake test has
+ * something to compare with. Called only where the cloth really will be
+ * stepped — a set gathered by the wake test itself is a question, not a step.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} reach the margin the gather used, metres
+ * @returns {void}
+ */
+export function cloth_remember_colliders(instance: ClothInstance, reach: number): void;
 //# sourceMappingURL=cloth_gather_colliders.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_gather_colliders.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_gather_colliders.js"],"names":[],"mappings":"AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;GAQG;AACH,kGAHW,MAAM,GACJ,MAAM,CAsJlB;AAgDD;;;;;;;;;;;;GAYG;AACH,2FAFa,OAAO,CAsBnB"}
+{"version":3,"file":"cloth_gather_colliders.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_gather_colliders.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qFAHW,MAAM,GACJ,MAAM,CAwBlB;AAED;;;;;;;;;GASG;AACH,kGAJW,MAAM,GAEJ,MAAM,CA6JlB;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2FAFa,OAAO,CAoCnB;AAED;;;;;;;;GAQG;AACH,yEAHW,MAAM,GACJ,IAAI,CAehB"}

package/src/engine/physics/cloth/ecs/cloth_gather_colliders.js

@@ -27,6 +27,8 @@ import {
     CCR_TZ
 } from "../collider/ClothColliderRecord.js";
 import { cloth_collider_refit_bounds } from "../collider/cloth_collider_bounds.js";
+import { CLOTH_CONTACT_MARGIN } from "../solver/cloth_contact_find.js";
+import { CLOTH_COLLIDER_SLOTS } from "../solver/cloth_solver_constants.js";
 
 /**
  * # Bringing the world's colliders into a cloth's frame
@@ -53,23 +55,106 @@ import { cloth_collider_refit_bounds } from "../collider/cloth_collider_bounds.j
  *
  * ## The query box
  *
- * The cloth's own particle bounds, fattened by how far a contact reaches, and
- * then by how far the solver will let a particle travel in one step. The second
- * term is what stops a fast cloth outrunning its own broadphase within the step
- * it was gathered for; it is the velocity clamp of §7 P1 read as a distance,
- * which is the quantity it was built out of.
+ * The cloth's own particle bounds, fattened by exactly what
+ * `cloth_contact_find` will reach for — no more, because a broadphase that is
+ * wider than its narrowphase is collecting colliders it will then throw away.
+ * {@link cloth_gather_reach} is that quantity and carries the derivation.
+ *
+ * It used to be the velocity clamp of §7 P1 read as a distance. That was wrong
+ * in both directions at once. The clamp is `4 · shortest_row · substeps ·
+ * iterations`, which for a rope of 10 cm links at 2 × 4 is **3.2 m** a step —
+ * so the box was fattened by metres to catch motion measured in centimetres,
+ * and a garment in a crowd collected every bone in the street and overflowed
+ * its table. `cloth_contact_find`'s own docblock had already worked out that
+ * this clamp is "about 154 m/s … three orders of magnitude" past real cloth
+ * speed and stopped using it (§54); the gather kept it. And being enormous, it
+ * hid the fact that it was also **missing** two terms the narrowphase does
+ * reach with — collider inflation and the collider's own travel — so a wide
+ * enough inflation was a row the gather never handed over.
+ *
+ * ## Where the table lives, and why it stopped growing
+ *
+ * In `ClothState`'s single buffer, {@link CLOTH_COLLIDER_SLOTS} records of it,
+ * which is §12's own layout. M2 grew a per-instance array instead, because the
+ * size is a property of the world rather than of the cloth — still true, and
+ * still not the deciding argument. M5's worker steps the cloth out of shared
+ * memory, and an array that can be replaced mid-run is memory the worker would
+ * have to be told about again before it could be named. A fixed region makes the
+ * two systems read the same bytes by construction.
+ *
+ * A cloth whose broadphase returns more than the capacity keeps the first
+ * {@link CLOTH_COLLIDER_SLOTS} the index hands back and says so once. That is
+ * arbitrary among the overflow — the index answers in its own order — which is
+ * why it warns rather than trusting a rule it does not have, and why the
+ * capacity is set well clear of what a scene reaches. `MEASUREMENTS.md` §41 is
+ * what the library's garments actually reach, and the answer is that they reach
+ * whatever the characters around them carry.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 
+/**
+ * How far past its own particles a cloth has to look, metres.
+ *
+ * The gather has one job the solver depends on: the set it hands over must
+ * contain every collider `cloth_contact_find` would draw a row against. So the
+ * margin is that function's own reach, maximised over the things the gather
+ * cannot yet know — which collider, and which particle:
+ *
+ *     (radius + inflation) · (1 + CLOTH_CONTACT_MARGIN)   the contact itself
+ *   + collider travel                                     §20, the collider's approach
+ *   + |v| · dt                                            §54, the particle's own
+ *
+ * The radius term is added by {@link cloth_gather_colliders}, which knows the
+ * cloth's `contact_radius`; this supplies the rest. Inflation and collider
+ * travel come from the index as maxima over every live record, because the
+ * gather has not queried yet and so cannot know which records it will get.
+ *
+ * **The velocity is read before the step and the narrowphase reads it after
+ * `damp`**, which only ever scales it down — so this is an upper bound on the
+ * travel the rows are actually discovered with, not an estimate of it. That
+ * ordering is what makes a margin this tight safe; if a step ever gains speed
+ * before `cloth_contact_find`, this stops being a bound and the term has to
+ * carry the acceleration too.
+ *
+ * @param {ClothState} state
+ * @param {ClothColliderIndex} index
+ * @param {number} dt fixed step, seconds
+ * @returns {number} metres
+ */
+export function cloth_gather_reach(state, index, dt) {
+    const velocity = state.velocity;
+
+    const particle_count = state.particle_count;
+
+    let fastest_squared = 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const speed_squared = velocity[p] * velocity[p]
+            + velocity[p + 1] * velocity[p + 1]
+            + velocity[p + 2] * velocity[p + 2];
+
+        if (speed_squared > fastest_squared) {
+            fastest_squared = speed_squared;
+        }
+    }
+
+    return dt * Math.sqrt(fastest_squared)
+        + index.max_collider_travel
+        + index.max_inflation * (1 + CLOTH_CONTACT_MARGIN);
+}
+
 /**
  * Query the index and rewrite the overlapping colliders into the cloth's frame.
  *
- * @param {ClothInstance} instance filled in place — `collider_table`,
- *   `collider_key` and `collider_count`
+ * @param {ClothInstance} instance read for its anchor pose and filter; its
+ *   state's `collider_table`, `collider_key` and `collider_count` are filled
  * @param {ClothColliderIndex} index
- * @param {number} reach how far a particle may travel this step, metres
+ * @param {number} reach how far past its particles the cloth has to look,
+ *   metres — {@link cloth_gather_reach}
  * @returns {number} how many colliders were gathered
  */
 export function cloth_gather_colliders(instance, index, reach) {
@@ -101,12 +186,14 @@ export function cloth_gather_colliders(instance, index, reach) {
     }
 
     if (particle_count === 0) {
-        instance.collider_count = 0;
+        state.collider_count = 0;
 
         return 0;
     }
 
-    const margin = reach + state.contact_radius * 2;
+    // The contact's own reach, on the same terms `cloth_contact_find` states
+    // it in, plus everything {@link cloth_gather_reach} already folded in.
+    const margin = reach + state.contact_radius * (1 + CLOTH_CONTACT_MARGIN);
 
     min_x -= margin;
     min_y -= margin;
@@ -160,25 +247,30 @@ export function cloth_gather_colliders(instance, index, reach) {
 
     const cloth = instance.cloth;
 
-    const found = index.query(
+    const overlapping = index.query(
         HANDLES, world_min_x, world_min_y, world_min_z,
         world_max_x, world_max_y, world_max_z,
         cloth.layer, cloth.mask
     );
 
-    if (instance.collider_table === null || instance.collider_table.length < found * CCR_STRIDE) {
-        let capacity = 8;
+    let found = overlapping;
 
-        while (capacity < found) {
-            capacity *= 2;
-        }
+    if (found > CLOTH_COLLIDER_SLOTS) {
+        found = CLOTH_COLLIDER_SLOTS;
+
+        if (!instance.collider_overflow_reported) {
+            instance.collider_overflow_reported = true;
 
-        instance.collider_table = new Float32Array(capacity * CCR_STRIDE);
-        instance.collider_key = new Int32Array(capacity);
+            console.warn(
+                `ClothSystem: entity ${instance.entity} overlaps ${overlapping} cloth colliders and the`
+                + ` per-cloth table holds ${CLOTH_COLLIDER_SLOTS}; the rest are not collided against.`
+                + ` Narrow the cloth's layer/mask, or split the collider.`
+            );
+        }
     }
 
-    const table = instance.collider_table;
-    const keys = instance.collider_key;
+    const table = state.collider_table;
+    const keys = state.collider_key;
 
     const source = index.table;
 
@@ -217,7 +309,7 @@ export function cloth_gather_colliders(instance, index, reach) {
         cloth_collider_refit_bounds(table, i, CCR_STRIDE);
     }
 
-    instance.collider_count = found;
+    state.collider_count = found;
 
     return found;
 }
@@ -269,22 +361,49 @@ function localise(
 }
 
 /**
- * Whether any collider overlapping this cloth moved between the previous step
- * and this one — §7 P5's "wake on collider motion", asked without waking.
+ * Whether the colliders overlapping this cloth have changed since the step it
+ * last took — §7 P5's "wake on collider motion", asked without waking.
  *
  * A sleeping cloth is not stepped and not written back, so something has to
- * notice when the world it was resting against moves. This is that something,
- * and it is a broadphase query plus a pose comparison: cheaper than a step by
+ * notice when the world it was resting against changes. This is that something,
+ * and it is a broadphase query plus two comparisons: cheaper than a step by
  * three orders of magnitude, which is what makes sleep worth having at all.
  *
+ * **Two comparisons, and the set is the one M2 did not have.** A pose
+ * comparison answers "did anything move", and `ClothColliderSystem#link`
+ * *places* a new collider rather than posing it — previous equals current — so
+ * a sphere spawned around a sleeping rope is a collider that has not moved.
+ * Measured: the rope slept through it and stayed asleep three hundred steps
+ * later with four of its six links inside. A handle appearing in the gathered
+ * set, or leaving it, is a change to the world the cloth went to sleep in
+ * whatever the poses say, and it costs one integer compare per record.
+ *
+ * The query uses the reach the cloth's last *step* gathered with, so the two
+ * sets are answers to the same question. A set built at zero margin against one
+ * built at a step's travel would differ for reasons that are about the margin.
+ *
  * @param {ClothInstance} instance
  * @param {ClothColliderIndex} index
  * @returns {boolean}
  */
 export function cloth_colliders_moved(instance, index) {
-    const found = cloth_gather_colliders(instance, index, 0);
+    const found = cloth_gather_colliders(instance, index, instance.gather_reach);
+
+    const keys = instance.state.collider_key;
 
-    const table = instance.collider_table;
+    if (found !== instance.collider_key_count) {
+        return true;
+    }
+
+    const seen = instance.collider_keys;
+
+    for (let i = 0; i < found; i++) {
+        if (keys[i] !== seen[i]) {
+            return true;
+        }
+    }
+
+    const table = instance.state.collider_table;
 
     for (let i = 0; i < found; i++) {
         const r = i * CCR_STRIDE;
@@ -303,6 +422,30 @@ export function cloth_colliders_moved(instance, index) {
     return false;
 }
 
+/**
+ * Record the set this cloth is about to step against, so the next wake test has
+ * something to compare with. Called only where the cloth really will be
+ * stepped — a set gathered by the wake test itself is a question, not a step.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} reach the margin the gather used, metres
+ * @returns {void}
+ */
+export function cloth_remember_colliders(instance, reach) {
+    const count = instance.state.collider_count;
+
+    const keys = instance.state.collider_key;
+
+    const seen = instance.collider_keys;
+
+    for (let i = 0; i < count; i++) {
+        seen[i] = keys[i];
+    }
+
+    instance.collider_key_count = count;
+    instance.gather_reach = reach;
+}
+
 /**
  * @type {number[]}
  * @private

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

@@ -51,4 +51,23 @@
  * @param {number} dt
  */
 export function cloth_seed_rig(instance: ClothInstance, proxy: ClothProxy, joints: number[], ecd: EntityComponentDataset, dt: number): void;
+/**
+ * Give back every joint's `TransformAttachment` authority that this cloth's
+ * seeding took from the GPU.
+ *
+ * The seed revokes so that the write-back reaches the row at all, and the
+ * consequence the module docblock states — "a joint cloth simulates stops being
+ * animatable by a clip" — is only the right trade while the cloth is *there*.
+ * A garment removed and nothing re-granting leaves its joints owned by a CPU
+ * that is no longer writing them: neither animated nor simulated, and stuck in
+ * the pose the solver stopped in.
+ *
+ * Only the joints the revoke actually changed are given back, so a joint that
+ * was already the CPU's before cloth arrived stays the CPU's.
+ *
+ * @param {ClothInstance} instance
+ * @param {EntityComponentDataset} ecd
+ * @returns {void}
+ */
+export function cloth_release_rig(instance: ClothInstance, ecd: EntityComponentDataset): void;
 //# sourceMappingURL=cloth_seed_rig.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_seed_rig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_rig.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;;;GAQG;AACH,mFAJW,MAAM,EAAE,mCAER,MAAM,QAyEhB"}
+{"version":3,"file":"cloth_seed_rig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_rig.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;;;GAQG;AACH,mFAJW,MAAM,EAAE,mCAER,MAAM,QAkFhB;AAoED;;;;;;;;;;;;;;;;;GAiBG;AACH,yFAFa,IAAI,CAoBhB"}