@woosh/meep-engine 3.52.0 → 3.54.0

package/src/shade/playground/additive_blending/main.js

@@ -0,0 +1,529 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { AnimationCurve } from "../../../engine/animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../../engine/animation/curve/Keyframe.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { Name } from "../../../engine/ecs/name/Name.js";
+import { TransformAttachment } from "../../../engine/ecs/transform-attachment/TransformAttachment.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { MeshSkin } from "../../../engine/graphics/ecs/mesh-v2/MeshSkin.js";
+import { AnimationClips } from "../../../engine/graphics3/animation/AnimationClips.js";
+import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
+import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.js";
+import { pose_evaluate_local } from "../../renderer/animation/pose/pose_evaluate_local.js";
+import { PosePlayback } from "../../renderer/animation/pose/PosePlayback.js";
+import { ShadeAnimationChannel } from "../../renderer/animation/ShadeAnimationChannel.js";
+import { ShadeAnimationClip } from "../../renderer/animation/ShadeAnimationClip.js";
+import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
+import { Node3DProperty } from "../../renderer/object_property/Node3DProperty.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
+import { render_submitted_frames } from "../render_submitted_frames.js";
+import { add_floor } from "../skinned_blas_refit/add_floor.js";
+import { place_character } from "../skinned_blas_refit/place_character.js";
+
+const CHARACTER_URL = '/test_assets/Michelle.glb';
+const SPACING = 1.25;
+
+/**
+ * Multiply two unit quaternions `a * b`.
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number[]}
+ */
+function quat_mul(a, b) {
+    return [
+        a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+        a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+        a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+        a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+    ];
+}
+
+/**
+ * Axis-angle unit quaternion.
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} rad
+ * @returns {number[]}
+ */
+function quat_axis_angle(ax, ay, az, rad) {
+    const half = rad * 0.5;
+    const s = Math.sin(half);
+    return [ax * s, ay * s, az * s, Math.cos(half)];
+}
+
+/**
+ * Build a looping 4-keyframe rotation channel that starts at `ref_q` (`t=0`), swings through
+ * `ref_q * delta_a` (`t=0.5`) and `ref_q * delta_b` (`t=1.0`), and returns to `ref_q` (`t=1.5`).
+ *
+ * @param {number} target
+ * @param {number[]} ref_q
+ * @param {number[]} delta_a
+ * @param {number[]} delta_b
+ * @returns {ShadeAnimationChannel}
+ */
+function make_wave_rotation_channel(target, ref_q, delta_a, delta_b) {
+    const q0 = ref_q;
+    const q1 = quat_mul(ref_q, delta_a);
+    const q2 = quat_mul(ref_q, delta_b);
+    const q3 = ref_q;
+    const times = [0.0, 0.5, 1.0, 1.5];
+    const qs = [q0, q1, q2, q3];
+
+    // Ensure consecutive hemisphere continuity
+    for (let i = 1; i < qs.length; i++) {
+        const prev = qs[i - 1];
+        const cur = qs[i];
+        if (prev[0] * cur[0] + prev[1] * cur[1] + prev[2] * cur[2] + prev[3] * cur[3] < 0) {
+            qs[i] = [-cur[0], -cur[1], -cur[2], -cur[3]];
+        }
+    }
+
+    return ShadeAnimationChannel.from({
+        target,
+        property: Node3DProperty.Rotation,
+        curves: {
+            x: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][0]))),
+            y: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][1]))),
+            z: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][2]))),
+            w: AnimationCurve.from(times.map((t, i) => Keyframe.from(t, qs[i][3]))),
+        },
+    });
+}
+
+/**
+ * Author a full-body clip where all joints start at `base_clip`'s `t = start_time` reference pose,
+ * lower-body joints remain static at that reference pose, and upper-body joints perform a clearly
+ * visible wave + torso twist + head nod gesture. Then convert it via `ShadeAnimationClip.from_additive`.
+ *
+ * @param {import("../../renderer/loader/SceneBundle.js").SceneBundle} bundle
+ * @param {ShadeAnimationClip} base_clip
+ */
+function build_upper_body_additive_clip(bundle, base_clip) {
+    const ref_time = base_clip.start_time;
+    const nodes = bundle.nodes;
+
+    /** @type {Map<number, Transform64>} */
+    const ref_poses = new Map();
+    for (let i = 0; i < nodes.length; i++) {
+        const p = new Transform64();
+        p.copy(nodes[i].local);
+        ref_poses.set(i, p);
+    }
+    base_clip.apply(ref_time, idx => ref_poses.get(idx));
+
+    // Upper-body gesture definitions keyed by Mixamo joint suffix
+    const upper_gestures = new Map([
+        ['Spine1', [quat_axis_angle(0, 1, 0, 18 * DEG_TO_RAD), quat_axis_angle(0, 1, 0, -18 * DEG_TO_RAD)]],
+        ['Spine2', [quat_axis_angle(0, 0, 1, 14 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, -14 * DEG_TO_RAD)]],
+        ['Neck', [quat_axis_angle(1, 0, 0, 16 * DEG_TO_RAD), quat_axis_angle(1, 0, 0, -12 * DEG_TO_RAD)]],
+        ['Head', [quat_axis_angle(0, 1, 0, 25 * DEG_TO_RAD), quat_axis_angle(0, 1, 0, -25 * DEG_TO_RAD)]],
+        ['RightArm', [quat_axis_angle(0, 0, 1, -55 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, -35 * DEG_TO_RAD)]],
+        ['RightForeArm', [quat_axis_angle(1, 0, 1, 45 * DEG_TO_RAD), quat_axis_angle(1, 0, -1, -35 * DEG_TO_RAD)]],
+        ['LeftArm', [quat_axis_angle(0, 0, 1, 40 * DEG_TO_RAD), quat_axis_angle(0, 0, 1, 15 * DEG_TO_RAD)]],
+    ]);
+
+    const raw_channels = [];
+
+    for (let i = 0; i < nodes.length; i++) {
+        const name = nodes[i].name ?? '';
+        const ref_pose = ref_poses.get(i);
+        const ref_q = [ref_pose.rotation_x, ref_pose.rotation_y, ref_pose.rotation_z, ref_pose.rotation_w];
+
+        let matched = null;
+        for (const [suffix, deltas] of upper_gestures.entries()) {
+            if (name.endsWith(suffix)) {
+                matched = deltas;
+                break;
+            }
+        }
+
+        if (matched !== null) {
+            raw_channels.push(make_wave_rotation_channel(i, ref_q, matched[0], matched[1]));
+        } else if (/UpLeg|Leg|Foot|Hips/i.test(name)) {
+            // Static lower-body channel at the Samba reference pose (not rest pose) —
+            // `ShadeAnimationClip.from_additive` must strip these automatically!
+            raw_channels.push(
+                ShadeAnimationChannel.from({
+                    target: i,
+                    property: Node3DProperty.Rotation,
+                    curves: {
+                        x: AnimationCurve.from([Keyframe.from(0, ref_q[0]), Keyframe.from(1.5, ref_q[0])]),
+                        y: AnimationCurve.from([Keyframe.from(0, ref_q[1]), Keyframe.from(1.5, ref_q[1])]),
+                        z: AnimationCurve.from([Keyframe.from(0, ref_q[2]), Keyframe.from(1.5, ref_q[2])]),
+                        w: AnimationCurve.from([Keyframe.from(0, ref_q[3]), Keyframe.from(1.5, ref_q[3])]),
+                    },
+                })
+            );
+        }
+    }
+
+    const raw_clip = ShadeAnimationClip.from({
+        name: "UpperBodyWave_raw",
+        channels: raw_channels,
+    });
+
+    const additive_clip = ShadeAnimationClip.from_additive(raw_clip, {
+        reference_clip: base_clip,
+        reference_time: ref_time,
+        rest_of: idx => nodes[idx]?.local,
+        name: "UpperBodyWave_additive",
+    });
+
+    return {
+        raw_channel_count: raw_clip.channels.length,
+        additive_channel_count: additive_clip.channels.length,
+        stripped_channel_count: raw_clip.channels.length - additive_clip.channels.length,
+        additive_clip,
+    };
+}
+
+function skinned_meshes_of(dataset, instance) {
+    return Array.from(instance.mesh_entities).filter(entity => dataset.getComponent(entity, MeshSkin) !== undefined);
+}
+
+async function world_bounds_of(scene_context, entity) {
+    const row = row_of_entity(entity);
+    const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
+    const box = record.bounding_box;
+    const low = new Vector3(box[0], box[1], box[2]);
+    const high = new Vector3(box[3], box[4], box[5]);
+    return {
+        low,
+        high,
+        radius: Math.hypot(high.x - low.x, high.y - low.y, high.z - low.z) * 0.5,
+    };
+}
+
+export async function start() {
+    const element = id => document.getElementById(id);
+    const status_el = element('status');
+    const audit_el = element('audit');
+    const stats_el = element('stats');
+
+    function set_status(text, kind = '') {
+        status_el.textContent = text;
+        status_el.className = kind;
+    }
+
+    const canvas = element('view');
+    const context = canvas.getContext('webgpu');
+    if (context === null) {
+        set_status('no WebGPU context available', 'fail');
+        return;
+    }
+
+    const renderer = new Renderer();
+    renderer.feature_path_tracing_enabled = false;
+    renderer.feature_taa_enabled = true;
+
+    set_status('acquiring WebGPU device…');
+    await renderer.initialize({ context });
+
+    const camera = new PerspectiveCamera();
+    camera.near = 0.01;
+    camera.far = 200;
+    camera.fov = 45 * DEG_TO_RAD;
+    camera.aspect = renderer.aspect_ratio;
+
+    const scene = new Scene();
+    const dataset = new EntityComponentDataset();
+    scene.dataset = dataset;
+
+    const controller = new OrbitalCameraController(camera, document.body);
+    const scene_context = renderer.scenes.obtain(scene);
+    const animations = scene_context.animation_manager;
+
+    set_status(`loading ${CHARACTER_URL} & rebasing additive clip…`);
+
+    const asset_manager = await make_playground_asset_manager();
+    const bundle = await load_gltf(CHARACTER_URL, { assetManager: asset_manager });
+    const base_src_clip = bundle.clips.find(c => /samba|dance/i.test(c.name ?? '')) ?? bundle.clips[0];
+
+    const additive_info = build_upper_body_additive_clip(bundle, base_src_clip);
+    bundle.clips.push(additive_info.additive_clip);
+
+    const prefab = prefab_compile(bundle);
+
+    // Spawn 3 characters side by side:
+    //  0 (Left,   x = -SPACING): Base dance only (weight = 1)
+    //  1 (Center, x = 0):        Base dance (weight = base_w) + Additive upper-body (weight = add_w)
+    //  2 (Right,  x = +SPACING): Additive upper-body only (weight = add_w)
+    const placements = [
+        { label: 'Left (Base Only)', x: -SPACING },
+        { label: 'Center (Base + Additive)', x: 0 },
+        { label: 'Right (Additive Only)', x: SPACING },
+    ];
+
+    const characters = [];
+    const all_meshes = [];
+
+    for (let i = 0; i < placements.length; i++) {
+        const { root, instance } = place_character(scene_context, dataset, prefab, placements[i].x, 0);
+        const meshes = skinned_meshes_of(dataset, instance);
+        all_meshes.push(...meshes);
+
+        const clips = dataset.getComponent(root, AnimationClips).clips;
+        const base_clip = clips.find(c => c.name === base_src_clip.name) ?? clips[0];
+        const add_clip = clips.find(c => c.name === "UpperBodyWave_additive");
+
+        let base_id = null;
+        let add_id = null;
+
+        if (i === 0 || i === 1) {
+            base_id = animations.register_clip(base_clip);
+            animations.set_playback_weight(base_id, 1.0);
+            animations.set_flags(base_id, AnimationClipFlags.Loop);
+            animations.start(base_id);
+        }
+
+        if (i === 1 || i === 2) {
+            add_id = animations.register_clip(add_clip);
+            animations.set_playback_weight(add_id, 1.0);
+            animations.set_flags(add_id, AnimationClipFlags.Loop);
+            animations.start(add_id);
+        }
+
+        // Map joint short names to entities for live GPU vs CPU verification
+        const joints_by_name = new Map();
+        for (const ch of base_clip.channels) {
+            const name_comp = dataset.getComponent(ch.target, Name);
+            if (name_comp !== undefined) {
+                joints_by_name.set(name_comp.getValue(), ch.target);
+            }
+        }
+
+        characters.push({
+            label: placements[i].label,
+            root,
+            instance,
+            meshes,
+            base_clip,
+            add_clip,
+            base_id,
+            add_id,
+            joints_by_name,
+        });
+    }
+
+    place_light(scene, make_sunlight({ intensity: 6 }));
+
+    await render_submitted_frames(renderer, camera, scene, 8);
+
+    let low = null;
+    let high = null;
+    for (const mesh_entity of all_meshes) {
+        const bounds = await world_bounds_of(scene_context, mesh_entity);
+        low = low === null ? bounds.low : new Vector3(
+            Math.min(low.x, bounds.low.x), Math.min(low.y, bounds.low.y), Math.min(low.z, bounds.low.z)
+        );
+        high = high === null ? bounds.high : new Vector3(
+            Math.max(high.x, bounds.high.x), Math.max(high.y, bounds.high.y), Math.max(high.z, bounds.high.z)
+        );
+    }
+
+    const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
+    add_floor(scene_context, Math.max(span.x, span.z) * 4, low.y);
+
+    const radius = Math.hypot(span.x, span.y, span.z) * 0.48;
+    camera_frame_sphere(
+        controller,
+        radius,
+        new Vector3((low.x + high.x) / 2, (low.y + high.y) / 2, (low.z + high.z) / 2)
+    );
+    camera.near = radius * 0.01;
+    camera.far = radius * 400;
+
+    load_default_environment(scene).then(applied => {
+        if (applied) renderer.indicate_view_change();
+    });
+
+    let animating = true;
+    let base_weight = 1.0;
+    let additive_weight = 1.0;
+
+    function apply_weights() {
+        const center = characters[1];
+        const right = characters[2];
+        animations.set_playback_weight(center.base_id, base_weight);
+        animations.set_playback_weight(center.add_id, additive_weight);
+        animations.set_playback_weight(right.add_id, additive_weight);
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    }
+
+    const slider_add = element('slider_additive_weight');
+    const val_add = element('val_additive_weight');
+    const slider_base = element('slider_base_weight');
+    const val_base = element('val_base_weight');
+
+    slider_add.addEventListener('input', () => {
+        additive_weight = Number.parseFloat(slider_add.value);
+        val_add.textContent = additive_weight.toFixed(2);
+        apply_weights();
+    });
+
+    slider_base.addEventListener('input', () => {
+        base_weight = Number.parseFloat(slider_base.value);
+        val_base.textContent = base_weight.toFixed(2);
+        apply_weights();
+    });
+
+    document.querySelectorAll('.preset').forEach(btn => {
+        btn.addEventListener('click', () => {
+            document.querySelectorAll('.preset').forEach(b => b.classList.remove('active'));
+            btn.classList.add('active');
+            base_weight = Number.parseFloat(btn.dataset.base);
+            additive_weight = Number.parseFloat(btn.dataset.add);
+            slider_base.value = String(base_weight);
+            slider_add.value = String(additive_weight);
+            val_base.textContent = base_weight.toFixed(2);
+            val_add.textContent = additive_weight.toFixed(2);
+            apply_weights();
+        });
+    });
+
+    const toggle_btn = element('toggle_animation');
+    toggle_btn.addEventListener('click', () => {
+        animating = !animating;
+        toggle_btn.textContent = animating ? 'Freeze pose' : 'Resume dance';
+    });
+
+    const pt_checkbox = element('path_tracing');
+    pt_checkbox.addEventListener('change', () => {
+        renderer.feature_path_tracing_enabled = pt_checkbox.checked;
+        renderer.feature_taa_enabled = !pt_checkbox.checked;
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    });
+
+    /**
+     * Read back GPU transform rows for Left, Center, and Right characters at deterministic clip times
+     * and verify:
+     *  1. Static lower-body channels were stripped by `ShadeAnimationClip.from_additive`.
+     *  2. Center dancer's lower-body joint (`LeftUpLeg`) matches Left dancer's GPU row.
+     *  3. Center dancer's upper-body joint (`RightArm`) matches the CPU `pose_evaluate_local` twin
+     *     and diverges from Left dancer when `additive_weight > 0`.
+     */
+    async function verify_additive({ sample_base_time = 0.6, sample_add_time = 0.5 } = {}) {
+        const was_animating = animating;
+        animating = false;
+
+        try {
+            const [left, center, right] = characters;
+            animations.set_time(left.base_id, sample_base_time);
+            animations.set_time(center.base_id, sample_base_time);
+            animations.set_time(center.add_id, sample_add_time);
+            animations.set_time(right.add_id, sample_add_time);
+
+            await render_submitted_frames(renderer, camera, scene, 2, 0);
+
+            const find_joint = (char, suffix) => {
+                for (const [name, entity] of char.joints_by_name.entries()) {
+                    if (name.endsWith(suffix)) return entity;
+                }
+                return null;
+            };
+
+            const left_leg = find_joint(left, 'LeftUpLeg');
+            const center_leg = find_joint(center, 'LeftUpLeg');
+            const left_arm = find_joint(left, 'RightArm');
+            const center_arm = find_joint(center, 'RightArm');
+            const right_arm = find_joint(right, 'RightArm');
+
+            const transforms_table = scene_context.scene_database.get('transforms');
+            const read_gpu_rot = async entity => {
+                const rec = await scene_context.scene_database.debug_table_read_element('transforms', row_of_entity(entity));
+                return Array.from(rec.local_rotation);
+            };
+
+            const gpu_left_leg = await read_gpu_rot(left_leg);
+            const gpu_center_leg = await read_gpu_rot(center_leg);
+            const gpu_left_arm = await read_gpu_rot(left_arm);
+            const gpu_center_arm = await read_gpu_rot(center_arm);
+            const gpu_right_arm = await read_gpu_rot(right_arm);
+
+            // CPU twin evaluation on Center dancer's RightArm
+            const center_arm_rest = dataset.getComponent(center_arm, TransformAttachment).transform;
+            const cpu_center_arm = pose_evaluate_local(new Transform64(), center_arm, center_arm_rest, [
+                PosePlayback.from(center.base_clip, sample_base_time, base_weight),
+                PosePlayback.from(center.add_clip, sample_add_time, additive_weight),
+            ]);
+
+            const quat_dot = (a, b) => Math.abs(a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3]);
+            const leg_match_dot = quat_dot(gpu_left_leg, gpu_center_leg);
+            const gpu_cpu_arm_dot = quat_dot(gpu_center_arm, [
+                cpu_center_arm.rotation_x,
+                cpu_center_arm.rotation_y,
+                cpu_center_arm.rotation_z,
+                cpu_center_arm.rotation_w,
+            ]);
+            const arm_delta_deg = Math.acos(Math.min(1, quat_dot(gpu_left_arm, gpu_center_arm))) * 2 * (180 / Math.PI);
+
+            const report = {
+                stripped_lower_channels: additive_info.stripped_channel_count,
+                surviving_upper_channels: additive_info.additive_channel_count,
+                leg_match_dot,
+                gpu_cpu_arm_dot,
+                arm_delta_deg,
+                gpu_center_arm,
+                gpu_right_arm,
+                pass: additive_info.stripped_channel_count > 0 && gpu_cpu_arm_dot > 0.9999,
+            };
+
+            audit_el.textContent =
+                `stripped static channels: ${report.stripped_lower_channels} (kept ${report.surviving_upper_channels} upper)\n` +
+                `GPU vs CPU twin dot (RightArm): ${report.gpu_cpu_arm_dot.toFixed(6)}\n` +
+                `Lower-body (LeftUpLeg) dot:     ${report.leg_match_dot.toFixed(6)}\n` +
+                `Upper-body additive deflection: ${report.arm_delta_deg.toFixed(1)}°`;
+
+            set_status(
+                report.pass
+                    ? `PASS — GPU & CPU twin match (${report.arm_delta_deg.toFixed(1)}° upper-body additive offset)`
+                    : `FAIL — GPU/CPU mismatch`,
+                report.pass ? 'pass' : 'fail'
+            );
+
+            return report;
+        } finally {
+            animating = was_animating;
+        }
+    }
+
+    element('run_verify').addEventListener('click', () => {
+        verify_additive().catch(console.error);
+    });
+
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+    globalThis.characters = characters;
+    globalThis.verify_additive = verify_additive;
+
+    await verify_additive();
+
+    create_frame_loop((time_delta_s, raf_time_s) => {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+        renderer.resize(width, height);
+        renderer.pixel_ratio = window.devicePixelRatio;
+        camera.aspect = width / height;
+
+        controller.update();
+        renderer.render(camera, scene, animating ? time_delta_s : 0);
+
+        const fps = raf_time_s > 0 ? (1 / raf_time_s).toFixed(0) : '--';
+        stats_el.textContent = `${(raf_time_s * 1000).toFixed(1)} ms · ${fps} fps · base=${base_weight.toFixed(2)} add=${additive_weight.toFixed(2)}`;
+    }, 60);
+}

package/src/shade/playground/foliage_wind/README.md

@@ -0,0 +1,18 @@
+# Procedural Foliage & GPU Fluid Wind Playground (`foliage_wind`)
+
+Interactive ECS playground demonstrating Meep Engine's procedural tree & foliage generation pipeline (`src/generation/foliage/`) coupled with GPU fluid-driven skeletal wind animation (`FoliageWindSystem` + `GPUFluidSystem` + `FluidEffectorsSystem`).
+
+## Architecture (ECS)
+
+Every element of the scene is driven through Meep's Entity-Component-System (`EntityManager` + `EntityComponentDataset`):
+
+1. **Tree Instantiation (`prefab_instantiate`)**:
+   - `generate_tree({ preset, seed })` generates a multi-LOD `TreeAsset` whose compiled `Prefab` carries `ShadedGeometry`, `MeshSkin`, and `FoliageWindRig` descriptors.
+   - `prefab_instantiate(lod_asset.prefab, dataset, root)` spawns the node hierarchy into `dataset` and attaches `FoliageWindRigs` on `root` with deterministic position-seeded flutter phase desynchronization.
+2. **ECS Graphics & Animation Systems**:
+   - `TransformAttachmentSystem` + `ParentEntitySystem` maintain the entity hierarchy.
+   - `ShadedGeometrySystem` and `MeshSkinSystem` register meshlets and skinning matrices with `GPUSceneContext`.
+   - `FoliageWindSystem` observes `[FoliageWindRigs, Transform64]`, holds the bone `RowChains`, and registers each tree's aeroelastic bone rig with `GPUAnimationManager`.
+   - `LightSystem` mirrors directional sun and sky fill `Light` entities into the scene.
+3. **ECS 3D Fluid Wind Simulation**:
+   - `FluidEffectorsSystem` + `GPUFluidSystem` step a 3-cascade 3D Navier-Stokes fluid grid (`GPUFluidComponent`) driven by a `GlobalFluidEffector` (ambient wind + periodic gusts) and a travelling `ImpulseFluidEffector` + `VortexFluidEffector` gust wave, publishing the velocity field to `GPUSceneWind` where `shader_foliage_wind_apply` (`chunk_foliage_wind_step`) samples it at every branch bone's world position.

package/src/shade/playground/foliage_wind/foliage_world.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Builds a subdivided meadow ground grid `MeshletGeometry` with subtle organic height undulation.
+ *
+ * @param {number} [half_extent=32]
+ * @param {number} [subdivisions=24]
+ * @returns {import("../../renderer/geometry/MeshletGeometry.js").MeshletGeometry}
+ */
+export function build_meadow_ground_geometry(half_extent?: number, subdivisions?: number): import("../../renderer/geometry/MeshletGeometry.js").MeshletGeometry;
+/**
+ * Creates a full ECS world (`EntityManager` + `EntityComponentDataset`) for the Foliage & Wind
+ * Playground, wiring:
+ * - `ParentEntitySystem`
+ * - `TransformAttachmentSystem`
+ * - `ShadedGeometrySystem`
+ * - `MeshSkinSystem`
+ * - `FoliageWindSystem`
+ * - `LightSystem`
+ * - `FluidEffectorsSystem`
+ * - `GPUFluidSystem`
+ *
+ * @param {import("../../../engine/graphics3/GraphicsEngine.js").GraphicsEngine} graphics
+ * @param {import("../../renderer/scene/Scene.js").Scene} scene
+ * @param {object} [initial_options]
+ * @param {"specimen"|"grove"} [initial_options.mode="specimen"]
+ * @param {string} [initial_options.preset="oak"]
+ * @param {number} [initial_options.seed=1337]
+ * @param {number} [initial_options.lod=0]
+ * @param {boolean} [initial_options.showLeaves=true]
+ * @param {number} [initial_options.windSpeed=6.5]
+ * @param {number} [initial_options.headingDeg=25]
+ * @param {number} [initial_options.gustStrength=4.5]
+ * @param {number} [initial_options.gustPeriod=5.5]
+ * @param {number} [initial_options.windWeight=1.0]
+ * @param {boolean} [initial_options.enableGPUFluid=true]
+ */
+export function createFoliageWindWorld(graphics: import("../../../engine/graphics3/GraphicsEngine.js").GraphicsEngine, scene: import("../../renderer/scene/Scene.js").Scene, initial_options?: {
+    mode?: "specimen" | "grove";
+    preset?: string;
+    seed?: number;
+    lod?: number;
+    showLeaves?: boolean;
+    windSpeed?: number;
+    headingDeg?: number;
+    gustStrength?: number;
+    gustPeriod?: number;
+    windWeight?: number;
+    enableGPUFluid?: boolean;
+}): Promise<{
+    entities: EntityManager;
+    dataset: EntityComponentDataset;
+    state: {
+        mode: "specimen" | "grove";
+        preset: string;
+        seed: number;
+        lod: number;
+        showLeaves: boolean;
+        windSpeed: number;
+        headingDeg: number;
+        gustStrength: number;
+        gustPeriod: number;
+        windWeight: number;
+    };
+    activeTrees: {
+        root: number;
+        instance: import("../../../engine/graphics3/prefab/PrefabInstance.js").PrefabInstance;
+        lod_asset: import("../../../generation/foliage/asset/TreeLODAsset.js").TreeLODAsset;
+        preset: string;
+    }[];
+    fluidEntity: number;
+    gustEntity: number;
+    globalWind: GlobalFluidEffector;
+    impulseEffector: ImpulseFluidEffector;
+    vortexEffector: VortexFluidEffector;
+    rebuildTrees: (overrides?: Partial<{
+        mode: "specimen" | "grove";
+        preset: string;
+        seed: number;
+        lod: number;
+        showLeaves: boolean;
+        windSpeed: number;
+        headingDeg: number;
+        gustStrength: number;
+        gustPeriod: number;
+        windWeight: number;
+    }>) => void;
+    setWind: (overrides?: Partial<{
+        mode: "specimen" | "grove";
+        preset: string;
+        seed: number;
+        lod: number;
+        showLeaves: boolean;
+        windSpeed: number;
+        headingDeg: number;
+        gustStrength: number;
+        gustPeriod: number;
+        windWeight: number;
+    }>) => void;
+    triggerLocalGust: ({ strength, vortexStrength, radius, duration, }?: {
+        strength?: number;
+        vortexStrength?: number;
+        radius?: number;
+        duration?: number;
+    }) => void;
+    step: (dt: number) => void;
+    getStats: () => {
+        mode: "specimen" | "grove";
+        preset: string;
+        seed: number;
+        lod: number;
+        showLeaves: boolean;
+        treeCount: number;
+        totalJoints: number;
+        totalVertices: number;
+        totalTriangles: number;
+        activeRigCount: number;
+        windSpeed: number;
+        gustStrength: number;
+        windWeight: number;
+        gustActive: boolean;
+    };
+    destroy: () => Promise<void>;
+}>;
+/**
+ * Ordered list of all species presets available in the playground.
+ * @type {string[]}
+ */
+export const FOLIAGE_PLAYGROUND_PRESETS: string[];
+import { EntityManager } from "../../../engine/ecs/EntityManager.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { GlobalFluidEffector } from "../../../engine/physics/fluid/effector/GlobalFluidEffector.js";
+import { ImpulseFluidEffector } from "../../../engine/physics/fluid/effector/ImpulseFluidEffector.js";
+import { VortexFluidEffector } from "../../../engine/physics/fluid/effector/VortexFluidEffector.js";
+//# sourceMappingURL=foliage_world.d.ts.map

package/src/shade/playground/foliage_wind/foliage_world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foliage_world.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/foliage_wind/foliage_world.js"],"names":[],"mappings":"AAoDA;;;;;;GAMG;AACH,2DAJW,MAAM,iBACN,MAAM,GACJ,OAAO,4CAA4C,EAAE,eAAe,CA4DhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iDAfW,OAAO,6CAA6C,EAAE,cAAc,SACpE,OAAO,+BAA+B,EAAE,KAAK;IAER,IAAI,GAAzC,UAAU,GAAC,OAAO;IACO,MAAM,GAA/B,MAAM;IACmB,IAAI,GAA7B,MAAM;IACmB,GAAG,GAA5B,MAAM;IACoB,UAAU,GAApC,OAAO;IACkB,SAAS,GAAlC,MAAM;IACmB,UAAU,GAAnC,MAAM;IACmB,YAAY,GAArC,MAAM;IACmB,UAAU,GAAnC,MAAM;IACmB,UAAU,GAAnC,MAAM;IACoB,cAAc,GAAxC,OAAO;;;;;;;;;;;;;;;;;cAoJS,MAAM;kBAAY,OAAO,oDAAoD,EAAE,cAAc;mBAAa,OAAO,mDAAmD,EAAE,YAAY;gBAAU,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAoK7L,QAAQ,GAAzB,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,MAAM,GAAvB,MAAM;QACW,QAAQ,GAAzB,MAAM;;eAsCN,MAAM;;;;;;;;;;;;;;;;;;GAwGpB;AArjBD;;;GAGG;AACH,yCAFU,MAAM,EAAE,CAYhB;8BA3C4B,sCAAsC;uCAD7B,+CAA+C;oCAmBlD,+DAA+D;qCAC9D,gEAAgE;oCACjE,+DAA+D"}