@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -112,14 +112,11 @@ export class ClothInstance {
     node_transform = [];
 
     /**
-     * Live `Node3D` per node — the joint each node drives. **Rig path only**,
-     * and node 0 is the anchor joint, which is not simulated.
-     *
-     * A joint rather than an entity because a skinned model's joints are not
-     * entities and will not be (D47): they are `Node3D`s inside the entity's
-     * `SceneBundleInstance`, and the only writable handle is
-     * `Node3D.transform_local`.
-     * @type {Node3D[]}
+     * The joint entity each node drives. **Rig path only**, and node 0 is the
+     * anchor joint, which is not simulated. A skinned model is a prefab spawned
+     * as entities, so a joint is an entity carrying a `TransformAttachment`,
+     * and that offset is the writable handle; {@link node_attachment} holds it.
+     * @type {Int32Array|number[]}
      */
     node_joint = [];
 
@@ -127,12 +124,13 @@ export class ClothInstance {
      * The anchor joint's **world** pose, evaluated on the CPU each step from the
      * clips the entity is playing. **Rig path only.**
      *
-     * Evaluated rather than read: a joint of an animated skeleton is under
-     * `TransformAuthority.GPU`, so its own `transform_global` is not maintained
-     * on the CPU at all and reading it would place the garment wherever the node
-     * was last posed by hand. `pose_evaluate_world` is the sanctioned answer and
-     * the one a socket on the same skeleton gets, which is what keeps a cape on
-     * the shoulder a scabbard hangs from.
+     * Evaluated rather than read: a joint of an animated skeleton has granted
+     * its offset to the GPU (`GPUStateAuthority`), so the CPU's copy of its
+     * world pose is the rest pose composed under the placement, and reading it
+     * would hang the garment where the character stood before the clip moved
+     * it. `t64_evaluate_world` is the sanctioned answer and the one a socket on
+     * the same skeleton gets, which is what keeps a cape on the shoulder a
+     * scabbard hangs from.
      * @type {Transform64}
      */
     anchor_pose = new Transform64();

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

@@ -15,14 +15,13 @@
  *
  * ## Why there are two cases at all
  *
- * Because the engine has two hierarchies and that is a decision rather than an
- * accident. `shade_node_to_entity_composition` expands a loaded model into
- * entities and gives a `ShadedGeometry` to every node that draws — except a
- * skinned one, which contributes its transform and its name and no geometry,
- * because its vertices deform against a skeleton the renderer owns and the GPU
- * poses. Making those joints entities is a design this program does not do
- * (D47). A rope prop is entities all the way down; a character's cape is not,
- * and never will be.
+ * Because a garment's joints are a skin's, not a subtree's. A prefab spawns a
+ * loaded model as entities — every joint one, with its offset in a
+ * `TransformAttachment` — and a rope prop is a subtree under an anchor entity,
+ * walked. A character's cape is a set of joints named out of a skin that also
+ * has a torso and two arms in it, and what says which of those joints are the
+ * cape is the proxy. The joints it drives are entities either way; the
+ * difference is how they are found.
  *
  * ## A proxy object, not a path
  *

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

@@ -1 +1 @@
-{"version":3,"file":"ClothRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;IAmBI;;;;;OAKG;IACH;QAHyB,IAAI,GAAlB,MAAM;QACJ,QAAQ,CAkBpB;IAvCD;;;;OAIG;IACH,OAFU,aAAW,IAAI,CAEZ;IAEb;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;IA0BT;;;OAGG;IACH,cAHW,QAAQ,GACN,OAAO,CAenB;IAED;;OAEG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH;;MAIC;IAED;;OAEG;IACH,mBAFW,MAAM,QAIhB;IAED,mBAEC;IAGL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B"}
+{"version":3,"file":"ClothRig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IAmBI;;;;;OAKG;IACH;QAHyB,IAAI,GAAlB,MAAM;QACJ,QAAQ,CAkBpB;IAvCD;;;;OAIG;IACH,OAFU,aAAW,IAAI,CAEZ;IAEb;;;;;;;OAOG;IACH,MAFU,MAAM,CAEP;IA0BT;;;OAGG;IACH,cAHW,QAAQ,GACN,OAAO,CAenB;IAED;;OAEG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH;;MAIC;IAED;;OAEG;IACH,mBAFW,MAAM,QAIhB;IAED,mBAEC;IAGL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B"}

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

@@ -18,14 +18,13 @@ import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
  *
  * ## Why there are two cases at all
  *
- * Because the engine has two hierarchies and that is a decision rather than an
- * accident. `shade_node_to_entity_composition` expands a loaded model into
- * entities and gives a `ShadedGeometry` to every node that draws — except a
- * skinned one, which contributes its transform and its name and no geometry,
- * because its vertices deform against a skeleton the renderer owns and the GPU
- * poses. Making those joints entities is a design this program does not do
- * (D47). A rope prop is entities all the way down; a character's cape is not,
- * and never will be.
+ * Because a garment's joints are a skin's, not a subtree's. A prefab spawns a
+ * loaded model as entities — every joint one, with its offset in a
+ * `TransformAttachment` — and a rope prop is a subtree under an anchor entity,
+ * walked. A character's cape is a set of joints named out of a skin that also
+ * has a torso and two arms in it, and what says which of those joints are the
+ * cape is the proxy. The joints it drives are entities either way; the
+ * difference is how they are found.
  *
  * ## A proxy object, not a path
  *

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

@@ -90,8 +90,9 @@ export class ClothSystem extends System<any> {
     private __attachments;
     /**
      * Where a skinned model instance comes from. Anything that answers
-     * `instance_of(entity)` with a `SceneBundleInstance` will do, and
-     * {@link MeshSystem} is what does in a running engine.
+     * `instance_of(entity)` with a `PrefabInstance` — skins whose joints
+     * are entities — will do, and {@link MeshSystem} is what does in a
+     * running engine.
      *
      * Public and assignable because a garment's joints are a *rendering*
      * structure and `MeshSystem` needs a graphics engine, a scene and a loader
@@ -101,10 +102,10 @@ export class ClothSystem extends System<any> {
      * `null` means no rig can seed, which is the same additive shape the
      * collider index has: a scene without one gets M1's cloth rather than an
      * error.
-     * @type {{instance_of: function(number): (SceneBundleInstance|null)}|null}
+     * @type {{instance_of: function(number): (PrefabInstance|null)}|null}
      */
     models: {
-        instance_of: (arg0: number) => (SceneBundleInstance | null);
+        instance_of: (arg0: number) => (PrefabInstance | null);
     } | null;
     /**
      * The collider index's owner, or `null` when the manager has none — in

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

@@ -1 +1 @@
-{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;OAIG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;OAGG;IACH,oBAAwB;IAExB;;;OAGG;IACH,sBAAqB;IAErB;;;;;;;;;;;;;;OAcG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,sBAAoB,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAE5D;IAEd;;;;;;;OAOG;IACH,oBAAmB;IAEnB;;;OAGG;IACH,sBAAsB;IAEtB;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAahB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAgBhB;IAED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,IAAI,CAahB;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;;CAibJ;uBA5tBsB,wBAAwB;4BAWxC,uCAAuC;sBAYxB,YAAY;4CAxBU,uDAAuD;oCAI5F,0DAA0D;8BAqBnC,oBAAoB;6BAErB,mBAAmB;yBAIvB,eAAe;8BADV,oBAAoB"}
+{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AA4DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;OAIG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;OAGG;IACH,oBAAwB;IAExB;;;OAGG;IACH,sBAAqB;IAErB;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;;;;;;OAOG;IACH,oBAAmB;IAEnB;;;OAGG;IACH,sBAAsB;IAEtB;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAiBzB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAahB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAgBhB;IAED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,IAAI,CAahB;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;;CAibJ;uBA3tBsB,wBAAwB;4BAWxC,uCAAuC;sBAUxB,YAAY;4CAtBU,uDAAuD;oCAI5F,0DAA0D;8BAmBnC,oBAAoB;6BAErB,mBAAmB;yBAIvB,eAAe;8BADV,oBAAoB"}

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

@@ -21,9 +21,7 @@ import {
     collect_entity_playbacks
 } from "../../../graphics3/pose/collect_entity_playbacks.js";
 import { MeshSystem } from "../../../graphics3/MeshSystem.js";
-import {
-    pose_evaluate_world
-} from "../../../../shade/renderer/animation/pose/pose_evaluate_world.js";
+import { t64_evaluate_world } from "../../../ecs/transform/t64_evaluate_world.js";
 import { cloth_contact_find } from "../solver/cloth_contact_find.js";
 import { cloth_self_find } from "../solver/cloth_self_find.js";
 import { CLOTH_SELF_RADIUS_MAX_RATIO, CLOTH_SELF_RADIUS_MIN_RATIO } from "../solver/cloth_solver_constants.js";
@@ -165,8 +163,9 @@ export class ClothSystem extends System {
 
     /**
      * Where a skinned model instance comes from. Anything that answers
-     * `instance_of(entity)` with a `SceneBundleInstance` will do, and
-     * {@link MeshSystem} is what does in a running engine.
+     * `instance_of(entity)` with a `PrefabInstance` — skins whose joints
+     * are entities — will do, and {@link MeshSystem} is what does in a
+     * running engine.
      *
      * Public and assignable because a garment's joints are a *rendering*
      * structure and `MeshSystem` needs a graphics engine, a scene and a loader
@@ -176,7 +175,7 @@ export class ClothSystem extends System {
      * `null` means no rig can seed, which is the same additive shape the
      * collider index has: a scene without one gets M1's cloth rather than an
      * error.
-     * @type {{instance_of: function(number): (SceneBundleInstance|null)}|null}
+     * @type {{instance_of: function(number): (PrefabInstance|null)}|null}
      */
     models = null;
 
@@ -418,7 +417,7 @@ export class ClothSystem extends System {
 
         instance.rig = rig;
 
-        cloth_seed_rig(instance, rig.proxy, skin.joints, dt);
+        cloth_seed_rig(instance, rig.proxy, skin.joints, ecd, dt);
     }
 
     /**
@@ -657,7 +656,7 @@ export class ClothSystem extends System {
         if (instance.rig === null) {
             cloth_write_back(instance, ecd);
         } else {
-            cloth_write_back_rig(instance, transform);
+            cloth_write_back_rig(instance, ecd);
         }
     }
 
@@ -666,9 +665,9 @@ export class ClothSystem extends System {
      * entity is playing.
      *
      * **Computed, never read back**, for two reasons that are both the engine's
-     * own. A joint of an animated skeleton is under `TransformAuthority.GPU`,
-     * so nothing maintains its CPU-side `transform_global` and reading it gives
-     * whatever the node was last posed at by hand. And GPU readback is a frame
+     * own. A joint of an animated skeleton is the GPU's (`GPUStateAuthority`),
+     * so nothing maintains its CPU-side world and reading it gives its rest
+     * pose under whatever the CPU last composed. And GPU readback is a frame
      * late and asynchronous, so anything depending on it would depend on frame
      * pacing — which is why `query_entity_node_world_pose` exists and is
      * documented as the only sanctioned way to ask this question. A cape and a
@@ -686,7 +685,7 @@ export class ClothSystem extends System {
 
         collect_entity_playbacks(playbacks, this.entityManager, instance.entity);
 
-        pose_evaluate_world(instance.anchor_pose, instance.node_joint[0], playbacks);
+        t64_evaluate_world(instance.anchor_pose, this.entityManager.dataset, instance.node_joint[0], playbacks);
 
         playbacks.length = 0;
 

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

@@ -7,22 +7,22 @@
  * 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
+ * ## The joints are entities, and cloth takes them back from the GPU
  *
- * §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.
+ * 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 **claims** `TransformAuthority.CPU` on every joint it drives. The
+ * 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
- * 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.
+ * 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
  *
@@ -35,12 +35,8 @@
  * 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.
+ * 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
@@ -50,9 +46,9 @@
  *
  * @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}
+ * @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: ClothInstance, proxy: ClothProxy, joints: Node3D[], dt: number): void;
+export function cloth_seed_rig(instance: ClothInstance, proxy: ClothProxy, joints: number[], ecd: EntityComponentDataset, dt: number): void;
 //# sourceMappingURL=cloth_seed_rig.d.ts.map

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":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;;;;;;GAQG;AACH,mFAJW,QAAQ,MACR,MAAM,GACJ,IAAI,CA6DhB"}
+{"version":3,"file":"cloth_seed_rig.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/cloth_seed_rig.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;;;GAQG;AACH,mFAJW,MAAM,EAAE,mCAER,MAAM,QAyEhB"}