@woosh/meep-engine 3.23.0 → 3.24.0

package/src/shade/renderer/animation/GPUAnimationManager.js

@@ -17,11 +17,15 @@ import {
     JOINTS_PER_SKIN_BLOCK,
 } from "./ANIMATION_SKIN_JOINT_BLOCK_STRUCT.js";
 import { POSE_ACCUMULATOR_SLOT_BYTES } from "./POSE_ACCUMULATOR_LAYOUT.js";
-import {
-    clip_scale_channels,
-    skin_clip_scale_conflicts
-} from "./skin_clip_scale_conflicts.js";
-import { skin_normalize_mesh_frame } from "./skin_normalize_mesh_frame.js";
+import { GPUStateAuthorityFlags } from "../../../engine/ecs/gpu/GPUStateAuthorityFlags.js";
+import { gpu_authority_grant } from "../../../engine/ecs/gpu/gpu_authority_grant.js";
+import { gpu_authority_revoke } from "../../../engine/ecs/gpu/gpu_authority_revoke.js";
+import { row_of_entity } from "../scene/rows/GPUSceneRows.js";
+import { gpu_authority_declare } from "../../../engine/ecs/gpu/gpu_authority_declare.js";
+import { TransformAttachment } from "../../../engine/ecs/transform-attachment/TransformAttachment.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../../../engine/ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { pose_evaluate_local } from "./pose/pose_evaluate_local.js";
 import {
     shader_animation_apply,
     WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE,
@@ -57,6 +61,23 @@ import {
  */
 const ZERO_KEYFRAME = Object.freeze({ time: 0, value: 0, inTangent: 0, outTangent: 0 });
 const ZERO_BINDING = Object.freeze({ track: 0, instance: 0, property: 0 });
+
+/**
+ * Scratch for seeding a released joint's offset — see {@link GPUAnimationManager#release_targets}.
+ *
+ * @type {Transform64}
+ */
+const SEED = new Transform64();
+
+/**
+ * The one playback a released joint is evaluated against: the clip that just left it, at the
+ * time and weight it was last set to.
+ *
+ * @type {{clip: ShadeAnimationClip|null, time: number, weight: number}}
+ */
+const SEED_PLAYBACK = { clip: null, time: 0, weight: 1 };
+
+const SEED_PLAYBACKS = [SEED_PLAYBACK];
 // Object.freeze on a typed array with elements throws under V8
 // ("Cannot freeze array buffer views with elements"), so we leave the
 // Float32Array unfrozen — the surrounding placeholder object is still
@@ -280,23 +301,31 @@ export class GPUAnimationManager {
     #free_skin_matrix_ranges = new Map();
 
     /**
-     * Registered skins by id, kept for one reason: a clip registered *after* a skin has to be held
-     * against it, and a clip registered before one has to be held against the skin when it arrives.
-     * The frame a skinned mesh is deformed in is fixed once, at registration, and a clip that scales
-     * a joint is the one thing that can undo it afterwards — see {@link skin_clip_scale_conflicts}
-     * and `SKINNING_FRAME_PLAN.md` §4.
+     * How many bound clips drive each entity, by entity. An entity's local TRS is the GPU's for
+     * as long as this is above zero: the first clip to bind grants `GPUStateAuthority`'s
+     * TransformAttachment bit, the last to unbind revokes it and marks the row so the CPU writes
+     * the rest pose back. Stated on the entity, never inferred from the bindings.
      *
-     * @type {Map<number, Skin>}
+     * @type {Map<number, number>}
+     */
+    #clips_driving = new Map();
+
+    /**
+     * The distinct entities each completed clip drives, by clip id — what {@link unregister_clip}
+     * gives back. A clip still pending drives nothing yet and is not here.
+     *
+     * @type {Map<number, number[]>}
      */
-    #skins_by_id = new Map();
+    #targets_by_clip = new Map();
 
     /**
-     * Registered clips that scale *something*, by id. Almost always empty — a character's clips
-     * rotate and translate — which is what keeps the pairwise check free in the ordinary case.
+     * The CPU's copy of what each registered clip is playing at: the clip itself and the last
+     * time and weight set on it. What a joint is evaluated against when its last clip leaves, so
+     * the offset handed back to the CPU is the pose the GPU last resolved rather than the rest.
      *
-     * @type {Map<number, ShadeAnimationClip>}
+     * @type {Map<number, {clip: ShadeAnimationClip, time: number, weight: number}>}
      */
-    #scaling_clips = new Map();
+    #playback_by_clip = new Map();
 
     /**
      * Per-frame pose-accumulator scratch buffer. One slot per
@@ -322,15 +351,15 @@ export class GPUAnimationManager {
 
     /**
      * Back-reference to the owning scene context. Lets the high-level
-     * `register_*` methods resolve `Node3D.id` → transforms-table row
-     * via {@link GPUSceneContext#id_mapping} and bind skinning meshes
-     * via {@link GPUSceneContext#skinning}, without callers having to
+     * `register_*` methods ask its rows whether a joint or a target
+     * entity has taken its transforms row yet, hand entities to the
+     * GPU through its dataset, and bind skinning meshes via
+     * {@link GPUSceneContext#skinning}, without callers having to
      * thread the context through every call.
      *
      * The manager doesn't touch this at construction (the scene
      * context is itself only partially constructed when it builds the
-     * manager) — only inside `register_*` calls, which happen after
-     * scene.build has populated `id_mapping`.
+     * manager) — only inside `register_*` calls.
      *
      * @type {GPUSceneContext}
      */
@@ -390,8 +419,8 @@ export class GPUAnimationManager {
 
     /**
      * Skins registered via {@link register_skin} whose joint-block
-     * chain hasn't been built yet because one or more joint Node3Ds
-     * lacks an `id_mapping` row. The skin's GPU table row exists
+     * chain hasn't been built yet because one or more joint entities
+     * has not taken its row yet. The skin's GPU table row exists
      * (placeholder `joint_block_head = NULL`, no joints driving the
      * prep pass yet), and state mutators / unregister already work
      * — but the deformation only kicks in once {@link update}
@@ -414,7 +443,7 @@ export class GPUAnimationManager {
     /**
      * Clips registered via {@link register_clip} whose bindings
      * chain hasn't been built yet because one or more channel
-     * targets lacks an `id_mapping` row. The clip's GPU table row
+     * targets has not taken its row yet. The clip's GPU table row
      * exists (placeholder `bound_track_group_head = NULL`, no
      * tracks driving the apply pass yet); time/state mutators and
      * unregister already work.
@@ -426,7 +455,7 @@ export class GPUAnimationManager {
      *
      * @type {Array<{
      *     clip_id: number,
-     *     channels: Array<{ track: number, target: Node3D, property: number }>,
+     *     channels: Array<{ track: number, target: number, property: number }>,
      * }>}
      */
     #pending_clips = [];
@@ -819,6 +848,12 @@ export class GPUAnimationManager {
     set_time(clip_id, time) {
         assert.isNumber(time, 'time');
         this.#patch_clip_field(clip_id, 'time', time);
+
+        const shadow = this.#playback_by_clip.get(clip_id);
+
+        if (shadow !== undefined) {
+            shadow.time = time;
+        }
     }
 
     /**
@@ -853,6 +888,12 @@ export class GPUAnimationManager {
     set_playback_weight(clip_id, weight) {
         assert.isNumber(weight, 'weight');
         this.#patch_clip_field(clip_id, 'playback_weight', weight);
+
+        const shadow = this.#playback_by_clip.get(clip_id);
+
+        if (shadow !== undefined) {
+            shadow.weight = weight;
+        }
     }
 
     /**
@@ -1034,30 +1075,21 @@ export class GPUAnimationManager {
     }
 
     /**
-     * High-level skin registration: consumes a {@link Skin} (CPU data
-     * with Node3D joint references and a flat inverse-bind matrix
-     * array), allocates a GPU skin record, and binds every entry in
-     * `skin.meshes` through the skinning context.
-     *
-     * **Eventual consistency.** The `skin_id` is allocated and
-     * returned synchronously — callers can immediately pass it to
-     * state mutators or {@link unregister_skin}. If any joint's
-     * Node3D hasn't been added to a scene yet (no `id_mapping` row),
-     * the joint-block chain that drives the deformation is queued
-     * and built on the next {@link update} that sees all joints
-     * resolved. The skin's table row uses a placeholder
-     * `joint_block_head` until then — observationally indistinguishable
-     * from "skin with no joints driving it" (no deformation runs).
-     *
-     * Mesh→skin bindings register immediately via
-     * {@link GPUMeshSkinningContext#bind}; the skinning context
-     * already tolerates pre-scene-build registration. Each mesh also
-     * gets its {@link SkinnedMesh#skin} reference and a fresh set of
-     * bounds off it, synchronously — that part does not wait for
-     * `id_mapping`, because it reads the joints' `transform_global`
-     * rather than any GPU row.
-     *
-     * @param {Skin} skin
+     * High-level skin registration: consumes a {@link Skin} whose joints and meshes are
+     * **entities**, allocates a GPU skin record, and binds every mesh entity through the
+     * skinning context.
+     *
+     * **Eventual consistency.** The `skin_id` is allocated and returned synchronously — callers
+     * can immediately pass it to state mutators or {@link unregister_skin}. If any joint has not
+     * taken its row yet (see `GPUSceneRows.acquire`), the joint-block chain that drives the
+     * deformation is queued and built on the next {@link update} that sees every joint there.
+     * The skin's table row uses a placeholder `joint_block_head` until then — observationally
+     * indistinguishable from "skin with no joints driving it" (no deformation runs).
+     *
+     * The frame a skin's meshes are deformed in is the prefab's business, fixed once at compile
+     * (`prefab_normalize_skin_frames`); nothing about it is decided here.
+     *
+     * @param {Skin} skin joints and meshes as entities
      * @returns {number} skin id (index into the `animation_skins` table)
      */
     register_skin(skin) {
@@ -1077,7 +1109,7 @@ export class GPUAnimationManager {
         // Reserve the skin row immediately with a placeholder head
         // pointer. State mutators and the public id are usable from
         // this point on; the joint chain gets patched in once
-        // id_mapping has every joint (possibly synchronously below,
+        // every joint has its row (possibly synchronously below,
         // possibly deferred via the pending queue).
         const skins_table = this.#database.get('animation_skins');
         const skin_id = skins_table.add({
@@ -1087,54 +1119,18 @@ export class GPUAnimationManager {
         });
         this.#skin_matrix_offsets.set(skin_id, skin_matrix_offset);
 
-        // Bind every mesh into the skinning context. Idempotent and
-        // pre-build tolerant — the binding upload defers until
-        // id_mapping is ready.
-        //
-        // Each mesh also takes a reference to the CPU-side skin and
-        // re-derives its bounds off it. From here on the skin's
-        // formula is what places the mesh's vertices, and `Mesh`'s
-        // composition — rest-pose geometry under `transform_global` —
-        // is the wrong one, because the skinning pass cancels that
-        // transform back out (see {@link SkinnedMesh#updateBoundsBasic}).
-        // Nothing else would notice: bounds are refreshed by
-        // `updateMatrices`, and a character does not move again just
-        // because it finished loading.
-        // Before any of that: put the meshes into the frame this skin actually deforms in. The
-        // skinning pass writes each clone's vertices in `inverse(mesh.global)` space, so
-        // `mesh.global` is that frame — and glTF says a skinned mesh's node transform is ignored,
-        // which makes the frame the engine's to choose rather than the exporter's to get right.
-        // Ahead of the bind loop because it moves the mesh, and the bounds published below have to
-        // be the ones that survive. See `SKINNING_FRAME_PLAN.md`.
-        this.#normalize_skin_frame(skin);
-
-        this.#skins_by_id.set(skin_id, skin);
-
-        for (const clip of this.#scaling_clips.values()) {
-            this.#report_scale_conflicts(skin, clip);
-        }
-
+        // Bind every mesh entity into the skinning context. The clone a binding deforms is made
+        // when the entity's mesh row is written — before or after this — and the binding follows.
         const skinning = this.#scene_context.skinning;
         const meshes = skin.meshes;
         for (let i = 0; i < meshes.length; i++) {
-            const mesh = meshes[i];
-
-            skinning.bind(mesh, skin_id);
-
-            mesh.skin = skin;
-            mesh.updateBoundsBasic();
+            assert.isNonNegativeInteger(meshes[i], `skin.meshes[${i}]`);
 
-            // The row the scene context published for this mesh holds the pre-skin bounds, and
-            // nothing about binding a skin looks like movement — `updateBoundsBasic` is not
-            // `updateMatrices` and does not touch the version the sync compares against. Without
-            // this the corrected box sits on the CPU object and never reaches the table.
-            mesh.needsUpdate = true;
+            skinning.bind(meshes[i], skin_id);
         }
 
-        // Try to complete now. If id_mapping is ready for every
-        // joint, the chain gets built and patched in. Otherwise the
-        // skin lands on #pending_skins and the next update() drain
-        // retries.
+        // Try to complete now. If every joint has its row, the chain gets built and patched in.
+        // Otherwise the skin lands on #pending_skins and the next update() drain retries.
         const pending = {
             skin_id,
             skin,
@@ -1148,119 +1144,11 @@ export class GPUAnimationManager {
         return skin_id;
     }
 
-    /**
-     * Put a skin's meshes into the frame it deforms in, and say so when they cannot be.
-     *
-     * The correction itself is {@link skin_normalize_mesh_frame}, which is where the argument lives.
-     * This is the reporting: an asset that renders wrong should say which asset and by how much, on
-     * the frame it is registered, rather than reaching a person as a screenshot of soup.
-     *
-     * @param {Skin} skin
-     */
-    #normalize_skin_frame(skin) {
-        const report = skin_normalize_mesh_frame(skin);
-
-        // a glTF skin's `name` is optional and often absent; the mesh it deforms is what a person
-        // would recognise, and is what the asset's own hierarchy calls it
-        const label = skin.name !== '' ? skin.name : (skin.meshes[0]?.name ?? '<unnamed>');
-
-        if (report.unwalked.length > 0) {
-            console.error(
-                `skin '${label}': ${report.unwalked.length} of its nodes have never been walked — `
-                + `'${report.unwalked[0].name}' among them — so their world transforms are the `
-                + `identity by default rather than by derivation. Call updateMatrices on the scene `
-                + `before registering. Nothing was moved; the deformation will be wrong.`
-            );
-
-            return;
-        }
-
-        if (report.frame_defect > 0.001) {
-            console.error(
-                `skin '${label}': no frame can deform it — `
-                + `inverse(frame) × joint.global × inverse_bind is ${report.frame_defect.toFixed(4)} `
-                + `away from rigid at its own bind pose, and a dual quaternion carries a rotation and `
-                + `a translation and nothing else. The rest pose has a non-uniform scale or a shear `
-                + `in it. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §4.`
-            );
-
-            return;
-        }
-
-        if (report.residual > 0.001) {
-            console.error(
-                `skin '${label}': its mesh frame did not land — ${report.residual.toFixed(6)} `
-                + `left over. A correction carrying shear does not survive a Transform64's TRS `
-                + `components. Rendering will be wrong; see SKINNING_FRAME_PLAN.md §3.`
-            );
-
-            return;
-        }
-
-        for (const mesh of report.obstructed) {
-            console.warn(
-                `skin '${label}': mesh node '${mesh.name}' carries the skin's frame now, and its `
-                + `${mesh.children.length} child node(s) inherit it. Sockets belong on bones.`
-            );
-        }
-
-        if (report.corrected > 0) {
-            // verbose rather than a warning: this is a legal asset shape, and a crowd of them would
-            // otherwise be a crowd of log lines
-            console.debug(
-                `skin '${label}': ${report.corrected} mesh frame(s) moved onto the skin's bind `
-                + `transform, absorbing ${report.absorbed.toFixed(4)} of non-rigidity the skinning `
-                + `pass could not have carried.`
-            );
-        }
-    }
-
-    /**
-     * Say so when a clip scales a skin's joints out from under the frame it is deformed in.
-     *
-     * The frame {@link skin_normalize_mesh_frame} chooses is fixed at registration, and it is sound
-     * because the joints and the mesh share their scaling ancestors. A scale that reaches only some
-     * of them breaks that every frame it plays, on the GPU, where nothing can see it —
-     * {@link skin_clip_scale_conflicts} is that question asked off the clip's own curves instead.
-     *
-     * Nothing is refused: the clip is legal animation and the skin is a legal skin, and it is their
-     * combination the skinning pass cannot carry. Refusing either would be picking one to blame.
-     *
-     * @param {Skin} skin
-     * @param {ShadeAnimationClip} clip
-     */
-    #report_scale_conflicts(skin, clip) {
-        const conflicts = skin_clip_scale_conflicts(skin, clip);
-
-        if (conflicts.length === 0) {
-            return;
-        }
-
-        const skin_label = skin.name !== '' ? skin.name : (skin.meshes[0]?.name ?? '<unnamed>');
-
-        const nodes = conflicts.map(conflict => conflict.node.name || '<unnamed>').join(', ');
-
-        const uniform = conflicts.every(conflict => conflict.uniform);
-
-        console.error(
-            `clip '${clip.name}' scales ${conflicts.length} node(s) of skin '${skin_label}' — `
-            + `${nodes} — which reach its joints but not its mesh, so the scale enters the joint `
-            + `matrices and not the frame they are folded against. A dual quaternion cannot carry `
-            + `it and no choice of frame fixes it: the deformation will be wrong while this clip `
-            + `plays. `
-            + (uniform
-                ? `The scale is uniform, which SKINNING_FRAME_PLAN.md §4 has a design for.`
-                : `The scale is non-uniform, which no dual quaternion holds — §4's linear-blend `
-                + `path or an import-time refusal.`)
-        );
-    }
-
     /**
      * Attempt to build the joint-block chain for a pending skin and
      * patch its head pointer onto the skin row. Returns `true` when
-     * every joint Node3D has resolved to a transforms-table row
-     * (and the chain was built); `false` when at least one joint is
-     * still missing.
+     * every joint entity holds its transforms row (and the chain was
+     * built); `false` when at least one joint has not taken it yet.
      *
      * @param {{
      *     skin_id: number,
@@ -1271,7 +1159,7 @@ export class GPUAnimationManager {
      * @returns {boolean}
      */
     #try_complete_skin(pending) {
-        const id_mapping = this.#scene_context.id_mapping;
+        const rows = this.#scene_context.rows;
         const joint_nodes = pending.skin.joints;
         const joint_count = joint_nodes.length;
         const inverse_bind_matrices = pending.inverse_bind_matrices;
@@ -1283,12 +1171,14 @@ export class GPUAnimationManager {
         // walks every block).
         const joints = new Array(joint_count);
         for (let i = 0; i < joint_count; i++) {
-            const node = joint_nodes[i];
-            const row = id_mapping.get(node.id);
-            if (row === undefined) return false;
+            const joint = joint_nodes[i];
+
+            assert.isNonNegativeInteger(joint, `skin.joints[${i}]`);
+
+            if (!rows.has(joint)) return false;
 
             joints[i] = {
-                node: row,
+                node: row_of_entity(joint),
                 // Per-joint slice of the flat matrix array. The
                 // marshaller copies these bytes into the skin-joint
                 // block record; sub-array views are fine — they
@@ -1332,26 +1222,25 @@ export class GPUAnimationManager {
     }
 
     /**
-     * High-level clip registration: consumes a {@link ShadeAnimationClip}
-     * (CPU data with Node3D targets and per-component curves), uploads
-     * curves and tracks, and creates the GPU clip record.
-     *
-     * **Eventual consistency.** The `clip_id` is allocated and
-     * returned synchronously — callers can immediately call
-     * {@link start} / {@link stop} / {@link set_time} /
-     * {@link set_playback_rate} / {@link set_flags} / {@link clear_flags}
-     * / {@link set_playback_weight} / {@link unregister_clip}. If
-     * any channel target's Node3D hasn't been added to a scene yet
-     * (no `id_mapping` row), the bindings chain that drives the
-     * apply pass is queued and built on the next {@link update}
-     * that sees all targets resolved. The clip's table row uses a
-     * placeholder `bound_track_group_head` until then — apply
-     * produces no contributions, so the clip is observationally
-     * inert (still subject to time advancement via the tick shader
-     * if `Playing` is set).
-     *
-     * Curves and tracks are interned synchronously since they're
-     * pure data — no `id_mapping` dependency.
+     * High-level clip registration: consumes a {@link ShadeAnimationClip} whose channels target
+     * **entities**, uploads curves and tracks, and creates the GPU clip record.
+     *
+     * **Eventual consistency.** The `clip_id` is allocated and returned synchronously — callers
+     * can immediately call {@link start} / {@link stop} / {@link set_time} / {@link set_playback_rate}
+     * / {@link set_flags} / {@link clear_flags} / {@link set_playback_weight} /
+     * {@link unregister_clip}. If any target has not taken its row yet, the bindings chain that
+     * drives the apply pass is queued and built on the next {@link update} that sees every target
+     * there. The clip's table row uses a placeholder `bound_track_group_head` until then — apply
+     * produces no contributions, so the clip is observationally inert (still subject to time
+     * advancement via the tick shader if `Playing` is set).
+     *
+     * **Binding is what hands a target to the GPU.** When the chain is built, every entity it
+     * drives has its `GPUStateAuthority` TransformAttachment bit granted, so the CPU stops
+     * writing its local TRS; the last clip to leave revokes it. The entity has to have declared
+     * the component — a prefab does, on every node a clip reaches — because a grant that could
+     * silently do nothing would be a claim nobody could see.
+     *
+     * Curves and tracks are interned synchronously since they're pure data.
      *
      * @param {ShadeAnimationClip} clip
      * @returns {number} clip id
@@ -1363,7 +1252,7 @@ export class GPUAnimationManager {
         const channels = clip.channels;
 
         // Intern every channel's curves + track now. None of this
-        // depends on id_mapping — pure data uploads.
+        // depends on the targets' rows — pure data uploads.
         //
         // Each curve goes through #intern_curve so two channels
         // referencing the same AnimationCurve instance share one
@@ -1391,7 +1280,7 @@ export class GPUAnimationManager {
         // Reserve the clip row immediately with a placeholder head
         // pointer. State mutators and the public id are usable from
         // this point on; the bindings chain gets patched in once
-        // id_mapping has every target. `time` defaults to 0 (the
+        // every target has its row. `time` defaults to 0 (the
         // playback offset relative to `time_start`; the apply
         // shader does `effective_time = clip.time + clip.time_start`).
         const clips_table = this.#database.get('animation_clips');
@@ -1405,54 +1294,47 @@ export class GPUAnimationManager {
             playback_weight: 1,
         });
 
+        this.#playback_by_clip.set(clip_id, { clip, time: 0, weight: 1 });
+
         const pending = { clip_id, channels: pending_channels };
         if (!this.#try_complete_clip(pending)) {
             this.#pending_clips.push(pending);
         }
 
-        /*
-         Asked cheaply first: a clip with no scale channel at all — which is every clip a character
-         normally carries — is dismissed in one pass over its channels and remembered by nothing. Only
-         a clip that scales something is worth holding against the skins, now and as more arrive.
-        */
-        if (clip_scale_channels(clip).length > 0) {
-            this.#scaling_clips.set(clip_id, clip);
-
-            for (const skin of this.#skins_by_id.values()) {
-                this.#report_scale_conflicts(skin, clip);
-            }
-        }
-
         return clip_id;
     }
 
     /**
      * Attempt to build the bindings chain for a pending clip and
      * patch its head pointer onto the clip row. Returns `true` when
-     * every channel target has resolved to a transforms-table row
-     * (and the chain was built); `false` when at least one is still
-     * missing.
+     * every channel target holds its transforms row (and the chain
+     * was built); `false` when at least one has not taken it yet.
+     *
+     * Completing is also when the targets are handed to the GPU — see {@link register_clip}.
      *
      * @param {{
      *     clip_id: number,
-     *     channels: Array<{ track: number, target: Node3D, property: number }>,
+     *     channels: Array<{ track: number, target: number, property: number }>,
      * }} pending
      * @returns {boolean}
      */
     #try_complete_clip(pending) {
-        const id_mapping = this.#scene_context.id_mapping;
+        const rows = this.#scene_context.rows;
         const channels = pending.channels;
         const clip_id = pending.clip_id;
 
         const bindings = new Array(channels.length);
         for (let i = 0; i < channels.length; i++) {
             const ch = channels[i];
-            const instance = id_mapping.get(ch.target.id);
-            if (instance === undefined) return false;
+            const target = ch.target;
+
+            assert.isNonNegativeInteger(target, `clip channel ${i} target`);
+
+            if (!rows.has(target)) return false;
 
             bindings[i] = {
                 track: ch.track,
-                instance,
+                instance: row_of_entity(target),
                 property: ch.property,
             };
         }
@@ -1477,9 +1359,174 @@ export class GPUAnimationManager {
         // register_clip and the drain.
         this.#patch_clip_field(clip_id, 'bound_track_group_head', head_group_id);
 
+        this.#take_targets(clip_id, channels);
+
         return true;
     }
 
+    /**
+     * Hand the entities a clip drives to the GPU: the first clip to bind an entity grants its
+     * TransformAttachment authority. Counted per entity, because two clips can drive one joint
+     * and it is the GPU's until the last of them leaves.
+     *
+     * @param {number} clip_id
+     * @param {Array<{target: number}>} channels
+     */
+    #take_targets(clip_id, channels) {
+        const rows = this.#scene_context.rows;
+        const dataset = rows.dataset;
+        const driving = this.#clips_driving;
+
+        const targets = [];
+
+        for (let i = 0; i < channels.length; i++) {
+            const target = channels[i].target;
+
+            if (targets.indexOf(target) !== -1) {
+                continue;
+            }
+
+            targets.push(target);
+
+            const count = driving.get(target) ?? 0;
+
+            if (count === 0) {
+                /*
+                 The first clip to drive a joint takes its offset, and with it the joint's world
+                 and every world below: the hierarchy pass composes the subtree from the rows, and
+                 the CPU stops composing it (D4). Stated on each entity of the subtree, so a
+                 reader can be told rather than left to infer it from the joint above.
+                */
+                gpu_authority_grant(
+                    dataset,
+                    target,
+                    GPUStateAuthorityFlags.TransformAttachment | GPUStateAuthorityFlags.Transform64
+                );
+
+                rows.for_each_descendant(target, descendant => {
+                    // a prefab declares its animated subtree; an entity attached under a joint
+                    // from elsewhere is declared here, at the one moment it is taken
+                    gpu_authority_declare(dataset, descendant);
+                    gpu_authority_grant(dataset, descendant, GPUStateAuthorityFlags.Transform64);
+                });
+            }
+
+            driving.set(target, count + 1);
+        }
+
+        this.#targets_by_clip.set(clip_id, targets);
+    }
+
+    /**
+     * Whether a clip still drives `entity` or a joint above it — in which case the GPU composes
+     * its world, whatever else has been released.
+     *
+     * @param {number} entity
+     * @param {EntityComponentDataset} dataset
+     * @returns {boolean}
+     */
+    #gpu_composed(entity, dataset) {
+        const driving = this.#clips_driving;
+
+        let cursor = entity;
+
+        while (cursor !== -1) {
+            if (driving.has(cursor)) {
+                return true;
+            }
+
+            const attachment = dataset.getComponent(cursor, TransformAttachment);
+
+            if (attachment === undefined || attachment === null) {
+                return false;
+            }
+
+            cursor = attachment.parent;
+        }
+
+        return false;
+    }
+
+    /**
+     * The reverse of {@link #take_targets}: the last clip to leave an entity hands its local TRS
+     * back to the CPU, and marks the row so the next flush writes the authored offset over the
+     * pose the GPU last resolved. An entity that has since been removed is skipped.
+     *
+     * @param {number} clip_id
+     */
+    #release_targets(clip_id) {
+        const targets = this.#targets_by_clip.get(clip_id);
+
+        if (targets === undefined) {
+            return;
+        }
+
+        this.#targets_by_clip.delete(clip_id);
+
+        const rows = this.#scene_context.rows;
+        const dataset = rows.dataset;
+        const driving = this.#clips_driving;
+        const shadow = this.#playback_by_clip.get(clip_id);
+
+        for (let i = 0; i < targets.length; i++) {
+            const target = targets[i];
+            const count = driving.get(target) - 1;
+
+            if (count > 0) {
+                driving.set(target, count);
+
+                continue;
+            }
+
+            driving.delete(target);
+
+            if (!dataset.entityExists(target)) {
+                continue;
+            }
+
+            /*
+             The joint's offset comes back to the CPU seeded with the pose the clip left it in,
+             evaluated at the clip's own last time and weight — what the accumulator last
+             resolved, exactly — so the row carries on from where the GPU had it rather than
+             snapping to the rest pose. Then the world of the joint and of everything under it
+             that no other clip still drives from above, and the announcement that recomposes
+             the returned subtree on this side and marks the row.
+            */
+            const attachment = dataset.getComponent(target, TransformAttachment);
+
+            if (attachment !== undefined && attachment !== null && shadow !== undefined) {
+                SEED_PLAYBACK.clip = shadow.clip;
+                SEED_PLAYBACK.time = shadow.time;
+                SEED_PLAYBACK.weight = shadow.weight;
+
+                pose_evaluate_local(SEED, target, attachment.transform, SEED_PLAYBACKS);
+
+                SEED_PLAYBACK.clip = null;
+
+                attachment.transform.copy(SEED);
+                attachment.transform.updateMatrix();
+            }
+
+            gpu_authority_revoke(dataset, target, GPUStateAuthorityFlags.TransformAttachment);
+
+            if (!this.#gpu_composed(target, dataset)) {
+                gpu_authority_revoke(dataset, target, GPUStateAuthorityFlags.Transform64);
+            }
+
+            rows.for_each_descendant(target, descendant => {
+                if (!this.#gpu_composed(descendant, dataset)) {
+                    gpu_authority_revoke(dataset, descendant, GPUStateAuthorityFlags.Transform64);
+                }
+            });
+
+            rows.mark_local(target);
+
+            if (attachment !== undefined && attachment !== null) {
+                dataset.sendEvent(target, TRANSFORM_ATTACHMENT_EVENT_CHANGE);
+            }
+        }
+    }
+
     /**
      * Drop a clip from the manager. Walks the bindings chain and
      * removes every group-node + the clip row. Tolerates the clip
@@ -1533,7 +1580,9 @@ export class GPUAnimationManager {
 
         clips_table.remove(clip_id);
 
-        this.#scaling_clips.delete(clip_id);
+        this.#release_targets(clip_id);
+
+        this.#playback_by_clip.delete(clip_id);
     }
 
     /**
@@ -1555,8 +1604,6 @@ export class GPUAnimationManager {
     unregister_skin(skin_id) {
         assert.isNonNegativeInteger(skin_id, 'skin_id');
 
-        this.#skins_by_id.delete(skin_id);
-
         for (let i = this.#pending_skins.length - 1; i >= 0; i--) {
             if (this.#pending_skins[i].skin_id === skin_id) {
                 this.#pending_skins.splice(i, 1);
@@ -1784,9 +1831,9 @@ export class GPUAnimationManager {
      * `database.buffer`.
      *
      * Also drains the pending-registration queues: skins and clips
-     * whose dependencies (joint Node3D rows, channel-target rows)
+     * whose dependencies (joint rows, channel-target rows)
      * weren't ready at register time get one shot per `update` to
-     * complete. Once `id_mapping` has the missing rows, the
+     * complete. Once every entity has taken its row, the
      * deferred chain build runs and the registration becomes
      * observationally complete — the next-frame `database.update`
      * picks up the patched head pointer.
@@ -1919,6 +1966,8 @@ export class GPUAnimationManager {
      *
      * @param {ShadeGPUCommandContext} cmd_ctx
      * @param {number} dt_seconds wall-clock seconds since last call
+     * @returns {boolean} whether the GPU moved any row this frame — a clip applied, or a skin
+     * deformed — which is what tells the bounds and the TLAS derived from rows that they are stale
      */
     tick(cmd_ctx, dt_seconds) {
         assert.defined(cmd_ctx, 'cmd_ctx');
@@ -1952,7 +2001,13 @@ export class GPUAnimationManager {
         // are host-driven (no clips bound) must still be deformed
         // each frame, otherwise it renders bind pose forever.
         this.dispatch_skin_matrix_prep(cmd_ctx);
-        this.#scene_context.skinning.update(cmd_ctx);
+
+        const deformed = this.#scene_context.skinning.update(cmd_ctx);
+
+        // Whether anything on the GPU moved a row this frame without the CPU knowing: a clip wrote
+        // a TRS, a skinning pass moved a clone. What follows the tick — bounds, the TLAS — is
+        // derived from rows, and this is what says the derivation is stale.
+        return apply_groups > 0 || deformed;
     }
 
     /**
@@ -2048,6 +2103,14 @@ export class GPUAnimationManager {
     }
 
     destroy() {
+        // A context that goes takes the GPU with it: nothing will resolve these rows again, so
+        // every entity it drove is the CPU's from here.
+        for (const clip_id of Array.from(this.#targets_by_clip.keys())) {
+            this.#release_targets(clip_id);
+        }
+
+        this.#playback_by_clip.clear();
+
         this.#database.destroy();
         for (let i = 0; i < 2; i++) {
             if (this.#skin_matrices_buffers[i] !== null) {