@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -1,24 +1,35 @@
 import { assert } from "../../../../core/assert.js";
-import { quat3_multiply_array } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
-import { quat3_nlerp_array } from "../../../../core/geom/3d/quaternion/quat3_nlerp.js";
+import { array_range_equal_strict } from "../../../../core/collection/array/array_range_equal_strict.js";
+import { pose3_apply_point_array } from "../../../../core/geom/3d/pose/pose3_apply_point_array.js";
+import { pose3_to_local_array } from "../../../../core/geom/3d/pose/pose3_to_local_array.js";
+import { quat3_clamp_angle_array } from "../../../../core/geom/3d/quaternion/quat3_clamp_angle_array.js";
+import {
+    quat3_multiply_conjugate_right_array
+} from "../../../../core/geom/3d/quaternion/quat3_multiply_conjugate_right_array.js";
 import { v3_quaternion_apply_array } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
 import { v3_quaternion_apply_inverse_array } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
 import { EntityObserver } from "../../../ecs/EntityObserver.js";
+import { EventType } from "../../../ecs/EventType.js";
+import { GPUStateAuthorityFlags } from "../../../ecs/gpu/GPUStateAuthorityFlags.js";
+import { gpu_authority_has } from "../../../ecs/gpu/gpu_authority_has.js";
+import { parent_entity_model_of } from "../../../ecs/parent/parent_entity_model_of.js";
 import {
-    TransformAttachment
-} from "../../../ecs/transform-attachment/TransformAttachment.js";
+    transform_attachment_parent_of
+} from "../../../ecs/transform-attachment/transform_attachment_parent_of.js";
 import {
     TransformAttachmentSystem
 } from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
 import {
     TRANSFORM64_ROTATION_OFFSET,
-    TRANSFORM64_TRANSLATION_OFFSET
+    TRANSFORM64_TRANSLATION_OFFSET,
+    Transform64
 } from "../../../ecs/transform/Transform64.js";
 import { t64_evaluate_world } from "../../../ecs/transform/t64_evaluate_world.js";
+import { t64_read_pose_array } from "../../../ecs/transform/t64_read_pose_array.js";
 import {
     collect_entity_playbacks
 } from "../../../graphics3/pose/collect_entity_playbacks.js";
-import { MeshSystem } from "../../../graphics3/MeshSystem.js";
+import { MeshSkin } from "../../../graphics/ecs/mesh-v2/MeshSkin.js";
 import { CLOTH_SELF_RADIUS_MAX_RATIO, CLOTH_SELF_RADIUS_MIN_RATIO } from "../solver/cloth_solver_constants.js";
 import { cloth_air_changed, cloth_sample_air } from "../wind/cloth_sample_air.js";
 import { ClothStepParam } from "../solver/cloth_step_instance.js";
@@ -26,11 +37,14 @@ import { ClothStepResult } from "../solver/ClothState.js";
 import { ClothColliderSystem } from "./ClothColliderSystem.js";
 import { ClothDynamicsFlags } from "./ClothDynamicsFlags.js";
 import { ClothFlags } from "./ClothFlags.js";
+import { ClothHold } from "./ClothHold.js";
 import { ClothInstance } from "./ClothInstance.js";
+import { ClothPin } from "./ClothPin.js";
+import { cloth_apply_holds, cloth_capture_hold, cloth_hold_step } from "./cloth_holds.js";
 import { ClothRig } from "./ClothRig.js";
 import {
-    CLOTH_ANCHOR_ROTATION_LIMIT,
-    CLOTH_ANCHOR_TRAVEL_REACH,
+    CLOTH_FRAME_ROTATION_LIMIT,
+    CLOTH_FRAME_TRAVEL_REACH,
     CLOTH_SLEEP_DISPLACEMENT_RATIO,
     CLOTH_SLEEP_SPEED_RATIO,
     CLOTH_SLEEP_STEPS,
@@ -61,12 +75,9 @@ import { cloth_write_back_rig } from "./cloth_write_back_rig.js";
  * # 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`
  *
@@ -101,11 +112,11 @@ import { cloth_write_back_rig } from "./cloth_write_back_rig.js";
  *
  * ## 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.
  *
@@ -127,14 +138,32 @@ import { cloth_write_back_rig } from "./cloth_write_back_rig.js";
  * 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
@@ -162,24 +191,6 @@ export class ClothWorld {
      */
     instances = [];
 
-    /**
-     * 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 = null;
-
     /**
      * @type {EntityManager|null}
      */
@@ -292,6 +303,44 @@ export class ClothWorld {
         this
     );
 
+    /**
+     * 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
+     */
+    __pin_observer = new EntityObserver(
+        [ClothPin],
+        (pin, entity) => this.#pin_added(pin, entity),
+        (pin, entity) => this.#pin_removed(pin, entity),
+        this
+    );
+
+    /**
+     * Holds by the cloth entity they name, each list ascending by holder — so a
+     * particle two pins name goes to the lower holder, every time.
+     * @type {Map<number, ClothHold[]>}
+     * @private
+     */
+    #holds = new Map();
+
+    /**
+     * Bumped for a cloth entity whenever a hold on it appears or goes;
+     * {@link ClothInstance#holds_version} is what an instance last applied.
+     * @type {Map<number, number>}
+     * @private
+     */
+    #hold_versions = new Map();
+
+    /**
+     * The dataset the observers are attached to, for the one thing a pin needs
+     * done outside a step: going when its cloth's entity does.
+     * @type {EntityComponentDataset|null}
+     * @private
+     */
+    #dataset = null;
+
     /**
      * Resolve the systems a cloth world reads. Called from the owning system's
      * `startup`.
@@ -311,10 +360,6 @@ export class ClothWorld {
         // Optional by design. A scene with no ClothColliderSystem gets cloth
         // that does not collide, rather than cloth that throws.
         this.colliders = entityManager.getSystem(ClothColliderSystem) ?? null;
-
-        if (this.models === null) {
-            this.models = entityManager.getSystem(MeshSystem) ?? null;
-        }
     }
 
     /**
@@ -347,7 +392,18 @@ export class ClothWorld {
      * @returns {void}
      */
     attach_dataset(dataset) {
+        this.#dataset = dataset;
+
         dataset.addObserver(this.__rig_observer, true);
+
+        // A cloth simulates fine with nothing holding it, so a scene need not
+        // have registered the component to have cloth in it.
+        dataset.registerComponentType(ClothPin);
+
+        // nor a skin, to have cloth that is not a rig
+        dataset.registerComponentType(MeshSkin);
+
+        dataset.addObserver(this.__pin_observer, true);
     }
 
     /**
@@ -356,6 +412,378 @@ export class ClothWorld {
      */
     detach_dataset(dataset) {
         dataset.removeObserver(this.__rig_observer, false);
+        dataset.removeObserver(this.__pin_observer, false);
+
+        this.#dataset = null;
+    }
+
+    /**
+     * @param {ClothPin} pin
+     * @param {number} holder
+     * @private
+     */
+    #pin_added(pin, holder) {
+        const cloth = pin.cloth;
+
+        let list = this.#holds.get(cloth);
+
+        if (list === undefined) {
+            list = [];
+
+            this.#holds.set(cloth, list);
+
+            // A pin names its cloth's entity, and an entity id is reused: when
+            // that entity goes, the pins naming it go with it, rather than
+            // waiting to hold whatever is spawned under the same id next. The
+            // same contract `IKGoal` has with its target.
+            const dataset = this.#dataset;
+
+            if (dataset !== null && dataset.entityExists(cloth)) {
+                dataset.addEntityEventListener(cloth, EventType.EntityRemoved, this.#cloth_entity_removed, this);
+            }
+        }
+
+        const hold = new ClothHold();
+
+        hold.holder = holder;
+        hold.pin = pin;
+
+        let at = list.length;
+
+        while (at > 0 && list[at - 1].holder > holder) {
+            at--;
+        }
+
+        list.splice(at, 0, hold);
+
+        this.#bump(cloth);
+    }
+
+    /**
+     * @param {ClothPin} pin
+     * @param {number} holder
+     * @private
+     */
+    #pin_removed(pin, holder) {
+        const cloth = pin.cloth;
+
+        const list = this.#holds.get(cloth);
+
+        if (list === undefined) {
+            return;
+        }
+
+        for (let i = 0; i < list.length; i++) {
+            if (list[i].holder === holder) {
+                list.splice(i, 1);
+
+                break;
+            }
+        }
+
+        if (list.length === 0) {
+            this.#holds.delete(cloth);
+
+            const dataset = this.#dataset;
+
+            if (dataset !== null && dataset.entityExists(cloth)) {
+                dataset.removeEntityEventListener(cloth, EventType.EntityRemoved, this.#cloth_entity_removed, this);
+            }
+        }
+
+        this.#bump(cloth);
+    }
+
+    /**
+     * A cloth's entity has gone: take every pin naming it off its holder.
+     *
+     * @param {*} event
+     * @param {number} cloth
+     * @private
+     */
+    #cloth_entity_removed(event, cloth) {
+        const list = this.#holds.get(cloth);
+
+        const dataset = this.#dataset;
+
+        if (list === undefined || dataset === null) {
+            return;
+        }
+
+        // Removing a pin edits the list, so walk a copy.
+        const holders = list.map(hold => hold.holder);
+
+        for (let i = 0; i < holders.length; i++) {
+            if (dataset.entityExists(holders[i])) {
+                dataset.removeComponentFromEntity(holders[i], ClothPin);
+            }
+        }
+    }
+
+    /**
+     * @param {number} cloth
+     * @private
+     */
+    #bump(cloth) {
+        this.#hold_versions.set(cloth, (this.#hold_versions.get(cloth) ?? 0) + 1);
+
+        const instance = this.__by_entity.get(cloth);
+
+        if (instance !== undefined) {
+            instance.asleep = false;
+            instance.still_steps = 0;
+        }
+    }
+
+    /**
+     * The particles a cloth has and the entities they are, enough to say
+     * whether a holder hangs from one of them.
+     *
+     * A holder that cloth itself moves — a link of the same rope, or anything
+     * hanging below one — would chase its own write-back one step behind, so it
+     * is refused once, by name, and holds nothing. The cloth's own entity is
+     * allowed: for a subtree it is the frame, which cloth reads and never writes.
+     *
+     * @param {ClothInstance} instance
+     * @param {ClothHold} hold
+     * @returns {string} empty when the hold may hold, otherwise why not
+     * @private
+     */
+    #refusal(instance, hold) {
+        const ecd = this.entityManager.dataset;
+
+        for (let entity = hold.holder, depth = 0; entity >= 0 && depth < 256; depth++) {
+            if (this.#is_output(instance, entity)) {
+                return `entity ${hold.holder} holds cloth ${instance.entity} and hangs from entity ${entity}, which that cloth moves`;
+            }
+
+            entity = transform_attachment_parent_of(ecd, entity);
+        }
+
+        const particles = hold.pin.particles;
+
+        for (let k = 0; k < particles.length; k++) {
+            if (particles[k] >= instance.node_count) {
+                return `entity ${hold.holder} holds particle ${particles[k]} of cloth ${instance.entity}, which has ${instance.node_count}`;
+            }
+        }
+
+        return "";
+    }
+
+    /**
+     * @param {ClothInstance} instance
+     * @param {number} entity
+     * @returns {boolean} whether cloth writes this entity's pose
+     * @private
+     */
+    #is_output(instance, entity) {
+        const output = instance.node_output;
+        const entities = instance.rig === null ? instance.node_entity : instance.node_joint;
+
+        for (let node = 0; node < instance.node_count; node++) {
+            if (output[node] !== 0 && entities[node] === entity) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Bring an instance's holds up to date with the pins that name it: pick up a
+     * changed set, take the offsets of any hold whose holder has just been found,
+     * and re-derive whatever holding decides. Nothing here runs unless something
+     * changed.
+     *
+     * @param {ClothInstance} instance
+     * @param {Float64Array} frame_translation the frame the particle positions are in
+     * @param {Float64Array} frame_rotation
+     * @returns {boolean} whether anything about what holds the cloth changed
+     * @private
+     */
+    #refresh_holds(instance, frame_translation, frame_rotation) {
+        let changed = false;
+
+        const holds = instance.holds;
+
+        for (let h = 0; h < holds.length; h++) {
+            const hold = holds[h];
+
+            if (!hold.captured && hold.valid && !hold.refused) {
+                cloth_capture_hold(instance, hold, frame_translation, frame_rotation);
+
+                changed = true;
+            }
+        }
+
+        if (changed || instance.holds_applied !== instance.holds_version) {
+            cloth_apply_holds(instance);
+
+            instance.holds_applied = instance.holds_version;
+
+            // A different set of holds is a different cloth to rest; the window
+            // that was open measured the old one.
+            instance.still_steps = 0;
+            instance.sleep_reference = null;
+
+            changed = true;
+        }
+
+        return changed;
+    }
+
+    /**
+     * Pick up a changed set of pins: the instance's holds become the registry's,
+     * each one admitted or refused.
+     *
+     * @param {ClothInstance} instance
+     * @private
+     */
+    #sync_holds(instance) {
+        const version = this.#hold_versions.get(instance.entity) ?? 0;
+
+        if (instance.holds_version === version) {
+            return;
+        }
+
+        const list = this.#holds.get(instance.entity);
+
+        instance.holds = list === undefined ? [] : list.slice();
+        instance.holds_version = version;
+
+        for (let h = 0; h < instance.holds.length; h++) {
+            const hold = instance.holds[h];
+
+            const refusal = this.#refusal(instance, hold);
+
+            hold.refused = refusal !== "";
+
+            if (hold.refused && !hold.reported) {
+                hold.reported = true;
+
+                console.warn(`ClothSystem: ${refusal}`);
+            }
+        }
+    }
+
+    /**
+     * Where every holder is this step: in the world, and in the cloth's frame.
+     *
+     * @param {ClothInstance} instance
+     * @param {Float64Array} frame_translation this step's frame
+     * @param {Float64Array} frame_rotation
+     * @returns {boolean} whether any holder moved, appeared or vanished since
+     *   the last step
+     * @private
+     */
+    #evaluate_holds(instance, frame_translation, frame_rotation) {
+        let moved = false;
+
+        const holds = instance.holds;
+
+        for (let h = 0; h < holds.length; h++) {
+            const hold = holds[h];
+
+            const was_valid = hold.valid;
+
+            hold.valid = !hold.refused && this.#holder_world(hold.holder, hold.world);
+
+            if (!hold.valid) {
+                moved = moved || was_valid;
+
+                continue;
+            }
+
+            const world = hold.world;
+            const pose = hold.pose;
+
+            // in the frame: q_f⁻¹ · (t − t_f), q_f⁻¹ ⊗ q
+            pose3_to_local_array(pose, 0, pose, 3, frame_translation, 0, frame_rotation, 0, world, 0, world, 3);
+
+            if (!hold.has_previous) {
+                moved = true;
+
+                continue;
+            }
+
+            if (!array_range_equal_strict(world, 0, hold.world_previous, 0, 7)) {
+                moved = true;
+            }
+        }
+
+        return moved;
+    }
+
+    /**
+     * A holder's world pose, `[tx, ty, tz, qx, qy, qz, qw]`.
+     *
+     * Read off its `Transform64` when the CPU owns that, which is every prop and
+     * every hand a script moves. A transform the GPU composes — a bone a clip
+     * drives — holds the rest pose under wherever the CPU last composed it, so
+     * it is evaluated exactly instead, under the clips of every model on its
+     * chain: a pole in a hand belongs to one model and hangs from another's
+     * bones, and evaluating it under only its own would put it where the hand
+     * was in the bind pose.
+     *
+     * @param {number} entity
+     * @param {Float64Array} out
+     * @returns {boolean} false when the entity has no pose to give yet — gone,
+     *   or hanging from a parent that has no transform
+     * @private
+     */
+    #holder_world(entity, out) {
+        const ecd = this.entityManager.dataset;
+
+        if (!ecd.entityExists(entity)) {
+            return false;
+        }
+
+        const transform = ecd.getComponent(entity, Transform64);
+
+        if (transform === undefined) {
+            return false;
+        }
+
+        let source = transform;
+
+        if (gpu_authority_has(ecd, entity, GPUStateAuthorityFlags.Transform64)) {
+            const playbacks = PLAYBACKS;
+
+            playbacks.length = 0;
+
+            // every model on the chain, each once; and a chain that is not
+            // complete yet is not one to evaluate
+            MODELS.length = 0;
+
+            for (let e = entity, depth = 0; e >= 0 && depth < 256; depth++) {
+                if (!ecd.entityExists(e) || ecd.getComponent(e, Transform64) === undefined) {
+                    playbacks.length = 0;
+
+                    return false;
+                }
+
+                const model = parent_entity_model_of(ecd, e);
+
+                if (MODELS.indexOf(model) === -1) {
+                    MODELS.push(model);
+
+                    collect_entity_playbacks(playbacks, this.entityManager, model);
+                }
+
+                e = transform_attachment_parent_of(ecd, e);
+            }
+
+            t64_evaluate_world(EVALUATED, ecd, entity, playbacks);
+
+            playbacks.length = 0;
+
+            source = EVALUATED;
+        }
+
+        t64_read_pose_array(out, 0, source);
+
+        return true;
     }
 
     /**
@@ -489,13 +917,14 @@ export class ClothWorld {
         }
 
         instance.seeded = false;
-        instance.anchor_valid = false;
+        instance.frame_valid = false;
 
         return instance;
     }
 
     /**
-     * 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.
      *
@@ -519,6 +948,37 @@ export class ClothWorld {
         return this.__by_entity.get(entity);
     }
 
+    /**
+     * 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, entity) {
+        const instance = this.__by_entity.get(cloth);
+
+        if (instance === undefined || !instance.seeded) {
+            return -1;
+        }
+
+        const entities = instance.rig === null ? instance.node_entity : instance.node_joint;
+
+        for (let node = 0; node < instance.node_count; node++) {
+            if (entities[node] === entity) {
+                return node;
+            }
+        }
+
+        return -1;
+    }
+
     /**
      * Everything that happens once per tick rather than once per cloth.
      *
@@ -640,9 +1100,9 @@ export class ClothWorld {
      * simulates the joints of the skinned model the entity is showing. There is
      * no mode field anywhere, and the solver does not know which ran.
      *
-     * A rig can fail to seed for reasons that are not errors — the model has
-     * not loaded, or nothing in the manager hands out model instances — and one
-     * that does is left unseeded for the next step to try again. A rig that
+     * A rig can fail to seed for reasons that are not errors — it names no skin
+     * yet, or the entity it names carries none yet, a model still loading — and
+     * one that does is left unseeded for the next step to try again. A rig that
      * fails for a reason that *is* an error says so once and then stops, because
      * a proxy that does not fit its skin will not start fitting it.
      *
@@ -659,6 +1119,10 @@ export class ClothWorld {
 
             cloth_seed_subtree(instance, ecd, this.attachments, dt);
 
+            // A new state holds nothing yet: the holds — offsets and all — are
+            // applied to it on its first step.
+            instance.holds_applied = -1;
+
             return;
         }
 
@@ -673,21 +1137,16 @@ export class ClothWorld {
             return;
         }
 
-        if (this.models === null) {
-            this.#refuse(instance, `entity ${instance.entity} has a ClothRig and nothing hands out model instances`);
+        const skin = rig.skin === -1 || !ecd.entityExists(rig.skin)
+            ? undefined
+            : ecd.getComponent(rig.skin, MeshSkin);
 
+        if (skin === undefined) {
+            // Not named yet, or not there yet: still loading. Not an error, and
+            // not worth a message.
             return;
         }
 
-        const model = this.models.instance_of(instance.entity);
-
-        if (model === null || model === undefined) {
-            // Still loading. Not an error, and not worth a message.
-            return;
-        }
-
-        const skin = model.skins[rig.skin];
-
         const error = rig.proxy.checkAgainst(skin);
 
         if (error !== "") {
@@ -699,6 +1158,8 @@ export class ClothWorld {
         instance.rig = rig;
 
         cloth_seed_rig(instance, rig.proxy, skin.joints, ecd, dt);
+
+        instance.holds_applied = -1;
     }
 
     /**
@@ -720,8 +1181,9 @@ export class ClothWorld {
 
     /**
      * 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
@@ -760,7 +1222,7 @@ export class ClothWorld {
 
         const transform = instance.rig === null
             ? instance.transform
-            : this.#anchor_pose(instance);
+            : this.#frame_pose(instance);
 
         const tx = transform[TRANSFORM64_TRANSLATION_OFFSET];
         const ty = transform[TRANSFORM64_TRANSLATION_OFFSET + 1];
@@ -771,15 +1233,38 @@ export class ClothWorld {
         const qz = transform[TRANSFORM64_ROTATION_OFFSET + 2];
         const qw = transform[TRANSFORM64_ROTATION_OFFSET + 3];
 
-        const previous_translation = instance.anchor_translation;
-        const previous_rotation = instance.anchor_rotation;
+        const previous_translation = instance.frame_translation;
+        const previous_rotation = instance.frame_rotation;
+
+        FRAME_TRANSLATION[0] = tx;
+        FRAME_TRANSLATION[1] = ty;
+        FRAME_TRANSLATION[2] = tz;
+
+        FRAME_ROTATION[0] = qx;
+        FRAME_ROTATION[1] = qy;
+        FRAME_ROTATION[2] = qz;
+        FRAME_ROTATION[3] = qw;
+
+        // What holds the cloth, before anything that might decide it is asleep:
+        // a hold appearing or going is a reason to wake, and so is a holder
+        // moving.
+        this.#sync_holds(instance);
+
+        const holders_moved = this.#evaluate_holds(instance, FRAME_TRANSLATION, FRAME_ROTATION);
+
+        // Positions are still in the frame they were last stepped in, which on
+        // a cloth's first step is this one; a hold begins where its particles
+        // are, so that is the frame its offsets are taken in.
+        const holds_changed = instance.frame_valid
+            ? this.#refresh_holds(instance, previous_translation, previous_rotation)
+            : this.#refresh_holds(instance, FRAME_TRANSLATION, FRAME_ROTATION);
 
         if (instance.cloth.blend !== instance.blend_seen) {
             instance.asleep = false;
             instance.still_steps = 0;
         }
 
-        const moved = instance.anchor_valid && (
+        const moved = instance.frame_valid && (
             previous_translation[0] !== tx
             || previous_translation[1] !== ty
             || previous_translation[2] !== tz
@@ -789,7 +1274,7 @@ export class ClothWorld {
             || previous_rotation[3] !== qw
         );
 
-        if (moved) {
+        if (moved || holders_moved || holds_changed) {
             instance.asleep = false;
             instance.still_steps = 0;
         }
@@ -814,7 +1299,7 @@ export class ClothWorld {
             // cheaper than the step it decides whether to skip.
             if (cloth_air_changed(
                 instance.state, this.wind,
-                instance.anchor_translation, instance.anchor_rotation,
+                instance.frame_translation, instance.frame_rotation,
                 instance.air_seen, CLOTH_SLEEP_SPEED_RATIO * instance.reach,
                 instance.age
             )) {
@@ -831,33 +1316,58 @@ export class ClothWorld {
             return false;
         }
 
-        if (moved) {
-            const displacement = Math.hypot(tx - previous_translation[0], ty - previous_translation[1], tz - previous_translation[2]);
+        // §7 P6. Locomotion moves a frame a fraction of the cloth's own reach a
+        // step; a jump past this is something else, whether it is the frame
+        // that jumped or something holding the cloth, measured in the frame.
+        const threshold = Math.max(CLOTH_TELEPORT_REACH * instance.reach, CLOTH_TELEPORT_FLOOR);
 
-            const teleport = displacement > Math.max(
-                CLOTH_TELEPORT_REACH * instance.reach,
-                CLOTH_TELEPORT_FLOOR
-            );
+        const frame_jumped = moved && Math.hypot(
+            tx - previous_translation[0], ty - previous_translation[1], tz - previous_translation[2]
+        ) > threshold;
+
+        let holder_jumped = false;
+
+        const holds = instance.holds;
+
+        for (let h = 0; h < holds.length; h++) {
+            const hold = holds[h];
+
+            if (!hold.valid || !hold.has_previous || !hold.captured) {
+                continue;
+            }
+
+            const pose = hold.pose;
+            const before = hold.pose_previous;
+
+            if (Math.hypot(pose[0] - before[0], pose[1] - before[1], pose[2] - before[2]) > threshold) {
+                holder_jumped = true;
+            }
+        }
 
-            if (teleport) {
-                this.#teleport(instance);
+        const keep = (instance.cloth.flags & ClothFlags.TeleportKeep) !== 0;
+
+        let reset = false;
+
+        if (frame_jumped || holder_jumped) {
+            instance.teleport_count++;
+
+            if (keep) {
+                instance.holds_dirty = true;
+
+                // The frame's jump needs nothing: the particles are in its frame.
+                // A holder's is carried onto what hangs from it.
+                for (let h = 0; h < holds.length; h++) {
+                    const hold = holds[h];
+
+                    if (hold.valid && hold.has_previous && hold.captured) {
+                        carry_with_holder(instance, h);
+                    }
+                }
             } else {
-                // the new pose goes in as an array: handed over as seven numbers, each was boxed
-                // wherever the call was not inlined
-                ANCHOR_POSE[0] = tx;
-                ANCHOR_POSE[1] = ty;
-                ANCHOR_POSE[2] = tz;
-                ANCHOR_POSE[3] = qx;
-                ANCHOR_POSE[4] = qy;
-                ANCHOR_POSE[5] = qz;
-                ANCHOR_POSE[6] = qw;
-
-                move_local_frame(instance, ANCHOR_POSE, previous_translation, previous_rotation);
+                reset = true;
             }
-        } else if (instance.anchor_valid && instance.cloth.dynamics.inertia > 0) {
-            // The frame is identical. Preserve the pinning side effect of
-            // move_local_frame without rewriting every free position/velocity.
-            pin_anchor(instance);
+        } else if (moved) {
+            move_local_frame(instance, FRAME_TRANSLATION, FRAME_ROTATION, previous_translation, previous_rotation);
         }
 
         previous_translation[0] = tx;
@@ -869,13 +1379,30 @@ export class ClothWorld {
         previous_rotation[2] = qz;
         previous_rotation[3] = qw;
 
-        instance.anchor_valid = true;
+        instance.frame_valid = true;
+
+        // Where every held particle goes, the pose hung from them, the leash
+        // centres — from this step's holder poses.
+        cloth_hold_step(instance);
+
+        if (reset) {
+            this.#reset(instance);
+        }
+
+        for (let h = 0; h < holds.length; h++) {
+            const hold = holds[h];
+
+            if (hold.valid) {
+                hold.pose_previous.set(hold.pose);
+                hold.world_previous.set(hold.world);
 
-        refresh_leash_targets(instance);
+                hold.has_previous = true;
+            }
+        }
 
         const dynamics = instance.cloth.dynamics;
 
-        // Gravity is a world vector and the solve is in the anchor's frame.
+        // Gravity is a world vector and the solve is in the cloth's frame.
         const gravity = this.gravity;
 
         // `previous_rotation` has just been set to this step's `q`; vector and rotation go in as arrays
@@ -894,7 +1421,8 @@ export class ClothWorld {
             // nothing beyond it — `cloth_gather_reach` carries the derivation,
             // and why the velocity clamp that used to stand here was both far
             // too wide and missing two terms.
-            const reach = cloth_gather_reach(state, this.colliders.index, dt);
+            // and as far again as a holder drags it, which no velocity says
+            const reach = cloth_gather_reach(state, this.colliders.index, dt) + instance.kinematic_travel;
 
             cloth_gather_colliders(instance, this.colliders.index, reach);
 
@@ -921,7 +1449,7 @@ export class ClothWorld {
 
             instance.air_varies = cloth_sample_air(
                 state, this.wind,
-                instance.anchor_translation, instance.anchor_rotation,
+                instance.frame_translation, instance.frame_rotation,
                 instance.air_seen, instance.age
             );
         } else {
@@ -929,6 +1457,7 @@ export class ClothWorld {
         }
 
         params[offset + ClothStepParam.DRAG_RESPONSE] = drag_response;
+        params[offset + ClothStepParam.KINEMATIC_TRAVEL] = instance.kinematic_travel;
 
         const self_collision = (dynamics.flags & ClothDynamicsFlags.SelfCollision) !== 0;
 
@@ -980,8 +1509,10 @@ export class ClothWorld {
     }
 
     /**
-     * The anchor joint's world pose, computed on the CPU from the clips the
-     * entity is playing.
+     * A rig's frame joint's world pose, computed on the CPU from the clips the
+     * entity is playing — and, while the playbacks are in hand, the pose in that
+     * frame of every bone the garment hangs from, for the write-back to express
+     * the garment's roots against.
      *
      * **Computed, never read back**, for two reasons that are both the engine's
      * own. A joint of an animated skeleton is the GPU's (`GPUStateAuthority`),
@@ -997,36 +1528,58 @@ export class ClothWorld {
      * @returns {Transform64}
      * @private
      */
-    #anchor_pose(instance) {
+    #frame_pose(instance) {
         const playbacks = PLAYBACKS;
 
         playbacks.length = 0;
 
         collect_entity_playbacks(playbacks, this.entityManager, instance.entity);
 
-        t64_evaluate_world(instance.anchor_pose, this.entityManager.dataset, instance.node_joint[0], playbacks);
+        const ecd = this.entityManager.dataset;
+
+        const frame = instance.frame_pose;
+
+        t64_evaluate_world(frame, ecd, instance.frame_entity, playbacks);
+
+        const node_output = instance.node_output;
+        const boundary = instance.boundary_pose;
+
+        for (let node = 0; node < instance.node_count; node++) {
+            if (node_output[node] !== 0) {
+                continue;
+            }
+
+            t64_evaluate_world(EVALUATED, ecd, instance.node_joint[node], playbacks);
+
+            const b = node * 7;
+
+            pose3_to_local_array(
+                boundary, b,
+                boundary, b + 3,
+                frame, TRANSFORM64_TRANSLATION_OFFSET,
+                frame, TRANSFORM64_ROTATION_OFFSET,
+                EVALUATED, TRANSFORM64_TRANSLATION_OFFSET,
+                EVALUATED, TRANSFORM64_ROTATION_OFFSET
+            );
+        }
 
         playbacks.length = 0;
 
-        return instance.anchor_pose;
+        return frame;
     }
 
     /**
+     * §7 P6's `Reset`: every particle onto the animated pose — the rest pose
+     * hung from where its holders now are — at rest, with nothing carried over.
+     *
+     * A held particle lands on its target, and its target is where the predict
+     * carries it to, so it does not move again this step: the jump is taken
+     * between steps rather than dragged through one.
+     *
      * @param {ClothInstance} instance
      * @private
      */
-    #teleport(instance) {
-        instance.teleport_count++;
-
-        if ((instance.cloth.flags & ClothFlags.TeleportKeep) !== 0) {
-            // `Keep` carries the cloth's shape across the jump. Particles are
-            // stored relative to the anchor, so that is exactly what happens if
-            // this function does nothing to them — the frame moved and they did
-            // not, which is MagicaCloth2's rigid delta expressed in the frame
-            // that makes it free.
-            return;
-        }
-
+    #reset(instance) {
         const state = instance.state;
 
         const node_count = instance.node_count;
@@ -1043,6 +1596,10 @@ export class ClothWorld {
         }
 
         state.position_previous.set(state.position);
+        state.kinematic_target.set(state.position);
+
+        instance.kinematic_travel = 0;
+        instance.holds_dirty = true;
         state.velocity.fill(0);
         state.inertia_blend.fill(0);
 
@@ -1078,54 +1635,62 @@ const LOCAL_GRAVITY = new Float64Array(3);
 const FRAME = new Float64Array(8);
 
 /**
- * The anchor's pose this step, `[tx, ty, tz, qx, qy, qz, qw]`, as {@link move_local_frame} takes it.
+ * The frame's translation and rotation this step, apart, as the holds and {@link move_local_frame}
+ * take them: the transform read once, before anything this step could write it.
  * @type {Float64Array}
  * @private
  */
-const ANCHOR_POSE = new Float64Array(7);
+const FRAME_TRANSLATION = new Float64Array(3);
 
 /**
- * {@link move_local_frame}'s `q_now⁻¹`, `[-qx, -qy, -qz, qw]`.
  * @type {Float64Array}
  * @private
  */
-const POSE_CONJUGATE = new Float64Array(4);
+const FRAME_ROTATION = new Float64Array(4);
 
 /**
- * The identity rotation, `[0, 0, 0, 1]`, which {@link move_local_frame} limits a turn towards. Never
- * written.
- * @type {Float64Array}
+ * An exactly evaluated world pose: a holder a clip drives, a bone a garment
+ * hangs from.
+ * @type {Transform64}
  * @private
  */
-const IDENTITY_ROTATION = new Float64Array([0, 0, 0, 1]);
+const EVALUATED = new Transform64();
 
 /**
- * Carry the particles across a change of anchor pose, by however much of it the
+ * The models a holder's chain passes through, each once.
+ * @type {number[]}
+ * @private
+ */
+const MODELS = [];
+
+/**
+ * Carry the free particles across a change of frame pose, by however much of it the
  * fabric is willing to feel. §7 P7.
  *
  * A particle at local `p` was at world `t_prev + q_prev·p`. Holding that world
  * position fixed, its local coordinates become `D + Q·p` with
  * `D = q_now⁻¹·(t_prev − t_now)` and `Q = q_now⁻¹ ⊗ q_prev`. Feeling *all* of
- * the anchor's motion is taking that; feeling *none* is leaving `p` alone; and
+ * the frame's motion is taking that; feeling *none* is leaving `p` alone; and
  * `inertia` is the lerp between them. Velocity is carried the same way, minus
  * the translation, since a translation of the frame does not rotate a vector.
  *
  * `D` and `Q` are limited before the lerp. The limits are the cloth's own reach
- * per step and a fixed angle per step, which is what makes an anchor that
+ * per step and a fixed angle per step, which is what makes a frame that
  * teleports a metre — or spins — something a cape *lags behind* rather than
  * something it is fired out of.
  *
  * Every vector and quaternion goes to its function as an array and an offset: handed over as numbers,
  * each was boxed into a heap object wherever the call was not inlined, which until V8 optimises this
- * is every call, twice per particle per step of a moving anchor.
+ * is every call, twice per particle per step of a moving frame.
  *
  * @param {ClothInstance} instance
- * @param {Float64Array} pose the anchor's pose now, `[tx, ty, tz, qx, qy, qz, qw]`
+ * @param {Float64Array} translation the frame's translation now
+ * @param {Float64Array} rotation the frame's rotation now
  * @param {Float64Array} previous_translation
  * @param {Float64Array} previous_rotation
  * @private
  */
-function move_local_frame(instance, pose, previous_translation, previous_rotation) {
+function move_local_frame(instance, translation, rotation, previous_translation, previous_rotation) {
     let inertia = instance.cloth.dynamics.inertia;
 
     if (inertia <= 0) {
@@ -1136,13 +1701,10 @@ function move_local_frame(instance, pose, previous_translation, previous_rotatio
         inertia = 1;
     }
 
-    FRAME[0] = previous_translation[0] - pose[0];
-    FRAME[1] = previous_translation[1] - pose[1];
-    FRAME[2] = previous_translation[2] - pose[2];
-
-    v3_quaternion_apply_inverse_array(FRAME, 0, FRAME, 0, pose, 3);
+    // the previous pose in the frame now: D and Q
+    pose3_to_local_array(FRAME, 0, FRAME, 4, translation, 0, rotation, 0, previous_translation, 0, previous_rotation, 0);
 
-    const travel_limit = CLOTH_ANCHOR_TRAVEL_REACH * instance.reach;
+    const travel_limit = CLOTH_FRAME_TRAVEL_REACH * instance.reach;
 
     const travel = Math.hypot(FRAME[0], FRAME[1], FRAME[2]);
 
@@ -1154,21 +1716,10 @@ function move_local_frame(instance, pose, previous_translation, previous_rotatio
         FRAME[2] *= scale;
     }
 
-    POSE_CONJUGATE[0] = -pose[3];
-    POSE_CONJUGATE[1] = -pose[4];
-    POSE_CONJUGATE[2] = -pose[5];
-    POSE_CONJUGATE[3] = pose[6];
-
-    quat3_multiply_array(FRAME, 4, POSE_CONJUGATE, 0, previous_rotation, 0);
-
-    // `|w|` is `cos(θ/2)`, so this is the angle test without an `acos`.
-    const half_angle_cos = FRAME[7] < 0 ? -FRAME[7] : FRAME[7];
-
-    if (half_angle_cos < Math.cos(CLOTH_ANCHOR_ROTATION_LIMIT * 0.5)) {
-        const angle = 2 * Math.acos(half_angle_cos > 1 ? 1 : half_angle_cos);
-
-        quat3_nlerp_array(FRAME, 4, IDENTITY_ROTATION, 0, FRAME, 4, CLOTH_ANCHOR_ROTATION_LIMIT / angle);
-    }
+    // Exactly the limit about the same axis. An nlerp from the identity by `limit / θ` follows the
+    // chord and turned less than the limit the further past it the frame spun: three quarters of it
+    // at a half turn.
+    quat3_clamp_angle_array(FRAME, 4, FRAME, 4, CLOTH_FRAME_ROTATION_LIMIT);
 
     const state = instance.state;
 
@@ -1181,7 +1732,16 @@ function move_local_frame(instance, pose, previous_translation, previous_rotatio
     const dy = FRAME[1];
     const dz = FRAME[2];
 
+    const mass_inverse = state.mass_inverse;
+
     for (let i = 0; i < particle_count; i++) {
+        // A held particle belongs to its holder, not to the world: it goes where
+        // its holder takes it, through the step, and not where the frame's
+        // motion would have left it.
+        if (mass_inverse[i] === 0) {
+            continue;
+        }
+
         const p = i * 3;
 
         v3_quaternion_apply_array(CARRIED, 0, position, p, FRAME, 4);
@@ -1196,30 +1756,60 @@ function move_local_frame(instance, pose, previous_translation, previous_rotatio
         velocity[p + 1] += inertia * (CARRIED[1] - velocity[p + 1]);
         velocity[p + 2] += inertia * (CARRIED[2] - velocity[p + 2]);
     }
-
-    pin_anchor(instance);
 }
 
 /**
+ * `ClothFlags.TeleportKeep` for a holder that jumped: its own jump, in the
+ * frame, applied to everything hanging from it — the particles it holds and
+ * every free one whose nearest held particle is one of them — positions and
+ * velocities alike. What hangs from another holder stays where it is.
+ *
  * @param {ClothInstance} instance
+ * @param {number} h index into {@link ClothInstance#holds}
  * @private
  */
-function pin_anchor(instance) {
-    const position = instance.state.position;
-    const velocity = instance.state.velocity;
-    // The anchor is pinned and is the origin of the frame it anchors, so it is
-    // the one particle that must not be carried anywhere.
-    const anchor = instance.particle_of_node[0] * 3;
-
-    position[anchor] = 0;
-    position[anchor + 1] = 0;
-    position[anchor + 2] = 0;
-
-    velocity[anchor] = 0;
-    velocity[anchor + 1] = 0;
-    velocity[anchor + 2] = 0;
+function carry_with_holder(instance, h) {
+    const hold = instance.holds[h];
+
+    const now = hold.pose;
+    const before = hold.pose_previous;
+
+    // the jump's rotation, q_now ⊗ q_before⁻¹
+    quat3_multiply_conjugate_right_array(JUMP, 0, now, 3, before, 3);
+
+    const state = instance.state;
+    const position = state.position;
+    const velocity = state.velocity;
+
+    const node_hold = instance.node_hold;
+    const source = instance.tether_source;
+    const particle_of_node = instance.particle_of_node;
+
+    for (let node = 0; node < instance.node_count; node++) {
+        const owner = node_hold[node] !== -1 ? node_hold[node] : (source[node] === -1 ? -1 : node_hold[source[node]]);
+
+        if (owner !== h) {
+            continue;
+        }
+
+        const p = particle_of_node[node] * 3;
+
+        CARRIED[0] = position[p] - before[0];
+        CARRIED[1] = position[p + 1] - before[1];
+        CARRIED[2] = position[p + 2] - before[2];
+
+        pose3_apply_point_array(position, p, now, 0, JUMP, 0, CARRIED, 0);
+
+        v3_quaternion_apply_array(velocity, p, velocity, p, JUMP, 0);
+    }
 }
 
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const JUMP = new Float64Array(4);
+
 /**
  * @type {Float64Array}
  * @private
@@ -1285,46 +1875,3 @@ function cloth_inside_sleep_window(instance) {
     return true;
 }
 
-/**
- * Point every leash row at where it measures from: a slack row at the
- * particle's animated position, a tether at the anchor.
- *
- * @param {ClothInstance} instance
- * @private
- */
-function refresh_leash_targets(instance) {
-    const state = instance.state;
-
-    const target = state.leash_target;
-
-    const animated = instance.animated_position;
-
-    const anchor = instance.particle_of_node[0] * 3;
-
-    const anchor_x = state.position[anchor];
-    const anchor_y = state.position[anchor + 1];
-    const anchor_z = state.position[anchor + 2];
-
-    const node_count = instance.node_count;
-
-    const slack_row = instance.slack_row;
-    const tether_row = instance.tether_row;
-
-    for (let node = 1; node < node_count; node++) {
-        const tether = tether_row[node];
-
-        if (tether >= 0) {
-            target[tether * 3] = anchor_x;
-            target[tether * 3 + 1] = anchor_y;
-            target[tether * 3 + 2] = anchor_z;
-        }
-
-        const slack = slack_row[node];
-
-        if (slack >= 0) {
-            target[slack * 3] = animated[node * 3];
-            target[slack * 3 + 1] = animated[node * 3 + 1];
-            target[slack * 3 + 2] = animated[node * 3 + 2];
-        }
-    }
-}