@woosh/meep-engine 3.23.0 → 3.24.0

package/src/engine/graphics3/MeshSystem.js

@@ -1,40 +1,116 @@
 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 { aabb3_matrix4_project } from "../../core/geom/3d/aabb/aabb3_matrix4_project.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 { Transform64 } from "../ecs/transform/Transform64.js";
-import { ParentEntity } from "../ecs/parent/ParentEntity.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 { shade_bundle_to_entity_composition } from "./shade_node_to_entity_composition.js";
-import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
-import { t64_announce_change } from "../ecs/transform/t64_announce_change.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";
 
 /**
- * Puts entities into Shade's scene and keeps them where the ECS says they are.
+ * @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.
  *
- * **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`.
+ * @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.
  *
- * 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.
+ * **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`.
  *
- * 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 owns the scene and tells the facade to draw it**, rather than the facade handing a graph out
+ * for anyone to write into.
  *
- * **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.
+ * **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 {
     /**
@@ -43,53 +119,43 @@ export class MeshSystem extends System {
     #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.
+     * 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.
+     * 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<SceneBundle>>}
+     * @type {Map<string, Promise<Prefab>>}
      */
-    #bundles = new Map();
+    #models = 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}>}
+     * @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 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.
+     * 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 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".
+     * 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 {object[]}
+     * @type {Entry[]}
      */
     #unregistered = [];
 
@@ -97,16 +163,12 @@ export class MeshSystem extends System {
      * 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.
+     * 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}[]}
+     * @type {Entry[]}
      */
     #awaiting_url = [];
 
@@ -146,82 +208,15 @@ export class MeshSystem extends System {
     }
 
     /**
-     * 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 `ShadedGeometrySystem` 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.
+     * 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 nodes that left the scene. The object's identity is the only signal that says so.
+     * driving entities that have gone. 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
+     * @returns {PrefabInstance|null} `null` for an entity this system has never seen, or one
      * whose model has not finished loading
      */
     instance_of(entity) {
@@ -235,7 +230,7 @@ export class MeshSystem extends System {
     }
 
     /**
-     * What the GPU's animation manager gave back for that instance — the skin and clip ids, in the
+     * 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
@@ -257,11 +252,31 @@ export class MeshSystem extends System {
     }
 
     /**
-     * Where an entity's model is, in world space.
+     * 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.
      *
-     * 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 {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
@@ -271,45 +286,57 @@ export class MeshSystem extends System {
     compute_world_bounds(target, entity) {
         const entry = this.#entries.get(entity);
 
-        if (entry === undefined) {
+        if (entry === undefined || entry.instance === null) {
             return false;
         }
 
+        const dataset = this.entityManager.dataset;
+        const primitives = entry.instance.mesh_entities;
+
         let found = false;
 
-        /**
-         * @param {Mesh} node
-         */
-        const combine = node => {
-            const bounds = node.bounding_box;
+        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 : bounds, 0, bounds, 0);
+            aabb3_array_combine(target, 0, found ? target : SCRATCH_BOUNDS, 0, SCRATCH_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);
+        // 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) {
@@ -317,24 +344,24 @@ export class MeshSystem extends System {
             this.#drop(entity);
         }
 
-        this.#bundles.clear();
+        this.#models.clear();
 
         this.#context = null;
         this.#unregistered.length = 0;
     }
 
     /**
-     * Tell the GPU about the models that have arrived since the last frame.
+     * Tell the GPU about the models that have arrived since the last frame: their entities take
+     * their rows, and their skins reach `GPUAnimationManager`.
      *
-     * **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.
+     * 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 the old one
-     * issued is void, and everything currently placed queues up again.
+     * 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
      */
@@ -363,23 +390,13 @@ export class MeshSystem extends System {
          **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 it is written down here rather
-         than fixed. The throw that exposed it is fixed (`ac5e430e3`); the amplifier is not, and any
-         future failure in registration reproduces the same cascade.
+         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++) {
-            const entry = waiting[i];
-
-            entry.animation = register_instance_animation(context, entry.instance);
+            this.#register(waiting[i], context);
         }
 
         waiting.length = 0;
@@ -395,15 +412,15 @@ export class MeshSystem extends System {
         const waiting = this.#awaiting_url;
 
         for (let i = waiting.length - 1; i >= 0; i--) {
-            const pending = waiting[i];
+            const entry = waiting[i];
 
-            if (pending.model.url === null) {
+            if (entry.model.url === null) {
                 continue;
             }
 
             waiting.splice(i, 1);
 
-            this.#attach(pending.entity, pending.model.url, pending.transform);
+            this.#attach(entry, entry.model.url);
         }
     }
 
@@ -425,41 +442,69 @@ export class MeshSystem extends System {
             }
 
             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 = { nodes: [], on_changed: null, instance: null, animation: null, composition: null };
+        const entry = new Entry();
 
-        this.#entries.set(entity, entry);
+        entry.entity = entity;
+        entry.model = model;
+        entry.transform = transform;
 
-        // 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.
-        // A Transform64 has no signals of its own, so the announcement comes from the dataset: the
-        // writer sends TRANSFORM64_EVENT_CHANGE and this wakes on it. Coarser than the three
-        // sub-object signals it replaces - a scale write wakes a placement that only reads the whole
-        // transform anyway - and #place already skips when nothing moved.
-        const on_changed = () => this.#place(entity, transform);
+        this.#entries.set(entity, entry);
 
-        entry.on_changed = on_changed;
+        // 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, on_changed);
+        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({ entity, model, transform });
+            this.#awaiting_url.push(entry);
 
             return;
         }
 
-        this.#attach(entity, model.url, transform);
+        this.#attach(entry, model.url);
     }
 
     /**
@@ -472,144 +517,75 @@ export class MeshSystem extends System {
     }
 
     /**
-     * Load the model if it has not been seen, then put a copy of it in the scene.
+     * The prefab for a url, loading and compiling it on first mention.
      *
-     * @param {number} entity
      * @param {string} url
-     * @param {Transform64} transform
+     * @returns {Promise<Prefab>}
      */
-    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;
+    #model(url) {
+        let prefab = this.#models.get(url);
 
-        const entry = this.#entries.get(entity);
+        if (prefab === undefined) {
+            prefab = this.#load(url).then(bundle => prefab_compile(bundle));
 
-        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;
+            this.#models.set(url, prefab);
         }
 
-        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);
+        return prefab;
     }
 
     /**
-     * Put a model into the dataset as entities.
+     * Load and compile the model if it has not been seen, then spawn it under the entity.
      *
-     * **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 `ShadedGeometrySystem` 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 {Transform64} transform
+     * @param {Entry} entry
+     * @param {string} url
      */
-    #expand(entity, bundle, transform) {
-        const entry = this.#entries.get(entity);
-
-        const composition = shade_bundle_to_entity_composition(bundle);
+    async #attach(entry, url) {
+        const entity = entry.entity;
 
-        composition.entity.add(ParentEntity.from(entity));
+        const prefab = await this.#model(url);
 
-        // Copying is only half of it: the composed entity is a writer like any other, so the
-        // systems placing ITS nodes wake on its own announcement, not on the source entity is.
-        // EntityNode.transform is the hierarchy pose, not the entity's component - the component is
-        // the world transform the node syncs down into. Under signals the copy alone triggered that
-        // sync; a Transform64 has none, so the sync is asked for explicitly.
-        const follow = () => {
-            composition.transform.copy(transform);
-
-            composition.transform_changed();
-        };
-
-        follow();
+        /*
+         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;
+        }
 
-        composition.build(this.entityManager.dataset);
+        const dataset = this.entityManager.dataset;
 
-        // the build linked the composed entity's own systems; sync once more so they see the pose
-        follow();
+        const instance = prefab_instantiate(prefab, dataset, entity);
 
-        // the composed entity follows the source transform, and a Transform64 has no signals of
-        // its own, so the follow rides the dataset announcement like every other consumer
-        const ecd = this.entityManager.dataset;
+        entry.instance = instance;
 
-        ecd.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, follow);
+        // 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;
 
-        composition.on.destroyed.addOne(
-            () => ecd.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, follow)
-        );
+        for (let i = 1; i < entities.length; i++) {
+            const member = entities[i];
 
-        entry.composition = composition;
-    }
+            const on_offset_moved = () => {
+                if (entry.context !== null) {
+                    entry.context.rows.mark_local(member);
+                }
+            };
 
-    /**
-     * @param {number} entity
-     * @param {Transform64} transform
-     */
-    #place(entity, transform) {
-        const entry = this.#entries.get(entity);
+            entry.on_offset_moved.set(member, on_offset_moved);
 
-        if (entry === undefined) {
-            return;
+            dataset.addEntityEventListener(member, TRANSFORM_ATTACHMENT_EVENT_CHANGE, on_offset_moved);
         }
 
-        const nodes = entry.nodes;
-
-        for (let i = 0; i < nodes.length; i++) {
-            const node = nodes[i];
-
-            node.transform_local.copy(transform);
-
-            // recomputes transform_global down the subtree, and bumps the version the scene
-            // database reads to decide what to upload
-            node.updateMatrices();
-        }
+        // 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);
     }
 
     /**
@@ -622,21 +598,12 @@ export class MeshSystem extends System {
             return;
         }
 
-        if (entry.on_changed !== null) {
-            this.entityManager.dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_changed);
-
-            entry.on_changed = null;
-        }
-
-        for (let i = 0; i < entry.nodes.length; i++) {
-            this.#scene.remove(entry.nodes[i]);
-        }
+        this.#entries.delete(entity);
 
-        if (entry.composition !== null) {
-            // the entities the model became are the model, so they go with it
-            entry.composition.destroy();
+        const dataset = this.entityManager.dataset;
 
-            entry.composition = null;
+        if (dataset.entityExists(entity)) {
+            dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_moved);
         }
 
         const waiting = this.#unregistered.indexOf(entry);
@@ -646,23 +613,49 @@ export class MeshSystem extends System {
             this.#unregistered.splice(waiting, 1);
         }
 
-        const awaiting = this.#awaiting_url.findIndex(pending => pending.entity === entity);
+        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 registration = entry.animation;
+        const instance = entry.instance;
 
-        if (registration !== null) {
-            if (this.#graphics.scene_context(this.#scene) === registration.context) {
-                unregister_instance_animation(registration);
+        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.animation = null;
+        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);
+            }
         }
 
-        this.#entries.delete(entity);
+        entry.animation = null;
+        entry.context = null;
+
+        // the entities the model became are the model, so they go with it
+        prefab_instance_destroy(dataset, instance);
     }
 }