@woosh/meep-engine 3.30.0 → 3.32.0

package/src/engine/graphics3/MeshSystem.js

@@ -1,661 +1,681 @@
-import { assert } from "../../core/assert.js";
-import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
-import { aabb3_matrix4_project } from "../../core/geom/3d/aabb/aabb3_matrix4_project.js";
-import { Scene } from "../../shade/renderer/scene/Scene.js";
-import { System } from "../ecs/System.js";
-import { Transform64 } from "../ecs/transform/Transform64.js";
-import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
-import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
-import { prefab_compile } from "./prefab/prefab_compile.js";
-import { prefab_instance_destroy, prefab_instantiate } from "./prefab/prefab_instantiate.js";
-import {
-    register_instance_animation,
-    unregister_instance_animation
-} from "./register_instance_animation.js";
-
-/**
- * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
- * @typedef {import("../../shade/renderer/loader/SceneBundle.js").SceneBundle} SceneBundle
- * @typedef {import("./prefab/Prefab.js").Prefab} Prefab
- * @typedef {import("./prefab/PrefabInstance.js").PrefabInstance} PrefabInstance
- * @typedef {import("./register_instance_animation.js").InstanceAnimationRegistration} InstanceAnimationRegistration
- * @typedef {import("./GraphicsEngine.js").GraphicsEngine} GraphicsEngine
- */
-
-/**
- * What {@link MeshSystem.mesh_entities_of} answers for an entity with nothing in the scene.
- *
- * @type {Int32Array}
- */
-const NO_ENTITIES = new Int32Array(0);
-
-const SCRATCH_BOUNDS = new Float32Array(6);
-
-/**
- * What one entity has: its model, once loaded, as entities; the ids the GPU issued for the model's
- * skins; and what is listening on its behalf.
- */
-class Entry {
-    /**
-     * @type {number}
-     */
-    entity = -1;
-
-    /**
-     * @type {SGMesh}
-     */
-    model = null;
-
-    /**
-     * @type {Transform64}
-     */
-    transform = null;
-
-    /**
-     * The model as entities, or null until it has loaded.
-     *
-     * @type {PrefabInstance|null}
-     */
-    instance = null;
-
-    /**
-     * What the GPU gave back for the instance's skins, or null while there is nothing registered —
-     * no model yet, no device yet, or a renderer restart that has not been drained.
-     *
-     * @type {InstanceAnimationRegistration|null}
-     */
-    animation = null;
-
-    /**
-     * The GPU context the instance's entities hold their rows in, or null while they hold none.
-     *
-     * @type {GPUSceneContext|null}
-     */
-    context = null;
-
-    /**
-     * Fires when the placing entity's world transform moves.
-     *
-     * @type {function(): void}
-     */
-    on_moved = null;
-
-    /**
-     * One per entity of the instance, firing when that entity's offset from its parent moves —
-     * a joint an IK solver, a ragdoll or a cloth wrote.
-     *
-     * @type {Map<number, function(): void>}
-     */
-    on_offset_moved = new Map();
-}
-
-/**
- * Puts models into the scene as entities, and keeps their rows where the entities say.
- *
- * **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`.
- *
- * **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 {
-    /**
-     * @type {GraphicsEngine}
-     */
-    #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 and compiled models, 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; compiling it once
-     * per placement would be the next.
-     *
-     * @type {Map<string, Promise<Prefab>>}
-     */
-    #models = new Map();
-
-    /**
-     * @type {Map<number, Entry>}
-     */
-    #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 attached and registered again.
-     *
-     * @type {GPUSceneContext|null}
-     */
-    #context = null;
-
-    /**
-     * Entries whose instance is not attached to {@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 and the answer is almost always "nothing to do".
-     *
-     * @type {Entry[]}
-     */
-    #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.
-     *
-     * @type {Entry[]}
-     */
-    #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 {GraphicsEngine} 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, Transform64];
-    }
-
-    /**
-     * @returns {Scene}
-     */
-    get scene() {
-        return this.#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.
-     *
-     * @param {number} entity
-     * @returns {PrefabInstance|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 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;
-    }
-
-    /**
-     * 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
-     * covers; anything that has to say something about a particular model's meshes starts here.
-     *
-     * @param {number} entity
-     * @returns {Int32Array} empty for an entity with nothing in the scene — never seen, or still
-     * loading, and neither is an error. Not to be kept: a model swap replaces it
-     */
-    mesh_entities_of(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined || entry.instance === null) {
-            return NO_ENTITIES;
-        }
-
-        return entry.instance.mesh_entities;
-    }
-
-    /**
-     * Where an entity's model is, in world space: the union of its primitives' geometry bounds
-     * under their own entities' world transforms — which the ECS composes, so this answers with no
-     * device and with no frame of latency, from what the simulation knows. The box the renderer
-     * culls by is derived on the GPU from the same and is not consulted.
-     *
-     * A skinned primitive answers at its rest pose, under the frame its skin deforms in.
-     *
-     * @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 || entry.instance === null) {
-            return false;
-        }
-
-        const dataset = this.entityManager.dataset;
-        const primitives = entry.instance.mesh_entities;
-
-        let found = false;
-
-        for (let i = 0; i < primitives.length; i++) {
-            const primitive = primitives[i];
-
-            if (!dataset.entityExists(primitive)) {
-                continue;
-            }
-
-            const geometry = dataset.getComponent(primitive, ShadedGeometry);
-            const world = dataset.getComponent(primitive, Transform64);
-
-            if (geometry === undefined || world === undefined || geometry.geometry === null) {
-                continue;
-            }
-
-            // a Transform64's matrix starts at element 0, so it is its own mat4 argument
-            aabb3_matrix4_project(SCRATCH_BOUNDS, geometry.geometry.bounding_box, world);
-
-            // 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 : SCRATCH_BOUNDS, 0, SCRATCH_BOUNDS, 0);
-
-            found = true;
-        }
-
-        return found;
-    }
-
-    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.#graphics.set_scene(scene);
-    }
-
-    async shutdown(entityManager) {
-        for (const entity of Array.from(this.#entries.keys())) {
-            this.#drop(entity);
-        }
-
-        this.#models.clear();
-
-        this.#context = null;
-        this.#unregistered.length = 0;
-    }
-
-    /**
-     * Tell the GPU about the models that have arrived since the last frame: their entities take
-     * their rows, and their skins reach `GPUAnimationManager`.
-     *
-     * The manager hangs off the scene's GPU context, which exists only while there is a device, so
-     * neither can 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 its row.
-     *
-     * A restart is the same event seen from here: the context object changes, every id and every
-     * row 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 entity already bound to another skin, and that assertion then fires once a frame for as
-         long as the game runs. 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 it is written down here rather than fixed.
-        */
-        for (let i = 0; i < waiting.length; i++) {
-            this.#register(waiting[i], context);
-        }
-
-        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 entry = waiting[i];
-
-            if (entry.model.url === null) {
-                continue;
-            }
-
-            waiting.splice(i, 1);
-
-            this.#attach(entry, entry.model.url);
-        }
-    }
-
-    /**
-     * 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;
-            entry.context = null;
-
-            waiting.push(entry);
-        }
-    }
-
-    /**
-     * Give an instance's entities their rows in a context, and its skins to the animation manager.
-     *
-     * Every entity of the model takes a `transforms` row — a joint composes on the GPU, a grouping
-     * node is what its children compose under — and the placing entity takes one too, so the whole
-     * hierarchy composes from it. The primitives' `meshes` rows are `ShadedGeometrySystem`'s.
-     *
-     * @param {Entry} entry
-     * @param {GPUSceneContext} context
-     */
-    #register(entry, context) {
-        const rows = context.rows;
-        const entities = entry.instance.entities;
-
-        for (let i = 0; i < entities.length; i++) {
-            rows.acquire(entities[i]);
-        }
-
-        entry.animation = register_instance_animation(context, entry.instance);
-        entry.context = context;
-    }
-
-    /**
-     * @param {SGMesh} model
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    link(model, transform, entity) {
-        const entry = new Entry();
-
-        entry.entity = entity;
-        entry.model = model;
-        entry.transform = transform;
-
-        this.#entries.set(entity, entry);
-
-        // The placing entity's own row is marked when its transform moves, not on a poll: an
-        // entity that has not moved costs nothing, which is the same bargain the scene database
-        // makes downstream. A Transform64 has no signals of its own, so the announcement comes from
-        // the dataset. The entities under it follow through the attachment system and need no
-        // marking of their own for a move of the root — the GPU composes them.
-        entry.on_moved = () => {
-            if (entry.context !== null) {
-                entry.context.rows.mark_world(entity);
-            }
-        };
-
-        this.entityManager.dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_moved);
-
-        if (model.url === null) {
-            // nothing to show yet; {@link update} watches for the url arriving
-            this.#awaiting_url.push(entry);
-
-            return;
-        }
-
-        this.#attach(entry, model.url);
-    }
-
-    /**
-     * @param {SGMesh} model
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    unlink(model, transform, entity) {
-        this.#drop(entity);
-    }
-
-    /**
-     * The prefab for a url, loading and compiling it on first mention.
-     *
-     * @param {string} url
-     * @returns {Promise<Prefab>}
-     */
-    #model(url) {
-        let prefab = this.#models.get(url);
-
-        if (prefab === undefined) {
-            prefab = this.#load(url).then(bundle => prefab_compile(bundle));
-
-            this.#models.set(url, prefab);
-        }
-
-        return prefab;
-    }
-
-    /**
-     * Load and compile the model if it has not been seen, then spawn it under the entity.
-     *
-     * @param {Entry} entry
-     * @param {string} url
-     */
-    async #attach(entry, url) {
-        const entity = entry.entity;
-
-        const prefab = await this.#model(url);
-
-        /*
-         Which entry this load is for was 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. Spawning for that one would leave a model in the scene
-         nothing owns.
-        */
-        if (this.#entries.get(entity) !== entry) {
-            // the entity left while its model was in flight, or left and came back as another
-            // entry — both ordinary at level-load rates
-            return;
-        }
-
-        const dataset = this.entityManager.dataset;
-
-        const instance = prefab_instantiate(prefab, dataset, entity);
-
-        entry.instance = instance;
-
-        // A joint's offset moving — an IK solver, a ragdoll, a cloth writing it — is that joint's
-        // row. The world transforms the attachment system composes below it are not: the GPU
-        // composes those itself, from the offsets.
-        const entities = instance.entities;
-
-        for (let i = 1; i < entities.length; i++) {
-            const member = entities[i];
-
-            const on_offset_moved = () => {
-                if (entry.context !== null) {
-                    entry.context.rows.mark_local(member);
-                }
-            };
-
-            entry.on_offset_moved.set(member, on_offset_moved);
-
-            dataset.addEntityEventListener(member, TRANSFORM_ATTACHMENT_EVENT_CHANGE, on_offset_moved);
-        }
-
-        // 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);
-    }
-
-    /**
-     * @param {number} entity
-     */
-    #drop(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        this.#entries.delete(entity);
-
-        const dataset = this.entityManager.dataset;
-
-        if (dataset.entityExists(entity)) {
-            dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_moved);
-        }
-
-        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.indexOf(entry);
-
-        if (awaiting !== -1) {
-            // it left before it ever had a model to load
-            this.#awaiting_url.splice(awaiting, 1);
-        }
-
-        const instance = entry.instance;
-
-        if (instance === null) {
-            return;
-        }
-
-        entry.instance = null;
-
-        for (const [member, listener] of entry.on_offset_moved) {
-            if (dataset.entityExists(member)) {
-                dataset.removeEntityEventListener(member, TRANSFORM_ATTACHMENT_EVENT_CHANGE, listener);
-            }
-        }
-
-        entry.on_offset_moved.clear();
-
-        // A destroyed context must not be handed its rows or its ids back: a renderer restart
-        // takes the GPU scene context with it, and what the old one issued means nothing to the
-        // context that replaces it — so the entry forgets them rather than returning them.
-        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
-            const rows = entry.context.rows;
-            const entities = instance.entities;
-
-            for (let i = 0; i < entities.length; i++) {
-                rows.release(entities[i]);
-            }
-
-            if (entry.animation !== null) {
-                unregister_instance_animation(entry.animation);
-            }
-        }
-
-        entry.animation = null;
-        entry.context = null;
-
-        // the entities the model became are the model, so they go with it
-        prefab_instance_destroy(dataset, instance);
-    }
-}
+import { assert } from "../../core/assert.js";
+import { aabb3_array_combine } from "../../core/geom/3d/aabb/aabb3_array_combine.js";
+import { aabb3_matrix4_project } from "../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { Scene } from "../../shade/renderer/scene/Scene.js";
+import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { SGMesh } from "../graphics/ecs/mesh-v2/aggregate/SGMesh.js";
+import { prefab_compile } from "./prefab/prefab_compile.js";
+import { prefab_instance_destroy, prefab_instantiate } from "./prefab/prefab_instantiate.js";
+import {
+    register_instance_animation,
+    unregister_instance_animation
+} from "./register_instance_animation.js";
+
+/**
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../shade/renderer/loader/SceneBundle.js").SceneBundle} SceneBundle
+ * @typedef {import("./prefab/Prefab.js").Prefab} Prefab
+ * @typedef {import("./prefab/PrefabInstance.js").PrefabInstance} PrefabInstance
+ * @typedef {import("./register_instance_animation.js").InstanceAnimationRegistration} InstanceAnimationRegistration
+ * @typedef {import("./GraphicsEngine.js").GraphicsEngine} GraphicsEngine
+ */
+
+/**
+ * What {@link MeshSystem.mesh_entities_of} answers for an entity with nothing in the scene.
+ *
+ * @type {Int32Array}
+ */
+const NO_ENTITIES = new Int32Array(0);
+
+const SCRATCH_BOUNDS = new Float32Array(6);
+
+/**
+ * What one entity has: its model, once loaded, as entities; the ids the GPU issued for the model's
+ * skins; and what is listening on its behalf.
+ */
+class Entry {
+    /**
+     * @type {number}
+     */
+    entity = -1;
+
+    /**
+     * @type {SGMesh}
+     */
+    model = null;
+
+    /**
+     * @type {Transform64}
+     */
+    transform = null;
+
+    /**
+     * The model as entities, or null until it has loaded.
+     *
+     * @type {PrefabInstance|null}
+     */
+    instance = null;
+
+    /**
+     * What the GPU gave back for the instance's skins, or null while there is nothing registered —
+     * no model yet, no device yet, or a renderer restart that has not been drained.
+     *
+     * @type {InstanceAnimationRegistration|null}
+     */
+    animation = null;
+
+    /**
+     * The GPU context the instance's entities hold their rows in, or null while they hold none.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    context = null;
+
+    /**
+     * Fires when the placing entity's world transform moves.
+     *
+     * @type {function(): void}
+     */
+    on_moved = null;
+
+    /**
+     * One per entity of the instance, firing when that entity's offset from its parent moves —
+     * a joint an IK solver, a ragdoll or a cloth wrote.
+     *
+     * @type {Map<number, function(): void>}
+     */
+    on_offset_moved = new Map();
+}
+
+/**
+ * Puts models into the scene as entities, and keeps their rows where the entities say.
+ *
+ * **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`.
+ *
+ * **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 {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #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 and compiled models, 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; compiling it once
+     * per placement would be the next.
+     *
+     * @type {Map<string, Promise<Prefab>>}
+     */
+    #models = new Map();
+
+    /**
+     * @type {Map<number, Entry>}
+     */
+    #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 attached and registered again.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    #context = null;
+
+    /**
+     * Entries whose instance is not attached to {@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 and the answer is almost always "nothing to do".
+     *
+     * @type {Entry[]}
+     */
+    #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.
+     *
+     * @type {Entry[]}
+     */
+    #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 {GraphicsEngine} 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, Transform64];
+    }
+
+    /**
+     * @returns {Scene}
+     */
+    get scene() {
+        return this.#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.
+     *
+     * **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
+     * reader is the {@link #collect_arrived_urls} drain that an entry leaves permanently the first
+     * frame a url is present, and the component's setter raises no signal. Noticing it would mean
+     * comparing a url per mesh entity per frame, which is the opposite of the bargain the rest of
+     * this system makes — an entity that has not moved costs nothing.
+     *
+     * @param {number} entity
+     * @returns {PrefabInstance|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 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;
+    }
+
+    /**
+     * 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
+     * covers; anything that has to say something about a particular model's meshes starts here.
+     *
+     * @param {number} entity
+     * @returns {Int32Array} empty for an entity with nothing in the scene — never seen, or still
+     * loading, and neither is an error. Not to be kept: a model swap replaces it
+     */
+    mesh_entities_of(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined || entry.instance === null) {
+            return NO_ENTITIES;
+        }
+
+        return entry.instance.mesh_entities;
+    }
+
+    /**
+     * Where an entity's model is, in world space: the union of its primitives' geometry bounds
+     * under their own entities' world transforms — which the ECS composes, so this answers with no
+     * device and with no frame of latency, from what the simulation knows. The box the renderer
+     * culls by is derived on the GPU from the same and is not consulted.
+     *
+     * A skinned primitive answers at its rest pose, under the frame its skin deforms in.
+     *
+     * @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 || entry.instance === null) {
+            return false;
+        }
+
+        const dataset = this.entityManager.dataset;
+        const primitives = entry.instance.mesh_entities;
+
+        let found = false;
+
+        for (let i = 0; i < primitives.length; i++) {
+            const primitive = primitives[i];
+
+            if (!dataset.entityExists(primitive)) {
+                continue;
+            }
+
+            const geometry = dataset.getComponent(primitive, ShadedGeometry);
+            const world = dataset.getComponent(primitive, Transform64);
+
+            if (geometry === undefined || world === undefined || geometry.geometry === null) {
+                continue;
+            }
+
+            // a Transform64's matrix starts at element 0, so it is its own mat4 argument
+            aabb3_matrix4_project(SCRATCH_BOUNDS, geometry.geometry.bounding_box, world);
+
+            // 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 : SCRATCH_BOUNDS, 0, SCRATCH_BOUNDS, 0);
+
+            found = true;
+        }
+
+        return found;
+    }
+
+    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.#graphics.set_scene(scene);
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+
+        this.#models.clear();
+
+        this.#context = null;
+        this.#unregistered.length = 0;
+    }
+
+    /**
+     * Tell the GPU about the models that have arrived since the last frame: their entities take
+     * their rows, and their skins reach `GPUAnimationManager`.
+     *
+     * The manager hangs off the scene's GPU context, which exists only while there is a device, so
+     * neither can 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
+     * what drives the deformation — a clip's bindings, a skin's meshes — follows when every entity
+     * it names has its row.
+     *
+     * A restart is the same event seen from here: the context object changes, every id and every
+     * row 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 must not cost the session.** The list used to be cleared after the loop,
+         so a registration that threw partway left the entries before it *already registered* and
+         *still queued*: the next update registered them a second time, `bind` found the entity
+         already bound to another skin, and that assertion then fired once a frame for as long as
+         the game ran — one failed model converted into permanent corruption of an unrelated one.
+
+         So an entry comes off the list BEFORE it is registered, and can never be registered twice
+         whatever happens next. The open question this leaves — what to do with an entry that
+         *cannot* be registered — is answered the only way a frame loop can afford: it is dropped,
+         once, with a message. That model does not appear; every other one does, and the next frame
+         is a normal frame.
+        */
+        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(`MeshSystem: failed to register entity ${entry.entity} ('${entry.model?.url}'), dropping it`, e);
+            }
+        }
+    }
+
+    /**
+     * 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 entry = waiting[i];
+
+            if (entry.model.url === null) {
+                continue;
+            }
+
+            waiting.splice(i, 1);
+
+            this.#attach(entry, entry.model.url);
+        }
+    }
+
+    /**
+     * 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;
+            entry.context = null;
+
+            waiting.push(entry);
+        }
+    }
+
+    /**
+     * Give an instance's entities their rows in a context, and its skins to the animation manager.
+     *
+     * Every entity of the model takes a `transforms` row — a joint composes on the GPU, a grouping
+     * node is what its children compose under — and the placing entity takes one too, so the whole
+     * hierarchy composes from it. The primitives' `meshes` rows are `ShadedGeometrySystem`'s.
+     *
+     * @param {Entry} entry
+     * @param {GPUSceneContext} context
+     */
+    #register(entry, context) {
+        const rows = context.rows;
+        const entities = entry.instance.entities;
+
+        for (let i = 0; i < entities.length; i++) {
+            rows.acquire(entities[i]);
+        }
+
+        entry.animation = register_instance_animation(context, entry.instance);
+        entry.context = context;
+    }
+
+    /**
+     * @param {SGMesh} model
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(model, transform, entity) {
+        const entry = new Entry();
+
+        entry.entity = entity;
+        entry.model = model;
+        entry.transform = transform;
+
+        this.#entries.set(entity, entry);
+
+        // The placing entity's own row is marked when its transform moves, not on a poll: an
+        // entity that has not moved costs nothing, which is the same bargain the scene database
+        // makes downstream. A Transform64 has no signals of its own, so the announcement comes from
+        // the dataset. The entities under it follow through the attachment system and need no
+        // marking of their own for a move of the root — the GPU composes them.
+        entry.on_moved = () => {
+            if (entry.context !== null) {
+                entry.context.rows.mark_world(entity);
+            }
+        };
+
+        this.entityManager.dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_moved);
+
+        if (model.url === null) {
+            // nothing to show yet; {@link update} watches for the url arriving
+            this.#awaiting_url.push(entry);
+
+            return;
+        }
+
+        this.#attach(entry, model.url);
+    }
+
+    /**
+     * @param {SGMesh} model
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(model, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * The prefab for a url, loading and compiling it on first mention.
+     *
+     * @param {string} url
+     * @returns {Promise<Prefab>}
+     */
+    #model(url) {
+        let prefab = this.#models.get(url);
+
+        if (prefab === undefined) {
+            prefab = this.#load(url).then(bundle => prefab_compile(bundle));
+
+            this.#models.set(url, prefab);
+        }
+
+        return prefab;
+    }
+
+    /**
+     * Load and compile the model if it has not been seen, then spawn it under the entity.
+     *
+     * @param {Entry} entry
+     * @param {string} url
+     */
+    async #attach(entry, url) {
+        const entity = entry.entity;
+
+        const prefab = await this.#model(url);
+
+        /*
+         Which entry this load is for was 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. Spawning for that one would leave a model in the scene
+         nothing owns.
+        */
+        if (this.#entries.get(entity) !== entry) {
+            // the entity left while its model was in flight, or left and came back as another
+            // entry — both ordinary at level-load rates
+            return;
+        }
+
+        const dataset = this.entityManager.dataset;
+
+        const instance = prefab_instantiate(prefab, dataset, entity);
+
+        entry.instance = instance;
+
+        // A joint's offset moving — an IK solver, a ragdoll, a cloth writing it — is that joint's
+        // row. The world transforms the attachment system composes below it are not: the GPU
+        // composes those itself, from the offsets.
+        const entities = instance.entities;
+
+        for (let i = 1; i < entities.length; i++) {
+            const member = entities[i];
+
+            const on_offset_moved = () => {
+                if (entry.context !== null) {
+                    entry.context.rows.mark_local(member);
+                }
+            };
+
+            entry.on_offset_moved.set(member, on_offset_moved);
+
+            dataset.addEntityEventListener(member, TRANSFORM_ATTACHMENT_EVENT_CHANGE, on_offset_moved);
+        }
+
+        // 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);
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#entries.delete(entity);
+
+        const dataset = this.entityManager.dataset;
+
+        if (dataset.entityExists(entity)) {
+            dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_moved);
+        }
+
+        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.indexOf(entry);
+
+        if (awaiting !== -1) {
+            // it left before it ever had a model to load
+            this.#awaiting_url.splice(awaiting, 1);
+        }
+
+        const instance = entry.instance;
+
+        if (instance === null) {
+            return;
+        }
+
+        entry.instance = null;
+
+        for (const [member, listener] of entry.on_offset_moved) {
+            if (dataset.entityExists(member)) {
+                dataset.removeEntityEventListener(member, TRANSFORM_ATTACHMENT_EVENT_CHANGE, listener);
+            }
+        }
+
+        entry.on_offset_moved.clear();
+
+        // A destroyed context must not be handed its rows or its ids back: a renderer restart
+        // takes the GPU scene context with it, and what the old one issued means nothing to the
+        // context that replaces it — so the entry forgets them rather than returning them.
+        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
+            const rows = entry.context.rows;
+            const entities = instance.entities;
+
+            for (let i = 0; i < entities.length; i++) {
+                rows.release(entities[i]);
+            }
+
+            if (entry.animation !== null) {
+                unregister_instance_animation(entry.animation);
+            }
+        }
+
+        entry.animation = null;
+        entry.context = null;
+
+        // the entities the model became are the model, so they go with it
+        prefab_instance_destroy(dataset, instance);
+    }
+}