@woosh/meep-engine 3.43.0 → 3.44.0

package/src/engine/graphics3/AnimationSystem.js

@@ -4,13 +4,10 @@ import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpec
 import { PosePlayback } from "../../shade/renderer/animation/pose/PosePlayback.js";
 import { Animation } from "../ecs/animation/Animation.js";
 import { System } from "../ecs/System.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
+import { AnimationClips } from "./animation/AnimationClips.js";
 import { ClipListPlayer } from "./animation/ClipListPlayer.js";
 import { write_clip_playback } from "./animation/write_clip_playback.js";
-import {
-    register_instance_clips,
-    unregister_instance_clips
-} from "./register_instance_animation.js";
+import { register_clips, unregister_clips } from "./register_clips.js";
 
 /**
  * @type {ClipPlayback[]}
@@ -23,9 +20,13 @@ const NOTHING = Object.freeze([]);
  *
  * 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 entity has which model, and when the ids the renderer issued for it stopped meaning
+ * which clips each entity has, and when the ids the renderer issued for them stopped meaning
  * anything.
  *
+ * **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.
+ *
  * **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 player's own clock. That is I-4: the pose
@@ -43,32 +44,31 @@ export class AnimationSystem extends System {
     #graphics;
 
     /**
-     * The system that owns the scene, the model instances, and the ids the animation manager issued
-     * for them.
+     * The scene whose GPU context issues the clip ids.
      *
-     * @type {MeshSystem}
+     * @type {Scene}
      */
-    #meshes;
+    #scene;
 
     /**
-     * @type {Map<number, {player: ClipListPlayer, instance: PrefabInstance|null, clip_registration: InstanceClipRegistration|null, played_slots: Int32Array, written: Float32Array, poses: PosePlayback[]}>}
+     * @type {Map<number, {player: ClipListPlayer, clips: ShadeAnimationClip[], bound: boolean, clip_registration: ClipRegistration|null, played_slots: Int32Array, written: Float32Array, poses: PosePlayback[]}>}
      */
     #entries = new Map();
 
     /**
      * @param {GraphicsEngine} graphics
-     * @param {MeshSystem} meshes
+     * @param {Scene} scene
      */
-    constructor(graphics, meshes) {
+    constructor(graphics, scene) {
         super();
 
         assert.defined(graphics, 'graphics');
-        assert.defined(meshes, 'meshes');
+        assert.equal(scene?.isScene, true, 'scene.isScene !== true');
 
         this.#graphics = graphics;
-        this.#meshes = meshes;
+        this.#scene = scene;
 
-        this.dependencies = [Animation, SGMesh];
+        this.dependencies = [Animation, 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 Animation and so runs after it
@@ -81,8 +81,7 @@ export class AnimationSystem extends System {
      * What an entity is playing, and where each of them is.
      *
      * One entry per clip in the component's list, in the list's own order. Empty for an entity this
-     * system is not driving — one that has left, or one whose model has not arrived, which is the
-     * same wait the clip durations are on.
+     * system is not driving — one that has left, or one whose clips arrived since the last update.
      *
      * @param {number} entity
      * @returns {ClipPlayback[]}
@@ -98,14 +97,15 @@ export class AnimationSystem extends System {
     }
 
     /**
-     * What the entity's model is playing, in the form the CPU pose evaluator takes: one entry per
-     * clip the model carries, at the weight and the time the renderer has been given.
+     * 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 of the model nothing names moves nothing.
+     * 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.
@@ -113,16 +113,17 @@ export class AnimationSystem extends System {
      * @param {PosePlayback[]} target appended to
      * @param {number} entity
      * @returns {boolean} whether this system is driving the entity — `false` for one with no
-     * {@link Animation}, and for one whose model has not arrived
+     * {@link Animation} or no {@link AnimationClips}, and for one whose clips arrived since the last
+     * update
      */
     write_pose_playbacks(target, entity) {
         const entry = this.#entries.get(entity);
 
-        if (entry === undefined || entry.instance === null) {
+        if (entry === undefined || !entry.bound) {
             return false;
         }
 
-        const clips = entry.instance.clips;
+        const clips = entry.clips;
         const weights = entry.player.weights;
         const poses = entry.poses;
         const played = entry.played_slots;
@@ -155,14 +156,19 @@ export class AnimationSystem extends System {
     }
 
     /**
+     * Only noted here: the clips are taken up by the next {@link update}. A link can happen anywhere
+     * the components are added — inside a model's spawn, for one `MeshSystem` loads — and binding is
+     * this system's work, on its own tick.
+     *
      * @param {Animation} component
-     * @param {SGMesh} model
+     * @param {AnimationClips} clips
      * @param {number} entity
      */
-    link(component, model, entity) {
+    link(component, clips, entity) {
         this.#entries.set(entity, {
             player: ClipListPlayer.from(component),
-            instance: null,
+            clips: clips.clips,
+            bound: false,
             clip_registration: null,
             played_slots: new Int32Array(0),
             written: new Float32Array(0),
@@ -172,10 +178,10 @@ export class AnimationSystem extends System {
 
     /**
      * @param {Animation} component
-     * @param {SGMesh} model
+     * @param {AnimationClips} clips
      * @param {number} entity
      */
-    unlink(component, model, entity) {
+    unlink(component, clips, entity) {
         const entry = this.#entries.get(entity);
 
         if (entry !== undefined) {
@@ -221,23 +227,23 @@ export class AnimationSystem extends System {
             return;
         }
 
-        if (registration.context === this.#graphics.scene_context(this.#meshes.scene)) {
-            unregister_instance_clips(registration);
+        if (registration.context === this.#graphics.scene_context(this.#scene)) {
+            unregister_clips(registration);
         }
 
         entry.clip_registration = null;
     }
 
     /**
-     * Which of the model's clips the list currently names, kept up to date.
+     * Which of the entity's clips the list currently names, kept up to date.
      *
      * **The list is edited while the game runs** — `ClipListPlayer` reconciles its playbacks against
      * it every tick, and `StopAnimationBehavior` empties it outright — so which clips are playable
      * is not settled once at bind.
      *
      * Maintained here rather than alongside the registration because **the pose evaluator needs it
-     * whether or not there is a device**: `query_entity_node_world_pose` answers on the CPU, from
-     * the clips this driver plays, and a game with rendering disabled still asks (I-4).
+     * whether or not there is a device**: `collect_entity_playbacks` answers on the CPU, from the
+     * clips this driver plays, and a game with rendering disabled still asks (I-4).
      *
      * @param {object} entry
      * @returns {boolean} whether the set changed
@@ -247,10 +253,9 @@ export class AnimationSystem extends System {
         const played = entry.played_slots;
 
         /*
-         The distinct slots, and distinct is the point: two entries of the list can name one clip of
-         the model, so the number of playbacks is not the number of clips. Comparing the two would
-         report a change on every frame for a list that had not moved, and a change here is a
-         re-registration.
+         The distinct slots, and distinct is the point: two entries of the list can name one clip, so
+         the number of playbacks is not the number of clips. Comparing the two would report a change
+         on every frame for a list that had not moved, and a change here is a re-registration.
         */
         const wanted = [];
 
@@ -289,12 +294,11 @@ export class AnimationSystem extends System {
      * the joints only it drives down to zero with it.
      *
      * @param {object} entry
-     * @param {PrefabInstance} instance
      * @param {GPUSceneContext} context
      * @param {boolean} set_changed whether {@link #refresh_played_slots} just moved
      * @returns {boolean} whether the registration was replaced
      */
-    #refresh_clips(entry, instance, context, set_changed) {
+    #refresh_clips(entry, context, set_changed) {
         const registration = entry.clip_registration;
 
         if (!set_changed && registration !== null && registration.context === context) {
@@ -303,42 +307,44 @@ export class AnimationSystem extends System {
 
         this.#release_clips_only(entry);
 
-        entry.clip_registration = register_instance_clips(context, instance, entry.played_slots);
+        entry.clip_registration = register_clips(context, entry.clips, entry.played_slots);
 
         return true;
     }
 
+    /**
+     * Take up the entity's clips: the list is played against them from here on.
+     *
+     * @param {object} entry
+     * @param {number} entity
+     * @param {EntityComponentDataset} ecd
+     */
+    #bind(entry, entity, ecd) {
+        const clips = entry.clips;
+
+        entry.player.bind(entity, ecd, clips);
+
+        entry.written = new Float32Array(clips.length).fill(-1);
+        entry.poses = clips.map(() => new PosePlayback());
+
+        entry.bound = true;
+    }
+
     /**
      * @param {number} time_delta_seconds
      */
     update(time_delta_seconds) {
         const ecd = this.entityManager.dataset;
 
-        const context = this.#graphics.scene_context(this.#meshes.scene);
+        const context = this.#graphics.scene_context(this.#scene);
 
         // No device — before the first start, and again after a stop. The clocks still run: a clip
         // that ends while the renderer is being replaced still says so.
         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) {
-                entry.instance = instance;
-
-                entry.player.bind(entity, ecd, instance);
-
-                entry.written = new Float32Array(instance.clips.length).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);
+            if (!entry.bound) {
+                this.#bind(entry, entity, ecd);
             }
 
             entry.player.tick(time_delta_seconds);
@@ -349,7 +355,7 @@ export class AnimationSystem extends System {
                 continue;
             }
 
-            if (this.#refresh_clips(entry, instance, context, set_changed)) {
+            if (this.#refresh_clips(entry, context, set_changed)) {
                 // whatever the last registration was told is not what this one knows
                 entry.written.fill(-1);
             }

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

@@ -0,0 +1,56 @@
+/**
+ * Deforms every primitive that carries a {@link MeshSkin}: registers its skin with the animation
+ * manager, binds the primitive to it, and holds a row for each joint and everything above it.
+ *
+ * **It does not care where the skin came from.** `MeshSystem` puts one on each skinned primitive of
+ * a model it loads; code building a skinned mesh puts one there itself. Both are the same
+ * components on the same kinds of entities, and this is the whole of what makes them deform —
+ * `ShadedGeometrySystem` draws the clone, this binds it.
+ *
+ * **One skeleton, one registration.** A body and its hair carry a skin each, with the same joints
+ * bound the same way; the manager answers both registrations with one skin, so the skeleton's
+ * matrices are made once a frame.
+ *
+ * **Joint rows are chains** ({@link RowChains}). A joint composes on the GPU under its parent's row;
+ * under a clip-driven ancestor that is the only place its world is right, and a clip keying the
+ * ancestor binds only once the ancestor holds a row.
+ *
+ * **Registration waits for {@link update}**, never happening at link. A spawn adds components node
+ * by node, so a joint later in the file is not complete when the primitive links; and there may be
+ * no device to register with. A restart replaces the context and voids every id it issued: they are
+ * forgotten rather than handed back, and every skin registers again in the new one.
+ */
+export class MeshSkinSystem extends System<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics: GraphicsEngine, scene: Scene);
+    dependencies: (typeof ShadedGeometry | typeof MeshSkin)[];
+    /**
+     * @returns {Scene}
+     */
+    get scene(): import("../../shade/renderer/scene/Scene.js").Scene;
+    startup(entityManager: any): Promise<void>;
+    shutdown(entityManager: any): Promise<void>;
+    /**
+     * @param {MeshSkin} skin
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    link(skin: MeshSkin, geometry: ShadedGeometry, entity: number): void;
+    /**
+     * @param {MeshSkin} skin
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    unlink(skin: MeshSkin, geometry: ShadedGeometry, entity: number): void;
+    #private;
+}
+export type GPUSceneContext = import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+export type GraphicsEngine = import("./GraphicsEngine.js").GraphicsEngine;
+export type Scene = import("../../shade/renderer/scene/Scene.js").Scene;
+import { System } from "../ecs/System.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { MeshSkin } from "../graphics/ecs/mesh-v2/MeshSkin.js";
+//# sourceMappingURL=MeshSkinSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MeshSkinSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/MeshSkinSystem.js"],"names":[],"mappings":"AAmDA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAsCI;;;OAGG;IACH,sBAHW,cAAc,SACd,KAAK,EAYf;IADG,0DAA8C;IAGlD;;OAEG;IACH,iEAEC;IAED,2CAeC;IAED,4CAUC;IAED;;;;OAIG;IACH,WAJW,QAAQ,YACR,cAAc,UACd,MAAM,QAehB;IAED;;;;OAIG;IACH,aAJW,QAAQ,YACR,cAAc,UACd,MAAM,QAIhB;;CA8HJ;8BApTY,OAAO,+CAA+C,EAAE,eAAe;6BACvE,OAAO,qBAAqB,EAAE,cAAc;oBAC5C,OAAO,qCAAqC,EAAE,KAAK;uBATzC,kBAAkB;+BAEV,2CAA2C;yBADjD,qCAAqC"}

package/src/engine/graphics3/MeshSkinSystem.js

@@ -0,0 +1,317 @@
+import { assert } from "../../core/assert.js";
+import { System } from "../ecs/System.js";
+import { MeshSkin } from "../graphics/ecs/mesh-v2/MeshSkin.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { RowChains } from "./RowChains.js";
+
+/**
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("./GraphicsEngine.js").GraphicsEngine} GraphicsEngine
+ * @typedef {import("../../shade/renderer/scene/Scene.js").Scene} Scene
+ */
+
+/**
+ * What the GPU gave one skinned primitive, and in which context.
+ */
+class Entry {
+    /**
+     * @type {number}
+     */
+    entity = -1;
+
+    /**
+     * @type {MeshSkin}
+     */
+    skin = null;
+
+    /**
+     * The id the animation manager issued for the skin, or -1 while nothing is registered: not yet,
+     * no device, or a restart not yet drained.
+     *
+     * @type {number}
+     */
+    skin_id = -1;
+
+    /**
+     * The context {@link skin_id} belongs to, or null while there is none.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    context = null;
+
+    /**
+     * Whether the joints' chains are held. They are held from the first registration until the
+     * entity leaves, across restarts: the chains re-acquire in a new context on their own.
+     *
+     * @type {boolean}
+     */
+    held = false;
+}
+
+/**
+ * Deforms every primitive that carries a {@link MeshSkin}: registers its skin with the animation
+ * manager, binds the primitive to it, and holds a row for each joint and everything above it.
+ *
+ * **It does not care where the skin came from.** `MeshSystem` puts one on each skinned primitive of
+ * a model it loads; code building a skinned mesh puts one there itself. Both are the same
+ * components on the same kinds of entities, and this is the whole of what makes them deform —
+ * `ShadedGeometrySystem` draws the clone, this binds it.
+ *
+ * **One skeleton, one registration.** A body and its hair carry a skin each, with the same joints
+ * bound the same way; the manager answers both registrations with one skin, so the skeleton's
+ * matrices are made once a frame.
+ *
+ * **Joint rows are chains** ({@link RowChains}). A joint composes on the GPU under its parent's row;
+ * under a clip-driven ancestor that is the only place its world is right, and a clip keying the
+ * ancestor binds only once the ancestor holds a row.
+ *
+ * **Registration waits for {@link update}**, never happening at link. A spawn adds components node
+ * by node, so a joint later in the file is not complete when the primitive links; and there may be
+ * no device to register with. A restart replaces the context and voids every id it issued: they are
+ * forgotten rather than handed back, and every skin registers again in the new one.
+ */
+export class MeshSkinSystem extends System {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * @type {Map<number, Entry>}
+     */
+    #entries = new Map();
+
+    /**
+     * The scene's GPU context as of the last {@link update}. A different one is a restart.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    #context = null;
+
+    /**
+     * Entries not registered with {@link #context}: linked since the last frame, or voided by a
+     * restart. A queue rather than a scan, because the answer is almost always "nothing to do".
+     *
+     * @type {Entry[]}
+     */
+    #unregistered = [];
+
+    /**
+     * The joints' chains. Null until the system has a dataset.
+     *
+     * @type {RowChains|null}
+     */
+    #chains = null;
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+
+        this.dependencies = [MeshSkin, ShadedGeometry];
+    }
+
+    /**
+     * @returns {Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = 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);
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+
+        this.#chains.destroy();
+        this.#chains = null;
+
+        this.#context = null;
+        this.#unregistered.length = 0;
+    }
+
+    /**
+     * @param {MeshSkin} skin
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    link(skin, geometry, entity) {
+        assert.equal(
+            geometry.getFlag(ShadedGeometryFlags.Skinned), true,
+            'a MeshSkin deforms a geometry that draws a clone: set ShadedGeometryFlags.Skinned'
+        );
+
+        const entry = new Entry();
+
+        entry.entity = entity;
+        entry.skin = skin;
+
+        this.#entries.set(entity, entry);
+        this.#unregistered.push(entry);
+    }
+
+    /**
+     * @param {MeshSkin} skin
+     * @param {ShadedGeometry} geometry
+     * @param {number} entity
+     */
+    unlink(skin, geometry, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * Register what arrived since the last frame, and everything again after a restart.
+     *
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        const context = this.#graphics.scene_context(this.#scene);
+
+        if (context === null) {
+            // No device — before the first start, or after a stop. The next context to arrive is a
+            // change like any other.
+            this.#chains.bind(null);
+
+            return;
+        }
+
+        if (context !== this.#context) {
+            this.#context = context;
+
+            this.#chains.bind(context.rows);
+
+            const waiting = this.#unregistered;
+
+            waiting.length = 0;
+
+            for (const entry of this.#entries.values()) {
+                // the old context's ids are void, and only forgotten
+                entry.skin_id = -1;
+                entry.context = null;
+
+                waiting.push(entry);
+            }
+        }
+
+        const waiting = this.#unregistered;
+
+        if (waiting.length === 0) {
+            return;
+        }
+
+        /*
+         An entry comes off the list before it is registered, so a registration that throws
+         cannot leave the ones before it queued for a second time — a mesh registered twice is
+         refused as a rebind, once a frame, for as long as the game runs. One that cannot be
+         registered is dropped with a message, and every other one goes ahead.
+        */
+        const entries = waiting.slice();
+
+        waiting.length = 0;
+
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+
+            try {
+                this.#register(entry, context);
+            } catch (e) {
+                console.error(`MeshSkinSystem: failed to register the skin of entity ${entry.entity}, dropping it`, e);
+            }
+        }
+    }
+
+    /**
+     * @param {Entry} entry
+     * @param {GPUSceneContext} context
+     */
+    #register(entry, context) {
+        const skin = entry.skin;
+        const joints = skin.joints;
+
+        if (!entry.held) {
+            for (let i = 0; i < joints.length; i++) {
+                this.#chains.hold(joints[i]);
+            }
+
+            entry.held = true;
+        }
+
+        const manager = context.animation_manager;
+
+        entry.skin_id = manager.register_skin(joints, skin.inverse_bind_matrices);
+        entry.context = context;
+
+        manager.bind_skin_mesh(entry.entity, entry.skin_id);
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#entries.delete(entity);
+
+        const waiting = this.#unregistered.indexOf(entry);
+
+        if (waiting !== -1) {
+            this.#unregistered.splice(waiting, 1);
+        }
+
+        // A context replaced by a restart took its ids with it; only the running one gets any back.
+        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
+            const manager = entry.context.animation_manager;
+
+            manager.unbind_skin_mesh(entity);
+            manager.unregister_skin(entry.skin_id);
+        }
+
+        entry.skin_id = -1;
+        entry.context = null;
+
+        if (entry.held) {
+            const joints = entry.skin.joints;
+
+            for (let i = 0; i < joints.length; i++) {
+                this.#chains.release(joints[i]);
+            }
+
+            entry.held = false;
+        }
+    }
+}