@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -0,0 +1,61 @@
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { ClothPin } from "./ClothPin.js";
+
+/**
+ * # Binary serialization for {@link ClothPin}
+ *
+ * The cloth's entity, then the particles. A rope is saved as its links and its
+ * `Cloth`; without its pin it would load as a rope nothing holds, and fall.
+ *
+ * The cloth is written as a raw entity id, the way `JointSerializationAdapter`
+ * writes its two: a scene's entities keep their ids across a save. A pin on an
+ * entity that is not saved — a bone a model spawned, which is transient — is
+ * not saved with it, and is put back by whatever spawns the model, as its
+ * `ClothRig` is.
+ *
+ * ## Version 0, and no upgrader
+ *
+ * A first version has no predecessor stream to upgrade from.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothPinSerializationAdapter extends BinaryClassSerializationAdapter {
+
+    klass = ClothPin;
+    version = 0;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ClothPin} value
+     */
+    serialize(buffer, value) {
+        buffer.writeUint32(value.cloth);
+
+        const particles = value.particles;
+
+        buffer.writeUintVar(particles.length);
+
+        for (let i = 0; i < particles.length; i++) {
+            buffer.writeUintVar(particles[i]);
+        }
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ClothPin} value
+     */
+    deserialize(buffer, value) {
+        value.cloth = buffer.readUint32();
+
+        const count = buffer.readUintVar();
+
+        const particles = new Int32Array(count);
+
+        for (let i = 0; i < count; i++) {
+            particles[i] = buffer.readUintVar();
+        }
+
+        value.particles = particles;
+    }
+}

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

@@ -2,15 +2,15 @@
  * # 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).
+ * transform subtree and becomes the **joints of a skin**: the `MeshSkin` on the
+ * entity {@link skin} names. 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));
+ * character.add(ClothRig.from(cape_proxy, cape_mesh));
  * ```
  *
  * ## Why there are two cases at all
@@ -30,21 +30,26 @@
  * 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.
+ * way. What serialises is the proxy's identity and the skin's entity.
+ *
+ * ## The skin is an entity's, and the rig names the entity
+ *
+ * The joints a proxy indexes are a skin's, and a skin is a `MeshSkin` on the mesh
+ * it deforms. The rig sits on the entity whose clips drive the bones the garment
+ * hangs from — the character — and names the mesh. Whatever spawned the model, or
+ * built the mesh in code, knows which entity that is; nothing has to be asked
+ * which model the character is showing.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export class ClothRig {
     /**
-     * @param {ClothProxy} [proxy]
-     * @param {object} [spec]
-     * @param {number} [spec.skin]
+     * @param {ClothProxy} proxy
+     * @param {number} skin the entity carrying the `MeshSkin` the proxy indexes
      * @returns {ClothRig}
      */
-    static from(proxy?: ClothProxy, spec?: {
-        skin?: number;
-    }): ClothRig;
+    static from(proxy: ClothProxy, 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.
@@ -52,11 +57,12 @@ export class ClothRig {
      */
     proxy: ClothProxy | null;
     /**
-     * Which of the instance's skins the proxy's joint indices are into.
+     * The entity whose `MeshSkin` the proxy's joint indices are into: the mesh
+     * the garment is, or one of the meshes bound to the same skeleton the same way.
      *
-     * 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.
+     * -1 until it is known — a model spawned after the rig went on its
+     * character — and while it is, or while the entity carries no skin yet, the
+     * rig waits, as it waits for a model still loading.
      * @type {number}
      */
     skin: number;

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

@@ -1 +1 @@
-{"version":3,"file":"ClothRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;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"}
+{"version":3,"file":"ClothRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAoBI;;;;OAIG;IACH,qCAHW,MAAM,GACJ,QAAQ,CAYpB;IAjCD;;;;OAIG;IACH,OAFU,aAAW,IAAI,CAEZ;IAEb;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEN;IAmBV;;;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

@@ -5,15 +5,15 @@ 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).
+ * transform subtree and becomes the **joints of a skin**: the `MeshSkin` on the
+ * entity {@link skin} names. 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));
+ * character.add(ClothRig.from(cape_proxy, cape_mesh));
  * ```
  *
  * ## Why there are two cases at all
@@ -33,7 +33,15 @@ import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
  * 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.
+ * way. What serialises is the proxy's identity and the skin's entity.
+ *
+ * ## The skin is an entity's, and the rig names the entity
+ *
+ * The joints a proxy indexes are a skin's, and a skin is a `MeshSkin` on the mesh
+ * it deforms. The rig sits on the entity whose clips drive the bones the garment
+ * hangs from — the character — and names the mesh. Whatever spawned the model, or
+ * built the mesh in code, knows which entity that is; nothing has to be asked
+ * which model the character is showing.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -48,34 +56,28 @@ export class ClothRig {
     proxy = null;
 
     /**
-     * Which of the instance's skins the proxy's joint indices are into.
+     * The entity whose `MeshSkin` the proxy's joint indices are into: the mesh
+     * the garment is, or one of the meshes bound to the same skeleton the same way.
      *
-     * 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.
+     * -1 until it is known — a model spawned after the rig went on its
+     * character — and while it is, or while the entity carries no skin yet, the
+     * rig waits, as it waits for a model still loading.
      * @type {number}
      */
-    skin = 0;
+    skin = -1;
 
     /**
-     * @param {ClothProxy} [proxy]
-     * @param {object} [spec]
-     * @param {number} [spec.skin]
+     * @param {ClothProxy} proxy
+     * @param {number} skin the entity carrying the `MeshSkin` the proxy indexes
      * @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;
-
+    static from(proxy, skin) {
+        assert.ok(proxy !== undefined && proxy !== null && proxy.isClothProxy === true, 'proxy must be a ClothProxy');
         assert.isNonNegativeInteger(skin, 'skin');
 
+        const r = new ClothRig();
+
+        r.proxy = proxy;
         r.skin = skin;
 
         return r;
@@ -121,7 +123,7 @@ export class ClothRig {
     /**
      * @param {object} json
      */
-    fromJSON({ skin = 0 }) {
+    fromJSON({ skin = -1 }) {
         this.skin = skin;
     }
 

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

@@ -48,7 +48,7 @@
 export class ClothSystem extends System<any> {
     constructor();
     dependencies: (typeof Transform64 | typeof Cloth)[];
-    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof ClothCollider> | ResourceAccessSpecification<typeof Cloth> | ResourceAccessSpecification<typeof ClothExclude> | ResourceAccessSpecification<typeof ClothRig>)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof GPUStateAuthority> | ResourceAccessSpecification<typeof ParentEntity> | ResourceAccessSpecification<typeof ClothCollider> | ResourceAccessSpecification<typeof Cloth> | ResourceAccessSpecification<typeof ClothExclude> | ResourceAccessSpecification<typeof ClothRig> | ResourceAccessSpecification<typeof ClothPin>)[];
     /**
      * @type {ClothWorld}
      */
@@ -100,19 +100,6 @@ export class ClothSystem extends System<any> {
      * @returns {ClothInstance[]}
      */
     get instances(): ClothInstance[];
-    /**
-     * @param {{instance_of: function(number): (PrefabInstance|null)}|null} value
-     */
-    set models(value: {
-        instance_of: (arg0: number) => (PrefabInstance | null);
-    });
-    /**
-     * Where a skinned model instance comes from — see {@link ClothWorld#models}.
-     * @returns {{instance_of: function(number): (PrefabInstance|null)}|null}
-     */
-    get models(): {
-        instance_of: (arg0: number) => (PrefabInstance | null);
-    };
     /**
      * @param {EntityManager} entityManager
      * @returns {Promise<void>}
@@ -157,14 +144,25 @@ export class ClothSystem extends System<any> {
      * @returns {ClothInstance|undefined}
      */
     instanceOf(entity: number): ClothInstance | undefined;
+    /**
+     * Which particle of a cloth an entity is, for a {@link ClothPin} that has
+     * the entity in hand — see {@link ClothWorld#particle_of}.
+     * @param {number} cloth the entity carrying the `Cloth`
+     * @param {number} entity
+     * @returns {number} the particle, or `−1`
+     */
+    particle_of(cloth: number, entity: number): number;
 }
 import { System } from "../../../ecs/System.js";
 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 { GPUStateAuthority } from "../../../ecs/gpu/GPUStateAuthority.js";
+import { ParentEntity } from "../../../ecs/parent/ParentEntity.js";
 import { ClothCollider } from "./ClothCollider.js";
 import { ClothExclude } from "./ClothExclude.js";
 import { ClothRig } from "./ClothRig.js";
+import { ClothPin } from "./ClothPin.js";
 import { ClothWorld } from "./ClothWorld.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":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;;;;;;OAYG;IACH,iBAAyD;IAEzD;;;;;;OAMG;IACH,qBAAkB;IAUlB;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAkBD;;OAEG;IACH,qBAEC;IAdD;;;;OAIG;IACH,gBAEC;IASD;;;;OAIG;IACH,iCAEC;IAUD;;OAEG;IACH;4BAToC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;OAWjE;IAbD;;;OAGG;IACH;4BAFoC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;MAIjE;IASD;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAIzB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;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;CA2EJ;uBAzSsB,wBAAwB;4BAInB,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;8BAInC,oBAAoB;6BACrB,mBAAmB;yBACvB,eAAe;2BACb,iBAAiB"}
+{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;;IAEI,oDAAoC;IAEpC,2dAYE;IAEF;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;;;;;;OAYG;IACH,iBAAyD;IAEzD;;;;;;OAMG;IACH,qBAAkB;IAUlB;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAkBD;;OAEG;IACH,qBAEC;IAdD;;;;OAIG;IACH,gBAEC;IASD;;;;OAIG;IACH,iCAEC;IAGD;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAIzB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;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;;;;;;OAMG;IACH,mBAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;CA2EJ;uBA9SsB,wBAAwB;4BAInB,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;kCAQ/B,uCAAuC;6BAC5C,qCAAqC;8BALpC,oBAAoB;6BACrB,mBAAmB;yBAEvB,eAAe;yBADf,eAAe;2BAIb,iBAAiB"}

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

@@ -9,7 +9,10 @@ import { CLOTH_STEP_PARAM_STRIDE, cloth_step_instance } from "../solver/cloth_st
 import { Cloth } from "./Cloth.js";
 import { ClothCollider } from "./ClothCollider.js";
 import { ClothExclude } from "./ClothExclude.js";
+import { ClothPin } from "./ClothPin.js";
 import { ClothRig } from "./ClothRig.js";
+import { GPUStateAuthority } from "../../../ecs/gpu/GPUStateAuthority.js";
+import { ParentEntity } from "../../../ecs/parent/ParentEntity.js";
 import { ClothWorld } from "./ClothWorld.js";
 
 /**
@@ -69,7 +72,12 @@ export class ClothSystem extends System {
         ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read | ResourceAccessKind.Write),
         ResourceAccessSpecification.from(ClothExclude, ResourceAccessKind.Read),
         ResourceAccessSpecification.from(ClothCollider, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(ClothRig, ResourceAccessKind.Read)
+        ResourceAccessSpecification.from(ClothRig, ResourceAccessKind.Read),
+        // What holds a cloth, and — to evaluate a holder a clip drives — the
+        // model it belongs to and who composes its transform.
+        ResourceAccessSpecification.from(ClothPin, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(ParentEntity, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(GPUStateAuthority, ResourceAccessKind.Read)
     ];
 
     /**
@@ -141,20 +149,6 @@ export class ClothSystem extends System {
         return this.world.instances;
     }
 
-    /**
-     * Where a skinned model instance comes from — see {@link ClothWorld#models}.
-     * @returns {{instance_of: function(number): (PrefabInstance|null)}|null}
-     */
-    get models() {
-        return this.world.models;
-    }
-
-    /**
-     * @param {{instance_of: function(number): (PrefabInstance|null)}|null} value
-     */
-    set models(value) {
-        this.world.models = value;
-    }
 
     /**
      * @param {EntityManager} entityManager
@@ -224,6 +218,17 @@ export class ClothSystem extends System {
         return this.world.instanceOf(entity);
     }
 
+    /**
+     * Which particle of a cloth an entity is, for a {@link ClothPin} that has
+     * the entity in hand — see {@link ClothWorld#particle_of}.
+     * @param {number} cloth the entity carrying the `Cloth`
+     * @param {number} entity
+     * @returns {number} the particle, or `−1`
+     */
+    particle_of(cloth, entity) {
+        return this.world.particle_of(cloth, entity);
+    }
+
     /**
      * Advance every cloth, then step every cloth, then finish every cloth.
      *

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

@@ -2,12 +2,9 @@
  * # Every cloth in a scene, and everything a step needs that is not arithmetic
  *
  * One {@link ClothInstance} per {@link Cloth} component, stepped at the fixed
- * rate. Per step, per cloth: move the local frame with the anchor, point the
- * leash rows at where they measure from, gather the colliders that could touch
- * it, step, and put the result back on the subtree. The animated pose the
- * leashes are measured against is not recomposed per step — in the entity path
- * it is constant in the anchor's own frame, and `cloth_seed_subtree.js` bakes
- * it.
+ * rate. Per step, per cloth: take where its holders are, move the local frame,
+ * point the leash rows at what they measure from, gather the colliders that
+ * could touch it, step, and put the result back on the subtree.
  *
  * ## Why this is not a `System`
  *
@@ -42,11 +39,11 @@
  *
  * ## The local frame and the inertia model — §7 P7
  *
- * Particles live in the anchor's own frame. When the anchor moves, the cloth is
+ * Particles live in the cloth's frame. When the frame moves, the cloth is
  * asked how much of that motion it would like to feel:
  * `ClothDynamics#inertia = 1` keeps every particle's **world** position and
  * velocity, so a cape trails a sprinting character; `0` keeps their **local**
- * ones, so the cloth rides the anchor as though it were standing still. The
+ * ones, so the cloth rides the frame as though it were standing still. The
  * blend between the two is a lerp in the local frame, which is all the frame
  * change is.
  *
@@ -68,14 +65,32 @@
  * step's drag response is zero, `cloth_step` takes the uniform-gravity path,
  * and a scene produces the bytes M5 measured.
  *
+ * ## Holds
+ *
+ * A {@link ClothPin} on any entity holds the particles it names. This world
+ * keeps one {@link ClothHold} per pin, by the cloth entity it names, for as long
+ * as the pin exists — **outside** the seeded instance, because the offsets a
+ * hold takes when it begins are the hold's and must survive a re-seed. A pin is
+ * only ever *noticed* by the observer; everything it changes in a cloth's state
+ * is written in {@link advance}, which is the one window in which the main
+ * thread owns that state under both systems.
+ *
+ * Each step, before anything else, every holder's pose is taken — read off its
+ * `Transform64` when the CPU owns it, evaluated exactly when a clip does — and
+ * expressed in the cloth's frame. `cloth_holds.js` turns those poses into
+ * where the held particles go, the animated pose hung from them, and the leash
+ * centres.
+ *
  * ## Teleport — §7 P6
  *
- * Anchor motion past a threshold is not locomotion and is not treated as any
- * amount of it. `ClothFlags.TeleportKeep` carries the shape across, which in a
- * local frame is literally doing nothing; the default re-seeds at the animated
- * pose with zero velocity and opens a stabilisation window in which the
- * velocity limit ramps back from nothing, so the first steps after a reset
- * cannot produce a whip.
+ * Frame motion past a threshold is not locomotion and is not treated as any
+ * amount of it, and neither is a holder jumping that far in the frame — a ship
+ * the rope is tied to, moved across the map. `ClothFlags.TeleportKeep` carries
+ * the shape across: for the frame that is literally doing nothing, and for a
+ * holder it is that holder's own jump applied to what hangs from it. The default
+ * re-seeds at the animated pose with zero velocity and opens a stabilisation
+ * window in which the velocity limit ramps back from nothing, so the first steps
+ * after a reset cannot produce a whip.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -100,25 +115,6 @@ export class ClothWorld {
      * @type {ClothInstance[]}
      */
     instances: ClothInstance[];
-    /**
-     * Where a skinned model instance comes from. Anything that answers
-     * `instance_of(entity)` with a `PrefabInstance` — skins whose joints
-     * are entities — 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): (PrefabInstance|null)}|null}
-     */
-    models: {
-        instance_of: (arg0: number) => (PrefabInstance | null);
-    } | null;
     /**
      * @type {EntityManager|null}
      */
@@ -217,6 +213,14 @@ export class ClothWorld {
      * @private
      */
     private __rig_observer;
+    /**
+     * Every {@link ClothPin} in the dataset, as the hold it makes. A pin is
+     * noticed here and nowhere else; what it does to a cloth is written in
+     * {@link advance}.
+     * @type {EntityObserver}
+     * @private
+     */
+    private __pin_observer;
     /**
      * Resolve the systems a cloth world reads. Called from the owning system's
      * `startup`.
@@ -265,7 +269,8 @@ export class ClothWorld {
      */
     reseed(entity: number): ClothInstance | undefined;
     /**
-     * Wake a sleeping cloth. Anchor motion and a `ClothDynamics` change do this
+     * Wake a sleeping cloth. Frame motion, a holder moving or a hold changing,
+     * and a `ClothDynamics` change do this
      * on their own; a caller that has changed the world in some way the cloth
      * cannot see — M6's wind, for one — says so here.
      *
@@ -278,6 +283,20 @@ export class ClothWorld {
      * @returns {ClothInstance|undefined}
      */
     instanceOf(entity: number): ClothInstance | undefined;
+    /**
+     * Which particle of a cloth an entity is: a link of a subtree cloth, or a
+     * joint of a rigged one — the number a {@link ClothPin} names it by.
+     *
+     * For code that has the entity rather than the number, which is what a hand
+     * closing on a rope has. It answers once the cloth has seeded, which is its
+     * first step.
+     *
+     * @param {number} cloth the entity carrying the `Cloth`
+     * @param {number} entity
+     * @returns {number} the particle, or `−1` when the entity is not one of the
+     *   cloth's, or the cloth has not seeded yet
+     */
+    particle_of(cloth: number, entity: number): number;
     /**
      * Everything that happens once per tick rather than once per cloth.
      *
@@ -307,8 +326,9 @@ export class ClothWorld {
     finish(instance: ClothInstance, ecd: EntityComponentDataset): void;
     /**
      * 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
-     * the leash rows measure from, and the colliders within reach.
+     * the step will run on: whatever the frame and the holders did, where the
+     * held particles go, where the leash rows measure from, and the colliders
+     * within reach.
      *
      * @param {ClothInstance} instance
      * @param {number} dt seconds
@@ -324,4 +344,5 @@ import { ClothInstance } from "./ClothInstance.js";
 import { TransformAttachmentSystem } from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
 import { ClothColliderSystem } from "./ClothColliderSystem.js";
 import { Cloth } from "./Cloth.js";
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
 //# sourceMappingURL=ClothWorld.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ClothWorld.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorld.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH;IAEI;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;;;;;;;;;OAYG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;OAEG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;OAEG;IACH,aAFU,yBAAyB,GAAC,IAAI,CAErB;IAEnB;;;;;;OAMG;IACH,WAFU,mBAAmB,GAAC,IAAI,CAEjB;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,oBAAkB,IAAI,CAEpB;IAEZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,oBAAwB;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAKE;IAEF;;;;;OAKG;IACH,2CAiBC;IAED;;;;;OAKG;IACH,YALW,KAAK,kCAEL,MAAM,GACJ,aAAa,CAczB;IAED;;;;;;;;OAQG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CA0BnC;IAyED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAuBnC;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;IAED;;;;;OAKG;IACH,uCAFW,MAAM,QAgBhB;IAED;;;;;;;;;OASG;IACH,wBANW,aAAa,mCAEb,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;OAOG;IACH,iBAJW,aAAa,gCAEX,IAAI,CA4ChB;IAwFD;;;;;;;;;;;OAWG;IACH,kBAPW,aAAa,MACb,MAAM,UACN,YAAY,UACZ,MAAM,GACJ,OAAO,CA0PnB;;CA8EJ;8BArgC6B,oBAAoB;0CAjB3C,gEAAgE;oCAcnC,0BAA0B;sBA4BxC,YAAY"}
+{"version":3,"file":"ClothWorld.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorld.js"],"names":[],"mappings":"AAmEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AACH;IAEI;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;;;;;;;;;OAYG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;OAEG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;OAEG;IACH,aAFU,yBAAyB,GAAC,IAAI,CAErB;IAEnB;;;;;;OAMG;IACH,WAFU,mBAAmB,GAAC,IAAI,CAEjB;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,oBAAkB,IAAI,CAEpB;IAEZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,oBAAwB;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAKE;IAEF;;;;;;OAMG;IACH,uBAKE;IA0BF;;;;;OAKG;IACH,2CAaC;IAED;;;;;OAKG;IACH,YALW,KAAK,aACL,WAAW,UACX,MAAM,GACJ,aAAa,CAczB;IAED;;;;;;;;OAQG;IACH,iDAFa,IAAI,CAehB;IAED;;;OAGG;IACH,iDAFa,IAAI,CAOhB;IA+YD;;;OAGG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CA0BnC;IAyED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAuBnC;IAED;;;;;;;;OAQG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;IAED;;;;;;;;;;;;OAYG;IACH,mBALW,MAAM,UACN,MAAM,GACJ,MAAM,CAmBlB;IAED;;;;;OAKG;IACH,uCAFW,MAAM,QAgBhB;IAED;;;;;;;;;OASG;IACH,wBANW,aAAa,mCAEb,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;OAOG;IACH,iBAJW,aAAa,gCAEX,IAAI,CA4ChB;IAyFD;;;;;;;;;;;;OAYG;IACH,kBAPW,aAAa,MACb,MAAM,UACN,YAAY,UACZ,MAAM,GACJ,OAAO,CAuUnB;;CA8GJ;8BAhlD6B,oBAAoB;0CAnB3C,gEAAgE;oCAenC,0BAA0B;sBA+BxC,YAAY;4BAzC3B,uCAAuC"}