@woosh/meep-engine 3.43.0 → 3.44.0

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

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

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

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

package/src/engine/graphics3/MeshSystem.js

@@ -4,23 +4,15 @@ import { aabb3_matrix4_project } from "../../core/geom/3d/aabb/aabb3_matrix4_pro
 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
  */
 
@@ -34,8 +26,7 @@ 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.
+ * What one entity has: its model, once loaded, as entities.
  */
 class Entry {
     /**
@@ -48,69 +39,33 @@ class Entry {
      */
     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.
+ * Loads models and spawns them as entities, so that a caller need not handle the loading lifecycle.
+ *
+ * **A shortcut, and nothing more.** Give an entity an {@link SGMesh} naming a file; when the file
+ * has loaded — whenever that is — the model appears under the entity as entities and components,
+ * and when the component goes, they go. Everything that makes the model work is those components,
+ * read by their own systems, exactly as if code had built them: `ShadedGeometry` draws through
+ * `ShadedGeometrySystem`, `MeshSkin` deforms through `MeshSkinSystem`, a `TransformAttachment`
+ * composes through `TransformAttachmentSystem`, and the `AnimationClips` on the entity play through
+ * `AnimationSystem` and `AnimationGraphSystem`. None of them knows this system exists, and this
+ * system puts nothing on the GPU itself.
  *
  * **A model is a prefab, and a placement is entities.** A loaded bundle is compiled once per url
- * ({@link prefab_compile}) and spawned once per entity that wears it
- * ({@link prefab_instantiate}): every node of the file becomes an entity attached to its parent's,
- * named, drawing where it draws, with the placing entity as the root. What used to be a private
- * copy of a node tree per placement is the dataset's own hierarchy, addressable by every system —
- * IK finds a foot by name, cloth seeds from joints, gameplay asks where a socket is — and the
- * renderer's tables are indexed by those entities, at `entity + 1`.
+ * ({@link prefab_compile}) and spawned once per entity that wears it ({@link prefab_instantiate}):
+ * every node of the file becomes an entity attached to its parent's, named, drawing where it draws,
+ * with the placing entity as the root.
  *
  * **It owns the scene and tells the facade to draw it**, rather than the facade handing a graph out
  * for anyone to write into.
- *
- * **Rows need a device, and registration does too.** A model loads whenever it loads, and there
- * may be no renderer yet; {@link update} attaches every instance's entities to the scene's GPU
- * context when one arrives, registers its skins with the animation manager, and does both again
- * after a renderer restart. Driving the clips is not this system's business — that is the
- * animation systems' — but a clip nothing has registered cannot be driven by anyone, which is why
- * the instance is handed out ({@link instance_of}) rather than kept.
  */
 export class MeshSystem extends System {
     /**
@@ -141,24 +96,6 @@ export class MeshSystem extends System {
      */
     #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.
      *
@@ -208,12 +145,8 @@ export class MeshSystem extends System {
     }
 
     /**
-     * The model an entity is showing, as entities: its skins and clips addressed to them, and its
-     * nodes by name.
-     *
-     * Handed out rather than copied because an animation driver has to know *which* instance it is
-     * bound to: a model swap builds a new one, and a driver still holding the old one would be
-     * driving entities that have gone. The object's identity is the only signal that says so.
+     * The model an entity is showing, as entities: the prefab, and its node entities by index and by
+     * name. What loading produced — nothing a model needs in order to work is only here.
      *
      * **A model swap is remove-component then add-component.** Reassigning {@link SGMesh#url} on an
      * attached mesh is NOT one and is not observed: `link` reads the url once, the only other
@@ -236,28 +169,6 @@ export class MeshSystem extends System {
         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
@@ -352,81 +263,19 @@ export class MeshSystem extends System {
         }
 
         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.
+     * Load the models of entities whose url has turned up since the last frame.
      *
      * @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;
@@ -444,52 +293,6 @@ export class MeshSystem extends System {
         }
     }
 
-    /**
-     * 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
@@ -500,23 +303,9 @@ export class MeshSystem extends System {
 
         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);
@@ -578,34 +367,7 @@ export class MeshSystem extends System {
             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);
+        entry.instance = prefab_instantiate(prefab, this.entityManager.dataset, entity);
     }
 
     /**
@@ -620,19 +382,6 @@ export class MeshSystem extends System {
 
         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) {
@@ -648,34 +397,8 @@ export class MeshSystem extends System {
 
         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);
+        // the entities the model became are the model, so they go with it — and what they held on
+        // the GPU goes with them, given back by the systems that took it
+        prefab_instance_destroy(this.entityManager.dataset, instance);
     }
 }

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

@@ -0,0 +1,76 @@
+/**
+ * The rows one system holds, each with the rows of everything it hangs from, kept where the
+ * entities say.
+ *
+ * **Why a chain and not a row.** A row whose attachment parent holds no row is written with its CPU
+ * world under the scene root. That is exact until something above it is driven on the GPU — a clip
+ * keying a joint takes the joint's whole subtree off the CPU, and its worlds there stop moving. So a
+ * primitive under an animated node, or a joint under another, composes correctly only when every
+ * entity above it holds a row too, and the GPU composes the chain from the top. A clip also binds
+ * only once every node it keys holds a row, so a chain is what lets it play at all.
+ *
+ * **Held per system.** One system's holds are its own: two primitives under one parent count twice
+ * here and hold the parent's row once. Two systems holding the same entity each hold its row — the
+ * rows count holders — and each follow it; across a model that overlap is the placing entity and a
+ * node or two.
+ *
+ * **Following is the dataset's events, as a placing system's always was.** An entity with an
+ * attachment holds its offset and its parent's row, so what moves it is a new offset, announced as
+ * `TRANSFORM_ATTACHMENT_EVENT_CHANGE`; its world follows on the GPU. The top of a chain holds its
+ * world, announced as `TRANSFORM64_EVENT_CHANGE`. One listener an entity, the same method for all of
+ * them, with the dataset passing the entity in.
+ *
+ * **A reparent is the attachment taken off and put back**, which no change event announces, so one
+ * observer on `TransformAttachment` watches for it and moves a held entity's hold onto its new chain.
+ *
+ * **Rows come and go with the device.** Until {@link bind} is given a scene's rows, holds and
+ * following are recorded and nothing is acquired; binding the rows of a new context after a restart
+ * acquires every held entity again, and no listener changes.
+ */
+export class RowChains {
+    /**
+     * @param {EntityComponentDataset} dataset
+     */
+    constructor(dataset: EntityComponentDataset);
+    /**
+     * The rows the chains are held in, or null while there is no device.
+     *
+     * @returns {GPUSceneRows|null}
+     */
+    get rows(): import("../../shade/renderer/scene/rows/GPUSceneRows.js").GPUSceneRows;
+    /**
+     * Hold the chains in these rows from now on. Rows replaced by a restart took what they held
+     * with them, so nothing is given back to them; every held entity is acquired in the new ones.
+     *
+     * @param {GPUSceneRows|null} rows
+     */
+    bind(rows: GPUSceneRows | null): void;
+    /**
+     * Whether this holds the entity, for itself or for something hanging from it.
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    holds(entity: number): boolean;
+    /**
+     * Hold the entity's row and the rows of everything it hangs from. Every hold is matched by a
+     * {@link release}.
+     *
+     * @param {number} entity
+     */
+    hold(entity: number): void;
+    /**
+     * Let go of one hold. The last lets go of the entity's row and of the hold it had on its parent.
+     *
+     * @param {number} entity
+     */
+    release(entity: number): void;
+    /**
+     * Let go of everything and stop watching the dataset.
+     */
+    destroy(): void;
+    #private;
+}
+export type EntityComponentDataset = import("../ecs/EntityComponentDataset.js").EntityComponentDataset;
+export type GPUSceneRows = import("../../shade/renderer/scene/rows/GPUSceneRows.js").GPUSceneRows;
+//# sourceMappingURL=RowChains.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RowChains.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/RowChains.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAiCI;;OAEG;IACH,qBAFW,sBAAsB,EAchC;IAED;;;;OAIG;IACH,mFAEC;IAED;;;;;OAKG;IACH,WAFW,YAAY,GAAC,IAAI,QAgB3B;IAED;;;;;OAKG;IACH,cAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,aAFW,MAAM,QA6BhB;IAED;;;;OAIG;IACH,gBAFW,MAAM,QA2BhB;IAED;;OAEG;IACH,gBAiBC;;CAyHJ;qCAnVY,OAAO,kCAAkC,EAAE,sBAAsB;2BACjE,OAAO,iDAAiD,EAAE,YAAY"}