@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -1,16 +1,10 @@
 import { TREE_RENDER_COST_CEILING } from "../analysis/tree_render_cost.js";
-import { TREE_LOD_ERROR_FINEST } from "../config/TreeLODConfig.js";
+import { TREE_LOD_ERROR_FINEST, TREE_LOD_ERROR_STEP } from "../config/TreeLODConfig.js";
 import { CUTOUT_HULL_VERTEX_COUNT } from "../material/FoliageAtlasCutout.js";
 import { tree_clusters } from "../mesh/tree_clusters.js";
 import { tree_mesh_compute_branch_rings } from "../mesh/tree_mesh_build_bark.js";
 import { tree_skeleton_assign_skin_joints } from "../skeleton/tree_skeleton_assign_skin_joints.js";
 
-/**
- * Ratio between consecutive errors the search tries: each a half-octave coarser than the last.
- * @type {number}
- */
-const ERROR_STEP = Math.SQRT2;
-
 /**
  * Triangles the bark `rings` and the cluster cards of the wood they leave out cost.
  *
@@ -19,7 +13,7 @@ const ERROR_STEP = Math.SQRT2;
  * @param {Map<number, Array<{m: number}>>} rings
  * @returns {number}
  */
-function triangles_of(skeleton, attachments, rings) {
+function triangles_of(skeleton, attachments, rings, cards) {
     let triangles = 0;
     for (const list of rings.values()) {
         for (let i = 1; i < list.length; i++) {
@@ -28,7 +22,9 @@ function triangles_of(skeleton, attachments, rings) {
         // the tip's cap
         triangles += list[list.length - 1].m;
     }
-    if (attachments.count > 0 || rings.size < skeleton.branch_count) {
+    if (cards !== null) {
+        triangles += cards(rings) * CUTOUT_HULL_VERTEX_COUNT;
+    } else if (attachments.count > 0 || rings.size < skeleton.branch_count) {
         // a card per cluster
         triangles += tree_clusters(skeleton, attachments, rings).length * CUTOUT_HULL_VERTEX_COUNT;
     }
@@ -46,7 +42,7 @@ function triangles_of(skeleton, attachments, rings) {
  * @returns {number}
  */
 export function tree_triangles_at_error(skeleton, species, attachments, error) {
-    return triangles_of(skeleton, attachments, tree_mesh_compute_branch_rings(skeleton, species, { error }));
+    return triangles_of(skeleton, attachments, tree_mesh_compute_branch_rings(skeleton, species, { error }), null);
 }
 
 /**
@@ -62,7 +58,7 @@ export function tree_triangles_at_error(skeleton, species, attachments, error) {
  * `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
@@ -76,9 +72,11 @@ export function tree_triangles_at_error(skeleton, species, attachments, error) {
  * @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, species, attachments, side_area, lod_count, planned = new Map()) {
+export function tree_lod_plan(skeleton, species, attachments, side_area, lod_count, planned = new Map(), cards = null) {
     const ceiling = TREE_RENDER_COST_CEILING;
     const rigged = species.wind.enabled;
     const drawn = new Map();
@@ -86,7 +84,7 @@ export function tree_lod_plan(skeleton, species, attachments, side_area, lod_cou
         let d = drawn.get(error);
         if (d === undefined) {
             const rings = planned.get(error) ?? tree_mesh_compute_branch_rings(skeleton, species, { error });
-            d = { rings, density: triangles_of(skeleton, attachments, rings) / side_area };
+            d = { rings, density: triangles_of(skeleton, attachments, rings, cards === null ? null : () => cards(error)) / side_area };
             drawn.set(error, d);
         }
         return d;
@@ -112,7 +110,7 @@ export function tree_lod_plan(skeleton, species, attachments, side_area, lod_cou
                     break;
                 }
             }
-            error *= ERROR_STEP;
+            error *= TREE_LOD_ERROR_STEP;
         }
     }
     return plan;

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

@@ -0,0 +1,119 @@
+/**
+ * @typedef {Object} TreeShootInstance
+ * @property {number} prototype index into `TreeShootPrototypes.prototypes`
+ * @property {number} carrier the tree's branch it is drawn on
+ * @property {number} scale `TREE_LOD_ERROR_STEP ^ shift`: wood, girth, leaves and cards alike
+ * @property {number} shift the steps of the error ladder its scale is: at the tree's error, the prototype's cuts `shift`
+ *           steps finer are drawn, as large
+ * @property {Float64Array} turn row-major 3x3, a turn about the vertical: the prototype's carrier's heading onto the tree's
+ * @property {Int32Array} branch_of per branch of the prototype in the sheet (from its `first`), its branch in the tree,
+ *           or -1 for wood no LOD draws, which the prototype's cuts alone draw
+ * @property {Array<import("../skeleton/tree_skeleton_copy_branches.js").TreeBranchPlacement>} placement_of per branch
+ *           of the prototype, where it is carried onto the tree: grafted as, or, undrawn, drawn as
+ */
+/**
+ * Draws a species' shoot prototypes on a tree grown by its generator graph (TWO_FRONT_ENDS_BRIEF_2026_10_28.md, G3).
+ * Every living carrier of a shoot rule's `source` takes the prototype of its generator whose carrier's length is nearest
+ * its own, in ratio (`tree_shoot_prototypes`).
+ *
+ * - **Scaled by the ladder.** The ratio is drawn as the nearest power of the error ladder's step: within the spread the
+ *   species' leaves grow to, 1, so the prototype is drawn as it grew. Wood, girth, leaves and cards are scaled alike,
+ *   so at the tree's error the tree draws as wood exactly what the prototype's cuts that many steps finer leave to wood.
+ * - **Turned about the vertical only**, from the prototype's carrier's heading to the tree's: up stays up, as the
+ *   prototype's leaves were lit and baked.
+ * - **The carrier** keeps its own course in the tree. It takes the prototype's growth past its framework's tip, turned
+ *   to carry on from the tree's carrier's tip, its annual units and its girth.
+ * - **The wood any LOD draws** (`TreeShootPrototypes.drawn`) is grafted onto it, each shoot system hung on the tree's
+ *   carrier where it hangs on the prototype's (`tree_skeleton_copy_branch`): the rig, the bark and the LOD plan take it
+ *   as the tree's own. Its leaf the tree holds by its annual units, as the prototype's wood held it.
+ * - **The rest** the prototype's cuts draw (`tree_shoot_instance_cards`); its leaf loads the segment it hangs from
+ *   (`TreeSkeleton.segment_carried_leaf_area`). Every branch of an instance is marked (`TreeSkeleton.branch_instance`),
+ *   so the tree's own leaves leave it to the prototype.
+ * - **Its girth holds together**: every branch is at least as thick as what grows from it (`tree_skeleton_floor_girth`).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton the tree's framework, grafted onto in place
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @returns {TreeShootInstance[]}
+ */
+export function tree_shoot_instances(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, prototypes: import("./tree_shoot_prototypes.js").TreeShootPrototypes): TreeShootInstance[];
+/**
+ * The cards of every instance on the tree at `error`: each prototype's cuts at the step of its error ladder `error` is
+ * (`TreeShootPrototypes.errors`, the LOD plan's own steps) less the instance's `shift`, carried as its instance carries
+ * them: from where they hang on the prototype to the same place on the tree, and skinned as the tree's drawn bark is
+ * there, or where the nearest drawn wood holds it (`tree_cluster_hang`).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton bound to the rig `rings` were planned with
+ * @param {Map<number, Array<{t_norm: number, cx: number, cy: number, cz: number}>>} rings the tree's at `error`
+ * @param {TreeShootInstance[]} instances
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @param {number} error m, a step of the error ladder
+ * @returns {{clusters: import("../mesh/tree_clusters.js").TreeCluster[], cards: Array<{cluster: number}>, placement: {rep: Int32Array, frames: Float64Array}}}
+ */
+export function tree_shoot_instance_cards(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, rings: Map<number, Array<{
+    t_norm: number;
+    cx: number;
+    cy: number;
+    cz: number;
+}>>, instances: TreeShootInstance[], prototypes: import("./tree_shoot_prototypes.js").TreeShootPrototypes, error: number): {
+    clusters: import("../mesh/tree_clusters.js").TreeCluster[];
+    cards: Array<{
+        cluster: number;
+    }>;
+    placement: {
+        rep: Int32Array;
+        frames: Float64Array;
+    };
+};
+/**
+ * How many cards the instances draw at `error` (`tree_shoot_instance_cards`), for the LOD plan.
+ *
+ * @param {TreeShootInstance[]} instances
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @param {number} error m, a step of the error ladder
+ * @returns {number}
+ */
+export function tree_shoot_instance_card_count(instances: TreeShootInstance[], prototypes: import("./tree_shoot_prototypes.js").TreeShootPrototypes, error: number): number;
+/**
+ * Every leaf's card the instances draw, carried onto the tree as they are (for `tree_grown_side_area`): positions,
+ * `3` per vertex. A leaf on a carrier lands where the carrier runs on the tree.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton the tree the instances are on
+ * @param {TreeShootInstance[]} instances
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @returns {Float32Array}
+ */
+export function tree_shoot_instance_leaves(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, instances: TreeShootInstance[], prototypes: import("./tree_shoot_prototypes.js").TreeShootPrototypes): Float32Array;
+export type TreeShootInstance = {
+    /**
+     * index into `TreeShootPrototypes.prototypes`
+     */
+    prototype: number;
+    /**
+     * the tree's branch it is drawn on
+     */
+    carrier: number;
+    /**
+     * `TREE_LOD_ERROR_STEP ^ shift`: wood, girth, leaves and cards alike
+     */
+    scale: number;
+    /**
+     * the steps of the error ladder its scale is: at the tree's error, the prototype's cuts `shift`
+     * steps finer are drawn, as large
+     */
+    shift: number;
+    /**
+     * row-major 3x3, a turn about the vertical: the prototype's carrier's heading onto the tree's
+     */
+    turn: Float64Array;
+    /**
+     * per branch of the prototype in the sheet (from its `first`), its branch in the tree,
+     * or -1 for wood no LOD draws, which the prototype's cuts alone draw
+     */
+    branch_of: Int32Array;
+    /**
+     * per branch
+     * of the prototype, where it is carried onto the tree: grafted as, or, undrawn, drawn as
+     */
+    placement_of: Array<import("../skeleton/tree_skeleton_copy_branches.js").TreeBranchPlacement>;
+};
+//# sourceMappingURL=tree_shoot_instances.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree_shoot_instances.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/tree_shoot_instances.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,+CAJW,OAAO,6BAA6B,EAAE,YAAY,cAClD,OAAO,4BAA4B,EAAE,mBAAmB,GACtD,iBAAiB,EAAE,CA6B/B;AA2GD;;;;;;;;;;;;GAYG;AACH,oDAPW,OAAO,6BAA6B,EAAE,YAAY,SAClD,IAAI,MAAM,EAAE,MAAM;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,aACxE,iBAAiB,EAAE,cACnB,OAAO,4BAA4B,EAAE,mBAAmB,SACxD,MAAM,GACJ;IAAC,QAAQ,EAAE,OAAO,0BAA0B,EAAE,WAAW,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IAAC,SAAS,EAAE;QAAC,GAAG,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAC,CAAA;CAAC,CA2D7J;AAED;;;;;;;GAOG;AACH,0DALW,iBAAiB,EAAE,cACnB,OAAO,4BAA4B,EAAE,mBAAmB,SACxD,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;;;GAQG;AACH,qDALW,OAAO,6BAA6B,EAAE,YAAY,aAClD,iBAAiB,EAAE,cACnB,OAAO,4BAA4B,EAAE,mBAAmB,GACtD,YAAY,CAyCxB;;;;;eAxTa,MAAM;;;;aACN,MAAM;;;;WACN,MAAM;;;;;WACN,MAAM;;;;UAEN,YAAY;;;;;eACZ,UAAU;;;;;kBAEV,MAAM,OAAO,4CAA4C,EAAE,mBAAmB,CAAC"}

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

@@ -0,0 +1,410 @@
+import { assert } from "../../../core/assert.js";
+import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
+import { TREE_LOD_ERROR_FINEST, TREE_LOD_ERROR_STEP } from "../config/TreeLODConfig.js";
+import { tree_cluster_hang } from "../mesh/tree_clusters.js";
+import { shoot_locate_on_chain } from "../skeleton/shoot_geometry.js";
+import { tree_branch_placement_apply, tree_branch_turn, tree_skeleton_copy_branch } from "../skeleton/tree_skeleton_copy_branches.js";
+import { tree_skeleton_extend_branch } from "../skeleton/tree_skeleton_extend_branch.js";
+import { tree_skeleton_floor_girth } from "../skeleton/tree_skeleton_floor_girth.js";
+import { tree_skeleton_read_joint_motion } from "../skeleton/tree_skeleton_read_joint_motion.js";
+
+const SCRATCH_A = new Float64Array(3);
+const SCRATCH_B = new Float64Array(3);
+const SCRATCH_V = new Float64Array(3);
+const SCRATCH_NODES = [];
+const SCRATCH_EDGES = [];
+
+/**
+ * @typedef {Object} TreeShootInstance
+ * @property {number} prototype index into `TreeShootPrototypes.prototypes`
+ * @property {number} carrier the tree's branch it is drawn on
+ * @property {number} scale `TREE_LOD_ERROR_STEP ^ shift`: wood, girth, leaves and cards alike
+ * @property {number} shift the steps of the error ladder its scale is: at the tree's error, the prototype's cuts `shift`
+ *           steps finer are drawn, as large
+ * @property {Float64Array} turn row-major 3x3, a turn about the vertical: the prototype's carrier's heading onto the tree's
+ * @property {Int32Array} branch_of per branch of the prototype in the sheet (from its `first`), its branch in the tree,
+ *           or -1 for wood no LOD draws, which the prototype's cuts alone draw
+ * @property {Array<import("../skeleton/tree_skeleton_copy_branches.js").TreeBranchPlacement>} placement_of per branch
+ *           of the prototype, where it is carried onto the tree: grafted as, or, undrawn, drawn as
+ */
+
+/**
+ * Draws a species' shoot prototypes on a tree grown by its generator graph (TWO_FRONT_ENDS_BRIEF_2026_10_28.md, G3).
+ * Every living carrier of a shoot rule's `source` takes the prototype of its generator whose carrier's length is nearest
+ * its own, in ratio (`tree_shoot_prototypes`).
+ *
+ * - **Scaled by the ladder.** The ratio is drawn as the nearest power of the error ladder's step: within the spread the
+ *   species' leaves grow to, 1, so the prototype is drawn as it grew. Wood, girth, leaves and cards are scaled alike,
+ *   so at the tree's error the tree draws as wood exactly what the prototype's cuts that many steps finer leave to wood.
+ * - **Turned about the vertical only**, from the prototype's carrier's heading to the tree's: up stays up, as the
+ *   prototype's leaves were lit and baked.
+ * - **The carrier** keeps its own course in the tree. It takes the prototype's growth past its framework's tip, turned
+ *   to carry on from the tree's carrier's tip, its annual units and its girth.
+ * - **The wood any LOD draws** (`TreeShootPrototypes.drawn`) is grafted onto it, each shoot system hung on the tree's
+ *   carrier where it hangs on the prototype's (`tree_skeleton_copy_branch`): the rig, the bark and the LOD plan take it
+ *   as the tree's own. Its leaf the tree holds by its annual units, as the prototype's wood held it.
+ * - **The rest** the prototype's cuts draw (`tree_shoot_instance_cards`); its leaf loads the segment it hangs from
+ *   (`TreeSkeleton.segment_carried_leaf_area`). Every branch of an instance is marked (`TreeSkeleton.branch_instance`),
+ *   so the tree's own leaves leave it to the prototype.
+ * - **Its girth holds together**: every branch is at least as thick as what grows from it (`tree_skeleton_floor_girth`).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton the tree's framework, grafted onto in place
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @returns {TreeShootInstance[]}
+ */
+export function tree_shoot_instances(skeleton, prototypes) {
+    const by_generator = new Map();
+    prototypes.prototypes.forEach((q, i) => {
+        let list = by_generator.get(q.generator);
+        if (list === undefined) by_generator.set(q.generator, list = []);
+        list.push(i);
+    });
+    /** @type {TreeShootInstance[]} */
+    const instances = [];
+    const framework_count = skeleton.branch_count;
+    for (let c = 0; c < framework_count; c++) {
+        const of_generator = by_generator.get(skeleton.branch_generator[c]);
+        const length = skeleton.branch_length[c];
+        if (of_generator === undefined || skeleton.branch_dead[c] || !(length > 0)) continue;
+        // the nearest in ratio
+        let best = -1, best_d = Infinity;
+        for (const i of of_generator) {
+            const d = Math.abs(Math.log(length / prototypes.prototypes[i].length));
+            if (d < best_d) {
+                best = i;
+                best_d = d;
+            }
+        }
+        instances.push(graft(skeleton, prototypes, best, c, instances.length));
+    }
+    tree_skeleton_floor_girth(skeleton);
+    return instances;
+}
+
+/**
+ * Places prototype `index` on carrier `carrier` of `skeleton`.
+ *
+ * @returns {TreeShootInstance}
+ */
+function graft(skeleton, prototypes, index, carrier, instance) {
+    const sheet = prototypes.sheet;
+    const q = prototypes.prototypes[index];
+    const shift = Math.round(Math.log(skeleton.branch_length[carrier] / q.length) / Math.log(TREE_LOD_ERROR_STEP));
+    const scale = Math.pow(TREE_LOD_ERROR_STEP, shift);
+
+    // turned about the vertical, its carrier's heading onto the tree's
+    const from = new Float64Array(3), to = new Float64Array(3);
+    sheet.node_read_position(from, 0, sheet.branch_root_vertex[q.first]);
+    skeleton.node_read_position(to, 0, skeleton.branch_root_vertex[carrier]);
+    const yaw = heading(skeleton, skeleton.branch_root_vertex[carrier]) - heading(sheet, sheet.branch_root_vertex[q.first]);
+    const cos = Math.cos(yaw), sin = Math.sin(yaw);
+    const turn = Float64Array.of(cos, 0, sin, 0, 1, 0, -sin, 0, cos);
+    const carry = { turn, scale, from, to };
+
+    // the carrier's growth past its framework's tip, carried on from the tree's carrier's tip and turned to continue it
+    sheet.collect_branch_chain(q.first, SCRATCH_NODES, SCRATCH_EDGES);
+    const nodes = SCRATCH_NODES.slice(), edges = SCRATCH_EDGES.slice();
+    const tip_t = q.length / sheet.branch_length[q.first];
+    let k0 = 0;
+    while (k0 + 1 < nodes.length && sheet.node_t_norm(nodes[k0 + 1]) <= tip_t + 1e-6) k0++;
+    if (k0 + 1 < nodes.length) {
+        const n = nodes.length - 1 - k0;
+        const points = new Float64Array((n + 1) * 3), radii = new Float64Array(n + 1), lengths = new Float64Array(n);
+        const host_tip = skeleton.branch_tip_vertex[carrier];
+        skeleton.node_read_position(SCRATCH_B, 0, host_tip);
+        skeleton.node_read_tangent(SCRATCH_V, 0, host_tip);
+        // the turn that takes the extension's own heading at the tip onto the tree's carrier's
+        sheet.node_read_tangent(SCRATCH_A, 0, nodes[k0]);
+        tree_branch_turn(SCRATCH_A, turn);
+        const onto = turn_onto(SCRATCH_A, SCRATCH_V);
+        sheet.node_read_position(SCRATCH_A, 0, nodes[k0]);
+        const tip = Float64Array.from(SCRATCH_A);
+        points.set(SCRATCH_B, 0);
+        radii[0] = skeleton.node_read_radius(host_tip);
+        for (let k = 1; k <= n; k++) {
+            sheet.node_read_position(SCRATCH_A, 0, nodes[k0 + k]);
+            for (let d = 0; d < 3; d++) SCRATCH_A[d] -= tip[d];
+            tree_branch_turn(SCRATCH_A, turn);
+            tree_branch_turn(SCRATCH_A, onto);
+            for (let d = 0; d < 3; d++) points[k * 3 + d] = SCRATCH_B[d] + scale * SCRATCH_A[d];
+            radii[k] = sheet.node_read_radius(nodes[k0 + k]) * scale;
+            lengths[k - 1] = sheet.segment_length(edges[k0 + k - 1]) * scale;
+        }
+        tree_skeleton_extend_branch(skeleton, carrier, points, radii, lengths);
+    }
+    // its units and its girth: at the same t, as the prototype's carrier has them
+    const unit_count = sheet.branch_unit_count[q.first];
+    if (unit_count > 0) {
+        const offset = sheet.branch_unit_offset[q.first];
+        skeleton.set_branch_units(carrier, sheet.unit_start_t.subarray(offset, offset + unit_count));
+    }
+    skeleton.collect_branch_chain(carrier, SCRATCH_NODES, SCRATCH_EDGES);
+    const host_nodes = SCRATCH_NODES.slice(), host_edges = SCRATCH_EDGES.slice();
+    for (const v of host_nodes) {
+        skeleton.node_write_radius(v, radius_at(sheet, nodes, skeleton.node_t_norm(v)) * scale);
+    }
+    skeleton.branch_base_radius[carrier] = sheet.branch_base_radius[q.first] * scale;
+    skeleton.branch_instance[carrier] = instance;
+
+    // where a shoot system hanging from the carrier at `t` lands: on the tree's carrier, wherever its course leaves it
+    const on_carrier = (t) => {
+        point_on(skeleton, host_nodes, host_edges, t, SCRATCH_B);
+        point_on(sheet, nodes, edges, t, SCRATCH_A);
+        tree_branch_placement_apply(SCRATCH_A, carry);
+        return { turn, scale, from, to: Float64Array.of(to[0] + SCRATCH_B[0] - SCRATCH_A[0], to[1] + SCRATCH_B[1] - SCRATCH_A[1], to[2] + SCRATCH_B[2] - SCRATCH_A[2]) };
+    };
+
+    // the wood any LOD draws, hung on the tree's carrier where it hangs on the prototype's
+    const branch_of = new Int32Array(q.branch_count).fill(-1);
+    const placement_of = new Array(q.branch_count).fill(carry);
+    branch_of[0] = carrier;
+    const edge_of = new Map();
+    for (let b = q.first + 1; b < q.first + q.branch_count; b++) {
+        const i = b - q.first;
+        const pb = sheet.branch_parent[b];
+        const t = sheet.branch_parent_attach_t[b];
+        const placement = pb === q.first ? on_carrier(t) : placement_of[pb - q.first];
+        placement_of[i] = placement;
+        if (!prototypes.drawn[b]) continue;
+        const parent = branch_of[pb - q.first];
+        skeleton.collect_branch_chain(parent, SCRATCH_NODES, SCRATCH_EDGES);
+        const edge = shoot_locate_on_chain(skeleton, SCRATCH_NODES, SCRATCH_EDGES, t).edge;
+        const level = skeleton.branch_level[carrier] + sheet.branch_level[b] - sheet.branch_level[q.first];
+        const id = tree_skeleton_copy_branch(sheet, b, skeleton, parent, edge, t, skeleton.segment_v0(edge), level, placement, edge_of);
+        skeleton.branch_instance[id] = instance;
+        branch_of[i] = id;
+    }
+
+    // what it carries without the tree holding it loads the segment it hangs from
+    for (const carried of q.carried) {
+        const host = branch_of[carried.parent - q.first];
+        skeleton.collect_branch_chain(host, SCRATCH_NODES, SCRATCH_EDGES);
+        const edge = shoot_locate_on_chain(skeleton, SCRATCH_NODES, SCRATCH_EDGES, carried.t).edge;
+        skeleton.segment_carried_leaf_area[edge] += carried.leaf_area * scale * scale;
+        skeleton.segment_carried_reach[edge] = Math.max(skeleton.segment_carried_reach[edge], carried.reach * scale);
+    }
+    return { prototype: index, carrier, scale, shift, turn, branch_of, placement_of };
+}
+
+/**
+ * The cards of every instance on the tree at `error`: each prototype's cuts at the step of its error ladder `error` is
+ * (`TreeShootPrototypes.errors`, the LOD plan's own steps) less the instance's `shift`, carried as its instance carries
+ * them: from where they hang on the prototype to the same place on the tree, and skinned as the tree's drawn bark is
+ * there, or where the nearest drawn wood holds it (`tree_cluster_hang`).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton bound to the rig `rings` were planned with
+ * @param {Map<number, Array<{t_norm: number, cx: number, cy: number, cz: number}>>} rings the tree's at `error`
+ * @param {TreeShootInstance[]} instances
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @param {number} error m, a step of the error ladder
+ * @returns {{clusters: import("../mesh/tree_clusters.js").TreeCluster[], cards: Array<{cluster: number}>, placement: {rep: Int32Array, frames: Float64Array}}}
+ */
+export function tree_shoot_instance_cards(skeleton, rings, instances, prototypes, error) {
+    const step = ladder_step(error);
+    const count = tree_shoot_instance_card_count(instances, prototypes, error);
+    const clusters = new Array(count);
+    const cards = new Array(count);
+    const rep = new Int32Array(count);
+    const frames = new Float64Array(count * 12);
+    if (count === 0) return { clusters, cards, placement: { rep, frames } };
+    const joint_motion = tree_skeleton_read_joint_motion(skeleton);
+    const at = new Float64Array(3);
+    let n = 0;
+    for (const instance of instances) {
+        const k = clamp_step(prototypes, step - instance.shift);
+        const { clusters: cut, cards: cut_cards } = prototypes.atlas.lods[k];
+        const source = prototypes.atlas.representatives.placements[k];
+        const owners = prototypes.owners[k];
+        const q = prototypes.prototypes[instance.prototype];
+        for (let i = 0; i < cut_cards.length; i++) {
+            if (owners[i] !== instance.prototype) continue;
+            const from = cut[cut_cards[i].cluster];
+            // where it hangs on the tree: on the copy of its branch, or for a whole prototype where its carrier starts
+            let branch, t;
+            if (from.branch >= 0) {
+                branch = instance.branch_of[from.branch - q.first];
+                t = from.t;
+                skeleton.collect_branch_chain(branch, SCRATCH_NODES, SCRATCH_EDGES);
+                point_on(skeleton, SCRATCH_NODES, SCRATCH_EDGES, t, at);
+            } else {
+                skeleton.node_read_position(at, 0, skeleton.branch_root_vertex[instance.carrier]);
+                branch = skeleton.branch_parent[instance.carrier];
+                t = skeleton.branch_parent_attach_t[instance.carrier];
+            }
+            // skinned as the nearest drawn wood holds it
+            while (branch >= 0 && !rings.has(branch)) {
+                t = skeleton.branch_parent_attach_t[branch];
+                branch = skeleton.branch_parent[branch];
+            }
+            const cluster = { branch, t, root: branch < 0 ? 0 : -1, leaves: [], wood: [], position: new Float64Array(3), joints: new Uint16Array(4), weights: new Float32Array(4) };
+            tree_cluster_hang(skeleton, rings, joint_motion, cluster);
+            clusters[n] = cluster;
+            cards[n] = { cluster: n };
+            rep[n] = source.rep[i];
+            // its tile on the prototype's card, turned and scaled as the instance is, from where it hangs on the tree
+            const f = i * 12, g = n * 12;
+            for (let d = 0; d < 3; d++) SCRATCH_A[d] = source.frames[f + d] - from.position[d];
+            tree_branch_turn(SCRATCH_A, instance.turn);
+            for (let d = 0; d < 3; d++) frames[g + d] = at[d] + instance.scale * SCRATCH_A[d];
+            for (let axis = 1; axis < 4; axis++) {
+                for (let d = 0; d < 3; d++) SCRATCH_A[d] = source.frames[f + axis * 3 + d];
+                tree_branch_turn(SCRATCH_A, instance.turn);
+                const s = axis < 3 ? instance.scale : 1;
+                for (let d = 0; d < 3; d++) frames[g + axis * 3 + d] = s * SCRATCH_A[d];
+            }
+            n++;
+        }
+    }
+    return { clusters, cards, placement: { rep, frames } };
+}
+
+/**
+ * How many cards the instances draw at `error` (`tree_shoot_instance_cards`), for the LOD plan.
+ *
+ * @param {TreeShootInstance[]} instances
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @param {number} error m, a step of the error ladder
+ * @returns {number}
+ */
+export function tree_shoot_instance_card_count(instances, prototypes, error) {
+    // prototypes without leaves draw no cards
+    if (prototypes.atlas === null) return 0;
+    const step = ladder_step(error);
+    let count = 0;
+    for (const instance of instances) {
+        const owners = prototypes.owners[clamp_step(prototypes, step - instance.shift)];
+        for (let i = 0; i < owners.length; i++) {
+            if (owners[i] === instance.prototype) count++;
+        }
+    }
+    return count;
+}
+
+/**
+ * Every leaf's card the instances draw, carried onto the tree as they are (for `tree_grown_side_area`): positions,
+ * `3` per vertex. A leaf on a carrier lands where the carrier runs on the tree.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton the tree the instances are on
+ * @param {TreeShootInstance[]} instances
+ * @param {import("./tree_shoot_prototypes.js").TreeShootPrototypes} prototypes
+ * @returns {Float32Array}
+ */
+export function tree_shoot_instance_leaves(skeleton, instances, prototypes) {
+    const { attachments, leaves, sheet } = prototypes;
+    if (leaves === null) return new Float32Array(0);
+    const positions = leaves.getAttribute(StandardAttributes.Position).data;
+    const per_leaf = positions.length / 3 / attachments.count;
+    const of_prototype = prototypes.prototypes.map(() => []);
+    for (const instance of instances) of_prototype[instance.prototype].push(instance);
+    let count = 0;
+    for (let a = 0; a < attachments.count; a++) count += of_prototype[prototypes.prototype_of[attachments.carriers[a]]].length;
+    const out = new Float32Array(count * per_leaf * 3);
+    const proto_nodes = [], proto_edges = [], host_nodes = [], host_edges = [];
+    let o = 0;
+    for (let a = 0; a < attachments.count; a++) {
+        const b = attachments.carriers[a];
+        const q = prototypes.prototypes[prototypes.prototype_of[b]];
+        const on_carrier = b === q.first;
+        if (on_carrier) sheet.collect_branch_chain(b, proto_nodes, proto_edges);
+        for (const instance of of_prototype[prototypes.prototype_of[b]]) {
+            let placement = instance.placement_of[b - q.first];
+            if (on_carrier) {
+                // where the carrier runs on the tree, at the leaf's place along it
+                skeleton.collect_branch_chain(instance.carrier, host_nodes, host_edges);
+                point_on(skeleton, host_nodes, host_edges, attachments.attach_t[a], SCRATCH_B);
+                point_on(sheet, proto_nodes, proto_edges, attachments.attach_t[a], SCRATCH_A);
+                tree_branch_placement_apply(SCRATCH_A, placement);
+                placement = { ...placement, to: Float64Array.of(placement.to[0] + SCRATCH_B[0] - SCRATCH_A[0], placement.to[1] + SCRATCH_B[1] - SCRATCH_A[1], placement.to[2] + SCRATCH_B[2] - SCRATCH_A[2]) };
+            }
+            for (let v = a * per_leaf; v < (a + 1) * per_leaf; v++) {
+                SCRATCH_V[0] = positions[v * 3];
+                SCRATCH_V[1] = positions[v * 3 + 1];
+                SCRATCH_V[2] = positions[v * 3 + 2];
+                tree_branch_placement_apply(SCRATCH_V, placement);
+                out[o++] = SCRATCH_V[0];
+                out[o++] = SCRATCH_V[1];
+                out[o++] = SCRATCH_V[2];
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * The step of the error ladder `error` is.
+ * @param {number} error
+ * @returns {number}
+ */
+function ladder_step(error) {
+    const exact = Math.log(error / TREE_LOD_ERROR_FINEST) / Math.log(TREE_LOD_ERROR_STEP);
+    const k = Math.round(exact);
+    assert.lessThan(Math.abs(exact - k), 1e-6, 'error is a step of the ladder');
+    return k;
+}
+
+/**
+ * A step of the prototypes' cuts: theirs, or the nearest they were cut at.
+ * @returns {number}
+ */
+function clamp_step(prototypes, k) {
+    return Math.max(0, Math.min(prototypes.errors.length - 1, k));
+}
+
+/**
+ * Azimuth of node `v`'s heading about the vertical, rad: of its tangent, or of its frame's radial where it stands
+ * upright.
+ * @returns {number}
+ */
+function heading(skeleton, v) {
+    skeleton.node_read_tangent(SCRATCH_A, 0, v);
+    if (Math.hypot(SCRATCH_A[0], SCRATCH_A[2]) < 1e-3) skeleton.node_read_frame_r(SCRATCH_A, 0, v);
+    return Math.atan2(SCRATCH_A[0], SCRATCH_A[2]);
+}
+
+/**
+ * The point at `t` along the chain `nodes`, `edges` into `out` (`shoot_locate_on_chain`).
+ */
+function point_on(skeleton, nodes, edges, t, out) {
+    const { edge, u } = shoot_locate_on_chain(skeleton, nodes, edges, t);
+    skeleton.evaluate_segment_position(out, 0, edge, u);
+}
+
+/**
+ * The radius of the branch whose chain is `nodes` at `t`.
+ * @returns {number}
+ */
+function radius_at(skeleton, nodes, t) {
+    for (let i = 0; i + 1 < nodes.length; i++) {
+        const t0 = skeleton.node_t_norm(nodes[i]), t1 = skeleton.node_t_norm(nodes[i + 1]);
+        if (t <= t1) {
+            const u = Math.min(1, Math.max(0, (t - t0) / Math.max(1e-9, t1 - t0)));
+            return skeleton.node_read_radius(nodes[i]) + u * (skeleton.node_read_radius(nodes[i + 1]) - skeleton.node_read_radius(nodes[i]));
+        }
+    }
+    return skeleton.node_read_radius(nodes[nodes.length - 1]);
+}
+
+/**
+ * The least turn (row-major 3x3) taking direction `a` onto direction `b`.
+ * @returns {Float64Array}
+ */
+function turn_onto(a, b) {
+    const la = Math.hypot(a[0], a[1], a[2]), lb = Math.hypot(b[0], b[1], b[2]);
+    const ax = a[0] / la, ay = a[1] / la, az = a[2] / la, bx = b[0] / lb, by = b[1] / lb, bz = b[2] / lb;
+    const vx = ay * bz - az * by, vy = az * bx - ax * bz, vz = ax * by - ay * bx;
+    const c = ax * bx + ay * by + az * bz;
+    if (c < -1 + 1e-9) {
+        // opposite: half a turn about an axis across them
+        const px = Math.abs(ax) < 0.9 ? 1 : 0, py = Math.abs(ax) < 0.9 ? 0 : 1;
+        const kx = -az * py, ky = az * px, kz = ax * py - ay * px;
+        const l = Math.hypot(kx, ky, kz);
+        const x = kx / l, y = ky / l, z = kz / l;
+        return Float64Array.of(2 * x * x - 1, 2 * x * y, 2 * x * z, 2 * x * y, 2 * y * y - 1, 2 * y * z, 2 * x * z, 2 * y * z, 2 * z * z - 1);
+    }
+    const k = 1 / (1 + c);
+    return Float64Array.of(
+        c + vx * vx * k, vx * vy * k - vz, vx * vz * k + vy,
+        vx * vy * k + vz, c + vy * vy * k, vy * vz * k - vx,
+        vx * vz * k - vy, vy * vz * k + vx, c + vz * vz * k
+    );
+}