@woosh/meep-engine 3.1.0 → 3.3.0

package/src/engine/graphics3/MeshSystem3.js

@@ -1,646 +1,646 @@
-import { assert } from "../../core/assert.js";
-import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
-import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
-import { Scene } from "../../shade/renderer/scene/Scene.js";
-import { instantiate_scene_bundle } from "./instantiate_scene_bundle.js";
-import {
-    register_instance_animation,
-    unregister_instance_animation
-} from "./register_instance_animation.js";
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { t64_copy_from_transform } from "../ecs/transform/t64_copy_from_transform.js";
-import { ParentEntity } from "../ecs/parent/ParentEntity.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
-import { shade_bundle_to_entity_composition } from "./shade_node_to_entity_composition.js";
-
-/**
- * Puts entities into Shade's scene and keeps them where the ECS says they are.
- *
- * **It owns the scene and tells the facade to draw it**, rather than the facade handing a graph out
- * for anyone to write into — that coupling is what §2.1 retires along with `GraphicsEngine.scene`.
- *
- * Placement is a `Transform` copied into `Node3D.transform_local`, through
- * {@link t64_copy_from_transform} because the node's transform is a `Transform64` since S2 and the
- * two types stay deliberately distinct. `transform_global` is **derived** — `updateMatrices`
- * recomputes it from the local transform and the parent chain — so writing it directly would be
- * undone by the next refresh, and the entity is placed through the local one.
- *
- * What makes this affordable is S1: the scene database takes row-level updates, so moving one
- * entity writes one row. Nothing here rebuilds anything.
- *
- * **It also hands each instance to the GPU's animation manager** ({@link update}), because it is
- * what builds instances and therefore the only thing that knows when one exists. Driving those
- * clips is not its business — that is the animation systems' — but a clip nothing has registered
- * cannot be driven by anyone.
- */
-export class MeshSystem3 extends System {
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * The scene this system writes into and the facade draws.
-     *
-     * Received rather than created: lights come from a system of their own, and both have to be
-     * putting content into the same scene for either to be visible.
-     *
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     * Loaded model bundles, by url. A level places the same model many times over, and loading it
-     * once per placement would be the dominant cost of opening one.
-     *
-     * @type {Map<string, Promise<SceneBundle>>}
-     */
-    #bundles = new Map();
-
-    /**
-     * What each entity has in the scene, and the signal bindings keeping it in step.
-     *
-     * `instance` and `animation` are null until the model has loaded and until the GPU has been
-     * told about it respectively — two different waits, which is why they are two fields.
-     *
-     * @type {Map<number, {nodes: Node3D[], bindings: SignalBinding[], instance: SceneBundleInstance|null, animation: InstanceAnimationRegistration|null}>}
-     */
-    #entries = new Map();
-
-    /**
-     * Shade's GPU state for {@link scene}, as of the last {@link update}.
-     *
-     * Held to answer one question: has the renderer been replaced since the last frame, so that
-     * everything placed has to be registered again. **Which manager a particular registration
-     * belongs to is the registration's own to say** — it carries the context that issued it — so
-     * this is not consulted when ids are handed back.
-     *
-     * @type {GPUSceneContext|null}
-     */
-    #context = null;
-
-    /**
-     * Entries whose instance is not registered with {@link #context} — either because it has just
-     * loaded, or because a restart invalidated what it had.
-     *
-     * A queue rather than a scan over every entity, because this is per-frame work in a level that
-     * places hundreds of models and the answer is almost always "nothing to do".
-     *
-     * @type {object[]}
-     */
-    #unregistered = [];
-
-    /**
-     * Entities whose `SGMesh` carried no url when it was linked.
-     *
-     * `SGMesh.url` is an accessor with no change signal behind it, and the game assigns it late as a
-     * matter of
-     * course: `GeneratedArmySystem` puts the component on an army entity and fills the url in from
-     * a promise, once the army it generated has picked the leader whose model the army wears. So a
-     * url that is missing at link time is the normal path to a model rather than an edge case, and
-     * the only way to notice one arriving is to look again.
-     *
-     * A list rather than a scan over every entity, and it is short: it holds only what has no model
-     * yet, and an entry leaves it for good the moment one is asked for.
-     *
-     * @type {{entity: number, model: SGMesh, transform: Transform}[]}
-     */
-    #awaiting_url = [];
-
-    /**
-     * Loads a glTF into Shade's own representation. Injected rather than imported so that the
-     * system can be driven in a spec without a network or a device — the loader is the one genuine
-     * boundary here.
-     *
-     * @type {function(string): Promise<SceneBundle>}
-     */
-    #load;
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {Scene} scene
-     * @param {function(string): Promise<SceneBundle>} load
-     */
-    constructor(graphics, scene, load) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-        assert.typeOf(load, 'function', 'load');
-
-        this.#graphics = graphics;
-        this.#scene = scene;
-        this.#load = load;
-
-        this.dependencies = [SGMesh, Transform];
-    }
-
-    /**
-     * @returns {Scene}
-     */
-    get scene() {
-        return this.#scene;
-    }
-
-    /**
-     * Visit every node of an entity's model that carries geometry.
-     *
-     * The nodes are what the scene database keys on, so anything that has to say something about a
-     * particular entity's meshes — which rows they occupy, which of them the visibility buffer will
-     * name — starts here. A grouping node is skipped, because it has no geometry and therefore no
-     * row of its own.
-     *
-     * @param {number} entity
-     * @param {function(SGMesh): void} visitor
-     * @returns {boolean} `false` when the entity has nothing in the scene — never seen, or still
-     * loading, and neither is an error
-     */
-    traverse_meshes(entity, visitor) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return false;
-        }
-
-        for (let i = 0; i < entry.nodes.length; i++) {
-            entry.nodes[i].traverse(node => {
-                if (node.isMesh === true) {
-                    visitor(node);
-                }
-            });
-        }
-
-        this.#traverse_expanded(entry, visitor);
-
-        return true;
-    }
-
-    /**
-     * The rows of a model that became entities.
-     *
-     * Its primitives are components on descendants rather than nodes this system holds, and each one
-     * carries the row `ShadedGeometrySystem3` put it in — so the walk is over the composition and the
-     * answer is the same kind of node the instance path yields. A primitive whose system has not
-     * linked it yet has no row and contributes nothing, which is the same "still loading" silence
-     * every reader here already tolerates.
-     *
-     * @param {object} entry
-     * @param {function(Mesh): void} visitor
-     */
-    #traverse_expanded(entry, visitor) {
-        const composition = entry.composition;
-
-        if (composition === null) {
-            return;
-        }
-
-        composition.traverse(node => {
-            const geometry = node.entity.getComponent(ShadedGeometry);
-
-            if (geometry === null || geometry === undefined) {
-                return;
-            }
-
-            if (geometry.node === null) {
-                return;
-            }
-
-            visitor(geometry.node);
-        });
-    }
-
-    /**
-     * The private copy of the model an entity is showing — its clips among other things, which is
-     * where their names and their durations come from.
-     *
-     * 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 nodes that left the scene. The object's identity is the only signal that says so.
-     *
-     * @param {number} entity
-     * @returns {SceneBundleInstance|null} `null` for an entity this system has never seen, or one
-     * whose model has not finished loading
-     */
-    instance_of(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return null;
-        }
-
-        return entry.instance;
-    }
-
-    /**
-     * What the GPU's animation manager gave back for that instance — the skin and clip 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) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return null;
-        }
-
-        return entry.animation;
-    }
-
-    /**
-     * Where an entity's model is, in world space.
-     *
-     * This is what makes picking possible without a second copy of the geometry: Shade already keeps
-     * a world bounding box per mesh, refreshed as part of the `updateMatrices` that places it, so the
-     * answer is a walk over what the entity has in the scene and nothing is recomputed.
-     *
-     * @param {ArrayLike<number>|number[]|Float32Array} target aabb3, order `x0,y0,z0,x1,y1,z1`
-     * @param {number} entity
-     * @returns {boolean} `false` when the entity has nothing in the scene — it may be an entity this
-     * system has never seen, or one whose model is still loading, and neither is an error
-     */
-    compute_world_bounds(target, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return false;
-        }
-
-        let found = false;
-
-        /**
-         * @param {Mesh} node
-         */
-        const combine = node => {
-            const bounds = node.bounding_box;
-
-            // combining the first box with itself is how it lands in `target` — one operation
-            // for both cases, rather than a copy that only ever runs once
-            aabb3_array_combine(target, 0, found ? target : bounds, 0, bounds, 0);
-
-            found = true;
-        };
-
-        for (let i = 0; i < entry.nodes.length; i++) {
-            entry.nodes[i].traverse(node => {
-                if (node.isMesh !== true) {
-                    // a grouping node carries no geometry, so it has no bounds of its own
-                    return;
-                }
-
-                combine(node);
-            });
-        }
-
-        this.#traverse_expanded(entry, combine);
-
-        return found;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#graphics.set_scene(this.#scene);
-    }
-
-    async shutdown(entityManager) {
-        for (const entity of Array.from(this.#entries.keys())) {
-            this.#drop(entity);
-        }
-
-        this.#bundles.clear();
-
-        this.#context = null;
-        this.#unregistered.length = 0;
-    }
-
-    /**
-     * Tell the GPU about the models that have arrived since the last frame.
-     *
-     * **This is where an instance's skins and clips reach `GPUAnimationManager`** — the manager
-     * hangs off the scene's GPU context, which exists only while there is a device, so registration
-     * cannot happen where instances are built (a model loads whenever it loads, including before
-     * the renderer has started). Registration is documented eventually-consistent at both entry
-     * points, so a frame of latency here costs nothing: the ids are live immediately and the chains
-     * that drive deformation are built when every joint has a row.
-     *
-     * A restart is the same event seen from here: the context object changes, every id the old one
-     * issued is void, and everything currently placed queues up again.
-     *
-     * @param {number} time_delta_seconds
-     */
-    update(time_delta_seconds) {
-        this.#collect_arrived_urls();
-
-        const context = this.#graphics.scene_context(this.#scene);
-
-        if (context === null) {
-            // No device — before the first start, or after a stop. Nothing is registered while
-            // this holds, and the next context to arrive is a change like any other.
-            return;
-        }
-
-        if (context !== this.#context) {
-            this.#invalidate_registrations(context);
-        }
-
-        const waiting = this.#unregistered;
-
-        if (waiting.length === 0) {
-            return;
-        }
-
-        /*
-         **A throw in here does not cost one model, it costs the session.** The list is cleared after
-         the loop, so a registration that throws partway leaves the entries before it *already
-         registered* and *still queued*: the next update registers them a second time, `bind` finds
-         the mesh already bound to another skin, and that assertion then fires once a frame for as
-         long as the game runs. Meanwhile the entry that threw never gets an `animation`, so `#drop`
-         has nothing to give back and its skinning bindings outlive their model — which is how a
-         `SkinnedMesh` ends up with no meshes-table row a hundred frames later.
-
-         Seen for real: a second skinned model arriving in one frame used to overrun the meshlet
-         buffers while a clone was queued (fixed in `GPUMeshletManager`), and the cascade above is
-         what turned that one throw into a dead animation layer. Registering one entry at a time and
-         taking it off the list as it succeeds is the shape of the fix; what to do with an entry that
-         *cannot* be registered is the open question, which is why this is a candidate in
-         MEEP3/LEDGER.md rather than a change.
-        */
-        for (let i = 0; i < waiting.length; i++) {
-            const entry = waiting[i];
-
-            entry.animation = register_instance_animation(context, entry.instance);
-        }
-
-        waiting.length = 0;
-    }
-
-    /**
-     * Load the models of entities whose url has turned up since the last frame.
-     *
-     * Ahead of everything the device gates, because a model arrives whenever it arrives and there
-     * may be no renderer yet — the same bargain {@link #attach} makes with registration.
-     */
-    #collect_arrived_urls() {
-        const waiting = this.#awaiting_url;
-
-        for (let i = waiting.length - 1; i >= 0; i--) {
-            const pending = waiting[i];
-
-            if (pending.model.url === null) {
-                continue;
-            }
-
-            waiting.splice(i, 1);
-
-            this.#attach(pending.entity, pending.model.url, pending.transform);
-        }
-    }
-
-    /**
-     * A different renderer is drawing this scene now, so nothing that has been registered still is.
-     *
-     * @param {GPUSceneContext} context
-     */
-    #invalidate_registrations(context) {
-        this.#context = context;
-
-        const waiting = this.#unregistered;
-
-        waiting.length = 0;
-
-        for (const entry of this.#entries.values()) {
-            if (entry.instance === null) {
-                continue;
-            }
-
-            entry.animation = null;
-
-            waiting.push(entry);
-        }
-    }
-
-    /**
-     * @param {SGMesh} model
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(model, transform, entity) {
-        const entry = { nodes: [], bindings: [], instance: null, animation: null, composition: null };
-
-        this.#entries.set(entity, entry);
-
-        // The entity is placed the moment its transform moves, not on a poll: a transform that has
-        // not changed costs nothing, which is the same bargain the scene database makes downstream.
-        const place = () => this.#place(entity, transform);
-
-        for (const component of [transform.position, transform.rotation, transform.scale]) {
-            const binding = new SignalBinding(component.onChanged, place);
-
-            binding.link();
-
-            entry.bindings.push(binding);
-        }
-
-        if (model.url === null) {
-            // nothing to show yet; {@link update} watches for the url arriving
-            this.#awaiting_url.push({ entity, model, transform });
-
-            return;
-        }
-
-        this.#attach(entity, model.url, transform);
-    }
-
-    /**
-     * @param {SGMesh} model
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(model, transform, entity) {
-        this.#drop(entity);
-    }
-
-    /**
-     * Load the model if it has not been seen, then put a copy of it in the scene.
-     *
-     * @param {number} entity
-     * @param {string} url
-     * @param {Transform} transform
-     */
-    async #attach(entity, url, transform) {
-        /*
-         Which entry this load is for, decided before the wait rather than after it. A load is in
-         flight for as long as a fetch and a decode take, and the entity can leave and come back
-         inside that window — so asking `#entries` afterwards answers "the entry this entity has
-         now", which may be a different one. Attaching to that leaves the scene holding a second
-         model nothing owns, and its skins registered with the GPU under a record that has already
-         been overwritten.
-        */
-        const started_for = this.#entries.get(entity);
-
-        let bundle = this.#bundles.get(url);
-
-        if (bundle === undefined) {
-            bundle = this.#load(url);
-
-            this.#bundles.set(url, bundle);
-        }
-
-        const loaded = await bundle;
-
-        const entry = this.#entries.get(entity);
-
-        if (entry !== started_for) {
-            // the entity left while its model was in flight, or left and came back as another
-            // entry — both ordinary at level-load rates
-            return;
-        }
-
-        if (loaded.skins.length === 0 && loaded.clips.length === 0) {
-            this.#expand(entity, loaded, transform);
-
-            return;
-        }
-
-        const instance = instantiate_scene_bundle(loaded);
-
-        entry.instance = instance;
-
-        for (const node of instance.roots) {
-            entry.nodes.push(node);
-
-            this.#scene.add(node);
-        }
-
-        this.#place(entity, transform);
-
-        // The GPU hears about it on the next update rather than here: a model finishes loading
-        // whenever it finishes, and there may be no device to tell.
-        this.#unregistered.push(entry);
-    }
-
-    /**
-     * Put a model into the dataset as entities.
-     *
-     * **This is what placing a model means in an ECS** (D47): meep has no scene graph to hand a file
-     * to, so the file's nodes become entities — parented, named, placed, and carrying a
-     * `ShadedGeometry` where they draw — and `ShadedGeometrySystem3` gives each of those a row.
-     * Nothing here touches the scene, and no copy of the model is made: the entities name the
-     * bundle's own geometry and material, so a model placed two hundred times is one of each.
-     *
-     * **Only a model that neither deforms nor animates comes this way.** A skinned one deforms
-     * against a skeleton the renderer owns and the GPU poses; an animated one has clips that drive
-     * the nodes of an instance, and `GPUAnimationManager` addresses those nodes rather than
-     * entities. Making joints entities, or moving playback onto entity transforms, are both designs
-     * outside this program (D47) — so anything with a skin or a clip keeps the instance path above,
-     * exactly as Phase 4 built it.
-     *
-     * @param {number} entity
-     * @param {SceneBundle} bundle
-     * @param {Transform} transform
-     */
-    #expand(entity, bundle, transform) {
-        const entry = this.#entries.get(entity);
-
-        const composition = shade_bundle_to_entity_composition(bundle);
-
-        composition.entity.add(ParentEntity.from(entity));
-
-        const follow = () => composition.transform.copy(transform);
-
-        follow();
-
-        composition.build(this.entityManager.dataset);
-
-        transform.subscribe(follow);
-
-        composition.on.destroyed.addOne(() => transform.unsubscribe(follow));
-
-        entry.composition = composition;
-    }
-
-    /**
-     * @param {number} entity
-     * @param {Transform} transform
-     */
-    #place(entity, transform) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        const nodes = entry.nodes;
-
-        for (let i = 0; i < nodes.length; i++) {
-            const node = nodes[i];
-
-            t64_copy_from_transform(node.transform_local, transform);
-
-            // recomputes transform_global down the subtree, and bumps the version the scene
-            // database reads to decide what to upload
-            node.updateMatrices();
-        }
-    }
-
-    /**
-     * @param {number} entity
-     */
-    #drop(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        for (let i = 0; i < entry.bindings.length; i++) {
-            entry.bindings[i].unlink();
-        }
-
-        for (let i = 0; i < entry.nodes.length; i++) {
-            this.#scene.remove(entry.nodes[i]);
-        }
-
-        if (entry.composition !== null) {
-            // the entities the model became are the model, so they go with it
-            entry.composition.destroy();
-
-            entry.composition = null;
-        }
-
-        const waiting = this.#unregistered.indexOf(entry);
-
-        if (waiting !== -1) {
-            // it left before the GPU was ever told about it
-            this.#unregistered.splice(waiting, 1);
-        }
-
-        const awaiting = this.#awaiting_url.findIndex(pending => pending.entity === entity);
-
-        if (awaiting !== -1) {
-            // it left before it ever had a model to load
-            this.#awaiting_url.splice(awaiting, 1);
-        }
-
-        const registration = entry.animation;
-
-        if (registration !== null) {
-            if (this.#graphics.scene_context(this.#scene) === registration.context) {
-                unregister_instance_animation(registration);
-            }
-
-            entry.animation = null;
-        }
-
-        this.#entries.delete(entity);
-    }
-}
+import { assert } from "../../core/assert.js";
+import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
+import { SignalBinding } from "../../core/events/signal/SignalBinding.js";
+import { Scene } from "../../shade/renderer/scene/Scene.js";
+import { instantiate_scene_bundle } from "./instantiate_scene_bundle.js";
+import {
+    register_instance_animation,
+    unregister_instance_animation
+} from "./register_instance_animation.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { t64_copy_from_transform } from "../ecs/transform/t64_copy_from_transform.js";
+import { ParentEntity } from "../ecs/parent/ParentEntity.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
+import { shade_bundle_to_entity_composition } from "./shade_node_to_entity_composition.js";
+
+/**
+ * Puts entities into Shade's scene and keeps them where the ECS says they are.
+ *
+ * **It owns the scene and tells the facade to draw it**, rather than the facade handing a graph out
+ * for anyone to write into — that coupling is what §2.1 retires along with `GraphicsEngine.scene`.
+ *
+ * Placement is a `Transform` copied into `Node3D.transform_local`, through
+ * {@link t64_copy_from_transform} because the node's transform is a `Transform64` since S2 and the
+ * two types stay deliberately distinct. `transform_global` is **derived** — `updateMatrices`
+ * recomputes it from the local transform and the parent chain — so writing it directly would be
+ * undone by the next refresh, and the entity is placed through the local one.
+ *
+ * What makes this affordable is S1: the scene database takes row-level updates, so moving one
+ * entity writes one row. Nothing here rebuilds anything.
+ *
+ * **It also hands each instance to the GPU's animation manager** ({@link update}), because it is
+ * what builds instances and therefore the only thing that knows when one exists. Driving those
+ * clips is not its business — that is the animation systems' — but a clip nothing has registered
+ * cannot be driven by anyone.
+ */
+export class MeshSystem3 extends System {
+    /**
+     * @type {GraphicsEngine3}
+     */
+    #graphics;
+
+    /**
+     * The scene this system writes into and the facade draws.
+     *
+     * Received rather than created: lights come from a system of their own, and both have to be
+     * putting content into the same scene for either to be visible.
+     *
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * Loaded model bundles, by url. A level places the same model many times over, and loading it
+     * once per placement would be the dominant cost of opening one.
+     *
+     * @type {Map<string, Promise<SceneBundle>>}
+     */
+    #bundles = new Map();
+
+    /**
+     * What each entity has in the scene, and the signal bindings keeping it in step.
+     *
+     * `instance` and `animation` are null until the model has loaded and until the GPU has been
+     * told about it respectively — two different waits, which is why they are two fields.
+     *
+     * @type {Map<number, {nodes: Node3D[], bindings: SignalBinding[], instance: SceneBundleInstance|null, animation: InstanceAnimationRegistration|null}>}
+     */
+    #entries = new Map();
+
+    /**
+     * Shade's GPU state for {@link scene}, as of the last {@link update}.
+     *
+     * Held to answer one question: has the renderer been replaced since the last frame, so that
+     * everything placed has to be registered again. **Which manager a particular registration
+     * belongs to is the registration's own to say** — it carries the context that issued it — so
+     * this is not consulted when ids are handed back.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    #context = null;
+
+    /**
+     * Entries whose instance is not registered with {@link #context} — either because it has just
+     * loaded, or because a restart invalidated what it had.
+     *
+     * A queue rather than a scan over every entity, because this is per-frame work in a level that
+     * places hundreds of models and the answer is almost always "nothing to do".
+     *
+     * @type {object[]}
+     */
+    #unregistered = [];
+
+    /**
+     * Entities whose `SGMesh` carried no url when it was linked.
+     *
+     * `SGMesh.url` is an accessor with no change signal behind it, and the game assigns it late as a
+     * matter of
+     * course: `GeneratedArmySystem` puts the component on an army entity and fills the url in from
+     * a promise, once the army it generated has picked the leader whose model the army wears. So a
+     * url that is missing at link time is the normal path to a model rather than an edge case, and
+     * the only way to notice one arriving is to look again.
+     *
+     * A list rather than a scan over every entity, and it is short: it holds only what has no model
+     * yet, and an entry leaves it for good the moment one is asked for.
+     *
+     * @type {{entity: number, model: SGMesh, transform: Transform}[]}
+     */
+    #awaiting_url = [];
+
+    /**
+     * Loads a glTF into Shade's own representation. Injected rather than imported so that the
+     * system can be driven in a spec without a network or a device — the loader is the one genuine
+     * boundary here.
+     *
+     * @type {function(string): Promise<SceneBundle>}
+     */
+    #load;
+
+    /**
+     * @param {GraphicsEngine3} graphics
+     * @param {Scene} scene
+     * @param {function(string): Promise<SceneBundle>} load
+     */
+    constructor(graphics, scene, load) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+        assert.typeOf(load, 'function', 'load');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+        this.#load = load;
+
+        this.dependencies = [SGMesh, Transform];
+    }
+
+    /**
+     * @returns {Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    /**
+     * Visit every node of an entity's model that carries geometry.
+     *
+     * The nodes are what the scene database keys on, so anything that has to say something about a
+     * particular entity's meshes — which rows they occupy, which of them the visibility buffer will
+     * name — starts here. A grouping node is skipped, because it has no geometry and therefore no
+     * row of its own.
+     *
+     * @param {number} entity
+     * @param {function(SGMesh): void} visitor
+     * @returns {boolean} `false` when the entity has nothing in the scene — never seen, or still
+     * loading, and neither is an error
+     */
+    traverse_meshes(entity, visitor) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return false;
+        }
+
+        for (let i = 0; i < entry.nodes.length; i++) {
+            entry.nodes[i].traverse(node => {
+                if (node.isMesh === true) {
+                    visitor(node);
+                }
+            });
+        }
+
+        this.#traverse_expanded(entry, visitor);
+
+        return true;
+    }
+
+    /**
+     * The rows of a model that became entities.
+     *
+     * Its primitives are components on descendants rather than nodes this system holds, and each one
+     * carries the row `ShadedGeometrySystem3` put it in — so the walk is over the composition and the
+     * answer is the same kind of node the instance path yields. A primitive whose system has not
+     * linked it yet has no row and contributes nothing, which is the same "still loading" silence
+     * every reader here already tolerates.
+     *
+     * @param {object} entry
+     * @param {function(Mesh): void} visitor
+     */
+    #traverse_expanded(entry, visitor) {
+        const composition = entry.composition;
+
+        if (composition === null) {
+            return;
+        }
+
+        composition.traverse(node => {
+            const geometry = node.entity.getComponent(ShadedGeometry);
+
+            if (geometry === null || geometry === undefined) {
+                return;
+            }
+
+            if (geometry.node === null) {
+                return;
+            }
+
+            visitor(geometry.node);
+        });
+    }
+
+    /**
+     * The private copy of the model an entity is showing — its clips among other things, which is
+     * where their names and their durations come from.
+     *
+     * 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 nodes that left the scene. The object's identity is the only signal that says so.
+     *
+     * @param {number} entity
+     * @returns {SceneBundleInstance|null} `null` for an entity this system has never seen, or one
+     * whose model has not finished loading
+     */
+    instance_of(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return null;
+        }
+
+        return entry.instance;
+    }
+
+    /**
+     * What the GPU's animation manager gave back for that instance — the skin and clip 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) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return null;
+        }
+
+        return entry.animation;
+    }
+
+    /**
+     * Where an entity's model is, in world space.
+     *
+     * This is what makes picking possible without a second copy of the geometry: Shade already keeps
+     * a world bounding box per mesh, refreshed as part of the `updateMatrices` that places it, so the
+     * answer is a walk over what the entity has in the scene and nothing is recomputed.
+     *
+     * @param {ArrayLike<number>|number[]|Float32Array} target aabb3, order `x0,y0,z0,x1,y1,z1`
+     * @param {number} entity
+     * @returns {boolean} `false` when the entity has nothing in the scene — it may be an entity this
+     * system has never seen, or one whose model is still loading, and neither is an error
+     */
+    compute_world_bounds(target, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return false;
+        }
+
+        let found = false;
+
+        /**
+         * @param {Mesh} node
+         */
+        const combine = node => {
+            const bounds = node.bounding_box;
+
+            // combining the first box with itself is how it lands in `target` — one operation
+            // for both cases, rather than a copy that only ever runs once
+            aabb3_array_combine(target, 0, found ? target : bounds, 0, bounds, 0);
+
+            found = true;
+        };
+
+        for (let i = 0; i < entry.nodes.length; i++) {
+            entry.nodes[i].traverse(node => {
+                if (node.isMesh !== true) {
+                    // a grouping node carries no geometry, so it has no bounds of its own
+                    return;
+                }
+
+                combine(node);
+            });
+        }
+
+        this.#traverse_expanded(entry, combine);
+
+        return found;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#graphics.set_scene(this.#scene);
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+
+        this.#bundles.clear();
+
+        this.#context = null;
+        this.#unregistered.length = 0;
+    }
+
+    /**
+     * Tell the GPU about the models that have arrived since the last frame.
+     *
+     * **This is where an instance's skins and clips reach `GPUAnimationManager`** — the manager
+     * hangs off the scene's GPU context, which exists only while there is a device, so registration
+     * cannot happen where instances are built (a model loads whenever it loads, including before
+     * the renderer has started). Registration is documented eventually-consistent at both entry
+     * points, so a frame of latency here costs nothing: the ids are live immediately and the chains
+     * that drive deformation are built when every joint has a row.
+     *
+     * A restart is the same event seen from here: the context object changes, every id the old one
+     * issued is void, and everything currently placed queues up again.
+     *
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        this.#collect_arrived_urls();
+
+        const context = this.#graphics.scene_context(this.#scene);
+
+        if (context === null) {
+            // No device — before the first start, or after a stop. Nothing is registered while
+            // this holds, and the next context to arrive is a change like any other.
+            return;
+        }
+
+        if (context !== this.#context) {
+            this.#invalidate_registrations(context);
+        }
+
+        const waiting = this.#unregistered;
+
+        if (waiting.length === 0) {
+            return;
+        }
+
+        /*
+         **A throw in here does not cost one model, it costs the session.** The list is cleared after
+         the loop, so a registration that throws partway leaves the entries before it *already
+         registered* and *still queued*: the next update registers them a second time, `bind` finds
+         the mesh already bound to another skin, and that assertion then fires once a frame for as
+         long as the game runs. Meanwhile the entry that threw never gets an `animation`, so `#drop`
+         has nothing to give back and its skinning bindings outlive their model — which is how a
+         `SkinnedMesh` ends up with no meshes-table row a hundred frames later.
+
+         Seen for real: a second skinned model arriving in one frame used to overrun the meshlet
+         buffers while a clone was queued (fixed in `GPUMeshletManager`), and the cascade above is
+         what turned that one throw into a dead animation layer. Registering one entry at a time and
+         taking it off the list as it succeeds is the shape of the fix; what to do with an entry that
+         *cannot* be registered is the open question, which is why this is a candidate in
+         MEEP3/LEDGER.md rather than a change.
+        */
+        for (let i = 0; i < waiting.length; i++) {
+            const entry = waiting[i];
+
+            entry.animation = register_instance_animation(context, entry.instance);
+        }
+
+        waiting.length = 0;
+    }
+
+    /**
+     * Load the models of entities whose url has turned up since the last frame.
+     *
+     * Ahead of everything the device gates, because a model arrives whenever it arrives and there
+     * may be no renderer yet — the same bargain {@link #attach} makes with registration.
+     */
+    #collect_arrived_urls() {
+        const waiting = this.#awaiting_url;
+
+        for (let i = waiting.length - 1; i >= 0; i--) {
+            const pending = waiting[i];
+
+            if (pending.model.url === null) {
+                continue;
+            }
+
+            waiting.splice(i, 1);
+
+            this.#attach(pending.entity, pending.model.url, pending.transform);
+        }
+    }
+
+    /**
+     * A different renderer is drawing this scene now, so nothing that has been registered still is.
+     *
+     * @param {GPUSceneContext} context
+     */
+    #invalidate_registrations(context) {
+        this.#context = context;
+
+        const waiting = this.#unregistered;
+
+        waiting.length = 0;
+
+        for (const entry of this.#entries.values()) {
+            if (entry.instance === null) {
+                continue;
+            }
+
+            entry.animation = null;
+
+            waiting.push(entry);
+        }
+    }
+
+    /**
+     * @param {SGMesh} model
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(model, transform, entity) {
+        const entry = { nodes: [], bindings: [], instance: null, animation: null, composition: null };
+
+        this.#entries.set(entity, entry);
+
+        // The entity is placed the moment its transform moves, not on a poll: a transform that has
+        // not changed costs nothing, which is the same bargain the scene database makes downstream.
+        const place = () => this.#place(entity, transform);
+
+        for (const component of [transform.position, transform.rotation, transform.scale]) {
+            const binding = new SignalBinding(component.onChanged, place);
+
+            binding.link();
+
+            entry.bindings.push(binding);
+        }
+
+        if (model.url === null) {
+            // nothing to show yet; {@link update} watches for the url arriving
+            this.#awaiting_url.push({ entity, model, transform });
+
+            return;
+        }
+
+        this.#attach(entity, model.url, transform);
+    }
+
+    /**
+     * @param {SGMesh} model
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(model, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * Load the model if it has not been seen, then put a copy of it in the scene.
+     *
+     * @param {number} entity
+     * @param {string} url
+     * @param {Transform} transform
+     */
+    async #attach(entity, url, transform) {
+        /*
+         Which entry this load is for, decided before the wait rather than after it. A load is in
+         flight for as long as a fetch and a decode take, and the entity can leave and come back
+         inside that window — so asking `#entries` afterwards answers "the entry this entity has
+         now", which may be a different one. Attaching to that leaves the scene holding a second
+         model nothing owns, and its skins registered with the GPU under a record that has already
+         been overwritten.
+        */
+        const started_for = this.#entries.get(entity);
+
+        let bundle = this.#bundles.get(url);
+
+        if (bundle === undefined) {
+            bundle = this.#load(url);
+
+            this.#bundles.set(url, bundle);
+        }
+
+        const loaded = await bundle;
+
+        const entry = this.#entries.get(entity);
+
+        if (entry !== started_for) {
+            // the entity left while its model was in flight, or left and came back as another
+            // entry — both ordinary at level-load rates
+            return;
+        }
+
+        if (loaded.skins.length === 0 && loaded.clips.length === 0) {
+            this.#expand(entity, loaded, transform);
+
+            return;
+        }
+
+        const instance = instantiate_scene_bundle(loaded);
+
+        entry.instance = instance;
+
+        for (const node of instance.roots) {
+            entry.nodes.push(node);
+
+            this.#scene.add(node);
+        }
+
+        this.#place(entity, transform);
+
+        // The GPU hears about it on the next update rather than here: a model finishes loading
+        // whenever it finishes, and there may be no device to tell.
+        this.#unregistered.push(entry);
+    }
+
+    /**
+     * Put a model into the dataset as entities.
+     *
+     * **This is what placing a model means in an ECS** (D47): meep has no scene graph to hand a file
+     * to, so the file's nodes become entities — parented, named, placed, and carrying a
+     * `ShadedGeometry` where they draw — and `ShadedGeometrySystem3` gives each of those a row.
+     * Nothing here touches the scene, and no copy of the model is made: the entities name the
+     * bundle's own geometry and material, so a model placed two hundred times is one of each.
+     *
+     * **Only a model that neither deforms nor animates comes this way.** A skinned one deforms
+     * against a skeleton the renderer owns and the GPU poses; an animated one has clips that drive
+     * the nodes of an instance, and `GPUAnimationManager` addresses those nodes rather than
+     * entities. Making joints entities, or moving playback onto entity transforms, are both designs
+     * outside this program (D47) — so anything with a skin or a clip keeps the instance path above,
+     * exactly as Phase 4 built it.
+     *
+     * @param {number} entity
+     * @param {SceneBundle} bundle
+     * @param {Transform} transform
+     */
+    #expand(entity, bundle, transform) {
+        const entry = this.#entries.get(entity);
+
+        const composition = shade_bundle_to_entity_composition(bundle);
+
+        composition.entity.add(ParentEntity.from(entity));
+
+        const follow = () => composition.transform.copy(transform);
+
+        follow();
+
+        composition.build(this.entityManager.dataset);
+
+        transform.subscribe(follow);
+
+        composition.on.destroyed.addOne(() => transform.unsubscribe(follow));
+
+        entry.composition = composition;
+    }
+
+    /**
+     * @param {number} entity
+     * @param {Transform} transform
+     */
+    #place(entity, transform) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        const nodes = entry.nodes;
+
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+
+            t64_copy_from_transform(node.transform_local, transform);
+
+            // recomputes transform_global down the subtree, and bumps the version the scene
+            // database reads to decide what to upload
+            node.updateMatrices();
+        }
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        for (let i = 0; i < entry.bindings.length; i++) {
+            entry.bindings[i].unlink();
+        }
+
+        for (let i = 0; i < entry.nodes.length; i++) {
+            this.#scene.remove(entry.nodes[i]);
+        }
+
+        if (entry.composition !== null) {
+            // the entities the model became are the model, so they go with it
+            entry.composition.destroy();
+
+            entry.composition = null;
+        }
+
+        const waiting = this.#unregistered.indexOf(entry);
+
+        if (waiting !== -1) {
+            // it left before the GPU was ever told about it
+            this.#unregistered.splice(waiting, 1);
+        }
+
+        const awaiting = this.#awaiting_url.findIndex(pending => pending.entity === entity);
+
+        if (awaiting !== -1) {
+            // it left before it ever had a model to load
+            this.#awaiting_url.splice(awaiting, 1);
+        }
+
+        const registration = entry.animation;
+
+        if (registration !== null) {
+            if (this.#graphics.scene_context(this.#scene) === registration.context) {
+                unregister_instance_animation(registration);
+            }
+
+            entry.animation = null;
+        }
+
+        this.#entries.delete(entity);
+    }
+}