@woosh/meep-engine 3.56.0 → 3.58.0

package/src/generation/foliage/analysis/tree_render_cost.js

@@ -0,0 +1,157 @@
+import { assert } from "../../../core/assert.js";
+import { convex_hull_monotone_2d } from "../../../core/geom/2d/convex-hull/convex_hull_monotone_2d.js";
+import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
+import { tree_mesh_build_foliage } from "../mesh/tree_mesh_build_foliage.js";
+
+/**
+ * Mean area (m^2) a tree's drawn envelope shows from the side, over every azimuth: the envelope is the convex hull of
+ * the drawn vertices in each of `slices` equal horizontal slices, and a convex slice's mean width over azimuths is its
+ * perimeter over PI (Cauchy), so the area is the sum of `perimeter / PI * thickness`. It is what a viewer at the
+ * tree's height sees of it, the part of the screen the tree's triangles are spent on.
+ *
+ * @param {Array<ArrayLike<number>>} position_arrays vertex positions, 3 per vertex, y up
+ * @param {number} [slices] horizontal slices the height is cut into; the measure's resolution
+ * @returns {number}
+ */
+export function tree_envelope_side_area(position_arrays, slices = 64) {
+    assert.isNonNegativeInteger(slices, 'slices');
+    assert.greaterThan(slices, 0, 'slices');
+
+    let y_min = Infinity;
+    let y_max = -Infinity;
+    for (const p of position_arrays) {
+        for (let i = 1; i < p.length; i += 3) {
+            if (p[i] < y_min) y_min = p[i];
+            if (p[i] > y_max) y_max = p[i];
+        }
+    }
+    if (!(y_max > y_min)) {
+        return 0;
+    }
+
+    const thickness = (y_max - y_min) / slices;
+    const bins = [];
+    for (let s = 0; s < slices; s++) {
+        bins.push([]);
+    }
+    for (const p of position_arrays) {
+        for (let i = 0; i < p.length; i += 3) {
+            const s = Math.min(slices - 1, Math.floor((p[i + 1] - y_min) / thickness));
+            bins[s].push(p[i], p[i + 2]);
+        }
+    }
+
+    let area = 0;
+    for (let s = 0; s < slices; s++) {
+        const points = bins[s];
+        if (points.length < 4) {
+            continue;
+        }
+        const hull = convex_hull_monotone_2d(points);
+        let perimeter = 0;
+        for (let k = 0; k < hull.length; k++) {
+            const a = hull[k] * 2;
+            const b = hull[(k + 1) % hull.length] * 2;
+            perimeter += Math.hypot(points[b] - points[a], points[b + 1] - points[a + 1]);
+        }
+        area += perimeter / Math.PI * thickness;
+    }
+    return area;
+}
+
+/**
+ * The most a generated tree may spend per square metre it shows from the side (`tree_render_cost`), at each LOD and in
+ * wind joints: the densest of the presets at 6aff5265e (2026-10-25), the last generator whose trees were drawn in real
+ * time, before twigs were meshed shoot by shoot (seed 1337), over `tree_grown_side_area` (its LOD0 drew every leaf's
+ * card). Triangles: the willow at LOD0 and LOD1, the shrub at LOD2; joints, which every LOD's rig is held to: the
+ * shrub; foliage texture bytes, every map's base level, which all of a tree's LODs share: the shrub, whose leaf atlas
+ * was the 640 KiB every preset's was. The fern was 7,065 triangles per m^2 at LOD0 there, nine times the willow, and
+ * its atlas 1.3 MiB per m^2, and is held to the same ceiling.
+ *
+ * A ceiling, not a target: a tree spends what its look needs, up to this.
+ *
+ * @type {{triangle_density: number[], joint_density: number, texture_density: number}}
+ */
+export const TREE_RENDER_COST_CEILING = { triangle_density: [761.2, 412.3, 96.2], joint_density: 16.89, texture_density: 240667 };
+
+/**
+ * What a tree grown as `skeleton` shows from the side, m^2: `tree_envelope_side_area` of its wood's nodes and every
+ * leaf's card, whatever an LOD draws them as.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} leaves every leaf's card
+ *        (`tree_mesh_build_foliage`), `null` for a leafless tree
+ * @returns {number}
+ */
+export function tree_grown_side_area(skeleton, leaves) {
+    const nodes = new Float32Array(skeleton.node_count * 3);
+    for (let v = 0; v < skeleton.node_count; v++) {
+        skeleton.node_read_position(nodes, v * 3, v);
+    }
+    const shown = [nodes];
+    if (leaves !== null) {
+        shown.push(leaves.getAttribute(StandardAttributes.Position).data);
+    }
+    return tree_envelope_side_area(shown);
+}
+
+/**
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} geometry
+ * @returns {number}
+ */
+function triangle_count(geometry) {
+    if (geometry === null || geometry.index === null) {
+        return 0;
+    }
+    return geometry.index.data.length / 3;
+}
+
+/**
+ * @typedef {Object} TreeRenderCost
+ * @property {number} side_area m^2, `tree_grown_side_area`: what the tree grew shows from the side
+ * @property {number[]} triangles bark and foliage triangles of each LOD
+ * @property {number[]} triangle_density each LOD's triangles per m^2 of `side_area`
+ * @property {number[]} joints each LOD's wind joints
+ * @property {number[]} joint_density each LOD's joints per m^2 of `side_area`
+ * @property {number} texture_bytes the base levels of every foliage texture its LODs draw with, each counted once
+ * @property {number} texture_density `texture_bytes` per m^2 of `side_area`
+ */
+
+/**
+ * What a generated tree costs to draw: its triangles and wind joints at every LOD and its foliage textures, each per
+ * square metre of what the tree shows from the side. A bigger tree covers more of the screen and may spend proportionately more.
+ *
+ * @param {import("../asset/TreeAsset.js").TreeAsset} asset from `generate_tree`
+ * @returns {TreeRenderCost}
+ */
+export function tree_render_cost(asset) {
+    assert.greaterThan(asset.lods.length, 0, 'asset.lods.length');
+
+    const leaves = asset.attachments.count > 0
+        ? tree_mesh_build_foliage(asset.skeleton, asset.attachments, asset.config, asset.foliage_cutout)
+        : null;
+    const side_area = tree_grown_side_area(asset.skeleton, leaves);
+    assert.greaterThan(side_area, 0, 'side_area');
+
+    const triangles = asset.lods.map(lod => triangle_count(lod.bark_geometry) + triangle_count(lod.foliage_geometry));
+    const joints = asset.lods.map(lod => lod.joint_count);
+    const textures = new Set();
+    for (const lod of asset.lods) {
+        const material = lod.foliage_material;
+        if (material === null) continue;
+        for (const texture of [material.texture_albedo, material.texture_normal, material.texture_orm]) {
+            if (texture) textures.add(texture.image.source);
+        }
+    }
+    let texture_bytes = 0;
+    for (const image of textures) texture_bytes += image.width * image.height * image.itemSize;
+    return {
+        side_area,
+        triangles,
+        triangle_density: triangles.map(t => t / side_area),
+        joints,
+        joint_density: joints.map(j => j / side_area),
+        texture_bytes,
+        texture_density: texture_bytes / side_area
+    };
+}

package/src/generation/foliage/animation/build_tree_wind_rig.d.ts

@@ -4,8 +4,9 @@
  *
  * Joint `0` (`SceneNode` index `1`, at the trunk base `(0, 0, 0)`) remains anchored at its bind
  * pose so the base of the trunk never pivots off the ground, while upper trunk and branch joints
- * carry physically derived Euler-Bernoulli cantilever compliance, natural frequency, damping ratio,
- * branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
+ * carry Euler-Bernoulli cantilever compliance and natural frequency (`skin_info.joint_compliance`, from the drag
+ * each joint carries and the bending stiffness of its span, and `joint_natural_frequency`, its branch's first mode),
+ * plus damping ratio, branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
  * dispatches `shader_foliage_wind_apply` to sample Meep's 3D fluid simulation wind field
  * (`GPUSceneWind`: `GlobalFluidEffector` far-field + 3D MAC `GPUFluidCascadeStack` wakes/vortices)
  * at each bone's world position and step a 2nd-order damped oscillator directly into `pose_accumulator`.

package/src/generation/foliage/animation/build_tree_wind_rig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build_tree_wind_rig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/animation/build_tree_wind_rig.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,+CAJW,6GAAsG,gBACtG,cAAc,MAAO,GACnB,cAAc,GAAC,IAAI,CAuF/B;+BAvG8B,6BAA6B;+BAD7B,6DAA6D"}
+{"version":3,"file":"build_tree_wind_rig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/animation/build_tree_wind_rig.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,+CAJW,6GAAsG,gBACtG,cAAc,MAAO,GACnB,cAAc,GAAC,IAAI,CAmE/B;+BArF8B,6BAA6B;+BAD7B,6DAA6D"}

package/src/generation/foliage/animation/build_tree_wind_rig.js

@@ -3,6 +3,7 @@ import { clamp } from "../../../core/math/clamp.js";
 import { FoliageWindJoint } from "../../../shade/renderer/animation/foliage/FoliageWindJoint.js";
 import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
 import { TreeWindConfig } from "../config/TreeWindConfig.js";
+import { tree_wind_bend_limit } from "./tree_wind_bend_limit.js";
 
 /**
  * Constructs a GPU fluid-driven `FoliageWindRig` (`name = "foliage_wind"`) for the structural
@@ -10,8 +11,9 @@ import { TreeWindConfig } from "../config/TreeWindConfig.js";
  *
  * Joint `0` (`SceneNode` index `1`, at the trunk base `(0, 0, 0)`) remains anchored at its bind
  * pose so the base of the trunk never pivots off the ground, while upper trunk and branch joints
- * carry physically derived Euler-Bernoulli cantilever compliance, natural frequency, damping ratio,
- * branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
+ * carry Euler-Bernoulli cantilever compliance and natural frequency (`skin_info.joint_compliance`, from the drag
+ * each joint carries and the bending stiffness of its span, and `joint_natural_frequency`, its branch's first mode),
+ * plus damping ratio, branch axis, and vortex-shedding turbulence parameters. At runtime, `GPUAnimationManager`
  * dispatches `shader_foliage_wind_apply` to sample Meep's 3D fluid simulation wind field
  * (`GPUSceneWind`: `GlobalFluidEffector` far-field + 3D MAC `GPUFluidCascadeStack` wakes/vortices)
  * at each bone's world position and step a 2nd-order damped oscillator directly into `pose_accumulator`.
@@ -22,7 +24,8 @@ import { TreeWindConfig } from "../config/TreeWindConfig.js";
  */
 export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig()) {
     const cfg = wind_config && wind_config.isTreeWindConfig ? wind_config : TreeWindConfig.from(wind_config);
-    if (!cfg.enabled || !skin_info || skin_info.joint_count <= 0) {
+    // Joint 0 is the anchored trunk base: with no other joint there is nothing to drive
+    if (!cfg.enabled || !skin_info || skin_info.joint_count <= 1) {
         return null;
     }
 
@@ -30,15 +33,9 @@ export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig(
     rig.name = "foliage_wind";
     rig.root = 0; // SceneNode 0 is the tree root in SceneBundle
 
-    const r0 = (skin_info.joint_radii && skin_info.joint_radii.length > 0)
-        ? Math.max(0.02, skin_info.joint_radii[0])
-        : 0.25;
-
-    const start_joint = skin_info.joint_count === 1 ? 0 : 1;
-
     // Count how many driven joints share the same structural level along each joint's ancestor chain
-    // so serial chains of joints on the same trunk/bough divide the total branch deflection cleanly.
-    const same_level_chain_count = new Uint8Array(skin_info.joint_count);
+    // so serial chains of joints on the same trunk/bough divide the total bend saturation cleanly.
+    const same_level_chain_count = new Uint16Array(skin_info.joint_count);
     for (let j = 0; j < skin_info.joint_count; j++) {
         const lvl = skin_info.joint_levels[j];
         let count = 0;
@@ -52,13 +49,9 @@ export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig(
         same_level_chain_count[j] = Math.max(1, count);
     }
 
-    for (let j = start_joint; j < skin_info.joint_count; j++) {
+    for (let j = 1; j < skin_info.joint_count; j++) {
         const level = skin_info.joint_levels[j];
-        const t_norm = j === 0 ? 0.5 : skin_info.joint_t_norms[j];
         const phase = skin_info.joint_phases[j] * PI2;
-        const r_j = (skin_info.joint_radii && j < skin_info.joint_radii.length)
-            ? Math.max(0.005, skin_info.joint_radii[j])
-            : r0 * Math.pow(0.5, level);
 
         let tx = skin_info.joint_tangents[j * 3];
         let ty = skin_info.joint_tangents[j * 3 + 1];
@@ -75,21 +68,10 @@ export function build_tree_wind_rig(skin_info, wind_config = new TreeWindConfig(
         }
 
         const chain_div = Math.max(1, same_level_chain_count[j]);
-        const base_comp = level === 0
-            ? cfg.trunk_compliance * 0.18
-            : cfg.branch_compliance * 0.24 * (1.0 + 0.35 * (level - 1));
-        const radius_factor = level === 0
-            ? clamp(Math.pow(r0 / Math.max(r_j, 0.25 * r0), 0.35), 0.6, 1.6)
-            : clamp(Math.pow(r0 / Math.max(r_j, 0.08 * r0), 0.45), 0.8, 3.2);
-        const compliance = (base_comp * radius_factor * clamp(0.35 + 0.65 * t_norm, 0.3, 1.15)) / chain_div;
-
-        const natural_frequency = cfg.natural_frequency * (1.0 + 0.65 * level + 0.35 * t_norm);
+        const compliance = skin_info.joint_compliance[j];
+        const natural_frequency = skin_info.joint_natural_frequency[j];
         const damping_ratio = clamp(cfg.damping_ratio * (1.0 + 0.12 * level), 0.05, 1.5);
-        const max_angle = clamp(
-            (cfg.max_bend_angle * (level === 0 ? 0.18 : (0.42 + 0.18 * Math.min(level, 2)))) / chain_div,
-            0.02,
-            0.85
-        );
+        const max_angle = clamp(tree_wind_bend_limit(cfg.max_bend_angle, level) / chain_div, 0.02, 0.85);
         const turbulence = clamp(cfg.turbulence * (level === 0 ? 0.35 : (0.65 + 0.35 * Math.min(level, 2))), 0.0, 1.0);
 
         rig.joints.push(FoliageWindJoint.from({

package/src/generation/foliage/animation/tree_wind_bend_limit.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bend (radians) that the wind joints on one branch can show between them: `chunk_foliage_wind_step` soft-saturates
+ * each joint's deflection `theta` to `theta * m / (m + theta)`, and `build_tree_wind_rig` gives every joint of a
+ * serial chain of `n` joints `m = limit / n`, so a branch bent by `theta` in total shows `theta * limit / (limit + theta)`
+ * however many joints share it equally.
+ *
+ * @param {number} max_bend_angle `TreeWindConfig.max_bend_angle`
+ * @param {number} level branching level of the branch, 0 for the trunk
+ * @returns {number}
+ */
+export function tree_wind_bend_limit(max_bend_angle: number, level: number): number;
+//# sourceMappingURL=tree_wind_bend_limit.d.ts.map

package/src/generation/foliage/animation/tree_wind_bend_limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_wind_bend_limit.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/animation/tree_wind_bend_limit.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qDAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB"}

package/src/generation/foliage/animation/tree_wind_bend_limit.js

@@ -0,0 +1,13 @@
+/**
+ * Bend (radians) that the wind joints on one branch can show between them: `chunk_foliage_wind_step` soft-saturates
+ * each joint's deflection `theta` to `theta * m / (m + theta)`, and `build_tree_wind_rig` gives every joint of a
+ * serial chain of `n` joints `m = limit / n`, so a branch bent by `theta` in total shows `theta * limit / (limit + theta)`
+ * however many joints share it equally.
+ *
+ * @param {number} max_bend_angle `TreeWindConfig.max_bend_angle`
+ * @param {number} level branching level of the branch, 0 for the trunk
+ * @returns {number}
+ */
+export function tree_wind_bend_limit(max_bend_angle, level) {
+    return max_bend_angle * (level === 0 ? 0.18 : (0.42 + 0.18 * Math.min(level, 2)));
+}

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

@@ -23,15 +23,11 @@ export class TreeAsset {
      */
     attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet;
     /**
-     * Extracted structural skin joint descriptors.
+     * The wind joints of all the wood as grown, which `attachments` are bound to; no LOD draws it, each has its own
+     * (`TreeLODAsset.skin_info`).
      * @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 (`name = "foliage_wind"`), or `null` if wind disabled.
-     * @type {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
-     */
-    wind_rig: import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig | null;
     /**
      * Procedural bark PBR `StandardShadeMaterial` shared across all LODs.
      * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
@@ -42,6 +38,11 @@ export class TreeAsset {
      * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
      */
     foliage_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * Shape of the synthesized foliage atlas (hull per tile, leaf coverage), or `null` with a caller's own foliage material.
+     * @type {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null}
+     */
+    foliage_cutout: import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout | null;
     /**
      * Progressive LOD asset chain (`lods[0]` = highest detail).
      * @type {import("./TreeLODAsset.js").TreeLODAsset[]}
@@ -67,6 +68,11 @@ export class TreeAsset {
      * @returns {import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry|null}
      */
     get foliage_meshlet_geometry(): import("../../../shade/renderer/geometry/MeshletGeometry.js").MeshletGeometry;
+    /**
+     * Highest-detail (`lods[0]`) GPU fluid-driven foliage wind rig, or `null` if wind is disabled.
+     * @returns {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
+     */
+    get wind_rig(): import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig;
     /**
      * Highest-detail (`lods[0]`) `SceneBundle` (lazy memoized).
      * @returns {import("../../../shade/renderer/loader/SceneBundle.js").SceneBundle|null}

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

@@ -1 +1 @@
-{"version":3,"file":"TreeAsset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/TreeAsset.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,QAFU,OAAO,gCAAgC,EAAE,iBAAiB,CAEtD;IAEd;;;OAGG;IACH,UAFU,OAAO,6BAA6B,EAAE,YAAY,CAE5C;IAEhB;;;OAGG;IACH,aAFU,OAAO,wCAAwC,EAAE,oBAAoB,CAE5D;IAEnB;;;OAGG;IACH,WAFU,6GAAsG,CAE/F;IAEjB;;;OAGG;IACH,UAFU,OAAO,6DAA6D,EAAE,cAAc,GAAC,IAAI,CAEnF;IAEhB;;;OAGG;IACH,eAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE9E;IAErB;;;OAGG;IACH,kBAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE3E;IAExB;;;OAGG;IACH,MAFU,OAAO,mBAAmB,EAAE,YAAY,EAAE,CAE1C;IAEV;;;OAGG;IACH,qFAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,2GAEC;IAED;;;OAGG;IACH,8GAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,0EAEC;IAGL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B"}
+{"version":3,"file":"TreeAsset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/TreeAsset.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,QAFU,OAAO,gCAAgC,EAAE,iBAAiB,CAEtD;IAEd;;;OAGG;IACH,UAFU,OAAO,6BAA6B,EAAE,YAAY,CAE5C;IAEhB;;;OAGG;IACH,aAFU,OAAO,wCAAwC,EAAE,oBAAoB,CAE5D;IAEnB;;;;OAIG;IACH,WAFU,6GAAsG,CAE/F;IAEjB;;;OAGG;IACH,eAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE9E;IAErB;;;OAGG;IACH,kBAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE3E;IAExB;;;OAGG;IACH,gBAFU,OAAO,mCAAmC,EAAE,kBAAkB,GAAC,IAAI,CAEvD;IAEtB;;;OAGG;IACH,MAFU,OAAO,mBAAmB,EAAE,YAAY,EAAE,CAE1C;IAEV;;;OAGG;IACH,qFAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,2GAEC;IAED;;;OAGG;IACH,8GAEC;IAED;;;OAGG;IACH,qGAEC;IAED;;;OAGG;IACH,wFAEC;IAED;;;OAGG;IACH,0EAEC;IAGL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B"}

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

@@ -26,17 +26,12 @@ export class TreeAsset {
     attachments = null;
 
     /**
-     * Extracted structural skin joint descriptors.
+     * The wind joints of all the wood as grown, which `attachments` are bound to; no LOD draws it, each has its own
+     * (`TreeLODAsset.skin_info`).
      * @type {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>}
      */
     skin_info = null;
 
-    /**
-     * GPU fluid-driven foliage wind rig (`name = "foliage_wind"`), or `null` if wind disabled.
-     * @type {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
-     */
-    wind_rig = null;
-
     /**
      * Procedural bark PBR `StandardShadeMaterial` shared across all LODs.
      * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
@@ -49,6 +44,12 @@ export class TreeAsset {
      */
     foliage_material = null;
 
+    /**
+     * Shape of the synthesized foliage atlas (hull per tile, leaf coverage), or `null` with a caller's own foliage material.
+     * @type {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null}
+     */
+    foliage_cutout = null;
+
     /**
      * Progressive LOD asset chain (`lods[0]` = highest detail).
      * @type {import("./TreeLODAsset.js").TreeLODAsset[]}
@@ -87,6 +88,14 @@ export class TreeAsset {
         return this.lods.length > 0 ? this.lods[0].foliage_meshlet_geometry : null;
     }
 
+    /**
+     * Highest-detail (`lods[0]`) GPU fluid-driven foliage wind rig, or `null` if wind is disabled.
+     * @returns {import("../../../shade/renderer/animation/foliage/FoliageWindRig.js").FoliageWindRig|null}
+     */
+    get wind_rig() {
+        return this.lods.length > 0 ? this.lods[0].wind_rig : null;
+    }
+
     /**
      * Highest-detail (`lods[0]`) `SceneBundle` (lazy memoized).
      * @returns {import("../../../shade/renderer/loader/SceneBundle.js").SceneBundle|null}

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

@@ -17,13 +17,21 @@ export class TreeLODAsset {
      */
     name: string;
     /**
-     * Configures lazy builders for `bark_geometry` and `foliage_geometry` so coarse LODs are only
-     * triangulated when accessed.
+     * What the LOD is drawn to: its error, the one this tree's ceiling allows (`tree_lod_plan`).
+     * @type {import("../config/TreeLODConfig.js").TreeLODConfig|null}
+     */
+    config: import("../config/TreeLODConfig.js").TreeLODConfig | null;
+    /**
+     * Configures lazy builders for the bark and the foliage, so an LOD is only built when it is drawn. The foliage's
+     * geometry and material are built together, `null` for a tree without foliage.
      *
      * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry} bark_builder
-     * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} foliage_builder
+     * @param {() => {geometry: import("../../../shade/renderer/geometry/Geometry.js").Geometry, material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}|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;
+    configure_lazy_geometries(bark_builder: () => import("../../../shade/renderer/geometry/Geometry.js").Geometry, foliage_builder: () => {
+        geometry: import("../../../shade/renderer/geometry/Geometry.js").Geometry;
+        material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    } | null): void;
     /**
      * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} value
      */
@@ -38,22 +46,27 @@ export class TreeLODAsset {
      */
     set foliage_geometry(value: import("../../../shade/renderer/geometry/Geometry.js").Geometry);
     /**
-     * Triangulated foliage card `Geometry`, or `null` if foliage is disabled / keep_ratio = 0.
+     * The LOD's foliage: its cluster cards, or `null` for a tree without foliage.
      * @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}
+     * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null} value
      */
-    bark_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    set foliage_material(value: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial);
     /**
-     * Shared procedural foliage `StandardShadeMaterial`.
+     * The material the LOD's foliage is drawn with: its cluster cards' baked atlas.
+     * @returns {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null}
+     */
+    get foliage_material(): import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * Shared procedural bark `StandardShadeMaterial`.
      * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
      */
-    foliage_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    bark_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
     /**
-     * Structural skin joint hierarchy extracted from the `TreeSkeleton`.
+     * The LOD's wind joints: on the wood it draws, a subset of the finer LOD's (`tree_lod_plan`), or `null` when the
+     * tree has no wind.
      * @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>;

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

@@ -1 +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"}
+{"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;IAEd;;;OAGG;IACH,QAFU,OAAO,4BAA4B,EAAE,aAAa,GAAC,IAAI,CAEnD;IAgCd;;;;;;OAMG;IACH,wCAHW,MAAM,OAAO,8CAA8C,EAAE,QAAQ,mBACrE,MAAM;QAAC,QAAQ,EAAE,OAAO,8CAA8C,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,OAAO,2DAA2D,EAAE,qBAAqB,CAAA;KAAC,GAAC,IAAI,QASrM;IAwBD;;OAEG;IACH,0FAGC;IAlBD;;;OAGG;IACH,qFAMC;IAmBD;;OAEG;IACH,6FAGC;IAfD;;;OAGG;IACH,wFAGC;IAmBD;;OAEG;IACH,uHAGC;IAfD;;;OAGG;IACH,kHAGC;IAUD;;;OAGG;IACH,eAFU,OAAO,2DAA2D,EAAE,qBAAqB,CAE9E;IAErB;;;;OAIG;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;4BA7W2B,+CAA+C"}

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

@@ -24,6 +24,12 @@ export class TreeLODAsset {
      */
     name = "tree";
 
+    /**
+     * What the LOD is drawn to: its error, the one this tree's ceiling allows (`tree_lod_plan`).
+     * @type {import("../config/TreeLODConfig.js").TreeLODConfig|null}
+     */
+    config = null;
+
     /**
      * @type {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null}
      */
@@ -40,9 +46,14 @@ export class TreeLODAsset {
     #foliage_geometry = null;
 
     /**
-     * @type {(() => import("../../../shade/renderer/geometry/Geometry.js").Geometry|null)|null}
+     * @type {(() => {geometry: import("../../../shade/renderer/geometry/Geometry.js").Geometry, material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}|null)|null}
+     */
+    #foliage_builder = null;
+
+    /**
+     * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null}
      */
-    #foliage_geometry_builder = null;
+    #foliage_material = null;
 
     /**
      * @type {boolean}
@@ -50,20 +61,31 @@ export class TreeLODAsset {
     #foliage_geometry_built = false;
 
     /**
-     * Configures lazy builders for `bark_geometry` and `foliage_geometry` so coarse LODs are only
-     * triangulated when accessed.
+     * Configures lazy builders for the bark and the foliage, so an LOD is only built when it is drawn. The foliage's
+     * geometry and material are built together, `null` for a tree without foliage.
      *
      * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry} bark_builder
-     * @param {() => import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} foliage_builder
+     * @param {() => {geometry: import("../../../shade/renderer/geometry/Geometry.js").Geometry, material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}|null} foliage_builder
      */
     configure_lazy_geometries(bark_builder, foliage_builder) {
         this.#bark_geometry_builder = bark_builder;
-        this.#foliage_geometry_builder = foliage_builder;
+        this.#foliage_builder = foliage_builder;
         this.#bark_geometry = null;
         this.#foliage_geometry = null;
+        this.#foliage_material = null;
         this.#foliage_geometry_built = false;
     }
 
+    #build_foliage() {
+        if (!this.#foliage_geometry_built && this.#foliage_builder !== null) {
+            this.#foliage_geometry_built = true;
+            const built = this.#foliage_builder();
+            this.#foliage_builder = null;
+            this.#foliage_geometry = built !== null ? built.geometry : null;
+            this.#foliage_material = built !== null ? built.material : null;
+        }
+    }
+
     /**
      * Triangulated bark `Geometry`.
      * @returns {import("../../../shade/renderer/geometry/Geometry.js").Geometry}
@@ -85,15 +107,11 @@ export class TreeLODAsset {
     }
 
     /**
-     * Triangulated foliage card `Geometry`, or `null` if foliage is disabled / keep_ratio = 0.
+     * The LOD's foliage: its cluster cards, or `null` for a tree without foliage.
      * @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;
-        }
+        this.#build_foliage();
         return this.#foliage_geometry;
     }
 
@@ -101,25 +119,36 @@ export class TreeLODAsset {
      * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} value
      */
     set foliage_geometry(value) {
+        this.#build_foliage();
         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}
+     * The material the LOD's foliage is drawn with: its cluster cards' baked atlas.
+     * @returns {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null}
      */
-    bark_material = null;
+    get foliage_material() {
+        this.#build_foliage();
+        return this.#foliage_material;
+    }
 
     /**
-     * Shared procedural foliage `StandardShadeMaterial`.
+     * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null} value
+     */
+    set foliage_material(value) {
+        this.#build_foliage();
+        this.#foliage_material = value;
+    }
+
+    /**
+     * Shared procedural bark `StandardShadeMaterial`.
      * @type {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
      */
-    foliage_material = null;
+    bark_material = null;
 
     /**
-     * Structural skin joint hierarchy extracted from the `TreeSkeleton`.
+     * The LOD's wind joints: on the wood it draws, a subset of the finer LOD's (`tree_lod_plan`), or `null` when the
+     * tree has no wind.
      * @type {ReturnType<import("../skeleton/tree_skeleton_assign_skin_joints.js").tree_skeleton_assign_skin_joints>}
      */
     skin_info = null;

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

@@ -7,6 +7,17 @@
  * - A `TreeSpeciesConfig` instance (`generate_tree(species_config)`).
  * - An options object (`generate_tree({ preset: "birch", seed: 42, crown: { height: 14 }, lod_count: 3 })`).
  *
+ * Each LOD is the tree drawn to a geometric error (`TreeLODConfig.error`): the finest at which its bark and its
+ * foliage, and its wind joints, fit that LOD's `TREE_RENDER_COST_CEILING` over the side area of the leaves and wood
+ * the tree grew (`tree_lod_plan`, `tree_grown_side_area`). Its foliage is one card per cluster (`tree_clusters`), each
+ * drawn with the tile of one of a few cuts (`tree_cluster_representatives`), shared by all its LODs in one atlas as
+ * large as the tree's texture ceiling: baked from the leaves and twigs that cut grew (`tree_cluster_bake`) at the
+ * leaf's own texel, or for a coarser LOD's cut, where the LOD before it is drawn to a pixel. Its rig is on the wood it draws, at a tolerance no finer than its
+ * error, its joints a subset of the finer LOD's, so switching keeps the joints both share.
+ *
+ * The asset's `foliage_material` and `skin_info` are the leaves' and the wood's as grown, which the cards are baked
+ * from and the leaves are bound to; each LOD has its own.
+ *
  * @param {string|import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig|Object} [options={}]
  * @returns {TreeAsset}
  */

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

@@ -1 +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"}
+{"version":3,"file":"generate_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/generate_tree.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wCAHW,MAAM,GAAC,OAAO,gCAAgC,EAAE,iBAAiB,MAAO,GACtE,SAAS,CAyIrB;0BAlKyB,gBAAgB"}