@woosh/meep-engine 3.55.0 → 3.57.0

package/src/shade/playground/foliage_wind/foliage_world.js

@@ -1,602 +1,600 @@
-import { assert } from "../../../core/assert.js";
-import { Quaternion } from "../../../core/geom/Quaternion.js";
-import { Vector3 } from "../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-import { PI2 } from "../../../core/math/PI2.js";
-import { seededRandom } from "../../../core/math/random/seededRandom.js";
-import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
-import { EntityManager } from "../../../engine/ecs/EntityManager.js";
-import { ParentEntitySystem } from "../../../engine/ecs/parent/ParentEntitySystem.js";
-import { TransformAttachmentSystem } from "../../../engine/ecs/transform-attachment/TransformAttachmentSystem.js";
-import { t64_announce_change } from "../../../engine/ecs/transform/t64_announce_change.js";
-import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
-import { Light } from "../../../engine/graphics/ecs/light/Light.js";
-import { DrawMode } from "../../../engine/graphics/ecs/mesh-v2/DrawMode.js";
-import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { FoliageWindRigs } from "../../../engine/graphics3/animation/FoliageWindRigs.js";
-import { FoliageWindSystem } from "../../../engine/graphics3/FoliageWindSystem.js";
-import { GPUFluidSystem } from "../../../engine/graphics3/GPUFluidSystem.js";
-import { LightSystem } from "../../../engine/graphics3/LightSystem.js";
-import { MeshSkinSystem } from "../../../engine/graphics3/MeshSkinSystem.js";
-import { prefab_instance_destroy, prefab_instantiate } from "../../../engine/graphics3/prefab/prefab_instantiate.js";
-import { ShadedGeometrySystem } from "../../../engine/graphics3/ShadedGeometrySystem.js";
-import { FluidEffectorsComponent } from "../../../engine/physics/fluid/ecs/FluidEffectorsComponent.js";
-import { FluidEffectorsSystem } from "../../../engine/physics/fluid/ecs/FluidEffectorsSystem.js";
-import { GPUFluidComponent } from "../../../engine/physics/fluid/ecs/GPUFluidComponent.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";
-import { TreePreset } from "../../../generation/foliage/config/TreePreset.js";
-import { generate_tree } from "../../../generation/foliage/asset/generate_tree.js";
-import { Attribute } from "../../renderer/geometry/Attribute.js";
-import { Geometry } from "../../renderer/geometry/Geometry.js";
-import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
-import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
-import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
-
-/**
- * Ordered list of all species presets available in the playground.
- * @type {string[]}
- */
-export const FOLIAGE_PLAYGROUND_PRESETS = [
-    TreePreset.Oak,
-    TreePreset.Pine,
-    TreePreset.Birch,
-    TreePreset.Willow,
-    TreePreset.Maple,
-    TreePreset.Spruce,
-    TreePreset.Palm,
-    TreePreset.Shrub,
-    TreePreset.Fern,
-];
-
-/**
- * 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 = 32, subdivisions = 24) {
-    const stride = subdivisions + 1;
-    const vertex_count = stride * stride;
-    const quad_count = subdivisions * subdivisions;
-
-    const positions = new Float32Array(vertex_count * 3);
-    const normals = new Float32Array(vertex_count * 3);
-    const uvs = new Float32Array(vertex_count * 2);
-    const indices = new Uint32Array(quad_count * 6);
-
-    let v = 0;
-    for (let iz = 0; iz <= subdivisions; iz++) {
-        const tz = iz / subdivisions;
-        const z = (tz * 2 - 1) * half_extent;
-        for (let ix = 0; ix <= subdivisions; ix++) {
-            const tx = ix / subdivisions;
-            const x = (tx * 2 - 1) * half_extent;
-
-            positions[v * 3] = x;
-            positions[v * 3 + 1] = 0;
-            positions[v * 3 + 2] = z;
-
-            normals[v * 3] = 0;
-            normals[v * 3 + 1] = 1;
-            normals[v * 3 + 2] = 0;
-
-            uvs[v * 2] = tx * 8;
-            uvs[v * 2 + 1] = tz * 8;
-            v++;
-        }
-    }
-
-    let idx = 0;
-    for (let iz = 0; iz < subdivisions; iz++) {
-        for (let ix = 0; ix < subdivisions; ix++) {
-            const i00 = iz * stride + ix;
-            const i10 = i00 + 1;
-            const i01 = (iz + 1) * stride + ix;
-            const i11 = i01 + 1;
-
-            indices[idx++] = i00;
-            indices[idx++] = i01;
-            indices[idx++] = i10;
-
-            indices[idx++] = i10;
-            indices[idx++] = i01;
-            indices[idx++] = i11;
-        }
-    }
-
-    const geometry = new Geometry();
-    geometry.index = Attribute.from(indices, 1, "index");
-    geometry.addAttribute(Attribute.from(positions, 3, "position"));
-    geometry.addAttribute(Attribute.from(normals, 3, "normal"));
-    geometry.addAttribute(Attribute.from(uvs, 2, "uv"));
-    geometry.ensureTangents();
-
-    return meshlet_geometry_build_from_geometry(geometry);
-}
-
-/**
- * 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 async function createFoliageWindWorld(graphics, scene, initial_options = {}) {
-    assert.defined(graphics, 'graphics');
-    assert.defined(scene, 'scene');
-
-    await MeshoptClusterizer.ready;
-
-    const enable_gpu_fluid = initial_options.enableGPUFluid !== false;
-
-    const entities = new EntityManager();
-    entities.fixedUpdateStepSize = 1 / 60;
-
-    const dataset = new EntityComponentDataset();
-    dataset.registerComponentType(GPUFluidComponent);
-
-    entities.addSystem(new ParentEntitySystem());
-    entities.addSystem(new TransformAttachmentSystem());
-    entities.addSystem(new ShadedGeometrySystem(graphics, scene));
-    entities.addSystem(new MeshSkinSystem(graphics, scene));
-    entities.addSystem(new FoliageWindSystem(graphics, scene));
-    entities.addSystem(new LightSystem(graphics, scene));
-    entities.addSystem(new FluidEffectorsSystem());
-
-    if (enable_gpu_fluid && typeof graphics.add_extension === "function") {
-        entities.addSystem(new GPUFluidSystem(graphics, scene));
-    }
-
-    entities.attachDataset(dataset);
-
-    await new Promise((resolve, reject) => entities.startup(resolve, reject));
-
-    // --- 1. ECS Lighting Entities ---
-    const sun_entity = dataset.createEntity();
-    const sun_light = new Light();
-    sun_light.type.set(Light.Type.DIRECTION);
-    sun_light.color.setRGB(1.0, 0.96, 0.88);
-    sun_light.intensity.set(2.2);
-    sun_light.radius.set(0.006475);
-    sun_light.castShadow.set(true);
-    sun_light.maxShadowDistance.set(60);
-
-    const sun_transform = new Transform64();
-    const sun_dir = new Vector3(-0.48, -0.78, -0.40).normalize();
-    const sun_rot = new Quaternion().fromUnitVectors(Vector3.forward, sun_dir);
-    sun_transform.setRotation(sun_rot.x, sun_rot.y, sun_rot.z, sun_rot.w);
-    sun_transform.updateMatrix();
-    dataset.addComponentToEntity(sun_entity, sun_light);
-    dataset.addComponentToEntity(sun_entity, sun_transform);
-
-    const fill_entity = dataset.createEntity();
-    const fill_light = new Light();
-    fill_light.type.set(Light.Type.DIRECTION);
-    fill_light.color.setRGB(0.55, 0.72, 0.95);
-    fill_light.intensity.set(0.65);
-    fill_light.castShadow.set(false);
-
-    const fill_transform = new Transform64();
-    const fill_dir = new Vector3(0.55, -0.55, 0.62).normalize();
-    const fill_rot = new Quaternion().fromUnitVectors(Vector3.forward, fill_dir);
-    fill_transform.setRotation(fill_rot.x, fill_rot.y, fill_rot.z, fill_rot.w);
-    fill_transform.updateMatrix();
-    dataset.addComponentToEntity(fill_entity, fill_light);
-    dataset.addComponentToEntity(fill_entity, fill_transform);
-
-    // --- 2. ECS Meadow Ground Entity ---
-    const ground_entity = dataset.createEntity();
-    const ground_material = new StandardShadeMaterial();
-    ground_material.diffuse_color.setRGB(0.22, 0.32, 0.15);
-    ground_material.roughness_factor = 0.92;
-    ground_material.metallic_factor = 0.0;
-    ground_material.ambient_factors.a = 1.0;
-    ground_material.ambient_factors.b = 0.0;
-    const ground_geometry = build_meadow_ground_geometry(36, 20);
-    const ground_shaded = ShadedGeometry.from(ground_geometry, ground_material, DrawMode.Triangles);
-    const ground_transform = new Transform64();
-    ground_transform.updateMatrix();
-    dataset.addComponentToEntity(ground_entity, ground_shaded);
-    dataset.addComponentToEntity(ground_entity, ground_transform);
-
-    // --- 3. ECS Fluid Wind & Cascade Simulation Entities ---
-    const fluid_entity = dataset.createEntity();
-    const fluid_transform = new Transform64();
-    fluid_transform.setTranslation(0, 6, 0);
-    fluid_transform.updateMatrix();
-
-    const fluid_component = new GPUFluidComponent();
-    fluid_component.resolution = [64, 32, 64];
-    fluid_component.cascade_count = 3;
-    fluid_component.cell_size = 0.5;
-    fluid_component.vorticity_confinement = 1.5;
-
-    const global_wind = new GlobalFluidEffector();
-    global_wind.wind = [6.5, 0, 2.5];
-    global_wind.drag = 1.5;
-    global_wind.gust = 0.5;
-    global_wind.gust_period = 5.5;
-
-    const fluid_effectors = new FluidEffectorsComponent();
-    fluid_effectors.addEffector(global_wind);
-    dataset.addComponentToEntity(fluid_entity, fluid_component);
-    dataset.addComponentToEntity(fluid_entity, fluid_effectors);
-    dataset.addComponentToEntity(fluid_entity, fluid_transform);
-
-    // Local travelling gust + vortex effector entity
-    const gust_entity = dataset.createEntity();
-    const gust_transform = new Transform64();
-    gust_transform.setTranslation(-20, 4, 0);
-    gust_transform.updateMatrix();
-
-    const impulse_effector = new ImpulseFluidEffector();
-    impulse_effector.radius = 0; // Inactive until triggered
-    impulse_effector.spread = 0.35;
-    impulse_effector.force = [0, 0, 0];
-
-    const vortex_effector = new VortexFluidEffector();
-    vortex_effector.radius = 0; // Inactive until triggered
-    vortex_effector.length = 8;
-    vortex_effector.strength = 0;
-
-    const local_effectors = new FluidEffectorsComponent();
-    local_effectors.addEffector(impulse_effector);
-    local_effectors.addEffector(vortex_effector);
-    dataset.addComponentToEntity(gust_entity, local_effectors);
-    dataset.addComponentToEntity(gust_entity, gust_transform);
-
-    // --- 4. Tree Management & Wind State ---
-    const state = {
-        mode: initial_options.mode ?? "specimen",
-        preset: initial_options.preset ?? TreePreset.Oak,
-        seed: initial_options.seed ?? 1337,
-        lod: initial_options.lod ?? 0,
-        showLeaves: initial_options.showLeaves ?? true,
-        windSpeed: initial_options.windSpeed ?? 6.5,
-        headingDeg: initial_options.headingDeg ?? 25,
-        gustStrength: initial_options.gustStrength ?? 4.5,
-        gustPeriod: initial_options.gustPeriod ?? 5.5,
-        windWeight: initial_options.windWeight ?? 1.0,
-    };
-
-    /**
-     * Cache of generated `TreeAsset`s keyed by `${preset}:${seed}:${showLeaves ? 1 : 0}` so switching LODs, modes, or leaves visibility is instant.
-     * @type {Map<string, import("../../../generation/foliage/asset/TreeAsset.js").TreeAsset>}
-     */
-    const asset_cache = new Map();
-
-    /**
-     * Active spawned tree instances in `dataset`.
-     * @type {Array<{root: number, instance: import("../../../engine/graphics3/prefab/PrefabInstance.js").PrefabInstance, lod_asset: import("../../../generation/foliage/asset/TreeLODAsset.js").TreeLODAsset, preset: string}>}
-     */
-    const active_trees = [];
-
-    /**
-     * Active local gust wave state.
-     */
-    const active_gust = {
-        remaining: 0,
-        duration: 2.4,
-        dir_x: 1,
-        dir_z: 0,
-        speed: 14,
-        strength: 28,
-        vortex_strength: 12,
-        radius: 6.5,
-    };
-
-    function obtainTreeAsset(preset, seed, show_leaves = state.showLeaves) {
-        const leaves_flag = Boolean(show_leaves);
-        const key = `${preset}:${seed | 0}:${leaves_flag ? 1 : 0}`;
-        let asset = asset_cache.get(key);
-        if (!asset) {
-            asset = generate_tree({
-                preset,
-                seed: seed | 0,
-                foliage: leaves_flag,
-            });
-            asset_cache.set(key, asset);
-        }
-        return asset;
-    }
-
-    function clearTrees() {
-        for (let i = active_trees.length - 1; i >= 0; i--) {
-            const entry = active_trees[i];
-            prefab_instance_destroy(dataset, entry.instance);
-            if (dataset.entityExists(entry.root)) {
-                dataset.removeEntity(entry.root);
-            }
-        }
-        active_trees.length = 0;
-    }
-
-    function spawnTreeInstance(preset, seed, lod, x, y, z, yaw_rad, uniform_scale) {
-        const tree_asset = obtainTreeAsset(preset, seed, state.showLeaves);
-        const clamped_lod = Math.max(0, Math.min(tree_asset.lods.length - 1, lod | 0));
-        const lod_asset = tree_asset.lods[clamped_lod];
-
-        const root = dataset.createEntity();
-        const placement = new Transform64();
-        placement.setTranslation(x, y, z);
-        const half_yaw = yaw_rad * 0.5;
-        placement.setRotation(0, Math.sin(half_yaw), 0, Math.cos(half_yaw));
-        placement.setScale(uniform_scale, uniform_scale, uniform_scale);
-        placement.updateMatrix();
-        dataset.addComponentToEntity(root, placement);
-
-        const instance = prefab_instantiate(lod_asset.prefab, dataset, root);
-
-        const rigs_comp = dataset.getComponent(root, FoliageWindRigs);
-        if (rigs_comp !== undefined) {
-            rigs_comp.weight = state.windWeight;
-        }
-
-        active_trees.push({
-            root,
-            instance,
-            lod_asset,
-            preset,
-        });
-    }
-
-    /**
-     * Rebuilds the spawned ECS tree entities for the current or updated configuration.
-     *
-     * @param {Partial<typeof state>} [overrides]
-     */
-    function rebuildTrees(overrides = {}) {
-        if (overrides.mode !== undefined) state.mode = overrides.mode;
-        if (overrides.preset !== undefined) state.preset = overrides.preset;
-        if (overrides.seed !== undefined) state.seed = overrides.seed | 0;
-        if (overrides.lod !== undefined) state.lod = overrides.lod | 0;
-        if (overrides.showLeaves !== undefined) state.showLeaves = Boolean(overrides.showLeaves);
-        if (overrides.windWeight !== undefined) state.windWeight = overrides.windWeight;
-
-        clearTrees();
-
-        if (state.mode === "grove") {
-            // Hero specimen in the center
-            spawnTreeInstance(state.preset, state.seed, state.lod, 0, 0, 0, 0, 1.0);
-
-            // Ring of botanical companions around the meadow
-            const grove_species = [
-                TreePreset.Oak,
-                TreePreset.Pine,
-                TreePreset.Birch,
-                TreePreset.Willow,
-                TreePreset.Maple,
-                TreePreset.Spruce,
-                TreePreset.Palm,
-                TreePreset.Shrub,
-            ];
-            const rng = seededRandom((state.seed ^ 0x5A17C9) | 0);
-            const ring_count = grove_species.length;
-
-            for (let i = 0; i < ring_count; i++) {
-                const angle = (i / ring_count) * PI2 + (rng() - 0.5) * 0.25;
-                const radius = 9.5 + rng() * 5.0;
-                const x = Math.cos(angle) * radius;
-                const z = Math.sin(angle) * radius;
-                const yaw = rng() * PI2;
-                const scale = 0.85 + rng() * 0.3;
-                const species = grove_species[i];
-                const tree_seed = (state.seed + (i + 1) * 97) | 0;
-
-                spawnTreeInstance(species, tree_seed, state.lod, x, 0, z, yaw, scale);
-            }
-        } else {
-            // Single hero specimen at the origin
-            spawnTreeInstance(state.preset, state.seed, state.lod, 0, 0, 0, 0, 1.0);
-        }
-    }
-
-    /**
-     * Updates the ECS `GlobalFluidEffector` wind parameters and tree `FoliageWindRigs` blend weights.
-     *
-     * @param {Partial<typeof state>} [overrides]
-     */
-    function setWind(overrides = {}) {
-        if (overrides.windSpeed !== undefined) state.windSpeed = overrides.windSpeed;
-        if (overrides.headingDeg !== undefined) state.headingDeg = overrides.headingDeg;
-        if (overrides.gustStrength !== undefined) state.gustStrength = overrides.gustStrength;
-        if (overrides.gustPeriod !== undefined) state.gustPeriod = overrides.gustPeriod;
-        if (overrides.windWeight !== undefined) state.windWeight = overrides.windWeight;
-
-        const heading_rad = state.headingDeg * DEG_TO_RAD;
-        const dir_x = Math.cos(heading_rad);
-        const dir_z = Math.sin(heading_rad);
-
-        const eff_speed = state.windSpeed > 0.05
-            ? state.windSpeed
-            : (state.gustStrength > 0 ? 0.05 : 0);
-
-        global_wind.wind[0] = dir_x * eff_speed;
-        global_wind.wind[1] = 0.0;
-        global_wind.wind[2] = dir_z * eff_speed;
-        global_wind.drag = 1.5;
-        global_wind.gust = eff_speed > 0 ? state.gustStrength / eff_speed : 0;
-        global_wind.gust_period = Math.max(0.5, state.gustPeriod);
-
-        for (let i = 0; i < active_trees.length; i++) {
-            const rigs_comp = dataset.getComponent(active_trees[i].root, FoliageWindRigs);
-            if (rigs_comp !== undefined) {
-                rigs_comp.weight = state.windWeight;
-            }
-        }
-    }
-
-    /**
-     * Launches a localized 3D wind gust + vortex swirl across the grove through the ECS
-     * `ImpulseFluidEffector` and `VortexFluidEffector` entities.
-     *
-     * @param {object} [options]
-     * @param {number} [options.strength=32]
-     * @param {number} [options.vortexStrength=14]
-     * @param {number} [options.radius=7.5]
-     * @param {number} [options.duration=2.2]
-     */
-    function triggerLocalGust({
-        strength = 32,
-        vortexStrength = 14,
-        radius = 7.5,
-        duration = 2.2,
-    } = {}) {
-        const heading_rad = state.headingDeg * DEG_TO_RAD;
-        const dir_x = Math.cos(heading_rad);
-        const dir_z = Math.sin(heading_rad);
-
-        active_gust.remaining = duration;
-        active_gust.duration = duration;
-        active_gust.dir_x = dir_x;
-        active_gust.dir_z = dir_z;
-        active_gust.strength = strength;
-        active_gust.vortex_strength = vortexStrength;
-        active_gust.radius = radius;
-
-        // Start upstream of the grove and sweep across the center
-        const start_dist = -14;
-        gust_transform.setTranslation(dir_x * start_dist, 3.5, dir_z * start_dist);
-        gust_transform.updateMatrix();
-        t64_announce_change(dataset, gust_entity);
-
-        impulse_effector.radius = radius;
-        impulse_effector.force[0] = dir_x * strength;
-        impulse_effector.force[1] = 2.5;
-        impulse_effector.force[2] = dir_z * strength;
-
-        vortex_effector.radius = radius * 0.85;
-        vortex_effector.strength = vortexStrength;
-    }
-
-    /**
-     * Advances the ECS world by `dt` seconds.
-     *
-     * @param {number} dt
-     */
-    function step(dt) {
-        const clamped_dt = Math.min(Math.max(dt, 0), 0.1);
-
-        if (active_gust.remaining > 0) {
-            active_gust.remaining = Math.max(0, active_gust.remaining - clamped_dt);
-            const progress = 1.0 - active_gust.remaining / active_gust.duration;
-            const envelope = Math.sin(progress * Math.PI);
-            const dist = -14 + progress * 28;
-
-            gust_transform.setTranslation(
-                active_gust.dir_x * dist,
-                3.5,
-                active_gust.dir_z * dist
-            );
-            gust_transform.updateMatrix();
-            t64_announce_change(dataset, gust_entity);
-
-            impulse_effector.radius = active_gust.radius;
-            impulse_effector.force[0] = active_gust.dir_x * active_gust.strength * envelope;
-            impulse_effector.force[1] = 2.0 * envelope;
-            impulse_effector.force[2] = active_gust.dir_z * active_gust.strength * envelope;
-
-            vortex_effector.radius = active_gust.radius * 0.85;
-            vortex_effector.strength = active_gust.vortex_strength * envelope;
-
-            if (active_gust.remaining === 0) {
-                impulse_effector.radius = 0;
-                impulse_effector.force[0] = 0;
-                impulse_effector.force[1] = 0;
-                impulse_effector.force[2] = 0;
-                vortex_effector.radius = 0;
-                vortex_effector.strength = 0;
-            }
-        }
-
-        entities.update(clamped_dt);
-    }
-
-    /**
-     * Returns live statistics for the HUD and tests.
-     */
-    function getStats() {
-        let total_joints = 0;
-        let total_vertices = 0;
-        let total_triangles = 0;
-
-        for (let i = 0; i < active_trees.length; i++) {
-            const lod_asset = active_trees[i].lod_asset;
-            total_joints += lod_asset.joint_count;
-            total_vertices += lod_asset.vertex_count;
-            total_triangles += lod_asset.triangle_count;
-        }
-
-        const context = graphics.scene_context(scene);
-        const active_rig_count = context
-            ? context.animation_manager.database.get('animation_foliage_rigs').occupancy.cardinality()
-            : 0;
-
-        return {
-            mode: state.mode,
-            preset: state.preset,
-            seed: state.seed,
-            lod: state.lod,
-            showLeaves: state.showLeaves,
-            treeCount: active_trees.length,
-            totalJoints: total_joints,
-            totalVertices: total_vertices,
-            totalTriangles: total_triangles,
-            activeRigCount: active_rig_count,
-            windSpeed: state.windSpeed,
-            gustStrength: state.gustStrength,
-            windWeight: state.windWeight,
-            gustActive: active_gust.remaining > 0,
-        };
-    }
-
-    async function destroy() {
-        clearTrees();
-        await new Promise((resolve, reject) => entities.shutdown(resolve, reject));
-    }
-
-    // Initialize wind and spawn initial tree(s)
-    setWind();
-    rebuildTrees();
-
-    return {
-        entities,
-        dataset,
-        state,
-        activeTrees: active_trees,
-        fluidEntity: fluid_entity,
-        gustEntity: gust_entity,
-        globalWind: global_wind,
-        impulseEffector: impulse_effector,
-        vortexEffector: vortex_effector,
-        rebuildTrees,
-        setWind,
-        triggerLocalGust,
-        step,
-        getStats,
-        destroy,
-    };
-}
+import { assert } from "../../../core/assert.js";
+import { Quaternion } from "../../../core/geom/Quaternion.js";
+import { Vector3 } from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { PI2 } from "../../../core/math/PI2.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { EntityManager } from "../../../engine/ecs/EntityManager.js";
+import { ParentEntitySystem } from "../../../engine/ecs/parent/ParentEntitySystem.js";
+import { TransformAttachmentSystem } from "../../../engine/ecs/transform-attachment/TransformAttachmentSystem.js";
+import { t64_announce_change } from "../../../engine/ecs/transform/t64_announce_change.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Light } from "../../../engine/graphics/ecs/light/Light.js";
+import { DrawMode } from "../../../engine/graphics/ecs/mesh-v2/DrawMode.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { FoliageWindRigs } from "../../../engine/graphics3/animation/FoliageWindRigs.js";
+import { FoliageWindSystem } from "../../../engine/graphics3/FoliageWindSystem.js";
+import { GPUFluidSystem } from "../../../engine/graphics3/GPUFluidSystem.js";
+import { LightSystem } from "../../../engine/graphics3/LightSystem.js";
+import { MeshSkinSystem } from "../../../engine/graphics3/MeshSkinSystem.js";
+import { prefab_instance_destroy, prefab_instantiate } from "../../../engine/graphics3/prefab/prefab_instantiate.js";
+import { ShadedGeometrySystem } from "../../../engine/graphics3/ShadedGeometrySystem.js";
+import { FluidEffectorsComponent } from "../../../engine/physics/fluid/ecs/FluidEffectorsComponent.js";
+import { FluidEffectorsSystem } from "../../../engine/physics/fluid/ecs/FluidEffectorsSystem.js";
+import { GPUFluidComponent } from "../../../engine/physics/fluid/ecs/GPUFluidComponent.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";
+import { TreePreset } from "../../../generation/foliage/config/TreePreset.js";
+import { generate_tree } from "../../../generation/foliage/asset/generate_tree.js";
+import { Attribute } from "../../renderer/geometry/Attribute.js";
+import { Geometry } from "../../renderer/geometry/Geometry.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+
+/**
+ * Ordered list of all species presets available in the playground.
+ * @type {string[]}
+ */
+export const FOLIAGE_PLAYGROUND_PRESETS = [
+    TreePreset.Oak,
+    TreePreset.Pine,
+    TreePreset.Birch,
+    TreePreset.Willow,
+    TreePreset.Maple,
+    TreePreset.Spruce,
+    TreePreset.Palm,
+    TreePreset.Shrub,
+    TreePreset.Fern,
+];
+
+/**
+ * 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 = 32, subdivisions = 24) {
+    const stride = subdivisions + 1;
+    const vertex_count = stride * stride;
+    const quad_count = subdivisions * subdivisions;
+
+    const positions = new Float32Array(vertex_count * 3);
+    const normals = new Float32Array(vertex_count * 3);
+    const uvs = new Float32Array(vertex_count * 2);
+    const indices = new Uint32Array(quad_count * 6);
+
+    let v = 0;
+    for (let iz = 0; iz <= subdivisions; iz++) {
+        const tz = iz / subdivisions;
+        const z = (tz * 2 - 1) * half_extent;
+        for (let ix = 0; ix <= subdivisions; ix++) {
+            const tx = ix / subdivisions;
+            const x = (tx * 2 - 1) * half_extent;
+
+            positions[v * 3] = x;
+            positions[v * 3 + 1] = 0;
+            positions[v * 3 + 2] = z;
+
+            normals[v * 3] = 0;
+            normals[v * 3 + 1] = 1;
+            normals[v * 3 + 2] = 0;
+
+            uvs[v * 2] = tx * 8;
+            uvs[v * 2 + 1] = tz * 8;
+            v++;
+        }
+    }
+
+    let idx = 0;
+    for (let iz = 0; iz < subdivisions; iz++) {
+        for (let ix = 0; ix < subdivisions; ix++) {
+            const i00 = iz * stride + ix;
+            const i10 = i00 + 1;
+            const i01 = (iz + 1) * stride + ix;
+            const i11 = i01 + 1;
+
+            indices[idx++] = i00;
+            indices[idx++] = i01;
+            indices[idx++] = i10;
+
+            indices[idx++] = i10;
+            indices[idx++] = i01;
+            indices[idx++] = i11;
+        }
+    }
+
+    const geometry = new Geometry();
+    geometry.index = Attribute.from(indices, 1, "index");
+    geometry.addAttribute(Attribute.from(positions, 3, "position"));
+    geometry.addAttribute(Attribute.from(normals, 3, "normal"));
+    geometry.addAttribute(Attribute.from(uvs, 2, "uv"));
+    geometry.ensureTangents();
+
+    return meshlet_geometry_build_from_geometry(geometry);
+}
+
+/**
+ * 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 async function createFoliageWindWorld(graphics, scene, initial_options = {}) {
+    assert.defined(graphics, 'graphics');
+    assert.defined(scene, 'scene');
+
+    await MeshoptClusterizer.ready;
+
+    const enable_gpu_fluid = initial_options.enableGPUFluid !== false;
+
+    const entities = new EntityManager();
+    entities.fixedUpdateStepSize = 1 / 60;
+
+    const dataset = new EntityComponentDataset();
+    dataset.registerComponentType(GPUFluidComponent);
+
+    entities.addSystem(new ParentEntitySystem());
+    entities.addSystem(new TransformAttachmentSystem());
+    entities.addSystem(new ShadedGeometrySystem(graphics, scene));
+    entities.addSystem(new MeshSkinSystem(graphics, scene));
+    entities.addSystem(new FoliageWindSystem(graphics, scene));
+    entities.addSystem(new LightSystem(graphics, scene));
+    entities.addSystem(new FluidEffectorsSystem());
+
+    if (enable_gpu_fluid && typeof graphics.add_extension === "function") {
+        entities.addSystem(new GPUFluidSystem(graphics, scene));
+    }
+
+    entities.attachDataset(dataset);
+
+    await new Promise((resolve, reject) => entities.startup(resolve, reject));
+
+    // --- 1. ECS Lighting Entities ---
+    const sun_entity = dataset.createEntity();
+    const sun_light = new Light();
+    sun_light.type.set(Light.Type.DIRECTION);
+    sun_light.color.setRGB(1.0, 0.96, 0.88);
+    sun_light.intensity.set(2.2);
+    sun_light.radius.set(0.006475);
+    sun_light.castShadow.set(true);
+    sun_light.maxShadowDistance.set(60);
+
+    const sun_transform = new Transform64();
+    const sun_dir = new Vector3(-0.48, -0.78, -0.40).normalize();
+    const sun_rot = new Quaternion().fromUnitVectors(Vector3.forward, sun_dir);
+    sun_transform.setRotation(sun_rot.x, sun_rot.y, sun_rot.z, sun_rot.w);
+    sun_transform.updateMatrix();
+    dataset.addComponentToEntity(sun_entity, sun_light);
+    dataset.addComponentToEntity(sun_entity, sun_transform);
+
+    const fill_entity = dataset.createEntity();
+    const fill_light = new Light();
+    fill_light.type.set(Light.Type.DIRECTION);
+    fill_light.color.setRGB(0.55, 0.72, 0.95);
+    fill_light.intensity.set(0.65);
+    fill_light.castShadow.set(false);
+
+    const fill_transform = new Transform64();
+    const fill_dir = new Vector3(0.55, -0.55, 0.62).normalize();
+    const fill_rot = new Quaternion().fromUnitVectors(Vector3.forward, fill_dir);
+    fill_transform.setRotation(fill_rot.x, fill_rot.y, fill_rot.z, fill_rot.w);
+    fill_transform.updateMatrix();
+    dataset.addComponentToEntity(fill_entity, fill_light);
+    dataset.addComponentToEntity(fill_entity, fill_transform);
+
+    // --- 2. ECS Meadow Ground Entity ---
+    const ground_entity = dataset.createEntity();
+    const ground_material = new StandardShadeMaterial();
+    ground_material.diffuse_color.setRGB(0.22, 0.32, 0.15);
+    ground_material.roughness_factor = 0.92;
+    ground_material.metallic_factor = 0.0;
+    ground_material.ambient_factors.a = 1.0;
+    ground_material.ambient_factors.b = 0.0;
+    const ground_geometry = build_meadow_ground_geometry(36, 20);
+    const ground_shaded = ShadedGeometry.from(ground_geometry, ground_material, DrawMode.Triangles);
+    const ground_transform = new Transform64();
+    ground_transform.updateMatrix();
+    dataset.addComponentToEntity(ground_entity, ground_shaded);
+    dataset.addComponentToEntity(ground_entity, ground_transform);
+
+    // --- 3. ECS Fluid Wind & Cascade Simulation Entities ---
+    const fluid_entity = dataset.createEntity();
+    const fluid_transform = new Transform64();
+    fluid_transform.setTranslation(0, 6, 0);
+    fluid_transform.updateMatrix();
+
+    const fluid_component = new GPUFluidComponent();
+    fluid_component.resolution = [64, 32, 64];
+    fluid_component.cascade_count = 3;
+    fluid_component.cell_size = 0.5;
+    fluid_component.vorticity_confinement = 1.5;
+
+    const global_wind = new GlobalFluidEffector();
+    global_wind.wind = [6.5, 0, 2.5];
+    global_wind.drag = 1.5;
+    global_wind.gust = 0.5;
+    global_wind.gust_period = 5.5;
+
+    const fluid_effectors = new FluidEffectorsComponent();
+    fluid_effectors.addEffector(global_wind);
+    dataset.addComponentToEntity(fluid_entity, fluid_component);
+    dataset.addComponentToEntity(fluid_entity, fluid_effectors);
+    dataset.addComponentToEntity(fluid_entity, fluid_transform);
+
+    // Local travelling gust + vortex effector entity
+    const gust_entity = dataset.createEntity();
+    const gust_transform = new Transform64();
+    gust_transform.setTranslation(-20, 4, 0);
+    gust_transform.updateMatrix();
+
+    const impulse_effector = new ImpulseFluidEffector();
+    impulse_effector.radius = 0; // Inactive until triggered
+    impulse_effector.spread = 0.35;
+    impulse_effector.force = [0, 0, 0];
+
+    const vortex_effector = new VortexFluidEffector();
+    vortex_effector.radius = 0; // Inactive until triggered
+    vortex_effector.length = 8;
+    vortex_effector.strength = 0;
+
+    const local_effectors = new FluidEffectorsComponent();
+    local_effectors.addEffector(impulse_effector);
+    local_effectors.addEffector(vortex_effector);
+    dataset.addComponentToEntity(gust_entity, local_effectors);
+    dataset.addComponentToEntity(gust_entity, gust_transform);
+
+    // --- 4. Tree Management & Wind State ---
+    const state = {
+        mode: initial_options.mode ?? "specimen",
+        preset: initial_options.preset ?? TreePreset.Oak,
+        seed: initial_options.seed ?? 1337,
+        lod: initial_options.lod ?? 0,
+        showLeaves: initial_options.showLeaves ?? true,
+        windSpeed: initial_options.windSpeed ?? 6.5,
+        headingDeg: initial_options.headingDeg ?? 25,
+        gustStrength: initial_options.gustStrength ?? 4.5,
+        gustPeriod: initial_options.gustPeriod ?? 5.5,
+        windWeight: initial_options.windWeight ?? 1.0,
+    };
+
+    /**
+     * Cache of generated `TreeAsset`s keyed by `${preset}:${seed}:${showLeaves ? 1 : 0}` so switching LODs, modes, or leaves visibility is instant.
+     * @type {Map<string, import("../../../generation/foliage/asset/TreeAsset.js").TreeAsset>}
+     */
+    const asset_cache = new Map();
+
+    /**
+     * Active spawned tree instances in `dataset`.
+     * @type {Array<{root: number, instance: import("../../../engine/graphics3/prefab/PrefabInstance.js").PrefabInstance, lod_asset: import("../../../generation/foliage/asset/TreeLODAsset.js").TreeLODAsset, preset: string}>}
+     */
+    const active_trees = [];
+
+    /**
+     * Active local gust wave state.
+     */
+    const active_gust = {
+        remaining: 0,
+        duration: 2.4,
+        dir_x: 1,
+        dir_z: 0,
+        speed: 14,
+        strength: 28,
+        vortex_strength: 12,
+        radius: 6.5,
+    };
+
+    function obtainTreeAsset(preset, seed, show_leaves = state.showLeaves) {
+        const leaves_flag = Boolean(show_leaves);
+        const key = `${preset}:${seed | 0}:${leaves_flag ? 1 : 0}`;
+        let asset = asset_cache.get(key);
+        if (!asset) {
+            asset = leaves_flag
+                ? generate_tree({ preset, seed: seed | 0 })
+                : generate_tree({ preset, seed: seed | 0, foliage_rules: [] });
+            asset_cache.set(key, asset);
+        }
+        return asset;
+    }
+
+    function clearTrees() {
+        for (let i = active_trees.length - 1; i >= 0; i--) {
+            const entry = active_trees[i];
+            prefab_instance_destroy(dataset, entry.instance);
+            if (dataset.entityExists(entry.root)) {
+                dataset.removeEntity(entry.root);
+            }
+        }
+        active_trees.length = 0;
+    }
+
+    function spawnTreeInstance(preset, seed, lod, x, y, z, yaw_rad, uniform_scale) {
+        const tree_asset = obtainTreeAsset(preset, seed, state.showLeaves);
+        const clamped_lod = Math.max(0, Math.min(tree_asset.lods.length - 1, lod | 0));
+        const lod_asset = tree_asset.lods[clamped_lod];
+
+        const root = dataset.createEntity();
+        const placement = new Transform64();
+        placement.setTranslation(x, y, z);
+        const half_yaw = yaw_rad * 0.5;
+        placement.setRotation(0, Math.sin(half_yaw), 0, Math.cos(half_yaw));
+        placement.setScale(uniform_scale, uniform_scale, uniform_scale);
+        placement.updateMatrix();
+        dataset.addComponentToEntity(root, placement);
+
+        const instance = prefab_instantiate(lod_asset.prefab, dataset, root);
+
+        const rigs_comp = dataset.getComponent(root, FoliageWindRigs);
+        if (rigs_comp !== undefined) {
+            rigs_comp.weight = state.windWeight;
+        }
+
+        active_trees.push({
+            root,
+            instance,
+            lod_asset,
+            preset,
+        });
+    }
+
+    /**
+     * Rebuilds the spawned ECS tree entities for the current or updated configuration.
+     *
+     * @param {Partial<typeof state>} [overrides]
+     */
+    function rebuildTrees(overrides = {}) {
+        if (overrides.mode !== undefined) state.mode = overrides.mode;
+        if (overrides.preset !== undefined) state.preset = overrides.preset;
+        if (overrides.seed !== undefined) state.seed = overrides.seed | 0;
+        if (overrides.lod !== undefined) state.lod = overrides.lod | 0;
+        if (overrides.showLeaves !== undefined) state.showLeaves = Boolean(overrides.showLeaves);
+        if (overrides.windWeight !== undefined) state.windWeight = overrides.windWeight;
+
+        clearTrees();
+
+        if (state.mode === "grove") {
+            // Hero specimen in the center
+            spawnTreeInstance(state.preset, state.seed, state.lod, 0, 0, 0, 0, 1.0);
+
+            // Ring of botanical companions around the meadow
+            const grove_species = [
+                TreePreset.Oak,
+                TreePreset.Pine,
+                TreePreset.Birch,
+                TreePreset.Willow,
+                TreePreset.Maple,
+                TreePreset.Spruce,
+                TreePreset.Palm,
+                TreePreset.Shrub,
+            ];
+            const rng = seededRandom((state.seed ^ 0x5A17C9) | 0);
+            const ring_count = grove_species.length;
+
+            for (let i = 0; i < ring_count; i++) {
+                const angle = (i / ring_count) * PI2 + (rng() - 0.5) * 0.25;
+                const radius = 9.5 + rng() * 5.0;
+                const x = Math.cos(angle) * radius;
+                const z = Math.sin(angle) * radius;
+                const yaw = rng() * PI2;
+                const scale = 0.85 + rng() * 0.3;
+                const species = grove_species[i];
+                const tree_seed = (state.seed + (i + 1) * 97) | 0;
+
+                spawnTreeInstance(species, tree_seed, state.lod, x, 0, z, yaw, scale);
+            }
+        } else {
+            // Single hero specimen at the origin
+            spawnTreeInstance(state.preset, state.seed, state.lod, 0, 0, 0, 0, 1.0);
+        }
+    }
+
+    /**
+     * Updates the ECS `GlobalFluidEffector` wind parameters and tree `FoliageWindRigs` blend weights.
+     *
+     * @param {Partial<typeof state>} [overrides]
+     */
+    function setWind(overrides = {}) {
+        if (overrides.windSpeed !== undefined) state.windSpeed = overrides.windSpeed;
+        if (overrides.headingDeg !== undefined) state.headingDeg = overrides.headingDeg;
+        if (overrides.gustStrength !== undefined) state.gustStrength = overrides.gustStrength;
+        if (overrides.gustPeriod !== undefined) state.gustPeriod = overrides.gustPeriod;
+        if (overrides.windWeight !== undefined) state.windWeight = overrides.windWeight;
+
+        const heading_rad = state.headingDeg * DEG_TO_RAD;
+        const dir_x = Math.cos(heading_rad);
+        const dir_z = Math.sin(heading_rad);
+
+        const eff_speed = state.windSpeed > 0.05
+            ? state.windSpeed
+            : (state.gustStrength > 0 ? 0.05 : 0);
+
+        global_wind.wind[0] = dir_x * eff_speed;
+        global_wind.wind[1] = 0.0;
+        global_wind.wind[2] = dir_z * eff_speed;
+        global_wind.drag = 1.5;
+        global_wind.gust = eff_speed > 0 ? state.gustStrength / eff_speed : 0;
+        global_wind.gust_period = Math.max(0.5, state.gustPeriod);
+
+        for (let i = 0; i < active_trees.length; i++) {
+            const rigs_comp = dataset.getComponent(active_trees[i].root, FoliageWindRigs);
+            if (rigs_comp !== undefined) {
+                rigs_comp.weight = state.windWeight;
+            }
+        }
+    }
+
+    /**
+     * Launches a localized 3D wind gust + vortex swirl across the grove through the ECS
+     * `ImpulseFluidEffector` and `VortexFluidEffector` entities.
+     *
+     * @param {object} [options]
+     * @param {number} [options.strength=32]
+     * @param {number} [options.vortexStrength=14]
+     * @param {number} [options.radius=7.5]
+     * @param {number} [options.duration=2.2]
+     */
+    function triggerLocalGust({
+        strength = 32,
+        vortexStrength = 14,
+        radius = 7.5,
+        duration = 2.2,
+    } = {}) {
+        const heading_rad = state.headingDeg * DEG_TO_RAD;
+        const dir_x = Math.cos(heading_rad);
+        const dir_z = Math.sin(heading_rad);
+
+        active_gust.remaining = duration;
+        active_gust.duration = duration;
+        active_gust.dir_x = dir_x;
+        active_gust.dir_z = dir_z;
+        active_gust.strength = strength;
+        active_gust.vortex_strength = vortexStrength;
+        active_gust.radius = radius;
+
+        // Start upstream of the grove and sweep across the center
+        const start_dist = -14;
+        gust_transform.setTranslation(dir_x * start_dist, 3.5, dir_z * start_dist);
+        gust_transform.updateMatrix();
+        t64_announce_change(dataset, gust_entity);
+
+        impulse_effector.radius = radius;
+        impulse_effector.force[0] = dir_x * strength;
+        impulse_effector.force[1] = 2.5;
+        impulse_effector.force[2] = dir_z * strength;
+
+        vortex_effector.radius = radius * 0.85;
+        vortex_effector.strength = vortexStrength;
+    }
+
+    /**
+     * Advances the ECS world by `dt` seconds.
+     *
+     * @param {number} dt
+     */
+    function step(dt) {
+        const clamped_dt = Math.min(Math.max(dt, 0), 0.1);
+
+        if (active_gust.remaining > 0) {
+            active_gust.remaining = Math.max(0, active_gust.remaining - clamped_dt);
+            const progress = 1.0 - active_gust.remaining / active_gust.duration;
+            const envelope = Math.sin(progress * Math.PI);
+            const dist = -14 + progress * 28;
+
+            gust_transform.setTranslation(
+                active_gust.dir_x * dist,
+                3.5,
+                active_gust.dir_z * dist
+            );
+            gust_transform.updateMatrix();
+            t64_announce_change(dataset, gust_entity);
+
+            impulse_effector.radius = active_gust.radius;
+            impulse_effector.force[0] = active_gust.dir_x * active_gust.strength * envelope;
+            impulse_effector.force[1] = 2.0 * envelope;
+            impulse_effector.force[2] = active_gust.dir_z * active_gust.strength * envelope;
+
+            vortex_effector.radius = active_gust.radius * 0.85;
+            vortex_effector.strength = active_gust.vortex_strength * envelope;
+
+            if (active_gust.remaining === 0) {
+                impulse_effector.radius = 0;
+                impulse_effector.force[0] = 0;
+                impulse_effector.force[1] = 0;
+                impulse_effector.force[2] = 0;
+                vortex_effector.radius = 0;
+                vortex_effector.strength = 0;
+            }
+        }
+
+        entities.update(clamped_dt);
+    }
+
+    /**
+     * Returns live statistics for the HUD and tests.
+     */
+    function getStats() {
+        let total_joints = 0;
+        let total_vertices = 0;
+        let total_triangles = 0;
+
+        for (let i = 0; i < active_trees.length; i++) {
+            const lod_asset = active_trees[i].lod_asset;
+            total_joints += lod_asset.joint_count;
+            total_vertices += lod_asset.vertex_count;
+            total_triangles += lod_asset.triangle_count;
+        }
+
+        const context = graphics.scene_context(scene);
+        const active_rig_count = context
+            ? context.animation_manager.database.get('animation_foliage_rigs').occupancy.cardinality()
+            : 0;
+
+        return {
+            mode: state.mode,
+            preset: state.preset,
+            seed: state.seed,
+            lod: state.lod,
+            showLeaves: state.showLeaves,
+            treeCount: active_trees.length,
+            totalJoints: total_joints,
+            totalVertices: total_vertices,
+            totalTriangles: total_triangles,
+            activeRigCount: active_rig_count,
+            windSpeed: state.windSpeed,
+            gustStrength: state.gustStrength,
+            windWeight: state.windWeight,
+            gustActive: active_gust.remaining > 0,
+        };
+    }
+
+    async function destroy() {
+        clearTrees();
+        await new Promise((resolve, reject) => entities.shutdown(resolve, reject));
+    }
+
+    // Initialize wind and spawn initial tree(s)
+    setWind();
+    rebuildTrees();
+
+    return {
+        entities,
+        dataset,
+        state,
+        activeTrees: active_trees,
+        fluidEntity: fluid_entity,
+        gustEntity: gust_entity,
+        globalWind: global_wind,
+        impulseEffector: impulse_effector,
+        vortexEffector: vortex_effector,
+        rebuildTrees,
+        setWind,
+        triggerLocalGust,
+        step,
+        getStats,
+        destroy,
+    };
+}