@woosh/meep-engine 3.40.0 → 3.42.0

package/src/engine/graphics3/AnimationGraphSystem.js

@@ -1,329 +1,337 @@
-import { assert } from "../../core/assert.js";
-import { PosePlayback } from "../../shade/renderer/animation/pose/PosePlayback.js";
-import { System } from "../ecs/System.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
-import { AnimationGraphController } from "./animation/AnimationGraphController.js";
-import { write_graph_playback } from "./animation/write_graph_playback.js";
-import {
-    register_instance_clips,
-    unregister_instance_clips
-} from "./register_instance_animation.js";
-
-/**
- * Drives every entity's {@link AnimationGraphController}: runs its clock, and tells the renderer
- * what its clips weigh and where they are playing.
- *
- * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
- * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
- * clip's time is written down each frame from the controller's own clock. That is I-4: the pose
- * gameplay reads (sockets, effect anchors, projectile spawns) and the pose on the screen have to be
- * the same pose, and they cannot be if two clocks are running.
- *
- * **Nothing here is culled.** The legacy system skipped entities smaller than 32 px², which let
- * camera framing decide whether a footstep effect or an ability release ever happened. The clock and
- * its notifications are gameplay and run for every entity whose model has arrived; what may be
- * culled is drawing, and drawing is Shade's to cull.
- */
-export class AnimationGraphSystem extends System {
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * The system that owns the scene, the model instances, and the ids the animation manager issued
-     * for them.
-     *
-     * @type {MeshSystem}
-     */
-    #meshes;
-
-    /**
-     * @type {Map<number, {controller: AnimationGraphController, instance: PrefabInstance|null, clip_registration: InstanceClipRegistration|null, slots: Int32Array, played_slots: Int32Array, clip_ids: Int32Array, weights: Float32Array, poses: PosePlayback[]}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @param {GraphicsEngine} graphics
-     * @param {MeshSystem} meshes
-     */
-    constructor(graphics, meshes) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(meshes, 'meshes');
-
-        this.#graphics = graphics;
-        this.#meshes = meshes;
-
-        this.dependencies = [AnimationGraphController, SGMesh];
-    }
-
-    /**
-     * @param {AnimationGraphController} controller
-     * @param {SGMesh} model
-     * @param {number} entity
-     */
-    link(controller, model, entity) {
-        this.#entries.set(entity, {
-            controller,
-            instance: null,
-            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's model 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 the model rests.
-     *
-     * 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.
-     *
-     * @param {PosePlayback[]} target appended to
-     * @param {number} entity
-     * @returns {boolean} whether this system is driving the entity — `false` for one with no
-     * {@link AnimationGraphController}, and for one whose model has not arrived
-     */
-    write_pose_playbacks(target, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined || entry.instance === null) {
-            return false;
-        }
-
-        const clips = entry.instance.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 model: 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;
-    }
-
-    /**
-     * @param {AnimationGraphController} controller
-     * @param {SGMesh} model
-     * @param {number} entity
-     */
-    unlink(controller, model, entity) {
-        controller.unlink();
-
-        const entry = this.#entries.get(entity);
-
-        if (entry !== undefined) {
-            this.#release_clips(entry);
-        }
-
-        this.#entries.delete(entity);
-    }
-
-    async shutdown(entityManager) {
-        for (const entry of this.#entries.values()) {
-            entry.controller.unlink();
-
-            this.#release_clips(entry);
-        }
-
-        this.#entries.clear();
-    }
-
-    /**
-     * 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_instance_animation}, same `===`.
-     *
-     * @param {object} entry
-     */
-    #release_clips(entry) {
-        const registration = entry.clip_registration;
-
-        if (registration === null) {
-            return;
-        }
-
-        if (registration.context === this.#graphics.scene_context(this.#meshes.scene)) {
-            unregister_instance_clips(registration);
-        }
-
-        entry.clip_registration = null;
-    }
-
-    /**
-     * @param {number} time_delta_seconds
-     */
-    update(time_delta_seconds) {
-        const ecd = this.entityManager.dataset;
-
-        const context = this.#graphics.scene_context(this.#meshes.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 instance = this.#meshes.instance_of(entity);
-
-            if (instance === null) {
-                // the model has not arrived, and its clips are what say how long they run
-                continue;
-            }
-
-            if (instance !== entry.instance) {
-                this.#bind_model(entry, entity, instance, ecd);
-            }
-
-            entry.controller.tick(time_delta_seconds);
-
-            if (context === null) {
-                continue;
-            }
-
-            /*
-             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, instance, context);
-            }
-
-            write_graph_playback(manager, entry.controller, entry.clip_ids, entry.weights);
-        }
-    }
-
-    /**
-     * Bind the graph to a model: work out which of the model's clips each of the graph's clips is,
-     * how long each of them runs, and start the graph on that.
-     *
-     * @param {object} entry
-     * @param {number} entity
-     * @param {PrefabInstance} instance
-     * @param {EntityComponentDataset} ecd
-     */
-    #bind_model(entry, entity, instance, ecd) {
-        const clip_index = entry.controller.def.clipIndex;
-        const clip_count = clip_index.length;
-
-        const slots = new Int32Array(clip_count);
-        const durations = new Float64Array(clip_count);
-
-        for (let i = 0; i < clip_count; i++) {
-            const name = clip_index[i].name;
-
-            const slot = instance.clips.findIndex(clip => clip.name === name);
-
-            if (slot === -1) {
-                throw new Error(`Animation clip '${name}' is not in the model`);
-            }
-
-            slots[i] = slot;
-            durations[i] = instance.clips[slot].duration;
-        }
-
-        entry.controller.unlink();
-        entry.controller.link(entity, ecd, durations);
-
-        entry.instance = instance;
-        entry.slots = slots;
-
-        /*
-         The distinct clips of the model 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 = instance.clips.map(() => new PosePlayback());
-
-        // ids the manager issued for the model that was here before name clips this one does not
-        // have
-        this.#release_clips(entry);
-    }
-
-    /**
-     * Make this graph's clips playable, and take up the ids that come back.
-     *
-     * **Only the clips the graph names are registered** (D37), so there is nothing to silence: a
-     * clip of the model 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 model's own pose.
-     *
-     * @param {object} entry
-     * @param {PrefabInstance} instance
-     * @param {GPUSceneContext} context
-     */
-    #bind_gpu(entry, instance, context) {
-        const registration = register_instance_clips(context, instance, entry.played_slots);
-
-        const slots = entry.slots;
-        const clip_ids = entry.clip_ids;
-
-        for (let i = 0; i < slots.length; i++) {
-            clip_ids[i] = registration.ids[slots[i]];
-        }
-
-        entry.clip_registration = registration;
-
-        // whatever the last renderer was told is not what this one knows
-        entry.weights.fill(-1);
-    }
-}
+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 { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
+import { AnimationGraphController } from "./animation/AnimationGraphController.js";
+import { write_graph_playback } from "./animation/write_graph_playback.js";
+import {
+    register_instance_clips,
+    unregister_instance_clips
+} from "./register_instance_animation.js";
+
+/**
+ * Drives every entity's {@link AnimationGraphController}: runs its clock, and tells the renderer
+ * what its clips weigh and where they are playing.
+ *
+ * **It is the CPU that plays the animation and the GPU that draws it.** Shade can advance a clip
+ * itself, and this never asks it to — `AnimationClipFlags.Playing` is left clear and every audible
+ * clip's time is written down each frame from the controller's own clock. That is I-4: the pose
+ * gameplay reads (sockets, effect anchors, projectile spawns) and the pose on the screen have to be
+ * the same pose, and they cannot be if two clocks are running.
+ *
+ * **Nothing here is culled.** The legacy system skipped entities smaller than 32 px², which let
+ * camera framing decide whether a footstep effect or an ability release ever happened. The clock and
+ * its notifications are gameplay and run for every entity whose model has arrived; what may be
+ * culled is drawing, and drawing is Shade's to cull.
+ */
+export class AnimationGraphSystem extends System {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * The system that owns the scene, the model instances, and the ids the animation manager issued
+     * for them.
+     *
+     * @type {MeshSystem}
+     */
+    #meshes;
+
+    /**
+     * @type {Map<number, {controller: AnimationGraphController, instance: PrefabInstance|null, clip_registration: InstanceClipRegistration|null, slots: Int32Array, played_slots: Int32Array, clip_ids: Int32Array, weights: Float32Array, poses: PosePlayback[]}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {MeshSystem} meshes
+     */
+    constructor(graphics, meshes) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(meshes, 'meshes');
+
+        this.#graphics = graphics;
+        this.#meshes = meshes;
+
+        this.dependencies = [AnimationGraphController, SGMesh];
+
+        // 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.components_used = [
+            ResourceAccessSpecification.from(AnimationGraphController, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        ];
+    }
+
+    /**
+     * @param {AnimationGraphController} controller
+     * @param {SGMesh} model
+     * @param {number} entity
+     */
+    link(controller, model, entity) {
+        this.#entries.set(entity, {
+            controller,
+            instance: null,
+            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's model 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 the model rests.
+     *
+     * 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.
+     *
+     * @param {PosePlayback[]} target appended to
+     * @param {number} entity
+     * @returns {boolean} whether this system is driving the entity — `false` for one with no
+     * {@link AnimationGraphController}, and for one whose model has not arrived
+     */
+    write_pose_playbacks(target, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined || entry.instance === null) {
+            return false;
+        }
+
+        const clips = entry.instance.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 model: 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;
+    }
+
+    /**
+     * @param {AnimationGraphController} controller
+     * @param {SGMesh} model
+     * @param {number} entity
+     */
+    unlink(controller, model, entity) {
+        controller.unlink();
+
+        const entry = this.#entries.get(entity);
+
+        if (entry !== undefined) {
+            this.#release_clips(entry);
+        }
+
+        this.#entries.delete(entity);
+    }
+
+    async shutdown(entityManager) {
+        for (const entry of this.#entries.values()) {
+            entry.controller.unlink();
+
+            this.#release_clips(entry);
+        }
+
+        this.#entries.clear();
+    }
+
+    /**
+     * 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_instance_animation}, same `===`.
+     *
+     * @param {object} entry
+     */
+    #release_clips(entry) {
+        const registration = entry.clip_registration;
+
+        if (registration === null) {
+            return;
+        }
+
+        if (registration.context === this.#graphics.scene_context(this.#meshes.scene)) {
+            unregister_instance_clips(registration);
+        }
+
+        entry.clip_registration = null;
+    }
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        const ecd = this.entityManager.dataset;
+
+        const context = this.#graphics.scene_context(this.#meshes.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 instance = this.#meshes.instance_of(entity);
+
+            if (instance === null) {
+                // the model has not arrived, and its clips are what say how long they run
+                continue;
+            }
+
+            if (instance !== entry.instance) {
+                this.#bind_model(entry, entity, instance, ecd);
+            }
+
+            entry.controller.tick(time_delta_seconds);
+
+            if (context === null) {
+                continue;
+            }
+
+            /*
+             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, instance, context);
+            }
+
+            write_graph_playback(manager, entry.controller, entry.clip_ids, entry.weights);
+        }
+    }
+
+    /**
+     * Bind the graph to a model: work out which of the model's clips each of the graph's clips is,
+     * how long each of them runs, and start the graph on that.
+     *
+     * @param {object} entry
+     * @param {number} entity
+     * @param {PrefabInstance} instance
+     * @param {EntityComponentDataset} ecd
+     */
+    #bind_model(entry, entity, instance, ecd) {
+        const clip_index = entry.controller.def.clipIndex;
+        const clip_count = clip_index.length;
+
+        const slots = new Int32Array(clip_count);
+        const durations = new Float64Array(clip_count);
+
+        for (let i = 0; i < clip_count; i++) {
+            const name = clip_index[i].name;
+
+            const slot = instance.clips.findIndex(clip => clip.name === name);
+
+            if (slot === -1) {
+                throw new Error(`Animation clip '${name}' is not in the model`);
+            }
+
+            slots[i] = slot;
+            durations[i] = instance.clips[slot].duration;
+        }
+
+        entry.controller.unlink();
+        entry.controller.link(entity, ecd, durations);
+
+        entry.instance = instance;
+        entry.slots = slots;
+
+        /*
+         The distinct clips of the model 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 = instance.clips.map(() => new PosePlayback());
+
+        // ids the manager issued for the model that was here before name clips this one does not
+        // have
+        this.#release_clips(entry);
+    }
+
+    /**
+     * Make this graph's clips playable, and take up the ids that come back.
+     *
+     * **Only the clips the graph names are registered** (D37), so there is nothing to silence: a
+     * clip of the model 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 model's own pose.
+     *
+     * @param {object} entry
+     * @param {PrefabInstance} instance
+     * @param {GPUSceneContext} context
+     */
+    #bind_gpu(entry, instance, context) {
+        const registration = register_instance_clips(context, instance, entry.played_slots);
+
+        const slots = entry.slots;
+        const clip_ids = entry.clip_ids;
+
+        for (let i = 0; i < slots.length; i++) {
+            clip_ids[i] = registration.ids[slots[i]];
+        }
+
+        entry.clip_registration = registration;
+
+        // whatever the last renderer was told is not what this one knows
+        entry.weights.fill(-1);
+    }
+}