@woosh/meep-engine 3.24.0 → 3.26.0

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

@@ -0,0 +1,1248 @@
+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 { EntityObserver } from "../../../ecs/EntityObserver.js";
+import {
+    TransformAttachment
+} from "../../../ecs/transform-attachment/TransformAttachment.js";
+import {
+    TransformAttachmentSystem
+} from "../../../ecs/transform-attachment/TransformAttachmentSystem.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../../../ecs/transform/Transform64.js";
+import { t64_evaluate_world } from "../../../ecs/transform/t64_evaluate_world.js";
+import {
+    collect_entity_playbacks
+} from "../../../graphics3/pose/collect_entity_playbacks.js";
+import { MeshSystem } from "../../../graphics3/MeshSystem.js";
+import { CLOTH_SELF_RADIUS_MAX_RATIO, CLOTH_SELF_RADIUS_MIN_RATIO } from "../solver/cloth_solver_constants.js";
+import { cloth_air_changed, cloth_sample_air } from "../wind/cloth_sample_air.js";
+import { ClothStepParam } from "../solver/cloth_step_instance.js";
+import { ClothStepResult } from "../solver/ClothState.js";
+import { ClothColliderSystem } from "./ClothColliderSystem.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_DISPLACEMENT_RATIO,
+    CLOTH_SLEEP_SPEED_RATIO,
+    CLOTH_SLEEP_STEPS,
+    CLOTH_STABILISE_STEPS,
+    CLOTH_TELEPORT_FLOOR,
+    CLOTH_TELEPORT_REACH,
+    cloth_drag_response,
+    cloth_velocity_limit,
+    cloth_velocity_retention
+} from "./cloth_dynamics_map.js";
+import {
+    cloth_colliders_moved,
+    cloth_gather_colliders,
+    cloth_gather_reach,
+    cloth_remember_colliders
+} from "./cloth_gather_colliders.js";
+import {
+    cloth_dynamics_change_needs_reseed,
+    cloth_reparameterise
+} from "./cloth_build_rows.js";
+import { Cloth } from "./Cloth.js";
+import { cloth_release_subtree, cloth_seed_subtree } from "./cloth_seed_subtree.js";
+import { cloth_release_rig, 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";
+
+/**
+ * # Every cloth in a scene, and everything a step needs that is not arithmetic
+ *
+ * One {@link ClothInstance} per {@link Cloth} component, stepped at the fixed
+ * rate. Per step, per cloth: move the local frame with the anchor, point the
+ * leash rows at where they measure from, gather the colliders that could touch
+ * it, step, and put the result back on the subtree. The animated pose the
+ * leashes are measured against is not recomposed per step — in the entity path
+ * it is constant in the anchor's own frame, and `cloth_seed_subtree.js` bakes
+ * it.
+ *
+ * ## Why this is not a `System`
+ *
+ * Because two of them drive it. {@link ClothSystem} steps every cloth inline;
+ * {@link WorkerClothSystem} hands the arithmetic to a worker and joins it on the
+ * next tick. §12 asks those two to produce **bit-identical** results, and the
+ * cheapest way to be sure of that is for there to be one copy of everything
+ * except the dispatch — so the registry, the seeding, the frame handling, the
+ * broadphase and the write-back live here, and the two systems differ only in
+ * where {@link ClothWorld#prepare} and {@link ClothWorld#finish} are separated
+ * by a thread.
+ *
+ * That split is also exactly §12's: "arbitrary user-facing work — component
+ * reads, `Transform64` sync, index queries — stays on the main thread; the pure
+ * numeric step crosses". {@link ensure_seeded} and {@link advance} are the first
+ * half, `cloth_step_instance` is the second, {@link finish} is what the result
+ * is worth.
+ *
+ * Seeding is its own call rather than the top of {@link advance} because the
+ * worker needs to get between them: a cloth's `ClothState` is what it registers
+ * with the worker, so it has to exist — and be acknowledged — before the cloth
+ * can be nominated for a step, and a re-seed replaces it and starts that again.
+ *
+ * ## The parameter block
+ *
+ * {@link prepare} does not call the step and does not return its arguments; it
+ * **writes them into a `Float64` block** the caller supplies. For
+ * {@link ClothSystem} that block is a private scratch array and the step follows
+ * immediately; for {@link WorkerClothSystem} it is a slice of the shared command
+ * region and the step happens on another thread. Neither system ever computes a
+ * step parameter of its own, so neither can compute one differently.
+ *
+ * ## 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.
+ *
+ * ## The wind — §10
+ *
+ * {@link wind} is a source of air and {@link advance} samples it into the
+ * cloth's own buffer, once per particle per step. That is the one piece of M6
+ * that stays on this thread: a fluid field is an ECS component holding a
+ * hundred thousand floats that its own solver rewrites every step, and the
+ * *answer* is three floats a particle. `cloth_sample_air.js` carries the
+ * decision; the aerodynamic arithmetic built on top of it lives in
+ * `cloth_step_instance` with everything else the budget is spent on.
+ *
+ * A source is optional and additive, like the collider index. With none, the
+ * step's drag response is zero, `cloth_step` takes the uniform-gravity path,
+ * and a scene produces the bytes M5 measured.
+ *
+ * ## 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 ClothWorld {
+
+    /**
+     * World gravity, m/s². Rotated into each cloth's local frame per step.
+     * @type {Float64Array}
+     */
+    gravity = new Float64Array([0, -9.81, 0]);
+
+    /**
+     * Live cloths, in the order they were linked.
+     *
+     * **Not sorted by hierarchy depth**, and it used to be. The sort existed so
+     * that a nested cloth advanced against an anchor the cloth above it had
+     * already written this step — which `WorkerClothSystem` cannot do, because
+     * the step it is writing back happened on another thread a tick ago. Both
+     * systems now advance every cloth, then step every cloth, then finish every
+     * cloth, so a nested cloth reads its parent one fixed step stale on both
+     * sides and the sort has nothing left to decide. `ClothSystem#fixedUpdate`
+     * carries the argument; `MEASUREMENTS.md` §56 carries the measurement.
+     * @type {ClothInstance[]}
+     */
+    instances = [];
+
+    /**
+     * Where a skinned model instance comes from. Anything that answers
+     * `instance_of(entity)` with a `PrefabInstance` — skins whose joints
+     * are entities — will do, and {@link MeshSystem} is what does in a
+     * running engine.
+     *
+     * Public and assignable because a garment's joints are a *rendering*
+     * structure and `MeshSystem` needs a graphics engine, a scene and a loader
+     * to exist — so a spec that wants joints without a renderer sets this
+     * instead, and gets exactly the interface the system uses.
+     *
+     * `null` means no rig can seed, which is the same additive shape the
+     * collider index has: a scene without one gets M1's cloth rather than an
+     * error.
+     * @type {{instance_of: function(number): (PrefabInstance|null)}|null}
+     */
+    models = null;
+
+    /**
+     * @type {EntityManager|null}
+     */
+    entityManager = null;
+
+    /**
+     * @type {TransformAttachmentSystem|null}
+     */
+    attachments = 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}
+     */
+    colliders = null;
+
+    /**
+     * Where the air comes from — §10. `null` means no air, which is the
+     * default and is **additive** in exactly the way the collider index is: a
+     * scene without one gets M5's cloth rather than an error, and adding one is
+     * the whole of turning wind on.
+     *
+     * Null rather than a still-air ambient, and the distinction is real. A
+     * source that answers zero everywhere is not "no wind": the drag row is a
+     * relaxation toward the air, so still air still resists a *moving* cloth,
+     * with the normal-facing factor making that resistance anisotropic. That is
+     * better physics than `ClothDynamics#damping`'s isotropic decay and it is
+     * not free — so it is a thing a scene asks for. What a cloth does in air
+     * that is not moving is `damping`'s job (§7 P5, where it is load-bearing);
+     * what it does in air that *is* is this.
+     *
+     * Assign {@link ClothAmbientWind} for weather, {@link ClothFluidWind} to
+     * read the fluid simulation and fall back to weather outside it.
+     * @type {AbstractClothWind|null}
+     */
+    wind = null;
+
+    /**
+     * Seconds of fixed step this world has **stepped**, which is the clock a
+     * wind source's gust is a function of.
+     *
+     * Accumulated from `dt` rather than read from a wall clock, because
+     * {@link ClothSystem} and {@link WorkerClothSystem} share this object and
+     * §12's parity gate is over every byte of every step: two runs of the same
+     * scene have the same `dt` sequence and therefore the same weather.
+     *
+     * **Stepped rather than ticked**, and that distinction is load-bearing
+     * rather than pedantic. A cloth under the worker is not advanced until its
+     * registration is acknowledged (§39), so the two systems reach a cloth's
+     * *first* step at different tick counts — and a clock that counted ticks
+     * would hand that cloth a different gust on the same step under the two
+     * systems, which is a divergence the parity gate would report and the design
+     * would deserve. So the clock moves when {@link advance} first runs in a
+     * tick: the world's weather is a function of how much cloth time has
+     * passed, not of how long something has been asking.
+     * @type {number}
+     */
+    time = 0;
+
+    /**
+     * Fixed-step seconds this tick owes the clock, consumed by the first
+     * {@link advance} — see {@link time}. Zero once spent.
+     * @type {number}
+     * @private
+     */
+    __wind_pending = 0;
+
+    /**
+     * Whether a cloth's {@link ClothState} must be backed by a
+     * `SharedArrayBuffer`. Stamped onto every instance as it is linked;
+     * {@link WorkerClothSystem} sets it, {@link ClothSystem} leaves it alone.
+     * @type {boolean}
+     */
+    shared_state = false;
+
+    /**
+     * @type {Map<number, ClothInstance>}
+     * @private
+     */
+    __by_entity = new Map();
+
+    /**
+     * Watches `Cloth` + {@link ClothRig} so the rig path is a **live**
+     * discriminator rather than one read once.
+     *
+     * `ClothSystem#dependencies` is `[Cloth, Transform64]` — the tuple that
+     * makes something a cloth — so a `ClothRig` added to a live cloth completes
+     * no tuple the system observes and a `ClothRig` removed from one breaks
+     * none. §3.1's "the discriminator is a component's presence" then holds only
+     * for a character spawned whole, which is the one case a spec constructs and
+     * the least likely one in a scene where a model loads asynchronously.
+     *
+     * Both edges re-seed. The removing edge also gives the joints back first,
+     * because the instance that knows which they were is about to stop being a
+     * rig.
+     * @type {EntityObserver}
+     * @private
+     */
+    __rig_observer = new EntityObserver(
+        [Cloth, ClothRig],
+        (cloth, rig, entity) => this.reseed(entity),
+        (cloth, rig, entity) => this.#rig_removed(entity),
+        this
+    );
+
+    /**
+     * Resolve the systems a cloth world reads. Called from the owning system's
+     * `startup`.
+     *
+     * @param {EntityManager} entityManager
+     */
+    attach(entityManager) {
+        this.entityManager = 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
+     * @returns {ClothInstance}
+     */
+    link(cloth, transform, entity) {
+        const instance = new ClothInstance();
+
+        instance.entity = entity;
+        instance.cloth = cloth;
+        instance.transform = transform;
+        instance.shared_state = this.shared_state;
+
+        this.instances.push(instance);
+        this.__by_entity.set(entity, instance);
+
+        return instance;
+    }
+
+    /**
+     * Watch this dataset for a {@link ClothRig} arriving at or leaving a live
+     * cloth. Called from the owning system's `handleDatasetAttached`; see
+     * {@link ClothWorld#__rig_observer} for why the system's own dependency
+     * tuple cannot answer this.
+     *
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    attach_dataset(dataset) {
+        dataset.addObserver(this.__rig_observer, true);
+    }
+
+    /**
+     * @param {EntityComponentDataset} dataset
+     * @returns {void}
+     */
+    detach_dataset(dataset) {
+        dataset.removeObserver(this.__rig_observer, false);
+    }
+
+    /**
+     * @param {number} entity
+     * @returns {ClothInstance|undefined} the instance that was removed
+     */
+    unlink(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return undefined;
+        }
+
+        // Give back what the seeding took. Seeding is not a read: it revokes
+        // the GPU's authority over a rig's joints, and it leaves the entity
+        // path's authored local transforms nowhere but inside the cloth,
+        // because `cloth_write_back` overwrites them every step. A cloth
+        // removed without this leaves joints nothing is writing and a subtree
+        // frozen in the shape the solver stopped in.
+        this.#release(instance);
+
+        this.__by_entity.delete(entity);
+
+        const index = this.instances.indexOf(instance);
+
+        if (index >= 0) {
+            this.instances.splice(index, 1);
+        }
+
+        return instance;
+    }
+
+    /**
+     * Hand back whatever this instance's seeding took from the scene.
+     *
+     * @param {ClothInstance} instance
+     * @private
+     */
+    #release(instance) {
+        if (!instance.seeded) {
+            return;
+        }
+
+        const ecd = this.entityManager === null ? null : this.entityManager.dataset;
+
+        if (ecd === null || ecd === undefined) {
+            return;
+        }
+
+        if (instance.rig === null) {
+            cloth_release_subtree(instance, ecd);
+        } else {
+            cloth_release_rig(instance, ecd);
+        }
+    }
+
+    /**
+     * A {@link ClothRig} has left a live cloth: give its joints back, then
+     * re-seed, which without a rig is the entity path.
+     *
+     * @param {number} entity
+     * @private
+     */
+    #rig_removed(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return;
+        }
+
+        this.#release(instance);
+
+        instance.rig = null;
+
+        this.reseed(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 {ClothInstance|undefined} the instance that will re-seed
+     */
+    reseed(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return undefined;
+        }
+
+        instance.seeded = false;
+        instance.anchor_valid = false;
+
+        return instance;
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * Everything that happens once per tick rather than once per cloth.
+     *
+     * @param {EntityComponentDataset} ecd
+     * @param {number} dt seconds
+     */
+    begin(ecd, dt) {
+        // Owed to the clock, and spent by the first `advance` — see {@link time}
+        // for why the two are not the same moment. Assigned rather than set, so a
+        // world whose source is taken away does not carry a debt.
+        this.__wind_pending = this.wind === null ? 0 : 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();
+        }
+    }
+
+    /**
+     * Make sure this cloth has a `ClothState` that matches its current
+     * `ClothDynamics`, seeding or re-seeding it if not.
+     *
+     * @param {ClothInstance} instance
+     * @param {EntityComponentDataset} ecd
+     * @param {number} dt seconds
+     * @returns {boolean} whether the cloth is ready to be stepped — `false` for
+     *   one that has been refused, or a rig whose model has not loaded yet
+     */
+    ensure_seeded(instance, ecd, dt) {
+        if (instance.refused) {
+            return false;
+        }
+
+        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.
+                return false;
+            }
+        } 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;
+        }
+
+        return true;
+    }
+
+    /**
+     * Take what the step produced: the sleep test, and the pose onto whichever
+     * hierarchy this cloth was built on.
+     *
+     * @param {ClothInstance} instance
+     * @param {EntityComponentDataset} ecd
+     * @returns {void}
+     */
+    finish(instance, ecd) {
+        const result = instance.state.result;
+
+        instance.contact_count = result[ClothStepResult.CONTACT_COUNT];
+        instance.self_pairs = result[ClothStepResult.SELF_PAIRS];
+
+        if ((instance.cloth.flags & ClothFlags.NeverSleep) === 0) {
+            if (cloth_inside_sleep_window(instance)) {
+                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, ecd);
+        }
+    }
+
+    /**
+     * 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) {
+            instance.rig = null;
+
+            cloth_seed_subtree(instance, ecd, this.attachments, dt);
+
+            return;
+        }
+
+        if (rig.proxy === null) {
+            // Present and not ready. The same branch as a model that has not
+            // loaded, and for the same reason: a proxy filled in a few ticks
+            // after the component is a rig that is arriving, not a rig that is
+            // absent. Treating it as absent walks the character's own transform
+            // subtree — which under a spawned model is the whole skeleton — and
+            // seeds a skeleton as one rope, throwing in a dev build through
+            // `gpu_authority_assert_cpu` and simulating it in a shipped one.
+            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, ecd, 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}`);
+    }
+
+    /**
+     * Carry one seeded cloth to the edge of its step and write the parameters
+     * the step will run on: whatever the anchor did to the local frame, where
+     * the leash rows measure from, and the colliders within reach.
+     *
+     * @param {ClothInstance} instance
+     * @param {number} dt seconds
+     * @param {Float64Array} params
+     * @param {number} offset first word of this cloth's block in `params`
+     * @returns {boolean} whether the cloth should be stepped — `false` for one
+     *   that is asleep, and then nothing has been written to `params`
+     */
+    advance(instance, dt, params, offset) {
+        // This cloth's own clock, moved before anything reads it — including
+        // the wake tests below, which are asking about the step that would
+        // follow. See {@link ClothInstance#age}.
+        instance.age += dt;
+
+        if (this.__wind_pending !== 0) {
+            this.time += this.__wind_pending;
+
+            this.__wind_pending = 0;
+
+            // Once a tick rather than once a cloth: a source that reads the
+            // dataset — every live fluid field and its world box — walks it here
+            // and every cloth then reads the cache. `FluidSystem` makes the same
+            // trade for its own effector broadphase.
+            //
+            // Here rather than in `begin` because of the clock, and {@link time}
+            // is where that is argued. Above the sleep tests deliberately: a
+            // world whose every cloth is asleep still has weather, and §10's
+            // "sleep wakes on a wind change" is the whole reason it needs to.
+            if (this.wind !== null) {
+                this.wind.begin(
+                    this.time,
+                    this.entityManager === null ? null : this.entityManager.dataset
+                );
+            }
+        }
+
+        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.state !== null) {
+            // §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 && this.wind !== null && instance.state !== null
+            && instance.cloth.dynamics.drag > 0) {
+            // §10's "sleep wakes on a wind change, so a settled banner does not
+            // sleep through a gust". One sample at the cloth's centre against
+            // the air the last applied step saw — the same shape as the collider
+            // test above, and the same argument: asking is orders of magnitude
+            // cheaper than the step it decides whether to skip.
+            if (cloth_air_changed(
+                instance.state, this.wind,
+                instance.anchor_translation, instance.anchor_rotation,
+                instance.air_seen, CLOTH_SLEEP_SPEED_RATIO * instance.reach,
+                instance.age
+            )) {
+                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 false;
+        }
+
+        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;
+
+        // 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;
+
+        const 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 what the narrowphase will reach for and
+            // nothing beyond it — `cloth_gather_reach` carries the derivation,
+            // and why the velocity clamp that used to stand here was both far
+            // too wide and missing two terms.
+            const reach = cloth_gather_reach(state, this.colliders.index, dt);
+
+            cloth_gather_colliders(instance, this.colliders.index, reach);
+
+            // What this cloth is about to step against, for the next wake test
+            // to compare with. Here rather than inside the gather because the
+            // wake test gathers too, and what it asks about is the set the last
+            // *step* saw.
+            cloth_remember_colliders(instance, reach);
+        } else {
+            state.collider_count = 0;
+
+            instance.collider_key_count = 0;
+        }
+
+        // §10. The one piece of a cloth's step that has to read the world and
+        // cannot cross to a worker, so it runs here in both systems and what
+        // crosses is the answer — three floats a particle, written into a region
+        // of the cloth's own shared buffer. `cloth_sample_air.js` is the
+        // argument.
+        let drag_response = 0;
+
+        if (this.wind !== null && dynamics.drag > 0) {
+            drag_response = cloth_drag_response(dynamics.drag, dt);
+
+            instance.air_varies = cloth_sample_air(
+                state, this.wind,
+                instance.anchor_translation, instance.anchor_rotation,
+                instance.air_seen, instance.age
+            );
+        } else {
+            instance.air_varies = false;
+        }
+
+        params[offset + ClothStepParam.DRAG_RESPONSE] = drag_response;
+
+        const self_collision = (dynamics.flags & ClothDynamicsFlags.SelfCollision) !== 0;
+
+        params[offset + ClothStepParam.DT] = dt;
+        params[offset + ClothStepParam.GRAVITY_X] = LOCAL_GRAVITY[0];
+        params[offset + ClothStepParam.GRAVITY_Y] = LOCAL_GRAVITY[1];
+        params[offset + ClothStepParam.GRAVITY_Z] = LOCAL_GRAVITY[2];
+        params[offset + ClothStepParam.SUBSTEPS] = dynamics.substeps;
+        params[offset + ClothStepParam.ITERATIONS] = dynamics.iterations;
+        params[offset + ClothStepParam.RETENTION] = cloth_velocity_retention(dynamics.damping, dt);
+        params[offset + ClothStepParam.CONTACT_RADIUS] = dynamics.thickness;
+        params[offset + ClothStepParam.COLLIDER_COUNT] = state.collider_count;
+        params[offset + ClothStepParam.SELF_COLLISION] = self_collision ? 1 : 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).
+        params[offset + ClothStepParam.SELF_RADIUS] = self_collision
+            ? Math.min(
+                Math.max(dynamics.thickness, instance.shortest_row * CLOTH_SELF_RADIUS_MIN_RATIO),
+                instance.closest_free_pair * CLOTH_SELF_RADIUS_MAX_RATIO
+            )
+            : 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.
+        //
+        // After the gather, which wants the cloth's *unramped* reach: the
+        // broadphase margin is how far a particle could travel, and a cloth
+        // that is being held still for three steps is still a cloth whose
+        // colliders have to be found before it is let go.
+        let clamp_limit = limit;
+
+        if (instance.stabilise_remaining > 0) {
+            clamp_limit *= (CLOTH_STABILISE_STEPS - instance.stabilise_remaining) / CLOTH_STABILISE_STEPS;
+
+            instance.stabilise_remaining--;
+        }
+
+        params[offset + ClothStepParam.VELOCITY_LIMIT] = clamp_limit;
+
+        return true;
+    }
+
+    /**
+     * 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 the GPU's (`GPUStateAuthority`),
+     * so nothing maintains its CPU-side world and reading it gives its rest
+     * pose under whatever the CPU last composed. 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);
+
+        t64_evaluate_world(instance.anchor_pose, this.entityManager.dataset, 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);
+
+/**
+ * Whether every particle is still within the sleep window's own anchor — §7
+ * P5's "maximum particle displacement over a window", and the reason the test
+ * is not the instantaneous speed it used to be.
+ *
+ * A cloth **resting on a collider** does not stop: its contact rows carry a
+ * penalty that `γ = 1` never decays, and what it settles into is a bounded
+ * limit cycle. Measured on an 8-link rope on a floor, that is a tenth of a
+ * millimetre of travel a step — nothing anyone can see — at a peak speed of
+ * 1.5e-2 m/s, eighteen times the threshold a speed test allowed. So the speed
+ * test held four of the seven library fabrics awake indefinitely on a floor
+ * while the same fabrics slept in 283 steps hanging free. Distance covered
+ * since the window opened tells those two apart; a speed sampled at one instant
+ * cannot. `MEASUREMENTS.md` §53.
+ *
+ * The anchor is re-taken whenever a particle leaves the threshold, so the
+ * window measures "how far has anything moved since the cloth last moved"
+ * rather than chopping time into fixed epochs a slow drift could hide inside.
+ *
+ * @param {ClothInstance} instance
+ * @returns {boolean}
+ * @private
+ */
+function cloth_inside_sleep_window(instance) {
+    const position = instance.state.position;
+
+    let reference = instance.sleep_reference;
+
+    if (reference === null || reference.length !== position.length) {
+        // First step, or a re-seed that changed the particle count. There is no
+        // window yet, so this step opens one.
+        instance.sleep_reference = Float32Array.from(position);
+
+        return false;
+    }
+
+    const threshold = CLOTH_SLEEP_DISPLACEMENT_RATIO * instance.reach;
+
+    const threshold_squared = threshold * threshold;
+
+    const particle_count = instance.state.particle_count;
+
+    for (let i = 0; i < particle_count; i++) {
+        const p = i * 3;
+
+        const dx = position[p] - reference[p];
+        const dy = position[p + 1] - reference[p + 1];
+        const dz = position[p + 2] - reference[p + 2];
+
+        if (dx * dx + dy * dy + dz * dz > threshold_squared) {
+            reference.set(position);
+
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Point every leash row at where it measures from: a slack row at the
+ * particle's animated position, a tether at the anchor.
+ *
+ * @param {ClothInstance} instance
+ * @private
+ */
+function refresh_leash_targets(instance) {
+    const state = instance.state;
+
+    const target = state.leash_target;
+
+    const animated = instance.animated_position;
+
+    const anchor = instance.particle_of_node[0] * 3;
+
+    const anchor_x = state.position[anchor];
+    const anchor_y = state.position[anchor + 1];
+    const anchor_z = state.position[anchor + 2];
+
+    const node_count = instance.node_count;
+
+    const slack_row = instance.slack_row;
+    const tether_row = instance.tether_row;
+
+    for (let node = 1; node < node_count; node++) {
+        const tether = tether_row[node];
+
+        if (tether >= 0) {
+            target[tether * 3] = anchor_x;
+            target[tether * 3 + 1] = anchor_y;
+            target[tether * 3 + 2] = anchor_z;
+        }
+
+        const slack = slack_row[node];
+
+        if (slack >= 0) {
+            target[slack * 3] = animated[node * 3];
+            target[slack * 3 + 1] = animated[node * 3 + 1];
+            target[slack * 3 + 2] = animated[node * 3 + 2];
+        }
+    }
+}