@woosh/meep-engine 3.43.0 → 3.45.0

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;
+        }
+    }
+}

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

@@ -1,23 +1,22 @@
 /**
- * Puts models into the scene as entities, and keeps their rows where the entities say.
+ * Loads models and spawns them as entities, so that a caller need not handle the loading lifecycle.
+ *
+ * **A shortcut, and nothing more.** Give an entity an {@link SGMesh} naming a file; when the file
+ * has loaded — whenever that is — the model appears under the entity as entities and components,
+ * and when the component goes, they go. Everything that makes the model work is those components,
+ * read by their own systems, exactly as if code had built them: `ShadedGeometry` draws through
+ * `ShadedGeometrySystem`, `MeshSkin` deforms through `MeshSkinSystem`, a `TransformAttachment`
+ * composes through `TransformAttachmentSystem`, and the `AnimationClips` on the entity play through
+ * `AnimationSystem` and `AnimationGraphSystem`. None of them knows this system exists, and this
+ * system puts nothing on the GPU itself.
  *
  * **A model is a prefab, and a placement is entities.** A loaded bundle is compiled once per url
- * ({@link prefab_compile}) and spawned once per entity that wears it
- * ({@link prefab_instantiate}): every node of the file becomes an entity attached to its parent's,
- * named, drawing where it draws, with the placing entity as the root. What used to be a private
- * copy of a node tree per placement is the dataset's own hierarchy, addressable by every system —
- * IK finds a foot by name, cloth seeds from joints, gameplay asks where a socket is — and the
- * renderer's tables are indexed by those entities, at `entity + 1`.
+ * ({@link prefab_compile}) and spawned once per entity that wears it ({@link prefab_instantiate}):
+ * every node of the file becomes an entity attached to its parent's, named, drawing where it draws,
+ * with the placing entity as the root.
  *
  * **It owns the scene and tells the facade to draw it**, rather than the facade handing a graph out
  * for anyone to write into.
- *
- * **Rows need a device, and registration does too.** A model loads whenever it loads, and there
- * may be no renderer yet; {@link update} attaches every instance's entities to the scene's GPU
- * context when one arrives, registers its skins with the animation manager, and does both again
- * after a renderer restart. Driving the clips is not this system's business — that is the
- * animation systems' — but a clip nothing has registered cannot be driven by anyone, which is why
- * the instance is handed out ({@link instance_of}) rather than kept.
  */
 export class MeshSystem extends System<any> {
     /**
@@ -32,12 +31,8 @@ export class MeshSystem extends System<any> {
      */
     get scene(): Scene;
     /**
-     * The model an entity is showing, as entities: its skins and clips addressed to them, and its
-     * nodes by name.
-     *
-     * Handed out rather than copied because an animation driver has to know *which* instance it is
-     * bound to: a model swap builds a new one, and a driver still holding the old one would be
-     * driving entities that have gone. The object's identity is the only signal that says so.
+     * The model an entity is showing, as entities: the prefab, and its node entities by index and by
+     * name. What loading produced — nothing a model needs in order to work is only here.
      *
      * **A model swap is remove-component then add-component.** Reassigning {@link SGMesh#url} on an
      * attached mesh is NOT one and is not observed: `link` reads the url once, the only other
@@ -51,19 +46,6 @@ export class MeshSystem extends System<any> {
      * whose model has not finished loading
      */
     instance_of(entity: number): PrefabInstance | null;
-    /**
-     * What the GPU's animation manager gave back for that instance — the skin ids, in the
-     * instance's own order.
-     *
-     * Same reasoning as {@link instance_of} and a stronger version of it: these ids belong to one
-     * renderer, and a restart voids every one of them. The object is replaced when that happens, so
-     * a driver that compares it against what it bound against notices in the same frame.
-     *
-     * @param {number} entity
-     * @returns {InstanceAnimationRegistration|null} `null` while there is nothing registered — no
-     * model yet, no device yet, or a renderer restart that has not been drained
-     */
-    animation_of(entity: number): InstanceAnimationRegistration | null;
     /**
      * The entities of an entity's model that draw — one per primitive of the file. Each holds the
      * `meshes` row `entity + 1`, which is what the visibility buffer writes for every pixel it
@@ -104,11 +86,9 @@ export class MeshSystem extends System<any> {
     unlink(model: SGMesh, transform: Transform64, entity: number): void;
     #private;
 }
-export type GPUSceneContext = import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
 export type SceneBundle = import("../../shade/renderer/loader/SceneBundle.js").SceneBundle;
 export type Prefab = import("./prefab/Prefab.js").Prefab;
 export type PrefabInstance = import("./prefab/PrefabInstance.js").PrefabInstance;
-export type InstanceAnimationRegistration = import("./register_instance_animation.js").InstanceAnimationRegistration;
 export type GraphicsEngine = import("./GraphicsEngine.js").GraphicsEngine;
 import { System } from "../ecs/System.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";

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

@@ -1 +1 @@
-{"version":3,"file":"MeshSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/MeshSystem.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAqEI;;;;OAIG;IACH,sBAJW,cAAc,SACd,KAAK,eACI,MAAM,KAAG,QAAQ,WAAW,CAAC,EAchD;IADG,qDAAyC;IAG7C;;OAEG;IACH,mBAEC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,oBAJW,MAAM,GACJ,cAAc,GAAC,IAAI,CAW/B;IAED;;;;;;;;;;;OAWG;IACH,qBAJW,MAAM,GACJ,6BAA6B,GAAC,IAAI,CAW9C;IAED;;;;;;;;OAQG;IACH,yBAJW,MAAM,GACJ,UAAU,CAWtB;IAED;;;;;;;;;;;;OAYG;IACH,6BALW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,UACvC,MAAM,GACJ,OAAO,CAwCnB;IAED,2CAeC;IAED,4CASC;IAuID;;;;OAIG;IACH,YAJW,MAAM,aACN,WAAW,UACX,MAAM,QAgChB;IAED;;;;OAIG;IACH,cAJW,MAAM,aACN,WAAW,UACX,MAAM,QAIhB;;CAgJJ;8BAtpBY,OAAO,+CAA+C,EAAE,eAAe;0BACvE,OAAO,4CAA4C,EAAE,WAAW;qBAChE,OAAO,oBAAoB,EAAE,MAAM;6BACnC,OAAO,4BAA4B,EAAE,cAAc;4CACnD,OAAO,kCAAkC,EAAE,6BAA6B;6BACxE,OAAO,qBAAqB,EAAE,cAAc;uBAnBlC,kBAAkB;4BACb,iCAAiC;uBAItC,6CAA6C;sBAN9C,qCAAqC"}
+{"version":3,"file":"MeshSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/MeshSystem.js"],"names":[],"mappings":"AAiDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAmDI;;;;OAIG;IACH,sBAJW,cAAc,SACd,KAAK,eACI,MAAM,KAAG,QAAQ,WAAW,CAAC,EAchD;IADG,qDAAyC;IAG7C;;OAEG;IACH,mBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,oBAJW,MAAM,GACJ,cAAc,GAAC,IAAI,CAW/B;IAED;;;;;;;;OAQG;IACH,yBAJW,MAAM,GACJ,UAAU,CAWtB;IAED;;;;;;;;;;;;OAYG;IACH,6BALW,UAAU,MAAM,CAAC,GAAC,MAAM,EAAE,GAAC,YAAY,UACvC,MAAM,GACJ,OAAO,CAwCnB;IAED,2CAeC;IAED,4CAMC;IA8BD;;;;OAIG;IACH,YAJW,MAAM,aACN,WAAW,UACX,MAAM,QAkBhB;IAED;;;;OAIG;IACH,cAJW,MAAM,aACN,WAAW,UACX,MAAM,QAIhB;;CA8EJ;0BAvYY,OAAO,4CAA4C,EAAE,WAAW;qBAChE,OAAO,oBAAoB,EAAE,MAAM;6BACnC,OAAO,4BAA4B,EAAE,cAAc;6BACnD,OAAO,qBAAqB,EAAE,cAAc;uBAXlC,kBAAkB;4BACb,iCAAiC;uBAEtC,6CAA6C;sBAJ9C,qCAAqC"}