@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -1,6 +1,11 @@
 import { quat3_multiply_array } from "../../../../core/geom/3d/quaternion/quat3_multiply.js";
 import { quat3_nlerp_array } from "../../../../core/geom/3d/quaternion/quat3_nlerp.js";
 import { quat3_shortest_arc_array } from "../../../../core/geom/3d/quaternion/quat3_shortest_arc.js";
+import { tri3_compute_normal_area_weighted_array } from "../../../../core/geom/3d/triangle/tri3_compute_normal_area_weighted_array.js";
+import { v3_normalize_array_checked } from "../../../../core/geom/vec3/v3_normalize_array_checked.js";
+import { v3_quaternion_apply_array } from "../../../../core/geom/vec3/v3_quaternion_apply.js";
+import { v3_reject_array } from "../../../../core/geom/vec3/v3_reject_array.js";
+import { clamp01 } from "../../../../core/math/clamp01.js";
 
 /**
  * # From particles to a pose — the half of the write-back that is arithmetic
@@ -34,6 +39,19 @@ import { quat3_shortest_arc_array } from "../../../../core/geom/3d/quaternion/qu
  * every link points at its child and a two-link chain reads as a hinge with a
  * corner in it.
  *
+ * ## A node on a surface turns with the surface
+ *
+ * A sheet's joints have no chain to swing along — a generated skin hangs every
+ * one of them off the frame — and what a joint's orientation is *for* there is
+ * the normal it turns its vertex's normal by. So a node with triangles around
+ * it takes the rotation that carries its animated surface onto its simulated
+ * one: a swing taking the area-weighted normal of its triangles onto the
+ * normal they have now, then a twist about that normal taking one fixed
+ * neighbour's direction onto where it is now. Both are shortest arcs, so there
+ * is no basis to orthonormalise and nothing new in `core`; M3's joint-budget
+ * fixture fits the same two directions. A surface that has collapsed to a line
+ * at the node keeps whichever half still has a direction.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -44,7 +62,7 @@ import { quat3_shortest_arc_array } from "../../../../core/geom/3d/quaternion/qu
  * @type {Float64Array}
  * @private
  */
-const SWING = new Float64Array(12);
+const SWING = new Float64Array(16);
 
 /** Where the parent-driven swing sits in {@link SWING}. @private */
 const SWING_PARENT = 0;
@@ -52,6 +70,8 @@ const SWING_PARENT = 0;
 const SWING_CHILD = 4;
 /** Where the blended swing sits. @private */
 const SWING_OUT = 8;
+/** Where a surface's twist sits. @private */
+const SWING_TWIST = 12;
 
 /**
  * @type {Float64Array}
@@ -59,13 +79,21 @@ const SWING_OUT = 8;
  */
 const DIRECTION = new Float64Array(12);
 
+/**
+ * Squared length below which a direction in {@link DIRECTION} is rounding
+ * rather than a direction, and is left as it was.
+ * @type {number}
+ * @private
+ */
+const NO_DIRECTION_SQR = 1e-24;
+
 /**
  * Fill `blended_position` and `blended_rotation` from the solved particles.
  *
  * Both are in the **cloth's own frame**: the position is the particle lerped
  * towards its animated one by `Cloth#blend`, and the rotation is the swing
- * composed onto the animated orientation. Node 0 — the anchor — is the origin of
- * that frame, so its rotation is the identity rather than anything read off it.
+ * composed onto the animated orientation. A root of the seeder's tree has no
+ * link above it and takes its children's swing alone.
  *
  * @param {ClothInstance} instance
  * @returns {void}
@@ -79,13 +107,7 @@ export function cloth_reconstruct_pose(instance) {
     const blended = instance.blended_position;
     const animated = instance.animated_position;
 
-    let blend = instance.cloth.blend;
-
-    if (blend < 0) {
-        blend = 0;
-    } else if (blend > 1) {
-        blend = 1;
-    }
+    const blend = clamp01(instance.cloth.blend);
 
     const position = state.position;
 
@@ -103,13 +125,23 @@ export function cloth_reconstruct_pose(instance) {
 
     const reconstructed = instance.blended_rotation;
 
-    reconstructed[0] = 0;
-    reconstructed[1] = 0;
-    reconstructed[2] = 0;
-    reconstructed[3] = 1;
+    const surface_offset = instance.surface_offset;
+
+    for (let node = 0; node < node_count; node++) {
+        if (surface_offset !== null && surface_offset[node + 1] > surface_offset[node]) {
+            surface_turn(instance, node, SWING_OUT);
+
+            quat3_multiply_array(reconstructed, node * 4, SWING, SWING_OUT, rotation, node * 4);
+
+            continue;
+        }
+
+        const has_parent_swing = parent[node] >= 0 && link_swing(instance, parent[node], node, SWING_PARENT);
+
+        if (!has_parent_swing) {
+            identity(SWING_PARENT);
+        }
 
-    for (let node = 1; node < node_count; node++) {
-        const has_parent_swing = link_swing(instance, parent[node], node, SWING_PARENT);
         const has_child_swing = children_swing(instance, node, SWING_CHILD);
 
         let swing = SWING_OUT;
@@ -133,6 +165,120 @@ export function cloth_reconstruct_pose(instance) {
     }
 }
 
+/**
+ * The turn that carries a node's animated surface onto its simulated one, into
+ * `SWING` at `out` — see the module docblock.
+ *
+ * @param {ClothInstance} instance
+ * @param {number} node with triangles around it
+ * @param {number} out
+ * @private
+ */
+function surface_turn(instance, node, out) {
+    const animated = instance.animated_position;
+    const blended = instance.blended_position;
+
+    surface_normal(DIRECTION, 0, instance, animated, node);
+    surface_normal(DIRECTION, 3, instance, blended, node);
+
+    const has_normal =
+        v3_normalize_array_checked(DIRECTION, 0, DIRECTION, 0, NO_DIRECTION_SQR) &&
+        v3_normalize_array_checked(DIRECTION, 3, DIRECTION, 3, NO_DIRECTION_SQR);
+
+    // the swing: normal onto normal
+    if (has_normal) {
+        quat3_shortest_arc_array(SWING, out, DIRECTION, 0, DIRECTION, 3);
+    } else {
+        identity(out);
+    }
+
+    const neighbour = instance.surface_neighbour[node];
+
+    const a = node * 3;
+    const b = neighbour * 3;
+
+    // the neighbour's animated direction, swung; and its simulated one
+    TANGENT[0] = animated[b] - animated[a];
+    TANGENT[1] = animated[b + 1] - animated[a + 1];
+    TANGENT[2] = animated[b + 2] - animated[a + 2];
+
+    v3_quaternion_apply_array(DIRECTION, 6, TANGENT, 0, SWING, out);
+
+    DIRECTION[9] = blended[b] - blended[a];
+    DIRECTION[10] = blended[b + 1] - blended[a + 1];
+    DIRECTION[11] = blended[b + 2] - blended[a + 2];
+
+    if (has_normal) {
+        // both into the plane the normal leaves them, so the arc between them
+        // turns about the normal and nothing else
+        v3_reject_array(DIRECTION, 6, DIRECTION, 6, DIRECTION, 3);
+        v3_reject_array(DIRECTION, 9, DIRECTION, 9, DIRECTION, 3);
+    }
+
+    if (
+        !v3_normalize_array_checked(DIRECTION, 6, DIRECTION, 6, NO_DIRECTION_SQR) ||
+        !v3_normalize_array_checked(DIRECTION, 9, DIRECTION, 9, NO_DIRECTION_SQR)
+    ) {
+        return;
+    }
+
+    // the twist, then the swing it follows
+    quat3_shortest_arc_array(SWING, SWING_TWIST, DIRECTION, 6, DIRECTION, 9);
+
+    quat3_multiply_array(SWING, out, SWING, SWING_TWIST, SWING, out);
+}
+
+/**
+ * One triangle's area-weighted normal, before it is summed.
+ * @type {Float64Array}
+ * @private
+ */
+const FACE_NORMAL = new Float64Array(3);
+
+/**
+ * The area-weighted normal of the triangles around a node, unnormalised, into
+ * `out` at `offset`.
+ *
+ * @param {Float64Array} out
+ * @param {number} offset
+ * @param {ClothInstance} instance
+ * @param {Float64Array} position 3 per node
+ * @param {number} node
+ * @private
+ */
+function surface_normal(out, offset, instance, position, node) {
+    const triangle = instance.triangle;
+    const surface = instance.surface_triangle;
+
+    let nx = 0, ny = 0, nz = 0;
+
+    for (let k = instance.surface_offset[node]; k < instance.surface_offset[node + 1]; k++) {
+        const t = surface[k] * 3;
+
+        // twice the area, along the normal: the weighting is the cross product's own length
+        tri3_compute_normal_area_weighted_array(
+            FACE_NORMAL, 0,
+            position, triangle[t] * 3,
+            position, triangle[t + 1] * 3,
+            position, triangle[t + 2] * 3
+        );
+
+        nx += FACE_NORMAL[0];
+        ny += FACE_NORMAL[1];
+        nz += FACE_NORMAL[2];
+    }
+
+    out[offset] = nx;
+    out[offset + 1] = ny;
+    out[offset + 2] = nz;
+}
+
+/**
+ * @type {Float64Array}
+ * @private
+ */
+const TANGENT = new Float64Array(3);
+
 /**
  * Swing of the link from `from` to `to`, into `SWING` at `out`.
  *
@@ -159,8 +305,8 @@ function link_swing(instance, from, to, out) {
     DIRECTION[4] = blended[b + 1] - blended[a + 1];
     DIRECTION[5] = blended[b + 2] - blended[a + 2];
 
-    const has_animated = unit(DIRECTION, 0);
-    const has_blended = unit(DIRECTION, 3);
+    const has_animated = v3_normalize_array_checked(DIRECTION, 0, DIRECTION, 0, NO_DIRECTION_SQR);
+    const has_blended = v3_normalize_array_checked(DIRECTION, 3, DIRECTION, 3, NO_DIRECTION_SQR);
 
     if (!has_animated || !has_blended) {
         identity(out);
@@ -212,7 +358,7 @@ function children_swing(instance, node, out) {
         DIRECTION[7] = animated[b + 1] - animated[a + 1];
         DIRECTION[8] = animated[b + 2] - animated[a + 2];
 
-        if (unit(DIRECTION, 6)) {
+        if (v3_normalize_array_checked(DIRECTION, 6, DIRECTION, 6, NO_DIRECTION_SQR)) {
             anim_x += DIRECTION[6];
             anim_y += DIRECTION[7];
             anim_z += DIRECTION[8];
@@ -222,7 +368,7 @@ function children_swing(instance, node, out) {
         DIRECTION[10] = blended[b + 1] - blended[a + 1];
         DIRECTION[11] = blended[b + 2] - blended[a + 2];
 
-        if (unit(DIRECTION, 9)) {
+        if (v3_normalize_array_checked(DIRECTION, 9, DIRECTION, 9, NO_DIRECTION_SQR)) {
             sim_x += DIRECTION[9];
             sim_y += DIRECTION[10];
             sim_z += DIRECTION[11];
@@ -237,8 +383,8 @@ function children_swing(instance, node, out) {
     DIRECTION[4] = sim_y;
     DIRECTION[5] = sim_z;
 
-    const has_animated = unit(DIRECTION, 0);
-    const has_blended = unit(DIRECTION, 3);
+    const has_animated = v3_normalize_array_checked(DIRECTION, 0, DIRECTION, 0, NO_DIRECTION_SQR);
+    const has_blended = v3_normalize_array_checked(DIRECTION, 3, DIRECTION, 3, NO_DIRECTION_SQR);
 
     if (!has_animated || !has_blended) {
         // Branches that cancel — a node with two children pointing opposite
@@ -254,35 +400,6 @@ function children_swing(instance, node, out) {
     return true;
 }
 
-/**
- * Normalise the vector at `offset` in place, reporting whether there was a direction to find; one
- * that was not is left as it was.
- *
- * @param {Float64Array} out
- * @param {number} offset
- * @returns {boolean}
- * @private
- */
-function unit(out, offset) {
-    const x = out[offset];
-    const y = out[offset + 1];
-    const z = out[offset + 2];
-
-    const length_squared = x * x + y * y + z * z;
-
-    if (length_squared < 1e-24) {
-        return false;
-    }
-
-    const inverse = 1 / Math.sqrt(length_squared);
-
-    out[offset] = x * inverse;
-    out[offset + 1] = y * inverse;
-    out[offset + 2] = z * inverse;
-
-    return true;
-}
-
 /**
  * @param {number} offset
  * @private

package/src/engine/physics/cloth/ecs/cloth_seed_rig.d.ts

@@ -1,9 +1,9 @@
 /**
  * # Seeding a cloth from a skinned model's joints — §11.2
  *
- * One particle per joint the proxy names, with the anchor as the fixed set, and
- * everything after that is `cloth_build_rows.js` — the same rows, the same
- * geodesics, the same leashes the entity path gets. §11 says "the solver is
+ * One particle per joint the proxy names — the garment's own and the bones it
+ * hangs from — and everything after that is `cloth_build_rows.js`: the same
+ * rows, the same leashes the entity path gets. §11 says "the solver is
  * identical either way; only seeding and write-back differ", and this file plus
  * `cloth_write_back_rig.js` is the whole of the difference.
  *
@@ -16,28 +16,23 @@
  * after the CPU's flush and whatever any bit says. The bit states that, and
  * stops the flush from racing it; it does not stop the clip.
  *
- * So the seed **holds** every joint it drives (`gpu_authority_hold`): the bit
- * clears, the animation manager mutes every binding that names the joint, and
- * the row is what the write-back wrote. A clip that binds a held joint later
- * binds muted, and one that leaves it leaves cloth's offset alone. Ending the
- * hold grants nothing; a clip still bound takes the joint back. So a cape
- * simulates under a clip that keys its bones too — exporters often bake every
- * bone — and the exact evaluation (`t64_evaluate_world`) answers a held joint
- * with cloth's offset, as the GPU shows it.
+ * So the seed **holds** every garment joint it drives (`gpu_authority_hold`):
+ * the bit clears, the animation manager mutes every binding that names the
+ * joint, and the row is what the write-back wrote. A clip that binds a held
+ * joint later binds muted, and one that leaves it leaves cloth's offset alone.
+ * Ending the hold grants nothing; a clip still bound takes the joint back. So a
+ * cape simulates under a clip that keys its bones too — exporters often bake
+ * every bone — and the exact evaluation (`t64_evaluate_world`) answers a held
+ * joint with cloth's offset, as the GPU shows it.
  *
- * ## The animated pose is constant, exactly as it is for a rope
+ * The bones the garment hangs from are not held: they are the character's, and
+ * cloth only reads them — each step, exactly, for the write-back to express the
+ * garment's roots against (`ClothInstance#boundary_pose`).
  *
- * §11.1 says a subtree's authored pose is rigid relative to its anchor, so in
- * the anchor's own frame it does not move, and then says "a subtree whose links
- * are themselves animated is not an M1 case — that is the rig path, where the
- * animated pose comes from the skeleton and is live".
+ * ## The rest pose is the proxy's
  *
- * For a **rigged** garment it is not live either, and the reason is the
- * hold above: cloth owns those joints, so nothing else poses them,
- * so their authored pose is the proxy's baked bind pose — constant in the
- * anchor's frame, exactly as a rope's is. What moves is the anchor, and the
- * anchor is a joint of the character's own animated skeleton, whose pose the
- * system evaluates exactly (`t64_evaluate_world`).
+ * Baked at build in the frame joint's bind pose, so a re-seed of a live garment
+ * reads the authored shape rather than the shape the solver left behind.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

package/src/engine/physics/cloth/ecs/cloth_seed_rig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_seed_rig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_rig.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;;;;;;;;GAQG;AACH,mFAJW,MAAM,EAAE,mCAER,MAAM,QAqFhB;AAoED;;;;;;;;;;;;;;;;GAgBG;AACH,yFAFa,IAAI,CAoBhB"}
+{"version":3,"file":"cloth_seed_rig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_rig.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;GAQG;AACH,mFAJW,MAAM,EAAE,mCAER,MAAM,QAkGhB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,yFAFa,IAAI,CAoBhB"}

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

@@ -1,18 +1,16 @@
 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 { GPUStateAuthorityFlags } from "../../../ecs/gpu/GPUStateAuthorityFlags.js";
 import { gpu_authority_hold } from "../../../ecs/gpu/gpu_authority_hold.js";
 import { gpu_authority_unhold } from "../../../ecs/gpu/gpu_authority_unhold.js";
 import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
-import { cloth_build_children, cloth_build_rows } from "./cloth_build_rows.js";
+import { cloth_build_children, cloth_build_rows, cloth_build_surface } from "./cloth_build_rows.js";
 
 /**
  * # Seeding a cloth from a skinned model's joints — §11.2
  *
- * One particle per joint the proxy names, with the anchor as the fixed set, and
- * everything after that is `cloth_build_rows.js` — the same rows, the same
- * geodesics, the same leashes the entity path gets. §11 says "the solver is
+ * One particle per joint the proxy names — the garment's own and the bones it
+ * hangs from — and everything after that is `cloth_build_rows.js`: the same
+ * rows, the same leashes the entity path gets. §11 says "the solver is
  * identical either way; only seeding and write-back differ", and this file plus
  * `cloth_write_back_rig.js` is the whole of the difference.
  *
@@ -25,28 +23,23 @@ import { cloth_build_children, cloth_build_rows } from "./cloth_build_rows.js";
  * after the CPU's flush and whatever any bit says. The bit states that, and
  * stops the flush from racing it; it does not stop the clip.
  *
- * So the seed **holds** every joint it drives (`gpu_authority_hold`): the bit
- * clears, the animation manager mutes every binding that names the joint, and
- * the row is what the write-back wrote. A clip that binds a held joint later
- * binds muted, and one that leaves it leaves cloth's offset alone. Ending the
- * hold grants nothing; a clip still bound takes the joint back. So a cape
- * simulates under a clip that keys its bones too — exporters often bake every
- * bone — and the exact evaluation (`t64_evaluate_world`) answers a held joint
- * with cloth's offset, as the GPU shows it.
+ * So the seed **holds** every garment joint it drives (`gpu_authority_hold`):
+ * the bit clears, the animation manager mutes every binding that names the
+ * joint, and the row is what the write-back wrote. A clip that binds a held
+ * joint later binds muted, and one that leaves it leaves cloth's offset alone.
+ * Ending the hold grants nothing; a clip still bound takes the joint back. So a
+ * cape simulates under a clip that keys its bones too — exporters often bake
+ * every bone — and the exact evaluation (`t64_evaluate_world`) answers a held
+ * joint with cloth's offset, as the GPU shows it.
  *
- * ## The animated pose is constant, exactly as it is for a rope
+ * The bones the garment hangs from are not held: they are the character's, and
+ * cloth only reads them — each step, exactly, for the write-back to express the
+ * garment's roots against (`ClothInstance#boundary_pose`).
  *
- * §11.1 says a subtree's authored pose is rigid relative to its anchor, so in
- * the anchor's own frame it does not move, and then says "a subtree whose links
- * are themselves animated is not an M1 case — that is the rig path, where the
- * animated pose comes from the skeleton and is live".
+ * ## The rest pose is the proxy's
  *
- * For a **rigged** garment it is not live either, and the reason is the
- * hold above: cloth owns those joints, so nothing else poses them,
- * so their authored pose is the proxy's baked bind pose — constant in the
- * anchor's frame, exactly as a rope's is. What moves is the anchor, and the
- * anchor is a joint of the character's own animated skeleton, whose pose the
- * system evaluates exactly (`t64_evaluate_world`).
+ * Baked at build in the frame joint's bind pose, so a re-seed of a live garment
+ * reads the authored shape rather than the shape the solver left behind.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -68,50 +61,43 @@ export function cloth_seed_rig(instance, proxy, joints, ecd, dt) {
     // instance, gives the last seeding's holds back first.
     assert.equal(instance.held_joints, null, 'a rig seeds over a rig that still holds its joints; ClothWorld#reseed gives them back first');
 
-    const joint_count = proxy.joint_count;
-
-    // Node 0 is the anchor, exactly as it is for the entity path: the fixed
-    // set, the origin of the local frame, and `d_geo = 0`.
-    const node_count = joint_count + 1;
+    const node_count = proxy.particle_count;
 
     instance.node_count = node_count;
+    instance.node_parent = Int32Array.from(proxy.parent);
+    instance.node_output = Uint8Array.from(proxy.output);
 
-    const node_parent = new Int32Array(node_count);
-
-    node_parent[0] = -1;
+    instance.frame_entity = joints[proxy.frame];
 
-    for (let i = 0; i < joint_count; i++) {
-        node_parent[i + 1] = proxy.joint_parent[i] + 1;
-    }
-
-    instance.node_parent = node_parent;
+    assert.defined(instance.frame_entity, `frame joint ${proxy.frame} of the skin`);
 
     const node_joint = new Int32Array(node_count);
-
-    node_joint[0] = joints[proxy.anchor];
-
     const node_attachment = new Array(node_count);
 
-    node_attachment[0] = null;
-
     // What this seeding holds, so that giving it back is possible. A hold that
     // nothing ends is half a transaction, and the half that is missing is the
     // one that runs when the garment is removed.
     const held = [];
 
-    for (let i = 0; i < joint_count; i++) {
-        const joint = joints[proxy.joint[i]];
+    for (let node = 0; node < node_count; node++) {
+        const joint = joints[proxy.joint[node]];
+
+        assert.defined(joint, `joint ${proxy.joint[node]} of the skin`);
+        assert.ok(ecd.entityExists(joint), `joint ${proxy.joint[node]} of the skin, entity ${joint}, does not exist`);
 
-        assert.defined(joint, `joint ${proxy.joint[i]} of the skin`);
-        assert.ok(ecd.entityExists(joint), `joint ${proxy.joint[i]} of the skin, entity ${joint}, does not exist`);
+        node_joint[node] = joint;
 
-        node_joint[i + 1] = joint;
+        if (proxy.output[node] === 0) {
+            node_attachment[node] = null;
+
+            continue;
+        }
 
         const attachment = ecd.getComponent(joint, TransformAttachment);
 
         assert.defined(attachment, `joint entity ${joint} carries no TransformAttachment to write`);
 
-        node_attachment[i + 1] = attachment;
+        node_attachment[node] = attachment;
 
         // See the module docblock. Every joint, whether or not a clip drives it now: one may bind
         // it later, and the hold is what it finds there.
@@ -135,81 +121,35 @@ export function cloth_seed_rig(instance, proxy, joints, ecd, dt) {
     instance.pruned_transform = [];
     instance.pruned_attachment = [];
 
-    cloth_build_children(instance);
-
-    read_bind_pose(instance, proxy);
-
-    instance.dynamics_seen.copy(instance.cloth.dynamics);
-
-    cloth_build_rows(instance, dt);
-
-    instance.seeded = true;
-}
-
-/**
- * The proxy's bind pose, composed: local offsets per node and the position and
- * rotation of every node in the anchor's frame.
- *
- * @param {ClothInstance} instance
- * @param {ClothProxy} proxy
- */
-function read_bind_pose(instance, proxy) {
-    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.
-    local_rotation[3] = 1;
-    rotation[3] = 1;
+    // Read from the proxy, so a re-seed is as authored; and the frame joint, if
+    // the garment hangs from it, is the identity in its own frame from the first
+    // step, the rest are evaluated every step.
+    instance.rest_position = Float32Array.from(proxy.rest_position);
+    instance.rest_rotation = Float32Array.from(proxy.rest_rotation);
 
-    const parent = instance.node_parent;
+    instance.rest_local_position = null;
+    instance.rest_local_rotation = null;
 
-    for (let node = 1; node < node_count; node++) {
-        const joint = node - 1;
+    instance.boundary_pose = new Float64Array(node_count * 7);
 
-        local_position[node * 3] = proxy.rest_position[joint * 3];
-        local_position[node * 3 + 1] = proxy.rest_position[joint * 3 + 1];
-        local_position[node * 3 + 2] = proxy.rest_position[joint * 3 + 2];
-
-        local_rotation[node * 4] = proxy.rest_rotation[joint * 4];
-        local_rotation[node * 4 + 1] = proxy.rest_rotation[joint * 4 + 1];
-        local_rotation[node * 4 + 2] = proxy.rest_rotation[joint * 4 + 2];
-        local_rotation[node * 4 + 3] = proxy.rest_rotation[joint * 4 + 3];
-
-        const p = parent[node];
+    for (let node = 0; node < node_count; node++) {
+        instance.boundary_pose[node * 7 + 6] = 1;
+    }
 
-        const pqx = rotation[p * 4];
-        const pqy = rotation[p * 4 + 1];
-        const pqz = rotation[p * 4 + 2];
-        const pqw = rotation[p * 4 + 3];
+    cloth_build_children(instance);
 
-        v3_quaternion_apply(
-            COMPOSE, 0,
-            local_position[node * 3], local_position[node * 3 + 1], local_position[node * 3 + 2],
-            pqx, pqy, pqz, pqw
-        );
+    instance.edge = Int32Array.from(proxy.edge);
+    instance.skip = Int32Array.from(proxy.skip);
+    instance.hinge = Int32Array.from(proxy.hinge);
+    instance.triangle = Int32Array.from(proxy.triangle);
 
-        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];
+    cloth_build_surface(instance);
 
-        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.dynamics_seen.copy(instance.cloth.dynamics);
 
-    instance.rest_local_position = local_position;
-    instance.rest_local_rotation = local_rotation;
+    cloth_build_rows(instance, dt);
 
-    instance.animated_position = position;
-    instance.animated_rotation = rotation;
+    instance.seeded = true;
 }
 
 /**
@@ -248,5 +188,3 @@ export function cloth_release_rig(instance, ecd) {
 
     instance.held_joints = null;
 }
-
-const COMPOSE = new Float64Array(3);

package/src/engine/physics/cloth/ecs/cloth_seed_subtree.d.ts

@@ -2,12 +2,27 @@
  * # 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.
+ * {@link Cloth} is on — that entity included, as node 0 — walked breadth-first
+ * through `TransformAttachmentSystem#findChildrenOf`, stopping at a nested
+ * `Cloth` or a {@link ClothExclude}. Stretch rows along the parent-child links
+ * and a bending model along each chain.
+ *
+ * **Node 0 is the cloth's frame and nothing holds it.** It is a particle like
+ * any other — links run from it, a {@link ClothPin} can hold it — but its
+ * entity is the frame, which cloth reads and never writes, so it has no output.
+ * A rope hung from its own top is a rope whose top entity pins particle 0:
+ *
+ * ```js
+ * rope_top.add(Cloth.from(ClothDynamics.ROPE));
+ * rope_top.add(ClothPin.from({ cloth: rope_top, particles: [0] }));
+ * ```
+ *
+ * **The particles are numbered by the walk**: breadth-first from node 0,
+ * siblings in the order `findChildrenOf` gives them, which is ascending entity
+ * id. A single chain is therefore numbered by depth whatever the ids; a pin on a
+ * branching subtree names a node of a walk that depends on how its siblings'
+ * ids were allocated, and `ClothSystem#particle_of` is how code that has the
+ * entity asks for the number.
  *
  * ## What "bend rows along each chain" turned out to mean
  *

package/src/engine/physics/cloth/ecs/cloth_seed_subtree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloth_seed_subtree.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_subtree.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;GASG;AACH,6CAPW,aAAa,2EAGb,MAAM,GAEJ,IAAI,CAwGhB;AA6GD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDAJW,aAAa,gCAEX,IAAI,CAkChB;8BAnU6B,oBAAoB"}
+{"version":3,"file":"cloth_seed_subtree.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_subtree.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH;;;;;;;;;GASG;AACH,6CAPW,aAAa,2EAGb,MAAM,GAEJ,IAAI,CAqHhB;AAiGD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDAJW,aAAa,gCAEX,IAAI,CAkChB;8BAnV6B,oBAAoB"}