@woosh/meep-engine 3.25.0 → 3.26.0

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

@@ -3,6 +3,7 @@ import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multip
 import { quat3_nlerp } from "../../../../core/geom/3d/quaternion/quat3_nlerp.js";
 import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
 import { v3_quaternion_apply_inverse } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import { EntityObserver } from "../../../ecs/EntityObserver.js";
 import {
     TransformAttachment
 } from "../../../ecs/transform-attachment/TransformAttachment.js";
@@ -30,6 +31,7 @@ import { ClothRig } from "./ClothRig.js";
 import {
     CLOTH_ANCHOR_ROTATION_LIMIT,
     CLOTH_ANCHOR_TRAVEL_REACH,
+    CLOTH_SLEEP_DISPLACEMENT_RATIO,
     CLOTH_SLEEP_SPEED_RATIO,
     CLOTH_SLEEP_STEPS,
     CLOTH_STABILISE_STEPS,
@@ -41,14 +43,17 @@ import {
 } from "./cloth_dynamics_map.js";
 import {
     cloth_colliders_moved,
-    cloth_gather_colliders
+    cloth_gather_colliders,
+    cloth_gather_reach,
+    cloth_remember_colliders
 } from "./cloth_gather_colliders.js";
 import {
     cloth_dynamics_change_needs_reseed,
     cloth_reparameterise
 } from "./cloth_build_rows.js";
-import { cloth_seed_subtree } from "./cloth_seed_subtree.js";
-import { cloth_seed_rig } from "./cloth_seed_rig.js";
+import { Cloth } from "./Cloth.js";
+import { cloth_release_subtree, cloth_seed_subtree } from "./cloth_seed_subtree.js";
+import { cloth_release_rig, cloth_seed_rig } from "./cloth_seed_rig.js";
 import { cloth_write_back } from "./cloth_write_back.js";
 import { cloth_write_back_rig } from "./cloth_write_back_rig.js";
 
@@ -143,8 +148,16 @@ export class ClothWorld {
     gravity = new Float64Array([0, -9.81, 0]);
 
     /**
-     * Live cloths, ordered so that an instance whose anchor sits inside another
-     * instance's subtree steps after it.
+     * Live cloths, in the order they were linked.
+     *
+     * **Not sorted by hierarchy depth**, and it used to be. The sort existed so
+     * that a nested cloth advanced against an anchor the cloth above it had
+     * already written this step — which `WorkerClothSystem` cannot do, because
+     * the step it is writing back happened on another thread a tick ago. Both
+     * systems now advance every cloth, then step every cloth, then finish every
+     * cloth, so a nested cloth reads its parent one fixed step stale on both
+     * sides and the sort has nothing left to decide. `ClothSystem#fixedUpdate`
+     * carries the argument; `MEASUREMENTS.md` §56 carries the measurement.
      * @type {ClothInstance[]}
      */
     instances = [];
@@ -252,10 +265,28 @@ export class ClothWorld {
     __by_entity = new Map();
 
     /**
-     * @type {boolean}
+     * Watches `Cloth` + {@link ClothRig} so the rig path is a **live**
+     * discriminator rather than one read once.
+     *
+     * `ClothSystem#dependencies` is `[Cloth, Transform64]` — the tuple that
+     * makes something a cloth — so a `ClothRig` added to a live cloth completes
+     * no tuple the system observes and a `ClothRig` removed from one breaks
+     * none. §3.1's "the discriminator is a component's presence" then holds only
+     * for a character spawned whole, which is the one case a spec constructs and
+     * the least likely one in a scene where a model loads asynchronously.
+     *
+     * Both edges re-seed. The removing edge also gives the joints back first,
+     * because the instance that knows which they were is about to stop being a
+     * rig.
+     * @type {EntityObserver}
      * @private
      */
-    __order_dirty = false;
+    __rig_observer = new EntityObserver(
+        [Cloth, ClothRig],
+        (cloth, rig, entity) => this.reseed(entity),
+        (cloth, rig, entity) => this.#rig_removed(entity),
+        this
+    );
 
     /**
      * Resolve the systems a cloth world reads. Called from the owning system's
@@ -299,11 +330,30 @@ export class ClothWorld {
         this.instances.push(instance);
         this.__by_entity.set(entity, instance);
 
-        this.__order_dirty = true;
-
         return instance;
     }
 
+    /**
+     * Watch this dataset for a {@link ClothRig} arriving at or leaving a live
+     * cloth. Called from the owning system's `handleDatasetAttached`; see
+     * {@link ClothWorld#__rig_observer} for why the system's own dependency
+     * tuple cannot answer this.
+     *
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    attach_dataset(dataset) {
+        dataset.addObserver(this.__rig_observer, true);
+    }
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    detach_dataset(dataset) {
+        dataset.removeObserver(this.__rig_observer, false);
+    }
+
     /**
      * @param {number} entity
      * @returns {ClothInstance|undefined} the instance that was removed
@@ -315,6 +365,14 @@ export class ClothWorld {
             return undefined;
         }
 
+        // Give back what the seeding took. Seeding is not a read: it revokes
+        // the GPU's authority over a rig's joints, and it leaves the entity
+        // path's authored local transforms nowhere but inside the cloth,
+        // because `cloth_write_back` overwrites them every step. A cloth
+        // removed without this leaves joints nothing is writing and a subtree
+        // frozen in the shape the solver stopped in.
+        this.#release(instance);
+
         this.__by_entity.delete(entity);
 
         const index = this.instances.indexOf(instance);
@@ -326,6 +384,51 @@ export class ClothWorld {
         return instance;
     }
 
+    /**
+     * Hand back whatever this instance's seeding took from the scene.
+     *
+     * @param {ClothInstance} instance
+     * @private
+     */
+    #release(instance) {
+        if (!instance.seeded) {
+            return;
+        }
+
+        const ecd = this.entityManager === null ? null : this.entityManager.dataset;
+
+        if (ecd === null || ecd === undefined) {
+            return;
+        }
+
+        if (instance.rig === null) {
+            cloth_release_subtree(instance, ecd);
+        } else {
+            cloth_release_rig(instance, ecd);
+        }
+    }
+
+    /**
+     * A {@link ClothRig} has left a live cloth: give its joints back, then
+     * re-seed, which without a rig is the entity path.
+     *
+     * @param {number} entity
+     * @private
+     */
+    #rig_removed(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return;
+        }
+
+        this.#release(instance);
+
+        instance.rig = null;
+
+        this.reseed(entity);
+    }
+
     /**
      * Throw away a cloth's binding so the next step walks its subtree again.
      *
@@ -348,8 +451,6 @@ export class ClothWorld {
         instance.seeded = false;
         instance.anchor_valid = false;
 
-        this.__order_dirty = true;
-
         return instance;
     }
 
@@ -385,10 +486,6 @@ export class ClothWorld {
      * @param {number} dt seconds
      */
     begin(ecd, dt) {
-        if (this.__order_dirty) {
-            this.#reorder(ecd);
-        }
-
         // Owed to the clock, and spent by the first `advance` — see {@link time}
         // for why the two are not the same moment. Assigned rather than set, so a
         // world whose source is taken away does not carry a debt.
@@ -457,10 +554,8 @@ export class ClothWorld {
         instance.contact_count = result[ClothStepResult.CONTACT_COUNT];
         instance.self_pairs = result[ClothStepResult.SELF_PAIRS];
 
-        const speed = result[ClothStepResult.SPEED];
-
         if ((instance.cloth.flags & ClothFlags.NeverSleep) === 0) {
-            if (speed < CLOTH_SLEEP_SPEED_RATIO * instance.reach) {
+            if (cloth_inside_sleep_window(instance)) {
                 instance.still_steps++;
 
                 if (instance.still_steps >= CLOTH_SLEEP_STEPS) {
@@ -502,7 +597,7 @@ export class ClothWorld {
     #seed(instance, ecd, dt) {
         const rig = ecd.getComponent(instance.entity, ClothRig);
 
-        if (rig === undefined || rig === null || rig.proxy === null) {
+        if (rig === undefined || rig === null) {
             instance.rig = null;
 
             cloth_seed_subtree(instance, ecd, this.attachments, dt);
@@ -510,6 +605,17 @@ export class ClothWorld {
             return;
         }
 
+        if (rig.proxy === null) {
+            // Present and not ready. The same branch as a model that has not
+            // loaded, and for the same reason: a proxy filled in a few ticks
+            // after the component is a rig that is arriving, not a rig that is
+            // absent. Treating it as absent walks the character's own transform
+            // subtree — which under a spawned model is the whole skeleton — and
+            // seeds a skeleton as one rope, throwing in a dev build through
+            // `gpu_authority_assert_cpu` and simulating it in a shipped one.
+            return;
+        }
+
         if (this.models === null) {
             this.#refuse(instance, `entity ${instance.entity} has a ClothRig and nothing hands out model instances`);
 
@@ -555,44 +661,6 @@ export class ClothWorld {
         console.warn(`ClothSystem: ${message}`);
     }
 
-    /**
-     * Depth-first order by hierarchy depth, so a nested cloth reads an anchor
-     * the cloth above it has already written.
-     *
-     * @param {EntityComponentDataset} ecd
-     * @private
-     */
-    #reorder(ecd) {
-        const instances = this.instances;
-
-        for (let i = 0; i < instances.length; i++) {
-            const instance = instances[i];
-
-            let depth = 0;
-            let entity = instance.entity;
-
-            // Bounded by the number of entities; a cycle in the attachment
-            // graph is not this system's to diagnose, but it is this loop's to
-            // survive.
-            for (let guard = 0; guard < 4096; guard++) {
-                const attachment = ecd.getComponent(entity, TransformAttachment);
-
-                if (attachment === undefined) {
-                    break;
-                }
-
-                entity = attachment.parent;
-                depth++;
-            }
-
-            instance.depth = depth;
-        }
-
-        instances.sort((a, b) => a.depth - b.depth);
-
-        this.__order_dirty = false;
-    }
-
     /**
      * Carry one seeded cloth to the edge of its step and write the parameters
      * the step will run on: whatever the anchor did to the local frame, where
@@ -606,6 +674,11 @@ export class ClothWorld {
      *   that is asleep, and then nothing has been written to `params`
      */
     advance(instance, dt, params, offset) {
+        // This cloth's own clock, moved before anything reads it — including
+        // the wake tests below, which are asking about the step that would
+        // follow. See {@link ClothInstance#age}.
+        instance.age += dt;
+
         if (this.__wind_pending !== 0) {
             this.time += this.__wind_pending;
 
@@ -686,7 +759,8 @@ export class ClothWorld {
             if (cloth_air_changed(
                 instance.state, this.wind,
                 instance.anchor_translation, instance.anchor_rotation,
-                instance.air_seen, CLOTH_SLEEP_SPEED_RATIO * instance.reach
+                instance.air_seen, CLOTH_SLEEP_SPEED_RATIO * instance.reach,
+                instance.age
             )) {
                 instance.asleep = false;
                 instance.still_steps = 0;
@@ -749,12 +823,23 @@ export class ClothWorld {
         state.contact_radius = dynamics.thickness;
 
         if (this.colliders !== null) {
-            // The gather's margin is how far a particle may travel this step,
-            // which is the velocity clamp read as a distance — the quantity it
-            // was built out of (`cloth_dynamics_map.js`).
-            cloth_gather_colliders(instance, this.colliders.index, limit * dt);
+            // The gather's margin is what the narrowphase will reach for and
+            // nothing beyond it — `cloth_gather_reach` carries the derivation,
+            // and why the velocity clamp that used to stand here was both far
+            // too wide and missing two terms.
+            const reach = cloth_gather_reach(state, this.colliders.index, dt);
+
+            cloth_gather_colliders(instance, this.colliders.index, reach);
+
+            // What this cloth is about to step against, for the next wake test
+            // to compare with. Here rather than inside the gather because the
+            // wake test gathers too, and what it asks about is the set the last
+            // *step* saw.
+            cloth_remember_colliders(instance, reach);
         } else {
             state.collider_count = 0;
+
+            instance.collider_key_count = 0;
         }
 
         // §10. The one piece of a cloth's step that has to read the world and
@@ -770,7 +855,7 @@ export class ClothWorld {
             instance.air_varies = cloth_sample_air(
                 state, this.wind,
                 instance.anchor_translation, instance.anchor_rotation,
-                instance.air_seen
+                instance.air_seen, instance.age
             );
         } else {
             instance.air_varies = false;
@@ -1059,6 +1144,65 @@ function move_local_frame(
  */
 const CARRIED = new Float64Array(3);
 
+/**
+ * Whether every particle is still within the sleep window's own anchor — §7
+ * P5's "maximum particle displacement over a window", and the reason the test
+ * is not the instantaneous speed it used to be.
+ *
+ * A cloth **resting on a collider** does not stop: its contact rows carry a
+ * penalty that `γ = 1` never decays, and what it settles into is a bounded
+ * limit cycle. Measured on an 8-link rope on a floor, that is a tenth of a
+ * millimetre of travel a step — nothing anyone can see — at a peak speed of
+ * 1.5e-2 m/s, eighteen times the threshold a speed test allowed. So the speed
+ * test held four of the seven library fabrics awake indefinitely on a floor
+ * while the same fabrics slept in 283 steps hanging free. Distance covered
+ * since the window opened tells those two apart; a speed sampled at one instant
+ * cannot. `MEASUREMENTS.md` §53.
+ *
+ * The anchor is re-taken whenever a particle leaves the threshold, so the
+ * window measures "how far has anything moved since the cloth last moved"
+ * rather than chopping time into fixed epochs a slow drift could hide inside.
+ *
+ * @param {ClothInstance} instance
+ * @returns {boolean}
+ * @private
+ */
+function cloth_inside_sleep_window(instance) {
+    const position = instance.state.position;
+
+    let reference = instance.sleep_reference;
+
+    if (reference === null || reference.length !== position.length) {
+        // First step, or a re-seed that changed the particle count. There is no
+        // window yet, so this step opens one.
+        instance.sleep_reference = Float32Array.from(position);
+
+        return false;
+    }
+
+    const threshold = CLOTH_SLEEP_DISPLACEMENT_RATIO * instance.reach;
+
+    const threshold_squared = threshold * threshold;
+
+    const particle_count = instance.state.particle_count;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const dx = position[p] - reference[p];
+        const dy = position[p + 1] - reference[p + 1];
+        const dz = position[p + 2] - reference[p + 2];
+
+        if (dx * dx + dy * dy + dz * dz > threshold_squared) {
+            reference.set(position);
+
+            return false;
+        }
+    }
+
+    return true;
+}
+
 /**
  * Point every leash row at where it measures from: a slack row at the
  * particle's animated position, a tether at the anchor.

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

@@ -133,6 +133,16 @@ export class WorkerClothSystem extends WorkerSystem {
     get models(): {
         instance_of: (arg0: number) => (PrefabInstance | null);
     };
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    handleDatasetAttached(dataset: EntityComponentDataset): void;
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    handleDatasetDetached(dataset: EntityComponentDataset): void;
     /**
      * @param {Cloth} cloth
      * @param {Transform64} transform

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

@@ -1 +1 @@
-{"version":3,"file":"WorkerClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/WorkerClothSystem.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH;IAoEI;;;;;;;;OAQG;IACH;QAPiC,cAAc,EAApC,MAAM,MAAM;QAIK,eAAe,GAAhC,MAAM;OAYhB;IApFD,oDAAoC;IAEpC,iUAOE;IAEF;;;;;OAKG;IACH,OAFU,UAAU,CAEK;IA6EzB;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAoBD;;OAEG;IACH,qBAEC;IAhBD;;;;;;OAMG;IACH,gBAEC;IASD;;OAEG;IACH,iCAEC;IASD;;OAEG;IACH;4BAToC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;OAWjE;IAZD;;OAEG;IACH;4BAFoC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;MAIjE;IA6CD;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAQhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;IAED;;;;OAIG;IACH,iCAEC;;CAmOJ;6BA/iB4B,oCAAoC;4BAIrC,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;8BAInC,oBAAoB;6BACrB,mBAAmB;yBACvB,eAAe;2BACb,iBAAiB"}
+{"version":3,"file":"WorkerClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/WorkerClothSystem.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH;IAoEI;;;;;;;;OAQG;IACH;QAPiC,cAAc,EAApC,MAAM,MAAM;QAIK,eAAe,GAAhC,MAAM;OAYhB;IApFD,oDAAoC;IAEpC,iUAOE;IAEF;;;;;OAKG;IACH,OAFU,UAAU,CAEK;IA6EzB;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAoBD;;OAEG;IACH,qBAEC;IAhBD;;;;;;OAMG;IACH,gBAEC;IASD;;OAEG;IACH,iCAEC;IASD;;OAEG;IACH;4BAToC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;OAWjE;IAZD;;OAEG;IACH;4BAFoC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;MAIjE;IAiCD;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAcD;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAQhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;IAED;;;;OAIG;IACH,iCAEC;;CAmOJ;6BA/jB4B,oCAAoC;4BAIrC,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;8BAInC,oBAAoB;6BACrB,mBAAmB;yBACvB,eAAe;2BACb,iBAAiB"}

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

@@ -22,7 +22,7 @@ import {
  * which is allocated once at startup and cannot grow.
  * @type {number}
  */
-const DEFAULT_MAX_CLOTH_COUNT = 32;
+const DEFAULT_MAX_CLOTH_COUNT = 64;
 
 /**
  * Drop-in alternative to {@link ClothSystem} that runs the solve on a worker
@@ -265,6 +265,22 @@ export class WorkerClothSystem extends WorkerSystem {
         await super.startup(entityManager);
     }
 
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    handleDatasetAttached(dataset) {
+        this.world.attach_dataset(dataset);
+    }
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    handleDatasetDetached(dataset) {
+        this.world.detach_dataset(dataset);
+    }
+
     /**
      * @param {EntityManager} entityManager
      * @returns {Promise<void>}

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

@@ -277,12 +277,36 @@ export const CLOTH_STABILISE_STEPS: number;
  */
 export const CLOTH_DRAG_RATE_MAX: number;
 /**
- * Speed below which a particle counts as still, as a fraction of the cloth's
- * reach per second. A metre-long rope sleeps once nothing on it is moving
- * faster than a millimetre a second.
+ * Speed below which the air counts as unchanged, as a fraction of the cloth's
+ * reach per second — §10's wake test, which asks whether a gust has arrived.
+ *
+ * This was the sleep test's own threshold until the sleep test stopped reading
+ * a speed; see {@link CLOTH_SLEEP_DISPLACEMENT_RATIO} for why.
  * @type {number}
  */
 export const CLOTH_SLEEP_SPEED_RATIO: number;
+/**
+ * How far a particle may travel from the window's anchor and still count as
+ * still, as a fraction of the cloth's reach (§7 P5).
+ *
+ * **Displacement rather than speed, and a contact is why.** A cloth resting on
+ * a collider carries contact rows whose penalty `γ = 1` never decays, and the
+ * configuration it settles into is a *bounded limit cycle* rather than a rest
+ * state: measured on an 8-link rope on a floor, a tenth of a millimetre of
+ * travel per step — invisible — at a peak particle speed of 1.5e-2 m/s, which
+ * is eighteen times what the old speed threshold allowed. An instantaneous
+ * speed cannot tell a cloth vibrating in place apart from one going somewhere;
+ * the distance it has covered since the window opened can, and that is what
+ * §7 P5's own text has always described.
+ *
+ * `5e-4` rather than {@link CLOTH_SLEEP_SPEED_RATIO}'s `1e-3` so the gate is no
+ * *looser* than the speed test it replaces: over the {@link CLOTH_SLEEP_STEPS}
+ * window at the engine's 60 Hz fixed step, half a thousandth of a reach is the
+ * same millimetre a second. Every library entry on a floor or a sphere sleeps
+ * inside 961 steps at this value. `MEASUREMENTS.md` §53.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_DISPLACEMENT_RATIO: number;
 /**
  * How many consecutive still steps put a cloth to sleep (§7 P5). Half a second
  * at 60 Hz, which is long enough that a cloth pausing at the top of a swing

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_dynamics_map.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_dynamics_map.js"],"names":[],"mappings":"AA0OA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;GAQG;AACH,uCAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;GAWG;AACH,mDAPW,MAAM,YAEN,MAAM,cACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,0CAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;GAQG;AACH,kDAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;AApVD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;GAWG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;GAKG;AACH,mCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,+CAFU,MAAM,CAEkC;AAElD;;;;;;;;GAQG;AACH,iCAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;;;GAaG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;GAKG;AACH,sCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB"}
+{"version":3,"file":"cloth_dynamics_map.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_dynamics_map.js"],"names":[],"mappings":"AAmQA;;;;;;;;GAQG;AACH,gDAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;GAQG;AACH,uCAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;;;GAWG;AACH,mDAPW,MAAM,YAEN,MAAM,cACN,MAAM,MACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,0CAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;GAQG;AACH,kDAJW,MAAM,MACN,MAAM,GACJ,MAAM,CAQlB;AA7WD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;GAWG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;GAKG;AACH,mCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,+CAFU,MAAM,CAEkC;AAElD;;;;;;;;GAQG;AACH,iCAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;;;GAaG;AACH,wCAFU,MAAM,CAE6B;AAE7C;;;;;;;;GAQG;AACH,0CAFU,MAAM,CAE+B;AAE/C;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;;GAQG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,kCAFU,MAAM,CAEsB;AAEtC;;;;;;;GAOG;AACH,sCAFU,MAAM,CAE4B;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,6CAFU,MAAM,CAEmC;AAEnD;;;;;GAKG;AACH,gCAFU,MAAM,CAEoB"}

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

@@ -217,13 +217,38 @@ export const CLOTH_STABILISE_STEPS = 20;
 export const CLOTH_DRAG_RATE_MAX = 60;
 
 /**
- * Speed below which a particle counts as still, as a fraction of the cloth's
- * reach per second. A metre-long rope sleeps once nothing on it is moving
- * faster than a millimetre a second.
+ * Speed below which the air counts as unchanged, as a fraction of the cloth's
+ * reach per second — §10's wake test, which asks whether a gust has arrived.
+ *
+ * This was the sleep test's own threshold until the sleep test stopped reading
+ * a speed; see {@link CLOTH_SLEEP_DISPLACEMENT_RATIO} for why.
  * @type {number}
  */
 export const CLOTH_SLEEP_SPEED_RATIO = 1e-3;
 
+/**
+ * How far a particle may travel from the window's anchor and still count as
+ * still, as a fraction of the cloth's reach (§7 P5).
+ *
+ * **Displacement rather than speed, and a contact is why.** A cloth resting on
+ * a collider carries contact rows whose penalty `γ = 1` never decays, and the
+ * configuration it settles into is a *bounded limit cycle* rather than a rest
+ * state: measured on an 8-link rope on a floor, a tenth of a millimetre of
+ * travel per step — invisible — at a peak particle speed of 1.5e-2 m/s, which
+ * is eighteen times what the old speed threshold allowed. An instantaneous
+ * speed cannot tell a cloth vibrating in place apart from one going somewhere;
+ * the distance it has covered since the window opened can, and that is what
+ * §7 P5's own text has always described.
+ *
+ * `5e-4` rather than {@link CLOTH_SLEEP_SPEED_RATIO}'s `1e-3` so the gate is no
+ * *looser* than the speed test it replaces: over the {@link CLOTH_SLEEP_STEPS}
+ * window at the engine's 60 Hz fixed step, half a thousandth of a reach is the
+ * same millimetre a second. Every library entry on a floor or a sphere sleeps
+ * inside 961 steps at this value. `MEASUREMENTS.md` §53.
+ * @type {number}
+ */
+export const CLOTH_SLEEP_DISPLACEMENT_RATIO = 5e-4;
+
 /**
  * How many consecutive still steps put a cloth to sleep (§7 P5). Half a second
  * at 60 Hz, which is long enough that a cloth pausing at the top of a swing