@woosh/meep-engine 3.39.0 → 3.41.0

package/src/engine/EngineHarness.js

@@ -26,6 +26,10 @@ import TopDownCameraController from "./graphics/ecs/camera/topdown/TopDownCamera
 import TopDownCameraControllerSystem from "./graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js";
 import { Light } from "./graphics/ecs/light/Light.js";
 import Water from "./graphics/ecs/water/Water.js";
+import { make_plane_geometry } from "../shade/renderer/geometry/primitives/make_plane_geometry.js";
+import { meshlet_geometry_build_from_geometry } from "../shade/renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { MeshoptClusterizer } from "../shade/renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { StandardAttributes } from "../shade/renderer/geometry/StandardAttributes.js";
 import { MouseEvents } from "./input/devices/events/MouseEvents.js";
 import KeyboardCameraController from "./input/ecs/controllers/KeyboardCameraController.js";
 import InputControllerSystem from "./input/ecs/systems/InputControllerSystem.js";
@@ -565,14 +569,23 @@ export class EngineHarness {
         if (enableWater) {
 
             if (em.getSystem(WaterSystem) === null) {
-                em.addSystem(new WaterSystem(engine.graphics));
+                em.addSystem(new WaterSystem(engine.graphics, EngineHarness.shadeScene(engine)));
             }
 
             const water = new Water();
 
-            water.level.set(waterLevel);
-
-            eb.add(water);
+            await MeshoptClusterizer.ready;
+            const plane = make_plane_geometry(size.x * 2, size.y * 2);
+            const positions = plane.getAttribute(StandardAttributes.Position).data;
+            const normals = plane.getAttribute(StandardAttributes.Normal).data;
+            for (let i = 0; i < positions.length; i += 3) {
+                positions[i + 2] = -positions[i + 1]; positions[i + 1] = 0;
+                normals[i] = 0; normals[i + 1] = 1; normals[i + 2] = 0;
+            }
+            const geometry = meshlet_geometry_build_from_geometry(plane);
+            const placement = new Transform64();
+            placement.setTranslation(size.x, waterLevel, size.y);
+            new Entity().add(water).add(geometry).add(placement).build(engine.entityManager.dataset);
         }
 
         eb.build(engine.entityManager.dataset);

package/src/engine/animation/curve/AnimationCurve.d.ts

@@ -119,12 +119,15 @@ export class AnimationCurve implements Iterable<Keyframe> {
      * Returns index of a key that is just before or at the time specified.
      * Useful for insertion and evaluation logic.
      * Note: if time is past the end of last key - index of the last key will be returned instead
+     * With assertions stripped, a NaN time is at or after no key, so like a time before the first key it returns 0.
      * @param {number} time
      * @returns {number} index of the key
      */
     getKeyIndexLow(time: number): number;
     /**
      * Evaluate interpolated value across the curve at a given time.
+     * On a curve of two or more keys, a NaN time fails an assertion during development; with assertions stripped it
+     * evaluates to NaN, or to the first key's value if the first two keys share a time.
      * @param {number} time time in seconds
      * @return {number} value at the specified time
      */

package/src/engine/animation/curve/AnimationCurve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationCurve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/AnimationCurve.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,gDANwB,QAAQ;IAuZ5B;;;;OAIG;IACH,kBAHW,QAAQ,EAAE,GACR,cAAc,CAQ1B;IAED;;;;;;;;;OASG;IACH,6BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAUzB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,YACN,MAAM,UACN,MAAM,GACL,cAAc,CAOzB;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAezB;IApdD;;;;;OAKG;IACH,eAFU,QAAQ,EAAE,CAEV;IAEV;;;;;OAKG;IACH,SAHW,QAAQ,GACN,MAAM,CAuClB;IAED;;;OAGG;IACH,cAFW,QAAQ,EAAE,QAUpB;IAED;;;;OAIG;IACH,YAHW,QAAQ,GACN,OAAO,CAYnB;IAED;;OAEG;IACH,cAEC;IAGD;;;OAGG;IACH,WAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,uBAUC;IAED;;;;OAIG;IACH,uBAcC;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAmDlB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACL,MAAM,CAoCjB;IAED;;;;OAIG;IACH,qBAFW,MAAM,QAqChB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;OAEG;IACH,yBAQC;IAGD;;;OAGG;IACH,YAFW,cAAc,QAIxB;IAED;;;OAGG;IACH,SAFY,cAAc,CAQzB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACb,OAAO,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED;;aAkBC;IAoFL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;IAGzC;;;OAGG;IACH,mBAA+B;IA9F3B,wDAQC;CAuEJ;yBAjfwB,eAAe"}
+{"version":3,"file":"AnimationCurve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/AnimationCurve.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,gDANwB,QAAQ;IA4Z5B;;;;OAIG;IACH,kBAHW,QAAQ,EAAE,GACR,cAAc,CAQ1B;IAED;;;;;;;;;OASG;IACH,6BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAUzB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,YACN,MAAM,UACN,MAAM,GACL,cAAc,CAOzB;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAezB;IAzdD;;;;;OAKG;IACH,eAFU,QAAQ,EAAE,CAEV;IAEV;;;;;OAKG;IACH,SAHW,QAAQ,GACN,MAAM,CAuClB;IAED;;;OAGG;IACH,cAFW,QAAQ,EAAE,QAUpB;IAED;;;;OAIG;IACH,YAHW,QAAQ,GACN,OAAO,CAYnB;IAED;;OAEG;IACH,cAEC;IAGD;;;OAGG;IACH,WAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,uBAUC;IAED;;;;OAIG;IACH,uBAcC;IAED;;;;;;;OAOG;IACH,qBAHW,MAAM,GACJ,MAAM,CAqDlB;IAED;;;;;;OAMG;IACH,eAHW,MAAM,GACL,MAAM,CAoCjB;IAED;;;;OAIG;IACH,qBAFW,MAAM,QAqChB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;OAEG;IACH,yBAQC;IAGD;;;OAGG;IACH,YAFW,cAAc,QAIxB;IAED;;;OAGG;IACH,SAFY,cAAc,CAQzB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACb,OAAO,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED;;aAkBC;IAoFL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;IAGzC;;;OAGG;IACH,mBAA+B;IA9F3B,wDAQC;CAuEJ;yBAtfwB,eAAe"}

package/src/engine/animation/curve/AnimationCurve.js

@@ -200,6 +200,7 @@ export class AnimationCurve {
      * Returns index of a key that is just before or at the time specified.
      * Useful for insertion and evaluation logic.
      * Note: if time is past the end of last key - index of the last key will be returned instead
+     * With assertions stripped, a NaN time is at or after no key, so like a time before the first key it returns 0.
      * @param {number} time
      * @returns {number} index of the key
      */
@@ -239,7 +240,9 @@ export class AnimationCurve {
             if (key_time <= time) {
                 found_index = pivot;
                 i0 = pivot + 1;
-            } else if (key_time > time) {
+            } else {
+                // also where a NaN on either side lands, as it compares false both ways:
+                // every iteration has to narrow the range, or the search never ends
                 i1 = pivot - 1;
             }
         }
@@ -256,6 +259,8 @@ export class AnimationCurve {
 
     /**
      * Evaluate interpolated value across the curve at a given time.
+     * On a curve of two or more keys, a NaN time fails an assertion during development; with assertions stripped it
+     * evaluates to NaN, or to the first key's value if the first two keys share a time.
      * @param {number} time time in seconds
      * @return {number} value at the specified time
      */

package/src/engine/asset/loaders/image/avif/threaded_image_encoder.js

@@ -229,7 +229,7 @@ export class ThreadedImageEncoder {
             width: sampler2d.width,
             height: sampler2d.height,
             item_size: sampler2d.itemSize,
-            is_hdr: data instanceof Uint16Array,
+            is_hdr: data instanceof Float16Array || data instanceof Uint16Array,
             quality,
             speed
         };

package/src/engine/ecs/EntityManager.d.ts

@@ -143,7 +143,15 @@ export class EntityManager {
      */
     private __execution_order_needs_update;
     /**
-     * Rebuild execution order
+     * Rebuild execution order.
+     *
+     * Nobody writes the order down; it is derived from what each system declares it touches. A
+     * system that writes a component runs before every other system in the same pass that reads it
+     * (see {@link orderSystemsByDeclaredAccess}, which also says how a cycle is broken). Where those
+     * edges leave a choice, the score below decides, then registration order.
+     *
+     * An explicit `runs_before` / `runs_after` was considered and rejected: it couples systems to
+     * each other by name, which is what deriving the order exists to avoid.
      * @private
      */
     private updateExecutionOrder;

package/src/engine/ecs/EntityManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAqBU,MAAM;;;;;;;;;AAoBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,kBAFU,aAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;;;MAGL;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEY;IAE5B;;;;;;;;OAQG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;OAKG;IACH,+BAA2B;IAE3B;;;;;;;;;;;;;;OAcG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IA8Bf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;OAGG;IACH,6BA4GC;IAED;;;;OAIG;IACH,4BAHW;QAAC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;KAAC,QAavD;IAED;;;OAGG;IACH,8BAHW;QAAC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;KAAC,GAC3C,OAAO,CAYnB;IAoBD;;;OAGG;IACH,uBAFa,KAAK,EAAE,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,cAkBhB;IAGD;;;OAGG;IACH,2BAFW,MAAM,QA6HhB;IAED;;;;;;;;;OASG;IACH,qBAFa,MAAM,CAKlB;IAED;;;;;OAKG;IACH,6CA6DC;IAED;;;;OAIG;IACH,mCAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAsDC;IAED;;;;;OAKG;IACH,oBA4FC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,2BAHW,KAAK,GACH,oBAAgB,CA0B5B;IAED;;;;OAIG;IACH,kCAJW,KAAK,SACL,WAAW,GACT,oBAAgB,CA0B5B;IAED;;;;;OAKG;IACH,mEAmEC;IAGL;;OAEG;IACH,yBA7wBe,sBAAsB,UA6wBA;IACrC;;OAEG;IACH,0BAAqC;IAErC;;OAEG;IACH,+BA5oBe,MAAM,UA4oBW;;CAd/B;6BAnpCY,OAAO,gCAAgC,EAAE,KAAK,CAAC,CAAC,CAAC;uBAN1B,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B;4BAEhC,aAAa"}
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/ecs/EntityManager.js"],"names":[],"mappings":"iCAsBU,MAAM;;;;;;;;;AAoBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAEI;;;;OAIG;IACH,kBAFU,aAAQ,CAEL;IAEb;;;;;;OAMG;IACH,uCAA2B;IAE3B;;;;;OAKG;IACH,iCAA4B;IAE5B;;OAEG;IACH;;;QAGI;;WAEG;;;MAGL;IAEF;;;OAGG;IACH,OAFU,kBAAkB,CAEO;IAEnC;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEY;IAE5B;;;;;;;;OAQG;IACH,wCAFU,MAAM,CAE4B;IAE5C;;;;;;;;OAQG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;OAKG;IACH,+BAA2B;IAE3B;;;;;;;;;;;;;;OAcG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,SAFU,sBAAsB,CAEjB;IA8Bf;;;;;OAKG;IACH,uCAAsC;IAEtC;;;;;;;;;;;OAWG;IACH,6BAkGC;IAED;;;;OAIG;IACH,4BAHW;QAAC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;KAAC,QAavD;IAED;;;OAGG;IACH,8BAHW;QAAC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;KAAC,GAC3C,OAAO,CAYnB;IAoBD;;;OAGG;IACH,uBAFa,KAAK,EAAE,CAuBnB;IAED;;;;;OAKG;IACH,uBAJW,sBAAsB,QA4ChC;IAGD;;;OAGG;IACH,sBA2BC;IAED;;;;OAIG;IACH,qCAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,6CAgBC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,cAkBhB;IAGD;;;OAGG;IACH,2BAFW,MAAM,QA6HhB;IAED;;;;;;;;;OASG;IACH,qBAFa,MAAM,CAKlB;IAED;;;;;OAKG;IACH,6CA6DC;IAED;;;;OAIG;IACH,mCAFa,QAAQ,OAAO,CAAC,CA2C5B;IAED;;;;;OAKG;IACH,mBAsDC;IAED;;;;;OAKG;IACH,oBA4FC;IAED;;;;;OAKG;IACH,kEAyEC;IAED;;;;OAIG;IACH,2BAHW,KAAK,GACH,oBAAgB,CA0B5B;IAED;;;;OAIG;IACH,kCAJW,KAAK,SACL,WAAW,GACT,oBAAgB,CA0B5B;IAED;;;;;OAKG;IACH,mEAmEC;IAGL;;OAEG;IACH,yBA7wBe,sBAAsB,UA6wBA;IACrC;;OAEG;IACH,0BAAqC;IAErC;;OAEG;IACH,+BA5oBe,MAAM,UA4oBW;;CAd/B;6BAjpCY,OAAO,gCAAgC,EAAE,KAAK,CAAC,CAAC,CAAC;uBAP1B,aAAa;mBAR9B,oCAAoC;uCAMhB,6BAA6B;4BAEhC,aAAa"}

package/src/engine/ecs/EntityManager.js

@@ -10,6 +10,7 @@ import { EntityComponentDataset } from "./EntityComponentDataset.js";
 import { EntityObserver } from "./EntityObserver.js";
 import { System, SystemState } from "./System.js";
 import { computeSystemComponentDependencyGraph } from "./system/computeSystemComponentDependencyGraph.js";
+import { orderSystemsByDeclaredAccess } from "./system/orderSystemsByDeclaredAccess.js";
 import { system_validate_class } from "./system_validate_class.js";
 
 /**
@@ -216,7 +217,15 @@ export class EntityManager {
     __execution_order_needs_update = true;
 
     /**
-     * Rebuild execution order
+     * Rebuild execution order.
+     *
+     * Nobody writes the order down; it is derived from what each system declares it touches. A
+     * system that writes a component runs before every other system in the same pass that reads it
+     * (see {@link orderSystemsByDeclaredAccess}, which also says how a cycle is broken). Where those
+     * edges leave a choice, the score below decides, then registration order.
+     *
+     * An explicit `runs_before` / `runs_after` was considered and rejected: it couples systems to
+     * each other by name, which is what deriving the order exists to avoid.
      * @private
      */
     updateExecutionOrder() {
@@ -253,6 +262,11 @@ export class EntityManager {
 
 
         /**
+         * Ranks the systems the write→read edges leave free to run in either order, and decides
+         * which system of a cycle runs first. It decides nothing an edge decides, and could not:
+         * it is a SUM over the components a system references, so a system that reads X and
+         * writes Y outscores the plain writer of X it depends on, and sorting by it alone ran that
+         * reader first.
          *
          * @param {System} system
          * @returns {number} higher values means it should be scheduled before others
@@ -275,24 +289,13 @@ export class EntityManager {
                 /*
                  The component itself, plus whatever depends on it.
 
-                 The `+ 1` is the whole of the fix, and the bug it closes is that the multipliers
-                 below were applied to a number the declaring system could not raise.
-                 `computeSystemComponentDependencyGraph` draws its edges from each component a
-                 system WRITES to each one it READS, so a component this system writes collects
-                 OUTgoing edges here and, from this system's own declaration, an in-degree of zero.
-                 Twice zero is zero: `Write` — the lever the whole design rests on — contributed
-                 nothing, a writer scored exactly what a reader scored, and `Array.prototype.sort`'s
-                 stability handed the decision back to registration order.
-
-                 Worse than a wrong answer, it was an answer that depended on OTHER systems'
-                 declarations. A port found its camera pose one frame late (GAP-037) only after
-                 reducing to a two-system rig; in the full application `PhysicsSystem` writing
-                 `RigidBody` and reading `Transform` lent `Transform` the incoming edge the camera
-                 system's own declaration did not, so a correct order was resting on a system it has
-                 nothing to do with, and would have inverted silently the day that system moved.
-
-                 An explicit `runs_before` / `runs_after` was considered and rejected: it couples
-                 systems to each other by name, which is what deriving the order exists to avoid.
+                 Without the `+ 1` the multipliers below apply to a number the declaring system
+                 cannot raise. `computeSystemComponentDependencyGraph` draws its edges from each
+                 component a system WRITES to each one it READS, so a component this system writes
+                 collects OUTgoing edges here and, from this system's own declaration, an in-degree
+                 of zero. Twice zero is zero, and Create, Write and Read stop ranking: a creator and
+                 a plain writer of one component, which no write→read edge orders, would tie and
+                 fall to registration order.
                 */
                 const weight = 1 + attached_edge_count;
 
@@ -311,18 +314,14 @@ export class EntityManager {
             return result;
         }
 
-        // pre-score systems for faster sorting
-        const scores = new Map();
+        // `order` is still in registration order here, which is what breaks a tie between scores
+        const scores = new Float64Array(executable_system_count);
 
         for (let i = 0; i < executable_system_count; i++) {
-            const system = order[i];
-
-            scores.set(system, scoreSystem(system));
+            scores[i] = scoreSystem(order[i]);
         }
 
-        order.sort((a, b) => {
-            return scores.get(b) - scores.get(a);
-        });
+        orderSystemsByDeclaredAccess(order, executable_system_count, scores);
 
         // clear update flag
         this.__execution_order_needs_update = false;

package/src/engine/ecs/gpu/GPUStateAuthority.d.ts

@@ -47,6 +47,26 @@ export class GPUStateAuthority {
      * @type {number}
      */
     flags: number;
+    /**
+     * Bitwise OR of the {@link GPUStateAuthorityFlags} a CPU writer holds against the GPU: a cloth
+     * simulating a cape joint's offset, while a clip may be bound to the same joint.
+     *
+     * Two writers want one component, and a hold is how the CPU one wins. A held bit is never set
+     * in {@link flags}: holding clears it, and a GPU writer's grant does not set it while the hold
+     * lasts. Whoever writes on the GPU hears of the hold (see
+     * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE}) and stops, and takes the component back when it
+     * ends. So {@link flags} stays the one statement of who writes, and what is held is why the GPU
+     * does not.
+     *
+     * One holder per component: a second CPU writer of the same component is the same race in
+     * another place, and holding twice is an error.
+     *
+     * Read it through {@link gpu_authority_held} and write it through {@link gpu_authority_hold} /
+     * {@link gpu_authority_unhold}.
+     *
+     * @type {number}
+     */
+    held: number;
 }
 export namespace GPUStateAuthority {
     let typeName: string;

package/src/engine/ecs/gpu/GPUStateAuthority.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUStateAuthority.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPUStateAuthority.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAYI;;;OAGG;IACH,oBAHW,MAAM,GACJ,iBAAiB,CAQ7B;IArBD;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;CAab;;kBAIS,MAAM;sBASN,OAAO"}
+{"version":3,"file":"GPUStateAuthority.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPUStateAuthority.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAiCI;;;OAGG;IACH,oBAHW,MAAM,GACJ,iBAAiB,CAQ7B;IA1CD;;;;;;;;OAQG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,MAAM,CAEP;CAaZ;;kBAIS,MAAM;sBASN,OAAO"}

package/src/engine/ecs/gpu/GPUStateAuthority.js

@@ -43,6 +43,27 @@ export class GPUStateAuthority {
      */
     flags = 0;
 
+    /**
+     * Bitwise OR of the {@link GPUStateAuthorityFlags} a CPU writer holds against the GPU: a cloth
+     * simulating a cape joint's offset, while a clip may be bound to the same joint.
+     *
+     * Two writers want one component, and a hold is how the CPU one wins. A held bit is never set
+     * in {@link flags}: holding clears it, and a GPU writer's grant does not set it while the hold
+     * lasts. Whoever writes on the GPU hears of the hold (see
+     * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE}) and stops, and takes the component back when it
+     * ends. So {@link flags} stays the one statement of who writes, and what is held is why the GPU
+     * does not.
+     *
+     * One holder per component: a second CPU writer of the same component is the same race in
+     * another place, and holding twice is an error.
+     *
+     * Read it through {@link gpu_authority_held} and write it through {@link gpu_authority_hold} /
+     * {@link gpu_authority_unhold}.
+     *
+     * @type {number}
+     */
+    held = 0;
+
     /**
      * @param {number} [flags]
      * @returns {GPUStateAuthority}

package/src/engine/ecs/gpu/GPU_AUTHORITY_EVENT_HOLD_CHANGE.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sent on an entity when a CPU writer takes or gives back a component it holds against the GPU —
+ * see {@link GPUStateAuthority#held}. The payload is the entity.
+ *
+ * What a GPU writer listens for on the entities it drives: a hold means stop writing, and the end of
+ * one means it may take the component back. Read the state off the entity rather than off the
+ * event; one event names both transitions.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const GPU_AUTHORITY_EVENT_HOLD_CHANGE: "@gpu_authority/hold_change";
+//# sourceMappingURL=GPU_AUTHORITY_EVENT_HOLD_CHANGE.d.ts.map

package/src/engine/ecs/gpu/GPU_AUTHORITY_EVENT_HOLD_CHANGE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPU_AUTHORITY_EVENT_HOLD_CHANGE.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/GPU_AUTHORITY_EVENT_HOLD_CHANGE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,2EAA4E"}

package/src/engine/ecs/gpu/GPU_AUTHORITY_EVENT_HOLD_CHANGE.js

@@ -0,0 +1,12 @@
+/**
+ * Sent on an entity when a CPU writer takes or gives back a component it holds against the GPU —
+ * see {@link GPUStateAuthority#held}. The payload is the entity.
+ *
+ * What a GPU writer listens for on the entities it drives: a hold means stop writing, and the end of
+ * one means it may take the component back. Read the state off the entity rather than off the
+ * event; one event names both transitions.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const GPU_AUTHORITY_EVENT_HOLD_CHANGE = "@gpu_authority/hold_change";

package/src/engine/ecs/gpu/gpu_authority_grant.d.ts

@@ -6,10 +6,16 @@
  * declaration site that was missed, and adding the component here to paper over it is exactly the
  * structural churn the declaration exists to avoid.
  *
+ * **A component a CPU writer holds is not granted** (see {@link GPUStateAuthority#held}). The hold
+ * is the reason, stated on the same component, and the GPU side takes the bit when the hold ends —
+ * {@link gpu_authority_unhold} says so on the entity. A clip binding a cloth's cape joint grants
+ * the joint's world and not its offset.
+ *
  * @param {EntityComponentDataset} dataset
  * @param {number} entity
  * @param {number} flags one or more {@link GPUStateAuthorityFlags}
  * @returns {boolean} whether anything changed — `false` when the GPU already owned all of them
+ * that are not held
  */
 export function gpu_authority_grant(dataset: EntityComponentDataset, entity: number, flags: number): boolean;
 //# sourceMappingURL=gpu_authority_grant.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_grant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gpu_authority_grant.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_grant.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,6EAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAsBnB"}
+{"version":3,"file":"gpu_authority_grant.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_grant.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AACH,6EALW,MAAM,SACN,MAAM,GACJ,OAAO,CAuBnB"}

package/src/engine/ecs/gpu/gpu_authority_grant.js

@@ -10,10 +10,16 @@ import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from ".
  * declaration site that was missed, and adding the component here to paper over it is exactly the
  * structural churn the declaration exists to avoid.
  *
+ * **A component a CPU writer holds is not granted** (see {@link GPUStateAuthority#held}). The hold
+ * is the reason, stated on the same component, and the GPU side takes the bit when the hold ends —
+ * {@link gpu_authority_unhold} says so on the entity. A clip binding a cloth's cape joint grants
+ * the joint's world and not its offset.
+ *
  * @param {EntityComponentDataset} dataset
  * @param {number} entity
  * @param {number} flags one or more {@link GPUStateAuthorityFlags}
  * @returns {boolean} whether anything changed — `false` when the GPU already owned all of them
+ * that are not held
  */
 export function gpu_authority_grant(dataset, entity, flags) {
     assert.defined(dataset, 'dataset');
@@ -26,7 +32,7 @@ export function gpu_authority_grant(dataset, entity, flags) {
     assert.ok(authority !== undefined && authority !== null, `entity ${entity} has no GPUStateAuthority — it must be declared at creation, see gpu_authority_declare`);
 
     const before = authority.flags;
-    const after = before | flags;
+    const after = before | (flags & ~authority.held);
 
     if (after === before) {
         return false;

package/src/engine/ecs/gpu/gpu_authority_held.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Does a CPU writer hold component X of entity E against the GPU? See
+ * {@link GPUStateAuthority#held}.
+ *
+ * Asks for **all** of `flags`, as {@link gpu_authority_has} does. No component means nothing is
+ * held.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean}
+ */
+export function gpu_authority_held(dataset: EntityComponentDataset, entity: number, flags: number): boolean;
+//# sourceMappingURL=gpu_authority_held.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_held.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_held.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_held.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,4EAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAUnB"}

package/src/engine/ecs/gpu/gpu_authority_held.js

@@ -0,0 +1,23 @@
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+
+/**
+ * Does a CPU writer hold component X of entity E against the GPU? See
+ * {@link GPUStateAuthority#held}.
+ *
+ * Asks for **all** of `flags`, as {@link gpu_authority_has} does. No component means nothing is
+ * held.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}
+ * @returns {boolean}
+ */
+export function gpu_authority_held(dataset, entity, flags) {
+    const authority = dataset.getComponent(entity, GPUStateAuthority);
+
+    if (authority === undefined || authority === null) {
+        return false;
+    }
+
+    return (authority.held & flags) === flags;
+}

package/src/engine/ecs/gpu/gpu_authority_hold.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Take these components for a CPU writer, against whatever writes them on the GPU, for as long as
+ * the hold lasts.
+ *
+ * A revoke says the GPU stopped writing. A hold says the CPU needs the component **whether or not
+ * the GPU wants it**: a cloth over a cape whose clip keys the same joints. The bits clear, the GPU
+ * side cannot grant them back until {@link gpu_authority_unhold}, and
+ * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE} tells a GPU writer already driving the entity to stop.
+ *
+ * Declares the entity if it never was. A hold is a claim and has to be visible on the entity; an
+ * entity no clip has ever been able to target carries no {@link GPUStateAuthority}, and a clip that
+ * binds it later must find the hold there. Seeding a garment is that entity's moment, as binding is
+ * for a joint attached under an animated one.
+ *
+ * **Holding does not seed a value.** The component holds what the CPU last wrote, which for a joint
+ * a clip was resolving is not this frame's pose; the holder writes its own before anything reads it.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, none of them already held
+ */
+export function gpu_authority_hold(dataset: EntityComponentDataset, entity: number, flags: number): void;
+//# sourceMappingURL=gpu_authority_hold.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_hold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_hold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_hold.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAHW,MAAM,SACN,MAAM,QAgBhB"}

package/src/engine/ecs/gpu/gpu_authority_hold.js

@@ -0,0 +1,41 @@
+import { assert } from "../../../core/assert.js";
+import { GPU_AUTHORITY_EVENT_HOLD_CHANGE } from "./GPU_AUTHORITY_EVENT_HOLD_CHANGE.js";
+import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from "./GPUStateAuthorityFlags.js";
+import { gpu_authority_declare } from "./gpu_authority_declare.js";
+
+/**
+ * Take these components for a CPU writer, against whatever writes them on the GPU, for as long as
+ * the hold lasts.
+ *
+ * A revoke says the GPU stopped writing. A hold says the CPU needs the component **whether or not
+ * the GPU wants it**: a cloth over a cape whose clip keys the same joints. The bits clear, the GPU
+ * side cannot grant them back until {@link gpu_authority_unhold}, and
+ * {@link GPU_AUTHORITY_EVENT_HOLD_CHANGE} tells a GPU writer already driving the entity to stop.
+ *
+ * Declares the entity if it never was. A hold is a claim and has to be visible on the entity; an
+ * entity no clip has ever been able to target carries no {@link GPUStateAuthority}, and a clip that
+ * binds it later must find the hold there. Seeding a garment is that entity's moment, as binding is
+ * for a joint attached under an animated one.
+ *
+ * **Holding does not seed a value.** The component holds what the CPU last wrote, which for a joint
+ * a clip was resolving is not this frame's pose; the holder writes its own before anything reads it.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, none of them already held
+ */
+export function gpu_authority_hold(dataset, entity, flags) {
+    assert.defined(dataset, 'dataset');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.isNonNegativeInteger(flags, 'flags');
+    assert.equal(flags & ~GPU_STATE_AUTHORITY_FLAGS_ALL, 0, `flags (${gpu_state_authority_flag_names(flags)}) contains bits GPUStateAuthorityFlags does not assign`);
+
+    const authority = gpu_authority_declare(dataset, entity);
+
+    assert.equal(authority.held & flags, 0, `entity ${entity} is already held for ${gpu_state_authority_flag_names(authority.held & flags)}: two CPU writers of one component`);
+
+    authority.held |= flags;
+    authority.flags &= ~flags;
+
+    dataset.sendEvent(entity, GPU_AUTHORITY_EVENT_HOLD_CHANGE, entity);
+}

package/src/engine/ecs/gpu/gpu_authority_unhold.d.ts

@@ -0,0 +1,14 @@
+/**
+ * End a CPU writer's hold on these components — the reverse of {@link gpu_authority_hold}.
+ *
+ * **Grants nothing.** Whether the GPU writes the component now is not the holder's to say: a clip
+ * may have bound the joint during the hold, or left it. The event tells whatever drives the entity
+ * on the GPU, and that writer takes the component back if it still wants it. With nothing driving
+ * it, it stays the CPU's, holding what the holder last wrote.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, every one of them held
+ */
+export function gpu_authority_unhold(dataset: EntityComponentDataset, entity: number, flags: number): void;
+//# sourceMappingURL=gpu_authority_unhold.d.ts.map

package/src/engine/ecs/gpu/gpu_authority_unhold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_authority_unhold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/gpu/gpu_authority_unhold.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,8EAHW,MAAM,SACN,MAAM,QAgBhB"}

package/src/engine/ecs/gpu/gpu_authority_unhold.js

@@ -0,0 +1,32 @@
+import { assert } from "../../../core/assert.js";
+import { GPU_AUTHORITY_EVENT_HOLD_CHANGE } from "./GPU_AUTHORITY_EVENT_HOLD_CHANGE.js";
+import { GPUStateAuthority } from "./GPUStateAuthority.js";
+import { GPU_STATE_AUTHORITY_FLAGS_ALL, gpu_state_authority_flag_names } from "./GPUStateAuthorityFlags.js";
+
+/**
+ * End a CPU writer's hold on these components — the reverse of {@link gpu_authority_hold}.
+ *
+ * **Grants nothing.** Whether the GPU writes the component now is not the holder's to say: a clip
+ * may have bound the joint during the hold, or left it. The event tells whatever drives the entity
+ * on the GPU, and that writer takes the component back if it still wants it. With nothing driving
+ * it, it stays the CPU's, holding what the holder last wrote.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} flags one or more {@link GPUStateAuthorityFlags}, every one of them held
+ */
+export function gpu_authority_unhold(dataset, entity, flags) {
+    assert.defined(dataset, 'dataset');
+    assert.isNonNegativeInteger(entity, 'entity');
+    assert.isNonNegativeInteger(flags, 'flags');
+    assert.equal(flags & ~GPU_STATE_AUTHORITY_FLAGS_ALL, 0, `flags (${gpu_state_authority_flag_names(flags)}) contains bits GPUStateAuthorityFlags does not assign`);
+
+    const authority = dataset.getComponent(entity, GPUStateAuthority);
+
+    assert.ok(authority !== undefined && authority !== null, `entity ${entity} has no GPUStateAuthority, so nothing holds it`);
+    assert.equal(authority.held & flags, flags, `entity ${entity} is not held for ${gpu_state_authority_flag_names(flags & ~authority.held)}`);
+
+    authority.held &= ~flags;
+
+    dataset.sendEvent(entity, GPU_AUTHORITY_EVENT_HOLD_CHANGE, entity);
+}

package/src/engine/ecs/ik/IKGoal.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A goal for the bone it sits on, the effector: bring it to where its target entity is, turning the
+ * bones from it up to {@link chain_root}. {@link IKGoalSystem} solves it.
+ *
+ * The tree is the {@link TransformAttachment} hierarchy, and the goal's path runs from the effector
+ * up to its chain root. A link of the path turns; the chain root turns and never moves. Joint limits
+ * are the physics `Joint` on each bone of the path.
+ *
+ * - The references are entities and are fixed while the component is attached: remove it and add it
+ *   back to change them.
+ * - The goal removes itself when its target or any bone of its path is destroyed.
+ * - Weights are 0..1. Position weight 0 gives the pose the bones would have without the goal, and the
+ *   pose is continuous in it. Rotation weight 0 leaves the effector's rotation riding its chain; 1
+ *   gives it the target's.
+ *
+ * Bones are spawned with their model and never saved, and an entity id means nothing in a save, so
+ * neither is this.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class IKGoal {
+    /**
+     * @param {{target:number, chain_root:number, position_weight:number, rotation_weight:number}} options
+     * every field required
+     * @returns {IKGoal}
+     */
+    static from({ target, chain_root, position_weight, rotation_weight }: {
+        target: number;
+        chain_root: number;
+        position_weight: number;
+        rotation_weight: number;
+    }): IKGoal;
+    /**
+     * The entity whose world pose the effector is brought to.
+     * @type {number}
+     */
+    target: number;
+    /**
+     * The highest bone the goal turns: the effector itself or one of its ancestors.
+     * @type {number}
+     */
+    chain_root: number;
+    /**
+     * How far toward the target the effector is pulled, 0..1.
+     * @type {number}
+     */
+    position_weight: number;
+    /**
+     * How far toward the target's rotation the effector is turned, 0..1.
+     * @type {number}
+     */
+    rotation_weight: number;
+}
+export namespace IKGoal {
+    let typeName: string;
+    let serializable: boolean;
+}
+//# sourceMappingURL=IKGoal.d.ts.map

package/src/engine/ecs/ik/IKGoal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IKGoal.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKGoal.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAyBI;;;;OAIG;IACH,sEAJW;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,UAAU,EAAC,MAAM,CAAC;QAAC,eAAe,EAAC,MAAM,CAAC;QAAC,eAAe,EAAC,MAAM,CAAA;KAAC,GAEhF,MAAM,CAkBlB;IA7CD;;;OAGG;IACH,QAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,YAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,iBAFU,MAAM,CAEI;CAwBvB;;kBAIS,MAAM;sBAMN,OAAO"}