@woosh/meep-engine 3.57.0 → 3.59.0

package/src/generation/foliage/config/ShootGrowthConfig.js

@@ -4,26 +4,54 @@ import { computeHashFloat } from "../../../core/primitives/numbers/computeHashFl
 
 /**
  * How a species' twig systems grow together, season by season, in the light they make for each other (see
- * `tree_skeleton_grow_shoots`): how old the framework is, and how a shoot's vigour follows the light it receives.
+ * `tree_skeleton_grow_shoots`): how old the tree is, how fast its leader grows, and how a shoot's vigour follows the
+ * light it receives.
  *
  * Vigour is the bifurcation ratio Rb, the net shoots a shoot leaves a year (Niinemets & Lukjanova 2003, New Phytol.
- * 158: 75-89). It rises with light: from 1, where shoots just replace themselves, at {@link compensation_light}, to
- * {@link vigour} at {@link saturation_light}, flat above, and below 1 in deeper shade, where a branch thins and dies.
- * The defaults are chosen; each preset says where its own come from.
+ * 158: 75-89). It rises with light: from 1, where shoots just replace themselves, at {@link compensation_light}, to the
+ * gross yield of the unit the shoot grew on at {@link saturation_light}, flat above, and below 1 in deeper shade, where a
+ * branch thins and dies. So in full light a shoot keeps every shoot its buds grow (`shoot_expected_yield`), and only
+ * shade sheds them. The defaults are chosen; each preset says where its own come from.
  */
 export class ShootGrowthConfig {
     /**
-     * Length (m) the leader grows a year. It dates the framework: every branch elongates at this rate from when its
-     * parent's growth reached where it joins, so the tree is as old as its longest path from the base took to grow.
+     * Length (m) the leader grows a year once the tree is tall, {@link leader_unit}. It dates the framework: every
+     * branch elongates at this rate from when its parent's growth reached where it joins, so the framework is as old as
+     * its longest path from the base took to grow.
      * @type {number}
      */
     leader_growth = 0.3;
 
     /**
-     * Net shoots a shoot leaves a year in full light (Rb at or above {@link saturation_light}).
+     * How far below {@link leader_growth} a seedling's leader grows: at height 0 the leader grows `leader_growth / (1 +
+     * leader_onset)` a year (see {@link leader_unit}). 0 grows it at `leader_growth` from the first year.
      * @type {number}
      */
-    vigour = 1.5;
+    leader_onset = 0;
+
+    /**
+     * Height (m) over which the leader's shortfall below {@link leader_growth} falls by `e` (see {@link leader_unit}).
+     * @type {number}
+     */
+    leader_height_scale = 1;
+
+    /**
+     * Seasons the tree grows. The framework the generator graph lays is as old as it took to grow
+     * ({@link leader_growth}); a tree older than that grows on, its framework's tips extending as shoots for the seasons
+     * left. 0 grows no longer than the framework took.
+     * @type {number}
+     */
+    age = 0;
+
+    /**
+     * Apical control `λ` of the Borchert-Honda allocation (Borchert & Honda 1984; Palubicki et al. 2009, ACM Trans.
+     * Graph. 28(3): 58): the light a tree's shoots receive is summed down to its base and shared back up, and at each
+     * node the axis that goes on takes a share weighted `λ`, its laterals `1 - λ`. A shoot grows its demographic
+     * length times the vigour it receives per unit of its own light, relative to the most vigorous shoot's. 0.5 shares
+     * by light alone, which gives every shoot the same: the demography's lengths unchanged.
+     * @type {number}
+     */
+    apical_control = 0.5;
 
     /**
      * Relative irradiance (1 under open sky) at which a shoot just replaces itself: Rb = 1.
@@ -52,14 +80,27 @@ export class ShootGrowthConfig {
     light_cell = 0.25;
 
     /**
-     * Net shoots a shoot leaves a year at relative irradiance `light`.
+     * Length (m) the leader of a tree `height` metres tall grows in a year: the logistic `leader_growth / (1 +
+     * leader_onset exp(-height / leader_height_scale))` by which Flower-Ellis et al. (1976) hold a young tree's height
+     * growth to its height (Kellomäki & Kurttio 1991, For. Ecol. Manage. 43: 103-123, Eq. 6).
+     * @param {number} height
+     * @returns {number}
+     */
+    leader_unit(height) {
+        return this.leader_growth / (1 + this.leader_onset * Math.exp(-Math.max(0, height) / this.leader_height_scale));
+    }
+
+    /**
+     * Net shoots a shoot leaves a year at relative irradiance `light`, where in full light it would keep all `gross`
+     * of the new shoots its buds grow.
      * @param {number} light
+     * @param {number} gross new shoots its buds grow a year
      * @returns {number}
      */
-    net_yield(light) {
+    net_yield(light, gross) {
         const span = Math.max(1e-6, this.saturation_light - this.compensation_light);
-        const slope = (this.vigour - 1) / span;
-        return Math.max(0, Math.min(this.vigour, 1 + (light - this.compensation_light) * slope));
+        const slope = (gross - 1) / span;
+        return Math.max(0, Math.min(gross, 1 + (light - this.compensation_light) * slope));
     }
 
     /**
@@ -81,7 +122,10 @@ export class ShootGrowthConfig {
             return this;
         }
         if (overrides.leader_growth !== undefined) this.leader_growth = Math.max(0.01, overrides.leader_growth);
-        if (overrides.vigour !== undefined) this.vigour = Math.max(0, overrides.vigour);
+        if (overrides.leader_onset !== undefined) this.leader_onset = Math.max(0, overrides.leader_onset);
+        if (overrides.leader_height_scale !== undefined) this.leader_height_scale = Math.max(1e-3, overrides.leader_height_scale);
+        if (overrides.age !== undefined) this.age = Math.max(0, overrides.age | 0);
+        if (overrides.apical_control !== undefined) this.apical_control = Math.min(0.999, Math.max(0.001, overrides.apical_control));
         if (overrides.compensation_light !== undefined) this.compensation_light = Math.min(1, Math.max(0, overrides.compensation_light));
         if (overrides.saturation_light !== undefined) this.saturation_light = Math.min(1, Math.max(0, overrides.saturation_light));
         if (overrides.leaf_clumping !== undefined) this.leaf_clumping = Math.min(1, Math.max(0, overrides.leaf_clumping));
@@ -96,7 +140,10 @@ export class ShootGrowthConfig {
     copy(other) {
         assert.defined(other, 'other');
         this.leader_growth = other.leader_growth;
-        this.vigour = other.vigour;
+        this.leader_onset = other.leader_onset;
+        this.leader_height_scale = other.leader_height_scale;
+        this.age = other.age;
+        this.apical_control = other.apical_control;
         this.compensation_light = other.compensation_light;
         this.saturation_light = other.saturation_light;
         this.leaf_clumping = other.leaf_clumping;
@@ -119,7 +166,10 @@ export class ShootGrowthConfig {
         if (this === other) return true;
         if (!other || !other.isShootGrowthConfig) return false;
         return this.leader_growth === other.leader_growth
-            && this.vigour === other.vigour
+            && this.leader_onset === other.leader_onset
+            && this.leader_height_scale === other.leader_height_scale
+            && this.age === other.age
+            && this.apical_control === other.apical_control
             && this.compensation_light === other.compensation_light
             && this.saturation_light === other.saturation_light
             && this.leaf_clumping === other.leaf_clumping
@@ -130,7 +180,11 @@ export class ShootGrowthConfig {
      * @returns {number}
      */
     hash() {
-        let h = hash_mix2(computeHashFloat(this.leader_growth), computeHashFloat(this.vigour));
+        let h = computeHashFloat(this.leader_growth);
+        h = hash_mix2(h, computeHashFloat(this.leader_onset));
+        h = hash_mix2(h, computeHashFloat(this.leader_height_scale));
+        h = hash_mix2(h, this.age);
+        h = hash_mix2(h, computeHashFloat(this.apical_control));
         h = hash_mix2(h, computeHashFloat(this.compensation_light));
         h = hash_mix2(h, computeHashFloat(this.saturation_light));
         h = hash_mix2(h, computeHashFloat(this.leaf_clumping));

package/src/generation/foliage/config/ShootSystemRule.d.ts

@@ -1,7 +1,7 @@
 /**
- * Peripheral shoot system edge of the generator graph: every living branch grown by generator `source` carries a
- * twig system grown year by year from its own buds, each axis of which is a branch of generator `target` (see
- * `tree_skeleton_grow_shoots`).
+ * Shoot system edge of the generator graph: every living branch grown by generator `source` carries a shoot system
+ * grown year by year from its own buds, each lateral a branch of the generator `target` names for its mother's order;
+ * the branch grows on from its tip when the tree is older than it (see `tree_skeleton_grow_shoots`).
  *
  * The model is the oak's [BB2000, BB1998], generalised: each year every living axis grows a terminal extension unit,
  * and the buds on its units grow into long shoots (the spring after, or the same season), short shoots, or nothing,
@@ -27,11 +27,11 @@ export class ShootSystemRule {
      */
     source: number;
     /**
-     * Generator index of the long shoots, which shapes how they look (radial segments, bark, tropisms). Greater than
-     * `source`.
-     * @type {number}
+     * Generator index of the long shoots grown on a mother of each order, which shapes how they look (radial segments,
+     * bark, tropisms). Each greater than `source`. A carrier's own extension keeps the carrier's generator.
+     * @type {number[]}
      */
-    target: number;
+    target: number[];
     /**
      * Generator index of the short shoots, so foliage rules can tell them apart (`FoliageSpawnRule.short_shoot`).
      * Greater than `source`. Used by zones whose buds grow short shoots.
@@ -75,12 +75,12 @@ export class ShootSystemRule {
      */
     length_negative_binomial_p: number[];
     /**
-     * Mean length (m) of an extension unit, at which a living shoot's yield of new shoots is counted
-     * ({@link shoot_expected_yield}), and against which a shoot's length ranks it for shedding: 5.9 cm on branch o1b1
-     * [BB2000 Table 4], where oak's outgrowth shares were counted.
-     * @type {number}
+     * Mean length (m) of an extension unit per order of the axis, at which a living shoot's yield of new shoots is
+     * counted ({@link shoot_expected_yield}), and against which a shoot's length ranks it for shedding: 5.9 cm on branch
+     * o1b1 [BB2000 Table 4], where oak's outgrowth shares were counted.
+     * @type {number[]}
      */
-    mean_unit_length: number;
+    mean_unit_length: number[];
     /**
      * Lateral bud zones along an extension unit. Oak's: the pseudo-whorl of "almost always four" subapical buds at
      * 0.8-0.99 of the unit [BB2000 p. 7, 11, 17], 1.17 of which grow out on branch o1b1 [BB2000 p. 11]; and the

package/src/generation/foliage/config/ShootSystemRule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShootSystemRule.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/ShootSystemRule.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;GAgBG;AACH;IAyHI;;;OAGG;IACH,sBAHW,QAAQ,eAAe,CAAC,GACtB,eAAe,CAM3B;IAhID;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,QAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,WAFU,MAAM,CAEU;IAE1B;;;;;OAKG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,iBAFU,MAAM,EAAE,CAEuB;IAEzC;;;;;OAKG;IACH,uBAFU,MAAM,EAAE,CAEU;IAE5B;;;OAGG;IACH,iBAFU,MAAM,EAAE,CAEsB;IAExC;;;;OAIG;IACH,4BAFU,MAAM,EAAE,CAEwB;IAE1C;;;;;OAKG;IACH,kBAFU,MAAM,CAES;IAEzB;;;;;;;OAOG;IACH,OAFU,YAAY,EAAE,CAkBtB;IAEF;;;OAGG;IACH,oBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,sBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,iBAFU,MAAM,EAAE,CAEO;IAEzB;;;OAGG;IACH,kBAFU,eAAe,GAAC,MAAM,CAEgB;IAYhD;;;OAGG;IACH,2BAHW,QAAQ,eAAe,CAAC,GACtB,IAAI,CA4BhB;IAED;;;OAGG;IACH,YAHW,eAAe,GACb,IAAI,CAoBhB;IAED;;OAEG;IACH,SAFa,eAAe,CAM3B;IAED;;;OAGG;IACH,cAHW,eAAe,GACb,OAAO,CAuBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAoBlB;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;6BApS4B,mBAAmB;gCADhB,sBAAsB"}
+{"version":3,"file":"ShootSystemRule.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/ShootSystemRule.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;GAgBG;AACH;IAyHI;;;OAGG;IACH,sBAHW,QAAQ,eAAe,CAAC,GACtB,eAAe,CAM3B;IAhID;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;;OAIG;IACH,QAFU,MAAM,EAAE,CAEL;IAEb;;;;OAIG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,WAFU,MAAM,CAEU;IAE1B;;;;;OAKG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,iBAFU,MAAM,EAAE,CAEuB;IAEzC;;;;;OAKG;IACH,uBAFU,MAAM,EAAE,CAEU;IAE5B;;;OAGG;IACH,iBAFU,MAAM,EAAE,CAEsB;IAExC;;;;OAIG;IACH,4BAFU,MAAM,EAAE,CAEwB;IAE1C;;;;;OAKG;IACH,kBAFU,MAAM,EAAE,CAES;IAE3B;;;;;;;OAOG;IACH,OAFU,YAAY,EAAE,CAkBtB;IAEF;;;OAGG;IACH,oBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,sBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,iBAFU,MAAM,EAAE,CAEO;IAEzB;;;OAGG;IACH,kBAFU,eAAe,GAAC,MAAM,CAEgB;IAYhD;;;OAGG;IACH,2BAHW,QAAQ,eAAe,CAAC,GACtB,IAAI,CAgChB;IAED;;;OAGG;IACH,YAHW,eAAe,GACb,IAAI,CAoBhB;IAED;;OAEG;IACH,SAFa,eAAe,CAM3B;IAED;;;OAGG;IACH,cAHW,eAAe,GACb,OAAO,CAuBnB;IAED;;OAEG;IACH,QAFa,MAAM,CAoBlB;IAGL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;6BAxS4B,mBAAmB;gCADhB,sBAAsB"}

package/src/generation/foliage/config/ShootSystemRule.js

@@ -35,9 +35,9 @@ function oak_by_order(value, offset) {
 }
 
 /**
- * Peripheral shoot system edge of the generator graph: every living branch grown by generator `source` carries a
- * twig system grown year by year from its own buds, each axis of which is a branch of generator `target` (see
- * `tree_skeleton_grow_shoots`).
+ * Shoot system edge of the generator graph: every living branch grown by generator `source` carries a shoot system
+ * grown year by year from its own buds, each lateral a branch of the generator `target` names for its mother's order;
+ * the branch grows on from its tip when the tree is older than it (see `tree_skeleton_grow_shoots`).
  *
  * The model is the oak's [BB2000, BB1998], generalised: each year every living axis grows a terminal extension unit,
  * and the buds on its units grow into long shoots (the spring after, or the same season), short shoots, or nothing,
@@ -59,11 +59,11 @@ export class ShootSystemRule {
     source = 2;
 
     /**
-     * Generator index of the long shoots, which shapes how they look (radial segments, bark, tropisms). Greater than
-     * `source`.
-     * @type {number}
+     * Generator index of the long shoots grown on a mother of each order, which shapes how they look (radial segments,
+     * bark, tropisms). Each greater than `source`. A carrier's own extension keeps the carrier's generator.
+     * @type {number[]}
      */
-    target = 3;
+    target = [3];
 
     /**
      * Generator index of the short shoots, so foliage rules can tell them apart (`FoliageSpawnRule.short_shoot`).
@@ -115,12 +115,12 @@ export class ShootSystemRule {
     length_negative_binomial_p = [0.58, 0.60];
 
     /**
-     * Mean length (m) of an extension unit, at which a living shoot's yield of new shoots is counted
-     * ({@link shoot_expected_yield}), and against which a shoot's length ranks it for shedding: 5.9 cm on branch o1b1
-     * [BB2000 Table 4], where oak's outgrowth shares were counted.
-     * @type {number}
+     * Mean length (m) of an extension unit per order of the axis, at which a living shoot's yield of new shoots is
+     * counted ({@link shoot_expected_yield}), and against which a shoot's length ranks it for shedding: 5.9 cm on branch
+     * o1b1 [BB2000 Table 4], where oak's outgrowth shares were counted.
+     * @type {number[]}
      */
-    mean_unit_length = 0.059;
+    mean_unit_length = [0.059];
 
     /**
      * Lateral bud zones along an extension unit. Oak's: the pseudo-whorl of "almost always four" subapical buds at
@@ -191,7 +191,11 @@ export class ShootSystemRule {
             return this;
         }
         if (overrides.source !== undefined) this.source = overrides.source | 0;
-        if (overrides.target !== undefined) this.target = overrides.target | 0;
+        if (overrides.target !== undefined) {
+            assert.isArray(overrides.target, 'target');
+            assert.greaterThan(overrides.target.length, 0, 'target.length');
+            this.target = overrides.target.map(t => t | 0);
+        }
         if (overrides.short_target !== undefined) this.short_target = overrides.short_target | 0;
         if (overrides.max_order !== undefined) this.max_order = Math.max(1, overrides.max_order | 0);
         if (overrides.carrier_order !== undefined) this.carrier_order = Math.max(1, overrides.carrier_order | 0);
@@ -202,7 +206,7 @@ export class ShootSystemRule {
             assert.isArray(overrides.length_negative_binomial_p, 'length_negative_binomial_p');
             this.length_negative_binomial_p = overrides.length_negative_binomial_p.map(p => Math.min(0.999, Math.max(0.001, p)));
         }
-        if (overrides.mean_unit_length !== undefined) this.mean_unit_length = Math.max(1e-3, overrides.mean_unit_length);
+        if (overrides.mean_unit_length !== undefined) this.mean_unit_length = list(overrides.mean_unit_length, 1e-3);
         if (overrides.zones !== undefined) {
             assert.isArray(overrides.zones, 'zones');
             this.zones = overrides.zones.map(z => ShootBudZone.from(z));
@@ -221,7 +225,7 @@ export class ShootSystemRule {
     copy(other) {
         assert.defined(other, 'other');
         this.source = other.source;
-        this.target = other.target;
+        this.target = other.target.slice();
         this.short_target = other.short_target;
         this.max_order = other.max_order;
         this.carrier_order = other.carrier_order;
@@ -229,7 +233,7 @@ export class ShootSystemRule {
         this.terminal_length_slope = other.terminal_length_slope.slice();
         this.max_unit_length = other.max_unit_length.slice();
         this.length_negative_binomial_p = other.length_negative_binomial_p.slice();
-        this.mean_unit_length = other.mean_unit_length;
+        this.mean_unit_length = other.mean_unit_length.slice();
         this.zones = other.zones.map(z => z.clone());
         this.short_shoot_growth = other.short_shoot_growth;
         this.short_shoot_survival = other.short_shoot_survival;
@@ -259,7 +263,7 @@ export class ShootSystemRule {
             if (!this.zones[i].equals(other.zones[i])) return false;
         }
         return this.source === other.source
-            && this.target === other.target
+            && isArrayEqualStrict(this.target, other.target)
             && this.short_target === other.short_target
             && this.max_order === other.max_order
             && this.carrier_order === other.carrier_order
@@ -267,7 +271,7 @@ export class ShootSystemRule {
             && isArrayEqualStrict(this.terminal_length_slope, other.terminal_length_slope)
             && isArrayEqualStrict(this.max_unit_length, other.max_unit_length)
             && isArrayEqualStrict(this.length_negative_binomial_p, other.length_negative_binomial_p)
-            && this.mean_unit_length === other.mean_unit_length
+            && isArrayEqualStrict(this.mean_unit_length, other.mean_unit_length)
             && this.short_shoot_growth === other.short_shoot_growth
             && this.short_shoot_survival === other.short_shoot_survival
             && isArrayEqualStrict(this.insertion_angle, other.insertion_angle)
@@ -278,7 +282,7 @@ export class ShootSystemRule {
      * @returns {number}
      */
     hash() {
-        let h = hash_mix2(this.source, this.target);
+        let h = hash_mix2(this.source, computeHashFloatArray(this.target));
         h = hash_mix2(h, this.short_target);
         h = hash_mix2(h, this.max_order);
         h = hash_mix2(h, this.carrier_order);
@@ -286,7 +290,7 @@ export class ShootSystemRule {
         h = hash_mix2(h, computeHashFloatArray(this.terminal_length_slope));
         h = hash_mix2(h, computeHashFloatArray(this.max_unit_length));
         h = hash_mix2(h, computeHashFloatArray(this.length_negative_binomial_p));
-        h = hash_mix2(h, computeHashFloat(this.mean_unit_length));
+        h = hash_mix2(h, computeHashFloatArray(this.mean_unit_length));
         for (let i = 0; i < this.zones.length; i++) {
             h = hash_mix2(h, this.zones[i].hash());
         }

package/src/generation/foliage/config/TreeGrowth.d.ts

@@ -0,0 +1,10 @@
+/**
+ * How a tree is grown. Both front ends grow the same `TreeSkeleton` and its leaves, which the rest of the pipeline
+ * draws alike (`TWO_FRONT_ENDS_BRIEF_2026_10_28.md`).
+ */
+export type TreeGrowth = string;
+export namespace TreeGrowth {
+    let Graph: string;
+    let Botanical: string;
+}
+//# sourceMappingURL=TreeGrowth.d.ts.map

package/src/generation/foliage/config/TreeGrowth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeGrowth.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/TreeGrowth.js"],"names":[],"mappings":";;;;yBAKU,MAAM"}

package/src/generation/foliage/config/TreeGrowth.js

@@ -0,0 +1,18 @@
+/**
+ * How a tree is grown. Both front ends grow the same `TreeSkeleton` and its leaves, which the rest of the pipeline
+ * draws alike (`TWO_FRONT_ENDS_BRIEF_2026_10_28.md`).
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const TreeGrowth = {
+    /**
+     * The framework of the generator graph alone (`tree_skeleton_grow_framework`): for real-time trees.
+     */
+    Graph: "graph",
+    /**
+     * The framework, then every shoot system on it, year by year in the crown's light (`tree_skeleton_grow`): for
+     * trees seen up close.
+     */
+    Botanical: "botanical",
+};

package/src/generation/foliage/config/TreeLODConfig.d.ts

@@ -1,5 +1,17 @@
 /**
- * Level-of-Detail (LOD) decimation and area-compensation configuration.
+ * Geometric error (m) of the finest LOD by default, and where `tree_lod_plan` starts looking for each tree's own:
+ * `generate_tree` draws each LOD at the finest error its `TREE_RENDER_COST_CEILING` allows. Chosen.
+ * @type {number}
+ */
+export const TREE_LOD_ERROR_FINEST: number;
+/**
+ * Ratio between consecutive errors a tree is cut at (`tree_lod_plan`'s search, a species' prototypes): each a
+ * half-octave coarser than the last.
+ * @type {number}
+ */
+export const TREE_LOD_ERROR_STEP: number;
+/**
+ * A level of detail: the tree drawn to a geometric error.
  */
 export class TreeLODConfig {
     /**
@@ -8,53 +20,24 @@ export class TreeLODConfig {
      */
     static from(options?: Partial<TreeLODConfig>): TreeLODConfig;
     /**
-     * Creates a default sequence of progressive LOD configurations.
+     * A chain of LODs, each drawn to twice the error of the one before, from `error` at level 0: each switches at twice
+     * the distance of the one before, at the same error on screen.
      * @param {number} [lod_count=3]
+     * @param {number} [error] m, of level 0
      * @returns {TreeLODConfig[]}
      */
-    static createDefaultChain(lod_count?: number): TreeLODConfig[];
+    static createDefaultChain(lod_count?: number, error?: number): TreeLODConfig[];
     /**
      * LOD index (0 = highest detail).
      * @type {number}
      */
     level: number;
     /**
-     * Multiplier in (0, 1] applied to radial ring segment counts (clamped >= 3).
-     * @type {number}
-     */
-    radial_scale: number;
-    /**
-     * Multiplier in (0, 1] applied to longitudinal Hermite spine subdivisions (clamped >= 1).
-     * @type {number}
-     */
-    longitudinal_scale: number;
-    /**
-     * Maximum branch recursion level retained in this LOD.
-     * @type {number}
-     */
-    max_branch_level: number;
-    /**
-     * Minimum branch base radius (meters) retained in this LOD.
-     * @type {number}
-     */
-    min_branch_radius: number;
-    /**
-     * Fraction in [0, 1] of foliage attachments retained via golden-ratio low-discrepancy rank.
+     * Geometric error (m) the LOD is drawn to: wood thinner than this is not drawn as a tube, and the bark's rings and
+     * their sides are as few as keep the surface within it (`tree_mesh_build_bark`).
      * @type {number}
      */
-    foliage_keep_ratio: number;
-    /**
-     * Area-compensation exponent eta in [0, 0.5]: remaining cards scale by `keep_ratio^(-eta)`
-     * so optical canopy density stays invariant across LOD transitions.
-     * @type {number}
-     */
-    foliage_area_compensation_exponent: number;
-    /**
-     * If true, complex cards (`TriStarCluster`, `RibbedFrond`, `CutoutHull`) collapse
-     * to simpler low-triangle `FoldedVCard` or single quad representations.
-     * @type {boolean}
-     */
-    simplify_cards: boolean;
+    error: number;
     /**
      * @param {Partial<TreeLODConfig>} [overrides]
      * @returns {this}

package/src/generation/foliage/config/TreeLODConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TreeLODConfig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/TreeLODConfig.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAmDI;;;OAGG;IACH,sBAHW,QAAQ,aAAa,CAAC,GACpB,aAAa,CAMzB;IAED;;;;OAIG;IACH,sCAHW,MAAM,GACJ,aAAa,EAAE,CAuD3B;IAtHD;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,oBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;OAGG;IACH,mBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,oBAFU,MAAM,CAES;IAEzB;;;;OAIG;IACH,oCAFU,MAAM,CAE0B;IAE1C;;;;OAIG;IACH,gBAFU,OAAO,CAEM;IAwEvB;;;OAGG;IACH,2BAHW,QAAQ,aAAa,CAAC,GACpB,IAAI,CAiBhB;IAED;;;OAGG;IACH,YAHW,aAAa,GACX,IAAI,CAahB;IAED;;OAEG;IACH,SAFa,aAAa,CAMzB;IAED;;;OAGG;IACH,cAHW,aAAa,GACX,OAAO,CAanB;IAED;;OAEG;IACH,QAFa,MAAM,CAUlB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC"}
+{"version":3,"file":"TreeLODConfig.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/config/TreeLODConfig.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,oCAFU,MAAM,CAE0B;AAE1C;;;;GAIG;AACH,kCAFU,MAAM,CAE8B;AAE9C;;GAEG;AACH;IAcI;;;OAGG;IACH,sBAHW,QAAQ,aAAa,CAAC,GACpB,aAAa,CAMzB;IAED;;;;;;OAMG;IACH,sCAJW,MAAM,UACN,MAAM,GACJ,aAAa,EAAE,CAY3B;IAxCD;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,OAFU,MAAM,CAEc;IA+B9B;;;OAGG;IACH,2BAHW,QAAQ,aAAa,CAAC,GACpB,IAAI,CAYhB;IAED;;;OAGG;IACH,YAHW,aAAa,GACX,IAAI,CAOhB;IAED;;OAEG;IACH,SAFa,aAAa,CAMzB;IAED;;;OAGG;IACH,cAHW,aAAa,GACX,OAAO,CAOnB;IAED;;OAEG;IACH,QAFa,MAAM,CAKlB;IAGL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CANtC"}

package/src/generation/foliage/config/TreeLODConfig.js

@@ -3,7 +3,21 @@ import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
 import { computeHashFloat } from "../../../core/primitives/numbers/computeHashFloat.js";
 
 /**
- * Level-of-Detail (LOD) decimation and area-compensation configuration.
+ * Geometric error (m) of the finest LOD by default, and where `tree_lod_plan` starts looking for each tree's own:
+ * `generate_tree` draws each LOD at the finest error its `TREE_RENDER_COST_CEILING` allows. Chosen.
+ * @type {number}
+ */
+export const TREE_LOD_ERROR_FINEST = 0.01;
+
+/**
+ * Ratio between consecutive errors a tree is cut at (`tree_lod_plan`'s search, a species' prototypes): each a
+ * half-octave coarser than the last.
+ * @type {number}
+ */
+export const TREE_LOD_ERROR_STEP = Math.SQRT2;
+
+/**
+ * A level of detail: the tree drawn to a geometric error.
  */
 export class TreeLODConfig {
     /**
@@ -13,48 +27,11 @@ export class TreeLODConfig {
     level = 0;
 
     /**
-     * Multiplier in (0, 1] applied to radial ring segment counts (clamped >= 3).
-     * @type {number}
-     */
-    radial_scale = 1.0;
-
-    /**
-     * Multiplier in (0, 1] applied to longitudinal Hermite spine subdivisions (clamped >= 1).
-     * @type {number}
-     */
-    longitudinal_scale = 1.0;
-
-    /**
-     * Maximum branch recursion level retained in this LOD.
-     * @type {number}
-     */
-    max_branch_level = 3;
-
-    /**
-     * Minimum branch base radius (meters) retained in this LOD.
-     * @type {number}
-     */
-    min_branch_radius = 0.0;
-
-    /**
-     * Fraction in [0, 1] of foliage attachments retained via golden-ratio low-discrepancy rank.
+     * Geometric error (m) the LOD is drawn to: wood thinner than this is not drawn as a tube, and the bark's rings and
+     * their sides are as few as keep the surface within it (`tree_mesh_build_bark`).
      * @type {number}
      */
-    foliage_keep_ratio = 1.0;
-
-    /**
-     * Area-compensation exponent eta in [0, 0.5]: remaining cards scale by `keep_ratio^(-eta)`
-     * so optical canopy density stays invariant across LOD transitions.
-     * @type {number}
-     */
-    foliage_area_compensation_exponent = 0.42;
-
-    /**
-     * If true, complex cards (`TriStarCluster`, `RibbedFrond`, `CutoutHull`) collapse
-     * to simpler low-triangle `FoldedVCard` or single quad representations.
-     * @type {boolean}
-     */
-    simplify_cards = false;
+    error = TREE_LOD_ERROR_FINEST;
 
     /**
      * @param {Partial<TreeLODConfig>} [options]
@@ -67,60 +44,19 @@ export class TreeLODConfig {
     }
 
     /**
-     * Creates a default sequence of progressive LOD configurations.
+     * A chain of LODs, each drawn to twice the error of the one before, from `error` at level 0: each switches at twice
+     * the distance of the one before, at the same error on screen.
      * @param {number} [lod_count=3]
+     * @param {number} [error] m, of level 0
      * @returns {TreeLODConfig[]}
      */
-    static createDefaultChain(lod_count = 3) {
+    static createDefaultChain(lod_count = 3, error = TREE_LOD_ERROR_FINEST) {
         const count = Math.max(1, lod_count | 0);
-        const presets = [
-            {
-                level: 0,
-                radial_scale: 1.0,
-                longitudinal_scale: 1.0,
-                max_branch_level: 3,
-                min_branch_radius: 0.0,
-                foliage_keep_ratio: 1.0,
-                foliage_area_compensation_exponent: 0.42,
-                simplify_cards: false
-            },
-            {
-                level: 1,
-                radial_scale: 0.65,
-                longitudinal_scale: 0.7,
-                max_branch_level: 2,
-                min_branch_radius: 0.015,
-                foliage_keep_ratio: 0.55,
-                foliage_area_compensation_exponent: 0.42,
-                simplify_cards: false
-            },
-            {
-                level: 2,
-                radial_scale: 0.45,
-                longitudinal_scale: 0.5,
-                max_branch_level: 1,
-                min_branch_radius: 0.035,
-                foliage_keep_ratio: 0.28,
-                foliage_area_compensation_exponent: 0.44,
-                simplify_cards: true
-            },
-            {
-                level: 3,
-                radial_scale: 0.35,
-                longitudinal_scale: 0.35,
-                max_branch_level: 1,
-                min_branch_radius: 0.06,
-                foliage_keep_ratio: 0.15,
-                foliage_area_compensation_exponent: 0.46,
-                simplify_cards: true
-            }
-        ];
-
         const result = [];
         for (let i = 0; i < count; i++) {
-            const template = presets[Math.min(i, presets.length - 1)];
-            const cfg = TreeLODConfig.from(template);
+            const cfg = new TreeLODConfig();
             cfg.level = i;
+            cfg.error = error * Math.pow(2, i);
             result.push(cfg);
         }
         return result;
@@ -135,15 +71,10 @@ export class TreeLODConfig {
             return this;
         }
         if (overrides.level !== undefined) this.level = overrides.level | 0;
-        if (overrides.radial_scale !== undefined) this.radial_scale = overrides.radial_scale;
-        if (overrides.longitudinal_scale !== undefined) this.longitudinal_scale = overrides.longitudinal_scale;
-        if (overrides.max_branch_level !== undefined) this.max_branch_level = overrides.max_branch_level | 0;
-        if (overrides.min_branch_radius !== undefined) this.min_branch_radius = overrides.min_branch_radius;
-        if (overrides.foliage_keep_ratio !== undefined) this.foliage_keep_ratio = overrides.foliage_keep_ratio;
-        if (overrides.foliage_area_compensation_exponent !== undefined) {
-            this.foliage_area_compensation_exponent = overrides.foliage_area_compensation_exponent;
+        if (overrides.error !== undefined) {
+            assert.greaterThan(overrides.error, 0, 'error');
+            this.error = overrides.error;
         }
-        if (overrides.simplify_cards !== undefined) this.simplify_cards = Boolean(overrides.simplify_cards);
         return this;
     }
 
@@ -154,13 +85,7 @@ export class TreeLODConfig {
     copy(other) {
         assert.defined(other, 'other');
         this.level = other.level;
-        this.radial_scale = other.radial_scale;
-        this.longitudinal_scale = other.longitudinal_scale;
-        this.max_branch_level = other.max_branch_level;
-        this.min_branch_radius = other.min_branch_radius;
-        this.foliage_keep_ratio = other.foliage_keep_ratio;
-        this.foliage_area_compensation_exponent = other.foliage_area_compensation_exponent;
-        this.simplify_cards = other.simplify_cards;
+        this.error = other.error;
         return this;
     }
 
@@ -181,25 +106,14 @@ export class TreeLODConfig {
         if (this === other) return true;
         if (!other || !other.isTreeLODConfig) return false;
         return this.level === other.level
-            && this.radial_scale === other.radial_scale
-            && this.longitudinal_scale === other.longitudinal_scale
-            && this.max_branch_level === other.max_branch_level
-            && this.min_branch_radius === other.min_branch_radius
-            && this.foliage_keep_ratio === other.foliage_keep_ratio
-            && this.foliage_area_compensation_exponent === other.foliage_area_compensation_exponent
-            && this.simplify_cards === other.simplify_cards;
+            && this.error === other.error;
     }
 
     /**
      * @returns {number}
      */
     hash() {
-        let h = hash_mix2(this.level, this.max_branch_level);
-        h = hash_mix2(h, computeHashFloat(this.radial_scale));
-        h = hash_mix2(h, computeHashFloat(this.longitudinal_scale));
-        h = hash_mix2(h, computeHashFloat(this.min_branch_radius));
-        h = hash_mix2(h, computeHashFloat(this.foliage_keep_ratio));
-        h = hash_mix2(h, this.simplify_cards ? 1 : 0);
+        let h = hash_mix2(this.level, computeHashFloat(this.error));
         return h;
     }
 }

package/src/generation/foliage/config/TreeSpeciesConfig.d.ts

@@ -66,7 +66,8 @@ export class TreeSpeciesConfig {
      */
     shoot_rules: ShootSystemRule[];
     /**
-     * How the twig systems of `shoot_rules` grow together: seasons, and vigour in the light they make for each other.
+     * How the shoot systems of `shoot_rules` grow together: the tree's age, its leader, and their vigour in the light they
+     * make for each other.
      * @type {ShootGrowthConfig}
      */
     shoot_growth: ShootGrowthConfig;