@woosh/meep-engine 3.51.0 → 3.53.0

package/src/engine/graphics3/AnimationSystem.js

@@ -1,34 +1,37 @@
-import { assert } from "../../core/assert.js";
 import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
-import { PosePlayback } from "../../shade/renderer/animation/pose/PosePlayback.js";
 import { Animation } from "../ecs/animation/Animation.js";
 import { System } from "../ecs/System.js";
 import { AnimationClips } from "./animation/AnimationClips.js";
+import { AnimationClipsSink } from "./animation/AnimationClipsSink.js";
 import { ClipListPlayer } from "./animation/ClipListPlayer.js";
-import { write_clip_playback } from "./animation/write_clip_playback.js";
-import { hold_clip_targets, register_clips, release_clip_targets, unregister_clips } from "./register_clips.js";
-import { RowChains } from "./RowChains.js";
 
 /**
  * @type {ClipPlayback[]}
  */
 const NOTHING = Object.freeze([]);
 
+/**
+ * Scratch list for collecting each tick's played slot indices without allocating.
+ *
+ * @type {number[]}
+ */
+const PLAYED_SLOTS = [];
+
 /**
  * Drives every entity's {@link Animation} component: runs the clocks of the clips its list names,
- * and tells the renderer what each of them weighs and where it is playing.
+ * writes their weights and times into the entity's {@link AnimationClips}, and hands that blend to
+ * the renderer through {@link AnimationClipsSink}.
  *
  * The list path is what the game uses wherever there is no state machine — buildings, critters and
  * the strategy map's groups — and {@link ClipListPlayer} is what plays it. This is the ECS half:
- * which clips each entity has, and when the ids the renderer issued for them stopped meaning
- * anything.
+ * which clips each entity has, and syncing the component's playback sink with the GPU.
  *
  * **The clips are the entity's {@link AnimationClips}.** An entity is driven while it carries both
  * components, whoever put them there — a model `MeshSystem` loaded, or a rig built in code. New
  * clips are a new component, which this system sees as the entity leaving and coming back.
  *
- * **Every node the clips key holds a row here** ({@link hold_clip_targets}), from the clips being
+ * **Every node the clips key holds a row here** ({@link AnimationClipsSink}), from the clips being
  * taken up until they go. A clip binds only once all of them do, and a keyed node outside every skin
  * with nothing drawn under it is held by no other system.
  *
@@ -44,29 +47,15 @@ const NOTHING = Object.freeze([]);
  */
 export class AnimationSystem extends System {
     /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * The scene whose GPU context issues the clip ids.
-     *
-     * @type {Scene}
+     * @type {AnimationClipsSink}
      */
-    #scene;
+    #sink;
 
     /**
-     * @type {Map<number, {player: ClipListPlayer, clips: ShadeAnimationClip[], bound: boolean, held: boolean, clip_registration: ClipRegistration|null, played_slots: Int32Array, written: Float32Array, poses: PosePlayback[]}>}
+     * @type {Map<number, {player: ClipListPlayer, clips: AnimationClips, bound: boolean}>}
      */
     #entries = new Map();
 
-    /**
-     * The chains of the nodes the clips key. Null until the system has a dataset.
-     *
-     * @type {RowChains|null}
-     */
-    #chains = null;
-
     /**
      * @param {GraphicsEngine} graphics
      * @param {Scene} scene
@@ -74,18 +63,16 @@ export class AnimationSystem extends System {
     constructor(graphics, scene) {
         super();
 
-        assert.defined(graphics, 'graphics');
-        assert.equal(scene?.isScene, true, 'scene.isScene !== true');
-
-        this.#graphics = graphics;
-        this.#scene = scene;
+        this.#sink = new AnimationClipsSink(graphics, scene);
 
         this.dependencies = [Animation, AnimationClips];
 
-        // this tick's clip times are this system's to set: whatever evaluates a pose from them
-        // (exact queries, IK's base pose) reads Animation and so runs after it
+        // this tick's clip times and weights are written onto AnimationClips: whatever evaluates a
+        // pose from them (exact queries, IK's base pose, contact probes) reads AnimationClips and
+        // so runs after it
         this.components_used = [
             ResourceAccessSpecification.from(Animation, ResourceAccessKind.Read | ResourceAccessKind.Write),
+            ResourceAccessSpecification.from(AnimationClips, ResourceAccessKind.Read | ResourceAccessKind.Write),
         ];
     }
 
@@ -109,18 +96,8 @@ export class AnimationSystem extends System {
     }
 
     /**
-     * What the entity is playing, in the form the CPU pose evaluator takes: one entry per clip of its
-     * {@link AnimationClips} that the list names, at the weight and the time the renderer has been
-     * given.
-     *
-     * **Only the clips the list 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.
-     *
-     * The entries are this system's own and are rewritten by the next call, which is what keeps a
-     * query on a per-frame path from allocating.
+     * What the entity is playing, in the form the CPU pose evaluator takes: delegates to the
+     * entity's {@link AnimationClips#write_pose_playbacks}.
      *
      * @param {PosePlayback[]} target appended to
      * @param {number} entity
@@ -135,36 +112,7 @@ export class AnimationSystem extends System {
             return false;
         }
 
-        const clips = entry.clips;
-        const weights = entry.player.weights;
-        const poses = entry.poses;
-        const played = entry.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];
-
-            // a clip the list names but has stopped playing is where it stopped, and at weight zero
-            // that is nowhere in particular
-            pose.time = 0;
-        }
-
-        const playbacks = entry.player.playbacks;
-
-        for (let i = 0; i < playbacks.length; i++) {
-            const playback = playbacks[i];
-
-            poses[playback.slot].time = playback.time;
-        }
-
-        for (let i = 0; i < played.length; i++) {
-            target.push(poses[played[i]]);
-        }
-
-        return true;
+        return entry.clips.write_pose_playbacks(target);
     }
 
     /**
@@ -179,13 +127,8 @@ export class AnimationSystem extends System {
     link(component, clips, entity) {
         this.#entries.set(entity, {
             player: ClipListPlayer.from(component),
-            clips: clips.clips,
+            clips,
             bound: false,
-            held: false,
-            clip_registration: null,
-            played_slots: new Int32Array(0),
-            written: new Float32Array(0),
-            poses: []
         });
     }
 
@@ -197,179 +140,66 @@ export class AnimationSystem extends System {
     unlink(component, clips, entity) {
         const entry = this.#entries.get(entity);
 
-        if (entry !== undefined) {
-            this.#release_clips(entry);
-
-            if (entry.held) {
-                release_clip_targets(this.#chains, entry.clips);
-
-                entry.held = false;
-            }
+        if (entry !== undefined && entry.bound) {
+            this.#sink.release(entry.clips);
         }
 
         this.#entries.delete(entity);
     }
 
     async startup(entityManager) {
-        // the scene's rows are this dataset's entities; the first system to place one says so
-        const dataset = entityManager.dataset;
-        const scene = this.#scene;
-
-        assert.ok(
-            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
-            'the scene is bound to another dataset'
-        );
-
-        scene.dataset = dataset;
-
-        this.#chains = new RowChains(dataset);
+        this.#sink.startup(entityManager.dataset);
     }
 
     async shutdown(entityManager) {
         for (const entry of this.#entries.values()) {
-            this.#release_clips(entry);
+            if (entry.bound) {
+                this.#sink.unbind_on_shutdown(entry.clips);
+            }
         }
 
         this.#entries.clear();
 
-        this.#chains.destroy();
-        this.#chains = null;
-    }
-
-    /**
-     * Give this entity's clips back, if the manager that issued them is still the one running.
-     *
-     * **An id may only be handed back to the manager that issued it.** A renderer restart replaces
-     * the GPU scene context and voids every id it gave out, so a registration stamped with a context
-     * that is no longer current is forgotten rather than returned.
-     *
-     * @param {object} entry
-     */
-    #release_clips(entry) {
-        this.#release_clips_only(entry);
-
-        entry.played_slots = new Int32Array(0);
-    }
-
-    /**
-     * The registration alone, leaving {@link #refresh_played_slots}'s answer where it is — which is
-     * what a re-registration wants, since the set it is about to register with is the current one.
-     *
-     * @param {object} entry
-     */
-    #release_clips_only(entry) {
-        const registration = entry.clip_registration;
-
-        if (registration === null) {
-            return;
-        }
-
-        if (registration.context === this.#graphics.scene_context(this.#scene)) {
-            unregister_clips(registration);
-        }
-
-        entry.clip_registration = null;
+        this.#sink.shutdown();
     }
 
     /**
-     * Which of the entity's clips the list currently names, kept up to date.
+     * Copy the player's current blend into the entity's {@link AnimationClips} sink.
      *
      * **The list is edited while the game runs** — `ClipListPlayer` reconciles its playbacks against
      * it every tick, and `StopAnimationBehavior` empties it outright — so which clips are playable
-     * is not settled once at bind.
-     *
-     * Maintained here rather than alongside the registration because **the pose evaluator needs it
-     * whether or not there is a device**: `collect_entity_playbacks` answers on the CPU, from the
-     * clips this driver plays, and a game with rendering disabled still asks (I-4).
+     * is refreshed every tick as well.
      *
-     * @param {object} entry
-     * @returns {boolean} whether the set changed
+     * @param {ClipListPlayer} player
+     * @param {AnimationClips} clips
+     * @returns {boolean} whether the distinct set of played slots changed
      */
-    #refresh_played_slots(entry) {
-        const playbacks = entry.player.playbacks;
-        const played = entry.played_slots;
+    #write_playback(player, clips) {
+        const playbacks = player.playbacks;
+        const weights = clips.weights;
+        const times = clips.times;
+        const slots = PLAYED_SLOTS;
 
-        /*
-         The distinct slots, and distinct is the point: two entries of the list can name one clip, so
-         the number of playbacks is not the number of clips. Comparing the two would report a change
-         on every frame for a list that had not moved, and a change here is a re-registration.
-        */
-        const wanted = [];
+        weights.set(player.weights);
+        times.fill(0);
+        slots.length = 0;
 
         for (let i = 0; i < playbacks.length; i++) {
-            const slot = playbacks[i].slot;
-
-            if (wanted.indexOf(slot) === -1) {
-                wanted.push(slot);
-            }
-        }
-
-        if (wanted.length === played.length) {
-            let same = true;
+            const playback = playbacks[i];
+            const slot = playback.slot;
 
-            for (let i = 0; i < wanted.length; i++) {
-                if (played[i] !== wanted[i]) {
-                    same = false;
-                    break;
-                }
-            }
+            slots.push(slot);
 
-            if (same) {
-                return false;
+            if (playback.weight > 0 || times[slot] === 0) {
+                times[slot] = playback.time;
             }
         }
 
-        entry.played_slots = Int32Array.from(wanted);
+        const changed = clips.set_played_slots(slots);
 
-        return true;
-    }
+        slots.length = 0;
 
-    /**
-     * Keep the registered clips equal to the ones the list names.
-     *
-     * A clip that leaves the list has to be unregistered, or it stays bound at weight zero and takes
-     * the joints only it drives down to zero with it.
-     *
-     * @param {object} entry
-     * @param {GPUSceneContext} context
-     * @param {boolean} set_changed whether {@link #refresh_played_slots} just moved
-     * @returns {boolean} whether the registration was replaced
-     */
-    #refresh_clips(entry, context, set_changed) {
-        const registration = entry.clip_registration;
-
-        if (!set_changed && registration !== null && registration.context === context) {
-            return false;
-        }
-
-        this.#release_clips_only(entry);
-
-        entry.clip_registration = register_clips(context, entry.clips, entry.played_slots);
-
-        return true;
-    }
-
-    /**
-     * Take up the entity's clips: the list is played against them from here on.
-     *
-     * @param {object} entry
-     * @param {number} entity
-     * @param {EntityComponentDataset} ecd
-     */
-    #bind(entry, entity, ecd) {
-        const clips = entry.clips;
-
-        entry.player.bind(entity, ecd, clips);
-
-        entry.written = new Float32Array(clips.length).fill(-1);
-        entry.poses = clips.map(() => new PosePlayback());
-
-        entry.bound = true;
-
-        // before anything registers, so the clips bind in the update that registers them
-        hold_clip_targets(this.#chains, clips);
-
-        entry.held = true;
+        return changed;
     }
 
     /**
@@ -377,35 +207,24 @@ export class AnimationSystem extends System {
      */
     update(time_delta_seconds) {
         const ecd = this.entityManager.dataset;
-
-        const context = this.#graphics.scene_context(this.#scene);
-
-        // No device — before the first start, and again after a stop. The clocks still run: a clip
-        // that ends while the renderer is being replaced still says so.
-        const manager = context === null ? null : context.animation_manager;
-
-        // a new context after a restart is acquired in whole; until there is one, holds are recorded
-        this.#chains.bind(context === null ? null : context.rows);
+        const context = this.#sink.begin_update();
 
         for (const [entity, entry] of this.#entries) {
-            if (!entry.bound) {
-                this.#bind(entry, entity, ecd);
-            }
+            const { player, clips } = entry;
 
-            entry.player.tick(time_delta_seconds);
+            if (!entry.bound) {
+                player.bind(entity, ecd, clips.clips);
 
-            const set_changed = this.#refresh_played_slots(entry);
+                this.#sink.bind(clips);
 
-            if (context === null) {
-                continue;
+                entry.bound = true;
             }
 
-            if (this.#refresh_clips(entry, context, set_changed)) {
-                // whatever the last registration was told is not what this one knows
-                entry.written.fill(-1);
-            }
+            player.tick(time_delta_seconds);
+
+            const set_changed = this.#write_playback(player, clips);
 
-            write_clip_playback(manager, entry.player, entry.clip_registration.ids, entry.written);
+            this.#sink.sync(clips, context, set_changed);
         }
     }
 }

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

@@ -0,0 +1,67 @@
+/**
+ * @typedef {import("../../shade/ShadeGraphicsEngine.js").ShadeGraphicsEngine} ShadeGraphicsEngine
+ * @typedef {import("../../shade/PublicScene.js").PublicScene} PublicScene
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig} FoliageWindRig
+ */
+/**
+ * @typedef {object} FoliageWindEntry
+ * @property {FoliageWindRigs} component
+ * @property {FoliageWindRig[]} rigs
+ * @property {GPUSceneContext|null} context
+ * @property {Int32Array|null} rig_ids
+ * @property {number} written_weight
+ */
+/**
+ * Registers every entity carrying {@link FoliageWindRigs} with the scene's
+ * {@link GPUAnimationManager}, so that procedural foliage skeletons deform in real time under
+ * the scene's 3D fluid dynamics cascades and global wind field (`GPUSceneWind`).
+ *
+ * **Rows.** Each rig's `root` entity and every `joint.target` entity are held in this system's
+ * {@link RowChains}, along with the transform chain above them, so every bone has a live
+ * `transforms` row on the GPU before {@link GPUAnimationManager#register_foliage_rig} binds it.
+ *
+ * **Lifecycle & Restart.** Mirrors {@link MeshSkinSystem}: rigs linked while a device is live
+ * register immediately; rigs linked before the renderer starts (or across a WebGPU device restart)
+ * bind and register on the next {@link update}. Changes to {@link FoliageWindRigs#weight} are
+ * propagated to {@link GPUAnimationManager#set_foliage_rig_weight} each frame.
+ */
+export class FoliageWindSystem extends System<any> {
+    /**
+     * @param {ShadeGraphicsEngine} graphics
+     * @param {PublicScene} scene
+     */
+    constructor(graphics: any, scene: any);
+    dependencies: (typeof Transform64 | typeof FoliageWindRigs)[];
+    startup(entityManager: any): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * @param {FoliageWindRigs} component
+     * @param {Transform64} _transform
+     * @param {number} entity
+     */
+    link(component: FoliageWindRigs, _transform: Transform64, entity: number): void;
+    /**
+     * @param {FoliageWindRigs} _component
+     * @param {Transform64} _transform
+     * @param {number} entity
+     */
+    unlink(_component: FoliageWindRigs, _transform: Transform64, entity: number): void;
+    update(): void;
+    #private;
+}
+export type ShadeGraphicsEngine = any;
+export type PublicScene = any;
+export type GPUSceneContext = import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext;
+export type FoliageWindRig = import("../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig;
+export type FoliageWindEntry = {
+    component: FoliageWindRigs;
+    rigs: FoliageWindRig[];
+    context: GPUSceneContext | null;
+    rig_ids: Int32Array | null;
+    written_weight: number;
+};
+import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { FoliageWindRigs } from "./animation/FoliageWindRigs.js";
+//# sourceMappingURL=FoliageWindSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageWindSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/FoliageWindSystem.js"],"names":[],"mappings":"AAMA;;;;;GAKG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;GAaG;AACH;IA0BI;;;OAGG;IACH,uCAUC;IADG,8DAAkD;IAGtD,2CAYC;IAED,0BAUC;IAED;;;;OAIG;IACH,gBAJW,eAAe,cACf,WAAW,UACX,MAAM,QAkChB;IAED;;;;OAIG;IACH,mBAJW,eAAe,cACf,WAAW,UACX,MAAM,QA0BhB;IAED,eAoCC;;CA8CJ;;;8BAvPY,OAAO,+CAA+C,EAAE,eAAe;6BACvE,OAAO,0DAA0D,EAAE,cAAc;;eAKhF,eAAe;UACf,cAAc,EAAE;aAChB,eAAe,GAAC,IAAI;aACpB,UAAU,GAAC,IAAI;oBACf,MAAM;;uBAlBG,kBAAkB;4BACb,iCAAiC;gCAC7B,gCAAgC"}