@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -0,0 +1,95 @@
+/**
+ * # Simulate a skinned model's joints instead of the entity subtree
+ *
+ * Add this beside a {@link Cloth} and the particle set stops being the entity's
+ * transform subtree and becomes the **joints of the skinned model the entity is
+ * showing**. That is the whole of the component's job, and there is no mode
+ * enum anywhere: `Cloth` alone simulates the subtree, `Cloth` + `ClothRig`
+ * simulates a rig, and component presence does the work a discriminator field
+ * would do badly (§3.1).
+ *
+ * ```js
+ * character.add(Cloth.from(CLOTH_SILK));
+ * character.add(ClothRig.from(cape_proxy));
+ * ```
+ *
+ * ## Why there are two cases at all
+ *
+ * Because the engine has two hierarchies and that is a decision rather than an
+ * accident. `shade_node_to_entity_composition` expands a loaded model into
+ * entities and gives a `ShadedGeometry` to every node that draws — except a
+ * skinned one, which contributes its transform and its name and no geometry,
+ * because its vertices deform against a skeleton the renderer owns and the GPU
+ * poses. Making those joints entities is a design this program does not do
+ * (D47). A rope prop is entities all the way down; a character's cape is not,
+ * and never will be.
+ *
+ * ## A proxy object, not a path
+ *
+ * {@link proxy} holds a built {@link ClothProxy}, following the convention the
+ * engine already uses for a component that points at a built, shared, immutable
+ * asset: `Collider#shape` holds an `AbstractShape3D` and is documented as *not*
+ * serialised because shapes are shared assets the pipeline wires up;
+ * `ParticleEffect` holds a `ParticleLayout` and a `ParticleProgram` the same
+ * way. What serialises is the proxy's identity and the skin ordinal.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothRig {
+    /**
+     * @param {ClothProxy} [proxy]
+     * @param {object} [spec]
+     * @param {number} [spec.skin]
+     * @returns {ClothRig}
+     */
+    static from(proxy?: ClothProxy, spec?: {
+        skin?: number;
+    }): ClothRig;
+    /**
+     * The built proxy: which joints, how they connect, and their bind pose.
+     * Shared and immutable — see the class docblock for the convention.
+     * @type {ClothProxy|null}
+     */
+    proxy: ClothProxy | null;
+    /**
+     * Which of the instance's skins the proxy's joint indices are into.
+     *
+     * A model with a body and a separate cape mesh has two skins, and a proxy
+     * built against one of them addresses nothing in the other. The ordinal is
+     * the asset's own and it is what a build writes down beside the indices.
+     * @type {number}
+     */
+    skin: number;
+    /**
+     * @param {ClothRig} other
+     * @returns {boolean}
+     */
+    equals(other: ClothRig): boolean;
+    /**
+     * @returns {number}
+     */
+    hash(): number;
+    /**
+     * The proxy is **not** serialised, for the same reason `Collider#shape` is
+     * not: it is a shared, immutable asset the pipeline wires up, and a copy per
+     * placement would be a copy of a build artefact.
+     */
+    toJSON(): {
+        skin: number;
+    };
+    /**
+     * @param {object} json
+     */
+    fromJSON({ skin }: object): void;
+    toString(): string;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isClothRig: boolean;
+}
+export namespace ClothRig {
+    let typeName: string;
+}
+//# sourceMappingURL=ClothRig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ClothRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;IAmBI;;;;;OAKG;IACH;QAHyB,IAAI,GAAlB,MAAM;QACJ,QAAQ,CAkBpB;IAvCD;;;;OAIG;IACH,OAFU,aAAW,IAAI,CAEZ;IAEb;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;IA0BT;;;OAGG;IACH,cAHW,QAAQ,GACN,OAAO,CAenB;IAED;;OAEG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH;;MAIC;IAED;;OAEG;IACH,mBAFW,MAAM,QAIhB;IAED,mBAEC;IAGL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B"}

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

@@ -0,0 +1,140 @@
+import { assert } from "../../../../core/assert.js";
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+
+/**
+ * # Simulate a skinned model's joints instead of the entity subtree
+ *
+ * Add this beside a {@link Cloth} and the particle set stops being the entity's
+ * transform subtree and becomes the **joints of the skinned model the entity is
+ * showing**. That is the whole of the component's job, and there is no mode
+ * enum anywhere: `Cloth` alone simulates the subtree, `Cloth` + `ClothRig`
+ * simulates a rig, and component presence does the work a discriminator field
+ * would do badly (§3.1).
+ *
+ * ```js
+ * character.add(Cloth.from(CLOTH_SILK));
+ * character.add(ClothRig.from(cape_proxy));
+ * ```
+ *
+ * ## Why there are two cases at all
+ *
+ * Because the engine has two hierarchies and that is a decision rather than an
+ * accident. `shade_node_to_entity_composition` expands a loaded model into
+ * entities and gives a `ShadedGeometry` to every node that draws — except a
+ * skinned one, which contributes its transform and its name and no geometry,
+ * because its vertices deform against a skeleton the renderer owns and the GPU
+ * poses. Making those joints entities is a design this program does not do
+ * (D47). A rope prop is entities all the way down; a character's cape is not,
+ * and never will be.
+ *
+ * ## A proxy object, not a path
+ *
+ * {@link proxy} holds a built {@link ClothProxy}, following the convention the
+ * engine already uses for a component that points at a built, shared, immutable
+ * asset: `Collider#shape` holds an `AbstractShape3D` and is documented as *not*
+ * serialised because shapes are shared assets the pipeline wires up;
+ * `ParticleEffect` holds a `ParticleLayout` and a `ParticleProgram` the same
+ * way. What serialises is the proxy's identity and the skin ordinal.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothRig {
+
+    /**
+     * The built proxy: which joints, how they connect, and their bind pose.
+     * Shared and immutable — see the class docblock for the convention.
+     * @type {ClothProxy|null}
+     */
+    proxy = null;
+
+    /**
+     * Which of the instance's skins the proxy's joint indices are into.
+     *
+     * A model with a body and a separate cape mesh has two skins, and a proxy
+     * built against one of them addresses nothing in the other. The ordinal is
+     * the asset's own and it is what a build writes down beside the indices.
+     * @type {number}
+     */
+    skin = 0;
+
+    /**
+     * @param {ClothProxy} [proxy]
+     * @param {object} [spec]
+     * @param {number} [spec.skin]
+     * @returns {ClothRig}
+     */
+    static from(proxy = undefined, spec = {}) {
+        const r = new ClothRig();
+
+        if (proxy !== undefined) {
+            assert.ok(proxy.isClothProxy === true, 'proxy must be a ClothProxy');
+
+            r.proxy = proxy;
+        }
+
+        const { skin = r.skin } = spec;
+
+        assert.isNonNegativeInteger(skin, 'skin');
+
+        r.skin = skin;
+
+        return r;
+    }
+
+    /**
+     * @param {ClothRig} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+
+        if (other === null || other === undefined || other.isClothRig !== true) {
+            return false;
+        }
+
+        // Proxies are shared immutable assets, so identity is the comparison —
+        // the same one `Collider#shape` gets when the pipeline hands out one
+        // instance per asset.
+        return this.proxy === other.proxy && this.skin === other.skin;
+    }
+
+    /**
+     * @returns {number}
+     */
+    hash() {
+        return hash_mix2(this.proxy === null ? 0 : 1, this.skin);
+    }
+
+    /**
+     * The proxy is **not** serialised, for the same reason `Collider#shape` is
+     * not: it is a shared, immutable asset the pipeline wires up, and a copy per
+     * placement would be a copy of a build artefact.
+     */
+    toJSON() {
+        return {
+            skin: this.skin
+        };
+    }
+
+    /**
+     * @param {object} json
+     */
+    fromJSON({ skin = 0 }) {
+        this.skin = skin;
+    }
+
+    toString() {
+        return `ClothRig{skin: ${this.skin}, proxy: ${this.proxy === null ? 'null' : this.proxy.name}}`;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ClothRig.prototype.isClothRig = true;
+
+ClothRig.typeName = "ClothRig";

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

@@ -66,7 +66,7 @@
 export class ClothSystem extends System<any> {
     constructor();
     dependencies: (typeof Transform64 | typeof Cloth)[];
-    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof Cloth> | ResourceAccessSpecification<typeof ClothExclude>)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof ClothCollider> | ResourceAccessSpecification<typeof Cloth> | ResourceAccessSpecification<typeof ClothExclude> | ResourceAccessSpecification<typeof ClothRig>)[];
     /**
      * World gravity, m/s². Rotated into each cloth's local frame per step.
      * @type {Float64Array}
@@ -88,6 +88,33 @@ export class ClothSystem extends System<any> {
      * @private
      */
     private __attachments;
+    /**
+     * Where a skinned model instance comes from. Anything that answers
+     * `instance_of(entity)` with a `SceneBundleInstance` will do, and
+     * {@link MeshSystem} is what does in a running engine.
+     *
+     * Public and assignable because a garment's joints are a *rendering*
+     * structure and `MeshSystem` needs a graphics engine, a scene and a loader
+     * to exist — so a spec that wants joints without a renderer sets this
+     * instead, and gets exactly the interface the system uses.
+     *
+     * `null` means no rig can seed, which is the same additive shape the
+     * collider index has: a scene without one gets M1's cloth rather than an
+     * error.
+     * @type {{instance_of: function(number): (SceneBundleInstance|null)}|null}
+     */
+    models: {
+        instance_of: (arg0: number) => (SceneBundleInstance | null);
+    } | null;
+    /**
+     * The collider index's owner, or `null` when the manager has none — in
+     * which case cloth simply does not collide, which is exactly M1's
+     * behaviour and is what makes the collision layer additive rather than a
+     * new requirement on every scene.
+     * @type {ClothColliderSystem|null}
+     * @private
+     */
+    private __colliders;
     /**
      * @type {boolean}
      * @private
@@ -144,6 +171,8 @@ import { Transform64 } from "../../../ecs/transform/Transform64.js";
 import { Cloth } from "./Cloth.js";
 import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
 import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
+import { ClothCollider } from "./ClothCollider.js";
 import { ClothExclude } from "./ClothExclude.js";
+import { ClothRig } from "./ClothRig.js";
 import { ClothInstance } from "./ClothInstance.js";
 //# sourceMappingURL=ClothSystem.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;;IAEI,oDAAoC;IAEpC,8NAKE;IAEF;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;OAIG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;OAGG;IACH,oBAAwB;IAExB;;;OAGG;IACH,sBAAqB;IAErB;;;OAGG;IACH,sBAAsB;IAEtB;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CASzB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAahB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAgBhB;IAED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,IAAI,CAahB;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;;CA0PJ;uBA5esB,wBAAwB;4BAWxC,uCAAuC;sBAExB,YAAY;4CAdU,uDAAuD;oCAI5F,0DAA0D;6BAWpC,mBAAmB;8BAElB,oBAAoB"}
+{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;OAIG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;OAGG;IACH,oBAAwB;IAExB;;;OAGG;IACH,sBAAqB;IAErB;;;;;;;;;;;;;;OAcG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,sBAAoB,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAE5D;IAEd;;;;;;;OAOG;IACH,oBAAmB;IAEnB;;;OAGG;IACH,sBAAsB;IAEtB;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAahB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAgBhB;IAED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,IAAI,CAahB;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;;CAibJ;uBA5tBsB,wBAAwB;4BAWxC,uCAAuC;sBAYxB,YAAY;4CAxBU,uDAAuD;oCAI5F,0DAA0D;8BAqBnC,oBAAoB;6BAErB,mBAAmB;yBAIvB,eAAe;8BADV,oBAAoB"}