@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -1,7 +1,6 @@
 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
@@ -81,9 +80,11 @@ export const TREE_RENDER_COST_CEILING = { triangle_density: [761.2, 412.3, 96.2]
  * @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
+ * @param {Float32Array|null} [carried] the cards of the leaves it draws but does not hold, its shoot prototypes'
+ *        (`tree_shoot_instance_leaves`): positions
  * @returns {number}
  */
-export function tree_grown_side_area(skeleton, leaves) {
+export function tree_grown_side_area(skeleton, leaves, carried = null) {
     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);
@@ -92,6 +93,9 @@ export function tree_grown_side_area(skeleton, leaves) {
     if (leaves !== null) {
         shown.push(leaves.getAttribute(StandardAttributes.Position).data);
     }
+    if (carried !== null && carried.length > 0) {
+        shown.push(carried);
+    }
     return tree_envelope_side_area(shown);
 }
 
@@ -108,7 +112,7 @@ function triangle_count(geometry) {
 
 /**
  * @typedef {Object} TreeRenderCost
- * @property {number} side_area m^2, `tree_grown_side_area`: what the tree grew shows from the side
+ * @property {number} side_area m^2, `tree_grown_side_area`: what the tree grew shows from the side (`TreeAsset.side_area`)
  * @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
@@ -127,10 +131,7 @@ function triangle_count(geometry) {
 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);
+    const side_area = asset.side_area;
     assert.greaterThan(side_area, 0, 'side_area');
 
     const triangles = asset.lods.map(lod => triangle_count(lod.bark_geometry) + triangle_count(lod.foliage_geometry));

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

@@ -22,6 +22,23 @@ export class TreeAsset {
      * @type {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet}
      */
     attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet;
+    /**
+     * What the tree grew shows from the side, m^2 (`tree_grown_side_area`): its wood and every leaf it draws, its
+     * shoot prototypes' included. Its LODs spend against it (`tree_lod_plan`, `tree_render_cost`).
+     * @type {number}
+     */
+    side_area: number;
+    /**
+     * The species' shoot prototypes it draws, when grown by its generator graph (`tree_shoot_prototypes`), else `null`:
+     * every leaf it draws is theirs, and `attachments` holds none.
+     * @type {import("./tree_shoot_prototypes.js").TreeShootPrototypes|null}
+     */
+    shoot_prototypes: import("./tree_shoot_prototypes.js").TreeShootPrototypes | null;
+    /**
+     * Where it draws them: one on each of its carriers (`tree_shoot_instances`), else `null`.
+     * @type {import("./tree_shoot_instances.js").TreeShootInstance[]|null}
+     */
+    shoot_instances: import("./tree_shoot_instances.js").TreeShootInstance[] | null;
     /**
      * 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`).

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;;;;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"}
+{"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,MAAM,CAEF;IAEd;;;;OAIG;IACH,kBAFU,OAAO,4BAA4B,EAAE,mBAAmB,GAAC,IAAI,CAE/C;IAExB;;;OAGG;IACH,iBAFU,OAAO,2BAA2B,EAAE,iBAAiB,EAAE,GAAC,IAAI,CAE/C;IAEvB;;;;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

@@ -25,6 +25,26 @@ export class TreeAsset {
      */
     attachments = null;
 
+    /**
+     * What the tree grew shows from the side, m^2 (`tree_grown_side_area`): its wood and every leaf it draws, its
+     * shoot prototypes' included. Its LODs spend against it (`tree_lod_plan`, `tree_render_cost`).
+     * @type {number}
+     */
+    side_area = 0;
+
+    /**
+     * The species' shoot prototypes it draws, when grown by its generator graph (`tree_shoot_prototypes`), else `null`:
+     * every leaf it draws is theirs, and `attachments` holds none.
+     * @type {import("./tree_shoot_prototypes.js").TreeShootPrototypes|null}
+     */
+    shoot_prototypes = null;
+
+    /**
+     * Where it draws them: one on each of its carriers (`tree_shoot_instances`), else `null`.
+     * @type {import("./tree_shoot_instances.js").TreeShootInstance[]|null}
+     */
+    shoot_instances = null;
+
     /**
      * 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`).

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

@@ -0,0 +1,69 @@
+/**
+ * What every tree of a species shares, whatever its seed or how it grew: its bark material, its leaf atlas and its
+ * shoot prototypes, each made once, when a tree first asks for it (`generate_tree`'s `cache`). The caller owns it,
+ * and what it holds lives as long as it does.
+ *
+ * Each is keyed on exactly what it is made from: the bark material on the species' `bark_material`, the leaf atlas on
+ * its `foliage` and `foliage_material`, made from a species holding those alone, and the prototypes on the whole
+ * species but its seed, as they grow on its own framework. Trees that differ in nothing one is made from share it.
+ */
+export class TreeSpeciesCache {
+    /**
+     * Lets go of everything held: the trees already made keep what they drew with.
+     */
+    clear(): void;
+    /**
+     * Number of bark materials held.
+     * @returns {number}
+     */
+    get bark_count(): number;
+    /**
+     * Number of leaf atlases held.
+     * @returns {number}
+     */
+    get leaf_count(): number;
+    /**
+     * Number of species whose shoot prototypes are held.
+     * @returns {number}
+     */
+    get prototype_count(): number;
+    /**
+     * The bark material of `species`, the same noise for every bark (`make_bark_material`'s own seed).
+     *
+     * @param {TreeSpeciesConfig} species
+     * @returns {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    bark_material(species: TreeSpeciesConfig): import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+    /**
+     * The leaf atlas of `species`, in the species' leaf material, which a tree clones to tint its own, and the atlas's
+     * shape.
+     *
+     * @param {TreeSpeciesConfig} species
+     * @returns {{material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, cutout: FoliageAtlasCutout}}
+     */
+    leaves(species: TreeSpeciesConfig): {
+        material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial;
+        cutout: FoliageAtlasCutout;
+    };
+    /**
+     * The shoot prototypes of `species` (`tree_shoot_prototypes`), whatever its seed, their cuts baked from the leaves
+     * of `material`: its own leaf atlas (`leaves`) by default, or a caller's own material, whose atlas has no fitted
+     * shape (`cutout` null).
+     *
+     * @param {TreeSpeciesConfig} species
+     * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null} [material]
+     * @param {FoliageAtlasCutout|null} [cutout] the shape of `material`'s atlas
+     * @returns {import("./tree_shoot_prototypes.js").TreeShootPrototypes}
+     */
+    prototypes(species: TreeSpeciesConfig, material?: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial | null, cutout?: FoliageAtlasCutout | null): import("./tree_shoot_prototypes.js").TreeShootPrototypes;
+    #private;
+}
+/**
+ * The cache `generate_tree` shares between the trees it is asked for without one of their own: each species' materials and
+ * shoot prototypes are made once, the first time a tree asks, and held until `clear`ed.
+ * @type {TreeSpeciesCache}
+ */
+export const TREE_SPECIES_CACHE: TreeSpeciesCache;
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { FoliageAtlasCutout } from "../material/FoliageAtlasCutout.js";
+//# sourceMappingURL=TreeSpeciesCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TreeSpeciesCache.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/TreeSpeciesCache.js"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH;IAoBI;;OAEG;IACH,cAKC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,uBAHW,iBAAiB,GACf,OAAO,2DAA2D,EAAE,qBAAqB,CAUrG;IAED;;;;;;OAMG;IACH,gBAHW,iBAAiB,GACf;QAAC,QAAQ,EAAE,OAAO,2DAA2D,EAAE,qBAAqB,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAA;KAAC,CAe7I;IAED;;;;;;;;;OASG;IACH,oBALW,iBAAiB,aACjB,OAAO,2DAA2D,EAAE,qBAAqB,GAAC,IAAI,WAC9F,kBAAkB,GAAC,IAAI,GACrB,OAAO,4BAA4B,EAAE,mBAAmB,CAsBpE;;CACJ;AAED;;;;GAIG;AACH,iCAFU,gBAAgB,CAE+B;kCAjJvB,gCAAgC;mCAC/B,mCAAmC"}

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

@@ -0,0 +1,147 @@
+import { HashMap } from "../../../core/collection/map/HashMap.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { FoliageAtlasCutout } from "../material/FoliageAtlasCutout.js";
+import { make_bark_material } from "../material/make_bark_material.js";
+import { make_foliage_material } from "../material/make_foliage_material.js";
+import { tree_shoot_prototypes } from "./tree_shoot_prototypes.js";
+
+/**
+ * What every tree of a species shares, whatever its seed or how it grew: its bark material, its leaf atlas and its
+ * shoot prototypes, each made once, when a tree first asks for it (`generate_tree`'s `cache`). The caller owns it,
+ * and what it holds lives as long as it does.
+ *
+ * Each is keyed on exactly what it is made from: the bark material on the species' `bark_material`, the leaf atlas on
+ * its `foliage` and `foliage_material`, made from a species holding those alone, and the prototypes on the whole
+ * species but its seed, as they grow on its own framework. Trees that differ in nothing one is made from share it.
+ */
+export class TreeSpeciesCache {
+    /**
+     * Each bark material, by the `bark_material` it is made from.
+     * @type {HashMap<import("../config/BarkMaterialConfig.js").BarkMaterialConfig, import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial>}
+     */
+    #barks = new HashMap();
+
+    /**
+     * Each leaf atlas, by the species it is made from: one holding its `foliage` and `foliage_material` alone.
+     * @type {HashMap<TreeSpeciesConfig, {material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, cutout: FoliageAtlasCutout}>}
+     */
+    #leaves = new HashMap();
+
+    /**
+     * Each species' shoot prototypes, by the species at their seed, then by the leaf material they are drawn with.
+     * @type {HashMap<TreeSpeciesConfig, Map<import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, import("./tree_shoot_prototypes.js").TreeShootPrototypes>>}
+     */
+    #prototypes = new HashMap();
+    #prototype_count = 0;
+
+    /**
+     * Lets go of everything held: the trees already made keep what they drew with.
+     */
+    clear() {
+        this.#barks.clear();
+        this.#leaves.clear();
+        this.#prototypes.clear();
+        this.#prototype_count = 0;
+    }
+
+    /**
+     * Number of bark materials held.
+     * @returns {number}
+     */
+    get bark_count() {
+        return this.#barks.size;
+    }
+
+    /**
+     * Number of leaf atlases held.
+     * @returns {number}
+     */
+    get leaf_count() {
+        return this.#leaves.size;
+    }
+
+    /**
+     * Number of species whose shoot prototypes are held.
+     * @returns {number}
+     */
+    get prototype_count() {
+        return this.#prototype_count;
+    }
+
+    /**
+     * The bark material of `species`, the same noise for every bark (`make_bark_material`'s own seed).
+     *
+     * @param {TreeSpeciesConfig} species
+     * @returns {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    bark_material(species) {
+        let material = this.#barks.get(species.bark_material);
+        if (material === undefined) {
+            const held = species.bark_material.clone();
+            material = make_bark_material(held);
+            this.#barks.set(held, material);
+        }
+        return material;
+    }
+
+    /**
+     * The leaf atlas of `species`, in the species' leaf material, which a tree clones to tint its own, and the atlas's
+     * shape.
+     *
+     * @param {TreeSpeciesConfig} species
+     * @returns {{material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, cutout: FoliageAtlasCutout}}
+     */
+    leaves(species) {
+        // the species as far as its leaves go, and no further: whatever the atlas reads, it reads from the key
+        const key = new TreeSpeciesConfig();
+        key.seed = 0;
+        key.foliage.copy(species.foliage);
+        key.foliage_material.copy(species.foliage_material);
+        let entry = this.#leaves.get(key);
+        if (entry === undefined) {
+            const cutout = new FoliageAtlasCutout();
+            entry = { material: make_foliage_material(key, cutout), cutout };
+            this.#leaves.set(key, entry);
+        }
+        return entry;
+    }
+
+    /**
+     * The shoot prototypes of `species` (`tree_shoot_prototypes`), whatever its seed, their cuts baked from the leaves
+     * of `material`: its own leaf atlas (`leaves`) by default, or a caller's own material, whose atlas has no fitted
+     * shape (`cutout` null).
+     *
+     * @param {TreeSpeciesConfig} species
+     * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null} [material]
+     * @param {FoliageAtlasCutout|null} [cutout] the shape of `material`'s atlas
+     * @returns {import("./tree_shoot_prototypes.js").TreeShootPrototypes}
+     */
+    prototypes(species, material = null, cutout = null) {
+        if (material === null) {
+            const leaves = this.leaves(species);
+            material = leaves.material;
+            cutout = leaves.cutout;
+        }
+        const key = species.clone();
+        key.seed = 0;
+        let by_material = this.#prototypes.get(key);
+        if (by_material === undefined) {
+            by_material = new Map();
+            this.#prototypes.set(key, by_material);
+        }
+        let prototypes = by_material.get(material);
+        if (prototypes === undefined) {
+            prototypes = tree_shoot_prototypes(key, material, cutout);
+            by_material.set(material, prototypes);
+            this.#prototype_count++;
+        }
+        return prototypes;
+    }
+}
+
+/**
+ * The cache `generate_tree` shares between the trees it is asked for without one of their own: each species' materials and
+ * shoot prototypes are made once, the first time a tree asks, and held until `clear`ed.
+ * @type {TreeSpeciesCache}
+ */
+export const TREE_SPECIES_CACHE = new TreeSpeciesCache();

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

@@ -7,6 +7,16 @@
  * - A `TreeSpeciesConfig` instance (`generate_tree(species_config)`).
  * - An options object (`generate_tree({ preset: "birch", seed: 42, crown: { height: 14 }, lod_count: 3 })`).
  *
+ * The options object also picks how the tree is grown, `growth` (`TreeGrowth`, by its generator graph unless given):
+ * its generator graph's framework with its species' shoot prototypes drawn on it, for most trees; or that framework
+ * with every shoot system grown on it, for trees seen up close. Both are drawn by one pipeline. A species is described
+ * for the front end that grows it (`make_tree_species_preset`'s `growth`): a preset's name is described for `growth`;
+ * a caller's own `TreeSpeciesConfig` is grown as it is, by the generator graph when passed alone, or by `growth` when
+ * passed as the options object's `species`. Its `cache`, a
+ * `TreeSpeciesCache`, shares each species' bark material, leaf atlas and shoot prototypes between the trees it grows;
+ * without one, every call shares `TREE_SPECIES_CACHE`. A caller's own materials (`custom_bark_material`,
+ * `custom_foliage_material`) are drawn with instead.
+ *
  * 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

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

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

@@ -1,16 +1,11 @@
+import { assert } from "../../../core/assert.js";
 import { TREE_RENDER_COST_CEILING, tree_grown_side_area } from "../analysis/tree_render_cost.js";
 import { build_tree_wind_rig } from "../animation/build_tree_wind_rig.js";
 import { TREE_LOD_ERROR_FINEST } from "../config/TreeLODConfig.js";
+import { TreeGrowth } from "../config/TreeGrowth.js";
 import { TreePreset } from "../config/TreePreset.js";
-import { FoliageAtlasCutout } from "../material/FoliageAtlasCutout.js";
-import { make_bark_material } from "../material/make_bark_material.js";
-import { foliage_material_from_samplers } from "../material/foliage_material_from_samplers.js";
-import { make_foliage_material } from "../material/make_foliage_material.js";
-import { tree_cluster_bake } from "../material/tree_cluster_bake.js";
+import { tree_cluster_atlas } from "../material/tree_cluster_atlas.js";
 import { foliage_collect_attachments } from "../mesh/foliage_collect_attachments.js";
-import { foliage_tile_layout } from "../material/foliage_tile.js";
-import { tree_cluster_cards } from "../mesh/tree_cluster_cards.js";
-import { tree_cluster_representatives } from "../mesh/tree_cluster_representatives.js";
 import { tree_clusters } from "../mesh/tree_clusters.js";
 import { tree_mesh_build_bark, tree_mesh_compute_branch_rings } from "../mesh/tree_mesh_build_bark.js";
 import { tree_mesh_build_clusters } from "../mesh/tree_mesh_build_clusters.js";
@@ -19,8 +14,11 @@ import { make_tree_species_preset } from "../presets/make_tree_species_preset.js
 import { tree_skeleton_assign_skin_joints } from "../skeleton/tree_skeleton_assign_skin_joints.js";
 import { tree_skeleton_bind_skin_joints } from "../skeleton/tree_skeleton_bind_skin_joints.js";
 import { tree_skeleton_grow } from "../skeleton/tree_skeleton_grow.js";
+import { tree_skeleton_grow_framework } from "../skeleton/tree_skeleton_grow_framework.js";
 import { TreeAsset } from "./TreeAsset.js";
 import { TreeLODAsset } from "./TreeLODAsset.js";
+import { TREE_SPECIES_CACHE } from "./TreeSpeciesCache.js";
+import { tree_shoot_instance_card_count, tree_shoot_instance_cards, tree_shoot_instance_leaves, tree_shoot_instances } from "./tree_shoot_instances.js";
 import { tree_lod_plan } from "./tree_lod_plan.js";
 
 /**
@@ -32,6 +30,16 @@ import { tree_lod_plan } from "./tree_lod_plan.js";
  * - A `TreeSpeciesConfig` instance (`generate_tree(species_config)`).
  * - An options object (`generate_tree({ preset: "birch", seed: 42, crown: { height: 14 }, lod_count: 3 })`).
  *
+ * The options object also picks how the tree is grown, `growth` (`TreeGrowth`, by its generator graph unless given):
+ * its generator graph's framework with its species' shoot prototypes drawn on it, for most trees; or that framework
+ * with every shoot system grown on it, for trees seen up close. Both are drawn by one pipeline. A species is described
+ * for the front end that grows it (`make_tree_species_preset`'s `growth`): a preset's name is described for `growth`;
+ * a caller's own `TreeSpeciesConfig` is grown as it is, by the generator graph when passed alone, or by `growth` when
+ * passed as the options object's `species`. Its `cache`, a
+ * `TreeSpeciesCache`, shares each species' bark material, leaf atlas and shoot prototypes between the trees it grows;
+ * without one, every call shares `TREE_SPECIES_CACHE`. A caller's own materials (`custom_bark_material`,
+ * `custom_foliage_material`) are drawn with instead.
+ *
  * 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
@@ -51,15 +59,21 @@ export function generate_tree(options = {}) {
     let eager_meshlets = false;
     let custom_bark_material = null;
     let custom_foliage_material = null;
+    // the generator graph unless an options object asks for another
+    let growth = TreeGrowth.Graph;
+    let cache = null;
 
     if (typeof options === "string") {
-        config = make_tree_species_preset(options);
+        config = make_tree_species_preset(options, {}, growth);
     } else if (options && options.isTreeSpeciesConfig) {
         config = options.clone();
     } else {
         const opts = options || {};
         const preset = opts.preset ?? TreePreset.Oak;
-        config = make_tree_species_preset(preset, opts);
+        growth = opts.growth ?? growth;
+        cache = opts.cache ?? null;
+        assert.enum(growth, TreeGrowth, "growth");
+        config = opts.species?.isTreeSpeciesConfig ? opts.species.clone() : make_tree_species_preset(preset, opts, growth);
         eager_meshlets = Boolean(opts.eager_meshlets);
         if (opts.custom_bark_material && opts.custom_bark_material.isShadeMaterial) {
             custom_bark_material = opts.custom_bark_material;
@@ -69,13 +83,18 @@ export function generate_tree(options = {}) {
         }
     }
 
-    const skeleton = tree_skeleton_grow(config);
+    const skeleton = growth === TreeGrowth.Graph ? tree_skeleton_grow_framework(config) : tree_skeleton_grow(config);
+    // what every tree of its species shares, made only where the caller gave none of its own
+    const species_cache = cache ?? TREE_SPECIES_CACHE;
+    // a tree grown by its generator graph draws its species' shoot prototypes on its carriers
+    const prototypes = growth === TreeGrowth.Graph && config.shoot_rules.length > 0
+        ? species_cache.prototypes(config, custom_foliage_material)
+        : null;
+    const instances = prototypes !== null ? tree_shoot_instances(skeleton, prototypes) : null;
     // the rig of all the wood as grown, which the leaves as grown are bound to
     const skin_info = tree_skeleton_assign_skin_joints(skeleton, config);
 
-    const bark_material = custom_bark_material !== null
-        ? custom_bark_material
-        : make_bark_material(config.bark_material, config.seed);
+    const bark_material = custom_bark_material !== null ? custom_bark_material : species_cache.bark_material(config);
 
     // The atlas's shape sets how many cards a shoot carries and, for hull cards, their outline. A caller's own
     // material has no fitted outline, so its cards cover whole tiles, at the density our atlas would need.
@@ -84,8 +103,10 @@ export function generate_tree(options = {}) {
     if (custom_foliage_material !== null) {
         foliage_material = custom_foliage_material;
     } else if (config.foliage_rules.length > 0) {
-        foliage_cutout = new FoliageAtlasCutout();
-        foliage_material = make_foliage_material(config, foliage_cutout);
+        // the species' atlas, in a material of the tree's own, which its leaves' tints scale
+        const leaves = species_cache.leaves(config);
+        foliage_cutout = leaves.cutout;
+        foliage_material = leaves.material.clone();
     }
     // The cards anchor on the bark's rings at the finest LOD's error. The LOD search's first step plans the rings at
     // TREE_LOD_ERROR_FINEST with the skeleton still bound to the rig as grown, as here: where the two errors are one,
@@ -117,8 +138,14 @@ export function generate_tree(options = {}) {
     // otherwise be held for as long as any LOD is not
     const has_leaves = attachments.count > 0 && foliage_material !== null;
     const grow_leaves = () => tree_mesh_build_foliage(skeleton, attachments, config, foliage_cutout);
-    const side_area = tree_grown_side_area(skeleton, has_leaves ? grow_leaves() : null);
-    const plan = tree_lod_plan(skeleton, config, attachments, side_area, config.lods.length, planned);
+    const draws_prototypes = prototypes !== null && prototypes.atlas !== null;
+    const side_area = tree_grown_side_area(skeleton, has_leaves ? grow_leaves() : null,
+        instances !== null ? tree_shoot_instance_leaves(skeleton, instances, prototypes) : null);
+    asset.side_area = side_area;
+    asset.shoot_prototypes = prototypes;
+    asset.shoot_instances = instances;
+    const plan = tree_lod_plan(skeleton, config, attachments, side_area, config.lods.length, planned,
+        instances !== null ? (error) => tree_shoot_instance_card_count(instances, prototypes, error) : null);
     const lod_configs = plan.map((p, i) => {
         const lod_cfg = config.lods[i].clone();
         lod_cfg.error = p.error;
@@ -130,17 +157,8 @@ export function generate_tree(options = {}) {
     let shared = null;
     const cluster_atlas = () => {
         if (shared === null) {
-            const leaves = grow_leaves();
-            const lods = lod_configs.map((lod_cfg) => {
-                const clusters = tree_clusters(skeleton, attachments, tree_mesh_compute_branch_rings(skeleton, config, lod_cfg));
-                return { clusters, cards: tree_cluster_cards(skeleton, attachments, leaves, clusters), error: lod_cfg.error };
-            });
-            const tiles = foliage_tile_layout(config);
-            const representatives = tree_cluster_representatives(skeleton, attachments, leaves, lods, tiles.texel,
-                tiles.legible_texel, TREE_RENDER_COST_CEILING.texture_density * side_area);
-            const bake = tree_cluster_bake(skeleton, config, representatives.cards, attachments, leaves, foliage_material, representatives.texels);
-            const material = foliage_material_from_samplers(bake.albedo, bake.normal, bake.orm, "foliage_clusters");
-            shared = { lods, representatives, bake, material };
+            shared = tree_cluster_atlas(skeleton, config, attachments, grow_leaves(), lod_configs, foliage_material,
+                TREE_RENDER_COST_CEILING.texture_density * side_area);
         }
         return shared;
     };
@@ -157,6 +175,16 @@ export function generate_tree(options = {}) {
                 return tree_mesh_build_bark(skeleton, config, lod_cfg);
             },
             () => {
+                if (instances !== null) {
+                    if (!draws_prototypes) return null;
+                    // its prototypes' cuts at its error, on its own rig
+                    tree_skeleton_bind_skin_joints(skeleton, lod_skin);
+                    const rings = tree_mesh_compute_branch_rings(skeleton, config, lod_cfg);
+                    const { clusters, cards, placement } = tree_shoot_instance_cards(skeleton, rings, instances, prototypes, lod_cfg.error);
+                    const geometry = tree_mesh_build_clusters(skeleton, config, clusters, cards, placement, prototypes.atlas.bake);
+                    if (geometry === null) return null;
+                    return { geometry, material: prototypes.atlas.material };
+                }
                 if (!has_leaves) return null;
                 tree_skeleton_bind_skin_joints(skeleton, lod_skin);
                 const clusters = tree_clusters(skeleton, attachments, tree_mesh_compute_branch_rings(skeleton, config, lod_cfg));

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

@@ -10,7 +10,8 @@
  *
  * @param {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
  * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
- * @param {Object} [options={}]
+ * @param {Object} [options={}] without a `tree` or a `prefab`, the tree is grown from these by `generate_tree` (its
+ *        `preset`, `seed`, `growth`, `cache` and the rest)
  * @param {import("./TreeAsset.js").TreeAsset} [options.tree] pre-generated `TreeAsset`
  * @param {import("../../../engine/graphics3/prefab/Prefab.js").Prefab} [options.prefab] pre-compiled `Prefab`
  * @param {number} [options.lod=0] LOD index when placing from `TreeAsset`

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

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

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

@@ -19,7 +19,8 @@ import { generate_tree } from "./generate_tree.js";
  *
  * @param {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
  * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
- * @param {Object} [options={}]
+ * @param {Object} [options={}] without a `tree` or a `prefab`, the tree is grown from these by `generate_tree` (its
+ *        `preset`, `seed`, `growth`, `cache` and the rest)
  * @param {import("./TreeAsset.js").TreeAsset} [options.tree] pre-generated `TreeAsset`
  * @param {import("../../../engine/graphics3/prefab/Prefab.js").Prefab} [options.prefab] pre-compiled `Prefab`
  * @param {number} [options.lod=0] LOD index when placing from `TreeAsset`

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

@@ -21,7 +21,7 @@ export function tree_triangles_at_error(skeleton: import("../skeleton/TreeSkelet
  * `TREE_RENDER_COST_CEILING` over `side_area` (`tree_grown_side_area`), its bark and cluster cards in triangles and,
  * when it is rigged for wind, its joints, no finer than the LOD before it and no finer than `TREE_LOD_ERROR_FINEST`:
  * each halving of the error quadruples the cluster cards' texels, which no ceiling yet bounds. Errors are tried a
- * half-octave apart ({@link ERROR_STEP}), up from the finest until the tree fits, or until it draws no wood at all.
+ * half-octave apart ({@link TREE_LOD_ERROR_STEP}), up from the finest until the tree fits, or until it draws no wood at all.
  *
  * An LOD's rig (`tree_skeleton_assign_skin_joints`) is on the wood it draws, at a tolerance no finer than its error
  * (a sway smaller than the shape's error cannot be seen), and its joints are a subset of the finer LOD's. The
@@ -35,6 +35,8 @@ export function tree_triangles_at_error(skeleton: import("../skeleton/TreeSkelet
  * @param {Map<number, ReturnType<typeof tree_mesh_compute_branch_rings>>} [planned] the bark's rings the caller has
  *        already planned (`tree_mesh_compute_branch_rings`), by error: the search takes them rather than planning them
  *        again
+ * @param {((error: number) => number)|null} [cards] how many cards the tree draws at an error, where they are not its
+ *        own cuts (`tree_shoot_instance_card_count`); its own clusters (`tree_clusters`) by default
  * @returns {TreeLODPlan[]}
  */
 export function tree_lod_plan(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet, side_area: number, lod_count: number, planned?: Map<number, Map<number, {
@@ -53,7 +55,7 @@ export function tree_lod_plan(skeleton: import("../skeleton/TreeSkeleton.js").Tr
     w1: number;
     w2: number;
     w3: number;
-}[]>>): TreeLODPlan[];
+}[]>>, cards?: ((error: number) => number) | null): TreeLODPlan[];
 /**
  * One LOD of a tree: the error it is drawn to and the rig on the wood it draws.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"tree_lod_plan.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/tree_lod_plan.js"],"names":[],"mappings":"AAqCA;;;;;;;;;GASG;AACH,kDANW,OAAO,6BAA6B,EAAE,YAAY,WAClD,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,wCAAwC,EAAE,oBAAoB,SACrE,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wCAVW,OAAO,6BAA6B,EAAE,YAAY,WAClD,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,wCAAwC,EAAE,oBAAoB,aACrE,MAAM,aACN,MAAM,YACN,IAAI,MAAM;;;;;;;;;;;;;;;;KAAoD,GAG5D,WAAW,EAAE,CAwCzB;;;;;;;;WA/Da,MAAM;;;;eACN,WAAW,uCAAuC,CAAC;;iDAnDhB,iDAAiD"}
+{"version":3,"file":"tree_lod_plan.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/tree_lod_plan.js"],"names":[],"mappings":"AAiCA;;;;;;;;;GASG;AACH,kDANW,OAAO,6BAA6B,EAAE,YAAY,WAClD,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,wCAAwC,EAAE,oBAAoB,SACrE,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wCAZW,OAAO,6BAA6B,EAAE,YAAY,WAClD,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,wCAAwC,EAAE,oBAAoB,aACrE,MAAM,aACN,MAAM,YACN,IAAI,MAAM;;;;;;;;;;;;;;;;KAAoD,UAG9D,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAC,IAAI,GAE9B,WAAW,EAAE,CAwCzB;;;;;;;;WAjEa,MAAM;;;;eACN,WAAW,uCAAuC,CAAC;;iDA/ChB,iDAAiD"}