@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -1,199 +1,201 @@
-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);
+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_revoke } from "../../../ecs/gpu/gpu_authority_revoke.js";
+import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.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.
+ *
+ * ## The joints are entities, and cloth takes them back from the GPU
+ *
+ * A skinned model is a prefab spawned as entities, so a joint is an entity with
+ * a `TransformAttachment` — the offset from its parent joint — and a
+ * `GPUStateAuthority` saying who writes that offset's row. A joint a clip
+ * drives is the GPU's: the clip resolves the row on the GPU and the CPU never
+ * writes it, so the attachment's offset stops describing it. Cloth writing that
+ * offset on such a joint would be writing to something nothing reads.
+ *
+ * So the seed **revokes** the GPU's authority over 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 component 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, whose pose the
+ * system evaluates exactly (`t64_evaluate_world`).
+ *
+ * @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 {number[]} joints the skin's joints as entities, in the order the proxy indexes
+ * @param {EntityComponentDataset} ecd
+ * @param {number} dt
+ */
+export function cloth_seed_rig(instance, proxy, joints, ecd, 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 Int32Array(node_count);
+
+    node_joint[0] = joints[proxy.anchor];
+
+    const node_attachment = new Array(node_count);
+
+    node_attachment[0] = null;
+
+    for (let i = 0; i < joint_count; i++) {
+        const joint = joints[proxy.joint[i]];
+
+        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[i + 1] = joint;
+
+        const attachment = ecd.getComponent(joint, TransformAttachment);
+
+        assert.defined(attachment, `joint entity ${joint} carries no TransformAttachment to write`);
+
+        node_attachment[i + 1] = attachment;
+
+        // See the module docblock. A clip-driven joint's offset is the GPU's, and taking it back
+        // is what makes the write-back reach the row at all. An entity that never declared has
+        // nothing to take back.
+        gpu_authority_revoke(ecd, joint, GPUStateAuthorityFlags.TransformAttachment);
+    }
+
+    instance.node_joint = node_joint;
+    instance.node_attachment = node_attachment;
+
+    // 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.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;
+}
+
+/**
+ * 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;
+
+    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;
+}
+
+const COMPOSE = new Float64Array(3);

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":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;GASG;AACH,6CAPW,aAAa,2EAGb,MAAM,GAEJ,IAAI,CAkGhB;8BA5J6B,oBAAoB"}
+{"version":3,"file":"cloth_seed_subtree.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_subtree.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH;;;;;;;;;GASG;AACH,6CAPW,aAAa,2EAGb,MAAM,GAEJ,IAAI,CAwGhB;8BAlK6B,oBAAoB"}

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

@@ -1,6 +1,8 @@
 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_assert_cpu } from "../../../ecs/gpu/gpu_authority_assert_cpu.js";
 import { TransformAttachment } from "../../../ecs/transform-attachment/TransformAttachment.js";
 import {
     TRANSFORM64_ROTATION_OFFSET,
@@ -139,6 +141,8 @@ export function cloth_seed_subtree(instance, ecd, attachments, dt) {
     for (let i = 0; i < instance.pruned_count; i++) {
         const entity = instance.pruned_entity[i];
 
+        gpu_authority_assert_cpu(ecd, entity, GPUStateAuthorityFlags.Transform64);
+
         instance.pruned_transform[i] = ecd.getComponent(entity, Transform64);
         instance.pruned_attachment[i] = ecd.getComponent(entity, TransformAttachment);
     }
@@ -153,6 +157,10 @@ export function cloth_seed_subtree(instance, ecd, attachments, dt) {
 
         assert.defined(transform, `Transform64 of cloth node ${node} (entity ${entity})`);
 
+        // A subtree cloth is a CPU chain from its anchor down; a garment hanging off a GPU-driven
+        // joint is the rig path's, which evaluates the anchor exactly instead of reading it.
+        gpu_authority_assert_cpu(ecd, entity, GPUStateAuthorityFlags.Transform64);
+
         instance.node_transform[node] = transform;
         instance.node_attachment[node] = node === 0
             ? null

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

@@ -1,49 +1,33 @@
 /**
  * # Putting the answer back onto a skinned model's joints — §11.2
  *
- * The same reconstruction the entity path uses, written onto `Node3D`s instead
- * of onto entities. **Cloth moves joints; it does not produce vertices** — the
- * mapping from a simulated joint to a render vertex already exists in this
- * engine and it is the skin, so the existing skinning pass does the rest,
- * including bounds refresh and BLAS refit that a bespoke vertex-deformation
- * path would have to reimplement.
+ * The same reconstruction the entity path uses, written onto the joint entities' offsets.
+ * **Cloth moves joints; it does not produce vertices** — the mapping from a simulated joint to a
+ * render vertex already exists in this engine and it is the skin, so the existing skinning pass
+ * does the rest, including bounds refresh and BLAS refit that a bespoke vertex-deformation path
+ * would have to reimplement.
  *
- * ## `transform_local` is the output, and `transform_global` is written too
+ * ## The offset is the output
  *
- * `transform_local` is a joint's own truth and the handle §11.2 names. It is
- * also *passive*: a `Node3D` does not track its components, and nothing
- * downstream sees a change until `updateMatrices` runs — which recurses into
- * every descendant, so calling it on the anchor would recompose the whole
- * character every fixed step to move a cape.
+ * A joint's `TransformAttachment` offset is its own truth and the handle §11.2 names: it is what
+ * the joint's row holds, and the GPU composes the world from it under the anchor's animated
+ * row. Writing it is announced on the joint, which is what carries it to the row — the model
+ * marks the row on that announcement — and what lets the attachment system recompose the CPU's
+ * copy of the world below it. That copy is composed under the anchor as the CPU knows it, which
+ * for a GPU-driven anchor is its rest pose: what the simulation may read about a cape joint is
+ * its offset, or an exact evaluation, never that composed world.
  *
- * So this pass composes the cloth subtree's `transform_global` itself, which
- * costs nothing because the pose is already in hand, and bumps each joint's
- * version through `needsUpdate` so the renderer uploads the row. Nothing above
- * the anchor is touched and nothing below the garment is walked.
- *
- * `transform_global` is derived, so writing it is only ever a shortcut for the
- * recomposition it saves — and it is a *correct* shortcut only because this
- * pass has the anchor's world pose and the whole chain under it. Anything that
- * moves the anchor without telling cloth invalidates it, which is the same
- * contract every consumer of a derived transform already has.
- *
- * ## What is not here
- *
- * No announcement, and no pruned boundary. The entity path has both because its
- * subtree is an entity hierarchy with other things hanging off it; a proxy's
- * joint list is closed by construction, and a socket parented to a cape joint
- * follows it through the ordinary node hierarchy.
+ * Nothing above the anchor is touched: the anchor is the character's, animated by its clips,
+ * and this pass hangs a cape from it.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 /**
- * Write one cloth's solved pose onto the joints it drives.
+ * Write the reconstructed pose onto the rig's joints.
  *
  * @param {ClothInstance} instance
- * @param {Transform64} anchor the anchor joint's **world** pose, evaluated by
- *   the caller — see `ClothSystem` for why it is not read off the node
- * @returns {void}
+ * @param {EntityComponentDataset} ecd
  */
-export function cloth_write_back_rig(instance: ClothInstance, anchor: Transform64): void;
+export function cloth_write_back_rig(instance: ClothInstance, ecd: EntityComponentDataset): void;
 //# sourceMappingURL=cloth_write_back_rig.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cloth_write_back_rig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_write_back_rig.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;GAOG;AACH,oFAFa,IAAI,CA2DhB"}
+{"version":3,"file":"cloth_write_back_rig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_write_back_rig.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,iGAqBC"}