@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -0,0 +1,212 @@
+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";

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

@@ -0,0 +1,126 @@
+/**
+ * # The marker that opts a collider into cloth
+ *
+ * Put this beside an existing `(Collider, Transform64)` and cloth collides
+ * against it. That is the whole of the component's job, and it is the third
+ * instance of a pattern the engine already has twice: `AcousticBody` opts a
+ * collider into the acoustic simulation and carries an `AcousticMaterial`,
+ * `FluidObstacle` opts a collider into the fluid simulation and carries an
+ * inflation radius. This should read as a sibling of those two rather than as a
+ * new invention.
+ *
+ * Everything not here is read from components the entity already has: geometry
+ * and friction from `Collider`, pose from `Transform64`.
+ *
+ * ## No `RigidBody` required
+ *
+ * A deliberate divergence from `FluidObstacle`, which requires one because it
+ * needs a wall velocity. Cloth's colliders are overwhelmingly character bones —
+ * ordinary entities in a `TransformAttachment` hierarchy — and making each of
+ * them a physics body to be seen by cloth would tax the common case. Collider
+ * velocity is derived from the pose delta between fixed steps, which the index
+ * caches anyway for swept collision (§8.2). A world prop that *does* carry a
+ * `RigidBody` adds a `ClothCollider` the same way and lands in the same index;
+ * the two cases are not distinguished.
+ *
+ * ## Layer and mask, which §3.5 did not have
+ *
+ * §3.5 gives this component three fields and says layer filtering comes "from
+ * the `Cloth` side". It cannot: `Cloth#mask` is a mask *of collider layers*,
+ * and with no `RigidBody` required there is nowhere else for a collider's layer
+ * to live. So the pair is here, with `RigidBody`'s own semantics — a cloth and
+ * a collider interact when each is in the other's mask — which is what
+ * `Cloth.js` already says it means by "`RigidBody` semantics".
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothCollider {
+    /**
+     * @param {object} [spec]
+     * @param {number} [spec.inflation]
+     * @param {number} [spec.friction_scale]
+     * @param {number} [spec.layer]
+     * @param {number} [spec.mask]
+     * @param {number} [spec.flags]
+     * @returns {ClothCollider}
+     */
+    static from(spec?: {
+        inflation?: number;
+        friction_scale?: number;
+        layer?: number;
+        mask?: number;
+        flags?: number;
+    }): ClothCollider;
+    /**
+     * Extra thickness in metres, on top of `ClothDynamics#thickness`.
+     *
+     * The contact row holds cloth at `thickness + inflation` from the surface,
+     * so this is how a garment is kept off a body it would otherwise graze —
+     * the same idea as `FluidObstacle#inflation`, and useful for the same
+     * reason: a collider that approximates a limb loosely wants the cloth held
+     * a little further out than the approximation.
+     * @type {number}
+     */
+    inflation: number;
+    /**
+     * Multiplies the entity's `Collider#friction` before it is combined with
+     * the cloth's own. `0` makes the surface frictionless to cloth without
+     * making it frictionless to rigid bodies, which is the case this exists
+     * for: a character's collision capsules are tuned for footing, and a cape
+     * that grips them the same way reads as glued.
+     * @type {number}
+     */
+    friction_scale: number;
+    /**
+     * Collision layer this collider belongs to, `RigidBody` semantics.
+     * @type {number}
+     */
+    layer: number;
+    /**
+     * Which `Cloth` layers this collider acts on.
+     * @type {number}
+     */
+    mask: number;
+    /**
+     * @see ClothColliderFlags
+     * @type {number}
+     */
+    flags: number;
+    /**
+     * @param {number|ClothColliderFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag: number | ClothColliderFlags): boolean;
+    /**
+     * @param {ClothCollider} other
+     * @returns {boolean}
+     */
+    equals(other: ClothCollider): boolean;
+    /**
+     * @returns {number}
+     */
+    hash(): number;
+    toJSON(): {
+        inflation: number;
+        friction_scale: number;
+        layer: number;
+        mask: number;
+        flags: number;
+    };
+    /**
+     * @param {object} json
+     */
+    fromJSON({ inflation, friction_scale, layer, mask, flags }: object): void;
+    toString(): string;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isClothCollider: boolean;
+}
+export namespace ClothCollider {
+    let typeName: string;
+}
+import { ClothColliderFlags } from "./ClothColliderFlags.js";
+//# sourceMappingURL=ClothCollider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ClothCollider.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothCollider.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IA0CI;;;;;;;;OAQG;IACH;QAPyB,SAAS,GAAvB,MAAM;QACQ,cAAc,GAA5B,MAAM;QACQ,KAAK,GAAnB,MAAM;QACQ,IAAI,GAAlB,MAAM;QACQ,KAAK,GAAnB,MAAM;QACJ,aAAa,CA0BzB;IAzED;;;;;;;;;OASG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEgB;IAqChC;;;OAGG;IACH,cAHW,MAAM,GAAC,kBAAkB,GACvB,OAAO,CAInB;IAED;;;OAGG;IACH,cAHW,aAAa,GACX,OAAO,CAgBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAUlB;IAED;;;;;;MAQC;IAED;;OAEG;IACH,4DAFW,MAAM,QAchB;IAED,mBAEC;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC;;;;mCA3LkC,yBAAyB"}

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

@@ -0,0 +1,199 @@
+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 { ClothColliderFlags } from "./ClothColliderFlags.js";
+
+/**
+ * # The marker that opts a collider into cloth
+ *
+ * Put this beside an existing `(Collider, Transform64)` and cloth collides
+ * against it. That is the whole of the component's job, and it is the third
+ * instance of a pattern the engine already has twice: `AcousticBody` opts a
+ * collider into the acoustic simulation and carries an `AcousticMaterial`,
+ * `FluidObstacle` opts a collider into the fluid simulation and carries an
+ * inflation radius. This should read as a sibling of those two rather than as a
+ * new invention.
+ *
+ * Everything not here is read from components the entity already has: geometry
+ * and friction from `Collider`, pose from `Transform64`.
+ *
+ * ## No `RigidBody` required
+ *
+ * A deliberate divergence from `FluidObstacle`, which requires one because it
+ * needs a wall velocity. Cloth's colliders are overwhelmingly character bones —
+ * ordinary entities in a `TransformAttachment` hierarchy — and making each of
+ * them a physics body to be seen by cloth would tax the common case. Collider
+ * velocity is derived from the pose delta between fixed steps, which the index
+ * caches anyway for swept collision (§8.2). A world prop that *does* carry a
+ * `RigidBody` adds a `ClothCollider` the same way and lands in the same index;
+ * the two cases are not distinguished.
+ *
+ * ## Layer and mask, which §3.5 did not have
+ *
+ * §3.5 gives this component three fields and says layer filtering comes "from
+ * the `Cloth` side". It cannot: `Cloth#mask` is a mask *of collider layers*,
+ * and with no `RigidBody` required there is nowhere else for a collider's layer
+ * to live. So the pair is here, with `RigidBody`'s own semantics — a cloth and
+ * a collider interact when each is in the other's mask — which is what
+ * `Cloth.js` already says it means by "`RigidBody` semantics".
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothCollider {
+
+    /**
+     * Extra thickness in metres, on top of `ClothDynamics#thickness`.
+     *
+     * The contact row holds cloth at `thickness + inflation` from the surface,
+     * so this is how a garment is kept off a body it would otherwise graze —
+     * the same idea as `FluidObstacle#inflation`, and useful for the same
+     * reason: a collider that approximates a limb loosely wants the cloth held
+     * a little further out than the approximation.
+     * @type {number}
+     */
+    inflation = 0;
+
+    /**
+     * Multiplies the entity's `Collider#friction` before it is combined with
+     * the cloth's own. `0` makes the surface frictionless to cloth without
+     * making it frictionless to rigid bodies, which is the case this exists
+     * for: a character's collision capsules are tuned for footing, and a cape
+     * that grips them the same way reads as glued.
+     * @type {number}
+     */
+    friction_scale = 1;
+
+    /**
+     * Collision layer this collider belongs to, `RigidBody` semantics.
+     * @type {number}
+     */
+    layer = 1;
+
+    /**
+     * Which `Cloth` layers this collider acts on.
+     * @type {number}
+     */
+    mask = 0xFFFFFFFF;
+
+    /**
+     * @see ClothColliderFlags
+     * @type {number}
+     */
+    flags = ClothColliderFlags.None;
+
+    /**
+     * @param {object} [spec]
+     * @param {number} [spec.inflation]
+     * @param {number} [spec.friction_scale]
+     * @param {number} [spec.layer]
+     * @param {number} [spec.mask]
+     * @param {number} [spec.flags]
+     * @returns {ClothCollider}
+     */
+    static from(spec = {}) {
+        const r = new ClothCollider();
+
+        const {
+            inflation = r.inflation,
+            friction_scale = r.friction_scale,
+            layer = r.layer,
+            mask = r.mask,
+            flags = r.flags
+        } = spec;
+
+        assert.isNumber(inflation, 'inflation');
+        assert.isNumber(friction_scale, 'friction_scale');
+        assert.isNonNegativeInteger(layer, 'layer');
+        assert.isNonNegativeInteger(mask, 'mask');
+        assert.isNonNegativeInteger(flags, 'flags');
+
+        r.inflation = inflation;
+        r.friction_scale = friction_scale;
+        r.layer = layer;
+        r.mask = mask;
+        r.flags = flags;
+
+        return r;
+    }
+
+    /**
+     * @param {number|ClothColliderFlags} flag
+     * @returns {boolean}
+     */
+    getFlag(flag) {
+        return (this.flags & flag) === flag;
+    }
+
+    /**
+     * @param {ClothCollider} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+
+        if (other === null || other === undefined || other.isClothCollider !== true) {
+            return false;
+        }
+
+        return this.inflation === other.inflation
+            && this.friction_scale === other.friction_scale
+            && this.layer === other.layer
+            && this.mask === other.mask
+            && this.flags === other.flags;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return combine_hash(
+            computeHashFloat(this.inflation),
+            computeHashFloat(this.friction_scale),
+            this.layer,
+            this.mask,
+            this.flags
+        );
+    }
+
+    toJSON() {
+        return {
+            inflation: this.inflation,
+            friction_scale: this.friction_scale,
+            layer: this.layer,
+            mask: this.mask,
+            flags: this.flags
+        };
+    }
+
+    /**
+     * @param {object} json
+     */
+    fromJSON({
+        inflation = 0,
+        friction_scale = 1,
+        layer = 1,
+        mask = 0xFFFFFFFF,
+        flags = ClothColliderFlags.None
+    }) {
+        this.inflation = inflation;
+        this.friction_scale = friction_scale;
+        this.layer = layer;
+        this.mask = mask;
+        this.flags = flags;
+    }
+
+    toString() {
+        return `ClothCollider${JSON.stringify(this.toJSON())}`;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ClothCollider.prototype.isClothCollider = true;
+
+ClothCollider.typeName = "ClothCollider";

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

@@ -0,0 +1,9 @@
+/**
+ * *
+ */
+export type ClothColliderFlags = number;
+export namespace ClothColliderFlags {
+    let None: number;
+    let Static: number;
+}
+//# sourceMappingURL=ClothColliderFlags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ClothColliderFlags.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothColliderFlags.js"],"names":[],"mappings":";;;iCAIU,MAAM"}

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

@@ -0,0 +1,32 @@
+/**
+ * Switches on {@link ClothCollider}.
+ *
+ * @readonly
+ * @enum {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const ClothColliderFlags = {
+    None: 0,
+
+    /**
+     * The collider never moves, so it is placed once and never swept.
+     *
+     * §8.2's swept collision interpolates each collider's pose between the
+     * previous step's and this one's, and rolling one pose into the other and
+     * refitting the swept bounds is the per-collider, per-step cost of that. A
+     * ground plane, a wall, a rock pays it for nothing, and a large static
+     * collider pays the most because its bounds are the biggest thing the
+     * broadphase tests against.
+     *
+     * Set this and the pose is written once, at link, into **both** slots, so
+     * the sweep degenerates to the pose it already had. Move the entity anyway
+     * and the cloth will not notice: that is the trade, and it is why this is
+     * an author's assertion rather than something derived from a pose that
+     * happens not to have changed yet.
+     */
+    Static: 1
+};
+
+Object.freeze(ClothColliderFlags);