@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -1,773 +1,1021 @@
-import { assert } from "../../../../core/assert.js";
-import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
-import { quat3_nlerp } from "../../../../core/geom/3d/quaternion/quat3_nlerp.js";
-import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
-import { v3_quaternion_apply_inverse } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
-import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
-import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
-import { System } from "../../../ecs/System.js";
-import {
-    TransformAttachment
-} from "../../../ecs/transform-attachment/TransformAttachment.js";
-import {
-    TransformAttachmentSystem
-} from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
-import {
-    TRANSFORM64_ROTATION_OFFSET,
-    TRANSFORM64_TRANSLATION_OFFSET,
-    Transform64
-} from "../../../ecs/transform/Transform64.js";
-import { cloth_step } from "../solver/cloth_step.js";
-import { Cloth } from "./Cloth.js";
-import { ClothExclude } from "./ClothExclude.js";
-import { ClothFlags } from "./ClothFlags.js";
-import { ClothInstance } from "./ClothInstance.js";
-import {
-    CLOTH_ANCHOR_ROTATION_LIMIT,
-    CLOTH_ANCHOR_TRAVEL_REACH,
-    CLOTH_SLEEP_SPEED_RATIO,
-    CLOTH_SLEEP_STEPS,
-    CLOTH_STABILISE_STEPS,
-    CLOTH_TELEPORT_FLOOR,
-    CLOTH_TELEPORT_REACH,
-    cloth_velocity_limit,
-    cloth_velocity_retention
-} from "./cloth_dynamics_map.js";
-import {
-    cloth_dynamics_change_needs_reseed,
-    cloth_reparameterise,
-    cloth_seed_subtree
-} from "./cloth_seed_subtree.js";
-import { cloth_write_back } from "./cloth_write_back.js";
-
-/**
- * # The system — gather, step, write back
- *
- * 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, 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.
- *
- * ## Where in the frame this runs
- *
- * Wherever the derived order puts it, and **nothing here depends on that**.
- *
- * The engine has two ways to order systems — registration order, and what each
- * system declares in `components_used` — and neither can express "after
- * whatever wrote this transform, before whatever reads it", because a system
- * that reads and writes one component is on both sides of that component's own
- * rule. Cloth is such a system: it reads a world transform and writes world
- * transforms. So rather than reach for a third mechanism, the write-back is
- * built so the order does not matter: it writes each node's **local** transform
- * alongside its world one, which makes a hierarchy recomposition reproduce the
- * simulated pose instead of replacing it with the authored one
- * (`cloth_write_back.js`).
- *
- * What is left is a **quality** question rather than a correctness one, and it
- * is smaller than it looks. Running before the system that poses the anchor
- * means reading last step's anchor pose, so the cloth's *shape* is one fixed
- * step stale; its *position* is not, because the attachment cascade carries the
- * whole subtree rigidly with the anchor from cloth's own local transforms.
- * `ClothSystem.spec.js` measures that lag rather than asserting a placement,
- * and asserts the property that actually matters: the pose survives being
- * recomposed.
- *
- * The declaration is the honest one — cloth reads `Cloth` and `ClothExclude`,
- * and reads and writes both `Transform64` and `TransformAttachment`. That puts
- * it before `TransformAttachmentSystem`, which is right: cloth writes the local
- * transforms and the attachment system is their reader.
- *
- * ## The local frame and the inertia model — §7 P7
- *
- * Particles live in the anchor's own frame. When the anchor 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
- * blend between the two is a lerp in the local frame, which is all the frame
- * change is.
- *
- * The felt motion is limited before the blend, which is what makes "character
- * sprints, cape behaves" a default rather than a tuning exercise, and the limits
- * are derived from the cloth's own reach rather than authored.
- *
- * ## 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.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class ClothSystem extends System {
-
-    dependencies = [Cloth, Transform64];
-
-    components_used = [
-        ResourceAccessSpecification.from(Cloth, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write),
-        ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read | ResourceAccessKind.Write),
-        ResourceAccessSpecification.from(ClothExclude, ResourceAccessKind.Read)
-    ];
-
-    /**
-     * World gravity, m/s². Rotated into each cloth's local frame per step.
-     * @type {Float64Array}
-     */
-    gravity = new Float64Array([0, -9.81, 0]);
-
-    /**
-     * Live cloths, ordered so that an instance whose anchor sits inside another
-     * instance's subtree steps after it.
-     * @type {ClothInstance[]}
-     */
-    instances = [];
-
-    /**
-     * @type {Map<number, ClothInstance>}
-     * @private
-     */
-    __by_entity = new Map();
-
-    /**
-     * @type {TransformAttachmentSystem|null}
-     * @private
-     */
-    __attachments = null;
-
-    /**
-     * @type {boolean}
-     * @private
-     */
-    __order_dirty = false;
-
-    /**
-     * @param {EntityManager} entityManager
-     * @returns {Promise<void>}
-     */
-    async startup(entityManager) {
-        this.__attachments = entityManager.getSystem(TransformAttachmentSystem);
-
-        assert.notNull(
-            this.__attachments,
-            'ClothSystem needs a TransformAttachmentSystem: the subtree walk is its parent-to-children index'
-        );
-    }
-
-    /**
-     * @param {Cloth} cloth
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    link(cloth, transform, entity) {
-        const instance = new ClothInstance();
-
-        instance.entity = entity;
-        instance.cloth = cloth;
-        instance.transform = transform;
-
-        this.instances.push(instance);
-        this.__by_entity.set(entity, instance);
-
-        this.__order_dirty = true;
-    }
-
-    /**
-     * @param {Cloth} cloth
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    unlink(cloth, transform, entity) {
-        const instance = this.__by_entity.get(entity);
-
-        if (instance === undefined) {
-            return;
-        }
-
-        this.__by_entity.delete(entity);
-
-        const index = this.instances.indexOf(instance);
-
-        if (index >= 0) {
-            this.instances.splice(index, 1);
-        }
-    }
-
-    /**
-     * Throw away a cloth's binding so the next step walks its subtree again.
-     *
-     * The walk is done once, because a rope's links do not come and go. When
-     * they do — a chain gains a link, a rig is rebuilt — this is how you say so,
-     * and it is the same contract `TransformAttachment#parent` already carries:
-     * the structure is immutable while it is attached, and changing it is an
-     * explicit act rather than something the engine polls for.
-     *
-     * @param {number} entity
-     * @returns {void}
-     */
-    reseed(entity) {
-        const instance = this.__by_entity.get(entity);
-
-        if (instance === undefined) {
-            return;
-        }
-
-        instance.seeded = false;
-        instance.anchor_valid = false;
-
-        this.__order_dirty = true;
-    }
-
-    /**
-     * Wake a sleeping cloth. Anchor motion 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.
-     *
-     * @param {number} entity
-     * @returns {void}
-     */
-    wake(entity) {
-        const instance = this.__by_entity.get(entity);
-
-        if (instance !== undefined) {
-            instance.asleep = false;
-            instance.still_steps = 0;
-        }
-    }
-
-    /**
-     * @param {number} entity
-     * @returns {ClothInstance|undefined}
-     */
-    instanceOf(entity) {
-        return this.__by_entity.get(entity);
-    }
-
-    /**
-     * @param {number} dt seconds
-     */
-    fixedUpdate(dt) {
-        const ecd = this.entityManager.dataset;
-
-        if (ecd === null || ecd === undefined) {
-            return;
-        }
-
-        const instances = this.instances;
-
-        if (this.__order_dirty) {
-            this.#reorder(ecd);
-        }
-
-        for (let i = 0; i < instances.length; i++) {
-            const instance = instances[i];
-
-            if (!instance.seeded) {
-                cloth_seed_subtree(instance, ecd, this.__attachments, dt);
-            } else if (!instance.cloth.dynamics.equals(instance.dynamics_seen)) {
-                if (cloth_dynamics_change_needs_reseed(instance.dynamics_seen, instance.cloth.dynamics)) {
-                    cloth_seed_subtree(instance, ecd, this.__attachments, dt);
-                } else {
-                    cloth_reparameterise(instance, dt);
-                }
-
-                instance.asleep = false;
-                instance.still_steps = 0;
-            }
-
-            this.#advance(instance, ecd, dt);
-        }
-    }
-
-    /**
-     * Depth-first order by hierarchy depth, so a nested cloth reads an anchor
-     * the cloth above it has already written.
-     *
-     * @param {EntityComponentDataset} ecd
-     * @private
-     */
-    #reorder(ecd) {
-        const instances = this.instances;
-
-        for (let i = 0; i < instances.length; i++) {
-            const instance = instances[i];
-
-            let depth = 0;
-            let entity = instance.entity;
-
-            // Bounded by the number of entities; a cycle in the attachment
-            // graph is not this system's to diagnose, but it is this loop's to
-            // survive.
-            for (let guard = 0; guard < 4096; guard++) {
-                const attachment = ecd.getComponent(entity, TransformAttachment);
-
-                if (attachment === undefined) {
-                    break;
-                }
-
-                entity = attachment.parent;
-                depth++;
-            }
-
-            instance.depth = depth;
-        }
-
-        instances.sort((a, b) => a.depth - b.depth);
-
-        this.__order_dirty = false;
-    }
-
-    /**
-     * @param {ClothInstance} instance
-     * @param {EntityComponentDataset} ecd
-     * @param {number} dt
-     * @private
-     */
-    #advance(instance, ecd, dt) {
-        const transform = instance.transform;
-
-        const tx = transform[TRANSFORM64_TRANSLATION_OFFSET];
-        const ty = transform[TRANSFORM64_TRANSLATION_OFFSET + 1];
-        const tz = transform[TRANSFORM64_TRANSLATION_OFFSET + 2];
-
-        const qx = transform[TRANSFORM64_ROTATION_OFFSET];
-        const qy = transform[TRANSFORM64_ROTATION_OFFSET + 1];
-        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;
-
-        if (instance.cloth.blend !== instance.blend_seen) {
-            instance.asleep = false;
-            instance.still_steps = 0;
-        }
-
-        const moved = instance.anchor_valid && (
-            previous_translation[0] !== tx
-            || previous_translation[1] !== ty
-            || previous_translation[2] !== tz
-            || previous_rotation[0] !== qx
-            || previous_rotation[1] !== qy
-            || previous_rotation[2] !== qz
-            || previous_rotation[3] !== qw
-        );
-
-        if (moved) {
-            instance.asleep = false;
-            instance.still_steps = 0;
-        }
-
-        if (instance.asleep) {
-            // Nothing is stepped and nothing is written: the pose on the
-            // subtree is already the pose, and rewriting it is what would make
-            // §7 P5's "bit-identical across the following 300 steps" an
-            // aspiration rather than a fact.
-            return;
-        }
-
-        if (instance.anchor_valid) {
-            const displacement = Math.hypot(tx - previous_translation[0], ty - previous_translation[1], tz - previous_translation[2]);
-
-            const teleport = displacement > Math.max(
-                CLOTH_TELEPORT_REACH * instance.reach,
-                CLOTH_TELEPORT_FLOOR
-            );
-
-            if (teleport) {
-                this.#teleport(instance);
-            } else {
-                move_local_frame(
-                    instance,
-                    tx, ty, tz, qx, qy, qz, qw,
-                    previous_translation, previous_rotation
-                );
-            }
-        }
-
-        previous_translation[0] = tx;
-        previous_translation[1] = ty;
-        previous_translation[2] = tz;
-
-        previous_rotation[0] = qx;
-        previous_rotation[1] = qy;
-        previous_rotation[2] = qz;
-        previous_rotation[3] = qw;
-
-        instance.anchor_valid = true;
-
-        refresh_leash_targets(instance);
-
-        const dynamics = instance.cloth.dynamics;
-
-        damp(instance, cloth_velocity_retention(dynamics.damping, dt));
-
-        // Gravity is a world vector and the solve is in the anchor's frame.
-        const gravity = this.gravity;
-
-        v3_quaternion_apply_inverse(LOCAL_GRAVITY, 0, gravity[0], gravity[1], gravity[2], qx, qy, qz, qw);
-
-        const state = instance.state;
-
-        cloth_step(
-            state, dt,
-            LOCAL_GRAVITY[0], LOCAL_GRAVITY[1], LOCAL_GRAVITY[2],
-            dynamics.substeps, dynamics.iterations
-        );
-
-        let limit = cloth_velocity_limit(
-            instance.shortest_row, dynamics.substeps, dynamics.iterations, dt
-        );
-
-        if (instance.stabilise_remaining > 0) {
-            // Ramp back from nothing over the window. The first step after a
-            // reset is allowed no velocity at all, which is what stops a
-            // re-seeded cloth from snapping taut and whipping.
-            limit *= (CLOTH_STABILISE_STEPS - instance.stabilise_remaining) / CLOTH_STABILISE_STEPS;
-
-            instance.stabilise_remaining--;
-        }
-
-        const speed = clamp_velocity(instance, limit);
-
-        if ((instance.cloth.flags & ClothFlags.NeverSleep) === 0) {
-            if (speed < CLOTH_SLEEP_SPEED_RATIO * instance.reach) {
-                instance.still_steps++;
-
-                if (instance.still_steps >= CLOTH_SLEEP_STEPS) {
-                    instance.asleep = true;
-                }
-            } else {
-                instance.still_steps = 0;
-            }
-        }
-
-        instance.blend_seen = instance.cloth.blend;
-
-        cloth_write_back(instance, ecd);
-    }
-
-    /**
-     * @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;
-        }
-
-        const state = instance.state;
-
-        const node_count = instance.node_count;
-        const animated = instance.animated_position;
-        const particle_of_node = instance.particle_of_node;
-
-        for (let node = 0; node < node_count; node++) {
-            const p = particle_of_node[node] * 3;
-            const n = node * 3;
-
-            state.position[p] = animated[n];
-            state.position[p + 1] = animated[n + 1];
-            state.position[p + 2] = animated[n + 2];
-        }
-
-        state.position_previous.set(state.position);
-        state.velocity.fill(0);
-        state.inertia_blend.fill(0);
-
-        // The multipliers describe forces in a configuration that no longer
-        // exists. Carrying them across would apply the old pose's tension to
-        // the new one on the first iteration, which is a whip with extra steps.
-        state.stretch_lambda.fill(0);
-        state.bend_lambda.fill(0);
-        state.leash_lambda.fill(0);
-
-        instance.stabilise_remaining = CLOTH_STABILISE_STEPS;
-    }
-}
-
-/**
- * @type {Float64Array}
- * @private
- */
-const LOCAL_GRAVITY = new Float64Array(3);
-
-/**
- * @type {Float64Array}
- * @private
- */
-const FRAME = new Float64Array(8);
-
-/**
- * Carry the particles across a change of anchor 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
- * `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
- * teleports a metre — or spins — something a cape *lags behind* rather than
- * something it is fired out of.
- *
- * @param {ClothInstance} instance
- * @param {number} tx
- * @param {number} ty
- * @param {number} tz
- * @param {number} qx
- * @param {number} qy
- * @param {number} qz
- * @param {number} qw
- * @param {Float64Array} previous_translation
- * @param {Float64Array} previous_rotation
- * @private
- */
-function move_local_frame(
-    instance,
-    tx, ty, tz, qx, qy, qz, qw,
-    previous_translation, previous_rotation
-) {
-    let inertia = instance.cloth.dynamics.inertia;
-
-    if (inertia <= 0) {
-        return;
-    }
-
-    if (inertia > 1) {
-        inertia = 1;
-    }
-
-    v3_quaternion_apply_inverse(
-        FRAME, 0,
-        previous_translation[0] - tx,
-        previous_translation[1] - ty,
-        previous_translation[2] - tz,
-        qx, qy, qz, qw
-    );
-
-    const travel_limit = CLOTH_ANCHOR_TRAVEL_REACH * instance.reach;
-
-    const travel = Math.hypot(FRAME[0], FRAME[1], FRAME[2]);
-
-    if (travel > travel_limit && travel > 0) {
-        const scale = travel_limit / travel;
-
-        FRAME[0] *= scale;
-        FRAME[1] *= scale;
-        FRAME[2] *= scale;
-    }
-
-    quat3_multiply(
-        FRAME, 4,
-        -qx, -qy, -qz, qw,
-        previous_rotation[0], previous_rotation[1], previous_rotation[2], previous_rotation[3]
-    );
-
-    // `|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(
-            FRAME, 4,
-            0, 0, 0, 1,
-            FRAME[4], FRAME[5], FRAME[6], FRAME[7],
-            CLOTH_ANCHOR_ROTATION_LIMIT / angle
-        );
-    }
-
-    const state = instance.state;
-
-    const particle_count = state.particle_count;
-
-    const position = state.position;
-    const velocity = state.velocity;
-
-    const dx = FRAME[0];
-    const dy = FRAME[1];
-    const dz = FRAME[2];
-
-    const rx = FRAME[4];
-    const ry = FRAME[5];
-    const rz = FRAME[6];
-    const rw = FRAME[7];
-
-    for (let i = 0; i < particle_count; i++) {
-        const p = i * 3;
-
-        v3_quaternion_apply(CARRIED, 0, position[p], position[p + 1], position[p + 2], rx, ry, rz, rw);
-
-        position[p] += inertia * (CARRIED[0] + dx - position[p]);
-        position[p + 1] += inertia * (CARRIED[1] + dy - position[p + 1]);
-        position[p + 2] += inertia * (CARRIED[2] + dz - position[p + 2]);
-
-        v3_quaternion_apply(CARRIED, 0, velocity[p], velocity[p + 1], velocity[p + 2], rx, ry, rz, rw);
-
-        velocity[p] += inertia * (CARRIED[0] - velocity[p]);
-        velocity[p + 1] += inertia * (CARRIED[1] - velocity[p + 1]);
-        velocity[p + 2] += inertia * (CARRIED[2] - velocity[p + 2]);
-    }
-
-    // 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;
-}
-
-/**
- * @type {Float64Array}
- * @private
- */
-const CARRIED = new Float64Array(3);
-
-/**
- * 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];
-        }
-    }
-}
-
-/**
- * Scale every particle's velocity, which is §7 P5's other half.
- *
- * The multiplier decay `α·γ` bleeds accumulated force out of a **hard** row,
- * and a soft row has no multiplier to decay — M0 measured a soft cloth landing
- * in a bounded limit cycle that 2,000 further steps do not move. This is what
- * reaches it, and it is why `ClothDynamics#damping` is part of the correctness
- * argument rather than a taste control. `MEASUREMENTS.md` §6.
- *
- * @param {ClothInstance} instance
- * @param {number} retention `[0, 1]`
- * @private
- */
-function damp(instance, retention) {
-    if (retention >= 1) {
-        return;
-    }
-
-    const velocity = instance.state.velocity;
-
-    for (let i = 0; i < velocity.length; i++) {
-        velocity[i] *= retention;
-    }
-}
-
-/**
- * Hold every particle's speed under the limit derived from
- * `ClothDynamics#thickness`, and report the largest speed left afterwards so
- * the sleep test has something to read.
- *
- * §7 P1 names this clamp and M0 deliberately left it out, because a clamp would
- * have masked the property M0 existed to measure. It is here rather than inside
- * `cloth_step` for the same reason: the solver's stability is still its own.
- *
- * Speed rather than displacement is what the sleep test reads, because
- * `position_previous` after a multi-substep step holds the start of the *last*
- * substep rather than the start of the step, and a motion measure that quietly
- * divides by the substep count is a sleep threshold that means something
- * different for every fabric.
- *
- * @param {ClothInstance} instance
- * @param {number} limit m/s
- * @returns {number} largest particle speed after clamping, m/s
- * @private
- */
-function clamp_velocity(instance, limit) {
-    const state = instance.state;
-
-    const particle_count = state.particle_count;
-
-    const velocity = state.velocity;
-
-    const limit_squared = limit * limit;
-
-    let worst_squared = 0;
-
-    for (let i = 0; i < particle_count; i++) {
-        const p = i * 3;
-
-        const vx = velocity[p];
-        const vy = velocity[p + 1];
-        const vz = velocity[p + 2];
-
-        let speed_squared = vx * vx + vy * vy + vz * vz;
-
-        if (speed_squared > limit_squared) {
-            const scale = limit / Math.sqrt(speed_squared);
-
-            velocity[p] = vx * scale;
-            velocity[p + 1] = vy * scale;
-            velocity[p + 2] = vz * scale;
-
-            speed_squared = limit_squared;
-        }
-
-        if (speed_squared > worst_squared) {
-            worst_squared = speed_squared;
-        }
-    }
-
-    return Math.sqrt(worst_squared);
-}
+import { assert } from "../../../../core/assert.js";
+import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { quat3_nlerp } from "../../../../core/geom/3d/quaternion/quat3_nlerp.js";
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse } from "../../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import { ResourceAccessKind } from "../../../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../../../core/model/ResourceAccessSpecification.js";
+import { System } from "../../../ecs/System.js";
+import {
+    TransformAttachment
+} from "../../../ecs/transform-attachment/TransformAttachment.js";
+import {
+    TransformAttachmentSystem
+} from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET,
+    Transform64
+} from "../../../ecs/transform/Transform64.js";
+import {
+    collect_entity_playbacks
+} from "../../../graphics3/pose/collect_entity_playbacks.js";
+import { MeshSystem } from "../../../graphics3/MeshSystem.js";
+import {
+    pose_evaluate_world
+} from "../../../../shade/renderer/animation/pose/pose_evaluate_world.js";
+import { cloth_contact_find } from "../solver/cloth_contact_find.js";
+import { cloth_self_find } from "../solver/cloth_self_find.js";
+import { CLOTH_SELF_RADIUS_MAX_RATIO, CLOTH_SELF_RADIUS_MIN_RATIO } from "../solver/cloth_solver_constants.js";
+import { cloth_step } from "../solver/cloth_step.js";
+import { Cloth } from "./Cloth.js";
+import { ClothCollider } from "./ClothCollider.js";
+import { ClothColliderSystem } from "./ClothColliderSystem.js";
+import { ClothExclude } from "./ClothExclude.js";
+import { ClothDynamicsFlags } from "./ClothDynamicsFlags.js";
+import { ClothFlags } from "./ClothFlags.js";
+import { ClothInstance } from "./ClothInstance.js";
+import { ClothRig } from "./ClothRig.js";
+import {
+    CLOTH_ANCHOR_ROTATION_LIMIT,
+    CLOTH_ANCHOR_TRAVEL_REACH,
+    CLOTH_SLEEP_SPEED_RATIO,
+    CLOTH_SLEEP_STEPS,
+    CLOTH_STABILISE_STEPS,
+    CLOTH_TELEPORT_FLOOR,
+    CLOTH_TELEPORT_REACH,
+    cloth_velocity_limit,
+    cloth_velocity_retention
+} from "./cloth_dynamics_map.js";
+import {
+    cloth_colliders_moved,
+    cloth_gather_colliders
+} from "./cloth_gather_colliders.js";
+import {
+    cloth_dynamics_change_needs_reseed,
+    cloth_reparameterise
+} from "./cloth_build_rows.js";
+import { cloth_seed_subtree } from "./cloth_seed_subtree.js";
+import { cloth_seed_rig } from "./cloth_seed_rig.js";
+import { cloth_write_back } from "./cloth_write_back.js";
+import { cloth_write_back_rig } from "./cloth_write_back_rig.js";
+
+/**
+ * # The system — gather, step, write back
+ *
+ * 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, 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.
+ *
+ * ## Where in the frame this runs
+ *
+ * Wherever the derived order puts it, and **nothing here depends on that**.
+ *
+ * The engine has two ways to order systems — registration order, and what each
+ * system declares in `components_used` — and neither can express "after
+ * whatever wrote this transform, before whatever reads it", because a system
+ * that reads and writes one component is on both sides of that component's own
+ * rule. Cloth is such a system: it reads a world transform and writes world
+ * transforms. So rather than reach for a third mechanism, the write-back is
+ * built so the order does not matter: it writes each node's **local** transform
+ * alongside its world one, which makes a hierarchy recomposition reproduce the
+ * simulated pose instead of replacing it with the authored one
+ * (`cloth_write_back.js`).
+ *
+ * What is left is a **quality** question rather than a correctness one, and it
+ * is smaller than it looks. Running before the system that poses the anchor
+ * means reading last step's anchor pose, so the cloth's *shape* is one fixed
+ * step stale; its *position* is not, because the attachment cascade carries the
+ * whole subtree rigidly with the anchor from cloth's own local transforms.
+ * `ClothSystem.spec.js` measures that lag rather than asserting a placement,
+ * and asserts the property that actually matters: the pose survives being
+ * recomposed.
+ *
+ * The declaration is the honest one — cloth reads `Cloth` and `ClothExclude`,
+ * and reads and writes both `Transform64` and `TransformAttachment`. That puts
+ * it before `TransformAttachmentSystem`, which is right: cloth writes the local
+ * transforms and the attachment system is their reader.
+ *
+ * ## The local frame and the inertia model — §7 P7
+ *
+ * Particles live in the anchor's own frame. When the anchor 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
+ * blend between the two is a lerp in the local frame, which is all the frame
+ * change is.
+ *
+ * The felt motion is limited before the blend, which is what makes "character
+ * sprints, cape behaves" a default rather than a tuning exercise, and the limits
+ * are derived from the cloth's own reach rather than authored.
+ *
+ * ## 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.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothSystem extends System {
+
+    dependencies = [Cloth, Transform64];
+
+    components_used = [
+        ResourceAccessSpecification.from(Cloth, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(TransformAttachment, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ResourceAccessSpecification.from(ClothExclude, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(ClothCollider, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(ClothRig, ResourceAccessKind.Read)
+    ];
+
+    /**
+     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @type {Float64Array}
+     */
+    gravity = new Float64Array([0, -9.81, 0]);
+
+    /**
+     * Live cloths, ordered so that an instance whose anchor sits inside another
+     * instance's subtree steps after it.
+     * @type {ClothInstance[]}
+     */
+    instances = [];
+
+    /**
+     * @type {Map<number, ClothInstance>}
+     * @private
+     */
+    __by_entity = new Map();
+
+    /**
+     * @type {TransformAttachmentSystem|null}
+     * @private
+     */
+    __attachments = null;
+
+    /**
+     * 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 = 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
+     */
+    __colliders = null;
+
+    /**
+     * @type {boolean}
+     * @private
+     */
+    __order_dirty = false;
+
+    /**
+     * @param {EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async startup(entityManager) {
+        this.__attachments = entityManager.getSystem(TransformAttachmentSystem);
+
+        assert.notNull(
+            this.__attachments,
+            'ClothSystem needs a TransformAttachmentSystem: the subtree walk is its parent-to-children index'
+        );
+
+        // 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;
+        }
+    }
+
+    /**
+     * @param {Cloth} cloth
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(cloth, transform, entity) {
+        const instance = new ClothInstance();
+
+        instance.entity = entity;
+        instance.cloth = cloth;
+        instance.transform = transform;
+
+        this.instances.push(instance);
+        this.__by_entity.set(entity, instance);
+
+        this.__order_dirty = true;
+    }
+
+    /**
+     * @param {Cloth} cloth
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(cloth, transform, entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return;
+        }
+
+        this.__by_entity.delete(entity);
+
+        const index = this.instances.indexOf(instance);
+
+        if (index >= 0) {
+            this.instances.splice(index, 1);
+        }
+    }
+
+    /**
+     * Throw away a cloth's binding so the next step walks its subtree again.
+     *
+     * The walk is done once, because a rope's links do not come and go. When
+     * they do — a chain gains a link, a rig is rebuilt — this is how you say so,
+     * and it is the same contract `TransformAttachment#parent` already carries:
+     * the structure is immutable while it is attached, and changing it is an
+     * explicit act rather than something the engine polls for.
+     *
+     * @param {number} entity
+     * @returns {void}
+     */
+    reseed(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return;
+        }
+
+        instance.seeded = false;
+        instance.anchor_valid = false;
+
+        this.__order_dirty = true;
+    }
+
+    /**
+     * Wake a sleeping cloth. Anchor motion 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.
+     *
+     * @param {number} entity
+     * @returns {void}
+     */
+    wake(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance !== undefined) {
+            instance.asleep = false;
+            instance.still_steps = 0;
+        }
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {ClothInstance|undefined}
+     */
+    instanceOf(entity) {
+        return this.__by_entity.get(entity);
+    }
+
+    /**
+     * @param {number} dt seconds
+     */
+    fixedUpdate(dt) {
+        const ecd = this.entityManager.dataset;
+
+        if (ecd === null || ecd === undefined) {
+            return;
+        }
+
+        const instances = this.instances;
+
+        if (this.__order_dirty) {
+            this.#reorder(ecd);
+        }
+
+        // The index is refreshed here rather than in its own system's fixed
+        // update, because the engine's ordering cannot put a reader after a
+        // writer of the same component and `ClothColliderSystem` reads strictly
+        // less than this system does. §4.1's conclusion, applied a second time:
+        // the answer is not a third mechanism, it is one call site.
+        if (this.__colliders !== null) {
+            this.__colliders.refresh();
+        }
+
+        for (let i = 0; i < instances.length; i++) {
+            const instance = instances[i];
+
+            if (instance.refused) {
+                continue;
+            }
+
+            if (!instance.seeded) {
+                this.#seed(instance, ecd, dt);
+
+                if (!instance.seeded) {
+                    // A rig whose model has not finished loading. Nothing is
+                    // wrong and nothing is retried-with-backoff: the next step
+                    // asks again, and a model that never loads costs one map
+                    // lookup a step.
+                    continue;
+                }
+            } else if (!instance.cloth.dynamics.equals(instance.dynamics_seen)) {
+                if (cloth_dynamics_change_needs_reseed(instance.dynamics_seen, instance.cloth.dynamics)) {
+                    this.#seed(instance, ecd, dt);
+                } else {
+                    cloth_reparameterise(instance, dt);
+                }
+
+                instance.asleep = false;
+                instance.still_steps = 0;
+            }
+
+            this.#advance(instance, ecd, dt);
+        }
+    }
+
+    /**
+     * Walk whichever hierarchy this cloth is built on.
+     *
+     * **The discriminator is a component's presence** (§3.1): `Cloth` alone
+     * simulates the entity's own transform subtree, `Cloth` + {@link ClothRig}
+     * 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
+     * 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.
+     *
+     * @param {ClothInstance} instance
+     * @param {EntityComponentDataset} ecd
+     * @param {number} dt
+     * @private
+     */
+    #seed(instance, ecd, dt) {
+        const rig = ecd.getComponent(instance.entity, ClothRig);
+
+        if (rig === undefined || rig === null || rig.proxy === null) {
+            instance.rig = null;
+
+            cloth_seed_subtree(instance, ecd, this.__attachments, dt);
+
+            return;
+        }
+
+        if (this.models === null) {
+            this.#refuse(instance, `entity ${instance.entity} has a ClothRig and nothing hands out model instances`);
+
+            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 !== "") {
+            this.#refuse(instance, `entity ${instance.entity}: ${error}`);
+
+            return;
+        }
+
+        instance.rig = rig;
+
+        cloth_seed_rig(instance, rig.proxy, skin.joints, dt);
+    }
+
+    /**
+     * Say once why a rig will not seed, and stop asking.
+     *
+     * @param {ClothInstance} instance
+     * @param {string} message
+     * @private
+     */
+    #refuse(instance, message) {
+        if (instance.refused) {
+            return;
+        }
+
+        instance.refused = true;
+
+        console.warn(`ClothSystem: ${message}`);
+    }
+
+    /**
+     * Depth-first order by hierarchy depth, so a nested cloth reads an anchor
+     * the cloth above it has already written.
+     *
+     * @param {EntityComponentDataset} ecd
+     * @private
+     */
+    #reorder(ecd) {
+        const instances = this.instances;
+
+        for (let i = 0; i < instances.length; i++) {
+            const instance = instances[i];
+
+            let depth = 0;
+            let entity = instance.entity;
+
+            // Bounded by the number of entities; a cycle in the attachment
+            // graph is not this system's to diagnose, but it is this loop's to
+            // survive.
+            for (let guard = 0; guard < 4096; guard++) {
+                const attachment = ecd.getComponent(entity, TransformAttachment);
+
+                if (attachment === undefined) {
+                    break;
+                }
+
+                entity = attachment.parent;
+                depth++;
+            }
+
+            instance.depth = depth;
+        }
+
+        instances.sort((a, b) => a.depth - b.depth);
+
+        this.__order_dirty = false;
+    }
+
+    /**
+     * @param {ClothInstance} instance
+     * @param {EntityComponentDataset} ecd
+     * @param {number} dt
+     * @private
+     */
+    #advance(instance, ecd, dt) {
+        const transform = instance.rig === null
+            ? instance.transform
+            : this.#anchor_pose(instance);
+
+        const tx = transform[TRANSFORM64_TRANSLATION_OFFSET];
+        const ty = transform[TRANSFORM64_TRANSLATION_OFFSET + 1];
+        const tz = transform[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+        const qx = transform[TRANSFORM64_ROTATION_OFFSET];
+        const qy = transform[TRANSFORM64_ROTATION_OFFSET + 1];
+        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;
+
+        if (instance.cloth.blend !== instance.blend_seen) {
+            instance.asleep = false;
+            instance.still_steps = 0;
+        }
+
+        const moved = instance.anchor_valid && (
+            previous_translation[0] !== tx
+            || previous_translation[1] !== ty
+            || previous_translation[2] !== tz
+            || previous_rotation[0] !== qx
+            || previous_rotation[1] !== qy
+            || previous_rotation[2] !== qz
+            || previous_rotation[3] !== qw
+        );
+
+        if (moved) {
+            instance.asleep = false;
+            instance.still_steps = 0;
+        }
+
+        if (instance.asleep && this.__colliders !== null && instance.collider_count >= 0) {
+            // §7 P5's "wake on collider motion". A sleeping cloth is neither
+            // stepped nor written back, so something has to notice the world it
+            // was resting against moving out from under it, and a broadphase
+            // query plus a pose comparison is three orders of magnitude cheaper
+            // than the step it decides whether to skip.
+            if (cloth_colliders_moved(instance, this.__colliders.index)) {
+                instance.asleep = false;
+                instance.still_steps = 0;
+            }
+        }
+
+        if (instance.asleep) {
+            // Nothing is stepped and nothing is written: the pose on the
+            // subtree is already the pose, and rewriting it is what would make
+            // §7 P5's "bit-identical across the following 300 steps" an
+            // aspiration rather than a fact.
+            return;
+        }
+
+        if (instance.anchor_valid) {
+            const displacement = Math.hypot(tx - previous_translation[0], ty - previous_translation[1], tz - previous_translation[2]);
+
+            const teleport = displacement > Math.max(
+                CLOTH_TELEPORT_REACH * instance.reach,
+                CLOTH_TELEPORT_FLOOR
+            );
+
+            if (teleport) {
+                this.#teleport(instance);
+            } else {
+                move_local_frame(
+                    instance,
+                    tx, ty, tz, qx, qy, qz, qw,
+                    previous_translation, previous_rotation
+                );
+            }
+        }
+
+        previous_translation[0] = tx;
+        previous_translation[1] = ty;
+        previous_translation[2] = tz;
+
+        previous_rotation[0] = qx;
+        previous_rotation[1] = qy;
+        previous_rotation[2] = qz;
+        previous_rotation[3] = qw;
+
+        instance.anchor_valid = true;
+
+        refresh_leash_targets(instance);
+
+        const dynamics = instance.cloth.dynamics;
+
+        damp(instance, cloth_velocity_retention(dynamics.damping, dt));
+
+        // Gravity is a world vector and the solve is in the anchor's frame.
+        const gravity = this.gravity;
+
+        v3_quaternion_apply_inverse(LOCAL_GRAVITY, 0, gravity[0], gravity[1], gravity[2], qx, qy, qz, qw);
+
+        const state = instance.state;
+
+        let limit = cloth_velocity_limit(
+            instance.shortest_row, dynamics.substeps, dynamics.iterations, dt
+        );
+
+        state.contact_radius = dynamics.thickness;
+
+        if (this.__colliders !== null) {
+            // The gather's margin is how far a particle may travel this step,
+            // which is the velocity clamp read as a distance — the quantity it
+            // was built out of (`cloth_dynamics_map.js`).
+            cloth_gather_colliders(instance, this.__colliders.index, limit * dt);
+
+            instance.contact_count = cloth_contact_find(
+                state, instance.collider_table, instance.collider_key, instance.collider_count
+            );
+        } else {
+            instance.collider_count = 0;
+            instance.contact_count = 0;
+        }
+
+        if ((dynamics.flags & ClothDynamicsFlags.SelfCollision) !== 0) {
+            // Half the shortest row, so the row's diameter is one particle
+            // spacing. `ClothState#self_radius` carries why the fabric's own
+            // thickness is the wrong length here and `MEASUREMENTS.md` §31 is the
+            // sweep that settled it. A fabric thicker than its proxy is coarse
+            // keeps its thickness — and is then clamped under the closest pair
+            // the proxy has with no row between them, because a diameter that
+            // reaches that pair puts a cloth which is not folded at all in
+            // permanent contact with itself (§36, §37).
+            state.self_radius = Math.min(
+                Math.max(dynamics.thickness, instance.shortest_row * CLOTH_SELF_RADIUS_MIN_RATIO),
+                instance.closest_free_pair * CLOTH_SELF_RADIUS_MAX_RATIO
+            );
+
+            instance.self_pairs = cloth_self_find(state, instance.self_exclusions);
+        } else {
+            state.self_count = 0;
+            instance.self_pairs = 0;
+        }
+
+        cloth_step(
+            state, dt,
+            LOCAL_GRAVITY[0], LOCAL_GRAVITY[1], LOCAL_GRAVITY[2],
+            dynamics.substeps, dynamics.iterations,
+            instance.collider_table, instance.collider_count
+        );
+
+        if (instance.stabilise_remaining > 0) {
+            // Ramp back from nothing over the window. The first step after a
+            // reset is allowed no velocity at all, which is what stops a
+            // re-seeded cloth from snapping taut and whipping.
+            limit *= (CLOTH_STABILISE_STEPS - instance.stabilise_remaining) / CLOTH_STABILISE_STEPS;
+
+            instance.stabilise_remaining--;
+        }
+
+        const speed = clamp_velocity(instance, limit);
+
+        if ((instance.cloth.flags & ClothFlags.NeverSleep) === 0) {
+            if (speed < CLOTH_SLEEP_SPEED_RATIO * instance.reach) {
+                instance.still_steps++;
+
+                if (instance.still_steps >= CLOTH_SLEEP_STEPS) {
+                    instance.asleep = true;
+                }
+            } else {
+                instance.still_steps = 0;
+            }
+        }
+
+        instance.blend_seen = instance.cloth.blend;
+
+        if (instance.rig === null) {
+            cloth_write_back(instance, ecd);
+        } else {
+            cloth_write_back_rig(instance, transform);
+        }
+    }
+
+    /**
+     * The anchor joint's world pose, computed on the CPU from the clips the
+     * entity is playing.
+     *
+     * **Computed, never read back**, for two reasons that are both the engine's
+     * own. A joint of an animated skeleton is under `TransformAuthority.GPU`,
+     * so nothing maintains its CPU-side `transform_global` and reading it gives
+     * whatever the node was last posed at by hand. And GPU readback is a frame
+     * late and asynchronous, so anything depending on it would depend on frame
+     * pacing — which is why `query_entity_node_world_pose` exists and is
+     * documented as the only sanctioned way to ask this question. A cape and a
+     * scabbard on the same shoulder get their answer from the same evaluator,
+     * off the same clock, which is what keeps them on the same shoulder.
+     *
+     * @param {ClothInstance} instance
+     * @returns {Transform64}
+     * @private
+     */
+    #anchor_pose(instance) {
+        const playbacks = PLAYBACKS;
+
+        playbacks.length = 0;
+
+        collect_entity_playbacks(playbacks, this.entityManager, instance.entity);
+
+        pose_evaluate_world(instance.anchor_pose, instance.node_joint[0], playbacks);
+
+        playbacks.length = 0;
+
+        return instance.anchor_pose;
+    }
+
+    /**
+     * @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;
+        }
+
+        const state = instance.state;
+
+        const node_count = instance.node_count;
+        const animated = instance.animated_position;
+        const particle_of_node = instance.particle_of_node;
+
+        for (let node = 0; node < node_count; node++) {
+            const p = particle_of_node[node] * 3;
+            const n = node * 3;
+
+            state.position[p] = animated[n];
+            state.position[p + 1] = animated[n + 1];
+            state.position[p + 2] = animated[n + 2];
+        }
+
+        state.position_previous.set(state.position);
+        state.velocity.fill(0);
+        state.inertia_blend.fill(0);
+
+        // The multipliers describe forces in a configuration that no longer
+        // exists. Carrying them across would apply the old pose's tension to
+        // the new one on the first iteration, which is a whip with extra steps.
+        state.stretch_lambda.fill(0);
+        state.bend_lambda.fill(0);
+        state.leash_lambda.fill(0);
+
+        instance.stabilise_remaining = CLOTH_STABILISE_STEPS;
+    }
+}
+
+/**
+ * The clip set handed to the pose evaluator, rebuilt per call from the
+ * animation systems' own entries. Nothing in here outlives the call.
+ * @type {PosePlayback[]}
+ * @private
+ */
+const PLAYBACKS = [];
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const LOCAL_GRAVITY = new Float64Array(3);
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const FRAME = new Float64Array(8);
+
+/**
+ * Carry the particles across a change of anchor 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
+ * `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
+ * teleports a metre — or spins — something a cape *lags behind* rather than
+ * something it is fired out of.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} tx
+ * @param {number} ty
+ * @param {number} tz
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @param {Float64Array} previous_translation
+ * @param {Float64Array} previous_rotation
+ * @private
+ */
+function move_local_frame(
+    instance,
+    tx, ty, tz, qx, qy, qz, qw,
+    previous_translation, previous_rotation
+) {
+    let inertia = instance.cloth.dynamics.inertia;
+
+    if (inertia <= 0) {
+        return;
+    }
+
+    if (inertia > 1) {
+        inertia = 1;
+    }
+
+    v3_quaternion_apply_inverse(
+        FRAME, 0,
+        previous_translation[0] - tx,
+        previous_translation[1] - ty,
+        previous_translation[2] - tz,
+        qx, qy, qz, qw
+    );
+
+    const travel_limit = CLOTH_ANCHOR_TRAVEL_REACH * instance.reach;
+
+    const travel = Math.hypot(FRAME[0], FRAME[1], FRAME[2]);
+
+    if (travel > travel_limit && travel > 0) {
+        const scale = travel_limit / travel;
+
+        FRAME[0] *= scale;
+        FRAME[1] *= scale;
+        FRAME[2] *= scale;
+    }
+
+    quat3_multiply(
+        FRAME, 4,
+        -qx, -qy, -qz, qw,
+        previous_rotation[0], previous_rotation[1], previous_rotation[2], previous_rotation[3]
+    );
+
+    // `|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(
+            FRAME, 4,
+            0, 0, 0, 1,
+            FRAME[4], FRAME[5], FRAME[6], FRAME[7],
+            CLOTH_ANCHOR_ROTATION_LIMIT / angle
+        );
+    }
+
+    const state = instance.state;
+
+    const particle_count = state.particle_count;
+
+    const position = state.position;
+    const velocity = state.velocity;
+
+    const dx = FRAME[0];
+    const dy = FRAME[1];
+    const dz = FRAME[2];
+
+    const rx = FRAME[4];
+    const ry = FRAME[5];
+    const rz = FRAME[6];
+    const rw = FRAME[7];
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        v3_quaternion_apply(CARRIED, 0, position[p], position[p + 1], position[p + 2], rx, ry, rz, rw);
+
+        position[p] += inertia * (CARRIED[0] + dx - position[p]);
+        position[p + 1] += inertia * (CARRIED[1] + dy - position[p + 1]);
+        position[p + 2] += inertia * (CARRIED[2] + dz - position[p + 2]);
+
+        v3_quaternion_apply(CARRIED, 0, velocity[p], velocity[p + 1], velocity[p + 2], rx, ry, rz, rw);
+
+        velocity[p] += inertia * (CARRIED[0] - velocity[p]);
+        velocity[p + 1] += inertia * (CARRIED[1] - velocity[p + 1]);
+        velocity[p + 2] += inertia * (CARRIED[2] - velocity[p + 2]);
+    }
+
+    // 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;
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const CARRIED = new Float64Array(3);
+
+/**
+ * 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];
+        }
+    }
+}
+
+/**
+ * Scale every particle's velocity, which is §7 P5's other half.
+ *
+ * The multiplier decay `α·γ` bleeds accumulated force out of a **hard** row,
+ * and a soft row has no multiplier to decay — M0 measured a soft cloth landing
+ * in a bounded limit cycle that 2,000 further steps do not move. This is what
+ * reaches it, and it is why `ClothDynamics#damping` is part of the correctness
+ * argument rather than a taste control. `MEASUREMENTS.md` §6.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} retention `[0, 1]`
+ * @private
+ */
+function damp(instance, retention) {
+    if (retention >= 1) {
+        return;
+    }
+
+    const velocity = instance.state.velocity;
+
+    for (let i = 0; i < velocity.length; i++) {
+        velocity[i] *= retention;
+    }
+}
+
+/**
+ * Hold every particle's speed under the limit derived from
+ * `ClothDynamics#thickness`, and report the largest speed left afterwards so
+ * the sleep test has something to read.
+ *
+ * §7 P1 names this clamp and M0 deliberately left it out, because a clamp would
+ * have masked the property M0 existed to measure. It is here rather than inside
+ * `cloth_step` for the same reason: the solver's stability is still its own.
+ *
+ * Speed rather than displacement is what the sleep test reads, because
+ * `position_previous` after a multi-substep step holds the start of the *last*
+ * substep rather than the start of the step, and a motion measure that quietly
+ * divides by the substep count is a sleep threshold that means something
+ * different for every fabric.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} limit m/s
+ * @returns {number} largest particle speed after clamping, m/s
+ * @private
+ */
+function clamp_velocity(instance, limit) {
+    const state = instance.state;
+
+    const particle_count = state.particle_count;
+
+    const velocity = state.velocity;
+
+    const limit_squared = limit * limit;
+
+    let worst_squared = 0;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const vx = velocity[p];
+        const vy = velocity[p + 1];
+        const vz = velocity[p + 2];
+
+        let speed_squared = vx * vx + vy * vy + vz * vz;
+
+        if (speed_squared > limit_squared) {
+            const scale = limit / Math.sqrt(speed_squared);
+
+            velocity[p] = vx * scale;
+            velocity[p + 1] = vy * scale;
+            velocity[p + 2] = vz * scale;
+
+            speed_squared = limit_squared;
+        }
+
+        if (speed_squared > worst_squared) {
+            worst_squared = speed_squared;
+        }
+    }
+
+    return Math.sqrt(worst_squared);
+}