@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -1,363 +1,479 @@
-import { ClothDynamics } from "./ClothDynamics.js";
-
-/**
- * # One live cloth — the binding between a subtree and a `ClothState`
- *
- * Everything {@link ClothSystem} needs to step one {@link Cloth} and put the
- * answer back where it came from. It is a struct: no behaviour, and every array
- * is indexed by **node**, which is the entity's position in the subtree walk
- * rather than its position in the solver.
- *
- * ## Two numberings, and why they are not the same one
- *
- * `ClothState` permutes its particles into colour order and never gives that up
- * — the sweep is a pair of counted loops over adjacent indices precisely
- * because it does. So a node index and a particle index are different things,
- * and {@link particle_of_node} is the only place they meet. Everything on this
- * object is in node order; everything in `state` is in particle order; the
- * write-back crosses once per node per step and nothing else ever does.
- *
- * ## The local frame
- *
- * Particle positions live in the **anchor's own frame** — rigid, so translation
- * and rotation but not scale, following the same convention the colliders use.
- * That is what makes §7 P7's inertia model natural (a cloth that feels none of
- * its anchor's motion is one whose local coordinates simply do not change) and,
- * as a consequence rather than as a goal, what makes `Float32` positions ample:
- * the coordinates are garment-sized rather than world-sized.
- *
- * The anchor is node 0, particle `particle_of_node[0]`, sits at the local
- * origin, and is pinned. §11.1's "the anchor entity itself is the fixed set" is
- * that sentence.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class ClothInstance {
-
-    /**
-     * The entity carrying the {@link Cloth} component — the anchor.
-     * @type {number}
-     */
-    entity = -1;
-
-    /**
-     * @type {Cloth|null}
-     */
-    cloth = null;
-
-    /**
-     * The anchor's world transform, which is also the cloth's local frame.
-     * @type {Transform64|null}
-     */
-    transform = null;
-
-    /**
-     * How deep the anchor sits in the transform hierarchy. Instances step in
-     * ascending depth so that a `Cloth` nested inside another one reads an
-     * anchor the outer solve has already written this step.
-     * @type {number}
-     */
-    depth = 0;
-
-    /**
-     * `false` until the subtree has been walked. Seeding is deferred to the
-     * first step rather than done at link, because a rope's links arrive as
-     * separate entities and the one carrying the `Cloth` has no reason to be
-     * last.
-     * @type {boolean}
-     */
-    seeded = false;
-
-    /**
-     * @type {ClothState|null}
-     */
-    state = null;
-
-    /**
-     * @type {number}
-     */
-    node_count = 0;
-
-    /**
-     * Entity per node, in walk order. Node 0 is the anchor.
-     * @type {Int32Array|null}
-     */
-    node_entity = null;
-
-    /**
-     * Parent node index, `−1` for the anchor.
-     * @type {Int32Array|null}
-     */
-    node_parent = null;
-
-    /**
-     * Live `Transform64` per node — the component instance, held so the step
-     * does not go through the dataset per node per frame.
-     * @type {Transform64[]}
-     */
-    node_transform = [];
-
-    /**
-     * Live `TransformAttachment` per node; `null` for the anchor.
-     *
-     * **While a cloth is live this is its output, not its input.** The
-     * write-back writes the local transform as well as the world one, so that a
-     * hierarchy recomposition reproduces the simulated pose rather than
-     * replacing it with the authored one — which is what makes the cloth's
-     * correctness independent of where the scheduler put it. The authored pose
-     * is captured once, at seed, into {@link rest_local_position} and
-     * {@link rest_local_rotation}, and lives in the cloth from then on.
-     * @type {TransformAttachment[]}
-     */
-    node_attachment = [];
-
-    /**
-     * The authored local translation of each node, captured at seed, 3 per node.
-     * Nothing else holds it once the first write-back has run.
-     * @type {Float32Array|null}
-     */
-    rest_local_position = null;
-
-    /**
-     * The authored local rotation of each node, captured at seed, 4 per node.
-     * @type {Float32Array|null}
-     */
-    rest_local_rotation = null;
-
-    /**
-     * CSR offsets into {@link node_child}, `node_count + 1` entries.
-     * @type {Int32Array|null}
-     */
-    node_child_offset = null;
-
-    /**
-     * Simulated children per node, node indices.
-     * @type {Int32Array|null}
-     */
-    node_child = null;
-
-    /**
-     * Entities the walk pruned — the root of a {@link ClothExclude} subtree, or
-     * a nested {@link Cloth}'s anchor — paired with {@link pruned_parent}.
-     *
-     * They are not particles, and they still have to move: each one composes
-     * against a link the solver just wrote. The write-back therefore poses each
-     * of them by hand and announces there, which reaches everything below them
-     * through the ordinary attachment cascade and reaches nothing above them.
-     * @type {Int32Array|null}
-     */
-    pruned_entity = null;
-
-    /**
-     * Node each pruned entity hangs off.
-     * @type {Int32Array|null}
-     */
-    pruned_parent = null;
-
-    /**
-     * @type {number}
-     */
-    pruned_count = 0;
-
-    /**
-     * Live `Transform64` per pruned entity.
-     * @type {Transform64[]}
-     */
-    pruned_transform = [];
-
-    /**
-     * Live `TransformAttachment` per pruned entity — the local transform
-     * this pass composes against the link the cloth just solved.
-     * @type {TransformAttachment[]}
-     */
-    pruned_attachment = [];
-
-    /**
-     * Solver particle for each node.
-     * @type {Int32Array|null}
-     */
-    particle_of_node = null;
-
-    /**
-     * Geodesic distance from the anchor to each node, metres — the sum of the
-     * rest link lengths along the path, not the straight-line distance.
-     *
-     * This one array drives the tether radius, the slack profile and the pin,
-     * so the three cannot disagree (§3.4). The anchor's is zero, which is what
-     * makes it the fixed set without a second mechanism saying so.
-     * @type {Float32Array|null}
-     */
-    geodesic = null;
-
-    /**
-     * The animated pose in the cloth's local frame — position, 3 per node —
-     * composed once at seed from {@link rest_local_position} down the walk.
-     *
-     * **Constant, and that is a property of the entity path rather than an
-     * optimisation.** The subtree's authored pose is rigid relative to its
-     * anchor, so expressed in the anchor's own frame it does not move; the only
-     * thing that changes step to step is where that frame is. A subtree whose
-     * links are themselves animated is not an M1 case — that is the rig path,
-     * where the animated pose comes from the skeleton (§11.2) and is live.
-     * @type {Float32Array|null}
-     */
-    animated_position = null;
-
-    /**
-     * The animated pose's orientation in the cloth's local frame, 4 per node.
-     * @type {Float32Array|null}
-     */
-    animated_rotation = null;
-
-    /**
-     * The pose the write-back actually writes: the simulated position lerped
-     * towards the animated one by {@link Cloth#blend}, in node order and in
-     * the local frame, 3 per node.
-     *
-     * It exists as an array rather than as a per-node temporary because the
-     * orientation reconstruction needs a node's *neighbours* in the same
-     * blended pose, and blending them twice — once as a neighbour, once as
-     * themselves — is how a rounding difference becomes a visible kink.
-     * @type {Float64Array|null}
-     */
-    blended_position = null;
-
-    /**
-     * The orientation the write-back reconstructed for each node, in the cloth's
-     * local frame, 4 per node.
-     *
-     * Kept for the length of the pass because a node's **local** transform is
-     * its pose relative to its parent's, so writing it needs the parent's
-     * reconstructed rotation — and the walk is breadth-first, so by the time a
-     * node is reached its parent is already in here.
-     * @type {Float64Array|null}
-     */
-    blended_rotation = null;
-
-    /**
-     * Leash row enforcing the slack bound for each node, `−1` where there is
-     * none — the anchor, and any node whose `slack` reaches the bound at which
-     * the row is provably inactive.
-     * @type {Int32Array|null}
-     */
-    slack_row = null;
-
-    /**
-     * Leash row enforcing the tether bound for each node, `−1` for the anchor.
-     * @type {Int32Array|null}
-     */
-    tether_row = null;
-
-    /**
-     * Stretch rows carrying the parent link of each node, `−1` for the anchor.
-     * @type {Int32Array|null}
-     */
-    link_row = null;
-
-    /**
-     * Strain-limit rows on the same links, `−1` when the flag is clear.
-     * @type {Int32Array|null}
-     */
-    strain_row = null;
-
-    /**
-     * Skip rows — the bending model for a chain, one per node that has a
-     * grandparent. `−1` where there is none.
-     * @type {Int32Array|null}
-     */
-    skip_row = null;
-
-    /**
-     * Largest {@link geodesic} in the cloth: how far this cloth can reach from
-     * its anchor, and the length scale the anchor limits and the teleport
-     * threshold are derived from.
-     * @type {number}
-     */
-    reach = 0;
-
-    /**
-     * Shortest row in the cloth, metres.
-     *
-     * The trust region caps a vertex update at the shortest row incident on
-     * that particle (§5.3), so this is the smallest distance any particle can
-     * be moved in one iteration — and `shortest_row · substeps · iterations`
-     * is therefore the whole of what one fixed step can undo. The velocity
-     * clamp is a multiple of it.
-     * @type {number}
-     */
-    shortest_row = 0;
-
-    /**
-     * The anchor's world translation as of the previous step, `[x, y, z]`.
-     * @type {Float64Array}
-     */
-    anchor_translation = new Float64Array(3);
-
-    /**
-     * The anchor's world rotation as of the previous step, `[x, y, z, w]`.
-     * @type {Float64Array}
-     */
-    anchor_rotation = new Float64Array([0, 0, 0, 1]);
-
-    /**
-     * `false` until the first step has recorded an anchor pose to compare
-     * against. The first step feels no inertia, which is correct: there is no
-     * motion yet, only a starting place.
-     * @type {boolean}
-     */
-    anchor_valid = false;
-
-    /**
-     * What {@link Cloth#dynamics} looked like when the rows were last
-     * parameterised. Compared rather than watched — a value object is cheap to
-     * compare and a dirty flag is a second thing to keep true.
-     * @type {ClothDynamics}
-     */
-    dynamics_seen = new ClothDynamics();
-
-    /**
-     * Steps remaining in the post-teleport stabilisation window, during which
-     * the velocity limit ramps back up from nothing (§7 P6). Zero when not
-     * stabilising.
-     * @type {number}
-     */
-    stabilise_remaining = 0;
-
-    /**
-     * Consecutive steps whose largest particle displacement was below the sleep
-     * threshold.
-     * @type {number}
-     */
-    still_steps = 0;
-
-    /**
-     * `true` while the cloth is neither stepped nor written back (§7 P5).
-     *
-     * The write-back is skipped as well as the step, and that is the whole of
-     * what makes P5's "bit-identical across the following 300 steps" a fact
-     * rather than a hope: a pose that is not rewritten cannot drift, and one
-     * that is rewritten from unchanged inputs is only *probably* identical.
-     * @type {boolean}
-     */
-    asleep = false;
-
-    /**
-     * What {@link Cloth#blend} was when the write-back last ran.
-     *
-     * Sleep skips the write-back, so a `blend` written while a cloth is asleep
-     * would otherwise take effect at some arbitrary later moment — the next
-     * time something else happened to wake it. A blend change is a request to
-     * see a different pose, so it wakes the cloth like any other.
-     * @type {number}
-     */
-    blend_seen = 1;
-
-    /**
-     * How many times this cloth has been re-seeded by a teleport. Diagnostic:
-     * a cloth resetting every few seconds is being driven by something that
-     * looks like a teleport and is not one.
-     * @type {number}
-     */
-    teleport_count = 0;
-}
+import { Transform64 } from "../../../ecs/transform/Transform64.js";
+import { ClothDynamics } from "./ClothDynamics.js";
+
+/**
+ * # One live cloth — the binding between a subtree and a `ClothState`
+ *
+ * Everything {@link ClothSystem} needs to step one {@link Cloth} and put the
+ * answer back where it came from. It is a struct: no behaviour, and every array
+ * is indexed by **node**, which is the entity's position in the subtree walk
+ * rather than its position in the solver.
+ *
+ * ## Two numberings, and why they are not the same one
+ *
+ * `ClothState` permutes its particles into colour order and never gives that up
+ * — the sweep is a pair of counted loops over adjacent indices precisely
+ * because it does. So a node index and a particle index are different things,
+ * and {@link particle_of_node} is the only place they meet. Everything on this
+ * object is in node order; everything in `state` is in particle order; the
+ * write-back crosses once per node per step and nothing else ever does.
+ *
+ * ## The local frame
+ *
+ * Particle positions live in the **anchor's own frame** — rigid, so translation
+ * and rotation but not scale, following the same convention the colliders use.
+ * That is what makes §7 P7's inertia model natural (a cloth that feels none of
+ * its anchor's motion is one whose local coordinates simply do not change) and,
+ * as a consequence rather than as a goal, what makes `Float32` positions ample:
+ * the coordinates are garment-sized rather than world-sized.
+ *
+ * The anchor is node 0, particle `particle_of_node[0]`, sits at the local
+ * origin, and is pinned. §11.1's "the anchor entity itself is the fixed set" is
+ * that sentence.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothInstance {
+
+    /**
+     * The entity carrying the {@link Cloth} component — the anchor.
+     * @type {number}
+     */
+    entity = -1;
+
+    /**
+     * @type {Cloth|null}
+     */
+    cloth = null;
+
+    /**
+     * The anchor's world transform, which is also the cloth's local frame.
+     * @type {Transform64|null}
+     */
+    transform = null;
+
+    /**
+     * How deep the anchor sits in the transform hierarchy. Instances step in
+     * ascending depth so that a `Cloth` nested inside another one reads an
+     * anchor the outer solve has already written this step.
+     * @type {number}
+     */
+    depth = 0;
+
+    /**
+     * `false` until the subtree has been walked. Seeding is deferred to the
+     * first step rather than done at link, because a rope's links arrive as
+     * separate entities and the one carrying the `Cloth` has no reason to be
+     * last.
+     * @type {boolean}
+     */
+    seeded = false;
+
+    /**
+     * @type {ClothState|null}
+     */
+    state = null;
+
+    /**
+     * @type {number}
+     */
+    node_count = 0;
+
+    /**
+     * Entity per node, in walk order. Node 0 is the anchor.
+     * @type {Int32Array|null}
+     */
+    node_entity = null;
+
+    /**
+     * Parent node index, `−1` for the anchor.
+     * @type {Int32Array|null}
+     */
+    node_parent = null;
+
+    /**
+     * The {@link ClothRig} beside the {@link Cloth}, or `null` for a cloth that
+     * simulates its own entity subtree.
+     *
+     * This is the discriminator, and it is a component's presence rather than
+     * an enum (§3.1). Held here rather than looked up per step because it is
+     * what says which seeder ran and therefore which of the two sets of arrays
+     * below is the live one.
+     * @type {ClothRig|null}
+     */
+    rig = null;
+
+    /**
+     * Live `Transform64` per node — the component instance, held so the step
+     * does not go through the dataset per node per frame. **Entity path only.**
+     * @type {Transform64[]}
+     */
+    node_transform = [];
+
+    /**
+     * Live `Node3D` per node — the joint each node drives. **Rig path only**,
+     * and node 0 is the anchor joint, which is not simulated.
+     *
+     * A joint rather than an entity because a skinned model's joints are not
+     * entities and will not be (D47): they are `Node3D`s inside the entity's
+     * `SceneBundleInstance`, and the only writable handle is
+     * `Node3D.transform_local`.
+     * @type {Node3D[]}
+     */
+    node_joint = [];
+
+    /**
+     * The anchor joint's **world** pose, evaluated on the CPU each step from the
+     * clips the entity is playing. **Rig path only.**
+     *
+     * Evaluated rather than read: a joint of an animated skeleton is under
+     * `TransformAuthority.GPU`, so its own `transform_global` is not maintained
+     * on the CPU at all and reading it would place the garment wherever the node
+     * was last posed by hand. `pose_evaluate_world` is the sanctioned answer and
+     * the one a socket on the same skeleton gets, which is what keeps a cape on
+     * the shoulder a scabbard hangs from.
+     * @type {Transform64}
+     */
+    anchor_pose = new Transform64();
+
+    /**
+     * Live `TransformAttachment` per node; `null` for the anchor.
+     *
+     * **While a cloth is live this is its output, not its input.** The
+     * write-back writes the local transform as well as the world one, so that a
+     * hierarchy recomposition reproduces the simulated pose rather than
+     * replacing it with the authored one — which is what makes the cloth's
+     * correctness independent of where the scheduler put it. The authored pose
+     * is captured once, at seed, into {@link rest_local_position} and
+     * {@link rest_local_rotation}, and lives in the cloth from then on.
+     * @type {TransformAttachment[]}
+     */
+    node_attachment = [];
+
+    /**
+     * The authored local translation of each node, captured at seed, 3 per node.
+     * Nothing else holds it once the first write-back has run.
+     * @type {Float32Array|null}
+     */
+    rest_local_position = null;
+
+    /**
+     * The authored local rotation of each node, captured at seed, 4 per node.
+     * @type {Float32Array|null}
+     */
+    rest_local_rotation = null;
+
+    /**
+     * CSR offsets into {@link node_child}, `node_count + 1` entries.
+     * @type {Int32Array|null}
+     */
+    node_child_offset = null;
+
+    /**
+     * Simulated children per node, node indices.
+     * @type {Int32Array|null}
+     */
+    node_child = null;
+
+    /**
+     * Entities the walk pruned — the root of a {@link ClothExclude} subtree, or
+     * a nested {@link Cloth}'s anchor — paired with {@link pruned_parent}.
+     *
+     * They are not particles, and they still have to move: each one composes
+     * against a link the solver just wrote. The write-back therefore poses each
+     * of them by hand and announces there, which reaches everything below them
+     * through the ordinary attachment cascade and reaches nothing above them.
+     * @type {Int32Array|null}
+     */
+    pruned_entity = null;
+
+    /**
+     * Node each pruned entity hangs off.
+     * @type {Int32Array|null}
+     */
+    pruned_parent = null;
+
+    /**
+     * @type {number}
+     */
+    pruned_count = 0;
+
+    /**
+     * Live `Transform64` per pruned entity.
+     * @type {Transform64[]}
+     */
+    pruned_transform = [];
+
+    /**
+     * Live `TransformAttachment` per pruned entity — the local transform
+     * this pass composes against the link the cloth just solved.
+     * @type {TransformAttachment[]}
+     */
+    pruned_attachment = [];
+
+    /**
+     * Solver particle for each node.
+     * @type {Int32Array|null}
+     */
+    particle_of_node = null;
+
+    /**
+     * Geodesic distance from the anchor to each node, metres — the sum of the
+     * rest link lengths along the path, not the straight-line distance.
+     *
+     * This one array drives the tether radius, the slack profile and the pin,
+     * so the three cannot disagree (§3.4). The anchor's is zero, which is what
+     * makes it the fixed set without a second mechanism saying so.
+     * @type {Float32Array|null}
+     */
+    geodesic = null;
+
+    /**
+     * The animated pose in the cloth's local frame — position, 3 per node —
+     * composed once at seed from {@link rest_local_position} down the walk.
+     *
+     * **Constant, and that is a property of the entity path rather than an
+     * optimisation.** The subtree's authored pose is rigid relative to its
+     * anchor, so expressed in the anchor's own frame it does not move; the only
+     * thing that changes step to step is where that frame is. A subtree whose
+     * links are themselves animated is not an M1 case — that is the rig path,
+     * where the animated pose comes from the skeleton (§11.2) and is live.
+     * @type {Float32Array|null}
+     */
+    animated_position = null;
+
+    /**
+     * The animated pose's orientation in the cloth's local frame, 4 per node.
+     * @type {Float32Array|null}
+     */
+    animated_rotation = null;
+
+    /**
+     * The pose the write-back actually writes: the simulated position lerped
+     * towards the animated one by {@link Cloth#blend}, in node order and in
+     * the local frame, 3 per node.
+     *
+     * It exists as an array rather than as a per-node temporary because the
+     * orientation reconstruction needs a node's *neighbours* in the same
+     * blended pose, and blending them twice — once as a neighbour, once as
+     * themselves — is how a rounding difference becomes a visible kink.
+     * @type {Float64Array|null}
+     */
+    blended_position = null;
+
+    /**
+     * The orientation the write-back reconstructed for each node, in the cloth's
+     * local frame, 4 per node.
+     *
+     * Kept for the length of the pass because a node's **local** transform is
+     * its pose relative to its parent's, so writing it needs the parent's
+     * reconstructed rotation — and the walk is breadth-first, so by the time a
+     * node is reached its parent is already in here.
+     * @type {Float64Array|null}
+     */
+    blended_rotation = null;
+
+    /**
+     * Leash row enforcing the slack bound for each node, `−1` where there is
+     * none — the anchor, and any node whose `slack` reaches the bound at which
+     * the row is provably inactive.
+     * @type {Int32Array|null}
+     */
+    slack_row = null;
+
+    /**
+     * Leash row enforcing the tether bound for each node, `−1` for the anchor.
+     * @type {Int32Array|null}
+     */
+    tether_row = null;
+
+    /**
+     * Stretch rows carrying the parent link of each node, `−1` for the anchor.
+     * @type {Int32Array|null}
+     */
+    link_row = null;
+
+    /**
+     * Strain-limit rows on the same links, `−1` when the flag is clear.
+     * @type {Int32Array|null}
+     */
+    strain_row = null;
+
+    /**
+     * Skip rows — the bending model for a chain, one per node that has a
+     * grandparent. `−1` where there is none.
+     * @type {Int32Array|null}
+     */
+    skip_row = null;
+
+    /**
+     * Largest {@link geodesic} in the cloth: how far this cloth can reach from
+     * its anchor, and the length scale the anchor limits and the teleport
+     * threshold are derived from.
+     * @type {number}
+     */
+    reach = 0;
+
+    /**
+     * Shortest row in the cloth, metres.
+     *
+     * The trust region caps a vertex update at the shortest row incident on
+     * that particle (§5.3), so this is the smallest distance any particle can
+     * be moved in one iteration — and `shortest_row · substeps · iterations`
+     * is therefore the whole of what one fixed step can undo. The velocity
+     * clamp is a multiple of it.
+     * @type {number}
+     */
+    shortest_row = 0;
+
+    /**
+     * The anchor's world translation as of the previous step, `[x, y, z]`.
+     * @type {Float64Array}
+     */
+    anchor_translation = new Float64Array(3);
+
+    /**
+     * The anchor's world rotation as of the previous step, `[x, y, z, w]`.
+     * @type {Float64Array}
+     */
+    anchor_rotation = new Float64Array([0, 0, 0, 1]);
+
+    /**
+     * `false` until the first step has recorded an anchor pose to compare
+     * against. The first step feels no inertia, which is correct: there is no
+     * motion yet, only a starting place.
+     * @type {boolean}
+     */
+    anchor_valid = false;
+
+    /**
+     * What {@link Cloth#dynamics} looked like when the rows were last
+     * parameterised. Compared rather than watched — a value object is cheap to
+     * compare and a dirty flag is a second thing to keep true.
+     * @type {ClothDynamics}
+     */
+    dynamics_seen = new ClothDynamics();
+
+    /**
+     * Steps remaining in the post-teleport stabilisation window, during which
+     * the velocity limit ramps back up from nothing (§7 P6). Zero when not
+     * stabilising.
+     * @type {number}
+     */
+    stabilise_remaining = 0;
+
+    /**
+     * Consecutive steps whose largest particle displacement was below the sleep
+     * threshold.
+     * @type {number}
+     */
+    still_steps = 0;
+
+    /**
+     * `true` while the cloth is neither stepped nor written back (§7 P5).
+     *
+     * The write-back is skipped as well as the step, and that is the whole of
+     * what makes P5's "bit-identical across the following 300 steps" a fact
+     * rather than a hope: a pose that is not rewritten cannot drift, and one
+     * that is rewritten from unchanged inputs is only *probably* identical.
+     * @type {boolean}
+     */
+    asleep = false;
+
+    /**
+     * What {@link Cloth#blend} was when the write-back last ran.
+     *
+     * Sleep skips the write-back, so a `blend` written while a cloth is asleep
+     * would otherwise take effect at some arbitrary later moment — the next
+     * time something else happened to wake it. A blend change is a request to
+     * see a different pose, so it wakes the cloth like any other.
+     * @type {number}
+     */
+    blend_seen = 1;
+
+    /**
+     * The colliders overlapping this cloth this step, packed in **its own
+     * frame** rather than the world's — the same layout `ClothColliderIndex`
+     * uses, in `Float32` rather than `Float64` because a cloth-local coordinate
+     * is garment-sized (§12).
+     *
+     * Grown, never shrunk, and rewritten every step by
+     * `cloth_gather_colliders`. It lives on the instance rather than inside
+     * {@link state}'s buffer because its size is a property of the *world* — how
+     * many colliders happen to be near this cloth right now — and `ClothState`'s
+     * one allocation is sized from the cloth. §12 puts it in the shared buffer
+     * when M5 needs it there.
+     * @type {Float32Array|null}
+     */
+    collider_table = null;
+
+    /**
+     * The index handle behind each record in {@link collider_table}. A record
+     * index is this step's; a handle is the collider's, and it is what a
+     * transient contact's multiplier is warm-started on.
+     * @type {Int32Array|null}
+     */
+    collider_key = null;
+
+    /**
+     * Live records in {@link collider_table}.
+     * @type {number}
+     */
+    collider_count = 0;
+
+    /**
+     * Which particle pairs a self-collision row must never be built on, because
+     * a persistent row already governs them (§9). CSR, sorted, built at seed and
+     * replaced by a re-seed — it depends only on the row tables, so nothing about
+     * a `ClothDynamics` change can invalidate it short of the rows themselves
+     * changing, and those changes all go through `cloth_build_rows`.
+     * @type {{offset: Int32Array, partner: Int32Array}|null}
+     */
+    self_exclusions = null;
+
+    /**
+     * How close two particles get in the **bind pose** with no row between them,
+     * metres — or `Infinity` when nothing is within reach of anything.
+     *
+     * The ceiling on a self-collision row's radius, and the reason it is a
+     * measured length rather than a multiple of {@link shortest_row}: on a
+     * triangulated sheet the two agree, and on a rigged garment — strips with
+     * nothing joining one to the next — they do not agree at all.
+     * `CLOTH_SELF_RADIUS_MAX_RATIO` and `MEASUREMENTS.md` §37.
+     * @type {number}
+     */
+    closest_free_pair = Infinity;
+
+    /**
+     * Self-collision pairs the last step found. Diagnostic, and the one to
+     * watch: a garment pinned at `CLOTH_SELF_PAIRS_PER_PARTICLE` per particle is
+     * one whose pairs are being dropped.
+     * @type {number}
+     */
+    self_pairs = 0;
+
+    /**
+     * Contact rows the last step created. Diagnostic — a garment whose contact
+     * count is pinned at four per particle is one whose collider set has more
+     * overlap than `CLOTH_CONTACT_SLOTS` can express.
+     * @type {number}
+     */
+    contact_count = 0;
+
+    /**
+     * `true` once the system has said why this cloth will not seed and stopped
+     * asking. A proxy that does not fit its skin will not start fitting it, and a
+     * warning a frame is a log nobody reads.
+     * @type {boolean}
+     */
+    refused = false;
+
+    /**
+     * How many times this cloth has been re-seeded by a teleport. Diagnostic:
+     * a cloth resetting every few seconds is being driven by something that
+     * looks like a teleport and is not one.
+     * @type {number}
+     */
+    teleport_count = 0;
+}