@woosh/meep-engine 3.40.0 → 3.41.0

package/src/engine/physics/cloth/MEASUREMENTS.md

@@ -3984,3 +3984,133 @@ colliding readings have a median of 0.90 and the twelve idle ones 0.95.
 
 **No library entry is re-sized.** Its bench cannot see a collider (§58), and a
 garment on a body is the colliding half of the tables above.
+
+## 61. A rig's joints were claimed with a bit the GPU never reads, by two parties at once
+
+Found reading code in the 2026-10-05 IK design review, and measured here before
+anything changed. Every reading below is a spec that registers a real clip
+through `GPUAnimationManager` on a `SoftwareGPUDevice` scene over the garment's
+own dataset (`cloth_rig.spec.js`), or runs the real apply pass under the WGSL
+emulator (`shader_animation_apply.spec.js`). The specs it replaced granted the
+bit by hand on joints no clip bound, so none of this was visible to them.
+
+```
+  what                                        before                                      after
+  clip unregistered while cloth held it,      bit 2 (GPU), and a CPU write of             bit 0; the row holds
+    then the garment removed                    (0.25, -0.5, 0.125) left the row at         (0.25, -0.5, 0.125)
+                                                0.0020000000949949026, for good
+  rig re-seeded while seeded, then removed    bit 0 with the clip still bound             bit 2
+  clip binding a joint cloth already holds    bit 2; the row stayed 0.0020000000949949026 bit 0; the row is
+                                                while cloth wrote 0.0011062223929911852     cloth's write
+  last clip leaving a held joint              offset (5, -0.10000382363796234, 0):        cloth's offset,
+                                                the clip's pose over cloth's 0.00173…       untouched
+  bindings of clips over a held cape          rows 3, 4, 5, 6, 7 (shoulder + cape)        3, then NULL ×4
+  apply pass over two held targets            8 accumulator words written                 none
+  cache / exact walk over a held level        cache off by 0.98 in a translation lane;    within 1e-12
+                                                the walk off in lane 12 (world x)
+```
+
+**Why the bit could not have worked.** The apply pass adds every bound clip into
+its target's accumulator slot whatever the clip's weight, the resolve writes the
+row, and both run in `tick`, after `build`'s flush. `GPUStateAuthority` gates
+only that flush. A cape joint whose clip still named its row was the clip's on
+screen, bit or no bit.
+
+**What changed.** A CPU writer *holds* a component (`gpu_authority_hold`):
+`GPUStateAuthority#held` records it, the bit clears, and `gpu_authority_grant`
+will not set a held bit. The animation manager hears the hold through an entity
+event on every joint it drives. It points that joint's bindings at
+`GPU_DATABASE_NULL`, whose type bits `write_object_property` ignores, and it
+skips the seed when the last clip leaves. When the hold ends it points them back
+and grants, if a clip is still bound. The exact evaluators read a held level as
+its offset (`t64_evaluate_local`). Cloth holds every joint it drives and never
+touches the bit.
+
+**Not measured:** a device run. The WGSL is unchanged; what changed is what the
+bindings name, and the emulator runs the real apply pass over it.
+
+### Found in review
+
+An adversarial pass over those six commits. Every candidate was measured before it
+was believed.
+
+- **A re-seeded rig leaked its holds** when it was taken away, or refused, before
+  the next seeding. `reseed` cleared `seeded`, the release asks `seeded`, and the
+  joints stayed held: their clips muted and nothing writing them. Before the hold
+  this was a bit that lied while the clip still won on the GPU; muting made it a
+  frozen joint. `reseed` now gives the holds back, and the seed asserts it
+  starts from none. Red first: bits `[0, 0, 0, 0]` against `[2, 2, 2, 2]`, the
+  bindings all NULL, after removing `Cloth`, after removing `ClothRig`, and after
+  a refused proxy.
+- **One line was pinned by nothing.** Of twelve mutants over the fixes, eleven
+  were killed. The survivor was the row mark a hold makes, which carries an offset
+  the holder wrote before it held. It is pinned now.
+- Measured and kept: the bind-time bookkeeping costs 129 ns a driven entity
+  (2.5 ms for 19,440, at registration only). The hold check costs the exact
+  evaluation 2.3% a level (64.0 to 65.8 µs over 70 levels, two clips of 210
+  channels, paired median).
+- Measured and dismissed: a muted rotation binding writes nothing to its slot,
+  rest rotation included (now in the emulator spec). A hold queues one word, the
+  binding's `instance`, and its end queues the row back. A renderer restart
+  reaches `GPUAnimationManager#destroy`, which removes every listener.
+
+### What a hold's end hands over
+
+Found reading code in the 2026-10-06 IK design review: two things the end of a
+hold did not hand to a clip still bound. Cloth's release is a plain unhold that
+leaves each joint's offset at cloth's last write-back, so both reached it. Real
+clips through the manager in `cloth_rig.spec.js`, and the apply and resolve
+passes under the WGSL emulator in `animation_pose_pipeline.spec.js`.
+
+The rest rows below read the rest each binding carries, which is what the resolve
+writes at weight zero (shown under the emulator, not on the cape).
+
+```
+  what                                        before                             after
+  rest a clip keying the cape carries         the rest from before the seed,     the offset cloth
+    once the garment goes                       [0, 0, 0, 1]                       left, z -0.00243
+  the same, the clip bound while cloth held   cloth's pose when it bound,        the offset cloth
+                                                z -0.000102                        left, z -0.00243
+  row y of a cape joint under a clip keying   -0.0999996, cloth's flush before   -0.1000130, cloth's
+    x alone, the garment removed between        its last five steps                last write-back
+    a step and the flush
+```
+
+**What changed.** The end of a hold, with a clip still bound, writes every
+binding's rest from the offset as the holder left it, with the unmute, and marks
+the row as a hand-over (`GPUSceneRows#mark_handover`): the flush writes it past
+the bit, once, and the resolve writes the axes the clip keys after it.
+
+**Decided, not changed:** a joint whose last clip left while it was held keeps
+the holder's offset when the hold ends, not the clip's last pose (2d67be636).
+The clip had been muted since the hold began, or since it bound, so its last pose
+is one the joint has not shown since; the seed's own rule, carry on from what is
+on screen, gives the holder's offset.
+
+**Open, not decided:** cloth's rig path leaves its last pose on the joints when it
+lets go, where the entity path puts the locals it captured back
+(`cloth_release_subtree`). The rig path never captured the joints' own offsets,
+but the instance holds the proxy's bind pose (`rest_local_*`), which it could put
+back. Measured: after the garment goes, a cape joint's offset rotation has z up
+to -0.00243 where that bind pose (identity, for the spec's skeleton) has 0, and a
+clip keying the cape carries it as its rest.
+
+**Found in review** of these two fixes:
+
+- **Two lines were pinned by nothing.** Of ten mutants over the fixes, eight were
+  killed. The survivors: the `MARK_LOCAL` inside the hand-over mark, since both
+  gap-2 specs had the holder announce its last write and so mark the row
+  themselves; and the rest read off the wrong component, since the emulator
+  spec's left rotation was `[0.5, 0.5, 0.5, 0.5]` and the cape turns about z
+  alone. Both are pinned now.
+- **The first bind had the same hole.** A clip that first binds a joint grants
+  the bit at once, so an offset announced earlier in that frame never reached the
+  row: `[0, 0, 0, 1]` against the `[0.1, 0.3, 0.5, 0.806]` announced. Binding
+  marks the hand-over too now. No engine path was found that triggers it today: the
+  drivers re-register a whole clip set in one call, whose outgoing seed is such an
+  announcement, but they set time from the CPU, so that seed equals what the GPU
+  last resolved.
+- Measured and dismissed: the binding writer over `instance` and `rest_rotation`
+  is two disjoint ranges of one row, which the partial upload shader spec already
+  lands under the emulator; and the worker path writes nothing after a release,
+  because a join for a cloth unlinked or reseeded since its dispatch is dropped.

package/src/engine/physics/cloth/PLAN.md

@@ -368,7 +368,8 @@ said cloth reuses `PhysicsSystem`'s producer/`__interp_restore` contract; M5 mea
 that contract is entity-keyed and a rigged garment's joints are not entities — and §13.1 and §18 carry
 what the cloth-shaped version would be and what it would cost. What keeps a cloth-driven bone from
 fighting an animation-driven one is not interpolation but `TransformAuthority`, which `cloth_seed_rig`
-claims (§11.2, `MEASUREMENTS.md` §25).
+claims (§11.2, `MEASUREMENTS.md` §25) — as a hold since §61, because the bit alone never stopped a
+clip on the GPU.
 
 ### 4.1 Ordering, and why the answer is not to be ordered
 
@@ -1430,6 +1431,20 @@ with no component left anywhere naming which joints those were. The seed now rec
 joints its revoke *changed*, and `cloth_release_rig` hands those back when the `Cloth` is removed or
 the `ClothRig` is taken away; a joint that was already the CPU's before cloth arrived stays the CPU's.
 
+**2026-10-06: the claim never stopped a clip, and the loan was handed back to whoever asked last.**
+No GPU pass reads `GPUStateAuthority`. A bound clip's bindings write a joint's row through the pose
+accumulator every frame, after the CPU's flush, whatever the bit says, so clearing the bit only let
+cloth's flush and the clip race for one row, and the clip won. And cloth and `GPUAnimationManager`
+each flipped the same bit without the other: a clip that left during the loan was answered by
+cloth's re-grant with a joint nothing wrote again, and a clip that arrived during it took the bit
+from under cloth's write-back. The rule now is a **hold**. `GPUStateAuthority#held` records that a CPU
+writer has the offset, the bit stays clear while it does, and the animation manager — the only
+writer of the bit — mutes every binding that names a held joint and leaves its offset alone when the
+last clip goes. Ending the hold grants nothing; a clip still bound takes the joint back. So **"a joint
+cloth simulates stops being animatable by a clip" is true now, and a garment whose joints are also
+keyed is not an authoring error**: exporters often bake every bone, and the cape simulates anyway.
+`MEASUREMENTS.md` §61.
+
 **The anchor's world pose is computed, never read back.** A joint of an animated skeleton has no
 CPU-side `transform_global` — nothing maintains it — so the rig path evaluates the anchor with
 `pose_evaluate_world` over the clips the entity is playing, which is the engine's own sanctioned

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

@@ -12,12 +12,11 @@
  * ## It has no `fixedUpdate`, and that is §4.1 applied a second time
  *
  * The index has to be refreshed from the world's transforms **before** any
- * cloth reads it, and the engine's two ordering mechanisms cannot express that:
- * `updateExecutionOrder` scores a system as a sum over the components it
- * references and sorts descending, so a system can only be moved *earlier* by
- * touching more, and `ClothSystem` — which reads and writes `Transform64` and
- * `TransformAttachment` — outscores a system that only reads. Registration
- * order does not break a non-tie.
+ * cloth reads it, and the derived order says the opposite: `updateExecutionOrder`
+ * runs a writer of a component before its readers, `ClothSystem` writes
+ * `Transform64`, and the index is not a component, so a system that steps only
+ * to read transforms into it would run after cloth. Registration order breaks
+ * only the ties that leaves.
  *
  * §4.1's conclusion applies unchanged: the answer is not a third mechanism, it
  * is not needing one. So this system does not step at all. {@link refresh} is

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

@@ -1 +1 @@
-{"version":3,"file":"ClothColliderSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothColliderSystem.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;;IAEI,8EAAsD;IAEtD,wKAIE;IAEF;;OAEG;IACH,OAFU,kBAAkB,CAEK;IAEjC;;;;;;OAMG;IACH,kBAAsB;IAEtB;;;;;;;;OAQG;IACH,iBAAc;IAEd;;;;;OAKG;IACH,qBALW,aAAa,YACb,QAAQ,aACR,WAAW,UACX,MAAM,QAoChB;IAED;;;;;OAKG;IACH,uBALW,aAAa,YACb,QAAQ,aACR,WAAW,UACX,MAAM,QAqBhB;IAED;;;;;;OAMG;IACH,WAFa,IAAI,CAkChB;IAED;;;;;;;;OAQG;IACH,uBAHW,MAAM,GACJ,IAAI,CAyBhB;IAED;;;;;;OAMG;IACH,gBAWC;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ;uBAtQsB,wBAAwB;4BAMxC,uCAAuC;yBACrB,uBAAuB;8BAElB,oBAAoB;4CAVN,uDAAuD;mCAShE,mCAAmC"}
+{"version":3,"file":"ClothColliderSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothColliderSystem.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH;;IAEI,8EAAsD;IAEtD,wKAIE;IAEF;;OAEG;IACH,OAFU,kBAAkB,CAEK;IAEjC;;;;;;OAMG;IACH,kBAAsB;IAEtB;;;;;;;;OAQG;IACH,iBAAc;IAEd;;;;;OAKG;IACH,qBALW,aAAa,YACb,QAAQ,aACR,WAAW,UACX,MAAM,QAoChB;IAED;;;;;OAKG;IACH,uBALW,aAAa,YACb,QAAQ,aACR,WAAW,UACX,MAAM,QAqBhB;IAED;;;;;;OAMG;IACH,WAFa,IAAI,CAkChB;IAED;;;;;;;;OAQG;IACH,uBAHW,MAAM,GACJ,IAAI,CAyBhB;IAED;;;;;;OAMG;IACH,gBAWC;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ;uBArQsB,wBAAwB;4BAMxC,uCAAuC;yBACrB,uBAAuB;8BAElB,oBAAoB;4CAVN,uDAAuD;mCAShE,mCAAmC"}

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

@@ -26,12 +26,11 @@ import { ClothColliderFlags } from "./ClothColliderFlags.js";
  * ## It has no `fixedUpdate`, and that is §4.1 applied a second time
  *
  * The index has to be refreshed from the world's transforms **before** any
- * cloth reads it, and the engine's two ordering mechanisms cannot express that:
- * `updateExecutionOrder` scores a system as a sum over the components it
- * references and sorts descending, so a system can only be moved *earlier* by
- * touching more, and `ClothSystem` — which reads and writes `Transform64` and
- * `TransformAttachment` — outscores a system that only reads. Registration
- * order does not break a non-tie.
+ * cloth reads it, and the derived order says the opposite: `updateExecutionOrder`
+ * runs a writer of a component before its readers, `ClothSystem` writes
+ * `Transform64`, and the index is not a component, so a system that steps only
+ * to read transforms into it would run after cloth. Registration order breaks
+ * only the ties that leaves.
  *
  * §4.1's conclusion applies unchanged: the answer is not a third mechanism, it
  * is not needing one. So this system does not step at all. {@link refresh} is

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

@@ -478,15 +478,12 @@ export class ClothInstance {
      */
     gather_reach: number;
     /**
-     * The joint entities this cloth's rig seeding took `TransformAttachment`
-     * authority from, so that removing the cloth can give it back. `null` on
-     * the entity path and before the first rig seeding.
-     *
-     * Only the ones the revoke actually changed: a joint that was already the
-     * CPU's is not one cloth has anything to hand back.
+     * The joint entities this cloth's rig seeding holds `TransformAttachment`
+     * on (`gpu_authority_hold`), so that removing the cloth can end the hold.
+     * `null` on the entity path and before the first rig seeding.
      * @type {number[]|null}
      */
-    revoked_joints: number[] | null;
+    held_joints: number[] | null;
     /**
      * Where every particle was when the current sleep window opened, or `null`
      * before the first step — §7 P5's sleep test measures displacement from

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

@@ -1 +1 @@
-{"version":3,"file":"ClothInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothInstance.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"ClothInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothInstance.js"],"names":[],"mappings":"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"}

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

@@ -538,15 +538,12 @@ export class ClothInstance {
     gather_reach = 0;
 
     /**
-     * The joint entities this cloth's rig seeding took `TransformAttachment`
-     * authority from, so that removing the cloth can give it back. `null` on
-     * the entity path and before the first rig seeding.
-     *
-     * Only the ones the revoke actually changed: a joint that was already the
-     * CPU's is not one cloth has anything to hand back.
+     * The joint entities this cloth's rig seeding holds `TransformAttachment`
+     * on (`gpu_authority_hold`), so that removing the cloth can end the hold.
+     * `null` on the entity path and before the first rig seeding.
      * @type {number[]|null}
      */
-    revoked_joints = null;
+    held_joints = null;
 
     /**
      * Where every particle was when the current sleep window opened, or `null`

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

@@ -37,9 +37,10 @@
  * recomposed.
  *
  * The declaration is the honest one — cloth reads `Cloth` and `ClothExclude`,
- * and reads and writes both `Transform64` and `TransformAttachment`. That puts
- * it before `TransformAttachmentSystem`, which is right: cloth writes the local
- * transforms and the attachment system is their reader.
+ * and reads and writes both `Transform64` and `TransformAttachment`. It runs
+ * before `TransformAttachmentSystem`, which is right — cloth writes the local
+ * transforms and the attachment system is their reader — and the passes are what
+ * guarantee it: cloth steps in `fixedUpdate`, the attachment system in `update`.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;;;;;;OAYG;IACH,iBAAyD;IAEzD;;;;;;OAMG;IACH,qBAAkB;IAUlB;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAkBD;;OAEG;IACH,qBAEC;IAdD;;;;OAIG;IACH,gBAEC;IASD;;;;OAIG;IACH,iCAEC;IAUD;;OAEG;IACH;4BAToC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;OAWjE;IAbD;;;OAGG;IACH;4BAFoC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;MAIjE;IASD;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAIzB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;CA2EJ;uBAxSsB,wBAAwB;4BAInB,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;8BAInC,oBAAoB;6BACrB,mBAAmB;yBACvB,eAAe;2BACb,iBAAiB"}
+{"version":3,"file":"ClothSystem.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothSystem.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;;IAEI,oDAAoC;IAEpC,iUAOE;IAEF;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;;;;;;OAYG;IACH,iBAAyD;IAEzD;;;;;;OAMG;IACH,qBAAkB;IAUlB;;OAEG;IACH,iCAEC;IAbD;;;OAGG;IACH,4BAEC;IAkBD;;OAEG;IACH,qBAEC;IAdD;;;;OAIG;IACH,gBAEC;IASD;;;;OAIG;IACH,iCAEC;IAUD;;OAEG;IACH;4BAToC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;OAWjE;IAbD;;;OAGG;IACH;4BAFoC,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC;MAIjE;IASD;;;OAGG;IACH,uCAFa,QAAQ,IAAI,CAAC,CAIzB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,wDAFa,IAAI,CAIhB;IAED;;;;OAIG;IACH,YAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,cAJW,KAAK,aACL,WAAW,UACX,MAAM,QAIhB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,IAAI,CAIhB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,gBAAc,SAAS,CAInC;CA2EJ;uBAzSsB,wBAAwB;4BAInB,uCAAuC;sBAE7C,YAAY;4CAPU,uDAAuD;oCAI5F,0DAA0D;8BAInC,oBAAoB;6BACrB,mBAAmB;yBACvB,eAAe;2BACb,iBAAiB"}

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

@@ -51,9 +51,10 @@ import { ClothWorld } from "./ClothWorld.js";
  * recomposed.
  *
  * The declaration is the honest one — cloth reads `Cloth` and `ClothExclude`,
- * and reads and writes both `Transform64` and `TransformAttachment`. That puts
- * it before `TransformAttachmentSystem`, which is right: cloth writes the local
- * transforms and the attachment system is their reader.
+ * and reads and writes both `Transform64` and `TransformAttachment`. It runs
+ * before `TransformAttachmentSystem`, which is right — cloth writes the local
+ * transforms and the attachment system is their reader — and the passes are what
+ * guarantee it: cloth steps in `fixedUpdate`, the attachment system in `update`.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

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

@@ -1 +1 @@
-{"version":3,"file":"ClothWorld.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorld.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH;IAEI;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;;;;;;;;;OAYG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;OAEG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;OAEG;IACH,aAFU,yBAAyB,GAAC,IAAI,CAErB;IAEnB;;;;;;OAMG;IACH,WAFU,mBAAmB,GAAC,IAAI,CAEjB;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,oBAAkB,IAAI,CAEpB;IAEZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,oBAAwB;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAKE;IAEF;;;;;OAKG;IACH,2CAiBC;IAED;;;;;OAKG;IACH,YALW,KAAK,kCAEL,MAAM,GACJ,aAAa,CAczB;IAED;;;;;;;;OAQG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CA0BnC;IAyED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAanC;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;IAED;;;;;OAKG;IACH,uCAFW,MAAM,QAgBhB;IAED;;;;;;;;;OASG;IACH,wBANW,aAAa,mCAEb,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;OAOG;IACH,iBAJW,aAAa,gCAEX,IAAI,CA4ChB;IAwFD;;;;;;;;;;;OAWG;IACH,kBAPW,aAAa,MACb,MAAM,UACN,YAAY,UACZ,MAAM,GACJ,OAAO,CA0PnB;;CA8EJ;8BA3/B6B,oBAAoB;0CAjB3C,gEAAgE;oCAcnC,0BAA0B;sBA4BxC,YAAY"}
+{"version":3,"file":"ClothWorld.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorld.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH;IAEI;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;;;;;;;;;OAYG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;OAEG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;OAEG;IACH,aAFU,yBAAyB,GAAC,IAAI,CAErB;IAEnB;;;;;;OAMG;IACH,WAFU,mBAAmB,GAAC,IAAI,CAEjB;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,oBAAkB,IAAI,CAEpB;IAEZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,oBAAwB;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAKE;IAEF;;;;;OAKG;IACH,2CAiBC;IAED;;;;;OAKG;IACH,YALW,KAAK,kCAEL,MAAM,GACJ,aAAa,CAczB;IAED;;;;;;;;OAQG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CA0BnC;IAyED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAuBnC;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;IAED;;;;;OAKG;IACH,uCAFW,MAAM,QAgBhB;IAED;;;;;;;;;OASG;IACH,wBANW,aAAa,mCAEb,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;OAOG;IACH,iBAJW,aAAa,gCAEX,IAAI,CA4ChB;IAwFD;;;;;;;;;;;OAWG;IACH,kBAPW,aAAa,MACb,MAAM,UACN,YAAY,UACZ,MAAM,GACJ,OAAO,CA0PnB;;CA8EJ;8BArgC6B,oBAAoB;0CAjB3C,gEAAgE;oCAcnC,0BAA0B;sBA4BxC,YAAY"}

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

@@ -478,6 +478,16 @@ export class ClothWorld {
             return undefined;
         }
 
+        // A rig's holds on its joints go with the binding being thrown away. Kept across the gap
+        // they would outlive `seeded`, which is all `#release` asks: a garment removed, or a rig
+        // refused, before the next seeding took them over would leave its joints held, the clips
+        // that key them muted, and nothing writing them.
+        const ecd = this.entityManager === null ? null : this.entityManager.dataset;
+
+        if (ecd !== null && ecd !== undefined) {
+            cloth_release_rig(instance, ecd);
+        }
+
         instance.seeded = false;
         instance.anchor_valid = false;
 

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

@@ -7,22 +7,23 @@
  * 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
+ * ## The joints are entities, and cloth holds their offsets
  *
  * 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.
+ * `GPUStateAuthority` saying who writes that offset's row. A clip bound to a
+ * joint writes the row on the GPU every frame, through the pose accumulator,
+ * 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 **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.
+ * 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.
  *
  * ## The animated pose is constant, exactly as it is for a rope
  *
@@ -32,7 +33,7 @@
  * 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,
+ * 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
@@ -52,18 +53,17 @@
  */
 export function cloth_seed_rig(instance: ClothInstance, proxy: ClothProxy, joints: number[], ecd: EntityComponentDataset, dt: number): void;
 /**
- * Give back every joint's `TransformAttachment` authority that this cloth's
- * seeding took from the GPU.
+ * End the hold this cloth's seeding took on every joint's `TransformAttachment`.
  *
- * The seed revokes so that the write-back reaches the row at all, and the
- * consequence the module docblock states — "a joint cloth simulates stops being
- * animatable by a clip" — is only the right trade while the cloth is *there*.
- * A garment removed and nothing re-granting leaves its joints owned by a CPU
- * that is no longer writing them: neither animated nor simulated, and stuck in
- * the pose the solver stopped in.
- *
- * Only the joints the revoke actually changed are given back, so a joint that
- * was already the CPU's before cloth arrived stays the CPU's.
+ * Ending a hold grants nothing, and that is the point: who writes a joint once
+ * the garment is gone is not cloth's to say. A clip still bound to the joint
+ * takes it back (the animation manager hears the hold end); a joint no clip
+ * binds stays the CPU's, holding the offset cloth last wrote. Either way the
+ * joint starts from that offset: a clip taking it back rests there, and finds
+ * it in the row on every axis it does not key. Granting it here
+ * instead — as this did — hands a joint whose clip left during the hold to a
+ * GPU that has nothing to write into it: the flush skips the row, no clip pass
+ * writes it, and the joint is frozen for good.
  *
  * @param {ClothInstance} instance
  * @param {EntityComponentDataset} ecd

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;;;;;GAQG;AACH,mFAJW,MAAM,EAAE,mCAER,MAAM,QAkFhB;AAoED;;;;;;;;;;;;;;;;;GAiBG;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":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH;;;;;;;;GAQG;AACH,mFAJW,MAAM,EAAE,mCAER,MAAM,QAqFhB;AAoED;;;;;;;;;;;;;;;;GAgBG;AACH,yFAFa,IAAI,CAoBhB"}

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

@@ -2,8 +2,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_grant } from "../../../ecs/gpu/gpu_authority_grant.js";
-import { gpu_authority_revoke } from "../../../ecs/gpu/gpu_authority_revoke.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";
 
@@ -16,22 +16,23 @@ import { cloth_build_children, cloth_build_rows } from "./cloth_build_rows.js";
  * 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
+ * ## The joints are entities, and cloth holds their offsets
  *
  * 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.
+ * `GPUStateAuthority` saying who writes that offset's row. A clip bound to a
+ * joint writes the row on the GPU every frame, through the pose accumulator,
+ * 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 **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.
+ * 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.
  *
  * ## The animated pose is constant, exactly as it is for a rope
  *
@@ -41,7 +42,7 @@ import { cloth_build_children, cloth_build_rows } from "./cloth_build_rows.js";
  * 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,
+ * 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
@@ -63,6 +64,10 @@ import { cloth_build_children, cloth_build_rows } from "./cloth_build_rows.js";
 export function cloth_seed_rig(instance, proxy, joints, ecd, dt) {
     assert.ok(proxy.isClothProxy === true, 'proxy must be a ClothProxy');
 
+    // Seeding takes the joints from nothing: `ClothWorld#reseed`, the only way back to an unseeded
+    // 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
@@ -89,10 +94,10 @@ export function cloth_seed_rig(instance, proxy, joints, ecd, dt) {
 
     node_attachment[0] = null;
 
-    // What this seeding took, so that giving it back is possible. A revoke that
-    // nothing can undo is half a transaction, and the half that is missing is
-    // the one that runs when the garment is removed.
-    const revoked = [];
+    // 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]];
@@ -108,15 +113,14 @@ export function cloth_seed_rig(instance, proxy, joints, ecd, dt) {
 
         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.
-        if (gpu_authority_revoke(ecd, joint, GPUStateAuthorityFlags.TransformAttachment)) {
-            revoked.push(joint);
-        }
+        // 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.
+        gpu_authority_hold(ecd, joint, GPUStateAuthorityFlags.TransformAttachment);
+
+        held.push(joint);
     }
 
-    instance.revoked_joints = revoked;
+    instance.held_joints = held;
 
     instance.node_joint = node_joint;
     instance.node_attachment = node_attachment;
@@ -209,41 +213,40 @@ function read_bind_pose(instance, proxy) {
 }
 
 /**
- * Give back every joint's `TransformAttachment` authority that this cloth's
- * seeding took from the GPU.
- *
- * The seed revokes so that the write-back reaches the row at all, and the
- * consequence the module docblock states — "a joint cloth simulates stops being
- * animatable by a clip" — is only the right trade while the cloth is *there*.
- * A garment removed and nothing re-granting leaves its joints owned by a CPU
- * that is no longer writing them: neither animated nor simulated, and stuck in
- * the pose the solver stopped in.
+ * End the hold this cloth's seeding took on every joint's `TransformAttachment`.
  *
- * Only the joints the revoke actually changed are given back, so a joint that
- * was already the CPU's before cloth arrived stays the CPU's.
+ * Ending a hold grants nothing, and that is the point: who writes a joint once
+ * the garment is gone is not cloth's to say. A clip still bound to the joint
+ * takes it back (the animation manager hears the hold end); a joint no clip
+ * binds stays the CPU's, holding the offset cloth last wrote. Either way the
+ * joint starts from that offset: a clip taking it back rests there, and finds
+ * it in the row on every axis it does not key. Granting it here
+ * instead — as this did — hands a joint whose clip left during the hold to a
+ * GPU that has nothing to write into it: the flush skips the row, no clip pass
+ * writes it, and the joint is frozen for good.
  *
  * @param {ClothInstance} instance
  * @param {EntityComponentDataset} ecd
  * @returns {void}
  */
 export function cloth_release_rig(instance, ecd) {
-    const revoked = instance.revoked_joints;
+    const held = instance.held_joints;
 
-    if (revoked === null) {
+    if (held === null) {
         return;
     }
 
-    for (let i = 0; i < revoked.length; i++) {
-        const joint = revoked[i];
+    for (let i = 0; i < held.length; i++) {
+        const joint = held[i];
 
         if (!ecd.entityExists(joint)) {
             continue;
         }
 
-        gpu_authority_grant(ecd, joint, GPUStateAuthorityFlags.TransformAttachment);
+        gpu_authority_unhold(ecd, joint, GPUStateAuthorityFlags.TransformAttachment);
     }
 
-    instance.revoked_joints = null;
+    instance.held_joints = null;
 }
 
 const COMPOSE = new Float64Array(3);

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

@@ -21,7 +21,7 @@
  * worst a shape one fixed step stale.
  *
  * That is also the shape of the engine's own precedent:
- * `InverseKinematicsSystem` reads world transforms the hierarchy has composed
+ * `IKGoalSystem` evaluates the world poses the hierarchy composes
  * and writes local ones back, and §11.2's rig path writes
  * `Node3D.transform_local` for the same reason — a local transform is what a
  * joint angle *is*.

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

@@ -33,7 +33,7 @@ import { cloth_reconstruct_pose } from "./cloth_reconstruct_pose.js";
  * worst a shape one fixed step stale.
  *
  * That is also the shape of the engine's own precedent:
- * `InverseKinematicsSystem` reads world transforms the hierarchy has composed
+ * `IKGoalSystem` evaluates the world poses the hierarchy composes
  * and writes local ones back, and §11.2's rig path writes
  * `Node3D.transform_local` for the same reason — a local transform is what a
  * joint angle *is*.