@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -0,0 +1,199 @@
+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 { TransformAuthority } from "../../../../shade/renderer/scene/TransformAuthority.js";
+import { cloth_build_children, cloth_build_rows } 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
+ * identical either way; only seeding and write-back differ", and this file plus
+ * `cloth_write_back_rig.js` is the whole of the difference.
+ *
+ * ## Cloth takes authority, and that is a real claim
+ *
+ * §11.2 says the writable handle is "the joint's `Node3D.transform_local` — the
+ * same handle the animation systems write". **The animation systems do not
+ * write it.** `TransformAuthority` is explicit: a node a clip drives is
+ * `GPU`, and "the CPU allocates and seeds the row, then never writes to it
+ * again, so the node's own `transform_local` stops describing it and should not
+ * be read as if it did". Cloth writing `transform_local` on such a node would
+ * be writing to something nothing reads.
+ *
+ * So the seed **claims** `TransformAuthority.CPU` on every joint it drives. The
+ * consequence is stated rather than hidden: a joint cloth simulates stops being
+ * animatable by a clip, because two writers of one row is the race the authority
+ * enum exists to prevent. That is the right trade for a cape — the whole point
+ * of simulating it is that nobody keyframes it — and it is an authoring error
+ * for a garment whose joints are also keyed, which is why the seed says so.
+ *
+ * ## The animated pose is constant, exactly as it is for a rope
+ *
+ * §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".
+ *
+ * For a **rigged** garment it is not live either, and the reason is the
+ * authority claim 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.
+ *
+ * The live case is the **unrigged** path, where the animated targets are mesh
+ * vertices skinned to the character's skeleton by
+ * `mesh_apply_skeletal_vertex_skinning` and genuinely move under the animation.
+ * That path is not in M3.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Seed `instance` from a proxy and the joints of a skin.
+ *
+ * @param {ClothInstance} instance seeded in place
+ * @param {ClothProxy} proxy
+ * @param {Node3D[]} joints the skin's joints, in the order the proxy indexes
+ * @param {number} dt fixed step, seconds
+ * @returns {void}
+ */
+export function cloth_seed_rig(instance, proxy, joints, dt) {
+    assert.ok(proxy.isClothProxy === true, 'proxy must be a ClothProxy');
+
+    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;
+
+    instance.node_count = node_count;
+
+    const node_parent = new Int32Array(node_count);
+
+    node_parent[0] = -1;
+
+    for (let i = 0; i < joint_count; i++) {
+        node_parent[i + 1] = proxy.joint_parent[i] + 1;
+    }
+
+    instance.node_parent = node_parent;
+
+    const node_joint = new Array(node_count);
+
+    node_joint[0] = joints[proxy.anchor];
+
+    for (let i = 0; i < joint_count; i++) {
+        const node = joints[proxy.joint[i]];
+
+        assert.defined(node, `joint ${proxy.joint[i]} of the skin`);
+
+        node_joint[i + 1] = node;
+
+        // See the module docblock. A clip-driven joint reads as GPU here, and
+        // taking it is what makes the write-back visible at all.
+        node.transform_authority = TransformAuthority.CPU;
+    }
+
+    instance.node_joint = node_joint;
+
+    // The entity path's arrays have no meaning here and holding stale ones is
+    // how a write-back reaches into a previous seeding's entities.
+    instance.node_entity = null;
+    instance.node_transform = [];
+    instance.node_attachment = [];
+    instance.pruned_count = 0;
+    instance.pruned_entity = null;
+    instance.pruned_parent = null;
+    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;
+}
+
+/**
+ * Compose the proxy's baked bind pose into the anchor's frame.
+ *
+ * The proxy's parents come before its children, so one forward pass is the whole
+ * hierarchy — the same property `cloth_seed_subtree` gets from a breadth-first
+ * walk and relies on for the same reason.
+ *
+ * @param {ClothInstance} instance
+ * @param {ClothProxy} proxy
+ * @private
+ */
+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;
+
+    const parent = instance.node_parent;
+
+    for (let node = 1; node < node_count; node++) {
+        const joint = node - 1;
+
+        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];
+
+        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);

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

@@ -1,45 +1,3 @@
-/**
- * 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: ClothInstance, ecd: EntityComponentDataset, attachments: TransformAttachmentSystem, dt: number): void;
-/**
- * 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: ClothInstance, dt: number): void;
-/**
- * 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: ClothDynamics, after: ClothDynamics): boolean;
 /**
  * # Seeding a cloth from an entity subtree — §11.1
  *
@@ -87,28 +45,15 @@ export function cloth_dynamics_change_needs_reseed(before: ClothDynamics, after:
  * @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: number;
-/**
- * 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.
+ * Walk the subtree and build everything {@link ClothSystem} needs to step it.
  *
- * §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}
+ * @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 const CLOTH_SLACK_REACH: number;
+export function cloth_seed_subtree(instance: ClothInstance, ecd: EntityComponentDataset, attachments: TransformAttachmentSystem, dt: number): void;
 import { ClothInstance } from "./ClothInstance.js";
 //# sourceMappingURL=cloth_seed_subtree.d.ts.map

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":"AAyFA;;;;;;;;;GASG;AACH,6CAPW,aAAa,2EAGb,MAAM,GAEJ,IAAI,CAkGhB;AAgXD;;;;;;;;;;;;;;;;GAgBG;AACH,+CAJW,aAAa,MACb,MAAM,GACJ,IAAI,CAoChB;AAED;;;;;;;;;;;GAWG;AACH,iGAFa,OAAO,CAkBnB;AApnBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;GAIG;AACH,kCAFU,MAAM,CAEwB;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,gCAFU,MAAM,CAEmB;8BA1EL,oBAAoB"}
+{"version":3,"file":"cloth_seed_subtree.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_subtree.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;GASG;AACH,6CAPW,aAAa,2EAGb,MAAM,GAEJ,IAAI,CAkGhB;8BA5J6B,oBAAoB"}