@woosh/meep-engine 3.51.0 → 3.53.0

package/src/shade/renderer/Renderer.js

@@ -22,13 +22,16 @@ import { shader_composite_volumetrics } from "./deferred/shader_composite_volume
 import { shader_deferred_main } from "./deferred/shader_deferred_main.js";
 import { LOCAL_LIGHT_SHADING } from "./deferred/LOCAL_LIGHT_SHADING.js";
 import { LocalLightShading } from "./deferred/LocalLightShading.js";
-import { shader_tonemap_HDR } from "./deferred/shader_tonemap_HDR.js";
-import { shader_tonemap_HDR_none } from "./deferred/shader_tonemap_HDR_none.js";
-import { shader_tonemap_HDR_pbr_neutral } from "./deferred/shader_tonemap_HDR_pbr_neutral.js";
-import { shader_tonemap_LDR } from "./deferred/shader_tonemap_LDR.js";
-import { shader_tonemap_LDR_none } from "./deferred/shader_tonemap_LDR_none.js";
-import { shader_tonemap_LDR_pbr_neutral } from "./deferred/shader_tonemap_LDR_pbr_neutral.js";
-import { TonemapDisplaySettings } from "./deferred/TonemapDisplaySettings.js";
+import { shader_tonemap_HDR } from "./deferred/tonemap/shader_tonemap_HDR.js";
+import { shader_tonemap_HDR_aces } from "./deferred/tonemap/shader_tonemap_HDR_aces.js";
+import { shader_tonemap_HDR_none } from "./deferred/tonemap/shader_tonemap_HDR_none.js";
+import { shader_tonemap_HDR_pbr_neutral } from "./deferred/tonemap/shader_tonemap_HDR_pbr_neutral.js";
+import { shader_tonemap_LDR } from "./deferred/tonemap/shader_tonemap_LDR.js";
+import { shader_tonemap_LDR_aces } from "./deferred/tonemap/shader_tonemap_LDR_aces.js";
+import { shader_tonemap_LDR_none } from "./deferred/tonemap/shader_tonemap_LDR_none.js";
+import { shader_tonemap_LDR_pbr_neutral } from "./deferred/tonemap/shader_tonemap_LDR_pbr_neutral.js";
+import { TonemapAces2Tables } from "./deferred/tonemap/TonemapAces2Tables.js";
+import { TonemapDisplaySettings } from "./deferred/tonemap/TonemapDisplaySettings.js";
 import { FrameContext } from "./extension/FrameContext.js";
 import { FramePhase } from "./extension/FramePhase.js";
 import { GBufferTextures } from "./extension/GBufferTextures.js";
@@ -225,11 +228,11 @@ export class Renderer {
 
     /**
      * How the exposed scene colour becomes display colour, on every output. An SDR and an HDR display run the same
-     * mode, so a scene looks alike on both; see {@link ShadeToneMappingMode}. Read every frame, so it can be flipped
+     * mode, so a scene looks alike on both; see {@link ShadeToneMappingMode}. ACES, Unreal's default look, unless set. Read every frame, so it can be flipped
      * at runtime. A mode not in use at {@link initialize} compiles its pass on the first frame that draws with it.
      * @type {ShadeToneMappingMode}
      */
-    tone_mapping_mode = ShadeToneMappingMode.GT7;
+    tone_mapping_mode = ShadeToneMappingMode.ACES;
 
     /**
      * Switches of the AVBOIT mode, read every frame while {@link transparency_mode} selects it.
@@ -838,7 +841,33 @@ export class Renderer {
      * @returns {RenderExtension} `extension`, for handing back to {@link remove_extension}
      */
     add_extension(extension) {
-        return this.#extensions.add(extension);
+        this.#extensions.add(extension);
+
+        if (
+            this.#graphics !== undefined
+            && !this.#destroyed
+            && !this.#device_lost
+            && typeof extension.enquirePipelines === 'function'
+        ) {
+            const enquiry = PipelineEnquiry.from(this.device);
+
+            extension.enquirePipelines(enquiry);
+
+            const graphics = this.#graphics;
+            const render = enquiry.render;
+
+            for (let i = 0; i < render.length; i++) {
+                graphics.render_pipelines.prepare(render[i]);
+            }
+
+            const compute = enquiry.compute;
+
+            for (let i = 0; i < compute.length; i++) {
+                graphics.compute_pipelines.prepare(compute[i]);
+            }
+        }
+
+        return extension;
     }
 
     /**
@@ -1399,6 +1428,13 @@ export class Renderer {
      */
     #tonemap_settings = new TonemapDisplaySettings();
 
+    /**
+     * The ACES HDR pass's two output transforms, built for the display in {@link #tonemap_settings}.
+     *
+     * @type {TonemapAces2Tables}
+     */
+    #tonemap_aces2_tables = new TonemapAces2Tables();
+
     #update_presentation_format() {
 
         const format8bit = navigator.gpu.getPreferredCanvasFormat();
@@ -1725,6 +1761,8 @@ export class Renderer {
             this.#autoexposure.enquirePipelines(enquiry);
         }
 
+        this.#extensions.enquirePipelines(enquiry);
+
         enquiry.render.push(this.#tonemap_shader().pipeline_for([this.#presentation_format]));
     }
 
@@ -1741,6 +1779,10 @@ export class Renderer {
             return this.#hdr_supported ? shader_tonemap_HDR_none : shader_tonemap_LDR_none;
         }
 
+        if (this.tone_mapping_mode === ShadeToneMappingMode.ACES) {
+            return this.#hdr_supported ? shader_tonemap_HDR_aces : shader_tonemap_LDR_aces;
+        }
+
         if (this.tone_mapping_mode === ShadeToneMappingMode.PBR_NEUTRAL) {
             return this.#hdr_supported ? shader_tonemap_HDR_pbr_neutral : shader_tonemap_LDR_pbr_neutral;
         }
@@ -1822,6 +1864,7 @@ export class Renderer {
         this.#scene_sdfs.clear();
 
         this.#autoexposure?.destroy();
+        this.#tonemap_aces2_tables.destroy();
         this.#depth_of_field?.destroy();
         this.#depth_of_field_unreal?.destroy();
         this.#restir_di?.destroy();
@@ -2428,6 +2471,21 @@ export class Renderer {
             }
         }
 
+        const graph = new FrameGraph("Shading");
+
+        /*
+         The view is updated and nothing has been rasterized, so an extension here is doing the
+         per-frame compute that later phases depend on. There are no records yet — the frame has
+         built nothing to hand out. Runs ahead of `scene.tick` and shadow allocation so scene-level
+         producers at `FrameStart` (such as `GPUFluidSystem` publishing `GPUSceneWind`) have finalized
+         their atlas and uniforms before `scene.tick` encodes.
+        */
+        const frame = new FrameContext(graph, view_ctx);
+
+        frame.phase = FramePhase.FrameStart;
+
+        this.#extensions.run(frame);
+
         // Per-frame animation tick — runs before shadow allocation so
         // animated transforms (joint poses, mesh.global from animated
         // parents) are in the scene database by the time shadow
@@ -2436,7 +2494,7 @@ export class Renderer {
 
         /*
          The virtual-geometry frame, which spans every graph this render records: the shadow maps
-         draw into graphs of their own before the `Shading` graph exists, and a shadow view cuts like
+         draw into graphs of their own before the `Shading` graph executes, and a shadow view cuts like
          any other view (SHADOW_PLAN_2026_09_28). So it opens here — before the shadow block and
          outside its `if`, so a frame with shadows off still opens and closes — for the view this
          frame is rendered for, which takes the feedback's first slot. The readback is recorded into
@@ -2466,20 +2524,6 @@ export class Renderer {
             sm.draw(command_ctx);
         }
 
-
-        const graph = new FrameGraph("Shading");
-
-        /*
-         The view is updated and nothing has been rasterized, so an extension here is doing the
-         per-frame compute that later phases depend on. There are no records yet — the frame has
-         built nothing to hand out.
-        */
-        const frame = new FrameContext(graph, view_ctx);
-
-        frame.phase = FramePhase.FrameStart;
-
-        this.#extensions.run(frame);
-
         // build main view rasterization job
         const raster_main = new RasterizationJob();
         raster_main.view_ctx = view_ctx;
@@ -3177,16 +3221,29 @@ export class Renderer {
 
         current_color_out = record_scene_color.color;
 
+        const tonemap_shader = this.#tonemap_shader();
+
         // every pass reads from the settings only the members its immediate struct names: the canvas's primaries
         // from its working space, and, on an HDR display, the peak
+        const tonemap_inputs = {
+            input_color: current_color_out,
+            settings: this.#tonemap_settings,
+            exposure,
+        };
+
+        if (tonemap_shader === shader_tonemap_HDR_aces) {
+            // the two ACES 2.0 transforms for this display, rebuilt only when the display changed
+            const display = this.#tonemap_settings;
+            const tables = this.#tonemap_aces2_tables;
+
+            tables.update(display.peak_nits);
+            tonemap_inputs.aces2_tables = graph_import_buffer(graph, tables.gpu_buffer(this.device), "tonemap/aces2 tables");
+        }
+
         [current_color_out] = graph_image_pass({
             graph,
-            shader: this.#tonemap_shader(),
-            inputs: {
-                input_color: current_color_out,
-                settings: this.#tonemap_settings,
-                exposure
-            },
+            shader: tonemap_shader,
+            inputs: tonemap_inputs,
             output: [gr_texture_canvas]
         });
 

package/src/shade/renderer/ShadeToneMappingMode.d.ts

@@ -2,13 +2,14 @@
  * How the exposed scene colour becomes display colour.
  *
  * One choice for every display. The same mode runs on an SDR and an HDR output, so a scene looks the same on both up
- * to the SDR display's limits. That is the reason Polyphony give for GT7's operator, and there is no per-output
- * setting on purpose.
+ * to the SDR display's limits. That is the reason Polyphony give for GT7's operator, and Epic's for how Unreal 5.8
+ * takes its Filmic picture to HDR, and there is no per-output setting on purpose.
  */
 export type ShadeToneMappingMode = number;
 export namespace ShadeToneMappingMode {
     let GT7: number;
     let NONE: number;
     let PBR_NEUTRAL: number;
+    let ACES: number;
 }
 //# sourceMappingURL=ShadeToneMappingMode.d.ts.map

package/src/shade/renderer/ShadeToneMappingMode.js

@@ -2,15 +2,15 @@
  * How the exposed scene colour becomes display colour.
  *
  * One choice for every display. The same mode runs on an SDR and an HDR output, so a scene looks the same on both up
- * to the SDR display's limits. That is the reason Polyphony give for GT7's operator, and there is no per-output
- * setting on purpose.
+ * to the SDR display's limits. That is the reason Polyphony give for GT7's operator, and Epic's for how Unreal 5.8
+ * takes its Filmic picture to HDR, and there is no per-output setting on purpose.
  *
  * @enum {number}
  */
 export const ShadeToneMappingMode = {
     /**
-     * GT7 tone mapping (Polyphony Digital, SIGGRAPH 2025). An exposed 1.0 shows at a 250 cd/m² paper white on both
-     * outputs. SDR clips at that paper white, the curve's SDR mode, and HDR rolls off to the display's peak.
+     * GT7 tone mapping (Polyphony Digital, SIGGRAPH 2025). An exposed 1.0 shows at the paper white on both outputs.
+     * SDR clips at that paper white, the curve's SDR mode, and HDR rolls off to the display's peak.
      */
     GT7: 0,
     /**
@@ -27,4 +27,15 @@ export const ShadeToneMappingMode = {
      * An exposed 0.18 shows at 0.14 of SDR white, where {@link GT7} shows it at 0.179.
      */
     PBR_NEUTRAL: 2,
+    /**
+     * Unreal Engine's default look, the default here too. SDR is UE's "Filmic" tone mapper at its default settings,
+     * the ACES-derived curve every Unreal title ships with unless it chose otherwise. HDR is what Unreal 5.8 does with
+     * the same method: the SDR picture, taken back to the scene through the inverse ACES 2.0 output transform for an
+     * SDR display, and rendered again with the ACES 2.0 output transform for the display's headroom.
+     *
+     * An exposed 0.18 shows at 0.18 of SDR white, as with {@link GT7}, with a mid-tone contrast of 1.36 against GT7's
+     * 1.05. On HDR the picture expands into the headroom and mid-grey rises with it, by ACES 2.0's design: 0.26 of SDR
+     * white at a 1000 cd/m² display.
+     */
+    ACES: 3,
 };

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");