@woosh/meep-engine 3.51.0 → 3.53.0

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"}

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

@@ -0,0 +1,205 @@
+import { assert } from "../../../core/assert.js";
+import { hold_clip_targets, register_clips, release_clip_targets, unregister_clips } from "../register_clips.js";
+import { RowChains } from "../RowChains.js";
+import { write_clip_playback } from "./write_clip_playback.js";
+
+/**
+ * @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 {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * The scene whose GPU context issues the clip ids.
+     *
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * The chains of the nodes the clips key. Null until the driver has a dataset.
+     *
+     * @type {RowChains|null}
+     */
+    #chains = null;
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        assert.defined(graphics, 'graphics');
+        assert.equal(scene?.isScene, true, 'scene.isScene !== true');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    /**
+     * Bind the scene to the dataset and start tracking row chains for keyed nodes.
+     *
+     * @param {EntityComponentDataset} dataset
+     */
+    startup(dataset) {
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        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);
+    }
+
+    /**
+     * 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) {
+        this.#release_registration(clips);
+
+        clips.unbind();
+    }
+
+    /**
+     * Tear down the row chains on system shutdown.
+     */
+    shutdown() {
+        this.#chains.destroy();
+        this.#chains = null;
+    }
+
+    /**
+     * 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() {
+        const context = this.#graphics.scene_context(this.#scene);
+
+        // 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);
+
+        return context;
+    }
+
+    /**
+     * 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) {
+        if (clips.bound) {
+            this.release(clips);
+        }
+
+        clips.bind();
+
+        hold_clip_targets(this.#chains, clips.clips);
+    }
+
+    /**
+     * 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) {
+        if (!clips.bound) {
+            return;
+        }
+
+        this.#release_registration(clips);
+
+        release_clip_targets(this.#chains, clips.clips);
+
+        clips.unbind();
+    }
+
+    /**
+     * 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, context, slots_changed) {
+        if (context === null) {
+            return;
+        }
+
+        const registration = clips.clip_registration;
+
+        if (slots_changed || registration === null || registration.context !== context) {
+            this.#release_registration(clips);
+
+            clips.clip_registration = register_clips(context, clips.clips, clips.played_slots);
+
+            // whatever the last registration was told is not what this one knows
+            clips.written.fill(-1);
+        }
+
+        write_clip_playback(context.animation_manager, clips);
+    }
+
+    /**
+     * Give these clips' registration back, if the manager that issued it 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 — returning it would corrupt a
+     * stranger's table.
+     *
+     * @param {AnimationClips} clips
+     */
+    #release_registration(clips) {
+        const registration = clips.clip_registration;
+
+        if (registration === null) {
+            return;
+        }
+
+        if (registration.context === this.#graphics.scene_context(this.#scene)) {
+            unregister_clips(registration);
+        }
+
+        clips.clip_registration = null;
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * The procedural foliage wind rigs a model came with, re-addressed to one placed instance's entities.
+ *
+ * **What it is for.** {@link prefab_instantiate} puts one of these on the root of a placed foliage
+ * model when the prefab carries {@link Prefab#foliage_rigs}, with every joint's `target` and the
+ * rig's `root` rewritten from the prefab's node index to the entity that node became in the
+ * instance. {@link FoliageWindSystem} pairs it with a {@link Transform64} on the same entity:
+ * `FoliageWindRigs` is *what* aeroelastic bone rigs the tree has and their blend weight, and
+ * `FoliageWindSystem` registers them with {@link GPUAnimationManager} and holds their scene rows.
+ */
+export class FoliageWindRigs {
+    /**
+     * @param {FoliageWindRig[]} [rigs]
+     * @param {number} [weight=1]
+     * @returns {FoliageWindRigs}
+     */
+    static from(rigs?: FoliageWindRig[], weight?: number): FoliageWindRigs;
+    /**
+     * Each rig's `root` and every joint's `target` are entity ids in the dataset this component
+     * lives in.
+     *
+     * @type {FoliageWindRig[]}
+     */
+    rigs: FoliageWindRig[];
+    /**
+     * Blend weight applied to all foliage wind rigs on this entity in `[0, 1]` (or `>= 0`). Setting
+     * `weight = 0` disables wind contribution in `GPUAnimationManager`'s pose accumulator.
+     *
+     * @type {number}
+     */
+    weight: number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isFoliageWindRigs: boolean;
+}
+export namespace FoliageWindRigs {
+    let typeName: string;
+    let serializable: boolean;
+}
+import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
+//# sourceMappingURL=FoliageWindRigs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageWindRigs.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/animation/FoliageWindRigs.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH;IAiBI;;;;OAIG;IACH,mBAJW,cAAc,EAAE,WAChB,MAAM,GACJ,eAAe,CAgB3B;IAnCD;;;;;OAKG;IACH,MAFU,cAAc,EAAE,CAEhB;IAEV;;;;;OAKG;IACH,QAFU,MAAM,CAEL;IAwBf;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;;kBAUS,MAAM;sBAMN,OAAO;;+BAjEc,6DAA6D"}

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

@@ -0,0 +1,69 @@
+import { assert } from "../../../core/assert.js";
+import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
+
+/**
+ * The procedural foliage wind rigs a model came with, re-addressed to one placed instance's entities.
+ *
+ * **What it is for.** {@link prefab_instantiate} puts one of these on the root of a placed foliage
+ * model when the prefab carries {@link Prefab#foliage_rigs}, with every joint's `target` and the
+ * rig's `root` rewritten from the prefab's node index to the entity that node became in the
+ * instance. {@link FoliageWindSystem} pairs it with a {@link Transform64} on the same entity:
+ * `FoliageWindRigs` is *what* aeroelastic bone rigs the tree has and their blend weight, and
+ * `FoliageWindSystem` registers them with {@link GPUAnimationManager} and holds their scene rows.
+ */
+export class FoliageWindRigs {
+    /**
+     * Each rig's `root` and every joint's `target` are entity ids in the dataset this component
+     * lives in.
+     *
+     * @type {FoliageWindRig[]}
+     */
+    rigs = [];
+
+    /**
+     * Blend weight applied to all foliage wind rigs on this entity in `[0, 1]` (or `>= 0`). Setting
+     * `weight = 0` disables wind contribution in `GPUAnimationManager`'s pose accumulator.
+     *
+     * @type {number}
+     */
+    weight = 1;
+
+    /**
+     * @param {FoliageWindRig[]} [rigs]
+     * @param {number} [weight=1]
+     * @returns {FoliageWindRigs}
+     */
+    static from(rigs = [], weight = 1) {
+        assert.isArray(rigs, 'rigs');
+        assert.isNumber(weight, 'weight');
+
+        for (let i = 0; i < rigs.length; i++) {
+            assert.isInstanceOf(rigs[i], FoliageWindRig, `rigs[${i}]`);
+        }
+
+        const r = new FoliageWindRigs();
+
+        r.rigs = rigs;
+        r.weight = weight;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+FoliageWindRigs.prototype.isFoliageWindRigs = true;
+
+/**
+ * @readonly
+ * @type {string}
+ */
+FoliageWindRigs.typeName = "FoliageWindRigs";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+FoliageWindRigs.serializable = false;