@woosh/meep-engine 3.52.0 → 3.54.0

package/src/generation/foliage/mesh/tree_mesh_build_foliage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Synthesizes the foliage `Geometry` for a given LOD from a `FoliageAttachmentSet`,
+ * applying golden-ratio low-discrepancy LOD decimation ($h_i < k_{\text{keep}}$),
+ * optical area-compensation scaling ($s_{\text{comp}} = k_{\text{keep}}^{-\eta}$),
+ * botanical 3D card geometry (`FoldedVCard`, `CrossCard`, `TriStarCluster`, `RibbedFrond`, `OctagonalCutoutHull`),
+ * MaxRect-packed ontogenetic variant UV remapping, hemisphere-safe normal puffing,
+ * volumetric canopy AO, and 4-joint skeletal wind skinning.
+ *
+ * Returns `null` if foliage is disabled or `lod_config.foliage_keep_ratio <= 0` or `attachments.count === 0`.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {TreeSpeciesConfig} [config]
+ * @param {TreeLODConfig} [lod_config]
+ * @param {Geometry} [out]
+ * @returns {Geometry|null}
+ */
+export function tree_mesh_build_foliage(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, attachments: import("./foliage_collect_attachments.js").FoliageAttachmentSet, config?: TreeSpeciesConfig, lod_config?: TreeLODConfig, out?: Geometry): Geometry | null;
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { TreeLODConfig } from "../config/TreeLODConfig.js";
+import { Geometry } from "../../../shade/renderer/geometry/Geometry.js";
+//# sourceMappingURL=tree_mesh_build_foliage.d.ts.map

package/src/generation/foliage/mesh/tree_mesh_build_foliage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_mesh_build_foliage.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/mesh/tree_mesh_build_foliage.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;GAgBG;AACH,kDAPW,OAAO,6BAA6B,EAAE,YAAY,eAClD,OAAO,kCAAkC,EAAE,oBAAoB,WAC/D,iBAAiB,eACjB,aAAa,QACb,QAAQ,GACN,QAAQ,GAAC,IAAI,CAuazB;kCA3biC,gCAAgC;8BADpC,4BAA4B;yBAPjC,8CAA8C"}

package/src/generation/foliage/mesh/tree_mesh_build_foliage.js

@@ -0,0 +1,454 @@
+import { clamp } from "../../../core/math/clamp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { Geometry } from "../../../shade/renderer/geometry/Geometry.js";
+import {
+	geometry_obtain_attribute,
+	geometry_obtain_index
+} from "../../../shade/renderer/geometry/geometry_obtain_attribute.js";
+import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
+import { FoliageCardType } from "../config/FoliageCardType.js";
+import { TreeLODConfig } from "../config/TreeLODConfig.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { compute_foliage_variant_atlas_layout } from "../material/make_foliage_material.js";
+import { tree_mesh_apply_canopy_ao } from "./tree_mesh_apply_canopy_ao.js";
+import { geometry_obtain_joints_attribute } from "./tree_mesh_build_bark.js";
+
+/**
+ * Synthesizes the foliage `Geometry` for a given LOD from a `FoliageAttachmentSet`,
+ * applying golden-ratio low-discrepancy LOD decimation ($h_i < k_{\text{keep}}$),
+ * optical area-compensation scaling ($s_{\text{comp}} = k_{\text{keep}}^{-\eta}$),
+ * botanical 3D card geometry (`FoldedVCard`, `CrossCard`, `TriStarCluster`, `RibbedFrond`, `OctagonalCutoutHull`),
+ * MaxRect-packed ontogenetic variant UV remapping, hemisphere-safe normal puffing,
+ * volumetric canopy AO, and 4-joint skeletal wind skinning.
+ *
+ * Returns `null` if foliage is disabled or `lod_config.foliage_keep_ratio <= 0` or `attachments.count === 0`.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("./foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {TreeSpeciesConfig} [config]
+ * @param {TreeLODConfig} [lod_config]
+ * @param {Geometry} [out]
+ * @returns {Geometry|null}
+ */
+export function tree_mesh_build_foliage(
+	skeleton,
+	attachments,
+	config = new TreeSpeciesConfig(),
+	lod_config = new TreeLODConfig(),
+	out = new Geometry()
+) {
+	const species = config && config.isTreeSpeciesConfig ? config : TreeSpeciesConfig.from(config);
+	const lod_cfg = lod_config && lod_config.isTreeLODConfig ? lod_config : TreeLODConfig.from(lod_config);
+	const fol = species.foliage;
+	const keep_ratio = clamp(lod_cfg.foliage_keep_ratio ?? 1.0, 0.0, 1.0);
+	if (!fol.enabled || !attachments || attachments.count === 0 || keep_ratio <= 0.0) {
+		return null;
+	}
+
+	// Filter active attachment indices by golden-ratio rank
+	const active_indices = [];
+	for (let i = 0; i < attachments.count; i++) {
+		if (attachments.ranks[i] < keep_ratio) {
+			active_indices.push(i);
+		}
+	}
+	if (active_indices.length === 0 && attachments.count > 0) {
+		active_indices.push(0);
+	}
+	const card_count = active_indices.length;
+
+	// Area compensation scale: k_keep^(-eta)
+	const eta = clamp(lod_cfg.foliage_area_compensation_exponent ?? 0.42, 0.0, 0.6);
+	const area_comp = Math.pow(Math.max(0.08, keep_ratio), -eta);
+
+	// Determine effective card type for this LOD
+	let card_type = fol.card_type;
+	if (lod_cfg.simplify_cards) {
+		card_type = FoliageCardType.FoldedVCard;
+	}
+
+	const frond_segs = Math.max(2, fol.frond_segments | 0);
+	let verts_per_card = 6;
+	let tris_per_card = 4;
+
+	switch (card_type) {
+		case FoliageCardType.CrossCard:
+			verts_per_card = 8;
+			tris_per_card = 4;
+			break;
+		case FoliageCardType.TriStarCluster:
+			verts_per_card = 12;
+			tris_per_card = 6;
+			break;
+		case FoliageCardType.RibbedFrond:
+			verts_per_card = 3 * (frond_segs + 1);
+			tris_per_card = 4 * frond_segs;
+			break;
+		case FoliageCardType.OctagonalCutoutHull:
+			verts_per_card = 7;
+			tris_per_card = 6;
+			break;
+		case FoliageCardType.FoldedVCard:
+		default:
+			verts_per_card = 6;
+			tris_per_card = 4;
+			break;
+	}
+
+	const total_vertices = card_count * verts_per_card;
+	const total_indices = card_count * tris_per_card * 3;
+
+	const positions = geometry_obtain_attribute(out, StandardAttributes.Position, 3, total_vertices);
+	const normals = geometry_obtain_attribute(out, StandardAttributes.Normal, 3, total_vertices);
+	const uv0 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates0, 2, total_vertices);
+	const uv1 = geometry_obtain_attribute(out, StandardAttributes.TextureCoordinates1, 2, total_vertices);
+	const colors = geometry_obtain_attribute(out, StandardAttributes.Color, 3, total_vertices);
+	const joints = geometry_obtain_joints_attribute(out, total_vertices);
+	const weights = geometry_obtain_attribute(out, StandardAttributes.SkinningWeights, 4, total_vertices);
+	const indices = geometry_obtain_index(out, total_indices);
+
+	const fol_mat = species.foliage_material;
+	const layout = compute_foliage_variant_atlas_layout(
+		fol_mat?.resolution ?? 128,
+		fol_mat?.variant_count ?? 4
+	);
+	const uv_rects = layout.uv_rects;
+	const variant_count = layout.variant_count;
+
+	const base_w = Math.max(0.05, fol.card_width) * area_comp;
+	const base_l = Math.max(0.05, fol.card_length) * area_comp;
+	const fold_angle = clamp(fol.fold_angle, 0.0, 0.65);
+	const sin_fold = Math.sin(fold_angle);
+	const cos_fold = Math.cos(fold_angle);
+	const arch_h = fol.arch_height;
+	const droop = fol.camber_droop;
+	const color_var_amp = clamp(fol.color_variation ?? 0.08, 0.0, 0.35);
+	const anchor_u = clamp(fol_mat?.stem_anchor_u ?? 0.5, 0.1, 0.9);
+	const anchor_v = clamp(fol_mat?.stem_anchor_v ?? 0.0, 0.0, 0.25);
+	const juv_shift = clamp(fol_mat?.juvenile_color_shift ?? 0.38, 0.0, 1.0);
+	const senescence = clamp(Math.max(fol_mat?.senescence ?? 0.0, fol_mat?.autumn_tint ?? 0.0), 0.0, 1.0);
+	const antho_pot = clamp(fol_mat?.anthocyanin_potential ?? 0.35, 0.0, 1.0);
+
+	let v_cursor = 0;
+	let i_cursor = 0;
+	let rect_u0 = 0.0;
+	let rect_v0 = 0.0;
+	let rect_u1 = 1.0;
+	let rect_v1 = 1.0;
+
+	/**
+	 * Helper to write a single foliage vertex in card-local coordinates `(x_w, y_u, z_f)`
+	 * and local normal `(nx_w, ny_u, nz_f)`, remapping local `[0, 1]^2` card UVs into the
+	 * card's assigned MaxRect-packed atlas tile `[rect_u0, rect_v0, rect_u1, rect_v1]`.
+	 */
+	const write_card_vertex = (
+		px0, py0, pz0,
+		wx, wy, wz,
+		ux, uy, uz,
+		fx, fy, fz,
+		x_w, y_u, z_f,
+		nx_w, ny_u, nz_f,
+		u_tex, v_tex,
+		flutter_w, phase_w,
+		r_col, g_col, b_col,
+		j0, j1, j2, j3,
+		w0, w1, w2, w3
+	) => {
+		const v3 = v_cursor * 3;
+		const v2 = v_cursor * 2;
+		const v4 = v_cursor * 4;
+
+		positions[v3] = px0 + wx * x_w + ux * y_u + fx * z_f;
+		positions[v3 + 1] = py0 + wy * x_w + uy * y_u + fy * z_f;
+		positions[v3 + 2] = pz0 + wz * x_w + uz * y_u + fz * z_f;
+
+		let gnx = wx * nx_w + ux * ny_u + fx * nz_f;
+		let gny = wy * nx_w + uy * ny_u + fy * nz_f;
+		let gnz = wz * nx_w + uz * ny_u + fz * nz_f;
+		const nl = Math.sqrt(gnx * gnx + gny * gny + gnz * gnz);
+		if (nl > 1e-8) {
+			gnx /= nl;
+			gny /= nl;
+			gnz /= nl;
+		}
+		normals[v3] = gnx;
+		normals[v3 + 1] = gny;
+		normals[v3 + 2] = gnz;
+
+		uv0[v2] = lerp(rect_u0, rect_u1, u_tex);
+		uv0[v2 + 1] = lerp(rect_v0, rect_v1, v_tex);
+
+		uv1[v2] = clamp(flutter_w, 0.0, 1.0);
+		uv1[v2 + 1] = clamp(phase_w, 0.0, 1.0);
+
+		colors[v3] = r_col;
+		colors[v3 + 1] = g_col;
+		colors[v3 + 2] = b_col;
+
+		joints[v4] = j0;
+		joints[v4 + 1] = j1;
+		joints[v4 + 2] = j2;
+		joints[v4 + 3] = j3;
+
+		weights[v4] = w0;
+		weights[v4 + 1] = w1;
+		weights[v4 + 2] = w2;
+		weights[v4 + 3] = w3;
+
+		return v_cursor++;
+	};
+
+	const has_j4 = Boolean(attachments.joints4 && attachments.weights4 && attachments.joints4.length >= attachments.count * 4);
+	const has_variants = Boolean(attachments.variant_indices && attachments.variant_indices.length >= attachments.count);
+	const has_maturities = Boolean(attachments.maturities && attachments.maturities.length >= attachments.count);
+	const has_sun = Boolean(attachments.sun_exposure && attachments.sun_exposure.length >= attachments.count);
+
+	for (let c = 0; c < card_count; c++) {
+		const att_idx = active_indices[c];
+		const a3 = att_idx * 3;
+		const a2 = att_idx * 2;
+		const a4 = att_idx * 4;
+
+		const px0 = attachments.positions[a3];
+		const py0 = attachments.positions[a3 + 1];
+		const pz0 = attachments.positions[a3 + 2];
+
+		const fx = attachments.forward[a3];
+		const fy = attachments.forward[a3 + 1];
+		const fz = attachments.forward[a3 + 2];
+
+		const ux = attachments.up[a3];
+		const uy = attachments.up[a3 + 1];
+		const uz = attachments.up[a3 + 2];
+
+		const wx = attachments.right[a3];
+		const wy = attachments.right[a3 + 1];
+		const wz = attachments.right[a3 + 2];
+
+		const maturity = has_maturities ? attachments.maturities[att_idx] : 0.5;
+		const sun_exp = has_sun ? attachments.sun_exposure[att_idx] : 0.65;
+		const v_idx = has_variants
+			? clamp(attachments.variant_indices[att_idx], 0, variant_count - 1)
+			: clamp(Math.floor(maturity * variant_count), 0, variant_count - 1);
+		const r4 = v_idx * 4;
+		rect_u0 = uv_rects[r4];
+		rect_v0 = uv_rects[r4 + 1];
+		rect_u1 = uv_rects[r4 + 2];
+		rect_v1 = uv_rects[r4 + 3];
+
+		const scale = attachments.scales[att_idx];
+		const card_w = base_w * scale;
+		const card_l = base_l * scale;
+		const half_w = card_w * 0.5;
+		const left_w = -card_w * anchor_u;
+		const right_w = card_w * (1.0 - anchor_u);
+
+		const phase = attachments.phases[att_idx];
+		const b_sway = attachments.branch_sway[att_idx];
+		const c_jit = attachments.color_jitter[att_idx] * color_var_amp;
+
+		// Continuous ontogenetic & crown-shell photoprotective modulation in vertex colors
+		const juv_lift = (0.5 - maturity) * juv_shift * 0.14;
+		let r_col = clamp(1.0 + c_jit * 1.1 + juv_lift * 0.9, 0.68, 1.0);
+		let g_col = clamp(1.0 + c_jit * 0.8 + juv_lift * 1.1, 0.68, 1.0);
+		let b_col = clamp(1.0 - c_jit * 0.6 - juv_lift * 0.5, 0.68, 1.0);
+
+		if (senescence > 1e-4) {
+			// Sun-exposed outer crown shell expresses stronger anthocyanin/carotenoid warmth than shaded interior
+			const shade_cool = (1.0 - sun_exp) * senescence * 0.22;
+			const sun_antho = sun_exp * senescence * antho_pot * 0.25;
+			r_col = clamp(r_col * (1.0 - shade_cool * 0.45 + sun_antho * 0.18), 0.65, 1.0);
+			g_col = clamp(g_col * (1.0 + shade_cool * 0.15 - sun_antho * 0.35), 0.55, 1.0);
+			b_col = clamp(b_col * (1.0 - sun_antho * 0.30), 0.55, 1.0);
+		}
+
+		const j0 = has_j4 ? attachments.joints4[a4] : attachments.joints[a2];
+		const j1 = has_j4 ? attachments.joints4[a4 + 1] : attachments.joints[a2 + 1];
+		const j2 = has_j4 ? attachments.joints4[a4 + 2] : 0;
+		const j3 = has_j4 ? attachments.joints4[a4 + 3] : 0;
+		const w0 = has_j4 ? attachments.weights4[a4] : attachments.weights[a2];
+		const w1 = has_j4 ? attachments.weights4[a4 + 1] : attachments.weights[a2 + 1];
+		const w2 = has_j4 ? attachments.weights4[a4 + 2] : 0.0;
+		const w3 = has_j4 ? attachments.weights4[a4 + 3] : 0.0;
+
+		const base_v = v_cursor;
+
+		if (card_type === FoliageCardType.CrossCard) {
+			// Plane 0: horizontal (W, F) with normal +U (since W x F = +U)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, left_w, 0, 0, 0, 1, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, right_w, 0, 0, 0, 1, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, left_w, 0, card_l, 0, 1, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, right_w, 0, card_l, 0, 1, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 2;
+
+			// Plane 1: vertical (-U to +U, F) with normal +W (since (-U) x F = +W)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -left_w, 0, 1, 0, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -right_w, 0, 1, 0, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -left_w, card_l, 1, 0, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0, -right_w, card_l, 1, 0, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 5;
+			indices[i_cursor++] = base_v + 7;
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 7;
+			indices[i_cursor++] = base_v + 6;
+		} else if (card_type === FoliageCardType.TriStarCluster) {
+			for (let p = 0; p < 3; p++) {
+				const ang = (p * Math.PI) / 3.0;
+				const ca = Math.cos(ang);
+				const sa = Math.sin(ang);
+				const p_left_x = ca * left_w;
+				const p_left_y = sa * left_w;
+				const p_right_x = ca * right_w;
+				const p_right_y = sa * right_w;
+				const pn_x = -sa;
+				const pn_y = ca;
+				const p_base = base_v + p * 4;
+
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_left_x, p_left_y, 0, pn_x, pn_y, 0, 0.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_right_x, p_right_y, 0, pn_x, pn_y, 0, 1.0, anchor_v, b_sway * 0.4, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_left_x, p_left_y, card_l, pn_x, pn_y, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, p_right_x, p_right_y, card_l, pn_x, pn_y, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+				indices[i_cursor++] = p_base + 0;
+				indices[i_cursor++] = p_base + 1;
+				indices[i_cursor++] = p_base + 3;
+				indices[i_cursor++] = p_base + 0;
+				indices[i_cursor++] = p_base + 3;
+				indices[i_cursor++] = p_base + 2;
+			}
+		} else if (card_type === FoliageCardType.RibbedFrond) {
+			const lift_wing = half_w * sin_fold;
+			const span_w = half_w * cos_fold;
+
+			for (let s = 0; s <= frond_segs; s++) {
+				const t = s / frond_segs;
+				const v_tex = anchor_v + (1.0 - anchor_v) * t;
+				const z_s = t * card_l;
+				const y_spine = card_l * (arch_h * 4.0 * t * (1.0 - t) - droop * t * t);
+				const env_w = Math.sin(Math.PI * (0.12 + 0.82 * t));
+				const w_s = span_w * env_w;
+				const lift_s = lift_wing * env_w;
+				const flutter = clamp(b_sway * 0.3 + 0.7 * t, 0.0, 1.0);
+
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -w_s, y_spine + lift_s, z_s, -sin_fold * 0.35, cos_fold, 0, 0.0, v_tex, flutter, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, y_spine, z_s, 0.0, 1.0, 0, anchor_u, v_tex, flutter * 0.75, phase, r_col * 0.94, g_col * 0.94, b_col * 0.94, j0, j1, j2, j3, w0, w1, w2, w3);
+				write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, w_s, y_spine + lift_s, z_s, sin_fold * 0.35, cos_fold, 0, 1.0, v_tex, flutter, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+				if (s > 0) {
+					const r0 = base_v + (s - 1) * 3;
+					const r1 = base_v + s * 3;
+					indices[i_cursor++] = r0 + 0;
+					indices[i_cursor++] = r0 + 1;
+					indices[i_cursor++] = r1 + 1;
+					indices[i_cursor++] = r0 + 0;
+					indices[i_cursor++] = r1 + 1;
+					indices[i_cursor++] = r1 + 0;
+
+					indices[i_cursor++] = r0 + 1;
+					indices[i_cursor++] = r0 + 2;
+					indices[i_cursor++] = r1 + 2;
+					indices[i_cursor++] = r0 + 1;
+					indices[i_cursor++] = r1 + 2;
+					indices[i_cursor++] = r1 + 1;
+				}
+			}
+		} else if (card_type === FoliageCardType.OctagonalCutoutHull) {
+			const lift = half_w * sin_fold * 0.7;
+			const span = half_w * cos_fold;
+			const camber = card_l * arch_h;
+
+			// v0: base petiole (0, 0, 0) at exact UV (anchor_u, anchor_v)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, 0.0, 0.0, 0, 1, 0, anchor_u, anchor_v, b_sway * 0.25, phase, r_col * 0.9, g_col * 0.9, b_col * 0.9, j0, j1, j2, j3, w0, w1, w2, w3);
+			// v1: lower-left
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span * 0.85, lift * 0.7, card_l * 0.28, -sin_fold * 0.3, cos_fold, 0, 0.08, 0.28, b_sway * 0.55, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			// v2: lower-right
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span * 0.85, lift * 0.7, card_l * 0.28, sin_fold * 0.3, cos_fold, 0, 0.92, 0.28, b_sway * 0.55, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			// v3: center midrib
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, camber, card_l * 0.52, 0, 1, 0, anchor_u, 0.52, b_sway * 0.65, phase, r_col * 0.96, g_col * 0.96, b_col * 0.96, j0, j1, j2, j3, w0, w1, w2, w3);
+			// v4: upper-left
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift, card_l * 0.74, -sin_fold * 0.3, cos_fold, 0, 0.04, 0.74, 0.9, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			// v5: upper-right
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift, card_l * 0.74, sin_fold * 0.3, cos_fold, 0, 0.96, 0.74, 0.9, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			// v6: apex tip
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, -card_l * droop * 0.5, card_l, 0, 1, 0, anchor_u, 0.98, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			// 6 outward (+U) triangles fanning around center midrib v3
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 2;
+			indices[i_cursor++] = base_v + 3;
+
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 1;
+
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 2;
+			indices[i_cursor++] = base_v + 5;
+
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 5;
+			indices[i_cursor++] = base_v + 6;
+
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 6;
+			indices[i_cursor++] = base_v + 4;
+
+			indices[i_cursor++] = base_v + 3;
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 1;
+		} else {
+			// Default: FoldedVCard (6 vertices, 4 triangles)
+			const lift = half_w * sin_fold;
+			const span = half_w * cos_fold;
+			const tip_droop = -card_l * droop * 0.5;
+			const mid_arch = card_l * arch_h * 0.5;
+
+			// Row 0 (base, z = 0)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift, 0.0, -sin_fold * 0.35, cos_fold, 0, 0.0, anchor_v, b_sway * 0.45, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, 0.0, 0.0, 0.0, 1.0, 0, anchor_u, anchor_v, b_sway * 0.25, phase, r_col * 0.92, g_col * 0.92, b_col * 0.92, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift, 0.0, sin_fold * 0.35, cos_fold, 0, 1.0, anchor_v, b_sway * 0.45, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			// Row 1 (tip, z = card_l)
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, -span, lift + tip_droop, card_l, -sin_fold * 0.35, cos_fold, 0, 0.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, 0.0, mid_arch + tip_droop, card_l, 0.0, 1.0, 0, anchor_u, 1.0, 0.85, phase, r_col * 0.96, g_col * 0.96, b_col * 0.96, j0, j1, j2, j3, w0, w1, w2, w3);
+			write_card_vertex(px0, py0, pz0, wx, wy, wz, ux, uy, uz, fx, fy, fz, span, lift + tip_droop, card_l, sin_fold * 0.35, cos_fold, 0, 1.0, 1.0, 1.0, phase, r_col, g_col, b_col, j0, j1, j2, j3, w0, w1, w2, w3);
+
+			// Left wing quad
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 0;
+			indices[i_cursor++] = base_v + 4;
+			indices[i_cursor++] = base_v + 3;
+
+			// Right wing quad
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 2;
+			indices[i_cursor++] = base_v + 5;
+			indices[i_cursor++] = base_v + 1;
+			indices[i_cursor++] = base_v + 5;
+			indices[i_cursor++] = base_v + 4;
+		}
+	}
+
+	// Apply volumetric canopy AO and hemisphere-safe normal puffing BEFORE ensureTangents()
+	tree_mesh_apply_canopy_ao(out, skeleton.crown_center, skeleton.crown_radii, {
+		ao_core_darkening: fol.ao_core_darkening ?? 0.35,
+		normal_puffiness: fol.normal_puffiness ?? 0.35,
+		preserve_existing_color: true
+	});
+
+	out.name = `${species.name || "tree"}_foliage_lod${lod_cfg.level}`;
+	out.ensureBounds();
+	out.ensureTangents();
+
+	return out;
+}

package/src/generation/foliage/presets/make_tree_species_preset.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns a rich, botanically tuned `TreeSpeciesConfig` for one of the 9 built-in
+ * `TreePreset` archetypes (`Oak`, `Pine`, `Birch`, `Willow`, `Maple`, `Spruce`, `Palm`, `Shrub`, `Fern`),
+ * with optional deep parameter overrides.
+ *
+ * @param {TreePreset|string} [preset=TreePreset.Oak]
+ * @param {Object} [overrides]
+ * @returns {TreeSpeciesConfig}
+ */
+export function make_tree_species_preset(preset?: TreePreset | string, overrides?: any): TreeSpeciesConfig;
+import { TreePreset } from "../config/TreePreset.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+//# sourceMappingURL=make_tree_species_preset.d.ts.map

package/src/generation/foliage/presets/make_tree_species_preset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_tree_species_preset.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/presets/make_tree_species_preset.js"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,kDAJW,UAAU,GAAC,MAAM,oBAEf,iBAAiB,CAs1B7B;2BAh2B0B,yBAAyB;kCAClB,gCAAgC"}