@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -0,0 +1,155 @@
+/**
+ * @typedef {Object} TreeShootPrototype
+ * @property {number} generator its carrier's generator, a shoot rule's `source`
+ * @property {number} carrier the framework branch it grew on
+ * @property {number} length m, its carrier's in the framework: what a carrier it is drawn on is scaled against
+ * @property {number} first its carrier's branch in `TreeShootPrototypes.sheet`; its shoots follow it
+ * @property {number} branch_count its branches in the sheet, from `first`
+ * @property {Array<{parent: number, t: number, leaf_area: number, reach: number}>} carried each shoot system on it that
+ *           no LOD draws as wood, hanging from drawn wood: the sheet branch and `t_norm` it hangs from, its one-sided leaf
+ *           area (m^2) and how far it reaches from there (m), as the wind's mechanics weigh them
+ */
+/**
+ * @typedef {Object} TreeShootPrototypes
+ * @property {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species the species as its prototypes grew,
+ *           at {@link PROTOTYPE_SEED}
+ * @property {TreeSkeleton} framework the species' framework, grown by its generator graph alone
+ * @property {TreeShootPrototype[]} prototypes
+ * @property {Map<number, {lengths: Float64Array, low: number, high: number}>} carriers per carrier generator, its
+ *           carriers' lengths (ascending), and the scale a prototype may be drawn at, its leaves' own spread
+ *           (`foliage_scale_spread`)
+ * @property {TreeSkeleton} sheet every prototype where it grew on the framework, under the framework's crown frame
+ * @property {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments the sheet's leaves
+ * @property {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} leaves every leaf's card
+ * @property {number} side_area m^2, every prototype's grown side area together
+ * @property {number[]} errors m, each error the sheet was cut at: {@link TREE_LOD_ERROR_STEP} apart from
+ *           {@link TREE_LOD_ERROR_FINEST} to the first that draws no wood, every prototype one cut
+ * @property {ReturnType<typeof tree_cluster_atlas>|null} atlas their cuts at every error, drawn with a few tiles, as
+ *           large as the texture ceiling affords over {@link side_area}
+ * @property {Uint8Array} drawn per sheet branch, whether any LOD draws it as wood: the finest error does, and so does
+ *           its parent; a carrier always is
+ * @property {Int32Array} prototype_of per sheet branch, its prototype
+ * @property {Int32Array[]} owners per error, each card's prototype
+ */
+/**
+ * A species' shoot prototypes (TWO_FRONT_ENDS_BRIEF_2026_10_28.md, G1): the shoot systems its shoot rules grow, grown
+ * once, by the botanical front end, on carriers of its own framework, and cut and baked into one atlas. A tree grown by
+ * its generator graph draws them on its carriers (G3).
+ *
+ * - **Where.** Each grows on a carrier of the framework the species' graph grows, in place: as old as that carrier is
+ *   in the tree, kept out of the framework's wood, in the light of its own leaves alone (`tree_skeleton_grow_shoots_on`).
+ *   It stays there: its leaves are collected, cut and baked where they grew, under the framework's crown frame, as a
+ *   tree's own are.
+ * - **Which.** For each generator the rules grow on, the carrier of median length first. Drawn on a carrier of another
+ *   length, a prototype is scaled by their ratio, and so are its leaves; within the spread of sizes the species' leaves
+ *   already grow to, a scaled leaf is one it grows (`foliage_scale_spread`). Prototypes are added, shortest first, until
+ *   their scaled lengths reach without a gap from the shortest carrier to the longest, each the longest carrier that
+ *   still reaches back to where the last one stopped.
+ * - **Cut.** At every error from the finest to where no wood is drawn, through the same cuts, representatives and bake
+ *   a tree's own LODs take (`tree_cluster_atlas`).
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial} leaf_material
+ *        the species' leaf material (`TreeSpeciesCache.leaves`)
+ * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null} cutout its atlas's shape, `null` for a
+ *        caller's own material, whose cards cover whole tiles
+ * @returns {TreeShootPrototypes}
+ */
+export function tree_shoot_prototypes(species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, leaf_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, cutout: import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout | null): TreeShootPrototypes;
+export type TreeShootPrototype = {
+    /**
+     * its carrier's generator, a shoot rule's `source`
+     */
+    generator: number;
+    /**
+     * the framework branch it grew on
+     */
+    carrier: number;
+    /**
+     * m, its carrier's in the framework: what a carrier it is drawn on is scaled against
+     */
+    length: number;
+    /**
+     * its carrier's branch in `TreeShootPrototypes.sheet`; its shoots follow it
+     */
+    first: number;
+    /**
+     * its branches in the sheet, from `first`
+     */
+    branch_count: number;
+    /**
+     * each shoot system on it that
+     * no LOD draws as wood, hanging from drawn wood: the sheet branch and `t_norm` it hangs from, its one-sided leaf
+     * area (m^2) and how far it reaches from there (m), as the wind's mechanics weigh them
+     */
+    carried: Array<{
+        parent: number;
+        t: number;
+        leaf_area: number;
+        reach: number;
+    }>;
+};
+export type TreeShootPrototypes = {
+    /**
+     * the species as its prototypes grew,
+     * at {@link PROTOTYPE_SEED }
+     */
+    species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig;
+    /**
+     * the species' framework, grown by its generator graph alone
+     */
+    framework: TreeSkeleton;
+    prototypes: TreeShootPrototype[];
+    /**
+     * per carrier generator, its
+     * carriers' lengths (ascending), and the scale a prototype may be drawn at, its leaves' own spread
+     * (`foliage_scale_spread`)
+     */
+    carriers: Map<number, {
+        lengths: Float64Array;
+        low: number;
+        high: number;
+    }>;
+    /**
+     * every prototype where it grew on the framework, under the framework's crown frame
+     */
+    sheet: TreeSkeleton;
+    /**
+     * the sheet's leaves
+     */
+    attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet;
+    /**
+     * every leaf's card
+     */
+    leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry | null;
+    /**
+     * m^2, every prototype's grown side area together
+     */
+    side_area: number;
+    /**
+     * m, each error the sheet was cut at: {@link TREE_LOD_ERROR_STEP } apart from
+     * {@link TREE_LOD_ERROR_FINEST } to the first that draws no wood, every prototype one cut
+     */
+    errors: number[];
+    /**
+     * their cuts at every error, drawn with a few tiles, as
+     * large as the texture ceiling affords over {@link side_area }
+     */
+    atlas: ReturnType<typeof tree_cluster_atlas> | null;
+    /**
+     * per sheet branch, whether any LOD draws it as wood: the finest error does, and so does
+     * its parent; a carrier always is
+     */
+    drawn: Uint8Array;
+    /**
+     * per sheet branch, its prototype
+     */
+    prototype_of: Int32Array;
+    /**
+     * per error, each card's prototype
+     */
+    owners: Int32Array[];
+};
+import { TreeSkeleton } from "../skeleton/TreeSkeleton.js";
+import { tree_cluster_atlas } from "../material/tree_cluster_atlas.js";
+//# sourceMappingURL=tree_shoot_prototypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree_shoot_prototypes.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/tree_shoot_prototypes.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CAPW,OAAO,gCAAgC,EAAE,iBAAiB,iBAC1D,OAAO,2DAA2D,EAAE,qBAAqB,UAEzF,OAAO,mCAAmC,EAAE,kBAAkB,GAAC,IAAI,GAEjE,mBAAmB,CAiJ/B;;;;;eAxMa,MAAM;;;;aACN,MAAM;;;;YACN,MAAM;;;;WACN,MAAM;;;;kBACN,MAAM;;;;;;aACN,MAAM;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC;;;;;;;aAOpE,OAAO,gCAAgC,EAAE,iBAAiB;;;;eAE1D,YAAY;gBACZ,kBAAkB,EAAE;;;;;;cACpB,IAAI,MAAM,EAAE;QAAC,OAAO,EAAE,YAAY,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC;;;;WAG/D,YAAY;;;;iBACZ,OAAO,wCAAwC,EAAE,oBAAoB;;;;YACrE,OAAO,8CAA8C,EAAE,QAAQ,GAAC,IAAI;;;;eACpE,MAAM;;;;;YACN,MAAM,EAAE;;;;;WAER,WAAW,yBAAyB,CAAC,GAAC,IAAI;;;;;WAE1C,UAAU;;;;kBAEV,UAAU;;;;YACV,UAAU,EAAE;;6BA5CG,6BAA6B;mCALvB,mCAAmC"}

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

@@ -0,0 +1,251 @@
+import { TREE_RENDER_COST_CEILING, tree_grown_side_area } from "../analysis/tree_render_cost.js";
+import { TREE_LOD_ERROR_FINEST, TREE_LOD_ERROR_STEP } from "../config/TreeLODConfig.js";
+import { tree_cluster_atlas } from "../material/tree_cluster_atlas.js";
+import { foliage_collect_attachments } from "../mesh/foliage_collect_attachments.js";
+import { foliage_scale_spread } from "../mesh/foliage_scale_spread.js";
+import { tree_mesh_compute_branch_rings } from "../mesh/tree_mesh_build_bark.js";
+import { tree_mesh_build_foliage } from "../mesh/tree_mesh_build_foliage.js";
+import { TreeSkeleton } from "../skeleton/TreeSkeleton.js";
+import { tree_skeleton_compute_segment_mechanics } from "../skeleton/tree_skeleton_compute_joint_mechanics.js";
+import { tree_skeleton_copy_branches } from "../skeleton/tree_skeleton_copy_branches.js";
+import { tree_skeleton_grow_framework } from "../skeleton/tree_skeleton_grow_framework.js";
+import { tree_skeleton_grow_shoots_on } from "../skeleton/tree_skeleton_grow_shoots.js";
+
+/**
+ * The seed a species' prototypes grow from: they are the species', whatever a tree's seed.
+ * @type {number}
+ */
+const PROTOTYPE_SEED = 0;
+
+/**
+ * @typedef {Object} TreeShootPrototype
+ * @property {number} generator its carrier's generator, a shoot rule's `source`
+ * @property {number} carrier the framework branch it grew on
+ * @property {number} length m, its carrier's in the framework: what a carrier it is drawn on is scaled against
+ * @property {number} first its carrier's branch in `TreeShootPrototypes.sheet`; its shoots follow it
+ * @property {number} branch_count its branches in the sheet, from `first`
+ * @property {Array<{parent: number, t: number, leaf_area: number, reach: number}>} carried each shoot system on it that
+ *           no LOD draws as wood, hanging from drawn wood: the sheet branch and `t_norm` it hangs from, its one-sided leaf
+ *           area (m^2) and how far it reaches from there (m), as the wind's mechanics weigh them
+ */
+
+/**
+ * @typedef {Object} TreeShootPrototypes
+ * @property {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species the species as its prototypes grew,
+ *           at {@link PROTOTYPE_SEED}
+ * @property {TreeSkeleton} framework the species' framework, grown by its generator graph alone
+ * @property {TreeShootPrototype[]} prototypes
+ * @property {Map<number, {lengths: Float64Array, low: number, high: number}>} carriers per carrier generator, its
+ *           carriers' lengths (ascending), and the scale a prototype may be drawn at, its leaves' own spread
+ *           (`foliage_scale_spread`)
+ * @property {TreeSkeleton} sheet every prototype where it grew on the framework, under the framework's crown frame
+ * @property {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments the sheet's leaves
+ * @property {import("../../../shade/renderer/geometry/Geometry.js").Geometry|null} leaves every leaf's card
+ * @property {number} side_area m^2, every prototype's grown side area together
+ * @property {number[]} errors m, each error the sheet was cut at: {@link TREE_LOD_ERROR_STEP} apart from
+ *           {@link TREE_LOD_ERROR_FINEST} to the first that draws no wood, every prototype one cut
+ * @property {ReturnType<typeof tree_cluster_atlas>|null} atlas their cuts at every error, drawn with a few tiles, as
+ *           large as the texture ceiling affords over {@link side_area}
+ * @property {Uint8Array} drawn per sheet branch, whether any LOD draws it as wood: the finest error does, and so does
+ *           its parent; a carrier always is
+ * @property {Int32Array} prototype_of per sheet branch, its prototype
+ * @property {Int32Array[]} owners per error, each card's prototype
+ */
+
+/**
+ * A species' shoot prototypes (TWO_FRONT_ENDS_BRIEF_2026_10_28.md, G1): the shoot systems its shoot rules grow, grown
+ * once, by the botanical front end, on carriers of its own framework, and cut and baked into one atlas. A tree grown by
+ * its generator graph draws them on its carriers (G3).
+ *
+ * - **Where.** Each grows on a carrier of the framework the species' graph grows, in place: as old as that carrier is
+ *   in the tree, kept out of the framework's wood, in the light of its own leaves alone (`tree_skeleton_grow_shoots_on`).
+ *   It stays there: its leaves are collected, cut and baked where they grew, under the framework's crown frame, as a
+ *   tree's own are.
+ * - **Which.** For each generator the rules grow on, the carrier of median length first. Drawn on a carrier of another
+ *   length, a prototype is scaled by their ratio, and so are its leaves; within the spread of sizes the species' leaves
+ *   already grow to, a scaled leaf is one it grows (`foliage_scale_spread`). Prototypes are added, shortest first, until
+ *   their scaled lengths reach without a gap from the shortest carrier to the longest, each the longest carrier that
+ *   still reaches back to where the last one stopped.
+ * - **Cut.** At every error from the finest to where no wood is drawn, through the same cuts, representatives and bake
+ *   a tree's own LODs take (`tree_cluster_atlas`).
+ *
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial} leaf_material
+ *        the species' leaf material (`TreeSpeciesCache.leaves`)
+ * @param {import("../material/FoliageAtlasCutout.js").FoliageAtlasCutout|null} cutout its atlas's shape, `null` for a
+ *        caller's own material, whose cards cover whole tiles
+ * @returns {TreeShootPrototypes}
+ */
+export function tree_shoot_prototypes(species, leaf_material, cutout) {
+    const config = species.clone();
+    config.seed = PROTOTYPE_SEED;
+    const framework = tree_skeleton_grow_framework(config);
+
+    // each carrier's shoot systems, grown in place on a framework of its own
+    const grown = new Map();
+    const grow = (carrier) => {
+        let skeleton = grown.get(carrier);
+        if (skeleton === undefined) {
+            skeleton = framework.clone();
+            const on = new Uint8Array(framework.branch_count);
+            on[carrier] = 1;
+            tree_skeleton_grow_shoots_on(skeleton, config, on);
+            grown.set(carrier, skeleton);
+        }
+        return skeleton;
+    };
+
+    const generators = [...new Set(config.shoot_rules.map(rule => rule.source))].sort((a, b) => a - b);
+    /** @type {TreeShootPrototype[]} */
+    const prototypes = [];
+    const carriers = new Map();
+    for (const generator of generators) {
+        const of_generator = [];
+        for (let b = 0; b < framework.branch_count; b++) {
+            if (framework.branch_generator[b] === generator && !framework.branch_dead[b] && framework.branch_length[b] > 0) {
+                of_generator.push(b);
+            }
+        }
+        if (of_generator.length === 0) continue;
+        of_generator.sort((a, b) => framework.branch_length[a] - framework.branch_length[b]);
+        const lengths = Float64Array.from(of_generator, b => framework.branch_length[b]);
+        const n = lengths.length;
+
+        // the median carrier's leaves say how far a prototype may be scaled; a system without leaves, any
+        const median = of_generator[n >> 1];
+        grow(median);
+        const own = foliage_collect_attachments(in_place(framework, grown, [median]), config, cutout);
+        const { low, high } = own.count > 0 ? foliage_scale_spread(own.scales, own.count) : { low: 0, high: Infinity };
+        carriers.set(generator, { lengths, low, high });
+
+        // `need`: the shortest length not yet reached, or, once `reached`, the longest that is
+        let need = lengths[0];
+        let reached = false;
+        for (; ;) {
+            // the longest carrier that scales down to it
+            let k = 0;
+            while (k + 1 < n && lengths[k + 1] * low <= need) k++;
+            if (reached && lengths[k] * high <= need) {
+                // none reaches further: no carrier's length lies past it within reach, so on to the next that does
+                let j = 0;
+                while (j < n && lengths[j] <= need) j++;
+                if (j === n) break;
+                need = lengths[j];
+                reached = false;
+                continue;
+            }
+            grow(of_generator[k]);
+            prototypes.push({ generator, carrier: of_generator[k], length: lengths[k], first: 0, branch_count: 0, carried: [] });
+            need = lengths[k] * high;
+            reached = true;
+            if (need >= lengths[n - 1]) break;
+        }
+    }
+
+    // every prototype where it grew, one skeleton
+    const sheet = in_place(framework, grown, prototypes.map(p => p.carrier), prototypes);
+    const attachments = foliage_collect_attachments(sheet, config, cutout);
+    const leaves = attachments.count > 0 ? tree_mesh_build_foliage(sheet, attachments, config, cutout) : null;
+    let side_area = 0;
+    for (const prototype of prototypes) {
+        const one = in_place(framework, grown, [prototype.carrier]);
+        const own = foliage_collect_attachments(one, config, cutout);
+        side_area += tree_grown_side_area(one, own.count > 0 ? tree_mesh_build_foliage(one, own, config, cutout) : null);
+    }
+
+    // the error ladder, to where no wood is drawn
+    const errors = [];
+    const lods = [];
+    const planned = new Map();
+    for (let error = TREE_LOD_ERROR_FINEST; ; error *= TREE_LOD_ERROR_STEP) {
+        const lod = config.lods[0].clone();
+        lod.error = error;
+        const rings = tree_mesh_compute_branch_rings(sheet, config, lod);
+        planned.set(error, rings);
+        errors.push(error);
+        lods.push(lod);
+        if (rings.size === 0) break;
+    }
+    const atlas = leaves !== null
+        ? tree_cluster_atlas(sheet, config, attachments, leaves, lods, leaf_material, TREE_RENDER_COST_CEILING.texture_density * side_area, planned)
+        : null;
+
+    // what any LOD can draw as wood: what the finest error draws, from the carrier out
+    const prototype_of = new Int32Array(sheet.branch_count).fill(-1);
+    const drawn = new Uint8Array(sheet.branch_count);
+    const finest = planned.get(TREE_LOD_ERROR_FINEST);
+    for (let i = 0; i < prototypes.length; i++) {
+        const q = prototypes[i];
+        prototype_of.fill(i, q.first, q.first + q.branch_count);
+        drawn[q.first] = 1;
+        for (let b = q.first + 1; b < q.first + q.branch_count; b++) {
+            drawn[b] = finest.has(b) && drawn[sheet.branch_parent[b]] ? 1 : 0;
+        }
+    }
+    const owners = atlas === null ? [] : atlas.lods.map(({ clusters, cards }) => Int32Array.from(cards, card => {
+        const cluster = clusters[card.cluster];
+        return prototype_of[cluster.branch >= 0 ? cluster.branch : cluster.root];
+    }));
+
+    // what each carries without drawing it as wood: the shoot systems hanging from its drawn wood, weighed as the
+    // wind's mechanics weigh the wood they would hang from
+    const mechanics = tree_skeleton_compute_segment_mechanics(sheet, config);
+    const top = new Int32Array(sheet.branch_count).fill(-1);
+    const area = new Float64Array(sheet.branch_count);
+    for (const q of prototypes) {
+        for (let b = q.first + 1; b < q.first + q.branch_count; b++) {
+            if (drawn[b]) continue;
+            const p = sheet.branch_parent[b];
+            top[b] = drawn[p] ? b : top[p];
+        }
+    }
+    for (let e = 0; e < sheet.segment_count; e++) {
+        const r = top[sheet.node_branch_id(sheet.segment_v1(e))];
+        if (r >= 0) area[r] += mechanics.leaf_area[e];
+    }
+    const nodes = [], edges = [];
+    const at = new Float64Array(3);
+    for (const q of prototypes) {
+        q.carried = [];
+        for (let r = q.first + 1; r < q.first + q.branch_count; r++) {
+            if (top[r] !== r) continue;
+            sheet.collect_branch_chain(r, nodes, edges);
+            if (edges.length === 0) continue;
+            // from where it hangs to the middle of its first segment, and on as far as that segment carries
+            sheet.node_read_position(at, 0, nodes[0]);
+            const e0 = edges[0];
+            const reach = mechanics.reach[e0] + Math.hypot(mechanics.mid[e0 * 3] - at[0], mechanics.mid[e0 * 3 + 1] - at[1], mechanics.mid[e0 * 3 + 2] - at[2]);
+            q.carried.push({ parent: sheet.branch_parent[r], t: sheet.branch_parent_attach_t[r], leaf_area: area[r], reach });
+        }
+    }
+    return { species: config, framework, prototypes, carriers, sheet, attachments, leaves, side_area, errors, atlas, drawn, prototype_of, owners };
+}
+
+/**
+ * The shoot systems of `carriers`, each with its carrier, where they grew on the framework (`grown`), in one skeleton
+ * under the framework's crown frame.
+ *
+ * @param {TreeSkeleton} framework
+ * @param {Map<number, TreeSkeleton>} grown each carrier's framework with its shoot systems grown
+ * @param {number[]} carriers
+ * @param {TreeShootPrototype[]} [records] where each carrier's branches land in the skeleton, recorded on its prototype
+ * @returns {TreeSkeleton}
+ */
+function in_place(framework, grown, carriers, records) {
+    const out = new TreeSkeleton();
+    for (let i = 0; i < carriers.length; i++) {
+        const carrier = carriers[i];
+        const skeleton = grown.get(carrier);
+        // the carrier, and every shoot: after the framework, mothers before their laterals
+        const branches = [carrier];
+        for (let b = framework.branch_count; b < skeleton.branch_count; b++) branches.push(b);
+        if (records !== undefined) {
+            records[i].first = out.branch_count;
+            records[i].branch_count = branches.length;
+        }
+        tree_skeleton_copy_branches(skeleton, branches, out);
+    }
+    out.crown_center.set(framework.crown_center);
+    out.crown_radii.set(framework.crown_radii);
+    return out;
+}

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

@@ -4,6 +4,12 @@
  * @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.
  */

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;;;;GAIG;AACH,oCAFU,MAAM,CAE0B;AAE1C;;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"}
+{"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

@@ -9,6 +9,13 @@ import { computeHashFloat } from "../../../core/primitives/numbers/computeHashFl
  */
 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.
  */

package/src/generation/foliage/index.d.ts

@@ -3,6 +3,7 @@ export { PhyllotaxisMode } from "./config/PhyllotaxisMode.js";
 export { FoliageCardType } from "./config/FoliageCardType.js";
 export { FoliageBarkType } from "./config/FoliageBarkType.js";
 export { TreePreset } from "./config/TreePreset.js";
+export { TreeGrowth } from "./config/TreeGrowth.js";
 export { BranchGeneratorConfig } from "./config/BranchGeneratorConfig.js";
 export { BranchSpawnRule } from "./config/BranchSpawnRule.js";
 export { FoliageSpawnRule } from "./config/FoliageSpawnRule.js";
@@ -22,6 +23,7 @@ export { make_tree_species_preset } from "./presets/make_tree_species_preset.js"
 export { TreeSkeleton } from "./skeleton/TreeSkeleton.js";
 export { spine_frame_double_reflection } from "./skeleton/spine_frame_double_reflection.js";
 export { tree_skeleton_grow } from "./skeleton/tree_skeleton_grow.js";
+export { tree_skeleton_grow_framework } from "./skeleton/tree_skeleton_grow_framework.js";
 export { tree_skeleton_compute_pipe_radii } from "./skeleton/tree_skeleton_compute_pipe_radii.js";
 export { tree_skeleton_assign_skin_joints } from "./skeleton/tree_skeleton_assign_skin_joints.js";
 export { branch_collar_project } from "./mesh/branch_collar_project.js";
@@ -52,5 +54,6 @@ export { tree_mesh_build_bark, geometry_obtain_joints_attribute } from "./mesh/t
 export { FoliageAtlasCutout, CUTOUT_HULL_VERTEX_COUNT } from "./material/FoliageAtlasCutout.js";
 export { foliage_tile_layout, foliage_tile_raster } from "./material/foliage_tile.js";
 export { leaf_geometry, needle_shoot_geometry } from "./material/leaf_geometry.js";
+export { TreeSpeciesCache, TREE_SPECIES_CACHE } from "./asset/TreeSpeciesCache.js";
 export { place_tree, unplace_tree } from "./asset/place_tree.js";
 //# sourceMappingURL=index.d.ts.map

package/src/generation/foliage/index.js

@@ -3,6 +3,7 @@ export { PhyllotaxisMode } from "./config/PhyllotaxisMode.js";
 export { FoliageCardType } from "./config/FoliageCardType.js";
 export { FoliageBarkType } from "./config/FoliageBarkType.js";
 export { TreePreset } from "./config/TreePreset.js";
+export { TreeGrowth } from "./config/TreeGrowth.js";
 export { BranchGeneratorConfig } from "./config/BranchGeneratorConfig.js";
 export { BranchSpawnRule } from "./config/BranchSpawnRule.js";
 export { FoliageSpawnRule } from "./config/FoliageSpawnRule.js";
@@ -25,6 +26,7 @@ export { TreeSkeleton } from "./skeleton/TreeSkeleton.js";
 export { crown_envelope_evaluate, crown_envelope_sdf } from "./skeleton/crown_envelope_evaluate.js";
 export { spine_frame_double_reflection } from "./skeleton/spine_frame_double_reflection.js";
 export { tree_skeleton_grow } from "./skeleton/tree_skeleton_grow.js";
+export { tree_skeleton_grow_framework } from "./skeleton/tree_skeleton_grow_framework.js";
 export { tree_skeleton_compute_pipe_radii } from "./skeleton/tree_skeleton_compute_pipe_radii.js";
 export { tree_skeleton_assign_skin_joints } from "./skeleton/tree_skeleton_assign_skin_joints.js";
 
@@ -54,6 +56,7 @@ export { FoliageWindSystem } from "../../engine/graphics3/FoliageWindSystem.js";
 
 export { TreeLODAsset } from "./asset/TreeLODAsset.js";
 export { TreeAsset } from "./asset/TreeAsset.js";
+export { TreeSpeciesCache, TREE_SPECIES_CACHE } from "./asset/TreeSpeciesCache.js";
 export { generate_tree } from "./asset/generate_tree.js";
 export { place_tree, unplace_tree } from "./asset/place_tree.js";
 

package/src/generation/foliage/material/foliage_tile.d.ts

@@ -11,9 +11,9 @@
  * @property {number} shoot_length length of shoot a needle-shoot tile draws (m), 0 for a leaf
  * @property {number} outline the mature organ's finest feature of shape (m), its margin's teeth aside (`LeafGeometry`)
  * @property {number} texel the tile's texel (m): `card_size / resolution`
- * @property {number} legible_texel the coarsest texel (m) a cluster card may draw the organ at, as coarse as still tells
- *           the leaf from another seen whole: its outline's finest feature `FEATURE_TEXELS` across; a needle, a line,
- *           as a stem is, `STEM_TEXELS` across its width
+ * @property {number} legible_texel the coarsest texel (m) a cluster card draws the organ at while the tree's atlas holds
+ *           its cover, as coarse as still tells the leaf from another seen whole: its outline's finest feature
+ *           `FEATURE_TEXELS` across; a needle, a line, as a stem is, `STEM_TEXELS` across its width
  */
 /**
  * Maturity variants of a species' foliage atlas.
@@ -90,9 +90,9 @@ export type FoliageTileLayout = {
      */
     texel: number;
     /**
-     * the coarsest texel (m) a cluster card may draw the organ at, as coarse as still tells
-     * the leaf from another seen whole: its outline's finest feature `FEATURE_TEXELS` across; a needle, a line,
-     * as a stem is, `STEM_TEXELS` across its width
+     * the coarsest texel (m) a cluster card draws the organ at while the tree's atlas holds
+     * its cover, as coarse as still tells the leaf from another seen whole: its outline's finest feature
+     * `FEATURE_TEXELS` across; a needle, a line, as a stem is, `STEM_TEXELS` across its width
      */
     legible_texel: number;
 };

package/src/generation/foliage/material/foliage_tile.js

@@ -60,9 +60,9 @@ const COVERAGE_ROWS = 4;
  * @property {number} shoot_length length of shoot a needle-shoot tile draws (m), 0 for a leaf
  * @property {number} outline the mature organ's finest feature of shape (m), its margin's teeth aside (`LeafGeometry`)
  * @property {number} texel the tile's texel (m): `card_size / resolution`
- * @property {number} legible_texel the coarsest texel (m) a cluster card may draw the organ at, as coarse as still tells
- *           the leaf from another seen whole: its outline's finest feature `FEATURE_TEXELS` across; a needle, a line,
- *           as a stem is, `STEM_TEXELS` across its width
+ * @property {number} legible_texel the coarsest texel (m) a cluster card draws the organ at while the tree's atlas holds
+ *           its cover, as coarse as still tells the leaf from another seen whole: its outline's finest feature
+ *           `FEATURE_TEXELS` across; a needle, a line, as a stem is, `STEM_TEXELS` across its width
  */
 
 /**

package/src/generation/foliage/material/tree_cluster_atlas.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The cluster cards of `skeleton` at each of `lods`' errors, all drawn with a few cuts' tiles in one atlas, no larger
+ * than `budget` (`tree_cluster_representatives`), baked from the leaves and twigs those cuts grew (`tree_cluster_bake`).
+ * A tree's own LODs are cut this way, and so are a species' prototypes.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {import("../../../shade/renderer/geometry/Geometry.js").Geometry} leaves every leaf's card, in attachment order
+ * @param {import("../config/TreeLODConfig.js").TreeLODConfig[]} lods finest first
+ * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial} leaf_material the
+ *        leaves' material, whose textures the cuts are baked from
+ * @param {number} budget bytes of atlas, its maps' base levels
+ * @param {Map<number, ReturnType<typeof tree_mesh_compute_branch_rings>>} [planned] the bark's rings the caller has
+ *        already planned, by error: taken rather than planned again
+ * @returns {{lods: Array<{clusters: import("../mesh/tree_clusters.js").TreeCluster[], cards: import("../mesh/tree_cluster_cards.js").TreeClusterCard[], error: number}>, representatives: *, bake: import("./tree_cluster_bake.js").TreeClusterBake, material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}}
+ */
+export function tree_cluster_atlas(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet, leaves: import("../../../shade/renderer/geometry/Geometry.js").Geometry, lods: import("../config/TreeLODConfig.js").TreeLODConfig[], leaf_material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, budget: number, planned?: Map<number, Map<number, {
+    cx: number;
+    cy: number;
+    cz: number;
+    r: number;
+    m: number;
+    t_norm: number;
+    flute_amp: number;
+    j0: number;
+    j1: number;
+    j2: number;
+    j3: number;
+    w0: number;
+    w1: number;
+    w2: number;
+    w3: number;
+}[]>>): {
+    lods: Array<{
+        clusters: import("../mesh/tree_clusters.js").TreeCluster[];
+        cards: import("../mesh/tree_cluster_cards.js").TreeClusterCard[];
+        error: number;
+    }>;
+    representatives: any;
+    bake: import("./tree_cluster_bake.js").TreeClusterBake;
+    material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+};
+//# sourceMappingURL=tree_cluster_atlas.d.ts.map

package/src/generation/foliage/material/tree_cluster_atlas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_cluster_atlas.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/material/tree_cluster_atlas.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH,6CAZW,OAAO,6BAA6B,EAAE,YAAY,WAClD,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,wCAAwC,EAAE,oBAAoB,UACrE,OAAO,8CAA8C,EAAE,QAAQ,QAC/D,OAAO,4BAA4B,EAAE,aAAa,EAAE,iBACpD,OAAO,2DAA2D,EAAE,qBAAqB,UAEzF,MAAM,YACN,IAAI,MAAM;;;;;;;;;;;;;;;;KAAoD,GAE5D;IAAC,IAAI,EAAE,MAAM;QAAC,QAAQ,EAAE,OAAO,0BAA0B,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,OAAO,+BAA+B,EAAE,eAAe,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAAC,eAAe,MAAI;IAAC,IAAI,EAAE,OAAO,wBAAwB,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,OAAO,2DAA2D,EAAE,qBAAqB,CAAA;CAAC,CAazV"}