@woosh/meep-engine 3.52.0 → 3.53.0

package/src/engine/graphics3/AnimationGraphSystem.js

@@ -1,23 +1,20 @@
-import { assert } from "../../core/assert.js";
 import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
-import { PosePlayback } from "../../shade/renderer/animation/pose/PosePlayback.js";
 import { System } from "../ecs/System.js";
 import { AnimationClips } from "./animation/AnimationClips.js";
+import { AnimationClipsSink } from "./animation/AnimationClipsSink.js";
 import { AnimationGraphController } from "./animation/AnimationGraphController.js";
-import { write_graph_playback } from "./animation/write_graph_playback.js";
-import { hold_clip_targets, register_clips, release_clip_targets, unregister_clips } from "./register_clips.js";
-import { RowChains } from "./RowChains.js";
 
 /**
- * Drives every entity's {@link AnimationGraphController}: runs its clock, and tells the renderer
- * what its clips weigh and where they are playing.
+ * Drives every entity's {@link AnimationGraphController}: runs its clock, writes its clips' weights
+ * and times into the entity's {@link AnimationClips}, and hands that blend to the renderer through
+ * {@link AnimationClipsSink}.
  *
  * **The clips are the entity's {@link AnimationClips}.** An entity is driven while it carries both
  * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
  * clips are a new component, which this system sees as the entity leaving and coming back.
  *
- * **Every node the clips key holds a row here** ({@link hold_clip_targets}), from the graph being
+ * **Every node the clips key holds a row here** ({@link AnimationClipsSink}), from the graph being
  * bound to the clips until they go. A clip binds only once all of them do, and a keyed node outside
  * every skin with nothing drawn under it — a socket, say — is held by no other system.
  *
@@ -34,29 +31,15 @@ import { RowChains } from "./RowChains.js";
  */
 export class AnimationGraphSystem extends System {
     /**
-     * @type {GraphicsEngine}
+     * @type {AnimationClipsSink}
      */
-    #graphics;
+    #sink;
 
     /**
-     * The scene whose GPU context issues the clip ids.
-     *
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     * @type {Map<number, {controller: AnimationGraphController, clips: ShadeAnimationClip[], bound: boolean, held: boolean, clip_registration: ClipRegistration|null, slots: Int32Array, played_slots: Int32Array, clip_ids: Int32Array, weights: Float32Array, poses: PosePlayback[]}>}
+     * @type {Map<number, {controller: AnimationGraphController, clips: AnimationClips, bound: boolean, slots: Int32Array}>}
      */
     #entries = new Map();
 
-    /**
-     * The chains of the nodes the clips key. Null until the system has a dataset.
-     *
-     * @type {RowChains|null}
-     */
-    #chains = null;
-
     /**
      * @param {GraphicsEngine} graphics
      * @param {Scene} scene
@@ -64,18 +47,16 @@ export class AnimationGraphSystem extends System {
     constructor(graphics, scene) {
         super();
 
-        assert.defined(graphics, 'graphics');
-        assert.equal(scene?.isScene, true, 'scene.isScene !== true');
-
-        this.#graphics = graphics;
-        this.#scene = scene;
+        this.#sink = new AnimationClipsSink(graphics, scene);
 
         this.dependencies = [AnimationGraphController, AnimationClips];
 
-        // this tick's clip times are this system's to set: whatever evaluates a pose from them
-        // (exact queries, IK's base pose) reads AnimationGraphController and so runs after it
+        // this tick's clip times and weights are written onto AnimationClips: whatever evaluates a
+        // pose from them (exact queries, IK's base pose, contact probes) reads AnimationClips and
+        // so runs after it
         this.components_used = [
             ResourceAccessSpecification.from(AnimationGraphController, ResourceAccessKind.Read | ResourceAccessKind.Write),
+            ResourceAccessSpecification.from(AnimationClips, ResourceAccessKind.Read | ResourceAccessKind.Write),
         ];
     }
 
@@ -92,34 +73,15 @@ export class AnimationGraphSystem extends System {
     link(controller, clips, entity) {
         this.#entries.set(entity, {
             controller,
-            clips: clips.clips,
+            clips,
             bound: false,
-            held: false,
-            clip_registration: null,
             slots: new Int32Array(0),
-            played_slots: new Int32Array(0),
-            clip_ids: new Int32Array(0),
-            weights: new Float32Array(0),
-            poses: []
         });
     }
 
     /**
-     * What the entity is playing, in the form the CPU pose evaluator takes: one entry per clip
-     * **this graph names**, at the weight and the time the renderer has been given.
-     *
-     * **The clips the graph does not name are not here, because they are not registered** (D37).
-     * The GPU's accumulator marks a joint dirty for every bound clip that writes to it, weight and
-     * all — so a bound clip at weight zero resolves the joints only it drives to zero rather than
-     * leaving them at rest. The answer is not to hand those clips to the evaluator so it can make
-     * the same mistake; it is not to bind them. What the graph never names, nothing plays, and the
-     * joints it alone would have driven stay where they rest.
-     *
-     * A clip the graph names but is not currently playing **is** here, at weight zero, because it is
-     * bound and the accumulator does see it.
-     *
-     * The entries are this system's own and are rewritten by the next call, which is what keeps a
-     * query on a per-frame path from allocating.
+     * What the entity is playing, in the form the CPU pose evaluator takes: delegates to the
+     * entity's {@link AnimationClips#write_pose_playbacks}.
      *
      * @param {PosePlayback[]} target appended to
      * @param {number} entity
@@ -134,43 +96,7 @@ export class AnimationGraphSystem extends System {
             return false;
         }
 
-        const clips = entry.clips;
-        const poses = entry.poses;
-        const played = entry.played_slots;
-
-        for (let i = 0; i < played.length; i++) {
-            const slot = played[i];
-            const pose = poses[slot];
-
-            pose.clip = clips[slot];
-            pose.weight = 0;
-            pose.time = 0;
-        }
-
-        const controller = entry.controller;
-        const slots = entry.slots;
-        const weights = controller.blendState.weights;
-
-        for (let i = 0; i < slots.length; i++) {
-            const pose = poses[slots[i]];
-            const weight = weights[i];
-
-            // assignment rather than accumulation, and it matters only where two of the graph's
-            // clips are one clip of the entity: the renderer is written to in this order too, so the
-            // last of them is what it holds
-            pose.weight = weight;
-
-            if (weight > 0) {
-                pose.time = controller.clip_time(i);
-            }
-        }
-
-        // once each, however many of the graph's clips named it — the renderer holds one row for it
-        for (let i = 0; i < played.length; i++) {
-            target.push(poses[played[i]]);
-        }
-
-        return true;
+        return entry.clips.write_pose_playbacks(target);
     }
 
     /**
@@ -183,69 +109,29 @@ export class AnimationGraphSystem extends System {
 
         const entry = this.#entries.get(entity);
 
-        if (entry !== undefined) {
-            this.#release_clips(entry);
-
-            if (entry.held) {
-                release_clip_targets(this.#chains, entry.clips);
-
-                entry.held = false;
-            }
+        if (entry !== undefined && entry.bound) {
+            this.#sink.release(entry.clips);
         }
 
         this.#entries.delete(entity);
     }
 
     async startup(entityManager) {
-        // the scene's rows are this dataset's entities; the first system to place one says so
-        const dataset = entityManager.dataset;
-        const scene = this.#scene;
-
-        assert.ok(
-            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
-            'the scene is bound to another dataset'
-        );
-
-        scene.dataset = dataset;
-
-        this.#chains = new RowChains(dataset);
+        this.#sink.startup(entityManager.dataset);
     }
 
     async shutdown(entityManager) {
         for (const entry of this.#entries.values()) {
             entry.controller.unlink();
 
-            this.#release_clips(entry);
+            if (entry.bound) {
+                this.#sink.unbind_on_shutdown(entry.clips);
+            }
         }
 
         this.#entries.clear();
 
-        this.#chains.destroy();
-        this.#chains = null;
-    }
-
-    /**
-     * Give this entity's clips back, if the manager that issued them is still the one running.
-     *
-     * **An id may only be handed back to the manager that issued it.** A renderer restart replaces
-     * the GPU scene context and voids every id it gave out, so a registration stamped with a context
-     * that is no longer current is forgotten rather than returned — returning it would corrupt a
-     * stranger's table. Same rule as {@link unregister_clips}, same `===`.
-     *
-     * @param {object} entry
-     */
-    #release_clips(entry) {
-        const registration = entry.clip_registration;
-
-        if (registration === null) {
-            return;
-        }
-
-        if (registration.context === this.#graphics.scene_context(this.#scene)) {
-            unregister_clips(registration);
-        }
-
-        entry.clip_registration = null;
+        this.#sink.shutdown();
     }
 
     /**
@@ -253,37 +139,23 @@ export class AnimationGraphSystem extends System {
      */
     update(time_delta_seconds) {
         const ecd = this.entityManager.dataset;
+        const context = this.#sink.begin_update();
 
-        const context = this.#graphics.scene_context(this.#scene);
-
-        // No device — before the first start, and again after a stop. The clocks still run: a unit
-        // that fires an ability while the renderer is being replaced still fires it.
-        const manager = context === null ? null : context.animation_manager;
+        for (const [entity, entry] of this.#entries) {
+            const { controller, clips } = entry;
 
-        // a new context after a restart is acquired in whole; until there is one, holds are recorded
-        this.#chains.bind(context === null ? null : context.rows);
+            let slots_changed = false;
 
-        for (const [entity, entry] of this.#entries) {
             if (!entry.bound) {
                 this.#bind_clips(entry, entity, ecd);
+                slots_changed = true;
             }
 
-            entry.controller.tick(time_delta_seconds);
+            controller.tick(time_delta_seconds);
 
-            if (context === null) {
-                continue;
-            }
+            this.#write_playback(controller, entry.slots, clips);
 
-            /*
-             Registered against the context that is running now. A renderer restart builds a new one
-             and voids every id the old gave out, and the stamp on the registration is how that is
-             noticed — in one comparison, without depending on when anything last ran.
-            */
-            if (entry.clip_registration === null || entry.clip_registration.context !== context) {
-                this.#bind_gpu(entry, context);
-            }
-
-            write_graph_playback(manager, entry.controller, entry.clip_ids, entry.weights);
+            this.#sink.sync(clips, context, slots_changed);
         }
     }
 
@@ -297,6 +169,7 @@ export class AnimationGraphSystem extends System {
      */
     #bind_clips(entry, entity, ecd) {
         const clips = entry.clips;
+        const available = clips.clips;
 
         const clip_index = entry.controller.def.clipIndex;
         const clip_count = clip_index.length;
@@ -307,14 +180,14 @@ export class AnimationGraphSystem extends System {
         for (let i = 0; i < clip_count; i++) {
             const name = clip_index[i].name;
 
-            const slot = clips.findIndex(clip => clip.name === name);
+            const slot = available.findIndex(clip => clip.name === name);
 
             if (slot === -1) {
                 throw new Error(`Animation clip '${name}' is not among the clips of entity ${entity}`);
             }
 
             slots[i] = slot;
-            durations[i] = clips[slot].duration;
+            durations[i] = available[slot].duration;
         }
 
         entry.controller.unlink();
@@ -322,59 +195,41 @@ export class AnimationGraphSystem extends System {
 
         entry.slots = slots;
 
-        /*
-         The distinct clips this graph plays. Two states can name one clip — an idle a hurt returns
-         to, say — and it is one row on the GPU either way, so it is one entry here: registered once,
-         reported to the pose evaluator once.
-        */
-        const played = [];
-
-        for (let i = 0; i < clip_count; i++) {
-            if (played.indexOf(slots[i]) === -1) {
-                played.push(slots[i]);
-            }
-        }
-
-        entry.played_slots = Int32Array.from(played);
-
-        entry.clip_ids = new Int32Array(clip_count);
-        entry.weights = new Float32Array(clip_count).fill(-1);
-        entry.poses = clips.map(() => new PosePlayback());
-
-        entry.bound = true;
-
         // past the throw above, so a graph that cannot be bound holds nothing; and before anything
         // registers, so the clips bind in the update that registers them
-        hold_clip_targets(this.#chains, clips);
+        this.#sink.bind(clips);
+        clips.set_played_slots(slots);
 
-        entry.held = true;
+        entry.bound = true;
     }
 
     /**
-     * Make this graph's clips playable, and take up the ids that come back.
+     * Copy the graph's current blend into the entity's {@link AnimationClips} sink.
      *
-     * **Only the clips the graph names are registered** (D37), so there is nothing to silence: a
-     * clip no state plays is never bound, never marks a joint, and leaves the joints only it would
-     * have driven at rest. What this used to do instead — register everything and then write a zero
-     * weight over the surplus — kept them bound, and a bound clip at weight zero resolves its joints
-     * to zero rather than to the rig's own pose.
-     *
-     * @param {object} entry
-     * @param {GPUSceneContext} context
+     * @param {AnimationGraphController} controller
+     * @param {Int32Array} slots
+     * @param {AnimationClips} clips
      */
-    #bind_gpu(entry, context) {
-        const registration = register_clips(context, entry.clips, entry.played_slots);
+    #write_playback(controller, slots, clips) {
+        const graph_weights = controller.blendState.weights;
+        const weights = clips.weights;
+        const times = clips.times;
 
-        const slots = entry.slots;
-        const clip_ids = entry.clip_ids;
+        weights.fill(0);
+        times.fill(0);
 
         for (let i = 0; i < slots.length; i++) {
-            clip_ids[i] = registration.ids[slots[i]];
-        }
+            const slot = slots[i];
+            const weight = graph_weights[i];
 
-        entry.clip_registration = registration;
+            // assignment rather than accumulation, and it matters only where two of the graph's
+            // clips are one clip of the entity: the renderer is written to in this order too, so the
+            // last of them is what it holds
+            weights[slot] = weight;
 
-        // whatever the last renderer was told is not what this one knows
-        entry.weights.fill(-1);
+            if (weight > 0) {
+                times[slot] = controller.clip_time(i);
+            }
+        }
     }
 }

package/src/engine/graphics3/AnimationSystem.d.ts

@@ -1,17 +1,17 @@
 /**
  * Drives every entity's {@link Animation} component: runs the clocks of the clips its list names,
- * and tells the renderer what each of them weighs and where it is playing.
+ * writes their weights and times into the entity's {@link AnimationClips}, and hands that blend to
+ * the renderer through {@link AnimationClipsSink}.
  *
  * The list path is what the game uses wherever there is no state machine — buildings, critters and
  * the strategy map's groups — and {@link ClipListPlayer} is what plays it. This is the ECS half:
- * which clips each entity has, and when the ids the renderer issued for them stopped meaning
- * anything.
+ * which clips each entity has, and syncing the component's playback sink with the GPU.
  *
  * **The clips are the entity's {@link AnimationClips}.** An entity is driven while it carries both
  * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
  * clips are a new component, which this system sees as the entity leaving and coming back.
  *
- * **Every node the clips key holds a row here** ({@link hold_clip_targets}), from the clips being
+ * **Every node the clips key holds a row here** ({@link AnimationClipsSink}), from the clips being
  * taken up until they go. A clip binds only once all of them do, and a keyed node outside every skin
  * with nothing drawn under it is held by no other system.
  *
@@ -32,7 +32,7 @@ export class AnimationSystem extends System<any> {
      */
     constructor(graphics: GraphicsEngine, scene: Scene);
     dependencies: (typeof Animation | typeof AnimationClips)[];
-    components_used: ResourceAccessSpecification<typeof Animation>[];
+    components_used: (ResourceAccessSpecification<typeof AnimationClips> | ResourceAccessSpecification<typeof Animation>)[];
     /**
      * What an entity is playing, and where each of them is.
      *
@@ -44,18 +44,8 @@ export class AnimationSystem extends System<any> {
      */
     playbacks_of(entity: number): ClipPlayback[];
     /**
-     * What the entity is playing, in the form the CPU pose evaluator takes: one entry per clip of its
-     * {@link AnimationClips} that the list names, at the weight and the time the renderer has been
-     * given.
-     *
-     * **Only the clips the list names are here, because they are the only ones registered** (D37).
-     * The GPU's accumulator marks a joint dirty for every bound clip that writes to it, weight and
-     * all — so a bound clip at weight zero resolves the joints only it drives to zero rather than
-     * leaving them at rest. The answer is not to hand the surplus to the evaluator so it agrees with
-     * a mistake; it is not to bind them, and then a clip nothing names moves nothing.
-     *
-     * The entries are this system's own and are rewritten by the next call, which is what keeps a
-     * query on a per-frame path from allocating.
+     * What the entity is playing, in the form the CPU pose evaluator takes: delegates to the
+     * entity's {@link AnimationClips#write_pose_playbacks}.
      *
      * @param {PosePlayback[]} target appended to
      * @param {number} entity
@@ -88,5 +78,4 @@ import { System } from "../ecs/System.js";
 import { Animation } from "../ecs/animation/Animation.js";
 import { AnimationClips } from "./animation/AnimationClips.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
-import { PosePlayback } from "../../shade/renderer/animation/pose/PosePlayback.js";
 //# sourceMappingURL=AnimationSystem.d.ts.map

package/src/engine/graphics3/AnimationSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationSystem.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAyBI;;;OAGG;IACH,oDAgBC;IAPG,2DAA+C;IAI/C,iEAEC;IAGL;;;;;;;;OAQG;IACH,qBAHW,MAAM,GACJ,cAAc,CAU1B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,6BANW,YAAY,EAAE,UACd,MAAM,GACJ,OAAO,CAyCnB;IAED;;;;;;;;OAQG;IACH,gBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAahB;IAED;;;;OAIG;IACH,kBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAgBhB;IAED,2CAaC;IAED,4CASC;;CA8KJ;uBArZsB,kBAAkB;0BADf,+BAA+B;+BAE1B,+BAA+B;4CAJlB,iDAAiD;6BAChE,qDAAqD"}
+{"version":3,"file":"AnimationSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/AnimationSystem.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAWI;;;OAGG;IACH,oDAcC;IATG,2DAA+C;IAK/C,wHAGC;IAGL;;;;;;;;OAQG;IACH,qBAHW,MAAM,GACJ,cAAc,CAU1B;IAED;;;;;;;;;OASG;IACH,6BANW,cAAc,UACd,MAAM,GACJ,OAAO,CAYnB;IAED;;;;;;;;OAQG;IACH,gBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAQhB;IAED;;;;OAIG;IACH,kBAJW,SAAS,SACT,cAAc,UACd,MAAM,QAUhB;IAED,2CAEC;IAED,4CAUC;;CAkEJ;uBAlOsB,kBAAkB;0BADf,+BAA+B;+BAE1B,+BAA+B;4CAHlB,iDAAiD"}