@woosh/meep-engine 3.21.0 → 3.22.0

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

@@ -0,0 +1,773 @@
+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);
+}