@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -1,331 +1,340 @@
-import { assert } from "../../../../core/assert.js";
-import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
-import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
-import { ClothDynamicsFlags } from "./ClothDynamicsFlags.js";
-
-/**
- * # How a cloth behaves — the whole parameter set
- *
- * Ten fields, and the library in `cloth_dynamics_library.js` is a set of points
- * in them that are known to be good. There is no second "advanced" block, no
- * field that silently rewrites another, and no animation curve over depth: the
- * per-particle profile that other cloth packages author with curves falls out
- * of the baked geodesic distance instead (§3.4).
- *
- * ## The stiffnesses are normalised, and what they map to is measured
- *
- * `stretch` and `bend` are coordinates in `[0, 1]`, not moduli in N/m, and they
- * are log-mapped internally so that `0.7` means something an author can predict
- * and `0.9` is not four orders of magnitude away from it. `cloth_dynamics_map.js`
- * is that mapping and carries the measurement behind each end of each range.
- *
- * Two of those mappings are M0 findings rather than taste:
- *
- * - **`stretch` does not map to a stiffness at all.** A stretch *penalty*
- *   stiffer than about `8·(m/h²)` makes the step add energy rather than
- *   dissipate it — measured at +6.8 J on a sheet whose entire gravitational
- *   potential is 1.2 J — and for a half-gram particle at 60 Hz × 2 substeps
- *   that boundary sits near 60 N/m, which is a rubber band rather than a
- *   fabric. So the stretch row is **hard** (§6), and `stretch` maps to the
- *   strain the fabric is allowed to carry before the strain-limit row stops it.
- *   `MEASUREMENTS.md` §6.
- * - **`bend` maps to a ratio, not to a stiffness.** A bend row is soft, so it
- *   has to stay inside that same dissipative band, and the band is a multiple
- *   of the row's own `m/h²` rather than a number of newtons per metre —
- *   `MEASUREMENTS.md` §4 held a chain at a fixed ratio across five decades of
- *   particle mass and got the same answer every time. Expressing `bend` as a
- *   ratio of `m/dt²` therefore keeps the fabric's *look* invariant to how heavy
- *   the author made it and to how many substeps the budget allows.
- *
- * ## `damping` is load-bearing
- *
- * §7 P5's mechanism for jitter at rest is the multiplier decay `α·γ < 1`, and
- * that reaches **hard** rows only, because a soft row has no multiplier to
- * decay. M0 measured a soft cloth landing in a bounded limit cycle that 2,000
- * further steps do not move. `damping` is what reaches it, which makes this
- * field part of the correctness argument rather than a taste control. See
- * `ClothSystem`'s settle pass.
- *
- * ## `substeps` and `iterations` are budget, and the library is sized to it
- *
- * They are here rather than on the system because a chain wants more of both
- * than a bedsheet does, so they are part of what "chain" means. They are also
- * the levers that bring a garment inside the measured frame budget: 1,024
- * particles at 2×4 costs 3.48 ms against a 2 ms target, and halving either one
- * lands inside (`MEASUREMENTS.md` §7). Every library entry states the particle
- * count it is sized for and which lever it took.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class ClothDynamics {
-
-    /**
-     * How little the fabric extends, `[0, 1]`. `0` is a knit that gives a
-     * quarter of its length; `1` is a chain. Maps to the strain-limit row's
-     * allowance, not to a stiffness — see the class docblock.
-     * @type {number}
-     */
-    stretch = 0.7;
-
-    /**
-     * How strongly the fabric resists folding, `[0, 1]`. Maps to a bend row
-     * stiffness expressed as a ratio of the row's own `m/dt²`.
-     * @type {number}
-     */
-    bend = 0.2;
-
-    /**
-     * Velocity retained per step, inverted: `0` is undamped, `1` is heavily
-     * damped. Load-bearing for §7 P5 on any cloth carrying soft rows.
-     * @type {number}
-     */
-    damping = 0.15;
-
-    /**
-     * How far the cloth may leave its animated pose, `[0, 1]`. Each particle's
-     * leash radius is `slack · d_geo,i` — its own baked geodesic distance to
-     * the fixed set — so a hem gets a long leash and a waistband a short one
-     * without anybody painting a profile (§3.4). At `0` every particle is
-     * welded to its animated position.
-     * @type {number}
-     */
-    slack = 0.5;
-
-    /**
-     * Particle radius, metres. Collision offset and self-collision separation
-     * from M2 onwards; in M1 it is the length scale the velocity clamp of
-     * §7 P1 is derived from.
-     * @type {number}
-     */
-    thickness = 0.02;
-
-    /**
-     * How much of the anchor's own world motion the cloth feels, `[0, 1]`.
-     * `1` is a cape that trails a sprinting character; `0` is a cloth welded
-     * into the anchor's frame, which feels no locomotion at all. §7 P7.
-     * @type {number}
-     */
-    inertia = 1;
-
-    /**
-     * Aerodynamic coupling to the air, `[0, 1]`. §10, and read from M6
-     * onwards; carried here from M1 so that a library entry says what the
-     * fabric is rather than what the current milestone can honour.
-     * @type {number}
-     */
-    drag = 0.1;
-
-    /**
-     * Solver substeps per fixed step. More substeps means less of implicit
-     * Euler's numerical damping and a livelier drape, and a proportionally
-     * larger frame cost.
-     * @type {number}
-     */
-    substeps = 2;
-
-    /**
-     * Descent iterations per substep. More iterations converges further
-     * towards the same answer rather than changing which answer it is (§5.1).
-     * @type {number}
-     */
-    iterations = 4;
-
-    /**
-     * @see ClothDynamicsFlags
-     * @type {number}
-     */
-    flags = ClothDynamicsFlags.StrainLimit;
-
-    /**
-     * @param {number|ClothDynamicsFlags} flag
-     * @returns {boolean}
-     */
-    getFlag(flag) {
-        return (this.flags & flag) === flag;
-    }
-
-    /**
-     * Build one from a partial specification; anything left out keeps the
-     * default above.
-     *
-     * @param {object} [spec]
-     * @param {number} [spec.stretch]
-     * @param {number} [spec.bend]
-     * @param {number} [spec.damping]
-     * @param {number} [spec.slack]
-     * @param {number} [spec.thickness]
-     * @param {number} [spec.inertia]
-     * @param {number} [spec.drag]
-     * @param {number} [spec.substeps]
-     * @param {number} [spec.iterations]
-     * @param {number} [spec.flags]
-     * @returns {ClothDynamics}
-     */
-    static from(spec = {}) {
-        const r = new ClothDynamics();
-
-        r.#assign(spec);
-
-        return r;
-    }
-
-    /**
-     * @param {object} spec
-     * @private
-     */
-    #assign({
-        stretch = this.stretch,
-        bend = this.bend,
-        damping = this.damping,
-        slack = this.slack,
-        thickness = this.thickness,
-        inertia = this.inertia,
-        drag = this.drag,
-        substeps = this.substeps,
-        iterations = this.iterations,
-        flags = this.flags
-    }) {
-        assert.isNumber(stretch, 'stretch');
-        assert.isNumber(bend, 'bend');
-        assert.isNumber(damping, 'damping');
-        assert.isNumber(slack, 'slack');
-        assert.isNumber(thickness, 'thickness');
-        assert.isNumber(inertia, 'inertia');
-        assert.isNumber(drag, 'drag');
-        assert.isPositiveInteger(substeps, 'substeps');
-        assert.isPositiveInteger(iterations, 'iterations');
-        assert.isNonNegativeInteger(flags, 'flags');
-
-        this.stretch = stretch;
-        this.bend = bend;
-        this.damping = damping;
-        this.slack = slack;
-        this.thickness = thickness;
-        this.inertia = inertia;
-        this.drag = drag;
-        this.substeps = substeps;
-        this.iterations = iterations;
-        this.flags = flags;
-    }
-
-    /**
-     * A mutable copy. This is how a library entry is edited: the entries are
-     * frozen and shared, and `clone` is the one step between "assign one" and
-     * "own one".
-     *
-     * @returns {ClothDynamics}
-     */
-    clone() {
-        const r = new ClothDynamics();
-
-        r.stretch = this.stretch;
-        r.bend = this.bend;
-        r.damping = this.damping;
-        r.slack = this.slack;
-        r.thickness = this.thickness;
-        r.inertia = this.inertia;
-        r.drag = this.drag;
-        r.substeps = this.substeps;
-        r.iterations = this.iterations;
-        r.flags = this.flags;
-
-        return r;
-    }
-
-    /**
-     * @param {ClothDynamics} other
-     * @returns {boolean}
-     */
-    copy(other) {
-        this.stretch = other.stretch;
-        this.bend = other.bend;
-        this.damping = other.damping;
-        this.slack = other.slack;
-        this.thickness = other.thickness;
-        this.inertia = other.inertia;
-        this.drag = other.drag;
-        this.substeps = other.substeps;
-        this.iterations = other.iterations;
-        this.flags = other.flags;
-
-        return this;
-    }
-
-    /**
-     * @param {ClothDynamics} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        if (other === this) {
-            return true;
-        }
-
-        if (other === null || other === undefined || other.isClothDynamics !== true) {
-            return false;
-        }
-
-        return this.stretch === other.stretch
-            && this.bend === other.bend
-            && this.damping === other.damping
-            && this.slack === other.slack
-            && this.thickness === other.thickness
-            && this.inertia === other.inertia
-            && this.drag === other.drag
-            && this.substeps === other.substeps
-            && this.iterations === other.iterations
-            && this.flags === other.flags;
-    }
-
-    /**
-     * @returns {number}
-     */
-    hash() {
-        return combine_hash(
-            computeHashFloat(this.stretch),
-            computeHashFloat(this.bend),
-            computeHashFloat(this.damping),
-            computeHashFloat(this.slack),
-            computeHashFloat(this.thickness),
-            computeHashFloat(this.inertia),
-            computeHashFloat(this.drag),
-            this.substeps,
-            this.iterations,
-            this.flags
-        );
-    }
-
-    toJSON() {
-        return {
-            stretch: this.stretch,
-            bend: this.bend,
-            damping: this.damping,
-            slack: this.slack,
-            thickness: this.thickness,
-            inertia: this.inertia,
-            drag: this.drag,
-            substeps: this.substeps,
-            iterations: this.iterations,
-            flags: this.flags
-        };
-    }
-
-    /**
-     * @param {object} json
-     */
-    fromJSON(json) {
-        this.#assign(json);
-    }
-
-    toString() {
-        return `ClothDynamics${JSON.stringify(this.toJSON())}`;
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-ClothDynamics.prototype.isClothDynamics = true;
-
-ClothDynamics.typeName = "ClothDynamics";
+import { assert } from "../../../../core/assert.js";
+import { combine_hash } from "../../../../core/collection/array/combine_hash.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { ClothDynamicsFlags } from "./ClothDynamicsFlags.js";
+
+/**
+ * # How a cloth behaves — the whole parameter set
+ *
+ * Ten fields, and the library in `cloth_dynamics_library.js` is a set of points
+ * in them that are known to be good. There is no second "advanced" block, no
+ * field that silently rewrites another, and no animation curve over depth: the
+ * per-particle profile that other cloth packages author with curves falls out
+ * of the baked geodesic distance instead (§3.4).
+ *
+ * ## The stiffnesses are normalised, and what they map to is measured
+ *
+ * `stretch` and `bend` are coordinates in `[0, 1]`, not moduli in N/m, and they
+ * are log-mapped internally so that `0.7` means something an author can predict
+ * and `0.9` is not four orders of magnitude away from it. `cloth_dynamics_map.js`
+ * is that mapping and carries the measurement behind each end of each range.
+ *
+ * Two of those mappings are M0 findings rather than taste:
+ *
+ * - **`stretch` does not map to a stiffness at all.** A stretch *penalty*
+ *   stiffer than about `8·(m/h²)` makes the step add energy rather than
+ *   dissipate it — measured at +6.8 J on a sheet whose entire gravitational
+ *   potential is 1.2 J — and for a half-gram particle at 60 Hz × 2 substeps
+ *   that boundary sits near 60 N/m, which is a rubber band rather than a
+ *   fabric. So the stretch row is **hard** (§6), and `stretch` maps to the
+ *   strain the fabric is allowed to carry before the strain-limit row stops it.
+ *   `MEASUREMENTS.md` §6.
+ * - **`bend` maps to a ratio, not to a stiffness.** A bend row is soft, so it
+ *   has to stay inside that same dissipative band, and the band is a multiple
+ *   of the row's own `m/h²` rather than a number of newtons per metre —
+ *   `MEASUREMENTS.md` §4 held a chain at a fixed ratio across five decades of
+ *   particle mass and got the same answer every time. Expressing `bend` as a
+ *   ratio of `m/dt²` therefore keeps the fabric's *look* invariant to how heavy
+ *   the author made it and to how many substeps the budget allows.
+ *
+ * ## `damping` is load-bearing
+ *
+ * §7 P5's mechanism for jitter at rest is the multiplier decay `α·γ < 1`, and
+ * that reaches **hard** rows only, because a soft row has no multiplier to
+ * decay. M0 measured a soft cloth landing in a bounded limit cycle that 2,000
+ * further steps do not move. `damping` is what reaches it, which makes this
+ * field part of the correctness argument rather than a taste control. See
+ * `ClothSystem`'s settle pass.
+ *
+ * ## `substeps` and `iterations` are budget, and the library is sized to it
+ *
+ * They are here rather than on the system because a chain wants more of both
+ * than a bedsheet does, so they are part of what "chain" means. They are also
+ * the levers that bring a garment inside the measured frame budget: 1,024
+ * particles at 2×4 costs 3.48 ms against a 2 ms target, and halving either one
+ * lands inside (`MEASUREMENTS.md` §7). Every library entry states the particle
+ * count it is sized for and which lever it took.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothDynamics {
+
+    /**
+     * How little the fabric extends, `[0, 1]`. `0` is a knit that gives a
+     * quarter of its length; `1` is a chain. Maps to the strain-limit row's
+     * allowance, not to a stiffness — see the class docblock.
+     * @type {number}
+     */
+    stretch = 0.7;
+
+    /**
+     * How strongly the fabric resists folding, `[0, 1]`. Maps to a bend row
+     * stiffness expressed as a ratio of the row's own `m/dt²`.
+     * @type {number}
+     */
+    bend = 0.2;
+
+    /**
+     * Velocity retained per step, inverted: `0` is undamped, `1` is heavily
+     * damped. Load-bearing for §7 P5 on any cloth carrying soft rows.
+     * @type {number}
+     */
+    damping = 0.15;
+
+    /**
+     * How far the cloth may leave its animated pose, `[0, 1]`. Each particle's
+     * leash radius is `slack · d_geo,i` — its own baked geodesic distance to
+     * the fixed set — so a hem gets a long leash and a waistband a short one
+     * without anybody painting a profile (§3.4). At `0` every particle is
+     * welded to its animated position.
+     * @type {number}
+     */
+    slack = 0.5;
+
+    /**
+     * Particle radius, metres. Collision offset and self-collision separation
+     * from M2 onwards; in M1 it is the length scale the velocity clamp of
+     * §7 P1 is derived from.
+     * @type {number}
+     */
+    thickness = 0.02;
+
+    /**
+     * How much of the anchor's own world motion the cloth feels, `[0, 1]`.
+     * `1` is a cape that trails a sprinting character; `0` is a cloth welded
+     * into the anchor's frame, which feels no locomotion at all. §7 P7.
+     * @type {number}
+     */
+    inertia = 1;
+
+    /**
+     * Aerodynamic coupling to the air, `[0, 1]`. §10.
+     *
+     * A **relaxation rate** toward whatever the air is doing, linearly mapped
+     * onto `[0, CLOTH_DRAG_RATE_MAX]` by `cloth_drag_response` — `0` is a cloth
+     * the air cannot reach and `1` is one with no aerodynamic memory at all,
+     * taking the air's velocity within a fixed step. The library reads silk at
+     * 0.45 (a 37 ms time constant) down to leather and chain at 0.05 (a third of
+     * a second).
+     *
+     * It only does anything where there is air: a `ClothWorld` with no wind
+     * source feels none, and what a cloth does in air that is *not* moving is
+     * `damping`'s job rather than this one.
+     * @type {number}
+     */
+    drag = 0.1;
+
+    /**
+     * Solver substeps per fixed step. More substeps means less of implicit
+     * Euler's numerical damping and a livelier drape, and a proportionally
+     * larger frame cost.
+     * @type {number}
+     */
+    substeps = 2;
+
+    /**
+     * Descent iterations per substep. More iterations converges further
+     * towards the same answer rather than changing which answer it is (§5.1).
+     * @type {number}
+     */
+    iterations = 4;
+
+    /**
+     * @see ClothDynamicsFlags
+     * @type {number}
+     */
+    flags = ClothDynamicsFlags.StrainLimit;
+
+    /**
+     * @param {number|ClothDynamicsFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+    /**
+     * Build one from a partial specification; anything left out keeps the
+     * default above.
+     *
+     * @param {object} [spec]
+     * @param {number} [spec.stretch]
+     * @param {number} [spec.bend]
+     * @param {number} [spec.damping]
+     * @param {number} [spec.slack]
+     * @param {number} [spec.thickness]
+     * @param {number} [spec.inertia]
+     * @param {number} [spec.drag]
+     * @param {number} [spec.substeps]
+     * @param {number} [spec.iterations]
+     * @param {number} [spec.flags]
+     * @returns {ClothDynamics}
+     */
+    static from(spec = {}) {
+        const r = new ClothDynamics();
+
+        r.#assign(spec);
+
+        return r;
+    }
+
+    /**
+     * @param {object} spec
+     * @private
+     */
+    #assign({
+        stretch = this.stretch,
+        bend = this.bend,
+        damping = this.damping,
+        slack = this.slack,
+        thickness = this.thickness,
+        inertia = this.inertia,
+        drag = this.drag,
+        substeps = this.substeps,
+        iterations = this.iterations,
+        flags = this.flags
+    }) {
+        assert.isNumber(stretch, 'stretch');
+        assert.isNumber(bend, 'bend');
+        assert.isNumber(damping, 'damping');
+        assert.isNumber(slack, 'slack');
+        assert.isNumber(thickness, 'thickness');
+        assert.isNumber(inertia, 'inertia');
+        assert.isNumber(drag, 'drag');
+        assert.isPositiveInteger(substeps, 'substeps');
+        assert.isPositiveInteger(iterations, 'iterations');
+        assert.isNonNegativeInteger(flags, 'flags');
+
+        this.stretch = stretch;
+        this.bend = bend;
+        this.damping = damping;
+        this.slack = slack;
+        this.thickness = thickness;
+        this.inertia = inertia;
+        this.drag = drag;
+        this.substeps = substeps;
+        this.iterations = iterations;
+        this.flags = flags;
+    }
+
+    /**
+     * A mutable copy. This is how a library entry is edited: the entries are
+     * frozen and shared, and `clone` is the one step between "assign one" and
+     * "own one".
+     *
+     * @returns {ClothDynamics}
+     */
+    clone() {
+        const r = new ClothDynamics();
+
+        r.stretch = this.stretch;
+        r.bend = this.bend;
+        r.damping = this.damping;
+        r.slack = this.slack;
+        r.thickness = this.thickness;
+        r.inertia = this.inertia;
+        r.drag = this.drag;
+        r.substeps = this.substeps;
+        r.iterations = this.iterations;
+        r.flags = this.flags;
+
+        return r;
+    }
+
+    /**
+     * @param {ClothDynamics} other
+     * @returns {boolean}
+     */
+    copy(other) {
+        this.stretch = other.stretch;
+        this.bend = other.bend;
+        this.damping = other.damping;
+        this.slack = other.slack;
+        this.thickness = other.thickness;
+        this.inertia = other.inertia;
+        this.drag = other.drag;
+        this.substeps = other.substeps;
+        this.iterations = other.iterations;
+        this.flags = other.flags;
+
+        return this;
+    }
+
+    /**
+     * @param {ClothDynamics} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+
+        if (other === null || other === undefined || other.isClothDynamics !== true) {
+            return false;
+        }
+
+        return this.stretch === other.stretch
+            && this.bend === other.bend
+            && this.damping === other.damping
+            && this.slack === other.slack
+            && this.thickness === other.thickness
+            && this.inertia === other.inertia
+            && this.drag === other.drag
+            && this.substeps === other.substeps
+            && this.iterations === other.iterations
+            && this.flags === other.flags;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.stretch),
+            computeHashFloat(this.bend),
+            computeHashFloat(this.damping),
+            computeHashFloat(this.slack),
+            computeHashFloat(this.thickness),
+            computeHashFloat(this.inertia),
+            computeHashFloat(this.drag),
+            this.substeps,
+            this.iterations,
+            this.flags
+        );
+    }
+
+    toJSON() {
+        return {
+            stretch: this.stretch,
+            bend: this.bend,
+            damping: this.damping,
+            slack: this.slack,
+            thickness: this.thickness,
+            inertia: this.inertia,
+            drag: this.drag,
+            substeps: this.substeps,
+            iterations: this.iterations,
+            flags: this.flags
+        };
+    }
+
+    /**
+     * @param {object} json
+     */
+    fromJSON(json) {
+        this.#assign(json);
+    }
+
+    toString() {
+        return `ClothDynamics${JSON.stringify(this.toJSON())}`;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ClothDynamics.prototype.isClothDynamics = true;
+
+ClothDynamics.typeName = "ClothDynamics";