@woosh/meep-engine 3.52.0 → 3.54.0

package/src/shade/renderer/animation/ADDITIVE_BLENDING_PLAN.md

@@ -0,0 +1,145 @@
+# Unified Rest-Anchored Delta Animation Blending
+
+**Status:** Approved & Implemented (Zero Runtime Switches / Enums)
+
+## 1. Core Insight: Why Bone Masks, Override Layers, and Runtime Blend Enums Are Not Needed
+
+In traditional engines where animations are dense full-skeleton arrays, combining a lower-body
+animation with an upper-body or additive animation requires runtime **bone masks**, an explicit
+**override layer mode**, and a runtime **additive vs. absolute clip switch**.
+
+`meep-engine` needs none of these:
+1. **`ShadeAnimationClip` is already sparse per-node and per-axis.** A clip's `channels` array only
+   contains entries for the specific entities (joints) and axes it keys. An upper-body clip with
+   only upper-body channels leaves every lower-body joint untouched. Any per-bone feathering (e.g.
+   `Spine_01` moving 30% as much as `Spine_03`) is naturally authored into the keyframe curves.
+2. **Every clip in the runtime is evaluated as a weighted delta from the target joint's Rest Pose
+   ($V_{\text{rest}}$).**
+   Instead of accumulating raw $w_i \cdot V_i(t)$ into a zero-based slot (which collapses
+   translation and scale toward zero whenever $\sum w_i < 1$, and ignores partial weights on single
+   rotation clips), the apply pass accumulates weighted **deltas from rest**
+   $w_i \cdot (V_i(t) - V_{\text{rest}})$ and the resolve pass adds the accumulated delta back onto
+   $V_{\text{rest}}$:
+   $$V_{\text{final}} = V_{\text{rest}} + \sum_i w_i \cdot \bigl(V_i(t) - V_{\text{rest}}\bigr)$$
+   (with $R_{\text{final}} = \text{normalize}(R_{\text{rest}} + \sum_i w_i \cdot (R_i(t) - R_{\text{rest}}))$ for rotation).
+
+---
+
+## 2. Adversarial Pass on the Zero-Runtime-Switch Design
+
+### 2.1. Why Naive "Import-Only Zero-Centered Deltas" Fail on a Zero-Based Accumulator
+Suppose we kept the old zero-based accumulator ($V_{\text{final}} = \sum_i w_i V_i(t)$) and tried to
+bake additive clips at import time as raw zero-centered deltas $\Delta V(t) = V(t) - V_{\text{ref}}$:
+- **Failure 1 (Unkeyed Base Channels / `clip.optimize`):** `load_gltf` calls `clip.optimize(rest)`,
+  stripping un-animated channels. In `Michelle.glb`, `SambaDancing` only keys `Translation` on 1 of
+  65 bones (`Hips`) and `Rotation` on 52 of 65 bones. If an additive clip keys a bone or axis that
+   the base clip does *not* key, the zero-based accumulator receives only $0 + w_{\text{add}} \Delta T$,
+  **wiping out the bone's rest translation and scale to zero**.
+- **Failure 2 (Rotation Collapse on Unkeyed Base Bones):** On a bone whose rotation is not keyed by
+  the active base clip, a zero-centered quaternion difference $\Delta R = R(t) - R_{\text{ref}}$ has
+  $w \approx 0$ for small angles. Normalizing $0 + w_{\text{add}} \Delta R$ without $R_{\text{rest}}$
+  normalizes a pure-imaginary chordal vector, **snapping the bone by $90^\circ$**.
+- **Failure 3 (Single Partial-Weight Clip):** On a zero-based accumulator, a single clip fading in
+  with weight $w \in (0, 1)$ scales translation and scale toward zero ($w \cdot T$, $w \cdot S$)
+  while leaving rotation at 100% full strength ($\text{normalize}(w \cdot R) = R$), then snaps at
+  $w = 0$.
+
+### 2.2. How Unified Rest-Anchored Delta Accumulation Solves Every Case Without Switches
+Under $V_{\text{final}} = V_{\text{rest}} + \sum_i w_i \cdot (V_i(t) - V_{\text{rest}})$:
+1. **Single clip at $w = 1$:**
+   $$V_{\text{rest}} + 1 \cdot (V_1 - V_{\text{rest}}) = V_1$$
+2. **Silent clip at $w = 0$ (fixes D37/E14 at the root for T, R, and S):**
+   $$V_{\text{rest}} + 0 \cdot (V_1 - V_{\text{rest}}) = V_{\text{rest}}$$
+   A bound clip at weight zero never clobbers non-zero rest translation or scale.
+3. **Single partial-body clip fading $w: 0 \to 1$:**
+   $$V_{\text{rest}} + w \cdot (V_1 - V_{\text{rest}}) = (1 - w) V_{\text{rest}} + w V_1$$
+   Smoothly interpolates (lerp for T/S, nlerp for R) from the joint's rest pose to $V_1$.
+4. **Two full-body clips crossfading ($w_1 + w_2 = 1$):**
+   $$V_{\text{rest}} + w_1(V_1 - V_{\text{rest}}) + w_2(V_2 - V_{\text{rest}}) = w_1 V_1 + w_2 V_2$$
+   Even if `clip.optimize` stripped a constant-at-rest channel from clip 1, clip 1's omitted delta
+   is identically $0$, so clip 2 still crossfades smoothly against $V_{\text{rest}}$!
+5. **Base clip ($w_{\text{base}} = 1$, or crossfading base clips summing to $1$) + Additive /
+   Upper-Body clip ($w_{\text{add}} = w$):**
+   $$V_{\text{rest}} + 1 \cdot (V_{\text{base}} - V_{\text{rest}}) + w \cdot (V_{\text{add}} - V_{\text{rest}}) = V_{\text{base}} + w \cdot \Delta V_{\text{add}}$$
+   And on any bone/axis that $V_{\text{base}}$ does *not* key, it automatically evaluates to
+   $V_{\text{rest}} + w \cdot \Delta V_{\text{add}}$.
+
+### 2.3. Adversarial Check: Why Quaternion Hemisphere Alignment Must Happen at Import/Build Time, Not Per-Frame in the Apply Shader
+Suppose a base clip spins a joint past $180^\circ$ so $\text{dot}(R_{\text{base}}(t), R_{\text{rest}})$
+crosses $0$ mid-clip, while an additive clip contributes $w_{\text{add}} \Delta R_{\text{add}}$.
+If the apply shader flipped $R_{\text{base}}(t) \to -R_{\text{base}}(t)$ dynamically when
+$\text{dot}(R_{\text{base}}(t), R_{\text{rest}}) < 0$, then at the crossing frame the sum would flip
+from $+R_{\text{base}} + w_{\text{add}} \Delta R_{\text{add}}$ to
+$-R_{\text{base}} + w_{\text{add}} \Delta R_{\text{add}} = -(R_{\text{base}} - w_{\text{add}} \Delta R_{\text{add}})$,
+inverting the direction of the additive offset mid-animation!
+By keeping sign canonicalization strictly at clip import/creation time (`quat3_canonicalize_sign_run`
+anchored to $R_{\text{rest}}$ at keyframe 0 and continuous across consecutive keyframes), curves
+remain $C^1$-continuous everywhere and the apply shader has zero sign-flip branches.
+
+---
+
+## 3. Architecture
+
+### 3.1. Accumulator Layout ([`POSE_ACCUMULATOR_LAYOUT.js`](./POSE_ACCUMULATOR_LAYOUT.js))
+
+Expand each per-row slot in `pose_accumulator` from 16 `u32`s (64 bytes) to 32 `u32`s (128 bytes,
+preserving power-of-two shift indexing) so rest translation and rest scale ride alongside rest
+rotation:
+
+```text
+Word Offset   Field                       Description
+──────────────────────────────────────────────────────────────────────────────────────────
+[0..3]        translation.xyz             Σ w_i * (T_i - rest_T)
+[3..7]        rotation.xyzw               Σ w_i * (R_i - rest_R)
+[7..10]       scale.xyz                   Σ w_i * (S_i - rest_S)
+[10]          dirty_mask                  Bitmask of touched channels (TX, TY, TZ, R, SX, SY, SZ)
+[11..15]      rest_rotation.xyzw          Target joint's rest rotation
+[15..18]      rest_translation.xyz        Target joint's rest translation
+[18..21]      rest_scale.xyz              Target joint's rest scale
+[21..32]      padding                     Power-of-two slot alignment (32 u32s = 128 bytes)
+```
+
+### 3.2. Zero-Overhead Binding Rest Value ([`ANIMATION_TRACK_BINDING_STRUCT.js`](./ANIMATION_TRACK_BINDING_STRUCT.js))
+
+Each row in `animation_bindings` targets a single `property` (`Translation`, `Rotation`, or `Scale`)
+and already carries a `vec4f` field (`rest_rotation`). By populating that `vec4f` with the target
+entity's rest value for its bound `property`—`[tx, ty, tz, 0]` for Translation, `[sx, sy, sz, 0]`
+for Scale, and `[rx, ry, rz, rw]` for Rotation, both at binding completion and in
+`GPUAnimationManager.#unmute`—the binding struct stays 32 bytes with zero extra memory overhead.
+
+### 3.3. GPU Apply & Resolve ([`chunk_pose_accumulator.js`](./chunk_pose_accumulator.js), [`shader_animation_pose_resolve.js`](./shader_animation_pose_resolve.js))
+
+- **Apply (`chunk_pose_accumulator`):**
+  - `pose_accumulator_add_translation(row, value, mask, weight, rest)`: for each masked axis $a$,
+    atomic-adds `value[a] - rest[a] * weight` into `POSE_OFFSET_TRANSLATION + a` and stores
+    `rest[a]` into `POSE_OFFSET_REST_TRANSLATION + a`.
+  - `pose_accumulator_add_rotation(row, value, mask, weight, rest)`: substitutes `weight` for a
+    missing $w$ curve (`let w = select(weight, value.w, (mask & 0x8u) != 0u)`), atomic-adds
+    `(value.xyz, w) - rest * weight` into `POSE_OFFSET_ROTATION`, and stores `rest` into
+    `POSE_OFFSET_REST_ROTATION`.
+  - `pose_accumulator_add_scale(row, value, mask, weight, rest)`: for each masked axis $a$,
+    atomic-adds `value[a] - rest[a] * weight` into `POSE_OFFSET_SCALE + a` and stores `rest[a]`
+    into `POSE_OFFSET_REST_SCALE + a`.
+- **Resolve (`shader_animation_pose_resolve`):**
+  - Translation (per dirty axis $a$): `t[a] = rest_t[a] + delta_t[a]`, then zeroes `delta_t[a]`.
+  - Rotation (when `POSE_DIRTY_R` set): `r = rest_r + delta_r`, zeroes `delta_r`, and writes
+    `normalize(r)` when `length(r) > 0.0`, else `rest_r`.
+  - Scale (per dirty axis $a$): `s[a] = rest_s[a] + delta_s[a]`, then zeroes `delta_s[a]`.
+
+### 3.4. CPU Twin Lockstep ([`pose_evaluate_local.js`](./pose/pose_evaluate_local.js))
+
+`pose_evaluate_local(result, target, rest, playbacks)` accumulates `(curve.evaluate(time) - rest_comp) * weight`
+into `SUM_TRANSLATION`, `SUM_ROTATION`, and `SUM_SCALE`, and resolves `rest + SUM` (normalizing
+rotation with fallback to `rest.rotation` on zero length), matching the GPU bit-for-bit.
+
+### 3.5. Import / Authoring Stage Additive Rebasing ([`ShadeAnimationClip.js`](./ShadeAnimationClip.js))
+
+`ShadeAnimationClip.from_additive(source_clip, { reference_clip, reference_time, rest_of, name })`
+rebases a clip authored relative to `reference_clip` at `reference_time` onto each target's rest
+pose `rest_of(target)`:
+- $T_{\text{out}}(t) = T_{\text{rest}} + (T_{\text{src}}(t) - T_{\text{ref}})$
+- $S_{\text{out}}(t) = S_{\text{rest}} + (S_{\text{src}}(t) - S_{\text{ref}})$
+- $R_{\text{out}}(t) = (R_{\text{src}}(t) \otimes R_{\text{ref}}^{-1}) \otimes R_{\text{rest}}$,
+  sign-canonicalized against $R_{\text{rest}}$
+- Automatically drops any axis curve or rotation channel whose delta from $V_{\text{ref}}$ is zero
+  across all keyframes (within `1e-5`).

package/src/shade/renderer/animation/ANIMATION_DATABASE_SPEC.d.ts

@@ -1,7 +1,7 @@
 /**
  * Schema for the GPU-side animation system.
  *
- * Tables fall into three categories:
+ * Tables fall into four categories:
  *
  *  - **Animation data** (immutable per curve definition): `animation_curves`
  *    (curve headers, each naming a run of keyframes), `animation_keyframes`
@@ -21,6 +21,14 @@
  *    joint row, writing `node.global * inverse_bind` into the shared
  *    skin-matrices scratch buffer at the joint's own row.
  *
+ *  - **Foliage fluid bones**: `animation_foliage_rigs` (one row per placed
+ *    foliage rig — the run of its aeroelastic joints and the root node
+ *    transform row) and `animation_foliage_joints` (one aeroelastic joint
+ *    per row, storing rest orientation, branch axis, compliance, spring-damper
+ *    state, and target Node3D row). Evaluated each frame by sampling
+ *    `GPUSceneWind` (`wind_field_sample`) and contributing rotations into
+ *    `pose_accumulator`.
+ *
  * Where a record has many of something, they are a run of rows it names by
  * its first row and a count — a range, declared below, so removing the
  * record removes the run.

package/src/shade/renderer/animation/ANIMATION_DATABASE_SPEC.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ANIMATION_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_DATABASE_SPEC.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,4DAQG;sCA7CmC,0CAA0C"}
+{"version":3,"file":"ANIMATION_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_DATABASE_SPEC.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,4DAUG;sCAzDmC,0CAA0C"}

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

@@ -3,6 +3,8 @@ import { SCENE_DATABASE_SPEC } from "../scene/SCENE_DATABASE_SPEC.js";
 import { ANIMATION_CLIP_STATE_STRUCT } from "./ANIMATION_CLIP_STATE_STRUCT.js";
 import { ANIMATION_CURVE_HEADER_STRUCT } from "./ANIMATION_CURVE_HEADER_STRUCT.js";
 import { ANIMATION_CURVE_KEYFRAME_STRUCT } from "./ANIMATION_CURVE_KEYFRAME_STRUCT.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";
@@ -11,7 +13,7 @@ import { ANIMATION_TRACK_METADATA_STRUCT } from "./ANIMATION_TRACK_METADATA_STRU
 /**
  * Schema for the GPU-side animation system.
  *
- * Tables fall into three categories:
+ * Tables fall into four categories:
  *
  *  - **Animation data** (immutable per curve definition): `animation_curves`
  *    (curve headers, each naming a run of keyframes), `animation_keyframes`
@@ -31,6 +33,14 @@ import { ANIMATION_TRACK_METADATA_STRUCT } from "./ANIMATION_TRACK_METADATA_STRU
  *    joint row, writing `node.global * inverse_bind` into the shared
  *    skin-matrices scratch buffer at the joint's own row.
  *
+ *  - **Foliage fluid bones**: `animation_foliage_rigs` (one row per placed
+ *    foliage rig — the run of its aeroelastic joints and the root node
+ *    transform row) and `animation_foliage_joints` (one aeroelastic joint
+ *    per row, storing rest orientation, branch axis, compliance, spring-damper
+ *    state, and target Node3D row). Evaluated each frame by sampling
+ *    `GPUSceneWind` (`wind_field_sample`) and contributing rotations into
+ *    `pose_accumulator`.
+ *
  * Where a record has many of something, they are a run of rows it names by
  * its first row and a count — a range, declared below, so removing the
  * record removes the run.
@@ -43,6 +53,8 @@ export const ANIMATION_DATABASE_SPEC = GPUDatabaseDefinition.from({
     animation_bindings: ANIMATION_TRACK_BINDING_STRUCT,
     animation_skins: ANIMATION_SKIN_STRUCT,
     animation_skin_joints: ANIMATION_SKIN_JOINT_STRUCT,
+    animation_foliage_rigs: ANIMATION_FOLIAGE_RIG_STRUCT,
+    animation_foliage_joints: ANIMATION_FOLIAGE_JOINT_STRUCT,
 });
 
 // A curve owns its run of keyframes.
@@ -118,3 +130,43 @@ ANIMATION_DATABASE_SPEC.add_link({
     nullable: true,
     owning: false,
 });
+
+// A foliage wind rig owns its run of aeroelastic joints.
+ANIMATION_DATABASE_SPEC.add_range({
+    table: 'animation_foliage_rigs',
+    first_field: 'joints_first',
+    count_field: 'joint_count',
+    target_database: ANIMATION_DATABASE_SPEC,
+    target_table: 'animation_foliage_joints',
+    owning: true,
+});
+
+// A foliage rig's root node in the scene transforms table (nullable while pending).
+ANIMATION_DATABASE_SPEC.add_link({
+    table: 'animation_foliage_rigs',
+    field: 'root_node',
+    target_database: SCENE_DATABASE_SPEC,
+    target_table: 'transforms',
+    nullable: true,
+    owning: false,
+});
+
+// A foliage joint's target node in the scene transforms table (nullable while pending or muted).
+ANIMATION_DATABASE_SPEC.add_link({
+    table: 'animation_foliage_joints',
+    field: 'node',
+    target_database: SCENE_DATABASE_SPEC,
+    target_table: 'transforms',
+    nullable: true,
+    owning: false,
+});
+
+// Back-pointer from a foliage joint to its owning rig.
+ANIMATION_DATABASE_SPEC.add_link({
+    table: 'animation_foliage_joints',
+    field: 'rig',
+    target_database: ANIMATION_DATABASE_SPEC,
+    target_table: 'animation_foliage_rigs',
+    nullable: false,
+    owning: false,
+});

package/src/shade/renderer/animation/ANIMATION_FOLIAGE_JOINT_STRUCT.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One aeroelastic foliage bone in `animation_foliage_joints`, driven on the GPU by sampling
+ * `GPUSceneWind` (`wind_field_sample(pos_ws)`) at the joint's world position and integrating a
+ * second-order damped spring-damper oscillator with Strouhal vortex shedding.
+ */
+export const ANIMATION_FOLIAGE_JOINT_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=ANIMATION_FOLIAGE_JOINT_STRUCT.d.ts.map

package/src/shade/renderer/animation/ANIMATION_FOLIAGE_JOINT_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ANIMATION_FOLIAGE_JOINT_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_FOLIAGE_JOINT_STRUCT.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,0DA8D4B;6BArEC,gCAAgC"}

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

@@ -0,0 +1,71 @@
+import { f32, u32, vec3f, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+
+/**
+ * One aeroelastic foliage bone in `animation_foliage_joints`, driven on the GPU by sampling
+ * `GPUSceneWind` (`wind_field_sample(pos_ws)`) at the joint's world position and integrating a
+ * second-order damped spring-damper oscillator with Strouhal vortex shedding.
+ */
+export const ANIMATION_FOLIAGE_JOINT_STRUCT = WebGPUStruct.from({
+    /**
+     * Rest-pose local rotation quaternion `(x, y, z, w)` of the joint.
+     */
+    rest_rotation: vec4f,
+
+    /**
+     * Unit growth axis of the branch segment in tree model space.
+     * Cross-flow aerodynamic drag acts along `cross(branch_axis, wind_model)`.
+     */
+    branch_axis: vec3f,
+
+    /**
+     * Rotational aeroelastic compliance (`rad / (m/s)^2`) derived from the pipe-model cross-section radius.
+     * Zero for an immobile ground anchor joint.
+     */
+    compliance: f32,
+
+    /**
+     * Stateful 3D axis-angle deflection vector `(theta_x, theta_y, theta_z)` in tree model space (radians).
+     */
+    angular_displacement: vec3f,
+
+    /**
+     * Undamped natural angular frequency `omega_0` (`rad/s`) of the branch's restoring bark stiffness.
+     */
+    natural_frequency: f32,
+
+    /**
+     * Stateful 3D angular velocity vector `(omega_x, omega_y, omega_z)` in tree model space (`rad/s`).
+     */
+    angular_velocity: vec3f,
+
+    /**
+     * Dimensionless damping ratio `zeta` (`> 0`).
+     */
+    damping_ratio: f32,
+
+    /**
+     * Target `transforms` row in `scene_database`, or `GPU_DATABASE_NULL` when pending or CPU-held.
+     */
+    node: u32,
+
+    /**
+     * Owning row in `animation_foliage_rigs`.
+     */
+    rig: u32,
+
+    /**
+     * Asymptotic soft-saturation deflection angle limit in radians (`theta_max`).
+     */
+    max_angle: f32,
+
+    /**
+     * Strouhal vortex-shedding oscillation amplitude factor.
+     */
+    turbulence: f32,
+
+    /**
+     * Stateful accumulated vortex-shedding phase in radians.
+     */
+    flutter_phase: f32,
+}, "AnimationFoliageJoint");

package/src/shade/renderer/animation/ANIMATION_FOLIAGE_RIG_STRUCT.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-instance foliage wind rig header in `animation_foliage_rigs`.
+ *
+ * Owns a contiguous run of rows in `animation_foliage_joints` (`joints_first`, `joint_count`),
+ * references the tree root's `transforms` row (`root_node`) so the GPU solver can transform
+ * world-space wind vectors from `GPUSceneWind` into the tree's model frame, and carries an
+ * overall blend/strength scalar `weight`.
+ */
+export const ANIMATION_FOLIAGE_RIG_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=ANIMATION_FOLIAGE_RIG_STRUCT.d.ts.map

package/src/shade/renderer/animation/ANIMATION_FOLIAGE_RIG_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ANIMATION_FOLIAGE_RIG_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/ANIMATION_FOLIAGE_RIG_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wDAoB0B;6BA9BG,gCAAgC"}

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

@@ -0,0 +1,32 @@
+import { f32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+
+/**
+ * Per-instance foliage wind rig header in `animation_foliage_rigs`.
+ *
+ * Owns a contiguous run of rows in `animation_foliage_joints` (`joints_first`, `joint_count`),
+ * references the tree root's `transforms` row (`root_node`) so the GPU solver can transform
+ * world-space wind vectors from `GPUSceneWind` into the tree's model frame, and carries an
+ * overall blend/strength scalar `weight`.
+ */
+export const ANIMATION_FOLIAGE_RIG_STRUCT = WebGPUStruct.from({
+    /**
+     * First row in `animation_foliage_joints` belonging to this rig, or `GPU_DATABASE_NULL` while pending.
+     */
+    joints_first: u32,
+
+    /**
+     * Number of joints in this rig's run.
+     */
+    joint_count: u32,
+
+    /**
+     * Row in `scene_database.transforms` of the tree instance's root node, or `GPU_DATABASE_NULL` while pending.
+     */
+    root_node: u32,
+
+    /**
+     * Contribution weight into the pose accumulator (`1.0` = full aeroelastic response, `0.0` = muted).
+     */
+    weight: f32,
+}, "AnimationFoliageRig");

package/src/shade/renderer/animation/GPUAnimationManager.d.ts

@@ -29,9 +29,10 @@
  */
 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
      */
@@ -424,6 +425,32 @@ export class GPUAnimationManager {
      * @param {number} clip_id
      */
     unregister_clip(clip_id: number): void;
+    /**
+     * 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: import("./foliage/FoliageWindRig.js").FoliageWindRig): number;
+    /**
+     * Update a registered foliage wind rig's contribution weight.
+     *
+     * @param {number} rig_id
+     * @param {number} weight
+     */
+    set_foliage_rig_weight(rig_id: number, weight: number): void;
+    /**
+     * 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: number): void;
     /**
      * 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

package/src/shade/renderer/animation/GPUAnimationManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUAnimationManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/GPUAnimationManager.js"],"names":[],"mappings":"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"}