@woosh/meep-engine 3.52.0 → 3.54.0

package/src/engine/graphics3/animation/AnimationClips.d.ts

@@ -1,19 +1,18 @@
 /**
- * @typedef {import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
- */
-/**
- * The clips this entity can play: each a {@link ShadeAnimationClip} whose channels key entities —
- * the joints of a rig, the nodes of a loaded model.
+ * The clips this entity can play — each a {@link ShadeAnimationClip} whose channels key entities
+ * (the joints of a rig, the nodes of a loaded model) — and the playback sink where whichever driver
+ * plays them writes what each weighs and where it is playing this tick.
  *
  * **It lives on the entity that plays them**, beside its `Animation` or `AnimationGraphController`.
  * A clip is one clock over many targets and describes no single one of them, so it is not a
  * component on a joint. `AnimationSystem` and `AnimationGraphSystem` resolve the names their lists
- * and graphs ask for against this set. The CPU pose consumers (IK, ContactProbe, cloth) ask those
- * drivers about a joint's `ParentEntity`, so a joint they should see names this entity there.
+ * and graphs ask for against this set and write the resulting blend back onto it; the GPU clip
+ * uploader and the CPU pose consumers (IK, ContactProbe, cloth, `query_entity_node_world_pose`)
+ * read from here without caring which driver produced the blend.
  *
  * **Not `Animation.clips`.** That list says what to play — a name, a weight, a repeat count each;
- * this says what there is to play and what each of those does to which entity. A name in the one is
- * looked up by name in the other.
+ * this says what there is to play, what each of those does to which entity, and where the active
+ * driver has placed each clip this frame.
  *
  * A model loaded by `MeshSystem` carries one on its root, re-addressed to the entities of that
  * placement; code that builds a rig puts one there the same way. A model with no clips carries an
@@ -23,10 +22,10 @@
  * clip, take the component off and put another on, which the drivers see as their entity leaving
  * and coming back.
  *
- * **The entities it keys go no sooner than it does.** While it is on, the drivers hold a row for
- * every entity a channel keys, as a skin holds its joints'. Removing one of them means taking this
- * off before the next frame — `prefab_instance_destroy` removes the entities and then the clips, in
- * one step — or the scene is left holding the row of an entity that is gone.
+ * **The entities it keys go no sooner than it does.** While it is bound, the driver's sink holds a
+ * row for every entity a channel keys, as a skin holds its joints'. Removing one of them means
+ * taking this off before the next frame — `prefab_instance_destroy` removes the entities and then
+ * the clips, in one step — or the scene is left holding the row of an entity that is gone.
  *
  * **Not saved**, for the reason `MeshSkin` is not: the channels key entities that whatever builds
  * the rig creates, and the curves are asset data. A load rebuilds them the way it rebuilds the rig.
@@ -47,6 +46,99 @@ export class AnimationClips {
      * @type {ShadeAnimationClip[]}
      */
     clips: ShadeAnimationClip[];
+    /**
+     * Whether a driver currently has these clips bound. `false` before the driver's first `update`
+     * after `link`, and `false` again once the driver unlinks or shuts down.
+     *
+     * @type {boolean}
+     */
+    bound: boolean;
+    /**
+     * Distinct indices into {@link clips} that the active driver plays (and registers on the GPU),
+     * in the driver's own order.
+     *
+     * Maintained here rather than alongside the GPU registration because **the pose evaluator needs
+     * it whether or not there is a device**: `collect_entity_playbacks` answers on the CPU from the
+     * clips the driver plays, and a game with rendering disabled still asks (I-4).
+     *
+     * @type {Int32Array}
+     */
+    played_slots: Int32Array;
+    /**
+     * What each of {@link clips} weighs this tick, in {@link clips}' order and at `f32` width — the
+     * width the renderer's clip table takes, so the CPU pose evaluator and the GPU agree on every
+     * share.
+     *
+     * @type {Float32Array}
+     */
+    weights: Float32Array;
+    /**
+     * Where each of {@link clips} is playing this tick, in seconds from its start, in {@link clips}'
+     * order.
+     *
+     * @type {Float64Array}
+     */
+    times: Float64Array;
+    /**
+     * One reusable {@link PosePlayback} per entry of {@link clips}, rewritten by
+     * {@link write_pose_playbacks} so per-frame CPU pose queries allocate nothing.
+     *
+     * @type {PosePlayback[]}
+     */
+    poses: PosePlayback[];
+    /**
+     * The active GPU registration for {@link played_slots}, or `null` when no device context has
+     * registered them yet.
+     *
+     * @type {ClipRegistration|null}
+     */
+    clip_registration: ClipRegistration | null;
+    /**
+     * The weight each entry of {@link clips} was last given on the GPU (`-1` where not yet written
+     * to the current registration).
+     *
+     * @type {Float32Array}
+     */
+    written: Float32Array;
+    /**
+     * Prepare the playback buffers when a driver takes up these clips.
+     */
+    bind(): void;
+    /**
+     * Clear the playback state when the driver releases these clips.
+     */
+    unbind(): void;
+    /**
+     * Update which of {@link clips} the driver plays, deduplicated in order of first appearance.
+     *
+     * Two entries of a clip list or two states of a graph can name one clip, and it is one row on
+     * the GPU either way — registered once, and reported to the pose evaluator once.
+     *
+     * @param {ArrayLike<number>} slots indices into {@link clips}
+     * @returns {boolean} whether the distinct set changed
+     */
+    set_played_slots(slots: ArrayLike<number>): boolean;
+    /**
+     * What the entity is playing, in the form the CPU pose evaluator takes: one entry per clip of
+     * {@link clips} in {@link played_slots}, at the weight and the time the renderer has been given.
+     *
+     * **Only the clips the driver names are here, because they are the only ones registered** (D37).
+     * The GPU's accumulator marks a joint dirty for every bound clip that writes to it, weight and
+     * all — so a bound clip at weight zero resolves the joints only it drives to zero rather than
+     * leaving them at rest. The answer is not to hand the surplus to the evaluator so it agrees
+     * with a mistake; it is not to bind them, and then a clip nothing names moves nothing.
+     *
+     * A clip the driver names that is not currently playing **is** here, at weight zero, because it
+     * is bound and the accumulator does see it.
+     *
+     * The entries are this component's own and are rewritten by the next call, which is what keeps
+     * a query on a per-frame path from allocating.
+     *
+     * @param {PosePlayback[]} target appended to
+     * @returns {boolean} whether a driver has bound these clips — `false` when no driver is playing
+     * them, or when they arrived since the driver's last update
+     */
+    write_pose_playbacks(target: PosePlayback[]): boolean;
     /**
      * @readonly
      * @type {boolean}
@@ -58,4 +150,6 @@ export namespace AnimationClips {
     let serializable: boolean;
 }
 export type ShadeAnimationClip = import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip;
+export type ClipRegistration = import("../register_clips.js").ClipRegistration;
+import { PosePlayback } from "../../../shade/renderer/animation/pose/PosePlayback.js";
 //# sourceMappingURL=AnimationClips.d.ts.map

package/src/engine/graphics3/animation/AnimationClips.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationClips.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/animation/AnimationClips.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IASI;;;OAGG;IACH,mBAHW,kBAAkB,EAAE,GAClB,cAAc,CAc1B;IAxBD;;;;;OAKG;IACH,OAFU,kBAAkB,EAAE,CAEnB;IAqBf;;;OAGG;IACH,2BAFU,OAAO,CAEwB;CANxC;;kBAUS,MAAM;sBAMN,OAAO;;iCA9EJ,OAAO,yDAAyD,EAAE,kBAAkB"}
+{"version":3,"file":"AnimationClips.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/animation/AnimationClips.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IAsEI;;;OAGG;IACH,mBAHW,kBAAkB,EAAE,GAClB,cAAc,CAc1B;IArFD;;;;;OAKG;IACH,OAFU,kBAAkB,EAAE,CAEnB;IAEX;;;;;OAKG;IACH,OAFU,OAAO,CAEH;IAEd;;;;;;;;;OASG;IACH,cAFU,UAAU,CAEO;IAE3B;;;;;;OAMG;IACH,SAFU,YAAY,CAEE;IAExB;;;;;OAKG;IACH,OAFU,YAAY,CAEF;IAEpB;;;;;OAKG;IACH,OAFU,YAAY,EAAE,CAEb;IAEX;;;;;OAKG;IACH,mBAFU,gBAAgB,GAAC,IAAI,CAEN;IAEzB;;;;;OAKG;IACH,SAFU,YAAY,CAEE;IAoBxB;;OAEG;IACH,aAWC;IAED;;OAEG;IACH,eAQC;IAED;;;;;;;;OAQG;IACH,wBAHW,UAAU,MAAM,CAAC,GACf,OAAO,CAsCnB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,6BAJW,YAAY,EAAE,GACZ,OAAO,CA0BnB;IAGL;;;OAGG;IACH,2BAFU,OAAO,CAEwB;CANxC;;kBAUS,MAAM;sBAMN,OAAO;;iCAlRJ,OAAO,yDAAyD,EAAE,kBAAkB;+BACpF,OAAO,sBAAsB,EAAE,gBAAgB;6BAJ/B,wDAAwD"}

package/src/engine/graphics3/animation/AnimationClips.js

@@ -1,22 +1,37 @@
 import { assert } from "../../../core/assert.js";
+import { PosePlayback } from "../../../shade/renderer/animation/pose/PosePlayback.js";
 
 /**
  * @typedef {import("../../../shade/renderer/animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("../register_clips.js").ClipRegistration} ClipRegistration
  */
 
+const EMPTY_SLOTS = new Int32Array(0);
+const EMPTY_WEIGHTS = new Float32Array(0);
+const EMPTY_TIMES = new Float64Array(0);
+
+/**
+ * Scratch list for deduplicating played slot indices without allocating when the set is unchanged.
+ *
+ * @type {number[]}
+ */
+const WANTED_SLOTS = [];
+
 /**
- * The clips this entity can play: each a {@link ShadeAnimationClip} whose channels key entities —
- * the joints of a rig, the nodes of a loaded model.
+ * The clips this entity can play — each a {@link ShadeAnimationClip} whose channels key entities
+ * (the joints of a rig, the nodes of a loaded model) — and the playback sink where whichever driver
+ * plays them writes what each weighs and where it is playing this tick.
  *
  * **It lives on the entity that plays them**, beside its `Animation` or `AnimationGraphController`.
  * A clip is one clock over many targets and describes no single one of them, so it is not a
  * component on a joint. `AnimationSystem` and `AnimationGraphSystem` resolve the names their lists
- * and graphs ask for against this set. The CPU pose consumers (IK, ContactProbe, cloth) ask those
- * drivers about a joint's `ParentEntity`, so a joint they should see names this entity there.
+ * and graphs ask for against this set and write the resulting blend back onto it; the GPU clip
+ * uploader and the CPU pose consumers (IK, ContactProbe, cloth, `query_entity_node_world_pose`)
+ * read from here without caring which driver produced the blend.
  *
  * **Not `Animation.clips`.** That list says what to play — a name, a weight, a repeat count each;
- * this says what there is to play and what each of those does to which entity. A name in the one is
- * looked up by name in the other.
+ * this says what there is to play, what each of those does to which entity, and where the active
+ * driver has placed each clip this frame.
  *
  * A model loaded by `MeshSystem` carries one on its root, re-addressed to the entities of that
  * placement; code that builds a rig puts one there the same way. A model with no clips carries an
@@ -26,10 +41,10 @@ import { assert } from "../../../core/assert.js";
  * clip, take the component off and put another on, which the drivers see as their entity leaving
  * and coming back.
  *
- * **The entities it keys go no sooner than it does.** While it is on, the drivers hold a row for
- * every entity a channel keys, as a skin holds its joints'. Removing one of them means taking this
- * off before the next frame — `prefab_instance_destroy` removes the entities and then the clips, in
- * one step — or the scene is left holding the row of an entity that is gone.
+ * **The entities it keys go no sooner than it does.** While it is bound, the driver's sink holds a
+ * row for every entity a channel keys, as a skin holds its joints'. Removing one of them means
+ * taking this off before the next frame — `prefab_instance_destroy` removes the entities and then
+ * the clips, in one step — or the scene is left holding the row of an entity that is gone.
  *
  * **Not saved**, for the reason `MeshSkin` is not: the channels key entities that whatever builds
  * the rig creates, and the curves are asset data. A load rebuilds them the way it rebuilds the rig.
@@ -46,6 +61,67 @@ export class AnimationClips {
      */
     clips = [];
 
+    /**
+     * Whether a driver currently has these clips bound. `false` before the driver's first `update`
+     * after `link`, and `false` again once the driver unlinks or shuts down.
+     *
+     * @type {boolean}
+     */
+    bound = false;
+
+    /**
+     * Distinct indices into {@link clips} that the active driver plays (and registers on the GPU),
+     * in the driver's own order.
+     *
+     * Maintained here rather than alongside the GPU registration because **the pose evaluator needs
+     * it whether or not there is a device**: `collect_entity_playbacks` answers on the CPU from the
+     * clips the driver plays, and a game with rendering disabled still asks (I-4).
+     *
+     * @type {Int32Array}
+     */
+    played_slots = EMPTY_SLOTS;
+
+    /**
+     * What each of {@link clips} weighs this tick, in {@link clips}' order and at `f32` width — the
+     * width the renderer's clip table takes, so the CPU pose evaluator and the GPU agree on every
+     * share.
+     *
+     * @type {Float32Array}
+     */
+    weights = EMPTY_WEIGHTS;
+
+    /**
+     * Where each of {@link clips} is playing this tick, in seconds from its start, in {@link clips}'
+     * order.
+     *
+     * @type {Float64Array}
+     */
+    times = EMPTY_TIMES;
+
+    /**
+     * One reusable {@link PosePlayback} per entry of {@link clips}, rewritten by
+     * {@link write_pose_playbacks} so per-frame CPU pose queries allocate nothing.
+     *
+     * @type {PosePlayback[]}
+     */
+    poses = [];
+
+    /**
+     * The active GPU registration for {@link played_slots}, or `null` when no device context has
+     * registered them yet.
+     *
+     * @type {ClipRegistration|null}
+     */
+    clip_registration = null;
+
+    /**
+     * The weight each entry of {@link clips} was last given on the GPU (`-1` where not yet written
+     * to the current registration).
+     *
+     * @type {Float32Array}
+     */
+    written = EMPTY_WEIGHTS;
+
     /**
      * @param {ShadeAnimationClip[]} clips may be empty
      * @returns {AnimationClips}
@@ -63,6 +139,127 @@ export class AnimationClips {
 
         return r;
     }
+
+    /**
+     * Prepare the playback buffers when a driver takes up these clips.
+     */
+    bind() {
+        const clips = this.clips;
+        const count = clips.length;
+
+        this.played_slots = EMPTY_SLOTS;
+        this.weights = new Float32Array(count);
+        this.times = new Float64Array(count);
+        this.poses = clips.map(clip => PosePlayback.from(clip, 0, 0));
+        this.clip_registration = null;
+        this.written = new Float32Array(count).fill(-1);
+        this.bound = true;
+    }
+
+    /**
+     * Clear the playback state when the driver releases these clips.
+     */
+    unbind() {
+        this.bound = false;
+        this.played_slots = EMPTY_SLOTS;
+        this.weights = EMPTY_WEIGHTS;
+        this.times = EMPTY_TIMES;
+        this.poses = [];
+        this.clip_registration = null;
+        this.written = EMPTY_WEIGHTS;
+    }
+
+    /**
+     * Update which of {@link clips} the driver plays, deduplicated in order of first appearance.
+     *
+     * Two entries of a clip list or two states of a graph can name one clip, and it is one row on
+     * the GPU either way — registered once, and reported to the pose evaluator once.
+     *
+     * @param {ArrayLike<number>} slots indices into {@link clips}
+     * @returns {boolean} whether the distinct set changed
+     */
+    set_played_slots(slots) {
+        const played = this.played_slots;
+        const wanted = WANTED_SLOTS;
+
+        wanted.length = 0;
+
+        for (let i = 0; i < slots.length; i++) {
+            const slot = slots[i];
+
+            if (wanted.indexOf(slot) === -1) {
+                wanted.push(slot);
+            }
+        }
+
+        if (wanted.length === played.length) {
+            let same = true;
+
+            for (let i = 0; i < wanted.length; i++) {
+                if (played[i] !== wanted[i]) {
+                    same = false;
+                    break;
+                }
+            }
+
+            if (same) {
+                wanted.length = 0;
+
+                return false;
+            }
+        }
+
+        this.played_slots = Int32Array.from(wanted);
+
+        wanted.length = 0;
+
+        return true;
+    }
+
+    /**
+     * What the entity is playing, in the form the CPU pose evaluator takes: one entry per clip of
+     * {@link clips} in {@link played_slots}, at the weight and the time the renderer has been given.
+     *
+     * **Only the clips the driver names are here, because they are the only ones registered** (D37).
+     * The GPU's accumulator marks a joint dirty for every bound clip that writes to it, weight and
+     * all — so a bound clip at weight zero resolves the joints only it drives to zero rather than
+     * leaving them at rest. The answer is not to hand the surplus to the evaluator so it agrees
+     * with a mistake; it is not to bind them, and then a clip nothing names moves nothing.
+     *
+     * A clip the driver names that is not currently playing **is** here, at weight zero, because it
+     * is bound and the accumulator does see it.
+     *
+     * The entries are this component's own and are rewritten by the next call, which is what keeps
+     * a query on a per-frame path from allocating.
+     *
+     * @param {PosePlayback[]} target appended to
+     * @returns {boolean} whether a driver has bound these clips — `false` when no driver is playing
+     * them, or when they arrived since the driver's last update
+     */
+    write_pose_playbacks(target) {
+        if (!this.bound) {
+            return false;
+        }
+
+        const clips = this.clips;
+        const weights = this.weights;
+        const times = this.times;
+        const poses = this.poses;
+        const played = this.played_slots;
+
+        for (let i = 0; i < played.length; i++) {
+            const slot = played[i];
+            const pose = poses[slot];
+
+            pose.clip = clips[slot];
+            pose.weight = weights[slot];
+            pose.time = times[slot];
+
+            target.push(pose);
+        }
+
+        return true;
+    }
 }
 
 /**

package/src/engine/graphics3/animation/AnimationClipsSink.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../../shade/renderer/scene/Scene.js").Scene} Scene
+ * @typedef {import("../GraphicsEngine.js").GraphicsEngine} GraphicsEngine
+ * @typedef {import("./AnimationClips.js").AnimationClips} AnimationClips
+ */
+/**
+ * Connects an animation driver (`AnimationSystem` or `AnimationGraphSystem`) to the scene's GPU
+ * context for every {@link AnimationClips} component the driver plays:
+ *
+ * - **Holds a row chain for every node the clips key** ({@link hold_clip_targets}), from the clips
+ *   being bound until they go. A clip binds on the GPU only once every node it keys holds a row, and
+ *   a keyed node outside every skin with nothing drawn under it is held by no other system.
+ * - **Registers only the clips the driver names** ({@link AnimationClips#played_slots}), and
+ *   re-registers when that set moves or when a renderer restart replaces the GPU scene context.
+ * - **Pushes this tick's weights and times** from {@link AnimationClips} to
+ *   {@link GPUAnimationManager} via {@link write_clip_playback}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AnimationClipsSink {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics: GraphicsEngine, scene: Scene);
+    /**
+     * Bind the scene to the dataset and start tracking row chains for keyed nodes.
+     *
+     * @param {EntityComponentDataset} dataset
+     */
+    startup(dataset: EntityComponentDataset): void;
+    /**
+     * Release the GPU registration and playback state of one {@link AnimationClips} during system
+     * shutdown, leaving row-chain teardown to {@link shutdown}.
+     *
+     * @param {AnimationClips} clips
+     */
+    unbind_on_shutdown(clips: AnimationClips): void;
+    /**
+     * Tear down the row chains on system shutdown.
+     */
+    shutdown(): void;
+    /**
+     * Bind the row chains to the current GPU context's rows and answer that context.
+     *
+     * No device — before the first start, and again after a stop — answers `null`. The driver's
+     * clocks still run; holds are recorded and acquired in whole when a context arrives.
+     *
+     * @returns {GPUSceneContext|null}
+     */
+    begin_update(): GPUSceneContext | null;
+    /**
+     * Take up an entity's {@link AnimationClips}: allocate its playback buffers and hold a row chain
+     * for every node its channels key.
+     *
+     * Called before anything registers, so the clips bind on the GPU in the update that registers
+     * them.
+     *
+     * @param {AnimationClips} clips
+     */
+    bind(clips: AnimationClips): void;
+    /**
+     * Let go of an entity's {@link AnimationClips}: return its GPU registration if the manager that
+     * issued it is still current, release the row chains held for its targets, and clear its
+     * playback state.
+     *
+     * @param {AnimationClips} clips
+     */
+    release(clips: AnimationClips): void;
+    /**
+     * Keep the GPU registration equal to {@link AnimationClips#played_slots} on the current context,
+     * and write this tick's weights and times down to the animation manager.
+     *
+     * @param {AnimationClips} clips
+     * @param {GPUSceneContext|null} context
+     * @param {boolean} slots_changed whether {@link AnimationClips#played_slots} changed this tick
+     */
+    sync(clips: AnimationClips, context: GPUSceneContext | null, slots_changed: boolean): void;
+    #private;
+}
+export type EntityComponentDataset = import("../../ecs/EntityComponentDataset.js").EntityComponentDataset;
+export type GPUSceneContext = import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+export type Scene = import("../../../shade/renderer/scene/Scene.js").Scene;
+export type GraphicsEngine = import("../GraphicsEngine.js").GraphicsEngine;
+export type AnimationClips = import("./AnimationClips.js").AnimationClips;
+//# sourceMappingURL=AnimationClipsSink.d.ts.map

package/src/engine/graphics3/animation/AnimationClipsSink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationClipsSink.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/animation/AnimationClipsSink.js"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IAoBI;;;OAGG;IACH,sBAHW,cAAc,SACd,KAAK,EAQf;IAED;;;;OAIG;IACH,iBAFW,sBAAsB,QAchC;IAED;;;;;OAKG;IACH,0BAFW,cAAc,QAMxB;IAED;;OAEG;IACH,iBAGC;IAED;;;;;;;OAOG;IACH,gBAFa,eAAe,GAAC,IAAI,CAShC;IAED;;;;;;;;OAQG;IACH,YAFW,cAAc,QAUxB;IAED;;;;;;OAMG;IACH,eAFW,cAAc,QAYxB;IAED;;;;;;;OAOG;IACH,YAJW,cAAc,WACd,eAAe,GAAC,IAAI,iBACpB,OAAO,QAmBjB;;CAyBJ;qCAtMY,OAAO,qCAAqC,EAAE,sBAAsB;8BACpE,OAAO,kDAAkD,EAAE,eAAe;oBAC1E,OAAO,wCAAwC,EAAE,KAAK;6BACtD,OAAO,sBAAsB,EAAE,cAAc;6BAC7C,OAAO,qBAAqB,EAAE,cAAc"}