@woosh/meep-engine 3.51.0 → 3.53.0

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

@@ -14,9 +14,17 @@ import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
 import { ANIMATION_CLIP_STATE_STRUCT } from "./ANIMATION_CLIP_STATE_STRUCT.js";
 import { ANIMATION_CURVE_KEYFRAME_STRUCT } from "./ANIMATION_CURVE_KEYFRAME_STRUCT.js";
 import { ANIMATION_DATABASE_SPEC } from "./ANIMATION_DATABASE_SPEC.js";
+import { ANIMATION_FOLIAGE_JOINT_STRUCT } from "./ANIMATION_FOLIAGE_JOINT_STRUCT.js";
+import { ANIMATION_FOLIAGE_RIG_STRUCT } from "./ANIMATION_FOLIAGE_RIG_STRUCT.js";
 import { ANIMATION_SKIN_JOINT_STRUCT } from "./ANIMATION_SKIN_JOINT_STRUCT.js";
 import { ANIMATION_SKIN_STRUCT } from "./ANIMATION_SKIN_STRUCT.js";
 import { ANIMATION_TRACK_BINDING_STRUCT } from "./ANIMATION_TRACK_BINDING_STRUCT.js";
+import { ShaderSwitchSet } from "../shader/compiler/ShaderSwitchSet.js";
+import { WIND_FIELD_UNIFORM } from "../wind/WIND_FIELD_UNIFORM.js";
+import {
+    shader_foliage_wind_apply,
+    WORKGROUP_SIZE as FOLIAGE_WIND_APPLY_WORKGROUP_SIZE,
+} from "./foliage/shader_foliage_wind_apply.js";
 import { AnimationClipFlags } from "./AnimationClipFlags.js";
 import { POSE_ACCUMULATOR_SLOT_BYTES } from "./POSE_ACCUMULATOR_LAYOUT.js";
 import { GPUStateAuthorityFlags } from "../../../engine/ecs/gpu/GPUStateAuthorityFlags.js";
@@ -29,6 +37,7 @@ import { gpu_authority_declare } from "../../../engine/ecs/gpu/gpu_authority_dec
 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 { Node3DProperty } from "../object_property/Node3DProperty.js";
 import { pose_evaluate_local } from "./pose/pose_evaluate_local.js";
 import { PosePlayback } from "./pose/PosePlayback.js";
 import {
@@ -107,6 +116,51 @@ function rest_rotation_of(dataset, entity) {
     return [rest.rotation_x, rest.rotation_y, rest.rotation_z, rest.rotation_w];
 }
 
+/**
+ * Write the rest value for a specific {@link Node3DProperty} into `out` (`[x, y, z, w]`).
+ *
+ * @param {number[]} out
+ * @param {Transform64} rest
+ * @param {number} property
+ * @returns {number[]} `out`
+ */
+function write_rest_for_property(out, rest, property) {
+    switch (property) {
+        case Node3DProperty.Translation:
+            out[0] = rest.translation_x;
+            out[1] = rest.translation_y;
+            out[2] = rest.translation_z;
+            out[3] = 0;
+            break;
+        case Node3DProperty.Scale:
+            out[0] = rest.scale_x;
+            out[1] = rest.scale_y;
+            out[2] = rest.scale_z;
+            out[3] = 0;
+            break;
+        case Node3DProperty.Rotation:
+        default:
+            out[0] = rest.rotation_x;
+            out[1] = rest.rotation_y;
+            out[2] = rest.rotation_z;
+            out[3] = rest.rotation_w;
+            break;
+    }
+    return out;
+}
+
+/**
+ * The rest value an entity rests at for a bound {@link Node3DProperty}, packed as `[x, y, z, w]`.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @param {number} property
+ * @returns {number[]}
+ */
+function rest_for_property(dataset, entity, property) {
+    return write_rest_for_property([0, 0, 0, 1], rest_of(dataset, entity), property);
+}
+
 /*
  Generated writers for the rows a registration adds as a run. Through `add_run` every row is a
  reflective walk of its type, and a run is one row per keyframe, binding or joint where a chain
@@ -117,6 +171,14 @@ function rest_rotation_of(dataset, entity) {
 const KEYFRAME_WRITER = generate_record_writer(ANIMATION_CURVE_KEYFRAME_STRUCT);
 const BINDING_WRITER = generate_record_writer(ANIMATION_TRACK_BINDING_STRUCT);
 const SKIN_JOINT_WRITER = generate_record_writer(ANIMATION_SKIN_JOINT_STRUCT);
+const FOLIAGE_JOINT_WRITER = generate_record_writer(ANIMATION_FOLIAGE_JOINT_STRUCT);
+const FOLIAGE_RIG_WEIGHT_WRITER = generate_record_writer(ANIMATION_FOLIAGE_RIG_STRUCT, ['weight']);
+const FOLIAGE_RIG_COMPLETE_WRITER = generate_record_writer(ANIMATION_FOLIAGE_RIG_STRUCT, ['joints_first', 'joint_count', 'root_node']);
+const FOLIAGE_JOINT_NODE_WRITER = generate_record_writer(ANIMATION_FOLIAGE_JOINT_STRUCT, ['node']);
+const FOLIAGE_JOINT_UNMUTE_WRITER = generate_record_writer(ANIMATION_FOLIAGE_JOINT_STRUCT, ['node', 'rest_rotation']);
+const FOLIAGE_RIG_JOINTS_FIRST_WORD = ANIMATION_FOLIAGE_RIG_STRUCT.get('joints_first').offset / 4;
+const FOLIAGE_JOINT_NODE = { node: 0 };
+const FOLIAGE_JOINT_UNMUTE = { node: 0, rest_rotation: [0, 0, 0, 1] };
 
 /*
  Writers for the fields of a clip that change after registration, each owning only its own words.
@@ -354,9 +416,10 @@ function skin_content_equals(skin, joints, inverse_bind_matrices) {
 export class GPUAnimationManager {
 
     /**
-     * Offer the pipelines {@link tick} runs on every frame: the transform hierarchy, which composes
-     * world matrices whether or not anything is animated — see {@link PipelineEnquiry}. The clip,
-     * pose and skinning passes are left to the first frame that has a clip or a skin.
+     * Offer the pipelines {@link tick} runs on every frame: the
+     * transform hierarchy — see {@link PipelineEnquiry}. The clip,
+     * pose and skinning passes are left to the first frame that has a
+     * clip or a skin.
      *
      * @param {PipelineEnquiry} enquiry
      */
@@ -626,6 +689,35 @@ export class GPUAnimationManager {
      */
     #pending_clips = [];
 
+    /**
+     * Foliage wind rigs registered via {@link register_foliage_rig} whose target entities have not
+     * all taken their scene-database transform rows yet.
+     *
+     * @type {Array<{ rig_id: number, rig: import("./foliage/FoliageWindRig.js").FoliageWindRig }>}
+     */
+    #pending_foliage_rigs = [];
+
+    /**
+     * Bound foliage wind rigs driving each entity, by entity id.
+     *
+     * @type {Map<number, number[]>}
+     */
+    #foliage_rigs_driving = new Map();
+
+    /**
+     * Distinct target entities driven by each completed foliage wind rig, by rig id.
+     *
+     * @type {Map<number, number[]>}
+     */
+    #targets_by_foliage_rig = new Map();
+
+    /**
+     * CPU shadow record of each registered foliage wind rig, by rig id.
+     *
+     * @type {Map<number, { rig: import("./foliage/FoliageWindRig.js").FoliageWindRig, weight: number }>}
+     */
+    #foliage_rig_by_id = new Map();
+
     /**
      * @param {GPUDevice} device
      * @param {string} label
@@ -1521,7 +1613,7 @@ export class GPUAnimationManager {
                 clip: clip_id,
                 // a held target's rest is the holder's pose of the moment, taken again when the
                 // hold ends: see #unmute
-                rest_rotation: rest_rotation_of(rows.dataset, target),
+                rest_rotation: rest_for_property(rows.dataset, target, ch.property),
             };
         }
 
@@ -1568,31 +1660,33 @@ export class GPUAnimationManager {
 
                 driving.set(target, clips);
 
-                /*
-                 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
-                );
-
-                // The offset as it stands is the clip's rest, and the row's on every axis it does
-                // not key: an announcement still waiting for the flush is skipped once the bit is set.
-                rows.mark_handover(target);
-
-                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);
-                });
-
-                // A CPU writer may hold the offset now or later; it says so on the entity.
-                dataset.addEntityEventListener(target, GPU_AUTHORITY_EVENT_HOLD_CHANGE, this.#hold_changed, this);
+                if (!this.#foliage_rigs_driving.has(target)) {
+                    /*
+                     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
+                    );
+
+                    // The offset as it stands is the clip's rest, and the row's on every axis it does
+                    // not key: an announcement still waiting for the flush is skipped once the bit is set.
+                    rows.mark_handover(target);
+
+                    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);
+                    });
+
+                    // A CPU writer may hold the offset now or later; it says so on the entity.
+                    dataset.addEntityEventListener(target, GPU_AUTHORITY_EVENT_HOLD_CHANGE, this.#hold_changed, this);
+                }
             }
 
             clips.push(clip_id);
@@ -1611,11 +1705,12 @@ export class GPUAnimationManager {
      */
     #gpu_composed(entity, dataset) {
         const driving = this.#clips_driving;
+        const foliage_driving = this.#foliage_rigs_driving;
 
         let cursor = entity;
 
         while (cursor !== -1) {
-            if (driving.has(cursor)) {
+            if (driving.has(cursor) || foliage_driving.has(cursor)) {
                 return true;
             }
 
@@ -1664,6 +1759,10 @@ export class GPUAnimationManager {
 
             driving.delete(target);
 
+            if (this.#foliage_rigs_driving.has(target)) {
+                continue;
+            }
+
             if (!dataset.entityExists(target)) {
                 continue;
             }
@@ -1776,6 +1875,10 @@ export class GPUAnimationManager {
         BINDING_INSTANCE.instance = GPU_DATABASE_NULL;
 
         this.#write_bindings(entity, BINDING_INSTANCE, BINDING_INSTANCE_WRITER);
+
+        FOLIAGE_JOINT_NODE.node = GPU_DATABASE_NULL;
+
+        this.#write_foliage_joints(entity, FOLIAGE_JOINT_NODE, FOLIAGE_JOINT_NODE_WRITER);
     }
 
     /**
@@ -1795,15 +1898,36 @@ export class GPUAnimationManager {
     #unmute(entity, dataset) {
         const rest = rest_of(dataset, entity);
         const rest_rotation = BINDING_UNMUTE.rest_rotation;
+        const row = row_of_entity(entity);
 
-        BINDING_UNMUTE.instance = row_of_entity(entity);
+        BINDING_UNMUTE.instance = row;
 
-        rest_rotation[0] = rest.rotation_x;
-        rest_rotation[1] = rest.rotation_y;
-        rest_rotation[2] = rest.rotation_z;
-        rest_rotation[3] = rest.rotation_w;
+        const clips = this.#clips_driving.get(entity);
+        if (clips !== undefined) {
+            const clips_table = this.#database.get('animation_clips');
+            const bindings = this.#database.get('animation_bindings');
+
+            for (let c = 0; c < clips.length; c++) {
+                const clip_id = clips[c];
+                const first = clips_table.get_word(clip_id, CLIP_BINDINGS_FIRST_WORD);
+                const channels = this.#playback_by_clip.get(clip_id).clip.channels;
+
+                for (let i = 0; i < channels.length; i++) {
+                    if (channels[i].target === entity) {
+                        write_rest_for_property(rest_rotation, rest, channels[i].property);
+                        bindings.set_fields(first + i, BINDING_UNMUTE, BINDING_UNMUTE_WRITER);
+                    }
+                }
+            }
+        }
+
+        FOLIAGE_JOINT_UNMUTE.node = row;
+        FOLIAGE_JOINT_UNMUTE.rest_rotation[0] = rest.rotation_x;
+        FOLIAGE_JOINT_UNMUTE.rest_rotation[1] = rest.rotation_y;
+        FOLIAGE_JOINT_UNMUTE.rest_rotation[2] = rest.rotation_z;
+        FOLIAGE_JOINT_UNMUTE.rest_rotation[3] = rest.rotation_w;
 
-        this.#write_bindings(entity, BINDING_UNMUTE, BINDING_UNMUTE_WRITER);
+        this.#write_foliage_joints(entity, FOLIAGE_JOINT_UNMUTE, FOLIAGE_JOINT_UNMUTE_WRITER);
     }
 
     /**
@@ -1882,6 +2006,285 @@ export class GPUAnimationManager {
         this.#playback_by_clip.delete(clip_id);
     }
 
+    /**
+     * Register a {@link FoliageWindRig} whose joints and root address ECS entities.
+     *
+     * Allocates a row in `animation_foliage_rigs` immediately. Once `rig.root` and every joint's
+     * `target` entity hold rows in `GPUSceneRows`, adds the run of `animation_foliage_joints`
+     * records and grants `GPUStateAuthority` on the driven joints.
+     *
+     * @param {import("./foliage/FoliageWindRig.js").FoliageWindRig} rig
+     * @returns {number} foliage rig id (index into `animation_foliage_rigs`)
+     */
+    register_foliage_rig(rig) {
+        assert.defined(rig, 'rig');
+        assert.equal(rig.isFoliageWindRig, true, 'rig.isFoliageWindRig !== true');
+        assert.isNonNegativeInteger(rig.root, 'rig.root');
+        assert.greaterThanOrEqual(rig.joints.length, 1, 'foliage rig must have at least one joint');
+
+        const cloned = rig.clone();
+        const weight = typeof cloned.weight === 'number' ? cloned.weight : 1.0;
+
+        const rigs_table = this.#database.get('animation_foliage_rigs');
+        const rig_id = rigs_table.add({
+            joints_first: GPU_DATABASE_NULL,
+            joint_count: 0,
+            root_node: GPU_DATABASE_NULL,
+            weight,
+        });
+
+        this.#foliage_rig_by_id.set(rig_id, { rig: cloned, weight });
+
+        const pending = { rig_id, rig: cloned };
+        if (!this.#try_complete_foliage_rig(pending)) {
+            this.#pending_foliage_rigs.push(pending);
+        }
+
+        return rig_id;
+    }
+
+    /**
+     * Update a registered foliage wind rig's contribution weight.
+     *
+     * @param {number} rig_id
+     * @param {number} weight
+     */
+    set_foliage_rig_weight(rig_id, weight) {
+        assert.isNonNegativeInteger(rig_id, 'rig_id');
+        assert.isNumber(weight, 'weight');
+
+        const rigs_table = this.#database.get('animation_foliage_rigs');
+        assert.equal(rigs_table.occupancy.get(rig_id), true, `Invalid foliage rig_id: ${rig_id} (not allocated)`);
+
+        rigs_table.set_fields(rig_id, { weight }, FOLIAGE_RIG_WEIGHT_WRITER);
+
+        const shadow = this.#foliage_rig_by_id.get(rig_id);
+        if (shadow !== undefined) {
+            shadow.weight = weight;
+        }
+    }
+
+    /**
+     * Drop a foliage wind rig from the manager: removes its row in `animation_foliage_rigs`
+     * (and with it the owned run in `animation_foliage_joints`) and releases GPU authority on
+     * its target entities. Safe to call repeatedly on the same id.
+     *
+     * @param {number} rig_id
+     */
+    unregister_foliage_rig(rig_id) {
+        assert.isNonNegativeInteger(rig_id, 'rig_id');
+
+        for (let i = this.#pending_foliage_rigs.length - 1; i >= 0; i--) {
+            if (this.#pending_foliage_rigs[i].rig_id === rig_id) {
+                this.#pending_foliage_rigs.splice(i, 1);
+            }
+        }
+
+        const rigs_table = this.#database.get('animation_foliage_rigs');
+        if (!rigs_table.occupancy.get(rig_id)) return;
+
+        rigs_table.remove(rig_id);
+
+        this.#release_foliage_targets(rig_id);
+
+        this.#foliage_rig_by_id.delete(rig_id);
+    }
+
+    /**
+     * @param {{ rig_id: number, rig: import("./foliage/FoliageWindRig.js").FoliageWindRig }} pending
+     * @returns {boolean}
+     */
+    #try_complete_foliage_rig(pending) {
+        const rows = this.#scene_context.rows;
+        const dataset = rows.dataset;
+        const rig = pending.rig;
+        const rig_id = pending.rig_id;
+
+        if (!rows.has(rig.root)) {
+            return false;
+        }
+
+        const src_joints = rig.joints;
+        const records = new Array(src_joints.length);
+
+        for (let i = 0; i < src_joints.length; i++) {
+            const j = src_joints[i];
+            const target = j.target;
+            assert.isNonNegativeInteger(target, `foliage rig joint ${i} target`);
+
+            if (!rows.has(target)) {
+                return false;
+            }
+
+            records[i] = {
+                rest_rotation: rest_rotation_of(dataset, target),
+                branch_axis: j.branch_axis,
+                compliance: j.compliance,
+                angular_displacement: [0, 0, 0],
+                natural_frequency: j.natural_frequency,
+                angular_velocity: [0, 0, 0],
+                damping_ratio: j.damping_ratio,
+                node: gpu_authority_held(dataset, target, GPUStateAuthorityFlags.TransformAttachment)
+                    ? GPU_DATABASE_NULL
+                    : row_of_entity(target),
+                rig: rig_id,
+                max_angle: j.max_angle,
+                turbulence: j.turbulence,
+                flutter_phase: j.flutter_phase ?? 0,
+            };
+        }
+
+        const joints_first = this.#database.get('animation_foliage_joints').add_run_records(records, FOLIAGE_JOINT_WRITER);
+
+        this.#database.get('animation_foliage_rigs').set_fields(
+            rig_id,
+            {
+                joints_first,
+                joint_count: records.length,
+                root_node: row_of_entity(rig.root),
+            },
+            FOLIAGE_RIG_COMPLETE_WRITER
+        );
+
+        this.#take_foliage_targets(rig_id, src_joints);
+
+        return true;
+    }
+
+    /**
+     * @param {number} rig_id
+     * @param {Array<{target: number}>} joints
+     */
+    #take_foliage_targets(rig_id, joints) {
+        const rows = this.#scene_context.rows;
+        const dataset = rows.dataset;
+        const driving = this.#foliage_rigs_driving;
+
+        const targets = [];
+
+        for (let i = 0; i < joints.length; i++) {
+            const target = joints[i].target;
+            if (targets.indexOf(target) !== -1) {
+                continue;
+            }
+            targets.push(target);
+
+            let rigs = driving.get(target);
+            if (rigs === undefined) {
+                rigs = [];
+                driving.set(target, rigs);
+
+                if (!this.#clips_driving.has(target)) {
+                    gpu_authority_declare(dataset, target);
+                    gpu_authority_grant(
+                        dataset,
+                        target,
+                        GPUStateAuthorityFlags.TransformAttachment | GPUStateAuthorityFlags.Transform64
+                    );
+
+                    rows.mark_handover(target);
+
+                    rows.for_each_descendant(target, descendant => {
+                        gpu_authority_declare(dataset, descendant);
+                        gpu_authority_grant(dataset, descendant, GPUStateAuthorityFlags.Transform64);
+                    });
+
+                    dataset.addEntityEventListener(target, GPU_AUTHORITY_EVENT_HOLD_CHANGE, this.#hold_changed, this);
+                }
+            }
+
+            rigs.push(rig_id);
+        }
+
+        this.#targets_by_foliage_rig.set(rig_id, targets);
+    }
+
+    /**
+     * @param {number} rig_id
+     */
+    #release_foliage_targets(rig_id) {
+        const targets = this.#targets_by_foliage_rig.get(rig_id);
+        if (targets === undefined) {
+            return;
+        }
+
+        this.#targets_by_foliage_rig.delete(rig_id);
+
+        const rows = this.#scene_context.rows;
+        const dataset = rows.dataset;
+        const driving = this.#foliage_rigs_driving;
+
+        for (let i = 0; i < targets.length; i++) {
+            const target = targets[i];
+            const rigs = driving.get(target);
+
+            rigs.splice(rigs.indexOf(rig_id), 1);
+
+            if (rigs.length > 0) {
+                continue;
+            }
+
+            driving.delete(target);
+
+            if (this.#clips_driving.has(target)) {
+                continue;
+            }
+
+            if (!dataset.entityExists(target)) {
+                continue;
+            }
+
+            dataset.removeEntityEventListener(target, GPU_AUTHORITY_EVENT_HOLD_CHANGE, this.#hold_changed, this);
+
+            const attachment = dataset.getComponent(target, TransformAttachment);
+
+            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);
+            }
+        }
+    }
+
+    /**
+     * @param {number} entity
+     * @param {object} fields
+     * @param {GPURecordWriter} writer
+     */
+    #write_foliage_joints(entity, fields, writer) {
+        const rigs = this.#foliage_rigs_driving.get(entity);
+        if (rigs === undefined) {
+            return;
+        }
+
+        const rigs_table = this.#database.get('animation_foliage_rigs');
+        const joints_table = this.#database.get('animation_foliage_joints');
+
+        for (let r = 0; r < rigs.length; r++) {
+            const rig_id = rigs[r];
+            const first = rigs_table.get_word(rig_id, FOLIAGE_RIG_JOINTS_FIRST_WORD);
+            const joints = this.#foliage_rig_by_id.get(rig_id).rig.joints;
+
+            for (let i = 0; i < joints.length; i++) {
+                if (joints[i].target === entity) {
+                    joints_table.set_fields(first + i, fields, writer);
+                }
+            }
+        }
+    }
+
     /**
      * Drop a skin from the manager: its row, and with it the run of its joints — the skin's range
      * owns the run, so the table removes it — and every skinning binding pointing at this skin (so
@@ -2174,6 +2577,7 @@ export class GPUAnimationManager {
     update(cmd_ctx) {
         this.#drain_pending_skins();
         this.#drain_pending_clips();
+        this.#drain_pending_foliage_rigs();
         this.#database.update(cmd_ctx);
     }
 
@@ -2195,6 +2599,14 @@ export class GPUAnimationManager {
         }
     }
 
+    #drain_pending_foliage_rigs() {
+        for (let i = this.#pending_foliage_rigs.length - 1; i >= 0; i--) {
+            if (this.#try_complete_foliage_rig(this.#pending_foliage_rigs[i])) {
+                this.#pending_foliage_rigs.splice(i, 1);
+            }
+        }
+    }
+
     /**
      * Run the per-frame skin-matrix-prep dispatch and advance the
      * ping-pong. Replaces the manual `shader_skin_matrix_prep.dispatch`
@@ -2359,13 +2771,16 @@ export class GPUAnimationManager {
         // Flush database + drain pending registrations.
         this.update(cmd_ctx);
 
-        // Only clip evaluation is conditional. Every scene needs current globals.
+        // Only clip / foliage wind evaluation is conditional. Every scene needs current globals.
         const apply_groups = this.#database
             .get('animation_bindings')
             .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
+        const foliage_groups = this.#database
+            .get('animation_foliage_joints')
+            .dispatch_group_count(FOLIAGE_WIND_APPLY_WORKGROUP_SIZE);
 
-        if (apply_groups > 0) {
-            this.#encode_clip_passes(cmd_ctx, dt, apply_groups);
+        if (apply_groups > 0 || foliage_groups > 0) {
+            this.#encode_clip_passes(cmd_ctx, dt, apply_groups, foliage_groups);
         } else {
             // CPU uploads seed global with the previous pose. Even without clips,
             // compose current globals and advance prev_global before skinning/rendering.
@@ -2384,37 +2799,40 @@ export class GPUAnimationManager {
         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;
+        // a TRS, a foliage wind bone deflected, or a skinning pass moved a clone.
+        return apply_groups > 0 || foliage_groups > 0 || deformed;
     }
 
     /**
-     * Encode the clip-driven passes: GPU tick (advances
-     * `clip.time`), track apply into the pose accumulator, pose
-     * resolve into node TRS, and transform-hierarchy propagation.
-     * Split out of {@link tick} so the skin passes there run
-     * independently of the bound-track early-out.
+     * Encode the clip-driven and foliage-fluid-wind passes: GPU tick (advances
+     * `clip.time`), track apply and/or foliage fluid wind apply into the pose
+     * accumulator, pose resolve into node TRS, and transform-hierarchy propagation.
      *
      * @param {ShadeGPUCommandContext} cmd_ctx
      * @param {number} dt clamped delta time, seconds
-     * @param {number} apply_groups dispatch group count for the
-     *     apply pass — caller guarantees `> 0`
+     * @param {number} apply_groups dispatch group count for the clip apply pass
+     * @param {number} [foliage_groups=0] dispatch group count for the foliage wind apply pass
      */
-    #encode_clip_passes(cmd_ctx, dt, apply_groups) {
+    #encode_clip_passes(cmd_ctx, dt, apply_groups, foliage_groups = 0) {
         // Tick: advance clip.time on the GPU.
-        const tick_groups = this.#database
-            .get('animation_clips')
-            .dispatch_group_count(ANIMATION_TICK_WORKGROUP_SIZE);
-        if (tick_groups > 0) {
-            shader_animation_tick.dispatch({
-                encoder: cmd_ctx,
-                group_count_x: tick_groups,
-                bindings: {
-                    dt,
-                    animation_database: this.#database.buffer,
-                },
-            });
+        if (apply_groups > 0) {
+            const tick_groups = this.#database
+                .get('animation_clips')
+                .dispatch_group_count(ANIMATION_TICK_WORKGROUP_SIZE);
+            if (tick_groups > 0) {
+                shader_animation_tick.dispatch({
+                    encoder: cmd_ctx,
+                    group_count_x: tick_groups,
+                    bindings: {
+                        dt,
+                        animation_database: this.#database.buffer,
+                    },
+                });
+            }
+        }
+
+        if (foliage_groups > 0 && this.#scene_context.wind) {
+            this.#scene_context.wind.update();
         }
 
         // Size the pose accumulator to cover every allocated row of
@@ -2426,7 +2844,7 @@ export class GPUAnimationManager {
         );
         this.ensure_pose_accumulator_capacity(transforms_table.element_capacity);
 
-        // ── Frame graph: apply → pose resolve → hierarchy propagate
+        // ── Frame graph: apply → foliage_wind_apply → pose resolve → hierarchy propagate
         const graph = new FrameGraph("GPUAnimationManager/Tick");
         const gr_animation_database = graph_import_buffer(
             graph, this.#database.buffer, "animation_database"
@@ -2434,28 +2852,59 @@ export class GPUAnimationManager {
         const gr_scene_database = graph_import_buffer(
             graph, this.#scene_context.scene_database_buffer, "scene_database"
         );
-        const gr_materials = graph_import_buffer(
-            graph, this.#scene_context.materials.metadata_table.buffer, "materials"
-        );
         const gr_pose_accumulator = graph_import_buffer(
             graph, this.#pose_accumulator_buffer, "pose_accumulator"
         );
 
-        const apply_data = {};
-        const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
-            shader_animation_apply.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: apply_groups,
-                bindings: {
+        let last_pose_accumulator = gr_pose_accumulator;
+
+        if (apply_groups > 0) {
+            const gr_materials = graph_import_buffer(
+                graph, this.#scene_context.materials.metadata_table.buffer, "materials"
+            );
+            const apply_data = {};
+            const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
+                shader_animation_apply.dispatch({
+                    encoder: ctx.encoder,
+                    group_count_x: apply_groups,
+                    bindings: {
+                        animation_database: resources.get(data.animation_database),
+                        pose_accumulator: resources.get(data.pose_accumulator),
+                        materials: resources.get(data.materials),
+                    },
+                });
+            });
+            apply_data.animation_database = apply_pass.read(gr_animation_database);
+            apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
+            apply_data.pose_accumulator = apply_pass.write(apply_pass.read(last_pose_accumulator));
+            last_pose_accumulator = apply_data.pose_accumulator;
+        }
+
+        if (foliage_groups > 0) {
+            const foliage_data = {};
+            const foliage_pass = graph.add("animation/foliage_wind_apply", foliage_data, (data, resources, ctx) => {
+                const bindings = {
+                    dt,
+                    scene_database: resources.get(data.scene_database),
                     animation_database: resources.get(data.animation_database),
                     pose_accumulator: resources.get(data.pose_accumulator),
-                    materials: resources.get(data.materials),
-                },
+                };
+                this.#scene_context.wind.bind(bindings);
+                const switches = ShaderSwitchSet.EMPTY.with(
+                    WIND_FIELD_UNIFORM,
+                    this.#scene_context.wind.cascade_count === 0
+                );
+                shader_foliage_wind_apply.variant(switches).dispatch({
+                    encoder: ctx.encoder,
+                    group_count_x: foliage_groups,
+                    bindings,
+                });
             });
-        });
-        apply_data.animation_database = apply_pass.read(gr_animation_database);
-        apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
-        apply_data.pose_accumulator = apply_pass.write(apply_pass.read(gr_pose_accumulator));
+            foliage_data.scene_database = foliage_pass.read(gr_scene_database);
+            foliage_data.animation_database = foliage_pass.write(foliage_pass.read(gr_animation_database));
+            foliage_data.pose_accumulator = foliage_pass.write(foliage_pass.read(last_pose_accumulator));
+            last_pose_accumulator = foliage_data.pose_accumulator;
+        }
 
         const resolve_data = {};
         const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
@@ -2470,7 +2919,7 @@ export class GPUAnimationManager {
             });
         });
         resolve_data.scene_database = resolve_pass.write(resolve_pass.read(gr_scene_database));
-        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(apply_data.pose_accumulator));
+        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(last_pose_accumulator));
 
         graph_scene_update_transform_hierarchy({
             graph,
@@ -2487,8 +2936,12 @@ export class GPUAnimationManager {
         for (const clip_id of Array.from(this.#targets_by_clip.keys())) {
             this.#release_targets(clip_id);
         }
+        for (const rig_id of Array.from(this.#targets_by_foliage_rig.keys())) {
+            this.#release_foliage_targets(rig_id);
+        }
 
         this.#playback_by_clip.clear();
+        this.#foliage_rig_by_id.clear();
 
         this.#database.destroy();
         for (let i = 0; i < 2; i++) {