@woosh/meep-engine 3.58.0 → 3.59.0

package/src/engine/graphics3/trail/trail_tube_write_geometry.d.ts

@@ -16,7 +16,7 @@
  * a vertex buffer per frame.
  *
  * Colour rides the vertices because that is what fades a trail along its length: the knot's own
- * bytes divided by 255, with its alpha — the simulator's age fade, already scaled by the trail's
+ * half-float colour as is, unclamped so HDR survives, with its alpha — the simulator's age fade, already scaled by the trail's
  * base opacity — as the fourth channel. A knot that has aged out is written transparent rather than
  * dropped, which is what the index buffer expects, and blending takes it out of the picture.
  *

package/src/engine/graphics3/trail/trail_tube_write_geometry.js

@@ -1,7 +1,7 @@
 import { assert } from "../../../core/assert.js";
-import {
-    geometry_obtain_attribute,
-    geometry_obtain_index
+import {
+    geometry_obtain_attribute,
+    geometry_obtain_index
 } from "../../../shade/renderer/geometry/geometry_obtain_attribute.js";
 import { StandardAttributes } from "../../../shade/renderer/geometry/StandardAttributes.js";
 import {
@@ -34,7 +34,7 @@ const TWO_PI = Math.PI * 2;
  * a vertex buffer per frame.
  *
  * Colour rides the vertices because that is what fades a trail along its length: the knot's own
- * bytes divided by 255, with its alpha — the simulator's age fade, already scaled by the trail's
+ * half-float colour as is, unclamped so HDR survives, with its alpha — the simulator's age fade, already scaled by the trail's
  * base opacity — as the fourth channel. A knot that has aged out is written transparent rather than
  * dropped, which is what the index buffer expects, and blending takes it out of the picture.
  *
@@ -54,15 +54,15 @@ export function trail_tube_write_geometry(geometry, tube) {
     const table = tube.table;
 
     // Views over the knot rows, not a copy of them. Every attribute up to the colour is a float, so
-    // a column index is also its offset in the float view; the colour is three bytes at the column
-    // that follows them.
+    // a column index is also its offset in the float view; the colour is three half floats at the
+    // column that follows them.
     const floats = new Float32Array(table.data);
-    const bytes = new Uint8Array(table.data);
+    const halves = new Float16Array(table.data);
 
     const float_stride = tube.bytes_per_vertex >> 2;
-    const byte_stride = tube.bytes_per_vertex;
+    const half_stride = tube.bytes_per_vertex >> 1;
 
-    const color_offset = TUBE_ATTRIBUTE_ADDRESS_COLOR * 4;
+    const color_offset = TUBE_ATTRIBUTE_ADDRESS_COLOR * 2;
 
     for (let i = 0; i < vertex_count; i++) {
         const f = i * float_stride;
@@ -88,12 +88,12 @@ export function trail_tube_write_geometry(geometry, tube) {
         positions[p + 1] = floats[f + TUBE_ATTRIBUTE_ADDRESS_POSITION + 1] + (c * ny + s * by) * radius;
         positions[p + 2] = floats[f + TUBE_ATTRIBUTE_ADDRESS_POSITION + 2] + (c * nz + s * bz) * radius;
 
-        const b = i * byte_stride + color_offset;
+        const h = i * half_stride + color_offset;
         const o = i * 4;
 
-        colors[o] = bytes[b] / 255;
-        colors[o + 1] = bytes[b + 1] / 255;
-        colors[o + 2] = bytes[b + 2] / 255;
+        colors[o] = halves[h];
+        colors[o + 1] = halves[h + 1];
+        colors[o + 2] = halves[h + 2];
         colors[o + 3] = floats[f + TUBE_ATTRIBUTE_ADDRESS_ALPHA];
     }
 

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#476@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#478@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#476@#clear_field"(fluid: FluidComponent): void;
+    static "__#478@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#476@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#478@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#476@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#478@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidObstacle> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof FluidComponent>)[];

package/src/generation/foliage/FOLIAGE_DESIGN.md

@@ -106,6 +106,16 @@ Evaluating any point or derivative at local parameter $u \in [0, 1]$ along edge
 - `spline3_hermite_derivative(u, p0x, p1x, m0x, m1x)` (for $x, y, z$)
 
 ### 4.2 Hybrid Parametric + Space-Colonization Growth Algorithm
+A tree grows by one of two front ends (`TreeGrowth`, `generate_tree`'s `growth`; TWO_FRONT_ENDS_BRIEF_2026_10_28.md):
+`TreeGrowth.Graph`, the default, grows the framework below alone (`tree_skeleton_grow_framework`) and draws its species'
+shoot prototypes on its carriers (`tree_shoot_prototypes`, `tree_shoot_instances`): the wood any LOD draws grafted
+onto each carrier, every leaf and twig the prototype's cuts at the tree's error, for most trees;
+`TreeGrowth.Botanical` grows that framework and then every shoot system of `species.shoot_rules` on it
+(`tree_skeleton_grow`, `tree_skeleton_grow_shoots`). The botanical tree's framework is the graph tree, node for node,
+thickened by the shoots it carries. Everything after the skeleton draws both alike. A species is the same for both but
+where the botanical front end grows its framework from shoots: the pine, grown from its seed, has its own graph framework
+(`make_tree_species_preset`'s `growth`).
+
 Branches are grown breadth-first from the trunk (`species.branches[0]`). Every `species.branch_rules` edge
 `source -> target` (always `source < target`, so the graph is acyclic) spawns branches of generator `target` along
 each branch of generator `source`; one generator may spawn several kinds of children (boughs, roots, stubs, sprouts,
@@ -353,7 +363,7 @@ Meep's visibility-buffer renderer (`Shade`) deforms `MeshletGeometry` on the GPU
    - Every bark and foliage vertex writes normalized `uv1 = [wind_hierarchy_weight, wind_edge_flutter_weight]` in $[0, 1]^2$ (encoded losslessly to `u16x2` in `MeshletBatch`).
 2. **Skeletal Joint Hierarchy & `Skin` Generation**:
    - The tree generator maps structural nodes (trunk sections + primary boughs up to a configurable joint budget $J_{\max} \le 64$) to `SceneNode` joints in pre-order.
-   - Every bark and foliage vertex binds up to 4 ancestor joints (`StandardAttributes.SkinningJoints`: `Uint16Array(4 * V)`, `StandardAttributes.SkinningWeights`: `Float32Array(4 * V)` summing to $1.0$) with smooth cubic Hermite weight falloff along each branch segment.
+   - Every bark and foliage vertex binds up to 4 joints (`StandardAttributes.SkinningJoints`: `Uint16Array(4 * V)`, `StandardAttributes.SkinningWeights`: `Float32Array(4 * V)` summing to $1.0$). A bark ring moves with the joint whose span it is in, alone: a joint turns its whole span about its pivot, as the rig placed it, so the bark is continuous across every pivot (which the joint turning it does not move) and a child's joint pivots where the bark it grows from carries it; between rings the mesh eases a pivot's crease over the ring segment around it. A child's first ring is seated in its parent's bark, carried as that bark carries it, and so is the child's wood before its own first joint. Blending a span with the joints above it, as the weights once did by `t_norm` along the branch, tore the bark at the pivot ending the span (the palm's trunk opened 7.6 cm in the reference wind). Leaves and cluster cards take the weights of the bark where they hang.
 3. **GPU Fluid-Driven Foliage Bone System (`FoliageWindRig` + `shader_foliage_wind_apply` + `GPUSceneWind`)**:
    - **Data Tables (`ANIMATION_DATABASE_SPEC`)**:
      - `animation_foliage_rigs` (`ANIMATION_FOLIAGE_RIG_STRUCT`): stores `joints_first`, `joint_count`, `root_node` (`transforms` row of the tree root), and `weight`.
@@ -366,7 +376,7 @@ Meep's visibility-buffer renderer (`Shade`) deforms `MeshletGeometry` on the GPU
      - Downstream `shader_animation_pose_resolve` $\to$ `graph_scene_update_transform_hierarchy` $\to$ `shader_skin_matrix_prep` $\to$ `GPUMeshSkinningContext` (dual-quaternion meshlet deformation + BLAS/TLAS BVH refit) executes unchanged with zero scale conflicts.
 
 ### 7.3 Procedural PBR `StandardShadeMaterial` Synthesis
-When the caller does not pass custom `bark_material` or `foliage_material`, the system synthesizes studio-quality procedural PBR textures using `Sampler2D` $\to$ `ShadeImage.fromSampler2D` $\to$ `ShadeTexture.from`:
+When the caller does not pass `custom_bark_material` or `custom_foliage_material`, the system synthesizes studio-quality procedural PBR textures using `Sampler2D` $\to$ `ShadeImage.fromSampler2D` $\to$ `ShadeTexture.from`. Both are the species', whatever the tree's seed or growth: a `TreeSpeciesCache` passed to `generate_tree` makes a bark material once per `bark_material` and a leaf atlas once per `foliage` and `foliage_material`, and shares them between the trees made alike, each tree tinting a leaf material of its own over the shared atlas.
 1. **`make_bark_material(config)`**:
    - Generates tileable (`TextureWrapType.Repeat`) bark **Albedo** (fissured ridges, lenticels/stripes for birch, warm heartwood/moss undertones), **Tangent-Space Normal Map** (derived analytically from height gradients), and **ORM Map** (`R`: fissure occlusion, `G`: micro-roughness, `B`: 0 metalness) on a `StandardShadeMaterial` (`TransparencyMode.Opaque`, `ShadeDrawSide.Front`).
 2. **`make_foliage_material(species)`**:
@@ -387,10 +397,11 @@ Each LOD (default 3) is the tree drawn to a geometric error $\epsilon_k$, in met
   (its leaves' and twigs' area: sized by its extent instead, the shrub's crown lost .12 of its density), hanging where it
   hangs, turned to run out its way. All of a tree's LODs share the one atlas.
 - **The texel is the leaf's**: the leaf material's own (`FoliageTileLayout.texel`), coarsened by halves only while the
-  cover does not fit the texture ceiling, never past what still tells the leaf from another
+  cover does not fit the texture ceiling, to what still tells the leaf from another
   (`FoliageTileLayout.legible_texel`: its outline's finest feature, teeth aside, four texels across, a needle two
-  across its width); a coarser LOD's representative at the error of the LOD before it, where that one is drawn to a
-  pixel. Tied to the LOD's error, LOD0's leaves were six texels long.
+  across its width), and past it only where even that does not fit: a blurred leaf is still the tree's, a tile drawn
+  past the leaves' spread is not (its twigs as thick as boughs); a coarser LOD's representative at the error of the
+  LOD before it, where that one is drawn to a pixel. Tied to the LOD's error, LOD0's leaves were six texels long.
 - **The bake** (`tree_cluster_bake`): each representative's tile is drawn orthographically from the leaves and twigs
   the tree grew, at its texel, 4x4 samples a texel, back to front in linear light. Every leaf is first pressed
   onto its card, turned about where it attaches until it lies in the card's plane, so a card shows the leaf area the
@@ -443,6 +454,11 @@ src/generation/foliage/
     crown_envelope_evaluate.js (+ .spec.js)
     spine_frame_double_reflection.js (+ .spec.js)
     tree_skeleton_grow.js (+ .spec.js)
+    tree_skeleton_grow_framework.js
+    tree_skeleton_fit_crown_frame.js
+    tree_skeleton_copy_branches.js (+ .spec.js)
+    tree_skeleton_extend_branch.js
+    tree_skeleton_floor_girth.js
     tree_skeleton_compute_pipe_radii.js (+ .spec.js)
     shoot_demography.js (+ .spec.js)
     tree_skeleton_grow_shoots.js (+ .spec.js)
@@ -459,6 +475,7 @@ src/generation/foliage/
     foliage_seasons.spec.js
     tree_mesh_build_foliage.js (+ .spec.js, _cutout.spec.js)
     tree_mesh_apply_canopy_ao.js (+ .spec.js)
+    foliage_scale_spread.js
     tree_clusters.js (+ .spec.js)
     tree_cluster_cards.js (+ .spec.js)
     tree_mesh_build_clusters.js
@@ -471,6 +488,7 @@ src/generation/foliage/
     FoliageAtlasCutout.js
     foliage_atlas_cutout.js (+ .spec.js)
     tree_cluster_bake.js (+ .spec.js)
+    tree_cluster_atlas.js
     tree_cluster_press.js
     tree_cluster_tiles.js
     tree_cluster_atlas_pack.js
@@ -480,6 +498,9 @@ src/generation/foliage/
   asset/
     TreeLODAsset.js
     TreeAsset.js
+    TreeSpeciesCache.js (+ .spec.js)
+    tree_shoot_prototypes.js (+ .spec.js)
+    tree_shoot_instances.js (+ .spec.js)
     tree_lod_plan.js (+ .spec.js)
     generate_tree.js (+ .spec.js)
     place_tree.js (+ .spec.js)

package/src/generation/foliage/LOD_REWORK_BRIEF_2026_10_27.md

@@ -484,3 +484,38 @@ upright.
 | fern | .42/.63 | .42/.63 | .50/.61 | .47/.65 |
 
 The palm is drawn with one tile for its 12 fronds (its fronds magnified 0.91-1.06), 0.76 MiB.
+
+## Tiles drawn past the leaves' spread (2026-10-28)
+
+**What was wrong** (Alex's screenshot of the pine, seed 60557, LOD0 in the playground): thick logs among the
+branches, some thicker than the trunk beside them. They were tiles' twigs, magnified. Where the texture ceiling could
+not hold a cover within the leaves' spread at the legible texel, the choice stopped at legible and drew the cuts no
+tile covered with the least unlike of all, at any size. A pine's LOD0 cuts are whole boughs, 3.5 GB of their own tiles
+at 0.8 mm against a 9.9 MiB ceiling: 86% of its LOD0 cover (by area) was drawn past the spread, magnified up to 10.8x;
+the spruce's up to 15.6x; the shrub's tiles shrunk down to 0.02x. "Up to 1.67x" above was the 90th percentile.
+
+**The fix.** No cut is drawn at a size the tree's leaves do not grow to: LOD0's texel keeps halving past the legible
+texel until the cover fits. A blurred leaf is still the tree's leaf; a magnified tile is another tree. The loop ends: a
+cut's size is never under a texel, so at a texel as large as every cut one tile draws them all.
+
+**Each preset**, LOD0 texel and FIA crown density side/below per LOD, before / after (seed 1337; 60557 where it differs):
+
+| preset | LOD0 texel | LOD0 | LOD1 | LOD2 | atlas |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| oak | 1.41 / 2.83 mm | .46/.46 / same | .45/.45 / same | .42/.42 / same | 824x804 / 502x505 |
+| pine | 0.80 / 6.4 mm | .26/.32 / .26/.31 | .25/.28 / .26/.31 | .22/.27 / .25/.37 | 1038x1005 / 625x650 |
+| spruce | 0.50 / 4.0 mm | .24/.39 / .25/.40 | .24/.40 / .24/.40 | .22/.40 / .22/.38 | 1057x402 / 421x417 |
+| shrub | 1.20 / 4.8 mm (60557: 9.6) | .67/.60 / .64/.58 | .59/.58 / .64/.58 | .53/.51 / .59/.52 | 433x368 / 341x351 |
+
+The willow, birch, maple, palm and fern fitted at or before legible and are drawn byte for byte as before.
+The conifers' generation takes 1-2 s longer (single runs on a busy machine); the pine's choice ~5.0 s against
+~3.4 s (paired, 3 runs each).
+
+**Measured open items** (independent review):
+- **A cut's wood can be drawn thicker than it grew without magnification.** A cut is matched to a tile by the size of
+  its leaf and wood area together, so a few needle shoots on 44 mm of 4 mm twig (pine 60557, LOD0 cut 791) are drawn
+  with a tile of the same area that is mostly 1.2 m of bough up to 27.5 mm across. Pine 60557: 58 of 881 LOD0 cuts
+  draw more than 3x the wood area they grew (89 before); thickest drawn wood over thickest grown at most 5.3x (20.6x
+  before). Maple up to 4.8x, birch 4.2x, oak LOD2 9.6x.
+- **A tile's wood runs off its cut's own wood**: on pine 60557 the angle between them is 10 degrees at the median,
+  27 at the 90th percentile, 12-15 cuts over 45 degrees, unchanged by this fix.

package/src/generation/foliage/SELF_ORGANIZING_FRAMEWORK_BRIEF_2026_10_26.md

@@ -140,7 +140,8 @@ What the rules need from the stem out, and what the presets already cite:
 5. **S4, bending** (F3), if taken.
 6. **S5, the other species:** spruce, maple, birch, willow, hazel, then oak once F5 has a source. Each is measured
    against S0 and looked at.
-7. **S6, removal.**
+7. **S6, removal.** Struck 2026-10-28: the generator graph is a front end of its own (TWO_FRONT_ENDS_BRIEF_2026_10_28.md,
+   G-F7), so its crown machinery stays.
    - The graph's crown machinery goes for shoot-grown species (hard break): branch spawn rules above the roots, space
      colonization, the crown envelope's growth role, BVH avoidance, and the back-filled carrier ages.
    - Specs are restated from their principle. Tiers come from whorls; collision is "a shoot never grows into older