@woosh/meep-engine 3.52.0 → 3.54.0

package/src/generation/foliage/asset/TreeLODAsset.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Represents one Level-of-Detail (LOD) of a procedurally generated `TreeAsset`.
+ *
+ * Provides immediate synchronous access to `bark_geometry` and `foliage_geometry` (`Geometry`),
+ * and lazy memoized access to `bark_meshlet_geometry`, `foliage_meshlet_geometry` (`MeshletGeometry`),
+ * `scene_bundle` (`SceneBundle`), and `prefab` (`Prefab`).
+ */
+export class TreeLODAsset {
+    /**
+     * LOD index (0 = highest detail).
+     * @type {number}
+     */
+    level: number;
+    /**
+     * Tree species name.
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Configures lazy builders for `bark_geometry` and `foliage_geometry` so coarse LODs are only
+     * triangulated when accessed.
+     *
+     * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry} bark_builder
+     * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} foliage_builder
+     */
+    configure_lazy_geometries(bark_builder: () => import("../../../shade/renderer/geometry/Geometry.js").Geometry, foliage_builder: () => import("../../../shade/renderer/geometry/Geometry.js").Geometry | null): void;
+    /**
+     * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} value
+     */
+    set bark_geometry(value: import("../../../shade/renderer/geometry/Geometry.js").Geometry);
+    /**
+     * Triangulated bark `Geometry`.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry}
+     */
+    get bark_geometry(): import("../../../shade/renderer/geometry/Geometry.js").Geometry;
+    /**
+     * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} value
+     */
+    set foliage_geometry(value: import("../../../shade/renderer/geometry/Geometry.js").Geometry);
+    /**
+     * Triangulated foliage card `Geometry`, or `null` if foliage is disabled / keep_ratio = 0.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    get foliage_geometry(): import("../../../shade/renderer/geometry/Geometry.js").Geometry;
+    /**
+     * Shared procedural bark `StandardShadeMaterial`.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    bark_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * Shared procedural foliage `StandardShadeMaterial`.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    foliage_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * Structural skin joint hierarchy extracted from the `TreeSkeleton`.
+     * @type {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>}
+     */
+    skin_info: ReturnType<typeof import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>;
+    /**
+     * GPU fluid-driven foliage wind rig (`target` indices in `SceneBundle` node space `1..J`), or `null`.
+     * @type {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
+     */
+    wind_rig: import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig | null;
+    /**
+     * Lazily builds and memoizes the bark `MeshletGeometry` + BLAS BVH.
+     * Note: Requires `await MeshoptClusterizer.ready` prior to first access.
+     *
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry}
+     */
+    get bark_meshlet_geometry(): import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry;
+    /**
+     * Lazily builds and memoizes the foliage `MeshletGeometry` + BLAS BVH (or `null` if no foliage).
+     * Note: Requires `await MeshoptClusterizer.ready` prior to first access.
+     *
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    get foliage_meshlet_geometry(): import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry;
+    /**
+     * Lazily constructs and memoizes a zero-defect `SceneBundle` with pre-order joint nodes,
+     * bark + foliage mesh nodes, a shared `Skin`, and the looping wind `ShadeAnimationClip`.
+     *
+     * @returns {SceneBundle}
+     */
+    get scene_bundle(): SceneBundle;
+    /**
+     * Lazily compiles and memoizes the `Prefab` from `this.scene_bundle`.
+     *
+     * @returns {import("../../../engine/graphics3/prefab/Prefab.js").Prefab}
+     */
+    get prefab(): import("../../../engine/graphics3/prefab/Prefab.js").Prefab;
+    /**
+     * Number of skeletal joints in this LOD.
+     * @returns {number}
+     */
+    get joint_count(): number;
+    /**
+     * Total vertex count across bark and foliage geometries for this LOD.
+     * @returns {number}
+     */
+    get vertex_count(): number;
+    /**
+     * Total triangle count across bark and foliage geometries for this LOD.
+     * @returns {number}
+     */
+    get triangle_count(): number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isTreeLODAsset: boolean;
+    #private;
+}
+import { SceneBundle } from "../../../shade/renderer/loader/SceneBundle.js";
+//# sourceMappingURL=TreeLODAsset.d.ts.map

package/src/generation/foliage/asset/TreeLODAsset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeLODAsset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/TreeLODAsset.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,MAFU,MAAM,CAEF;IA2Bd;;;;;;OAMG;IACH,wCAHW,MAAM,OAAO,8CAA8C,EAAE,QAAQ,mBACrE,MAAM,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI,QAQpF;IAcD;;OAEG;IACH,0FAGC;IAlBD;;;OAGG;IACH,qFAMC;IAuBD;;OAEG;IACH,6FAIC;IApBD;;;OAGG;IACH,wFAOC;IAWD;;;OAGG;IACH,eAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE9E;IAErB;;;OAGG;IACH,kBAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE3E;IAExB;;;OAGG;IACH,WAFU,6GAAsG,CAE/F;IAEjB;;;OAGG;IACH,UAFU,OAAO,6DAA6D,EAAE,cAAc,GAAC,IAAI,CAEnF;IA2BhB;;;;;OAKG;IACH,2GAKC;IAED;;;;;OAKG;IACH,8GAUC;IAED;;;;;OAKG;IACH,gCAwGC;IAED;;;;OAIG;IACH,0EAKC;IAED;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,2BAIC;IAED;;;OAGG;IACH,6BAIC;IAGL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;;CANpC;4BAhV2B,+CAA+C"}

package/src/generation/foliage/asset/TreeLODAsset.js

@@ -0,0 +1,346 @@
+import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
+import { Skin } from "../../../shade/renderer/animation/Skin.js";
+import { meshlet_geometry_build_from_geometry } from "../../../shade/renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { SceneBundle } from "../../../shade/renderer/loader/SceneBundle.js";
+import { SceneNode } from "../../../shade/renderer/loader/SceneNode.js";
+
+/**
+ * Represents one Level-of-Detail (LOD) of a procedurally generated `TreeAsset`.
+ *
+ * Provides immediate synchronous access to `bark_geometry` and `foliage_geometry` (`Geometry`),
+ * and lazy memoized access to `bark_meshlet_geometry`, `foliage_meshlet_geometry` (`MeshletGeometry`),
+ * `scene_bundle` (`SceneBundle`), and `prefab` (`Prefab`).
+ */
+export class TreeLODAsset {
+    /**
+     * LOD index (0 = highest detail).
+     * @type {number}
+     */
+    level = 0;
+
+    /**
+     * Tree species name.
+     * @type {string}
+     */
+    name = "tree";
+
+    /**
+     * @type {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    #bark_geometry = null;
+
+    /**
+     * @type {(() => import("../../../shade/renderer/geometry/Geometry.js").Geometry)|null}
+     */
+    #bark_geometry_builder = null;
+
+    /**
+     * @type {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    #foliage_geometry = null;
+
+    /**
+     * @type {(() => import("../../../shade/renderer/geometry/Geometry.js").Geometry|null)|null}
+     */
+    #foliage_geometry_builder = null;
+
+    /**
+     * @type {boolean}
+     */
+    #foliage_geometry_built = false;
+
+    /**
+     * Configures lazy builders for `bark_geometry` and `foliage_geometry` so coarse LODs are only
+     * triangulated when accessed.
+     *
+     * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry} bark_builder
+     * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} foliage_builder
+     */
+    configure_lazy_geometries(bark_builder, foliage_builder) {
+        this.#bark_geometry_builder = bark_builder;
+        this.#foliage_geometry_builder = foliage_builder;
+        this.#bark_geometry = null;
+        this.#foliage_geometry = null;
+        this.#foliage_geometry_built = false;
+    }
+
+    /**
+     * Triangulated bark `Geometry`.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry}
+     */
+    get bark_geometry() {
+        if (this.#bark_geometry === null && this.#bark_geometry_builder !== null) {
+            this.#bark_geometry = this.#bark_geometry_builder();
+            this.#bark_geometry_builder = null;
+        }
+        return this.#bark_geometry;
+    }
+
+    /**
+     * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} value
+     */
+    set bark_geometry(value) {
+        this.#bark_geometry = value;
+        this.#bark_geometry_builder = null;
+    }
+
+    /**
+     * Triangulated foliage card `Geometry`, or `null` if foliage is disabled / keep_ratio = 0.
+     * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
+     */
+    get foliage_geometry() {
+        if (!this.#foliage_geometry_built && this.#foliage_geometry_builder !== null) {
+            this.#foliage_geometry_built = true;
+            this.#foliage_geometry = this.#foliage_geometry_builder();
+            this.#foliage_geometry_builder = null;
+        }
+        return this.#foliage_geometry;
+    }
+
+    /**
+     * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} value
+     */
+    set foliage_geometry(value) {
+        this.#foliage_geometry = value;
+        this.#foliage_geometry_built = true;
+        this.#foliage_geometry_builder = null;
+    }
+
+    /**
+     * Shared procedural bark `StandardShadeMaterial`.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    bark_material = null;
+
+    /**
+     * Shared procedural foliage `StandardShadeMaterial`.
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    foliage_material = null;
+
+    /**
+     * Structural skin joint hierarchy extracted from the `TreeSkeleton`.
+     * @type {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>}
+     */
+    skin_info = null;
+
+    /**
+     * GPU fluid-driven foliage wind rig (`target` indices in `SceneBundle` node space `1..J`), or `null`.
+     * @type {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
+     */
+    wind_rig = null;
+
+    /**
+     * @type {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    #bark_meshlet_geometry = null;
+
+    /**
+     * @type {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    #foliage_meshlet_geometry = null;
+
+    /**
+     * @type {boolean}
+     */
+    #foliage_meshlet_built = false;
+
+    /**
+     * @type {SceneBundle|null}
+     */
+    #scene_bundle = null;
+
+    /**
+     * @type {import("../../../engine/graphics3/prefab/Prefab.js").Prefab|null}
+     */
+    #prefab = null;
+
+    /**
+     * Lazily builds and memoizes the bark `MeshletGeometry` + BLAS BVH.
+     * Note: Requires `await MeshoptClusterizer.ready` prior to first access.
+     *
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry}
+     */
+    get bark_meshlet_geometry() {
+        if (this.#bark_meshlet_geometry === null && this.bark_geometry !== null) {
+            this.#bark_meshlet_geometry = meshlet_geometry_build_from_geometry(this.bark_geometry);
+        }
+        return this.#bark_meshlet_geometry;
+    }
+
+    /**
+     * Lazily builds and memoizes the foliage `MeshletGeometry` + BLAS BVH (or `null` if no foliage).
+     * Note: Requires `await MeshoptClusterizer.ready` prior to first access.
+     *
+     * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
+     */
+    get foliage_meshlet_geometry() {
+        if (!this.#foliage_meshlet_built) {
+            this.#foliage_meshlet_built = true;
+            if (this.foliage_geometry !== null && this.foliage_geometry.getPrimitiveCount() > 0) {
+                this.#foliage_meshlet_geometry = meshlet_geometry_build_from_geometry(this.foliage_geometry);
+            } else {
+                this.#foliage_meshlet_geometry = null;
+            }
+        }
+        return this.#foliage_meshlet_geometry;
+    }
+
+    /**
+     * Lazily constructs and memoizes a zero-defect `SceneBundle` with pre-order joint nodes,
+     * bark + foliage mesh nodes, a shared `Skin`, and the looping wind `ShadeAnimationClip`.
+     *
+     * @returns {SceneBundle}
+     */
+    get scene_bundle() {
+        if (this.#scene_bundle !== null) {
+            return this.#scene_bundle;
+        }
+
+        const bundle = new SceneBundle();
+
+        // Node 0: named root so prefab_compile keeps a single root above joints and mesh nodes
+        bundle.add_node(SceneNode.from({
+            name: `${this.name}_lod${this.level}_root`,
+            parent: -1
+        }));
+
+        const skin_info = this.skin_info;
+        const joint_node_indices = [];
+
+        if (skin_info && skin_info.joint_count > 0) {
+            const J = skin_info.joint_count;
+            const ibm = new Float32Array(J * 16);
+
+            for (let j = 0; j < J; j++) {
+                const pj = skin_info.joint_parents[j];
+                const parent_node = pj < 0 ? 0 : (pj + 1);
+
+                const jx = skin_info.joint_positions[j * 3];
+                const jy = skin_info.joint_positions[j * 3 + 1];
+                const jz = skin_info.joint_positions[j * 3 + 2];
+
+                const px = pj < 0 ? 0.0 : skin_info.joint_positions[pj * 3];
+                const py = pj < 0 ? 0.0 : skin_info.joint_positions[pj * 3 + 1];
+                const pz = pj < 0 ? 0.0 : skin_info.joint_positions[pj * 3 + 2];
+
+                const node_idx = bundle.add_node(SceneNode.from({
+                    name: `joint_${j}`,
+                    parent: parent_node,
+                    translation: [jx - px, jy - py, jz - pz],
+                    rotation: [0, 0, 0, 1],
+                    scale: [1, 1, 1]
+                }));
+                joint_node_indices.push(node_idx);
+
+                // Exact inverse-bind matrix T(-p_j) for zero frame defect (frame_defect === 0)
+                const m_off = j * 16;
+                ibm[m_off + 0] = 1.0;
+                ibm[m_off + 5] = 1.0;
+                ibm[m_off + 10] = 1.0;
+                ibm[m_off + 12] = -jx;
+                ibm[m_off + 13] = -jy;
+                ibm[m_off + 14] = -jz;
+                ibm[m_off + 15] = 1.0;
+            }
+
+            const mesh_node_indices = [];
+
+            const bark_node = bundle.add_node(SceneNode.from({
+                name: `${this.name}_bark_lod${this.level}`,
+                parent: 0,
+                geometry: this.bark_meshlet_geometry,
+                material: this.bark_material
+            }));
+            mesh_node_indices.push(bark_node);
+
+            const fol_meshlet = this.foliage_meshlet_geometry;
+            if (fol_meshlet !== null) {
+                const fol_node = bundle.add_node(SceneNode.from({
+                    name: `${this.name}_foliage_lod${this.level}`,
+                    parent: 0,
+                    geometry: fol_meshlet,
+                    material: this.foliage_material
+                }));
+                mesh_node_indices.push(fol_node);
+            }
+
+            bundle.skins.push(Skin.from({
+                name: `${this.name}_skin_lod${this.level}`,
+                joints: joint_node_indices,
+                inverse_bind_matrices: ibm,
+                meshes: mesh_node_indices
+            }));
+
+            if (this.wind_rig !== null && this.wind_rig.joints.length > 0) {
+                bundle.foliage_rigs.push(this.wind_rig.clone());
+            }
+        } else {
+            bundle.add_node(SceneNode.from({
+                name: `${this.name}_bark_lod${this.level}`,
+                parent: 0,
+                geometry: this.bark_meshlet_geometry,
+                material: this.bark_material
+            }));
+
+            const fol_meshlet = this.foliage_meshlet_geometry;
+            if (fol_meshlet !== null) {
+                bundle.add_node(SceneNode.from({
+                    name: `${this.name}_foliage_lod${this.level}`,
+                    parent: 0,
+                    geometry: fol_meshlet,
+                    material: this.foliage_material
+                }));
+            }
+        }
+
+        this.#scene_bundle = bundle;
+        return bundle;
+    }
+
+    /**
+     * Lazily compiles and memoizes the `Prefab` from `this.scene_bundle`.
+     *
+     * @returns {import("../../../engine/graphics3/prefab/Prefab.js").Prefab}
+     */
+    get prefab() {
+        if (this.#prefab === null) {
+            this.#prefab = prefab_compile(this.scene_bundle);
+        }
+        return this.#prefab;
+    }
+
+    /**
+     * Number of skeletal joints in this LOD.
+     * @returns {number}
+     */
+    get joint_count() {
+        return this.skin_info ? this.skin_info.joint_count : 0;
+    }
+
+    /**
+     * Total vertex count across bark and foliage geometries for this LOD.
+     * @returns {number}
+     */
+    get vertex_count() {
+        const bark_v = this.bark_geometry?.getAttribute("position")?.count ?? 0;
+        const fol_v = this.foliage_geometry?.getAttribute("position")?.count ?? 0;
+        return bark_v + fol_v;
+    }
+
+    /**
+     * Total triangle count across bark and foliage geometries for this LOD.
+     * @returns {number}
+     */
+    get triangle_count() {
+        const bark_i = this.bark_geometry?.index?.count ?? 0;
+        const fol_i = this.foliage_geometry?.index?.count ?? 0;
+        return ((bark_i + fol_i) / 3) | 0;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+TreeLODAsset.prototype.isTreeLODAsset = true;

package/src/generation/foliage/asset/generate_tree.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Turn-key procedural tree and foliage generator.
+ *
+ * Can be called with:
+ * - Zero arguments (`generate_tree()`) -> generates a complete 3-LOD Oak `TreeAsset`.
+ * - A preset string (`generate_tree("pine")` or `generate_tree(TreePreset.Willow)`).
+ * - A `TreeSpeciesConfig` instance (`generate_tree(species_config)`).
+ * - An options object (`generate_tree({ preset: "birch", seed: 42, crown: { height: 14 }, lod_count: 3 })`).
+ *
+ * @param {string|import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig|Object} [options={}]
+ * @returns {TreeAsset}
+ */
+export function generate_tree(options?: string | import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig | any): TreeAsset;
+import { TreeAsset } from "./TreeAsset.js";
+//# sourceMappingURL=generate_tree.d.ts.map

package/src/generation/foliage/asset/generate_tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/generate_tree.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AACH,wCAHW,MAAM,GAAC,OAAO,gCAAgC,EAAE,iBAAiB,MAAO,GACtE,SAAS,CAqErB;0BAlFyB,gBAAgB"}

package/src/generation/foliage/asset/generate_tree.js

@@ -0,0 +1,93 @@
+import { build_tree_wind_rig } from "../animation/build_tree_wind_rig.js";
+import { TreePreset } from "../config/TreePreset.js";
+import { make_bark_material } from "../material/make_bark_material.js";
+import { make_foliage_material } from "../material/make_foliage_material.js";
+import { foliage_collect_attachments } from "../mesh/foliage_collect_attachments.js";
+import { tree_mesh_build_bark } from "../mesh/tree_mesh_build_bark.js";
+import { tree_mesh_build_foliage } from "../mesh/tree_mesh_build_foliage.js";
+import { make_tree_species_preset } from "../presets/make_tree_species_preset.js";
+import { tree_skeleton_assign_skin_joints } from "../skeleton/tree_skeleton_assign_skin_joints.js";
+import { tree_skeleton_grow } from "../skeleton/tree_skeleton_grow.js";
+import { TreeAsset } from "./TreeAsset.js";
+import { TreeLODAsset } from "./TreeLODAsset.js";
+
+/**
+ * Turn-key procedural tree and foliage generator.
+ *
+ * Can be called with:
+ * - Zero arguments (`generate_tree()`) -> generates a complete 3-LOD Oak `TreeAsset`.
+ * - A preset string (`generate_tree("pine")` or `generate_tree(TreePreset.Willow)`).
+ * - A `TreeSpeciesConfig` instance (`generate_tree(species_config)`).
+ * - An options object (`generate_tree({ preset: "birch", seed: 42, crown: { height: 14 }, lod_count: 3 })`).
+ *
+ * @param {string|import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig|Object} [options={}]
+ * @returns {TreeAsset}
+ */
+export function generate_tree(options = {}) {
+    let config;
+    let eager_meshlets = false;
+    let custom_bark_material = null;
+    let custom_foliage_material = null;
+
+    if (typeof options === "string") {
+        config = make_tree_species_preset(options);
+    } else if (options && options.isTreeSpeciesConfig) {
+        config = options.clone();
+    } else {
+        const opts = options || {};
+        const preset = opts.preset ?? TreePreset.Oak;
+        config = make_tree_species_preset(preset, opts);
+        eager_meshlets = Boolean(opts.eager_meshlets);
+        if (opts.custom_bark_material && opts.custom_bark_material.isShadeMaterial) {
+            custom_bark_material = opts.custom_bark_material;
+        }
+        if (opts.custom_foliage_material && opts.custom_foliage_material.isShadeMaterial) {
+            custom_foliage_material = opts.custom_foliage_material;
+        }
+    }
+
+    const skeleton = tree_skeleton_grow(config);
+    const skin_info = tree_skeleton_assign_skin_joints(skeleton, config.wind.max_joints);
+    const wind_rig = config.wind.enabled ? build_tree_wind_rig(skin_info, config.wind) : null;
+    const attachments = foliage_collect_attachments(skeleton, config);
+
+    const bark_material = custom_bark_material !== null
+        ? custom_bark_material
+        : make_bark_material(config.bark_material, config.seed);
+
+    const foliage_material = custom_foliage_material !== null
+        ? custom_foliage_material
+        : (config.foliage.enabled ? make_foliage_material(config.foliage_material, config.seed) : null);
+
+    const asset = new TreeAsset();
+    asset.config = config;
+    asset.skeleton = skeleton;
+    asset.attachments = attachments;
+    asset.skin_info = skin_info;
+    asset.wind_rig = wind_rig;
+    asset.bark_material = bark_material;
+    asset.foliage_material = foliage_material;
+
+    for (let i = 0; i < config.lods.length; i++) {
+        const lod_cfg = config.lods[i];
+        const lod_asset = new TreeLODAsset();
+        lod_asset.level = i;
+        lod_asset.name = config.name || "tree";
+        lod_asset.configure_lazy_geometries(
+            () => tree_mesh_build_bark(skeleton, config, lod_cfg),
+            () => tree_mesh_build_foliage(skeleton, attachments, config, lod_cfg)
+        );
+        lod_asset.bark_material = bark_material;
+        lod_asset.foliage_material = foliage_material;
+        lod_asset.skin_info = config.wind.enabled ? skin_info : null;
+        lod_asset.wind_rig = wind_rig;
+
+        if (eager_meshlets) {
+            void lod_asset.prefab;
+        }
+
+        asset.lods.push(lod_asset);
+    }
+
+    return asset;
+}

package/src/generation/foliage/asset/place_tree.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Turn-key helper to place a procedural tree (`TreeAsset`, `Prefab`, or on-the-fly generation options)
+ * into a bare `GPUSceneContext` + `EntityComponentDataset` (one without ECS graphics systems),
+ * automatically registering its GPU fluid-driven `FoliageWindRig` with `GPUAnimationManager` so its
+ * bones sample `GPUSceneWind` (3D fluid dynamics cascades + global far-field wind) every frame.
+ *
+ * When using a full ECS world with `ShadedGeometrySystem`, `MeshSkinSystem`, and `FoliageWindSystem`,
+ * prefer `prefab_instantiate(tree.prefab, dataset, root)` directly so the ECS systems manage rows,
+ * skins, and wind rigs automatically.
+ *
+ * @param {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
+ * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+ * @param {Object} [options={}]
+ * @param {import("./TreeAsset.js").TreeAsset} [options.tree] pre-generated `TreeAsset`
+ * @param {import("../../../engine/graphics3/prefab/Prefab.js").Prefab} [options.prefab] pre-compiled `Prefab`
+ * @param {number} [options.lod=0] LOD index when placing from `TreeAsset`
+ * @param {Transform64} [options.placement] explicit `Transform64` placement
+ * @param {number[]|{x:number,y:number,z:number}} [options.position] world position `[x, y, z]`
+ * @param {number[]|{x:number,y:number,z:number,w:number}} [options.rotation] world quaternion `[x, y, z, w]`
+ * @param {number} [options.rotation_y] yaw rotation around `+Y` in radians
+ * @param {number|number[]|{x:number,y:number,z:number}} [options.scale] uniform or 3-axis scale
+ * @param {boolean} [options.wind=true] whether to register GPU fluid-driven foliage wind rigs
+ * @param {number} [options.wind_weight=1.0] foliage wind rig blend weight in `pose_accumulator`
+ * @param {number} [options.wind_phase_offset] explicit phase offset in radians for flutter desynchronization
+ * @returns {{
+ *   root: number,
+ *   instance: import("../../../engine/graphics3/prefab/PrefabInstance.js").PrefabInstance,
+ *   skins: {entity: number, skin_id: number}[]|null,
+ *   foliage_rig_ids: number[],
+ *   drawn: number,
+ *   tree: import("./TreeAsset.js").TreeAsset|null,
+ *   prefab: import("../../../engine/graphics3/prefab/Prefab.js").Prefab
+ * }}
+ */
+export function place_tree(scene_context: import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext, dataset: import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset, options?: {
+    tree?: import("./TreeAsset.js").TreeAsset;
+    prefab?: import("../../../engine/graphics3/prefab/Prefab.js").Prefab;
+    lod?: number;
+    placement?: Transform64;
+    position?: number[] | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation?: number[] | {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+    };
+    rotation_y?: number;
+    scale?: number | number[] | {
+        x: number;
+        y: number;
+        z: number;
+    };
+    wind?: boolean;
+    wind_weight?: number;
+    wind_phase_offset?: number;
+}): {
+    root: number;
+    instance: import("../../../engine/graphics3/prefab/PrefabInstance.js").PrefabInstance;
+    skins: {
+        entity: number;
+        skin_id: number;
+    }[] | null;
+    foliage_rig_ids: number[];
+    drawn: number;
+    tree: import("./TreeAsset.js").TreeAsset | null;
+    prefab: import("../../../engine/graphics3/prefab/Prefab.js").Prefab;
+};
+/**
+ * Unplaces a tree previously placed via `place_tree`, unregistering its GPU fluid-driven foliage
+ * wind rigs BEFORE destroying the prefab instance so target entities still exist in `dataset` during cleanup.
+ *
+ * @param {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
+ * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+ * @param {ReturnType<typeof place_tree>} placed
+ */
+export function unplace_tree(scene_context: import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext, dataset: import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset, placed: ReturnType<typeof place_tree>): void;
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+//# sourceMappingURL=place_tree.d.ts.map

package/src/generation/foliage/asset/place_tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/place_tree.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,0CAxBW,OAAO,kDAAkD,EAAE,eAAe,WAC1E,OAAO,+CAA+C,EAAE,sBAAsB;IAEjC,IAAI,GAAjD,OAAO,gBAAgB,EAAE,SAAS;IACoC,MAAM,GAA5E,OAAO,4CAA4C,EAAE,MAAM;IAC1C,GAAG,GAApB,MAAM;IACgB,SAAS,GAA/B,WAAW;IACqC,QAAQ,GAAxD,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IACoB,QAAQ,GAAjE,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IAC7B,UAAU,GAA3B,MAAM;IACiD,KAAK,GAA5D,MAAM,GAAC,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IAC1B,IAAI,GAAtB,OAAO;IACU,WAAW,GAA5B,MAAM;IACW,iBAAiB,GAAlC,MAAM;IACJ;IACZ,IAAQ,EAAE,MAAM,CAAC;IACjB,QAAY,EAAE,OAAO,oDAAoD,EAAE,cAAc,CAAC;IAC1F,KAAS,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,EAAE,GAAC,IAAI,CAAC;IACpD,eAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,KAAS,EAAE,MAAM,CAAC;IAClB,IAAQ,EAAE,OAAO,gBAAgB,EAAE,SAAS,GAAC,IAAI,CAAC;IAClD,MAAU,EAAE,OAAO,4CAA4C,EAAE,MAAM,CAAA;CACpE,CA+HH;AAED;;;;;;;GAOG;AACH,4CAJW,OAAO,kDAAkD,EAAE,eAAe,WAC1E,OAAO,+CAA+C,EAAE,sBAAsB,UAC9E,WAAW,iBAAiB,CAAC,QAiBvC;4BA/L2B,8CAA8C"}