@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -1,645 +1,317 @@
-import { assert } from "../../../../core/assert.js";
-import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
-import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
-import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
-import {
-    TRANSFORM64_ROTATION_OFFSET,
-    TRANSFORM64_TRANSLATION_OFFSET,
-    Transform64
-} from "../../../ecs/transform/Transform64.js";
-import { ClothState } from "../solver/ClothState.js";
-import { Cloth } from "./Cloth.js";
-import { ClothDynamicsFlags } from "./ClothDynamicsFlags.js";
-import { ClothExclude } from "./ClothExclude.js";
-import { ClothInstance } from "./ClothInstance.js";
-import { cloth_bend_ratio, cloth_strain_allowance } from "./cloth_dynamics_map.js";
-
-/**
- * # Seeding a cloth from an entity subtree — §11.1
- *
- * One particle per entity in the transform subtree of the entity the
- * {@link Cloth} is on, walked breadth-first through
- * `TransformAttachmentSystem#findChildrenOf`, stopping at a nested `Cloth` or a
- * {@link ClothExclude}. Stretch rows along the parent-child links, a bending
- * model along each chain, and the anchor itself as the fixed set — so `d_geo`
- * is distance along the chain from the anchor and every derived quantity in
- * §3.4 works unchanged.
- *
- * ## What "bend rows along each chain" turned out to mean
- *
- * §11.1 asks for bend rows and the row model has one — the quadratic hinge of
- * §6, four particles across the diamond either side of a shared edge. **A chain
- * has no diamond.** `bt_edge_read_diamond` declines a wire edge for exactly
- * that reason, and it is right to: the stencil is a discrete mean curvature over
- * a surface and a rope is not one.
- *
- * The bending model here is instead a **skip row** — an ordinary stretch row
- * between a node and its grandparent, at whatever distance the authored pose
- * puts them. It is §6's own doctrine applied once more ("one row model,
- * parameterised by mode"), it costs no new row kind, and it has the two
- * properties §6 wanted from quadratic bending: there is no normal, no angle and
- * no sign, so nothing degenerates at 0° or 180°, and a fold is high energy
- * rather than a singular configuration. It also does something the quadratic
- * stencil explicitly cannot (§18): because its rest length is read from the
- * authored pose rather than assumed flat, **it holds a curved rest shape**.
- *
- * The row is soft, so its stiffness has to stay inside the dissipative band
- * M0 measured; `cloth_dynamics_map.js` is where that is arranged and why.
- *
- * ## Mass is uniform, and the answer does not depend on it
- *
- * {@link ClothDynamics} carries no mass or density, and it does not need to.
- * Every row scale in this system is a **ratio** of the row's own `m/h²` — the
- * hard rows through the penalty band (`MEASUREMENTS.md` §4 held a chain at a
- * fixed ratio across five decades of particle mass and got the same residual
- * column every time), the soft ones through `cloth_bend_ratio` — and gravity is
- * an acceleration. So the constant below is arbitrary in the strict sense that
- * changing it changes no trajectory, and what matters about it is only that it
- * is the same for every particle.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * Mass of one particle, kg. Arbitrary and uniform — see the module docblock for
- * why "arbitrary" is a statement about the solver rather than a shrug.
- * @type {number}
- */
-export const CLOTH_PARTICLE_MASS = 0.02;
-
-/**
- * Slack radius at `ClothDynamics#slack = 1`, as a multiple of `d_geo`.
- *
- * It is **2**, and that is a derivation rather than a taste. The tether row
- * already holds every particle within `d_geo` of the anchor, and the animated
- * position it is leashed to is itself within `d_geo` of the anchor — a chord is
- * never longer than the arc it subtends. By the triangle inequality the two can
- * therefore never be more than `2·d_geo` apart, so a slack radius of `2·d_geo`
- * is **provably inactive** and `slack = 1` means exactly "no leash" with no
- * sentinel value and no discontinuity to code around.
- *
- * §3.4 writes `r_i = slack · d_geo,i`, which makes `slack = 1` a real and
- * fairly tight constraint instead: a rope hanging straight down cannot swing
- * through 90°, because its tip would move `√2·d_geo` to get there. That is a
- * bound nobody asked for at the setting that is supposed to ask for none.
- * @type {number}
- */
-export const CLOTH_SLACK_REACH = 2;
-
-/**
- * Walk the subtree and build everything {@link ClothSystem} needs to step it.
- *
- * @param {ClothInstance} instance seeded in place
- * @param {EntityComponentDataset} ecd
- * @param {TransformAttachmentSystem} attachments
- * @param {number} dt fixed step, seconds — the bend row's scale is a ratio of
- *   `m/dt²`, so the step length is part of the rest data
- * @returns {void}
- */
-export function cloth_seed_subtree(instance, ecd, attachments, dt) {
-    const remembered = remember_rest_pose(instance);
-
-    const anchor = instance.entity;
-
-    const node_entity = [anchor];
-    const node_parent = [-1];
-
-    const pruned_entity = [];
-    const pruned_parent = [];
-
-    const scratch = [];
-
-    // Breadth-first, so a node's parent is always already numbered and the
-    // write-back can walk forwards.
-    for (let node = 0; node < node_entity.length; node++) {
-        const entity = node_entity[node];
-
-        const child_count = attachments.countChildrenOf(entity);
-
-        if (child_count === 0) {
-            continue;
-        }
-
-        scratch.length = child_count;
-
-        attachments.findChildrenOf(scratch, 0, entity);
-
-        for (let i = 0; i < child_count; i++) {
-            const child = scratch[i];
-
-            const excluded = ecd.getComponent(child, ClothExclude) !== undefined
-                || ecd.getComponent(child, Cloth) !== undefined;
-
-            if (excluded) {
-                pruned_entity.push(child);
-                pruned_parent.push(node);
-
-                continue;
-            }
-
-            if (ecd.getComponent(child, Transform64) === undefined) {
-                // Not in the transform hierarchy in any usable sense. Its own
-                // children are unreachable too, so it is a prune rather than a
-                // skip — and it is not posed by the write-back either, because
-                // there is nothing to pose.
-                continue;
-            }
-
-            node_entity.push(child);
-            node_parent.push(node);
-        }
-    }
-
-    const node_count = node_entity.length;
-
-    instance.node_count = node_count;
-    instance.node_entity = Int32Array.from(node_entity);
-    instance.node_parent = Int32Array.from(node_parent);
-
-    instance.pruned_count = pruned_entity.length;
-    instance.pruned_entity = Int32Array.from(pruned_entity);
-    instance.pruned_parent = Int32Array.from(pruned_parent);
-
-    instance.pruned_transform = new Array(instance.pruned_count);
-    instance.pruned_attachment = new Array(instance.pruned_count);
-
-    for (let i = 0; i < instance.pruned_count; i++) {
-        const entity = instance.pruned_entity[i];
-
-        instance.pruned_transform[i] = ecd.getComponent(entity, Transform64);
-        instance.pruned_attachment[i] = ecd.getComponent(entity, TransformAttachment);
-    }
-
-    instance.node_transform = new Array(node_count);
-    instance.node_attachment = new Array(node_count);
-
-    for (let node = 0; node < node_count; node++) {
-        const entity = instance.node_entity[node];
-
-        const transform = ecd.getComponent(entity, Transform64);
-
-        assert.defined(transform, `Transform64 of cloth node ${node} (entity ${entity})`);
-
-        instance.node_transform[node] = transform;
-        instance.node_attachment[node] = node === 0
-            ? null
-            : ecd.getComponent(entity, TransformAttachment);
-    }
-
-    build_children(instance);
-    read_rest_pose(instance, remembered);
-
-    instance.dynamics_seen.copy(instance.cloth.dynamics);
-
-    build_state(instance, dt);
-}
-
-/**
- * CSR children per node, from the parent array.
- * @param {ClothInstance} instance
- * @private
- */
-function build_children(instance) {
-    const node_count = instance.node_count;
-    const parent = instance.node_parent;
-
-    const offset = new Int32Array(node_count + 1);
-
-    for (let node = 1; node < node_count; node++) {
-        offset[parent[node] + 1]++;
-    }
-
-    for (let node = 0; node < node_count; node++) {
-        offset[node + 1] += offset[node];
-    }
-
-    const child = new Int32Array(node_count > 0 ? node_count - 1 : 0);
-    const cursor = offset.slice(0, node_count);
-
-    for (let node = 1; node < node_count; node++) {
-        child[cursor[parent[node]]++] = node;
-    }
-
-    instance.node_child_offset = offset;
-    instance.node_child = child;
-}
-
-/**
- * Capture the authored pose, and compose it into the anchor's frame.
- *
- * The **local** transforms are the source, not the world ones. That is not a
- * preference: the write-back takes ownership of `TransformAttachment#transform`
- * (§11.1), so this is the one moment the authored pose is still readable, and
- * reading the world transforms instead would give the same answer now and the
- * *simulated* pose on any later re-seed.
- *
- * `remembered` carries a previous seeding's capture across a re-seed, keyed by
- * entity, so a structural change to a live cloth keeps the authored pose of
- * every node that was already in it.
- *
- * The composed result is constant — the subtree's authored pose is rigid
- * relative to its anchor, so in the anchor's own frame it does not move — which
- * is why nothing recomposes it per step.
- *
- * @param {ClothInstance} instance
- * @param {Map<number, {position: number[], rotation: number[]}>} remembered
- * @private
- */
-function read_rest_pose(instance, remembered) {
-    const node_count = instance.node_count;
-
-    const local_position = new Float32Array(node_count * 3);
-    const local_rotation = new Float32Array(node_count * 4);
-
-    const position = new Float32Array(node_count * 3);
-    const rotation = new Float32Array(node_count * 4);
-
-    // The anchor is the origin of the frame it anchors: no offset, no rotation.
-    local_rotation[3] = 1;
-    rotation[3] = 1;
-
-    const parent = instance.node_parent;
-
-    for (let node = 1; node < node_count; node++) {
-        const captured = remembered.get(instance.node_entity[node]);
-
-        if (captured !== undefined) {
-            local_position[node * 3] = captured.position[0];
-            local_position[node * 3 + 1] = captured.position[1];
-            local_position[node * 3 + 2] = captured.position[2];
-
-            local_rotation[node * 4] = captured.rotation[0];
-            local_rotation[node * 4 + 1] = captured.rotation[1];
-            local_rotation[node * 4 + 2] = captured.rotation[2];
-            local_rotation[node * 4 + 3] = captured.rotation[3];
-        } else {
-            const attachment = instance.node_attachment[node];
-
-            const local = attachment === undefined || attachment === null
-                ? null
-                : attachment.transform;
-
-            if (local === null) {
-                // In the walk because something said it was a child, but with no
-                // local transform to compose. Its authored pose is its parent's,
-                // which is the only answer available and is at least inside the
-                // reachable set.
-                local_rotation[node * 4 + 3] = 1;
-            } else {
-                local_position[node * 3] = local[TRANSFORM64_TRANSLATION_OFFSET];
-                local_position[node * 3 + 1] = local[TRANSFORM64_TRANSLATION_OFFSET + 1];
-                local_position[node * 3 + 2] = local[TRANSFORM64_TRANSLATION_OFFSET + 2];
-
-                local_rotation[node * 4] = local[TRANSFORM64_ROTATION_OFFSET];
-                local_rotation[node * 4 + 1] = local[TRANSFORM64_ROTATION_OFFSET + 1];
-                local_rotation[node * 4 + 2] = local[TRANSFORM64_ROTATION_OFFSET + 2];
-                local_rotation[node * 4 + 3] = local[TRANSFORM64_ROTATION_OFFSET + 3];
-            }
-        }
-
-        // Compose down the walk. Breadth-first numbering means the parent is
-        // always already done, so one forward pass is the whole hierarchy.
-        const p = parent[node];
-
-        const pqx = rotation[p * 4];
-        const pqy = rotation[p * 4 + 1];
-        const pqz = rotation[p * 4 + 2];
-        const pqw = rotation[p * 4 + 3];
-
-        v3_quaternion_apply(
-            COMPOSE, 0,
-            local_position[node * 3], local_position[node * 3 + 1], local_position[node * 3 + 2],
-            pqx, pqy, pqz, pqw
-        );
-
-        position[node * 3] = position[p * 3] + COMPOSE[0];
-        position[node * 3 + 1] = position[p * 3 + 1] + COMPOSE[1];
-        position[node * 3 + 2] = position[p * 3 + 2] + COMPOSE[2];
-
-        quat3_multiply(
-            rotation, node * 4,
-            pqx, pqy, pqz, pqw,
-            local_rotation[node * 4], local_rotation[node * 4 + 1],
-            local_rotation[node * 4 + 2], local_rotation[node * 4 + 3]
-        );
-    }
-
-    instance.rest_local_position = local_position;
-    instance.rest_local_rotation = local_rotation;
-
-    instance.animated_position = position;
-    instance.animated_rotation = rotation;
-}
-
-/**
- * @type {Float64Array}
- * @private
- */
-const COMPOSE = new Float64Array(3);
-
-/**
- * The authored pose a previous seeding captured, keyed by entity, so a re-seed
- * of a live cloth does not mistake the shape the solver left behind for the
- * shape the author authored.
- *
- * @param {ClothInstance} instance
- * @returns {Map<number, {position: number[], rotation: number[]}>}
- * @private
- */
-function remember_rest_pose(instance) {
-    const remembered = new Map();
-
-    if (!instance.seeded || instance.rest_local_position === null) {
-        return remembered;
-    }
-
-    for (let node = 1; node < instance.node_count; node++) {
-        remembered.set(instance.node_entity[node], {
-            position: [
-                instance.rest_local_position[node * 3],
-                instance.rest_local_position[node * 3 + 1],
-                instance.rest_local_position[node * 3 + 2]
-            ],
-            rotation: [
-                instance.rest_local_rotation[node * 4],
-                instance.rest_local_rotation[node * 4 + 1],
-                instance.rest_local_rotation[node * 4 + 2],
-                instance.rest_local_rotation[node * 4 + 3]
-            ]
-        });
-    }
-
-    return remembered;
-}
-
-/**
- * Rows, geodesics and the `ClothState` itself.
- *
- * @param {ClothInstance} instance
- * @param {number} dt
- * @private
- */
-function build_state(instance, dt) {
-    const node_count = instance.node_count;
-
-    const parent = instance.node_parent;
-    const rest = instance.animated_position;
-
-    const dynamics = instance.cloth.dynamics;
-
-    const strain_limited = (dynamics.flags & ClothDynamicsFlags.StrainLimit) !== 0;
-
-    const geodesic = new Float32Array(node_count);
-
-    const mass_inverse = new Float32Array(node_count);
-
-    // The anchor is the fixed set: zero inverse mass, and a geodesic of zero,
-    // which is what makes every derived radius collapse onto it correctly.
-    for (let node = 1; node < node_count; node++) {
-        mass_inverse[node] = 1 / CLOTH_PARTICLE_MASS;
-    }
-
-    const stretch_particle = [];
-    const stretch_rest = [];
-    const stretch_stiffness = [];
-    const stretch_force_min = [];
-    const stretch_force_max = [];
-
-    const link_row = new Int32Array(node_count).fill(-1);
-    const strain_row = new Int32Array(node_count).fill(-1);
-    const skip_row = new Int32Array(node_count).fill(-1);
-
-    const strain = cloth_strain_allowance(dynamics.stretch);
-
-    // A skip row spans two links and both of its ends are free, so its
-    // effective inertia along the constraint is half a particle's.
-    const bend_stiffness = cloth_bend_ratio(dynamics.bend)
-        * (CLOTH_PARTICLE_MASS * 0.5) / (dt * dt);
-
-    let reach = 0;
-
-    for (let node = 1; node < node_count; node++) {
-        const p = parent[node];
-
-        const length = Math.hypot(
-            rest[node * 3] - rest[p * 3],
-            rest[node * 3 + 1] - rest[p * 3 + 1],
-            rest[node * 3 + 2] - rest[p * 3 + 2]
-        );
-
-        geodesic[node] = geodesic[p] + length;
-
-        if (geodesic[node] > reach) {
-            reach = geodesic[node];
-        }
-
-        link_row[node] = stretch_rest.length;
-
-        // Hard, bilateral: the fabric row. It is hard because a *penalty* stiff
-        // enough to be fabric adds energy rather than dissipating it — see
-        // `cloth_dynamics_map.js`, and `MEASUREMENTS.md` §6 for the +6.8 J.
-        stretch_particle.push(p, node);
-        stretch_rest.push(length);
-        stretch_stiffness.push(Infinity);
-        stretch_force_min.push(-Infinity);
-        stretch_force_max.push(Infinity);
-
-        if (strain_limited) {
-            strain_row[node] = stretch_rest.length;
-
-            // Hard, one-sided: §6's strain limit, and note the clamp. A row
-            // that bounds a distance from ABOVE may only apply force that
-            // reduces `C`, which for a distance row is the positive half —
-            // `[0, +∞)`. §6's table has this row at `(−∞, 0]`, which is the
-            // force that pushes the two ends apart; `cloth_leash_row.js`
-            // carries the derivation and a spec that shows it directly.
-            stretch_particle.push(p, node);
-            stretch_rest.push(length * (1 + strain));
-            stretch_stiffness.push(Infinity);
-            stretch_force_min.push(0);
-            stretch_force_max.push(Infinity);
-        }
-
-        const grandparent = parent[p];
-
-        if (grandparent >= 0 && bend_stiffness > 0) {
-            const span = Math.hypot(
-                rest[node * 3] - rest[grandparent * 3],
-                rest[node * 3 + 1] - rest[grandparent * 3 + 1],
-                rest[node * 3 + 2] - rest[grandparent * 3 + 2]
-            );
-
-            skip_row[node] = stretch_rest.length;
-
-            // Soft, bilateral: the bending model. Its rest length is read from
-            // the authored pose, so a chain authored with a curve holds it.
-            stretch_particle.push(grandparent, node);
-            stretch_rest.push(span);
-            stretch_stiffness.push(bend_stiffness);
-            stretch_force_min.push(-Infinity);
-            stretch_force_max.push(Infinity);
-        }
-    }
-
-    const leash_particle = [];
-    const leash_radius = [];
-
-    const slack_row = new Int32Array(node_count).fill(-1);
-    const tether_row = new Int32Array(node_count).fill(-1);
-
-    const slack_scale = CLOTH_SLACK_REACH * clamp01(dynamics.slack);
-
-    for (let node = 1; node < node_count; node++) {
-        // Tether first: §7 P2's long-range attachment, and the row that makes a
-        // low iteration budget viable at all, because being hard it is enforced
-        // almost exactly in one iteration however deep the chain is.
-        tether_row[node] = leash_radius.length;
-
-        leash_particle.push(node);
-        leash_radius.push(geodesic[node]);
-
-        if (slack_scale < CLOTH_SLACK_REACH) {
-            slack_row[node] = leash_radius.length;
-
-            leash_particle.push(node);
-            leash_radius.push(slack_scale * geodesic[node]);
-        }
-    }
-
-    let shortest_row = Infinity;
-
-    for (let row = 0; row < stretch_rest.length; row++) {
-        if (stretch_rest[row] > 0 && stretch_rest[row] < shortest_row) {
-            shortest_row = stretch_rest[row];
-        }
-    }
-
-    // A cloth of one particle has no rows at all, so it has no correction
-    // authority to speak of and its reach is the only length it carries.
-    instance.shortest_row = shortest_row < Infinity ? shortest_row : reach;
-
-    instance.geodesic = geodesic;
-    instance.reach = reach;
-    instance.link_row = link_row;
-    instance.strain_row = strain_row;
-    instance.skip_row = skip_row;
-    instance.slack_row = slack_row;
-    instance.tether_row = tether_row;
-
-    const state = ClothState.from({
-        position: rest,
-        mass_inverse,
-        stretch_particle: Int32Array.from(stretch_particle),
-        stretch_rest: Float32Array.from(stretch_rest),
-        stretch_stiffness: Float32Array.from(stretch_stiffness),
-        stretch_force_min: Float32Array.from(stretch_force_min),
-        stretch_force_max: Float32Array.from(stretch_force_max),
-        leash_particle: Int32Array.from(leash_particle),
-        leash_radius: Float32Array.from(leash_radius)
-    });
-
-    const particle_of_node = new Int32Array(node_count);
-
-    for (let particle = 0; particle < node_count; particle++) {
-        particle_of_node[state.source_of_particle[particle]] = particle;
-    }
-
-    instance.particle_of_node = particle_of_node;
-    instance.blended_position = new Float64Array(node_count * 3);
-    instance.blended_rotation = new Float64Array(node_count * 4);
-    instance.state = state;
-    instance.seeded = true;
-}
-
-/**
- * @param {number} v
- * @returns {number}
- * @private
- */
-function clamp01(v) {
-    return v < 0 ? 0 : (v > 1 ? 1 : v);
-}
-
-/**
- * Re-parameterise the rows of an already-seeded cloth from its current
- * {@link ClothDynamics}, without walking the subtree again.
- *
- * This is what makes `cloth.dynamics.slack = 0.2` work live: the topology, the
- * rest lengths and the geodesics are properties of the authored pose and do not
- * move, and everything that does move is a number in a row table.
- *
- * The multipliers are **not** reset. A row whose radius has just changed is
- * carrying a force appropriate to the radius it had, and it is one warm start
- * away from carrying the right one; zeroing them would put a visible jolt into
- * every parameter change instead.
- *
- * @param {ClothInstance} instance
- * @param {number} dt
- * @returns {void}
- */
-export function cloth_reparameterise(instance, dt) {
-    const dynamics = instance.cloth.dynamics;
-
-    const state = instance.state;
-
-    const node_count = instance.node_count;
-
-    const strain = cloth_strain_allowance(dynamics.stretch);
-
-    const bend_stiffness = cloth_bend_ratio(dynamics.bend)
-        * (CLOTH_PARTICLE_MASS * 0.5) / (dt * dt);
-
-    const slack_scale = CLOTH_SLACK_REACH * clamp01(dynamics.slack);
-
-    for (let node = 1; node < node_count; node++) {
-        const link = instance.link_row[node];
-        const strain_limit = instance.strain_row[node];
-        const skip = instance.skip_row[node];
-        const slack = instance.slack_row[node];
-
-        if (strain_limit >= 0) {
-            state.stretch_rest[strain_limit] = state.stretch_rest[link] * (1 + strain);
-        }
-
-        if (skip >= 0) {
-            state.stretch_stiffness[skip] = bend_stiffness;
-        }
-
-        if (slack >= 0) {
-            state.leash_radius[slack] = slack_scale * instance.geodesic[node];
-        }
-    }
-
-    instance.dynamics_seen.copy(dynamics);
-}
-
-/**
- * Whether a dynamics change needs the subtree walked again rather than merely
- * re-parameterised.
- *
- * Two fields do: turning the strain limit on or off adds or removes rows, and
- * so does moving `slack` across the bound at which its row is provably
- * inactive. Everything else is a number in a table that already exists.
- *
- * @param {ClothDynamics} before
- * @param {ClothDynamics} after
- * @returns {boolean}
- */
-export function cloth_dynamics_change_needs_reseed(before, after) {
-    const strain_before = (before.flags & ClothDynamicsFlags.StrainLimit) !== 0;
-    const strain_after = (after.flags & ClothDynamicsFlags.StrainLimit) !== 0;
-
-    if (strain_before !== strain_after) {
-        return true;
-    }
-
-    const leashed_before = clamp01(before.slack) < 1;
-    const leashed_after = clamp01(after.slack) < 1;
-
-    if (leashed_before !== leashed_after) {
-        return true;
-    }
-
-    return (before.bend > 0) !== (after.bend > 0);
-}
+import { assert } from "../../../../core/assert.js";
+import { quat3_multiply } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { v3_quaternion_apply } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET,
+    Transform64
+} from "../../../ecs/transform/Transform64.js";
+import { Cloth } from "./Cloth.js";
+import { ClothExclude } from "./ClothExclude.js";
+import { ClothInstance } from "./ClothInstance.js";
+import { cloth_build_children, cloth_build_rows } from "./cloth_build_rows.js";
+
+/**
+ * # Seeding a cloth from an entity subtree — §11.1
+ *
+ * One particle per entity in the transform subtree of the entity the
+ * {@link Cloth} is on, walked breadth-first through
+ * `TransformAttachmentSystem#findChildrenOf`, stopping at a nested `Cloth` or a
+ * {@link ClothExclude}. Stretch rows along the parent-child links, a bending
+ * model along each chain, and the anchor itself as the fixed set — so `d_geo`
+ * is distance along the chain from the anchor and every derived quantity in
+ * §3.4 works unchanged.
+ *
+ * ## What "bend rows along each chain" turned out to mean
+ *
+ * §11.1 asks for bend rows and the row model has one — the quadratic hinge of
+ * §6, four particles across the diamond either side of a shared edge. **A chain
+ * has no diamond.** `bt_edge_read_diamond` declines a wire edge for exactly
+ * that reason, and it is right to: the stencil is a discrete mean curvature over
+ * a surface and a rope is not one.
+ *
+ * The bending model here is instead a **skip row** — an ordinary stretch row
+ * between a node and its grandparent, at whatever distance the authored pose
+ * puts them. It is §6's own doctrine applied once more ("one row model,
+ * parameterised by mode"), it costs no new row kind, and it has the two
+ * properties §6 wanted from quadratic bending: there is no normal, no angle and
+ * no sign, so nothing degenerates at 0° or 180°, and a fold is high energy
+ * rather than a singular configuration. It also does something the quadratic
+ * stencil explicitly cannot (§18): because its rest length is read from the
+ * authored pose rather than assumed flat, **it holds a curved rest shape**.
+ *
+ * The row is soft, so its stiffness has to stay inside the dissipative band
+ * M0 measured; `cloth_dynamics_map.js` is where that is arranged and why.
+ *
+ * ## Mass is uniform, and the answer does not depend on it
+ *
+ * {@link ClothDynamics} carries no mass or density, and it does not need to.
+ * Every row scale in this system is a **ratio** of the row's own `m/h²` — the
+ * hard rows through the penalty band (`MEASUREMENTS.md` §4 held a chain at a
+ * fixed ratio across five decades of particle mass and got the same residual
+ * column every time), the soft ones through `cloth_bend_ratio` — and gravity is
+ * an acceleration. So the constant below is arbitrary in the strict sense that
+ * changing it changes no trajectory, and what matters about it is only that it
+ * is the same for every particle.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Walk the subtree and build everything {@link ClothSystem} needs to step it.
+ *
+ * @param {ClothInstance} instance seeded in place
+ * @param {EntityComponentDataset} ecd
+ * @param {TransformAttachmentSystem} attachments
+ * @param {number} dt fixed step, seconds — the bend row's scale is a ratio of
+ *   `m/dt²`, so the step length is part of the rest data
+ * @returns {void}
+ */
+export function cloth_seed_subtree(instance, ecd, attachments, dt) {
+    const remembered = remember_rest_pose(instance);
+
+    const anchor = instance.entity;
+
+    const node_entity = [anchor];
+    const node_parent = [-1];
+
+    const pruned_entity = [];
+    const pruned_parent = [];
+
+    const scratch = [];
+
+    // Breadth-first, so a node's parent is always already numbered and the
+    // write-back can walk forwards.
+    for (let node = 0; node < node_entity.length; node++) {
+        const entity = node_entity[node];
+
+        const child_count = attachments.countChildrenOf(entity);
+
+        if (child_count === 0) {
+            continue;
+        }
+
+        scratch.length = child_count;
+
+        attachments.findChildrenOf(scratch, 0, entity);
+
+        for (let i = 0; i < child_count; i++) {
+            const child = scratch[i];
+
+            const excluded = ecd.getComponent(child, ClothExclude) !== undefined
+                || ecd.getComponent(child, Cloth) !== undefined;
+
+            if (excluded) {
+                pruned_entity.push(child);
+                pruned_parent.push(node);
+
+                continue;
+            }
+
+            if (ecd.getComponent(child, Transform64) === undefined) {
+                // Not in the transform hierarchy in any usable sense. Its own
+                // children are unreachable too, so it is a prune rather than a
+                // skip — and it is not posed by the write-back either, because
+                // there is nothing to pose.
+                continue;
+            }
+
+            node_entity.push(child);
+            node_parent.push(node);
+        }
+    }
+
+    const node_count = node_entity.length;
+
+    instance.node_count = node_count;
+    instance.node_entity = Int32Array.from(node_entity);
+    instance.node_parent = Int32Array.from(node_parent);
+
+    instance.pruned_count = pruned_entity.length;
+    instance.pruned_entity = Int32Array.from(pruned_entity);
+    instance.pruned_parent = Int32Array.from(pruned_parent);
+
+    instance.pruned_transform = new Array(instance.pruned_count);
+    instance.pruned_attachment = new Array(instance.pruned_count);
+
+    for (let i = 0; i < instance.pruned_count; i++) {
+        const entity = instance.pruned_entity[i];
+
+        instance.pruned_transform[i] = ecd.getComponent(entity, Transform64);
+        instance.pruned_attachment[i] = ecd.getComponent(entity, TransformAttachment);
+    }
+
+    instance.node_transform = new Array(node_count);
+    instance.node_attachment = new Array(node_count);
+
+    for (let node = 0; node < node_count; node++) {
+        const entity = instance.node_entity[node];
+
+        const transform = ecd.getComponent(entity, Transform64);
+
+        assert.defined(transform, `Transform64 of cloth node ${node} (entity ${entity})`);
+
+        instance.node_transform[node] = transform;
+        instance.node_attachment[node] = node === 0
+            ? null
+            : ecd.getComponent(entity, TransformAttachment);
+    }
+
+    cloth_build_children(instance);
+    read_rest_pose(instance, remembered);
+
+    instance.dynamics_seen.copy(instance.cloth.dynamics);
+
+    cloth_build_rows(instance, dt);
+}
+
+/**
+ * Capture the authored pose, and compose it into the anchor's frame.
+ *
+ * The **local** transforms are the source, not the world ones. That is not a
+ * preference: the write-back takes ownership of `TransformAttachment#transform`
+ * (§11.1), so this is the one moment the authored pose is still readable, and
+ * reading the world transforms instead would give the same answer now and the
+ * *simulated* pose on any later re-seed.
+ *
+ * `remembered` carries a previous seeding's capture across a re-seed, keyed by
+ * entity, so a structural change to a live cloth keeps the authored pose of
+ * every node that was already in it.
+ *
+ * The composed result is constant — the subtree's authored pose is rigid
+ * relative to its anchor, so in the anchor's own frame it does not move — which
+ * is why nothing recomposes it per step.
+ *
+ * @param {ClothInstance} instance
+ * @param {Map<number, {position: number[], rotation: number[]}>} remembered
+ * @private
+ */
+function read_rest_pose(instance, remembered) {
+    const node_count = instance.node_count;
+
+    const local_position = new Float32Array(node_count * 3);
+    const local_rotation = new Float32Array(node_count * 4);
+
+    const position = new Float32Array(node_count * 3);
+    const rotation = new Float32Array(node_count * 4);
+
+    // The anchor is the origin of the frame it anchors: no offset, no rotation.
+    local_rotation[3] = 1;
+    rotation[3] = 1;
+
+    const parent = instance.node_parent;
+
+    for (let node = 1; node < node_count; node++) {
+        const captured = remembered.get(instance.node_entity[node]);
+
+        if (captured !== undefined) {
+            local_position[node * 3] = captured.position[0];
+            local_position[node * 3 + 1] = captured.position[1];
+            local_position[node * 3 + 2] = captured.position[2];
+
+            local_rotation[node * 4] = captured.rotation[0];
+            local_rotation[node * 4 + 1] = captured.rotation[1];
+            local_rotation[node * 4 + 2] = captured.rotation[2];
+            local_rotation[node * 4 + 3] = captured.rotation[3];
+        } else {
+            const attachment = instance.node_attachment[node];
+
+            const local = attachment === undefined || attachment === null
+                ? null
+                : attachment.transform;
+
+            if (local === null) {
+                // In the walk because something said it was a child, but with no
+                // local transform to compose. Its authored pose is its parent's,
+                // which is the only answer available and is at least inside the
+                // reachable set.
+                local_rotation[node * 4 + 3] = 1;
+            } else {
+                local_position[node * 3] = local[TRANSFORM64_TRANSLATION_OFFSET];
+                local_position[node * 3 + 1] = local[TRANSFORM64_TRANSLATION_OFFSET + 1];
+                local_position[node * 3 + 2] = local[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+                local_rotation[node * 4] = local[TRANSFORM64_ROTATION_OFFSET];
+                local_rotation[node * 4 + 1] = local[TRANSFORM64_ROTATION_OFFSET + 1];
+                local_rotation[node * 4 + 2] = local[TRANSFORM64_ROTATION_OFFSET + 2];
+                local_rotation[node * 4 + 3] = local[TRANSFORM64_ROTATION_OFFSET + 3];
+            }
+        }
+
+        // Compose down the walk. Breadth-first numbering means the parent is
+        // always already done, so one forward pass is the whole hierarchy.
+        const p = parent[node];
+
+        const pqx = rotation[p * 4];
+        const pqy = rotation[p * 4 + 1];
+        const pqz = rotation[p * 4 + 2];
+        const pqw = rotation[p * 4 + 3];
+
+        v3_quaternion_apply(
+            COMPOSE, 0,
+            local_position[node * 3], local_position[node * 3 + 1], local_position[node * 3 + 2],
+            pqx, pqy, pqz, pqw
+        );
+
+        position[node * 3] = position[p * 3] + COMPOSE[0];
+        position[node * 3 + 1] = position[p * 3 + 1] + COMPOSE[1];
+        position[node * 3 + 2] = position[p * 3 + 2] + COMPOSE[2];
+
+        quat3_multiply(
+            rotation, node * 4,
+            pqx, pqy, pqz, pqw,
+            local_rotation[node * 4], local_rotation[node * 4 + 1],
+            local_rotation[node * 4 + 2], local_rotation[node * 4 + 3]
+        );
+    }
+
+    instance.rest_local_position = local_position;
+    instance.rest_local_rotation = local_rotation;
+
+    instance.animated_position = position;
+    instance.animated_rotation = rotation;
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const COMPOSE = new Float64Array(3);
+
+/**
+ * The authored pose a previous seeding captured, keyed by entity, so a re-seed
+ * of a live cloth does not mistake the shape the solver left behind for the
+ * shape the author authored.
+ *
+ * @param {ClothInstance} instance
+ * @returns {Map<number, {position: number[], rotation: number[]}>}
+ * @private
+ */
+function remember_rest_pose(instance) {
+    const remembered = new Map();
+
+    if (!instance.seeded || instance.rest_local_position === null) {
+        return remembered;
+    }
+
+    for (let node = 1; node < instance.node_count; node++) {
+        remembered.set(instance.node_entity[node], {
+            position: [
+                instance.rest_local_position[node * 3],
+                instance.rest_local_position[node * 3 + 1],
+                instance.rest_local_position[node * 3 + 2]
+            ],
+            rotation: [
+                instance.rest_local_rotation[node * 4],
+                instance.rest_local_rotation[node * 4 + 1],
+                instance.rest_local_rotation[node * 4 + 2],
+                instance.rest_local_rotation[node * 4 + 3]
+            ]
+        });
+    }
+
+    return remembered;
+}
+