@woosh/meep-engine 3.22.0 → 3.23.0

package/src/engine/physics/cloth/build/ClothProxy.d.ts

@@ -0,0 +1,147 @@
+/**
+ * # The built artefact a `ClothRig` points at
+ *
+ * Shared, immutable, and produced once at import. `ClothRig#proxy` holds one of
+ * these the way `Collider#shape` holds an `AbstractShape3D` and `ParticleEffect`
+ * holds a `ParticleProgram`: the component serialises the proxy's *identity*,
+ * and the asset pipeline wires the object up (§3.2).
+ *
+ * ## Joints by index, resolved once
+ *
+ * Every field below is an integer or a float. **No names survive into the
+ * runtime**, and that is §3.2's central commitment: a joint is a `Node3D` inside
+ * a `SceneBundleInstance` rather than an entity, so an `EntityReference` to one
+ * is impossible by construction, and reintroducing strings at runtime to work
+ * around that would be the wrong answer. {@link joint} holds indices into
+ * `Skin#joints`, resolved at build time from `SceneBundleInstance#nodes`.
+ *
+ * {@link joint_name} is the exception and it is build-time provenance: it is
+ * what a diagnostic prints when a proxy does not fit the model it was pointed
+ * at, and nothing on the step path reads it.
+ *
+ * ## The rigged form, which is the whole of M3
+ *
+ * §11.2 has two cases and they differ only in where the joints and the weights
+ * came from. **A rigged garment brings both**: an artist made 8–20 cape joints
+ * and skinned the cape to them, so the proxy is thin — joint indices, the
+ * topology connecting them, the bind pose, and `d_geo`. There is no binding
+ * step and no generated geometry, because the artist's skin *is* the relation.
+ *
+ * The unrigged case generates a joint set and a skin for a garment that has
+ * neither, and its extra data — the render mesh's generated weights and
+ * inverse-bind matrices — is not in this class yet. §11.3 step 9 and §18's open
+ * joint-budget question are what would add it.
+ *
+ * ## The bind pose is baked, not read
+ *
+ * {@link rest_position} and {@link rest_rotation} are the joints' **local**
+ * transforms at bind time, carried in the proxy rather than read from the
+ * instance at seed. Reading them from the instance works exactly once: cloth
+ * takes ownership of `Node3D.transform_local` the moment it starts writing, so
+ * a re-seed of a live garment would read the shape the solver left behind and
+ * call it the authored pose. M1 solved the same problem for the entity path with
+ * a per-seed capture (`remember_rest_pose`); a proxy can do better, because the
+ * bind pose is build data and does not have to be remembered at all.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothProxy {
+    /**
+     * @param {object} description
+     * @param {string} [description.name]
+     * @param {Int32Array|number[]} description.joint
+     * @param {Int32Array|number[]} description.joint_parent
+     * @param {number} description.anchor
+     * @param {Float32Array|number[]} description.rest_position
+     * @param {Float32Array|number[]} description.rest_rotation
+     * @param {string[]} [description.joint_name]
+     * @returns {ClothProxy}
+     */
+    static from({ name, joint, joint_parent, anchor, rest_position, rest_rotation, joint_name }: {
+        name?: string;
+        joint: Int32Array | number[];
+        joint_parent: Int32Array | number[];
+        anchor: number;
+        rest_position: Float32Array | number[];
+        rest_rotation: Float32Array | number[];
+        joint_name?: string[];
+    }): ClothProxy;
+    /**
+     * Name, for diagnostics and for a tool listing the proxies an asset carries.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * How many joints this proxy simulates. The anchor is **not** one of them.
+     * @type {number}
+     */
+    joint_count: number;
+    /**
+     * Index into `Skin#joints` for each simulated joint.
+     * @type {Int32Array}
+     */
+    joint: Int32Array;
+    /**
+     * Parent of each simulated joint, as an index into this proxy's own joint
+     * list, or `-1` for a joint whose parent is the anchor.
+     *
+     * A proxy's joints are stored **parents before children**, so one forward
+     * pass composes the whole chain — the same ordering `cloth_seed_subtree`
+     * gets from a breadth-first walk, and for the same reason.
+     * @type {Int32Array}
+     */
+    joint_parent: Int32Array;
+    /**
+     * Index into `Skin#joints` of the joint the garment hangs from.
+     *
+     * It is not simulated, it is the cloth's local frame, and its `d_geo` is
+     * zero — which is what makes §3.4's derived quantities collapse onto it
+     * correctly without a second mechanism saying "this one is pinned".
+     *
+     * For a rigged garment the fixed set *is* the anchor, and it falls out of
+     * the topology rather than out of skin weights: a joint whose parent is
+     * outside the proxy is a joint the garment hangs from. §11.3's step 5 —
+     * "particles whose skin weights are dominated by joints outside the
+     * garment's own joint set are pinned" — is the **unrigged** rule, where the
+     * particles are mesh vertices and there is no joint tree to read.
+     * @type {number}
+     */
+    anchor: number;
+    /**
+     * Each joint's bind-pose local translation, 3 per joint.
+     * @type {Float32Array}
+     */
+    rest_position: Float32Array;
+    /**
+     * Each joint's bind-pose local rotation, 4 per joint.
+     * @type {Float32Array}
+     */
+    rest_rotation: Float32Array;
+    /**
+     * Names, in {@link joint} order, then the anchor's last. Build-time
+     * provenance; nothing on the step path reads it.
+     * @type {string[]}
+     */
+    joint_name: string[];
+    /**
+     * Whether this proxy can address the skin it is about to be used with.
+     *
+     * A proxy is built against one model and a `ClothRig` points at whichever
+     * one the entity is showing, so the two can disagree — a model swap, an
+     * asset rebuilt with a joint removed, a proxy pointed at the wrong skin
+     * ordinal. Every one of those is an authoring mistake rather than a runtime
+     * condition, and this is what turns it into a message naming the joint
+     * instead of a garment simulating somebody's spine.
+     *
+     * @param {Skin} skin
+     * @returns {string} empty when the proxy fits, otherwise what is wrong
+     */
+    checkAgainst(skin: Skin): string;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isClothProxy: boolean;
+}
+//# sourceMappingURL=ClothProxy.d.ts.map

package/src/engine/physics/cloth/build/ClothProxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClothProxy.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/ClothProxy.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAmEI;;;;;;;;;;OAUG;IACH;QATgC,IAAI,GAAzB,MAAM;QAC2B,KAAK,EAAtC,UAAU,GAAC,MAAM,EAAE;QACc,YAAY,EAA7C,UAAU,GAAC,MAAM,EAAE;QACC,MAAM,EAA1B,MAAM;QAC6B,aAAa,EAAhD,YAAY,GAAC,MAAM,EAAE;QACc,aAAa,EAAhD,YAAY,GAAC,MAAM,EAAE;QACE,UAAU,GAAjC,MAAM,EAAE;QACN,UAAU,CAuCtB;IAjHD;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,OAFU,UAAU,CAEP;IAEb;;;;;;;;OAQG;IACH,cAFU,UAAU,CAEA;IAEpB;;;;;;;;;;;;;;OAcG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,eAFU,YAAY,CAED;IAErB;;;OAGG;IACH,eAFU,YAAY,CAED;IAErB;;;;OAIG;IACH,YAFU,MAAM,EAAE,CAEF;IAoDhB;;;;;;;;;;;;OAYG;IACH,0BAFa,MAAM,CAqBlB;IAGL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;CANhC"}

package/src/engine/physics/cloth/build/ClothProxy.js

@@ -0,0 +1,207 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * # The built artefact a `ClothRig` points at
+ *
+ * Shared, immutable, and produced once at import. `ClothRig#proxy` holds one of
+ * these the way `Collider#shape` holds an `AbstractShape3D` and `ParticleEffect`
+ * holds a `ParticleProgram`: the component serialises the proxy's *identity*,
+ * and the asset pipeline wires the object up (§3.2).
+ *
+ * ## Joints by index, resolved once
+ *
+ * Every field below is an integer or a float. **No names survive into the
+ * runtime**, and that is §3.2's central commitment: a joint is a `Node3D` inside
+ * a `SceneBundleInstance` rather than an entity, so an `EntityReference` to one
+ * is impossible by construction, and reintroducing strings at runtime to work
+ * around that would be the wrong answer. {@link joint} holds indices into
+ * `Skin#joints`, resolved at build time from `SceneBundleInstance#nodes`.
+ *
+ * {@link joint_name} is the exception and it is build-time provenance: it is
+ * what a diagnostic prints when a proxy does not fit the model it was pointed
+ * at, and nothing on the step path reads it.
+ *
+ * ## The rigged form, which is the whole of M3
+ *
+ * §11.2 has two cases and they differ only in where the joints and the weights
+ * came from. **A rigged garment brings both**: an artist made 8–20 cape joints
+ * and skinned the cape to them, so the proxy is thin — joint indices, the
+ * topology connecting them, the bind pose, and `d_geo`. There is no binding
+ * step and no generated geometry, because the artist's skin *is* the relation.
+ *
+ * The unrigged case generates a joint set and a skin for a garment that has
+ * neither, and its extra data — the render mesh's generated weights and
+ * inverse-bind matrices — is not in this class yet. §11.3 step 9 and §18's open
+ * joint-budget question are what would add it.
+ *
+ * ## The bind pose is baked, not read
+ *
+ * {@link rest_position} and {@link rest_rotation} are the joints' **local**
+ * transforms at bind time, carried in the proxy rather than read from the
+ * instance at seed. Reading them from the instance works exactly once: cloth
+ * takes ownership of `Node3D.transform_local` the moment it starts writing, so
+ * a re-seed of a live garment would read the shape the solver left behind and
+ * call it the authored pose. M1 solved the same problem for the entity path with
+ * a per-seed capture (`remember_rest_pose`); a proxy can do better, because the
+ * bind pose is build data and does not have to be remembered at all.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ClothProxy {
+
+    /**
+     * Name, for diagnostics and for a tool listing the proxies an asset carries.
+     * @type {string}
+     */
+    name = "";
+
+    /**
+     * How many joints this proxy simulates. The anchor is **not** one of them.
+     * @type {number}
+     */
+    joint_count = 0;
+
+    /**
+     * Index into `Skin#joints` for each simulated joint.
+     * @type {Int32Array}
+     */
+    joint = null;
+
+    /**
+     * Parent of each simulated joint, as an index into this proxy's own joint
+     * list, or `-1` for a joint whose parent is the anchor.
+     *
+     * A proxy's joints are stored **parents before children**, so one forward
+     * pass composes the whole chain — the same ordering `cloth_seed_subtree`
+     * gets from a breadth-first walk, and for the same reason.
+     * @type {Int32Array}
+     */
+    joint_parent = null;
+
+    /**
+     * Index into `Skin#joints` of the joint the garment hangs from.
+     *
+     * It is not simulated, it is the cloth's local frame, and its `d_geo` is
+     * zero — which is what makes §3.4's derived quantities collapse onto it
+     * correctly without a second mechanism saying "this one is pinned".
+     *
+     * For a rigged garment the fixed set *is* the anchor, and it falls out of
+     * the topology rather than out of skin weights: a joint whose parent is
+     * outside the proxy is a joint the garment hangs from. §11.3's step 5 —
+     * "particles whose skin weights are dominated by joints outside the
+     * garment's own joint set are pinned" — is the **unrigged** rule, where the
+     * particles are mesh vertices and there is no joint tree to read.
+     * @type {number}
+     */
+    anchor = -1;
+
+    /**
+     * Each joint's bind-pose local translation, 3 per joint.
+     * @type {Float32Array}
+     */
+    rest_position = null;
+
+    /**
+     * Each joint's bind-pose local rotation, 4 per joint.
+     * @type {Float32Array}
+     */
+    rest_rotation = null;
+
+    /**
+     * Names, in {@link joint} order, then the anchor's last. Build-time
+     * provenance; nothing on the step path reads it.
+     * @type {string[]}
+     */
+    joint_name = [];
+
+    /**
+     * @param {object} description
+     * @param {string} [description.name]
+     * @param {Int32Array|number[]} description.joint
+     * @param {Int32Array|number[]} description.joint_parent
+     * @param {number} description.anchor
+     * @param {Float32Array|number[]} description.rest_position
+     * @param {Float32Array|number[]} description.rest_rotation
+     * @param {string[]} [description.joint_name]
+     * @returns {ClothProxy}
+     */
+    static from({
+        name = "",
+        joint,
+        joint_parent,
+        anchor,
+        rest_position,
+        rest_rotation,
+        joint_name = []
+    }) {
+        const joint_count = joint.length;
+
+        assert.equal(joint_parent.length, joint_count, 'joint_parent.length');
+        assert.equal(rest_position.length, joint_count * 3, 'rest_position.length');
+        assert.equal(rest_rotation.length, joint_count * 4, 'rest_rotation.length');
+        assert.isNonNegativeInteger(anchor, 'anchor');
+
+        for (let i = 0; i < joint_count; i++) {
+            // Parents before children: the composition down the chain is one
+            // forward pass and there is nowhere for a cycle to hide.
+            assert.ok(
+                joint_parent[i] < i,
+                `ClothProxy joint ${i} has parent ${joint_parent[i]}, which is not before it`
+            );
+        }
+
+        const r = new ClothProxy();
+
+        r.name = name;
+        r.joint_count = joint_count;
+        r.joint = Int32Array.from(joint);
+        r.joint_parent = Int32Array.from(joint_parent);
+        r.anchor = anchor;
+        r.rest_position = Float32Array.from(rest_position);
+        r.rest_rotation = Float32Array.from(rest_rotation);
+        r.joint_name = joint_name.slice();
+
+        return r;
+    }
+
+    /**
+     * Whether this proxy can address the skin it is about to be used with.
+     *
+     * A proxy is built against one model and a `ClothRig` points at whichever
+     * one the entity is showing, so the two can disagree — a model swap, an
+     * asset rebuilt with a joint removed, a proxy pointed at the wrong skin
+     * ordinal. Every one of those is an authoring mistake rather than a runtime
+     * condition, and this is what turns it into a message naming the joint
+     * instead of a garment simulating somebody's spine.
+     *
+     * @param {Skin} skin
+     * @returns {string} empty when the proxy fits, otherwise what is wrong
+     */
+    checkAgainst(skin) {
+        if (skin === undefined || skin === null) {
+            return `${this.name}: no skin`;
+        }
+
+        const count = skin.joints.length;
+
+        if (this.anchor >= count) {
+            return `${this.name}: anchor is joint ${this.anchor} of a skin with ${count}`;
+        }
+
+        for (let i = 0; i < this.joint_count; i++) {
+            if (this.joint[i] >= count) {
+                return `${this.name}: joint ${i} (${this.joint_name[i] ?? '?'})`
+                    + ` is index ${this.joint[i]} of a skin with ${count}`;
+            }
+        }
+
+        return "";
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ClothProxy.prototype.isClothProxy = true;

package/src/engine/physics/cloth/build/cloth_proxy_from_joints.d.ts

@@ -0,0 +1,70 @@
+/**
+ * # Building a proxy for a garment that is already rigged
+ *
+ * §11.3 lists ten steps and says that for a rigged garment "only steps 5–8 run,
+ * over the joint graph rather than a mesh". This is those steps: derive the
+ * fixed set, bake the bind pose, resolve names to indices, and validate. Steps
+ * 1–4 are mesh work a rigged garment does not need — the artist's joints *are*
+ * the particle set and the artist's skin *is* the binding — and steps 9 and 10's
+ * mesh half belong to the unrigged path.
+ *
+ * The colouring step (7) is absent for a reason rather than an omission: the
+ * cloth's own row builder colours the particle graph inside
+ * `ClothState.from`, and it does that for the entity path too. Baking a
+ * permutation into the proxy would be a second answer to a question that
+ * already has one, and it would have to agree with `cloth_color_particles`
+ * exactly or the rows would name the wrong particles.
+ *
+ * ## The fixed set falls out of the topology
+ *
+ * A joint whose parent is outside the named set is a joint the garment hangs
+ * from, and **every one of them must hang from the same bone** — that bone is
+ * the anchor. §11.3 step 5 derives the fixed set from *skin weights* instead,
+ * which is the right rule for the unrigged path, where the particles are mesh
+ * vertices and there is no joint tree to read. For a rigged garment the tree is
+ * the answer and the weights are not needed.
+ *
+ * Several chains from one bone are one garment and are the point: §3.1's "put
+ * `Cloth` on a node with several chains under it and you get all of them in one
+ * coupled solve" is exactly a cape's four strips off one shoulder. Chains from
+ * *different* bones are refused, because there is then no single frame to
+ * simulate in and no single fixed set — that is two garments, and nothing stops
+ * a caller building two proxies.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @typedef {object} ClothProxyBuildResult
+ * @property {ClothProxy|null} proxy `null` when the build refused
+ * @property {string} error empty when it did not
+ */
+/**
+ * Build a proxy from the joints of a skin, named.
+ *
+ * The names are the only place a name appears anywhere in the system (§11.3
+ * step 8) and they do not survive: what comes back holds indices into
+ * `skin.joints`.
+ *
+ * @param {Skin} skin the instance's skin, or the asset's — the joint *order* is
+ *   what is read, and instantiation preserves it
+ * @param {string[]} joint_names the garment's own joints, in any order
+ * @param {object} [options]
+ * @param {string} [options.name]
+ * @returns {ClothProxyBuildResult}
+ */
+export function cloth_proxy_from_joints(skin: Skin, joint_names: string[], { name }?: {
+    name?: string;
+}): ClothProxyBuildResult;
+export type ClothProxyBuildResult = {
+    /**
+     * `null` when the build refused
+     */
+    proxy: ClothProxy | null;
+    /**
+     * empty when it did not
+     */
+    error: string;
+};
+import { ClothProxy } from "./ClothProxy.js";
+//# sourceMappingURL=cloth_proxy_from_joints.d.ts.map

package/src/engine/physics/cloth/build/cloth_proxy_from_joints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_proxy_from_joints.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_proxy_from_joints.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,iEALW,MAAM,EAAE;IAES,IAAI,GAArB,MAAM;IACJ,qBAAqB,CAyLjC;;;;;WAzMa,UAAU,GAAC,IAAI;;;;WACf,MAAM;;2BA1CO,iBAAiB"}

package/src/engine/physics/cloth/build/cloth_proxy_from_joints.js

@@ -0,0 +1,256 @@
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../../../ecs/transform/Transform64.js";
+import { ClothProxy } from "./ClothProxy.js";
+
+/**
+ * # Building a proxy for a garment that is already rigged
+ *
+ * §11.3 lists ten steps and says that for a rigged garment "only steps 5–8 run,
+ * over the joint graph rather than a mesh". This is those steps: derive the
+ * fixed set, bake the bind pose, resolve names to indices, and validate. Steps
+ * 1–4 are mesh work a rigged garment does not need — the artist's joints *are*
+ * the particle set and the artist's skin *is* the binding — and steps 9 and 10's
+ * mesh half belong to the unrigged path.
+ *
+ * The colouring step (7) is absent for a reason rather than an omission: the
+ * cloth's own row builder colours the particle graph inside
+ * `ClothState.from`, and it does that for the entity path too. Baking a
+ * permutation into the proxy would be a second answer to a question that
+ * already has one, and it would have to agree with `cloth_color_particles`
+ * exactly or the rows would name the wrong particles.
+ *
+ * ## The fixed set falls out of the topology
+ *
+ * A joint whose parent is outside the named set is a joint the garment hangs
+ * from, and **every one of them must hang from the same bone** — that bone is
+ * the anchor. §11.3 step 5 derives the fixed set from *skin weights* instead,
+ * which is the right rule for the unrigged path, where the particles are mesh
+ * vertices and there is no joint tree to read. For a rigged garment the tree is
+ * the answer and the weights are not needed.
+ *
+ * Several chains from one bone are one garment and are the point: §3.1's "put
+ * `Cloth` on a node with several chains under it and you get all of them in one
+ * coupled solve" is exactly a cape's four strips off one shoulder. Chains from
+ * *different* bones are refused, because there is then no single frame to
+ * simulate in and no single fixed set — that is two garments, and nothing stops
+ * a caller building two proxies.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @typedef {object} ClothProxyBuildResult
+ * @property {ClothProxy|null} proxy `null` when the build refused
+ * @property {string} error empty when it did not
+ */
+
+/**
+ * Build a proxy from the joints of a skin, named.
+ *
+ * The names are the only place a name appears anywhere in the system (§11.3
+ * step 8) and they do not survive: what comes back holds indices into
+ * `skin.joints`.
+ *
+ * @param {Skin} skin the instance's skin, or the asset's — the joint *order* is
+ *   what is read, and instantiation preserves it
+ * @param {string[]} joint_names the garment's own joints, in any order
+ * @param {object} [options]
+ * @param {string} [options.name]
+ * @returns {ClothProxyBuildResult}
+ */
+export function cloth_proxy_from_joints(skin, joint_names, { name = "" } = {}) {
+    if (skin === undefined || skin === null) {
+        return refuse(`${name}: no skin`);
+    }
+
+    const joints = skin.joints;
+
+    /** @type {Map<Node3D, number>} node → index in `skin.joints` */
+    const index_of = new Map();
+
+    for (let i = 0; i < joints.length; i++) {
+        index_of.set(joints[i], i);
+    }
+
+    /** @type {Map<string, Node3D>} */
+    const by_name = new Map();
+
+    for (let i = 0; i < joints.length; i++) {
+        const joint = joints[i];
+
+        if (joint.name !== "" && !by_name.has(joint.name)) {
+            by_name.set(joint.name, joint);
+        }
+    }
+
+    /** @type {Set<Node3D>} the garment's own joints */
+    const members = new Set();
+
+    for (const joint_name of joint_names) {
+        const node = by_name.get(joint_name);
+
+        if (node === undefined) {
+            return refuse(`${name}: the skin has no joint named "${joint_name}"`);
+        }
+
+        if (members.has(node)) {
+            return refuse(`${name}: "${joint_name}" is named twice`);
+        }
+
+        members.add(node);
+    }
+
+    if (members.size === 0) {
+        return refuse(`${name}: no joints`);
+    }
+
+    // Roots: members whose parent is not a member. They all have to hang from
+    // the same bone, and that bone is the anchor.
+    /** @type {Node3D[]} */
+    const roots = [];
+
+    for (const node of members) {
+        if (node.parent === null || !members.has(node.parent)) {
+            roots.push(node);
+        }
+    }
+
+    const anchor_node = roots[0].parent;
+
+    if (anchor_node === null) {
+        return refuse(`${name}: "${roots[0].name}" has no parent, so the garment has nothing to hang from`);
+    }
+
+    for (const root of roots) {
+        if (root.parent !== anchor_node) {
+            return refuse(
+                `${name}: "${roots[0].name}" hangs from "${anchor_node.name}" and "${root.name}" hangs`
+                + ` from "${root.parent === null ? 'nothing' : root.parent.name}" — a garment hangs from one`
+                + ` anchor, and chains from different bones are two garments`
+            );
+        }
+    }
+
+    const anchor = index_of.get(anchor_node);
+
+    if (anchor === undefined) {
+        return refuse(
+            `${name}: "${roots[0].name}" hangs from "${anchor_node.name}", which is not a joint of this skin`
+        );
+    }
+
+    // Parents before children, so one forward pass composes the chain.
+    /** @type {Node3D[]} */
+    const ordered = [];
+
+    /** @type {Map<Node3D, number>} */
+    const position = new Map();
+
+    // Breadth-first from every root at once, which keeps parents before
+    // children across the whole forest rather than only within one chain.
+    const queue = roots.slice();
+
+    while (queue.length > 0) {
+        const node = queue.shift();
+
+        position.set(node, ordered.length);
+        ordered.push(node);
+
+        for (const child of node.children) {
+            if (members.has(child)) {
+                queue.push(child);
+            }
+        }
+    }
+
+    if (ordered.length !== members.size) {
+        const stranded = [];
+
+        for (const node of members) {
+            if (!position.has(node)) {
+                stranded.push(node.name);
+            }
+        }
+
+        return refuse(
+            `${name}: ${stranded.length} joints are unreachable from the anchor (${stranded.join(', ')})`
+        );
+    }
+
+    const joint_count = ordered.length;
+
+    const joint = new Int32Array(joint_count);
+    const joint_parent = new Int32Array(joint_count);
+
+    const rest_position = new Float32Array(joint_count * 3);
+    const rest_rotation = new Float32Array(joint_count * 4);
+
+    const joint_name = [];
+
+    for (let i = 0; i < joint_count; i++) {
+        const node = ordered[i];
+
+        const resolved = index_of.get(node);
+
+        if (resolved === undefined) {
+            return refuse(`${name}: "${node.name}" is not a joint of this skin`);
+        }
+
+        joint[i] = resolved;
+        joint_parent[i] = members.has(node.parent) ? position.get(node.parent) : -1;
+
+        joint_name.push(node.name);
+
+        const local = node.transform_local;
+
+        rest_position[i * 3] = local[TRANSFORM64_TRANSLATION_OFFSET];
+        rest_position[i * 3 + 1] = local[TRANSFORM64_TRANSLATION_OFFSET + 1];
+        rest_position[i * 3 + 2] = local[TRANSFORM64_TRANSLATION_OFFSET + 2];
+
+        rest_rotation[i * 4] = local[TRANSFORM64_ROTATION_OFFSET];
+        rest_rotation[i * 4 + 1] = local[TRANSFORM64_ROTATION_OFFSET + 1];
+        rest_rotation[i * 4 + 2] = local[TRANSFORM64_ROTATION_OFFSET + 2];
+        rest_rotation[i * 4 + 3] = local[TRANSFORM64_ROTATION_OFFSET + 3];
+
+        // A joint at no distance from its parent is a zero-length link, which
+        // has no direction for a stretch row's gradient and no rest length for
+        // it to hold. §7 P8 rejects it at build time rather than tolerating it
+        // at runtime, which is what "build-time validation, not runtime
+        // tolerance" means. The root is included: its parent is the anchor.
+        const length = Math.hypot(
+            rest_position[i * 3], rest_position[i * 3 + 1], rest_position[i * 3 + 2]
+        );
+
+        if (length <= 0) {
+            return refuse(
+                `${name}: "${node.name}" sits exactly on its parent, so the link between them`
+                + ` has no length and no direction`
+            );
+        }
+    }
+
+    return {
+        proxy: ClothProxy.from({
+            name,
+            joint,
+            joint_parent,
+            anchor,
+            rest_position,
+            rest_rotation,
+            joint_name
+        }),
+        error: ""
+    };
+}
+
+/**
+ * @param {string} error
+ * @returns {ClothProxyBuildResult}
+ * @private
+ */
+function refuse(error) {
+    return { proxy: null, error };
+}