@woosh/meep-engine 3.52.0 → 3.53.0

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

@@ -3,6 +3,8 @@ import { chunk_atomic_add_f32_storage } from "../shader/chunk/atomic/chunk_atomi
 import {
     POSE_ACCUMULATOR_OFFSET_DIRTY,
     POSE_ACCUMULATOR_OFFSET_REST_ROTATION,
+    POSE_ACCUMULATOR_OFFSET_REST_SCALE,
+    POSE_ACCUMULATOR_OFFSET_REST_TRANSLATION,
     POSE_ACCUMULATOR_OFFSET_ROTATION,
     POSE_ACCUMULATOR_OFFSET_SCALE,
     POSE_ACCUMULATOR_OFFSET_TRANSLATION,
@@ -42,6 +44,8 @@ const POSE_OFFSET_ROTATION: u32 = ${POSE_ACCUMULATOR_OFFSET_ROTATION}u;
 const POSE_OFFSET_SCALE: u32 = ${POSE_ACCUMULATOR_OFFSET_SCALE}u;
 const POSE_OFFSET_DIRTY: u32 = ${POSE_ACCUMULATOR_OFFSET_DIRTY}u;
 const POSE_OFFSET_REST_ROTATION: u32 = ${POSE_ACCUMULATOR_OFFSET_REST_ROTATION}u;
+const POSE_OFFSET_REST_TRANSLATION: u32 = ${POSE_ACCUMULATOR_OFFSET_REST_TRANSLATION}u;
+const POSE_OFFSET_REST_SCALE: u32 = ${POSE_ACCUMULATOR_OFFSET_REST_SCALE}u;
 
 const POSE_DIRTY_TX: u32 = ${POSE_DIRTY_TX}u;
 const POSE_DIRTY_TY: u32 = ${POSE_DIRTY_TY}u;
@@ -57,23 +61,28 @@ fn pose_accumulator_slot_base(row: u32) -> u32 {
     return row * POSE_ACCUMULATOR_STRIDE;
 }
 
-fn pose_accumulator_add_translation(row: u32, value: vec3<f32>, mask: u32) {
-    let base = pose_accumulator_slot_base(row) + POSE_OFFSET_TRANSLATION;
+fn pose_accumulator_add_translation(row: u32, value: vec3<f32>, mask: u32, weight: f32, rest: vec3<f32>) {
+    let slot_base = pose_accumulator_slot_base(row);
+    let base = slot_base + POSE_OFFSET_TRANSLATION;
+    let rest_base = slot_base + POSE_OFFSET_REST_TRANSLATION;
     var dirty_bits: u32 = 0u;
     if (mask & 0x1u) != 0u {
-        atomic_add_f32_storage(&pose_accumulator[base + 0u], value.x);
+        atomic_add_f32_storage(&pose_accumulator[base + 0u], value.x - rest.x * weight);
+        atomicStore(&pose_accumulator[rest_base + 0u], bitcast<u32>(rest.x));
         dirty_bits |= POSE_DIRTY_TX;
     }
     if (mask & 0x2u) != 0u {
-        atomic_add_f32_storage(&pose_accumulator[base + 1u], value.y);
+        atomic_add_f32_storage(&pose_accumulator[base + 1u], value.y - rest.y * weight);
+        atomicStore(&pose_accumulator[rest_base + 1u], bitcast<u32>(rest.y));
         dirty_bits |= POSE_DIRTY_TY;
     }
     if (mask & 0x4u) != 0u {
-        atomic_add_f32_storage(&pose_accumulator[base + 2u], value.z);
+        atomic_add_f32_storage(&pose_accumulator[base + 2u], value.z - rest.z * weight);
+        atomicStore(&pose_accumulator[rest_base + 2u], bitcast<u32>(rest.z));
         dirty_bits |= POSE_DIRTY_TZ;
     }
     if dirty_bits != 0u {
-        atomicOr(&pose_accumulator[pose_accumulator_slot_base(row) + POSE_OFFSET_DIRTY], dirty_bits);
+        atomicOr(&pose_accumulator[slot_base + POSE_OFFSET_DIRTY], dirty_bits);
     }
 }
 
@@ -84,55 +93,54 @@ fn pose_accumulator_add_rotation(row: u32, value: vec4<f32>, mask: u32, weight:
     // right for x/y/z but turns a missing w curve into a 180-degree
     // rotation after normalisation — pose_evaluate_local, the CPU twin,
     // defaults w to 1 and the GPU must match.
-    // The resolve pass normalises the accumulated sum, which is what
-    // corrects a weighted-vec4 blend back onto the unit 4-sphere.
+    // The resolve pass adds rest and normalises the accumulated delta sum,
+    // which corrects a weighted-vec4 blend back onto the unit 4-sphere.
     //
-    // The value arrives ALREADY multiplied by the clip's weight, which is why
-    // the weight is passed in rather than inferred: this clip's share of the
-    // identity's w is the weight, not 1.0. Substituting an unweighted 1.0 made
-    // one clip at weight 0.5 accumulate (0.5x, 0.5y, 0.5z, 1.0) against the
-    // twin's (0.5x, 0.5y, 0.5z, 0.5) — a different rotation once normalised,
-    // pulled toward identity — and it put a floor of 1.0 under the sum's
-    // length, so the resolve's rest-pose fallback for a zero-length sum could
-    // not fire and a joint rotated only by a silent clip lost its rest pose.
+    // The value arrives ALREADY multiplied by the clip's weight, so by
+    // distributive law w_i * (q_i - rest) == value - rest * weight.
     let w = select(weight, value.w, (mask & 0x8u) != 0u);
 
-    let base = pose_accumulator_slot_base(row) + POSE_OFFSET_ROTATION;
-    atomic_add_f32_storage(&pose_accumulator[base + 0u], value.x);
-    atomic_add_f32_storage(&pose_accumulator[base + 1u], value.y);
-    atomic_add_f32_storage(&pose_accumulator[base + 2u], value.z);
-    atomic_add_f32_storage(&pose_accumulator[base + 3u], w);
+    let slot_base = pose_accumulator_slot_base(row);
+    let base = slot_base + POSE_OFFSET_ROTATION;
+    atomic_add_f32_storage(&pose_accumulator[base + 0u], value.x - rest.x * weight);
+    atomic_add_f32_storage(&pose_accumulator[base + 1u], value.y - rest.y * weight);
+    atomic_add_f32_storage(&pose_accumulator[base + 2u], value.z - rest.z * weight);
+    atomic_add_f32_storage(&pose_accumulator[base + 3u], w - rest.w * weight);
 
     // The target's rest rotation, stored rather than added, by every contribution whatever its
-    // weight: the resolve writes it when the sum has length zero, which is every clip rotating the
-    // joint playing at weight zero, and by then the row holds the last clip's pose rather than the
-    // rest. Every binding of one target carries the same rest, so concurrent stores agree.
-    let rest_base = pose_accumulator_slot_base(row) + POSE_OFFSET_REST_ROTATION;
+    // weight: the resolve reconstructs rest + delta from it. Every binding of one target carries
+    // the same rest, so concurrent stores agree.
+    let rest_base = slot_base + POSE_OFFSET_REST_ROTATION;
     atomicStore(&pose_accumulator[rest_base + 0u], bitcast<u32>(rest.x));
     atomicStore(&pose_accumulator[rest_base + 1u], bitcast<u32>(rest.y));
     atomicStore(&pose_accumulator[rest_base + 2u], bitcast<u32>(rest.z));
     atomicStore(&pose_accumulator[rest_base + 3u], bitcast<u32>(rest.w));
 
-    atomicOr(&pose_accumulator[pose_accumulator_slot_base(row) + POSE_OFFSET_DIRTY], POSE_DIRTY_R);
+    atomicOr(&pose_accumulator[slot_base + POSE_OFFSET_DIRTY], POSE_DIRTY_R);
 }
 
-fn pose_accumulator_add_scale(row: u32, value: vec3<f32>, mask: u32) {
-    let base = pose_accumulator_slot_base(row) + POSE_OFFSET_SCALE;
+fn pose_accumulator_add_scale(row: u32, value: vec3<f32>, mask: u32, weight: f32, rest: vec3<f32>) {
+    let slot_base = pose_accumulator_slot_base(row);
+    let base = slot_base + POSE_OFFSET_SCALE;
+    let rest_base = slot_base + POSE_OFFSET_REST_SCALE;
     var dirty_bits: u32 = 0u;
     if (mask & 0x1u) != 0u {
-        atomic_add_f32_storage(&pose_accumulator[base + 0u], value.x);
+        atomic_add_f32_storage(&pose_accumulator[base + 0u], value.x - rest.x * weight);
+        atomicStore(&pose_accumulator[rest_base + 0u], bitcast<u32>(rest.x));
         dirty_bits |= POSE_DIRTY_SX;
     }
     if (mask & 0x2u) != 0u {
-        atomic_add_f32_storage(&pose_accumulator[base + 1u], value.y);
+        atomic_add_f32_storage(&pose_accumulator[base + 1u], value.y - rest.y * weight);
+        atomicStore(&pose_accumulator[rest_base + 1u], bitcast<u32>(rest.y));
         dirty_bits |= POSE_DIRTY_SY;
     }
     if (mask & 0x4u) != 0u {
-        atomic_add_f32_storage(&pose_accumulator[base + 2u], value.z);
+        atomic_add_f32_storage(&pose_accumulator[base + 2u], value.z - rest.z * weight);
+        atomicStore(&pose_accumulator[rest_base + 2u], bitcast<u32>(rest.z));
         dirty_bits |= POSE_DIRTY_SZ;
     }
     if dirty_bits != 0u {
-        atomicOr(&pose_accumulator[pose_accumulator_slot_base(row) + POSE_OFFSET_DIRTY], dirty_bits);
+        atomicOr(&pose_accumulator[slot_base + POSE_OFFSET_DIRTY], dirty_bits);
     }
 }
 `, [chunk_atomic_add_f32_storage]);

package/src/shade/renderer/animation/foliage/FoliageWindJoint.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Botanical and aeroelastic parameters for one skeletal foliage bone in a {@link FoliageWindRig}.
+ *
+ * When carried on a {@link SceneBundle} or {@link Prefab}, {@link target} is a node index;
+ * when bound to a placed instance (`place_tree` or `GPUAnimationManager#register_foliage_rig`),
+ * {@link target} is the joint's ECS entity ID.
+ */
+export class FoliageWindJoint {
+    /**
+     * @param {Object} options
+     * @param {number} options.target
+     * @param {ArrayLike<number>} [options.branch_axis]
+     * @param {number} [options.compliance]
+     * @param {number} [options.natural_frequency]
+     * @param {number} [options.damping_ratio]
+     * @param {number} [options.max_angle]
+     * @param {number} [options.turbulence]
+     * @param {number} [options.phase_offset]
+     * @param {number} [options.flutter_phase]
+     * @returns {FoliageWindJoint}
+     */
+    static from({ target, branch_axis, compliance, natural_frequency, damping_ratio, max_angle, turbulence, phase_offset, flutter_phase, }: {
+        target: number;
+        branch_axis?: ArrayLike<number>;
+        compliance?: number;
+        natural_frequency?: number;
+        damping_ratio?: number;
+        max_angle?: number;
+        turbulence?: number;
+        phase_offset?: number;
+        flutter_phase?: number;
+    }): FoliageWindJoint;
+    /**
+     * Target node index (in a `SceneBundle` / `Prefab`) or ECS entity ID (when bound to an instance).
+     * @type {number}
+     */
+    target: number;
+    /**
+     * Unit growth axis `[dx, dy, dz]` of the branch segment in tree model space.
+     * @type {Float32Array}
+     */
+    branch_axis: Float32Array;
+    /**
+     * Rotational aeroelastic compliance (`rad / (m/s)^2`) derived from the pipe-model cross-section radius.
+     * @type {number}
+     */
+    compliance: number;
+    /**
+     * Undamped natural angular frequency `omega_0` (`rad/s`) of the branch's restoring stiffness.
+     * @type {number}
+     */
+    natural_frequency: number;
+    /**
+     * Dimensionless damping ratio `zeta` (`> 0`).
+     * @type {number}
+     */
+    damping_ratio: number;
+    /**
+     * Asymptotic soft-saturation deflection angle limit in radians (`theta_max`).
+     * @type {number}
+     */
+    max_angle: number;
+    /**
+     * Strouhal vortex-shedding oscillation amplitude factor.
+     * @type {number}
+     */
+    turbulence: number;
+    /**
+     * Initial vortex-shedding phase offset in radians.
+     * @type {number}
+     */
+    phase_offset: number;
+    /**
+     * @param {number} v
+     */
+    set flutter_phase(v: number);
+    /**
+     * Alias for {@link phase_offset}.
+     * @returns {number}
+     */
+    get flutter_phase(): number;
+    /**
+     * @param {FoliageWindJoint} other
+     * @returns {this}
+     */
+    copy(other: FoliageWindJoint): this;
+    /**
+     * @returns {FoliageWindJoint}
+     */
+    clone(): FoliageWindJoint;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isFoliageWindJoint: boolean;
+}
+//# sourceMappingURL=FoliageWindJoint.d.ts.map

package/src/shade/renderer/animation/foliage/FoliageWindJoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageWindJoint.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/foliage/FoliageWindJoint.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH;IAgEI;;;;;;;;;;;;OAYG;IACH;QAX2B,MAAM,EAAtB,MAAM;QACsB,WAAW,GAAvC,UAAU,MAAM,CAAC;QACA,UAAU,GAA3B,MAAM;QACW,iBAAiB,GAAlC,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,SAAS,GAA1B,MAAM;QACW,UAAU,GAA3B,MAAM;QACW,YAAY,GAA7B,MAAM;QACW,aAAa,GAA9B,MAAM;QACJ,gBAAgB,CAyC5B;IAnHD;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,aAFU,YAAY,CAEoB;IAE1C;;;OAGG;IACH,YAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,mBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,eAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,WAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,YAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,cAFU,MAAM,CAEG;IAUnB;;OAEG;IACH,6BAEC;IAbD;;;OAGG;IACH,4BAEC;IA+DD;;;OAGG;IACH,YAHW,gBAAgB,GACd,IAAI,CAehB;IAED;;OAEG;IACH,SAFa,gBAAgB,CAM5B;IAGL;;;OAGG;IACH,6BAFU,OAAO,CAE4B;CAN5C"}

package/src/shade/renderer/animation/foliage/FoliageWindJoint.js

@@ -0,0 +1,161 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Botanical and aeroelastic parameters for one skeletal foliage bone in a {@link FoliageWindRig}.
+ *
+ * When carried on a {@link SceneBundle} or {@link Prefab}, {@link target} is a node index;
+ * when bound to a placed instance (`place_tree` or `GPUAnimationManager#register_foliage_rig`),
+ * {@link target} is the joint's ECS entity ID.
+ */
+export class FoliageWindJoint {
+    /**
+     * Target node index (in a `SceneBundle` / `Prefab`) or ECS entity ID (when bound to an instance).
+     * @type {number}
+     */
+    target = 0;
+
+    /**
+     * Unit growth axis `[dx, dy, dz]` of the branch segment in tree model space.
+     * @type {Float32Array}
+     */
+    branch_axis = new Float32Array([0, 1, 0]);
+
+    /**
+     * Rotational aeroelastic compliance (`rad / (m/s)^2`) derived from the pipe-model cross-section radius.
+     * @type {number}
+     */
+    compliance = 0.02;
+
+    /**
+     * Undamped natural angular frequency `omega_0` (`rad/s`) of the branch's restoring stiffness.
+     * @type {number}
+     */
+    natural_frequency = 3.0;
+
+    /**
+     * Dimensionless damping ratio `zeta` (`> 0`).
+     * @type {number}
+     */
+    damping_ratio = 0.45;
+
+    /**
+     * Asymptotic soft-saturation deflection angle limit in radians (`theta_max`).
+     * @type {number}
+     */
+    max_angle = 0.45;
+
+    /**
+     * Strouhal vortex-shedding oscillation amplitude factor.
+     * @type {number}
+     */
+    turbulence = 0.35;
+
+    /**
+     * Initial vortex-shedding phase offset in radians.
+     * @type {number}
+     */
+    phase_offset = 0.0;
+
+    /**
+     * Alias for {@link phase_offset}.
+     * @returns {number}
+     */
+    get flutter_phase() {
+        return this.phase_offset;
+    }
+
+    /**
+     * @param {number} v
+     */
+    set flutter_phase(v) {
+        this.phase_offset = v;
+    }
+
+    /**
+     * @param {Object} options
+     * @param {number} options.target
+     * @param {ArrayLike<number>} [options.branch_axis]
+     * @param {number} [options.compliance]
+     * @param {number} [options.natural_frequency]
+     * @param {number} [options.damping_ratio]
+     * @param {number} [options.max_angle]
+     * @param {number} [options.turbulence]
+     * @param {number} [options.phase_offset]
+     * @param {number} [options.flutter_phase]
+     * @returns {FoliageWindJoint}
+     */
+    static from({
+        target,
+        branch_axis = [0, 1, 0],
+        compliance = 0.02,
+        natural_frequency = 3.0,
+        damping_ratio = 0.45,
+        max_angle = 0.45,
+        turbulence = 0.35,
+        phase_offset,
+        flutter_phase = 0.0,
+    }) {
+        assert.isNonNegativeInteger(target, 'target');
+        const r = new FoliageWindJoint();
+        r.target = target;
+
+        let ax = branch_axis[0] ?? 0;
+        let ay = branch_axis[1] ?? 1;
+        let az = branch_axis[2] ?? 0;
+        const len = Math.hypot(ax, ay, az);
+        if (len > 1e-6) {
+            ax /= len;
+            ay /= len;
+            az /= len;
+        } else {
+            ax = 0;
+            ay = 1;
+            az = 0;
+        }
+        r.branch_axis[0] = ax;
+        r.branch_axis[1] = ay;
+        r.branch_axis[2] = az;
+
+        r.compliance = Math.max(0, compliance);
+        r.natural_frequency = Math.max(0.1, natural_frequency);
+        r.damping_ratio = Math.max(0.05, damping_ratio);
+        r.max_angle = Math.max(0.01, max_angle);
+        r.turbulence = Math.max(0, turbulence);
+        r.phase_offset = phase_offset !== undefined ? phase_offset : flutter_phase;
+        return r;
+    }
+
+    /**
+     * @param {FoliageWindJoint} other
+     * @returns {this}
+     */
+    copy(other) {
+        assert.defined(other, 'other');
+        this.target = other.target;
+        this.branch_axis[0] = other.branch_axis[0];
+        this.branch_axis[1] = other.branch_axis[1];
+        this.branch_axis[2] = other.branch_axis[2];
+        this.compliance = other.compliance;
+        this.natural_frequency = other.natural_frequency;
+        this.damping_ratio = other.damping_ratio;
+        this.max_angle = other.max_angle;
+        this.turbulence = other.turbulence;
+        this.phase_offset = other.phase_offset;
+        return this;
+    }
+
+    /**
+     * @returns {FoliageWindJoint}
+     */
+    clone() {
+        const r = new FoliageWindJoint();
+        r.copy(this);
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+FoliageWindJoint.prototype.isFoliageWindJoint = true;

package/src/shade/renderer/animation/foliage/FoliageWindRig.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Aeroelastic foliage bone rig descriptor for GPU fluid-driven skeletal wind animation.
+ *
+ * Unlike a baked keyframe {@link ShadeAnimationClip}, a `FoliageWindRig` defines the physical
+ * and botanical parameters of each skeletal branch joint (`branch_axis`, `compliance`,
+ * `natural_frequency`, `damping_ratio`, `max_angle`, `turbulence`, `phase_offset`).
+ *
+ * At runtime, `GPUAnimationManager` evaluates `shader_foliage_wind_apply` on the GPU, sampling
+ * the scene's 3D fluid wind field (`GPUSceneWind` / `wind_field_sample(pos_ws)`) at each bone's
+ * world position, stepping a second-order damped spring-damper oscillator with Strouhal vortex
+ * shedding, and contributing the resulting bone rotations into `pose_accumulator`.
+ */
+export class FoliageWindRig {
+    /**
+     * @param {Object} options
+     * @param {string} [options.name=""]
+     * @param {number} [options.root=0]
+     * @param {number} [options.weight=1.0]
+     * @param {FoliageWindJoint[]} [options.joints=[]]
+     * @returns {FoliageWindRig}
+     */
+    static from({ name, root, weight, joints }?: {
+        name?: string;
+        root?: number;
+        weight?: number;
+        joints?: FoliageWindJoint[];
+    }): FoliageWindRig;
+    /**
+     * Optional rig name.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Root node index (in a `SceneBundle` / `Prefab`, typically `0`) or root ECS entity ID (when bound).
+     * Used by the GPU solver to transform world-space wind vectors into the tree's model frame.
+     * @type {number}
+     */
+    root: number;
+    /**
+     * Overall rig contribution weight (`1.0` = full aeroelastic response).
+     * @type {number}
+     */
+    weight: number;
+    /**
+     * Aeroelastic joints in this rig.
+     * @type {FoliageWindJoint[]}
+     */
+    joints: FoliageWindJoint[];
+    /**
+     * @param {FoliageWindRig} other
+     * @returns {this}
+     */
+    copy(other: FoliageWindRig): this;
+    /**
+     * @returns {FoliageWindRig}
+     */
+    clone(): FoliageWindRig;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isFoliageWindRig: boolean;
+}
+import { FoliageWindJoint } from "./FoliageWindJoint.js";
+//# sourceMappingURL=FoliageWindRig.d.ts.map

package/src/shade/renderer/animation/foliage/FoliageWindRig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FoliageWindRig.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/foliage/FoliageWindRig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH;IA0BI;;;;;;;OAOG;IACH;QAN4B,IAAI,GAArB,MAAM;QACW,IAAI,GAArB,MAAM;QACW,MAAM,GAAvB,MAAM;QACuB,MAAM,GAAnC,gBAAgB,EAAE;QAChB,cAAc,CAY1B;IA3CD;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,QAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,QAFU,gBAAgB,EAAE,CAEhB;IAsBZ;;;OAGG;IACH,YAHW,cAAc,GACZ,IAAI,CAShB;IAED;;OAEG;IACH,SAFa,cAAc,CAM1B;IAGL;;;OAGG;IACH,2BAFU,OAAO,CAEwB;CANxC;iCAjFgC,uBAAuB"}

package/src/shade/renderer/animation/foliage/FoliageWindRig.js

@@ -0,0 +1,89 @@
+import { assert } from "../../../../core/assert.js";
+import { FoliageWindJoint } from "./FoliageWindJoint.js";
+
+/**
+ * Aeroelastic foliage bone rig descriptor for GPU fluid-driven skeletal wind animation.
+ *
+ * Unlike a baked keyframe {@link ShadeAnimationClip}, a `FoliageWindRig` defines the physical
+ * and botanical parameters of each skeletal branch joint (`branch_axis`, `compliance`,
+ * `natural_frequency`, `damping_ratio`, `max_angle`, `turbulence`, `phase_offset`).
+ *
+ * At runtime, `GPUAnimationManager` evaluates `shader_foliage_wind_apply` on the GPU, sampling
+ * the scene's 3D fluid wind field (`GPUSceneWind` / `wind_field_sample(pos_ws)`) at each bone's
+ * world position, stepping a second-order damped spring-damper oscillator with Strouhal vortex
+ * shedding, and contributing the resulting bone rotations into `pose_accumulator`.
+ */
+export class FoliageWindRig {
+    /**
+     * Optional rig name.
+     * @type {string}
+     */
+    name = "";
+
+    /**
+     * Root node index (in a `SceneBundle` / `Prefab`, typically `0`) or root ECS entity ID (when bound).
+     * Used by the GPU solver to transform world-space wind vectors into the tree's model frame.
+     * @type {number}
+     */
+    root = 0;
+
+    /**
+     * Overall rig contribution weight (`1.0` = full aeroelastic response).
+     * @type {number}
+     */
+    weight = 1.0;
+
+    /**
+     * Aeroelastic joints in this rig.
+     * @type {FoliageWindJoint[]}
+     */
+    joints = [];
+
+    /**
+     * @param {Object} options
+     * @param {string} [options.name=""]
+     * @param {number} [options.root=0]
+     * @param {number} [options.weight=1.0]
+     * @param {FoliageWindJoint[]} [options.joints=[]]
+     * @returns {FoliageWindRig}
+     */
+    static from({ name = "", root = 0, weight = 1.0, joints = [] } = {}) {
+        assert.isNonNegativeInteger(root, 'root');
+        assert.isArray(joints, 'joints');
+
+        const r = new FoliageWindRig();
+        r.name = name;
+        r.root = root;
+        r.weight = weight;
+        r.joints = joints.map((j) => (j && j.isFoliageWindJoint ? j.clone() : FoliageWindJoint.from(j)));
+        return r;
+    }
+
+    /**
+     * @param {FoliageWindRig} other
+     * @returns {this}
+     */
+    copy(other) {
+        assert.defined(other, 'other');
+        this.name = other.name;
+        this.root = other.root;
+        this.weight = other.weight;
+        this.joints = other.joints.map((j) => j.clone());
+        return this;
+    }
+
+    /**
+     * @returns {FoliageWindRig}
+     */
+    clone() {
+        const r = new FoliageWindRig();
+        r.copy(this);
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+FoliageWindRig.prototype.isFoliageWindRig = true;

package/src/shade/renderer/animation/foliage/chunk_foliage_wind_step.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Aeroelastic foliage bone step and local pose composition.
+ *
+ * - `foliage_wind_to_model(wind_ws, root_global)`: projects a world-space fluid velocity (m/s)
+ *   onto the unit local axes of the tree root's world matrix (`mat4_extract_scale` + `v3_safe_rcp`),
+ *   preserving metric wind speed regardless of node scale.
+ * - `foliage_wind_step(joint, wind_model, dt)`: evaluates cross-flow aerodynamic drag torque and
+ *   Strouhal vortex-shedding oscillation around the bone's rest `branch_axis` (using
+ *   `build_orthonormal_matrix_n` when flow is axial), soft-saturates the target deflection to
+ *   `joint.max_angle`, and advances the bone's 2nd-order damped spring-damper state with an
+ *   unconditionally stable implicit Euler step.
+ * - `foliage_wind_local_rotation(rest_rotation, angular_displacement)`: composes the bone's
+ *   rest quaternion with the axis-angle deflection (`quat_from_axis_angle` + `quat_multiply`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_foliage_wind_step: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_foliage_wind_step.d.ts.map

package/src/shade/renderer/animation/foliage/chunk_foliage_wind_step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_foliage_wind_step.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/foliage/chunk_foliage_wind_step.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,sCAFU,SAAS,CAmHjB;0BApIwB,oCAAoC"}