@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -9,63 +9,91 @@
  * ## 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`.
+ * runtime**, and that is §3.2's central commitment. {@link joint} holds indices
+ * into `Skin#joints`, resolved at build time; indices into a skin are stable
+ * across respawns where entity ids are not.
  *
- * {@link joint_name} is the exception and it is build-time provenance: it is
+ * {@link particle_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
+ * ## Particles, and which of them cloth writes
  *
- * §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.
+ * Every particle is a joint of the skin. Most are the garment's own — an artist
+ * made 8–20 cape joints and skinned the cape to them — and those are the ones
+ * cloth simulates and writes ({@link output} set). The rest are the **bones the
+ * garment hangs from**: the parent of each of the garment's root joints, which
+ * is not the garment's to move. They are particles all the same, because the
+ * links from them to the roots are the first links of the fabric, and what holds
+ * them is whatever holds anything — a `ClothPin`, on the bone itself:
  *
- * 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.
+ * ```js
+ * for (const group of built.groups) {
+ *     skin.joints[group.joint].add(ClothPin.from({ cloth: character, particles: group.particles }));
+ * }
+ * ```
+ *
+ * A garment hanging from one bone is today's cape; one hanging from both
+ * shoulders and the spine is the same proxy with three such particles.
+ *
+ * ## The fabric is the proxy's
+ *
+ * {@link edge}, {@link skip} and {@link hinge} are the particle graph the rows
+ * are built from — a joint chain's links and the pairs two links apart, or a
+ * sheet's triangle edges and the hinges across them. {@link parent} is a
+ * different thing: the hierarchy the *output* is written against, which for a
+ * chain happens to run along the same links and for a sheet runs nowhere — every
+ * joint of a generated skin hangs straight off the frame.
+ *
+ * ## The frame is named, and it holds nothing
+ *
+ * {@link frame} is the joint the garment **rides**: the cloth is simulated in its
+ * frame, and its motion is what §7 P7's inertia and limits soften. It is chosen
+ * at build — the one bone a garment hangs from, or the nearest joint above all
+ * of them — and it decides nothing about what is held.
  *
  * ## 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.
+ * {@link rest_position} and {@link rest_rotation} are each particle's bind pose
+ * **in the frame joint's bind pose**, carried in the proxy rather than read from
+ * the instance at seed. Reading them from the instance works exactly once: cloth
+ * takes ownership of the joints' offsets 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.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export class ClothProxy {
     /**
-     * @param {object} description
+     * @param {object} description every field but `name` and `particle_name` required
      * @param {string} [description.name]
      * @param {Int32Array|number[]} description.joint
-     * @param {Int32Array|number[]} description.joint_parent
-     * @param {number} description.anchor
+     * @param {Uint8Array|number[]} description.output
+     * @param {Int32Array|number[]} description.parent
+     * @param {Int32Array|number[]} description.edge
+     * @param {Int32Array|number[]} description.skip
+     * @param {Int32Array|number[]} description.hinge
+     * @param {Int32Array|number[]} description.triangle
+     * @param {number} description.frame
      * @param {Float32Array|number[]} description.rest_position
      * @param {Float32Array|number[]} description.rest_rotation
-     * @param {string[]} [description.joint_name]
+     * @param {string[]} [description.particle_name]
      * @returns {ClothProxy}
      */
-    static from({ name, joint, joint_parent, anchor, rest_position, rest_rotation, joint_name }: {
+    static from({ name, joint, output, parent, edge, skip, hinge, triangle, frame, rest_position, rest_rotation, particle_name }: {
         name?: string;
         joint: Int32Array | number[];
-        joint_parent: Int32Array | number[];
-        anchor: number;
+        output: Uint8Array | number[];
+        parent: Int32Array | number[];
+        edge: Int32Array | number[];
+        skip: Int32Array | number[];
+        hinge: Int32Array | number[];
+        triangle: Int32Array | number[];
+        frame: number;
         rest_position: Float32Array | number[];
         rest_rotation: Float32Array | number[];
-        joint_name?: string[];
+        particle_name?: string[];
     }): ClothProxy;
     /**
      * Name, for diagnostics and for a tool listing the proxies an asset carries.
@@ -73,57 +101,79 @@ export class ClothProxy {
      */
     name: string;
     /**
-     * How many joints this proxy simulates. The anchor is **not** one of them.
+     * How many particles this proxy has.
      * @type {number}
      */
-    joint_count: number;
+    particle_count: number;
     /**
-     * Index into `Skin#joints` for each simulated joint.
+     * Index into `Skin#joints` for each particle.
      * @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.
+     * `1` for a garment joint cloth simulates and writes, `0` for a bone the
+     * garment hangs from, which cloth only reads.
+     * @type {Uint8Array}
+     */
+    output: Uint8Array;
+    /**
+     * Parent of each particle's joint, as an index into this proxy's own
+     * particles, or `-1` for a joint whose parent is not one of them: a bone the
+     * garment hangs from, or — for a garment that writes it — a joint hanging
+     * straight off the frame joint.
      *
-     * 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.
+     * Parents before children, so one forward pass composes the whole forest —
+     * the same ordering `cloth_seed_subtree` gets from a breadth-first walk, and
+     * for the same reason.
      * @type {Int32Array}
      */
-    joint_parent: Int32Array;
+    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.
+     * The fabric: particle pairs joined by a hard stretch row, 2 per edge.
+     * @type {Int32Array}
+     */
+    edge: Int32Array;
+    /**
+     * A chain's bending: particle pairs two links apart, 2 per pair.
+     * @type {Int32Array}
+     */
+    skip: Int32Array;
+    /**
+     * A surface's bending: the shared edge, then the wing opposite it in each
+     * of its two triangles, 4 per hinge — `cloth_bend_row`'s stencil.
+     * @type {Int32Array}
+     */
+    hinge: Int32Array;
+    /**
+     * Triangles over the particles, 3 per triangle, for a garment that has a
+     * surface: what its joints' orientation is read off. Empty for a chain.
+     * @type {Int32Array}
+     */
+    triangle: Int32Array;
+    /**
+     * Index into `Skin#joints` of the joint whose frame the garment is
+     * simulated in.
      * @type {number}
      */
-    anchor: number;
+    frame: number;
     /**
-     * Each joint's bind-pose local translation, 3 per joint.
+     * Each particle's bind-pose position in the frame joint's bind pose, 3 per
+     * particle.
      * @type {Float32Array}
      */
     rest_position: Float32Array;
     /**
-     * Each joint's bind-pose local rotation, 4 per joint.
+     * Each particle's bind-pose orientation in the frame joint's bind pose, 4
+     * per particle.
      * @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.
+     * Names, in particle order. Build-time provenance; nothing on the step path
+     * reads it.
      * @type {string[]}
      */
-    joint_name: string[];
+    particle_name: string[];
     /**
      * Whether this proxy can address the skin it is about to be used with.
      *
@@ -134,10 +184,12 @@ export class ClothProxy {
      * condition, and this is what turns it into a message naming the joint
      * instead of a garment simulating somebody's spine.
      *
-     * @param {Skin} skin
+     * @param {{joints: ArrayLike<number>}} skin a `MeshSkin`, or anything with joints in the order the proxy indexes
      * @returns {string} empty when the proxy fits, otherwise what is wrong
      */
-    checkAgainst(skin: Skin): string;
+    checkAgainst(skin: {
+        joints: ArrayLike<number>;
+    }): string;
     /**
      * @readonly
      * @type {boolean}

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

@@ -1 +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"}
+{"version":3,"file":"ClothProxy.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/ClothProxy.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH;IA8FI;;;;;;;;;;;;;;;OAeG;IACH;QAdgC,IAAI,GAAzB,MAAM;QAC2B,KAAK,EAAtC,UAAU,GAAC,MAAM,EAAE;QACc,MAAM,EAAvC,UAAU,GAAC,MAAM,EAAE;QACc,MAAM,EAAvC,UAAU,GAAC,MAAM,EAAE;QACc,IAAI,EAArC,UAAU,GAAC,MAAM,EAAE;QACc,IAAI,EAArC,UAAU,GAAC,MAAM,EAAE;QACc,KAAK,EAAtC,UAAU,GAAC,MAAM,EAAE;QACc,QAAQ,EAAzC,UAAU,GAAC,MAAM,EAAE;QACC,KAAK,EAAzB,MAAM;QAC6B,aAAa,EAAhD,YAAY,GAAC,MAAM,EAAE;QACc,aAAa,EAAhD,YAAY,GAAC,MAAM,EAAE;QACE,aAAa,GAApC,MAAM,EAAE;QACN,UAAU,CAsDtB;IAhKD;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,OAFU,UAAU,CAEP;IAEb;;;;OAIG;IACH,QAFU,UAAU,CAEN;IAEd;;;;;;;;;;OAUG;IACH,QAFU,UAAU,CAEN;IAEd;;;OAGG;IACH,MAFU,UAAU,CAER;IAEZ;;;OAGG;IACH,MAFU,UAAU,CAER;IAEZ;;;;OAIG;IACH,OAFU,UAAU,CAEP;IAEb;;;;OAIG;IACH,UAFU,UAAU,CAEJ;IAEhB;;;;OAIG;IACH,OAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,eAFU,YAAY,CAED;IAErB;;;;OAIG;IACH,eAFU,YAAY,CAED;IAErB;;;;OAIG;IACH,eAFU,MAAM,EAAE,CAEC;IAwEnB;;;;;;;;;;;;OAYG;IACH,mBAHW;QAAC,MAAM,EAAE,UAAU,MAAM,CAAC,CAAA;KAAC,GACzB,MAAM,CAqBlB;IAGL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;CANhC"}

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

@@ -11,39 +11,57 @@ import { assert } from "../../../../core/assert.js";
  * ## 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`.
+ * runtime**, and that is §3.2's central commitment. {@link joint} holds indices
+ * into `Skin#joints`, resolved at build time; indices into a skin are stable
+ * across respawns where entity ids are not.
  *
- * {@link joint_name} is the exception and it is build-time provenance: it is
+ * {@link particle_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
+ * ## Particles, and which of them cloth writes
  *
- * §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.
+ * Every particle is a joint of the skin. Most are the garment's own — an artist
+ * made 8–20 cape joints and skinned the cape to them — and those are the ones
+ * cloth simulates and writes ({@link output} set). The rest are the **bones the
+ * garment hangs from**: the parent of each of the garment's root joints, which
+ * is not the garment's to move. They are particles all the same, because the
+ * links from them to the roots are the first links of the fabric, and what holds
+ * them is whatever holds anything — a `ClothPin`, on the bone itself:
  *
- * 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.
+ * ```js
+ * for (const group of built.groups) {
+ *     skin.joints[group.joint].add(ClothPin.from({ cloth: character, particles: group.particles }));
+ * }
+ * ```
+ *
+ * A garment hanging from one bone is today's cape; one hanging from both
+ * shoulders and the spine is the same proxy with three such particles.
+ *
+ * ## The fabric is the proxy's
+ *
+ * {@link edge}, {@link skip} and {@link hinge} are the particle graph the rows
+ * are built from — a joint chain's links and the pairs two links apart, or a
+ * sheet's triangle edges and the hinges across them. {@link parent} is a
+ * different thing: the hierarchy the *output* is written against, which for a
+ * chain happens to run along the same links and for a sheet runs nowhere — every
+ * joint of a generated skin hangs straight off the frame.
+ *
+ * ## The frame is named, and it holds nothing
+ *
+ * {@link frame} is the joint the garment **rides**: the cloth is simulated in its
+ * frame, and its motion is what §7 P7's inertia and limits soften. It is chosen
+ * at build — the one bone a garment hangs from, or the nearest joint above all
+ * of them — and it decides nothing about what is held.
  *
  * ## 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.
+ * {@link rest_position} and {@link rest_rotation} are each particle's bind pose
+ * **in the frame joint's bind pose**, carried in the proxy rather than read from
+ * the instance at seed. Reading them from the instance works exactly once: cloth
+ * takes ownership of the joints' offsets 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.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -57,110 +75,157 @@ export class ClothProxy {
     name = "";
 
     /**
-     * How many joints this proxy simulates. The anchor is **not** one of them.
+     * How many particles this proxy has.
      * @type {number}
      */
-    joint_count = 0;
+    particle_count = 0;
 
     /**
-     * Index into `Skin#joints` for each simulated joint.
+     * Index into `Skin#joints` for each particle.
      * @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.
+     * `1` for a garment joint cloth simulates and writes, `0` for a bone the
+     * garment hangs from, which cloth only reads.
+     * @type {Uint8Array}
+     */
+    output = null;
+
+    /**
+     * Parent of each particle's joint, as an index into this proxy's own
+     * particles, or `-1` for a joint whose parent is not one of them: a bone the
+     * garment hangs from, or — for a garment that writes it — a joint hanging
+     * straight off the frame joint.
      *
-     * 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.
+     * Parents before children, so one forward pass composes the whole forest —
+     * the same ordering `cloth_seed_subtree` gets from a breadth-first walk, and
+     * for the same reason.
      * @type {Int32Array}
      */
-    joint_parent = null;
+    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.
+     * The fabric: particle pairs joined by a hard stretch row, 2 per edge.
+     * @type {Int32Array}
+     */
+    edge = null;
+
+    /**
+     * A chain's bending: particle pairs two links apart, 2 per pair.
+     * @type {Int32Array}
+     */
+    skip = null;
+
+    /**
+     * A surface's bending: the shared edge, then the wing opposite it in each
+     * of its two triangles, 4 per hinge — `cloth_bend_row`'s stencil.
+     * @type {Int32Array}
+     */
+    hinge = null;
+
+    /**
+     * Triangles over the particles, 3 per triangle, for a garment that has a
+     * surface: what its joints' orientation is read off. Empty for a chain.
+     * @type {Int32Array}
+     */
+    triangle = null;
+
+    /**
+     * Index into `Skin#joints` of the joint whose frame the garment is
+     * simulated in.
      * @type {number}
      */
-    anchor = -1;
+    frame = -1;
 
     /**
-     * Each joint's bind-pose local translation, 3 per joint.
+     * Each particle's bind-pose position in the frame joint's bind pose, 3 per
+     * particle.
      * @type {Float32Array}
      */
     rest_position = null;
 
     /**
-     * Each joint's bind-pose local rotation, 4 per joint.
+     * Each particle's bind-pose orientation in the frame joint's bind pose, 4
+     * per particle.
      * @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.
+     * Names, in particle order. Build-time provenance; nothing on the step path
+     * reads it.
      * @type {string[]}
      */
-    joint_name = [];
+    particle_name = [];
 
     /**
-     * @param {object} description
+     * @param {object} description every field but `name` and `particle_name` required
      * @param {string} [description.name]
      * @param {Int32Array|number[]} description.joint
-     * @param {Int32Array|number[]} description.joint_parent
-     * @param {number} description.anchor
+     * @param {Uint8Array|number[]} description.output
+     * @param {Int32Array|number[]} description.parent
+     * @param {Int32Array|number[]} description.edge
+     * @param {Int32Array|number[]} description.skip
+     * @param {Int32Array|number[]} description.hinge
+     * @param {Int32Array|number[]} description.triangle
+     * @param {number} description.frame
      * @param {Float32Array|number[]} description.rest_position
      * @param {Float32Array|number[]} description.rest_rotation
-     * @param {string[]} [description.joint_name]
+     * @param {string[]} [description.particle_name]
      * @returns {ClothProxy}
      */
     static from({
         name = "",
         joint,
-        joint_parent,
-        anchor,
+        output,
+        parent,
+        edge,
+        skip,
+        hinge,
+        triangle,
+        frame,
         rest_position,
         rest_rotation,
-        joint_name = []
+        particle_name = []
     }) {
-        const joint_count = joint.length;
+        const particle_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');
+        assert.equal(output.length, particle_count, 'output.length');
+        assert.equal(parent.length, particle_count, 'parent.length');
+        assert.equal(rest_position.length, particle_count * 3, 'rest_position.length');
+        assert.equal(rest_rotation.length, particle_count * 4, 'rest_rotation.length');
+        assert.isNonNegativeInteger(frame, 'frame');
+        assert.equal(edge.length % 2, 0, 'edge.length is a whole number of pairs');
+        assert.equal(skip.length % 2, 0, 'skip.length is a whole number of pairs');
+        assert.equal(hinge.length % 4, 0, 'hinge.length is a whole number of quads');
+        assert.equal(triangle.length % 3, 0, 'triangle.length is a whole number of triples');
 
-        for (let i = 0; i < joint_count; i++) {
-            // Parents before children: the composition down the chain is one
+        for (let i = 0; i < particle_count; i++) {
+            // Parents before children: the composition down the forest 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`
+                parent[i] < i,
+                `ClothProxy particle ${i} has parent ${parent[i]}, which is not before it`
             );
         }
 
         const r = new ClothProxy();
 
         r.name = name;
-        r.joint_count = joint_count;
+        r.particle_count = particle_count;
         r.joint = Int32Array.from(joint);
-        r.joint_parent = Int32Array.from(joint_parent);
-        r.anchor = anchor;
+        r.output = Uint8Array.from(output);
+        r.parent = Int32Array.from(parent);
+        r.edge = Int32Array.from(edge);
+        r.skip = Int32Array.from(skip);
+        r.hinge = Int32Array.from(hinge);
+        r.triangle = Int32Array.from(triangle);
+        r.frame = frame;
         r.rest_position = Float32Array.from(rest_position);
         r.rest_rotation = Float32Array.from(rest_rotation);
-        r.joint_name = joint_name.slice();
+        r.particle_name = particle_name.slice();
 
         return r;
     }
@@ -175,7 +240,7 @@ export class ClothProxy {
      * condition, and this is what turns it into a message naming the joint
      * instead of a garment simulating somebody's spine.
      *
-     * @param {Skin} skin
+     * @param {{joints: ArrayLike<number>}} skin a `MeshSkin`, or anything with joints in the order the proxy indexes
      * @returns {string} empty when the proxy fits, otherwise what is wrong
      */
     checkAgainst(skin) {
@@ -185,14 +250,14 @@ export class ClothProxy {
 
         const count = skin.joints.length;
 
-        if (this.anchor >= count) {
-            return `${this.name}: anchor is joint ${this.anchor} of a skin with ${count}`;
+        if (this.frame >= count) {
+            return `${this.name}: frame is joint ${this.frame} of a skin with ${count}`;
         }
 
-        for (let i = 0; i < this.joint_count; i++) {
+        for (let i = 0; i < this.particle_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 `${this.name}: particle ${i} (${this.particle_name[i] ?? '?'})`
+                    + ` is joint ${this.joint[i]} of a skin with ${count}`;
             }
         }
 

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

@@ -0,0 +1,44 @@
+/**
+ * @typedef {import("../../../graphics3/prefab/Prefab.js").Prefab} Prefab
+ */
+/**
+ * Each node's bind pose relative to the frame node's, composed from the
+ * prefab's local rest poses down from the frame, `[tx, ty, tz, qx, qy, qz, qw]`.
+ * Every node asked about hangs below the frame.
+ *
+ * Both proxy builders bake their rest pose this way — in the frame joint's own
+ * bind pose — so that a re-seed reads what was authored rather than what the
+ * solver left on the joints.
+ *
+ * Rigid, as every pose cloth holds is: a local scale is not applied. That is
+ * not a convention this can opt out of alone — the write-back is rigid too,
+ * and the GPU applies a parent's scale on top of what cloth writes, so a
+ * scaled bake would draw a scaled link twice over. A builder refuses a rig
+ * where it would matter, with {@link cloth_bind_scaled_above}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ *
+ * @param {Prefab} prefab
+ * @param {number} frame
+ * @returns {function(number): Float64Array}
+ */
+export function cloth_bind_in_frame(prefab: Prefab, frame: number): (arg0: number) => Float64Array;
+/**
+ * The nearest node above `node`, up to and including the prefab's root, whose
+ * rest scale is not one; or -1.
+ *
+ * Cloth simulates and writes back rigid poses, and everything under a scaled
+ * node is drawn scaled: a link below one is simulated at its authored length and
+ * drawn at that times the scale, and a scale above the frame draws the whole
+ * garment at another size than the one its colliders meet. Measured, a 10 cm
+ * chain under a joint scaled by 2: simulated links 0.1, drawn 0.2. A node's own
+ * scale moves nothing cloth places, so it is not asked about.
+ *
+ * @param {Prefab} prefab
+ * @param {number} node
+ * @returns {number}
+ */
+export function cloth_bind_scaled_above(prefab: Prefab, node: number): number;
+export type Prefab = import("../../../graphics3/prefab/Prefab.js").Prefab;
+//# sourceMappingURL=cloth_bind_in_frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloth_bind_in_frame.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/build/cloth_bind_in_frame.js"],"names":[],"mappings":"AAOA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAJW,MAAM,SACN,MAAM,UACK,MAAM,KAAG,YAAY,CAqC1C;AASD;;;;;;;;;;;;;;GAcG;AACH,gDAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAgBlB;qBAlGY,OAAO,qCAAqC,EAAE,MAAM"}