@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -1,212 +1,220 @@
-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 { ClothDynamics } from "./ClothDynamics.js";
-import { ClothFlags } from "./ClothFlags.js";
-
-/**
- * # The thing that simulates
- *
- * Put it on an entity and that entity's transform subtree becomes a simulated
- * chain: a rope, a chain, a hanging sign, a mooring line, a multi-strand rig.
- *
- * ```js
- * rope_top.add(Cloth.from(ClothDynamics.ROPE));
- * ```
- *
- * **The anchor is the entity the component is on**, and nothing names anything.
- * The particle set is that entity's own transform subtree, walked through
- * `TransformAttachmentSystem#findChildrenOf` — the parent-to-children index the
- * engine already maintains. Put `Cloth` on the top link of a rope and you get
- * the rope; put it on a node with several chains under it and you get all of
- * them in **one coupled solve**, which is what makes self-collision between
- * them work when it arrives.
- *
- * Two rules keep the walk unambiguous:
- *
- * - **A nested `Cloth` claims its own subtree.** The walk stops when it meets
- *   another `Cloth`, so independent hanging parts of one prop partition
- *   naturally. The two solves are ordered by hierarchy depth, so the outer one
- *   has written the inner one's anchor before the inner one reads it.
- * - **{@link ClothExclude}** prunes a subtree from the walk, for the rig with a
- *   non-simulated attachment point in the middle of a chain.
- *
- * From M3 a `ClothRig` alongside this component redirects the particle set to a
- * skinned model instance's joints instead (§11.2). The solver is identical
- * either way; only seeding and write-back differ, which is why there is no mode
- * enum here — component presence does the job an enum would otherwise do badly.
- *
- * ## What has to be true of the subtree
- *
- * Every simulated entity needs a `TransformAttachment` naming its parent and a
- * `Transform64`; that is what "is in the transform subtree" means, and it is
- * the ordinary way anything is parented. The subtree is walked **once**, when
- * the cloth first steps. Adding or removing links afterwards needs an explicit
- * re-seed, which is the same contract `TransformAttachment#parent` already
- * carries: remove the component and add it back.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class Cloth {
-
-    /**
-     * How it behaves. Assign a frozen library entry directly and it is shared,
-     * immutable and free; `.clone()` it and you own a copy to edit. Writing a
-     * field on an owned copy takes effect on the next step — the system
-     * compares what it last saw and re-parameterises the rows when it differs,
-     * so `cloth.dynamics.slack = 0.2` works live.
-     * @type {ClothDynamics}
-     */
-    dynamics = new ClothDynamics();
-
-    /**
-     * `0` is the fully animated pose, `1` the fully simulated one.
-     *
-     * A lerp applied at write-back rather than a solver parameter, so it is
-     * free and always safe. It is the escape hatch for cinematics, for LOD, and
-     * for "turn it off for this one shot"; from M5 the culling pass drives it
-     * to blend a cloth back in without a pop.
-     * @type {number}
-     */
-    blend = 1;
-
-    /**
-     * Collision layer this cloth belongs to, `RigidBody` semantics. Read from
-     * M2, when there is something to filter.
-     * @type {number}
-     */
-    layer = 1;
-
-    /**
-     * Which `ClothCollider` layers this cloth collides against. Read from M2.
-     * @type {number}
-     */
-    mask = 0xFFFFFFFF;
-
-    /**
-     * @see ClothFlags
-     * @type {number}
-     */
-    flags = ClothFlags.None;
-
-    /**
-     * @param {number|ClothFlags} flag
-     * @returns {boolean}
-     */
-    getFlag(flag) {
-        return (this.flags & flag) === flag;
-    }
-
-    /**
-     * @param {ClothDynamics} [dynamics] assigned by reference — pass a library
-     *   entry to share it, `.clone()` first to own it
-     * @param {object} [spec]
-     * @param {number} [spec.blend]
-     * @param {number} [spec.layer]
-     * @param {number} [spec.mask]
-     * @param {number} [spec.flags]
-     * @returns {Cloth}
-     */
-    static from(dynamics = undefined, spec = {}) {
-        const r = new Cloth();
-
-        if (dynamics !== undefined) {
-            assert.ok(dynamics.isClothDynamics === true, 'dynamics must be a ClothDynamics');
-
-            r.dynamics = dynamics;
-        }
-
-        const {
-            blend = r.blend,
-            layer = r.layer,
-            mask = r.mask,
-            flags = r.flags
-        } = spec;
-
-        assert.isNumber(blend, 'blend');
-        assert.isNonNegativeInteger(layer, 'layer');
-        assert.isNonNegativeInteger(mask, 'mask');
-        assert.isNonNegativeInteger(flags, 'flags');
-
-        r.blend = blend;
-        r.layer = layer;
-        r.mask = mask;
-        r.flags = flags;
-
-        return r;
-    }
-
-    /**
-     * @param {Cloth} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        if (other === this) {
-            return true;
-        }
-
-        if (other === null || other === undefined || other.isCloth !== true) {
-            return false;
-        }
-
-        return this.dynamics.equals(other.dynamics)
-            && this.blend === other.blend
-            && this.layer === other.layer
-            && this.mask === other.mask
-            && this.flags === other.flags;
-    }
-
-    /**
-     * @returns {number}
-     */
-    hash() {
-        return combine_hash(
-            this.dynamics.hash(),
-            computeHashFloat(this.blend),
-            this.layer,
-            this.mask,
-            this.flags
-        );
-    }
-
-    toJSON() {
-        return {
-            dynamics: this.dynamics.toJSON(),
-            blend: this.blend,
-            layer: this.layer,
-            mask: this.mask,
-            flags: this.flags
-        };
-    }
-
-    /**
-     * @param {object} json
-     */
-    fromJSON({ dynamics, blend = 1, layer = 1, mask = 0xFFFFFFFF, flags = ClothFlags.None }) {
-        // Deserialising into a shared frozen library entry would be a
-        // cross-instance write, so a loaded cloth always owns its dynamics.
-        this.dynamics = new ClothDynamics();
-
-        if (dynamics !== undefined) {
-            this.dynamics.fromJSON(dynamics);
-        }
-
-        this.blend = blend;
-        this.layer = layer;
-        this.mask = mask;
-        this.flags = flags;
-    }
-
-    toString() {
-        return `Cloth${JSON.stringify(this.toJSON())}`;
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-Cloth.prototype.isCloth = true;
-
-Cloth.typeName = "Cloth";
+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 { ClothDynamics } from "./ClothDynamics.js";
+import { ClothFlags } from "./ClothFlags.js";
+
+/**
+ * # The thing that simulates
+ *
+ * Put it on an entity and that entity's transform subtree becomes a simulated
+ * chain: a rope, a chain, a hanging sign, a mooring line, a multi-strand rig.
+ *
+ * ```js
+ * rope_top.add(Cloth.from(ClothDynamics.ROPE));
+ * rope_top.add(ClothPin.from({ cloth: rope_top, particles: [0] }));
+ * ```
+ *
+ * **The entity the component is on is the cloth's frame**, and nothing names
+ * anything. The particle set is that entity and its transform subtree, walked
+ * through `TransformAttachmentSystem#findChildrenOf` — the parent-to-children
+ * index the engine already maintains — with the entity itself as particle 0.
+ * Put `Cloth` on the top link of a rope and you get the rope; put it on a node
+ * with several chains under it and you get all of them in **one coupled
+ * solve**, which is what makes self-collision between them work.
+ *
+ * **What holds it is a separate question**, answered by {@link ClothPin}s: any
+ * number of them, on any entities, holding any particles, added and removed
+ * while it runs. The rope above is held at its top by its own entity; a rope
+ * bridge is that plus a post holding its last link; a rope nothing holds falls.
+ * The frame is only what the cloth is simulated in and what §7 P7's inertia is
+ * measured against — the entity the cloth rides, which cloth reads and never
+ * writes.
+ *
+ * Two rules keep the walk unambiguous:
+ *
+ * - **A nested `Cloth` claims its own subtree.** The walk stops when it meets
+ *   another `Cloth`, so independent hanging parts of one prop partition
+ *   naturally, each read one fixed step after the cloth above it wrote it.
+ * - **{@link ClothExclude}** prunes a subtree from the walk, for the rig with a
+ *   non-simulated attachment point in the middle of a chain.
+ *
+ * From M3 a `ClothRig` alongside this component redirects the particle set to a
+ * skinned model instance's joints instead (§11.2). The solver is identical
+ * either way; only seeding and write-back differ, which is why there is no mode
+ * enum here — component presence does the job an enum would otherwise do badly.
+ *
+ * ## What has to be true of the subtree
+ *
+ * Every simulated entity needs a `TransformAttachment` naming its parent and a
+ * `Transform64`; that is what "is in the transform subtree" means, and it is
+ * the ordinary way anything is parented. The subtree is walked **once**, when
+ * the cloth first steps. Adding or removing links afterwards needs an explicit
+ * re-seed, which is the same contract `TransformAttachment#parent` already
+ * carries: remove the component and add it back.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Cloth {
+
+    /**
+     * How it behaves. Assign a frozen library entry directly and it is shared,
+     * immutable and free; `.clone()` it and you own a copy to edit. Writing a
+     * field on an owned copy takes effect on the next step — the system
+     * compares what it last saw and re-parameterises the rows when it differs,
+     * so `cloth.dynamics.slack = 0.2` works live.
+     * @type {ClothDynamics}
+     */
+    dynamics = new ClothDynamics();
+
+    /**
+     * `0` is the fully animated pose, `1` the fully simulated one.
+     *
+     * A lerp applied at write-back rather than a solver parameter, so it is
+     * free and always safe. It is the escape hatch for cinematics, for LOD, and
+     * for "turn it off for this one shot"; from M5 the culling pass drives it
+     * to blend a cloth back in without a pop.
+     * @type {number}
+     */
+    blend = 1;
+
+    /**
+     * Collision layer this cloth belongs to, `RigidBody` semantics. Read from
+     * M2, when there is something to filter.
+     * @type {number}
+     */
+    layer = 1;
+
+    /**
+     * Which `ClothCollider` layers this cloth collides against. Read from M2.
+     * @type {number}
+     */
+    mask = 0xFFFFFFFF;
+
+    /**
+     * @see ClothFlags
+     * @type {number}
+     */
+    flags = ClothFlags.None;
+
+    /**
+     * @param {number|ClothFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+    /**
+     * @param {ClothDynamics} [dynamics] assigned by reference — pass a library
+     *   entry to share it, `.clone()` first to own it
+     * @param {object} [spec]
+     * @param {number} [spec.blend]
+     * @param {number} [spec.layer]
+     * @param {number} [spec.mask]
+     * @param {number} [spec.flags]
+     * @returns {Cloth}
+     */
+    static from(dynamics = undefined, spec = {}) {
+        const r = new Cloth();
+
+        if (dynamics !== undefined) {
+            assert.ok(dynamics.isClothDynamics === true, 'dynamics must be a ClothDynamics');
+
+            r.dynamics = dynamics;
+        }
+
+        const {
+            blend = r.blend,
+            layer = r.layer,
+            mask = r.mask,
+            flags = r.flags
+        } = spec;
+
+        assert.isNumber(blend, 'blend');
+        assert.isNonNegativeInteger(layer, 'layer');
+        assert.isNonNegativeInteger(mask, 'mask');
+        assert.isNonNegativeInteger(flags, 'flags');
+
+        r.blend = blend;
+        r.layer = layer;
+        r.mask = mask;
+        r.flags = flags;
+
+        return r;
+    }
+
+    /**
+     * @param {Cloth} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+
+        if (other === null || other === undefined || other.isCloth !== true) {
+            return false;
+        }
+
+        return this.dynamics.equals(other.dynamics)
+            && this.blend === other.blend
+            && this.layer === other.layer
+            && this.mask === other.mask
+            && this.flags === other.flags;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return combine_hash(
+            this.dynamics.hash(),
+            computeHashFloat(this.blend),
+            this.layer,
+            this.mask,
+            this.flags
+        );
+    }
+
+    toJSON() {
+        return {
+            dynamics: this.dynamics.toJSON(),
+            blend: this.blend,
+            layer: this.layer,
+            mask: this.mask,
+            flags: this.flags
+        };
+    }
+
+    /**
+     * @param {object} json
+     */
+    fromJSON({ dynamics, blend = 1, layer = 1, mask = 0xFFFFFFFF, flags = ClothFlags.None }) {
+        // Deserialising into a shared frozen library entry would be a
+        // cross-instance write, so a loaded cloth always owns its dynamics.
+        this.dynamics = new ClothDynamics();
+
+        if (dynamics !== undefined) {
+            this.dynamics.fromJSON(dynamics);
+        }
+
+        this.blend = blend;
+        this.layer = layer;
+        this.mask = mask;
+        this.flags = flags;
+    }
+
+    toString() {
+        return `Cloth${JSON.stringify(this.toJSON())}`;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Cloth.prototype.isCloth = true;
+
+Cloth.typeName = "Cloth";

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

@@ -29,6 +29,12 @@ export const ClothDynamicsFlags = {
      * all and the row makes it marginally *worse*. `CLOTH_SILK`, `CLOTH_COTTON`
      * and `CLOTH_HAIR` set it; nothing else does. `MEASUREMENTS.md` §33.
      *
+     * Those figures are at the stiffness M4 shipped. At today's
+     * `CLOTH_SELF_RATIO`, the row removes 63% to 71% of the folding sheet's
+     * crossings, and in exchange a cloth resting on itself (a pile, a drape
+     * whose edges fold under, a skirt after a twirl) comes to rest instead of
+     * jittering for ever. `MEASUREMENTS.md` §65.
+     *
      * What it buys is **fewer crossings while the cloth moves**, not a cleaner
      * cloth at rest: a sheet that settles takes its tangles out with it either
      * way. And it is one tier of two — `MEASUREMENTS.md` §32 measures the limit

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

@@ -0,0 +1,91 @@
+/**
+ * # One {@link ClothPin}, as the cloth sees it
+ *
+ * The pin is the author's statement — this entity holds these particles of that
+ * cloth. This is what the statement turns into: where each held particle sits
+ * relative to its holder, and where the holder is this step. {@link ClothWorld}
+ * keeps one per pin for as long as the pin exists, **outside** the seeded
+ * instance, because the offsets are the hold's and not the `ClothState`'s: a
+ * re-seed builds a new state and must not move what is being held.
+ *
+ * A struct: {@link ClothWorld} and `cloth_holds.js` are its behaviour.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothHold {
+    /**
+     * The entity carrying the {@link ClothPin}.
+     * @type {number}
+     */
+    holder: number;
+    /**
+     * @type {ClothPin|null}
+     */
+    pin: ClothPin | null;
+    /**
+     * Each held particle relative to the holder, in the holder's own frame, 3 per
+     * entry of the pin's particle list. Taken once, when the hold begins.
+     * @type {Float64Array}
+     */
+    offset: Float64Array;
+    /**
+     * Whether {@link offset} has been taken. Until it has, the hold holds
+     * nothing: its holder has not been found yet, or its cloth has not seeded.
+     * @type {boolean}
+     */
+    captured: boolean;
+    /**
+     * The holder's rotation in the cloth's frame when the hold began, `[x, y, z, w]`
+     * — what the animated pose measures the holder's turn from.
+     * @type {Float64Array}
+     */
+    rotation_at_hold: Float64Array;
+    /**
+     * The holder's pose in the cloth's frame this step, `[tx, ty, tz, qx, qy, qz, qw]`.
+     * @type {Float64Array}
+     */
+    pose: Float64Array;
+    /**
+     * {@link pose} as of the previous step — what the teleport test measures a
+     * jump against.
+     * @type {Float64Array}
+     */
+    pose_previous: Float64Array;
+    /**
+     * The holder's world pose this step, and the previous step's — what the
+     * wake test compares, because a holder that has not moved is a world that
+     * has not changed whatever the frame did.
+     * @type {Float64Array}
+     */
+    world: Float64Array;
+    /**
+     * @type {Float64Array}
+     */
+    world_previous: Float64Array;
+    /**
+     * Whether {@link pose} and {@link world} hold this step's answer. A holder
+     * whose hierarchy is not complete yet has none, and its particles stay where
+     * the last answer put them.
+     * @type {boolean}
+     */
+    valid: boolean;
+    /**
+     * Whether {@link pose_previous} and {@link world_previous} mean anything.
+     * @type {boolean}
+     */
+    has_previous: boolean;
+    /**
+     * Whether the cloth refused this hold — a holder that the cloth itself
+     * moves, or a particle it does not have — in which case it holds nothing.
+     * @type {boolean}
+     */
+    refused: boolean;
+    /**
+     * Whether the refusal has been said. Once: a hold that does not fit will not
+     * start fitting, and a warning a step is a log nobody reads.
+     * @type {boolean}
+     */
+    reported: boolean;
+}
+//# sourceMappingURL=ClothHold.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ClothHold.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothHold.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;IAEI;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,KAFU,WAAS,IAAI,CAEZ;IAEX;;;;OAIG;IACH,QAFU,YAAY,CAEO;IAE7B;;;;OAIG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;OAIG;IACH,kBAFU,YAAY,CAE4B;IAElD;;;OAGG;IACH,MAFU,YAAY,CAEyB;IAE/C;;;;OAIG;IACH,eAFU,YAAY,CAEkC;IAExD;;;;;OAKG;IACH,OAFU,YAAY,CAE0B;IAEhD;;OAEG;IACH,gBAFU,YAAY,CAEmC;IAEzD;;;;;OAKG;IACH,OAFU,OAAO,CAEH;IAEd;;;OAGG;IACH,cAFU,OAAO,CAEI;IAErB;;;;OAIG;IACH,SAFU,OAAO,CAED;IAEhB;;;;OAIG;IACH,UAFU,OAAO,CAEA;CACpB"}

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

@@ -0,0 +1,103 @@
+/**
+ * # One {@link ClothPin}, as the cloth sees it
+ *
+ * The pin is the author's statement — this entity holds these particles of that
+ * cloth. This is what the statement turns into: where each held particle sits
+ * relative to its holder, and where the holder is this step. {@link ClothWorld}
+ * keeps one per pin for as long as the pin exists, **outside** the seeded
+ * instance, because the offsets are the hold's and not the `ClothState`'s: a
+ * re-seed builds a new state and must not move what is being held.
+ *
+ * A struct: {@link ClothWorld} and `cloth_holds.js` are its behaviour.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothHold {
+
+    /**
+     * The entity carrying the {@link ClothPin}.
+     * @type {number}
+     */
+    holder = -1;
+
+    /**
+     * @type {ClothPin|null}
+     */
+    pin = null;
+
+    /**
+     * Each held particle relative to the holder, in the holder's own frame, 3 per
+     * entry of the pin's particle list. Taken once, when the hold begins.
+     * @type {Float64Array}
+     */
+    offset = new Float64Array(0);
+
+    /**
+     * Whether {@link offset} has been taken. Until it has, the hold holds
+     * nothing: its holder has not been found yet, or its cloth has not seeded.
+     * @type {boolean}
+     */
+    captured = false;
+
+    /**
+     * The holder's rotation in the cloth's frame when the hold began, `[x, y, z, w]`
+     * — what the animated pose measures the holder's turn from.
+     * @type {Float64Array}
+     */
+    rotation_at_hold = new Float64Array([0, 0, 0, 1]);
+
+    /**
+     * The holder's pose in the cloth's frame this step, `[tx, ty, tz, qx, qy, qz, qw]`.
+     * @type {Float64Array}
+     */
+    pose = new Float64Array([0, 0, 0, 0, 0, 0, 1]);
+
+    /**
+     * {@link pose} as of the previous step — what the teleport test measures a
+     * jump against.
+     * @type {Float64Array}
+     */
+    pose_previous = new Float64Array([0, 0, 0, 0, 0, 0, 1]);
+
+    /**
+     * The holder's world pose this step, and the previous step's — what the
+     * wake test compares, because a holder that has not moved is a world that
+     * has not changed whatever the frame did.
+     * @type {Float64Array}
+     */
+    world = new Float64Array([0, 0, 0, 0, 0, 0, 1]);
+
+    /**
+     * @type {Float64Array}
+     */
+    world_previous = new Float64Array([0, 0, 0, 0, 0, 0, 1]);
+
+    /**
+     * Whether {@link pose} and {@link world} hold this step's answer. A holder
+     * whose hierarchy is not complete yet has none, and its particles stay where
+     * the last answer put them.
+     * @type {boolean}
+     */
+    valid = false;
+
+    /**
+     * Whether {@link pose_previous} and {@link world_previous} mean anything.
+     * @type {boolean}
+     */
+    has_previous = false;
+
+    /**
+     * Whether the cloth refused this hold — a holder that the cloth itself
+     * moves, or a particle it does not have — in which case it holds nothing.
+     * @type {boolean}
+     */
+    refused = false;
+
+    /**
+     * Whether the refusal has been said. Once: a hold that does not fit will not
+     * start fitting, and a warning a step is a log nobody reads.
+     * @type {boolean}
+     */
+    reported = false;
+}