@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -1,74 +1,30 @@
-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 { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { CLOTH_STEP_PARAM_STRIDE, cloth_step_instance } from "../solver/cloth_step_instance.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";
+import { ClothWorld } from "./ClothWorld.js";
 
 /**
- * # The system — gather, step, write back
+ * # The system — gather, step, write back, all on this thread
+ *
+ * Every cloth in the scene stepped inline at the fixed rate. The work itself
+ * lives in {@link ClothWorld}, which this shares with {@link WorkerClothSystem}
+ * so that §12's "`ClothSystem` and `WorkerClothSystem` must produce bit-identical
+ * results" is a property of there being one copy rather than of two copies
+ * agreeing. What is left here is a `System`'s own surface — what it depends on,
+ * what it accesses, and the loop.
  *
- * 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.
+ * This is the fallback where `SharedArrayBuffer` is unavailable, and it is **not
+ * a degraded mode**: it is the same solver over the same data in the same
+ * order, and the only thing the worker buys is which thread pays for it.
  *
  * ## Where in the frame this runs
  *
@@ -99,29 +55,6 @@ import { cloth_write_back_rig } from "./cloth_write_back_rig.js";
  * 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
  */
@@ -139,82 +72,83 @@ export class ClothSystem extends System {
     ];
 
     /**
-     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @type {ClothWorld}
+     */
+    world = new ClothWorld();
+
+    /**
+     * One cloth's step parameters, reused for every cloth in turn because the
+     * step follows immediately.
+     *
+     * The same block {@link WorkerClothSystem} writes into the shared command
+     * region — one layout, written by one function, so the inline path and the
+     * worker path cannot be handed different numbers.
      * @type {Float64Array}
+     * @private
      */
-    gravity = new Float64Array([0, -9.81, 0]);
+    __params = new Float64Array(CLOTH_STEP_PARAM_STRIDE);
 
     /**
-     * Live cloths, ordered so that an instance whose anchor sits inside another
-     * instance's subtree steps after it.
-     * @type {ClothInstance[]}
+     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @returns {Float64Array}
      */
-    instances = [];
+    get gravity() {
+        return this.world.gravity;
+    }
 
     /**
-     * @type {Map<number, ClothInstance>}
-     * @private
+     * @param {Float64Array} value
      */
-    __by_entity = new Map();
+    set gravity(value) {
+        this.world.gravity = value;
+    }
 
     /**
-     * @type {TransformAttachmentSystem|null}
-     * @private
+     * Where the air comes from — see {@link ClothWorld#wind}. `null` by default,
+     * which is a scene with no wind in it.
+     * @returns {AbstractClothWind|null}
      */
-    __attachments = null;
+    get wind() {
+        return this.world.wind;
+    }
 
     /**
-     * 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}
+     * @param {AbstractClothWind|null} value
      */
-    models = null;
+    set wind(value) {
+        this.world.wind = value;
+    }
 
     /**
-     * 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
+     * Live cloths, ordered so that an instance whose anchor sits inside another
+     * instance's subtree steps after it.
+     * @returns {ClothInstance[]}
      */
-    __colliders = null;
+    get instances() {
+        return this.world.instances;
+    }
 
     /**
-     * @type {boolean}
-     * @private
+     * Where a skinned model instance comes from — see {@link ClothWorld#models}.
+     * @returns {{instance_of: function(number): (PrefabInstance|null)}|null}
      */
-    __order_dirty = false;
+    get models() {
+        return this.world.models;
+    }
+
+    /**
+     * @param {{instance_of: function(number): (PrefabInstance|null)}|null} value
+     */
+    set models(value) {
+        this.world.models = value;
+    }
 
     /**
      * @param {EntityManager} entityManager
      * @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;
-        }
+        this.world.attach(entityManager);
     }
 
     /**
@@ -223,16 +157,7 @@ export class ClothSystem extends System {
      * @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;
+        this.world.link(cloth, transform, entity);
     }
 
     /**
@@ -241,61 +166,25 @@ export class ClothSystem extends System {
      * @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);
-        }
+        this.world.unlink(entity);
     }
 
     /**
      * 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;
+        this.world.reseed(entity);
     }
 
     /**
-     * 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.
-     *
+     * Wake a sleeping cloth.
      * @param {number} entity
      * @returns {void}
      */
     wake(entity) {
-        const instance = this.__by_entity.get(entity);
-
-        if (instance !== undefined) {
-            instance.asleep = false;
-            instance.still_steps = 0;
-        }
+        this.world.wake(entity);
     }
 
     /**
@@ -303,7 +192,7 @@ export class ClothSystem extends System {
      * @returns {ClothInstance|undefined}
      */
     instanceOf(entity) {
-        return this.__by_entity.get(entity);
+        return this.world.instanceOf(entity);
     }
 
     /**
@@ -316,706 +205,28 @@ export class ClothSystem extends System {
             return;
         }
 
-        const instances = this.instances;
+        const world = this.world;
 
-        if (this.__order_dirty) {
-            this.#reorder(ecd);
-        }
+        world.begin(ecd, dt);
 
-        // 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();
-        }
+        const instances = world.instances;
 
-        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;
+        const params = this.__params;
 
         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 (!world.ensure_seeded(instance, ecd, dt)) {
+                continue;
             }
-        }
-
-        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;
+            if (!world.advance(instance, dt, params, 0)) {
+                continue;
             }
-        }
-
-        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];
+            cloth_step_instance(instance.state, instance.self_exclusions, params, 0);
 
-    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;
+            world.finish(instance, ecd);
         }
     }
-
-    return Math.sqrt(worst_squared);
 }