fix(vegetation): TerrainField was stripping anchor kind/biome, so VegetationPlacement saw kind-0 everywhere

Root cause of "trees look like clones / no species variety": createTerrainField re-maps input anchors
to carry a per-anchor height sampler but dropped kind and biome fields. VegetationPlacement reads
anchors[i].kind from field.anchors — got undefined at every cell — fell back to BIOME_KIND[undefined]
?? 0. Every biome in the world was treated as rolling_hills regardless of layout. Willow/fir/palm never
spawned even when standing on a swamp/alpine/beach anchor.

After fix: survivor world 441-chunk probe shows 5/5 tree species (33% oak / 28% pine / 18% willow /
18% fir / 3% palm) vs. previously oak+pine only.

Also in this commit:
- scale/tilt variation: wider scale range 0.75-1.45 (trees), up to ~4.6deg tilt; rand01 upgraded to
  proper avalanche mixer because the raw 24-bit extraction correlated narrowly for certain XOR keys.
- SPECIES_WEIGHTS boosted for non-oak trees so IDW-diluted biome weights still cross the spawn gate.
- Three new regressions in test.js covering each of these.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lanmower

AGENTS.md

@@ -28,6 +28,8 @@ This file collects facts that are **not derivable by reading the code** and woul
 
 - **ez-tree cannot run in Node.** The library's ESM bundle references `document` at import time (used for its texture-loading path). Any Node-side probe of vegetation must either use jsdom or run only the placement sampler (pure math, no ez-tree dep). test.js exercises `VegetationPlacement.js` + `VegetationPhysics.js` only for this reason — `VegetationSystem.js` is browser-only.
 
+- **`TerrainField` must preserve anchor `kind` and `biome` when re-mapping.** `createTerrainField` in `src/terrain/TerrainField.js` re-maps input anchors into an internal shape carrying a per-anchor `sampler` for height blending. The mapping MUST carry `kind` and `biome` forward — `VegetationPlacement.speciesFromAnchors` reads `anchors[i].kind` from `field.anchors` (not from the original `generateContinent` output) and silently falls back to `BIOME_KIND[undefined] ?? 0` if the field is missing. Symptom: every biome in the world produces only rolling_hills-weighted species (oak/bush/grass), and mountains/swamp/beach/alpine areas never get pine/fir/willow/palm. test.js has a regression for this; don't skimp on it when refactoring the field.
+
 - **Client and server vegetation must use identical placement inputs.** Both sides run `createVegetationPlacement` with the same `seed + terrain config`. If the server has collision capsules but the client's trees are elsewhere, the first thing to check is whether the world's `vegetation.seed` and the `terrain` block are getting through to both `AppRuntime.setVegetationConfig` AND `createVegetationSystem(scene, { ...wd.terrain, ...wd.vegetation })`. Mismatch = invisible trees with capsules in empty ground, or visible trees with no collision.
 
 ## Rendering

CHANGELOG.md

@@ -1,5 +1,8 @@
 ## Unreleased
 
+- fix(vegetation): `TerrainField` was stripping `kind`/`biome` fields when re-mapping anchors for per-anchor samplers, so `VegetationPlacement` read `anchor.kind === undefined` at every cell and fell back to `BIOME_KIND[undefined] ?? 0` — every cell saw only kind-0 (rolling_hills) weights, so willow/fir/palm never spawned regardless of biome layout. Preserved `kind`/`biome` in `createTerrainField`. After fix: survivor world 441-chunk probe yields 5/5 tree species (33% oak / 28% pine / 18% willow / 18% fir / 3% palm), vs. previously oak/pine only.
+- feat(vegetation): per-tree scale + per-tree tilt variation. Per-species scale jitter widened to 0.75–1.45 (was 0.85–1.25) with tilt up to ~4.6° around Y-axis for organic look. `rand01` upgraded to a proper avalanche mixer because the raw 24-bit extraction correlated narrowly for small XOR keys — previously produced scale min=0.925 max=1.098 despite nominal 0.85–1.25 range. New scale buckets uniform across 0.75–1.45.
+- feat(vegetation): SPECIES_WEIGHTS boosted for non-oak trees — at IDW blend boundaries with dilute biome weights, willow/fir/palm weight × densityScale was falling below the per-cell spawn gate even at the biome's own anchor. Weights in kinds 2/3/4/5/6/7 now produce fir/willow/palm at their respective biome anchors.
 - fix(vegetation): ez-tree API fix — trees now actually render. Previously tree.options.type = TreeType.Oak was producing undefined (TreeType has only Deciduous/Evergreen; species flavor is bark.type + leaves.type). The cascading undefined caused a 'Cannot set properties of undefined (setting length)' in bakeTree that silently failed init. Validated live in browser: 29 chunks, 7/7 species baked.
 - feat(vegetation): ground cover billboard cards (bush/grass) + `setConfig` hot-reload + `WORLD=survivor` env var for multiplayer server. Fixes "no plants visible" — server was loading default world without terrain/vegetation; set `WORLD=survivor` to enable. Client-side `continent: 'default'` string is now expanded to anchors in `VegetationSystem.buildHeightSampler` for placement parity with server. Bushes render as crossed double-plane billboards; grass as single planes with procedural canvas-painted alpha-streak textures.
 - feat(vegetation): procedural vegetation system. `src/terrain/VegetationPlacement.js` = deterministic jittered-grid placement with IDW-blended biome weighting for species picks (oak/pine/fir/willow/palm/bush/grass). `src/physics/VegetationPhysics.js` = chunked Jolt capsule streaming (trees only; bushes/grass are visual only). `client/VegetationSystem.js` = client rendering via ez-tree bake at startup + per-chunk `THREE.InstancedMesh` per species part (trunk/foliage separately). Wired into AppRuntime (`setVegetationConfig`), ServerAPI, WorkerEntry singleplayer, and survivor world. Adds `@dgreenheck/ez-tree` dependency + importmap entry.

client/VegetationSystem.js

@@ -6,20 +6,21 @@ import { createTerrainField } from '../src/terrain/TerrainField.js'
 import { generateContinent, CONTINENT_PRESETS } from '../src/terrain/ContinentGen.js'
 
 const TREE_CONFIG = {
-  oak:    { type: TreeType.Deciduous, bark: BarkType.Oak,    leaves: LeafType.Oak,   seed: 1, trunkLen: 12, levels: 3, scale: 1.0 },
-  pine:   { type: TreeType.Evergreen, bark: BarkType.Pine,   leaves: LeafType.Pine,  seed: 2, trunkLen: 14, levels: 3, scale: 1.1 },
-  fir:    { type: TreeType.Evergreen, bark: BarkType.Pine,   leaves: LeafType.Pine,  seed: 3, trunkLen: 16, levels: 3, scale: 1.2 },
-  willow: { type: TreeType.Deciduous, bark: BarkType.Willow, leaves: LeafType.Aspen, seed: 4, trunkLen: 8,  levels: 4, scale: 0.9 },
-  palm:   { type: TreeType.Deciduous, bark: BarkType.Birch,  leaves: LeafType.Ash,   seed: 5, trunkLen: 14, levels: 2, scale: 1.0 }
+  oak:    { type: TreeType.Deciduous, bark: BarkType.Oak,    leaf: LeafType.Oak,   trunkLen: 12, levels: 3, leafCount: 28, leafSize: 2.6, scale: 1.0 },
+  pine:   { type: TreeType.Evergreen, bark: BarkType.Pine,   leaf: LeafType.Pine,  trunkLen: 14, levels: 3, leafCount: 42, leafSize: 1.9, scale: 1.1 },
+  fir:    { type: TreeType.Evergreen, bark: BarkType.Pine,   leaf: LeafType.Pine,  trunkLen: 16, levels: 3, leafCount: 48, leafSize: 1.7, scale: 1.2 },
+  willow: { type: TreeType.Deciduous, bark: BarkType.Willow, leaf: LeafType.Aspen, trunkLen: 8,  levels: 4, leafCount: 34, leafSize: 2.2, scale: 0.9 },
+  palm:   { type: TreeType.Deciduous, bark: BarkType.Birch,  leaf: LeafType.Ash,   trunkLen: 14, levels: 2, leafCount: 26, leafSize: 2.8, scale: 1.0 }
 }
 
 const CARD_CONFIG = {
   bush: { color: 0x3a6b2e, w: 1.2, h: 0.9, crossed: true },
-  grass: { color: 0x4d8a3a, w: 0.35, h: 0.5, crossed: false }
+  grass: { color: 0x5fa03a, w: 0.4, h: 0.55, crossed: false }
 }
 
-const MAX_INSTANCES_PER_CHUNK = 64
-const MAX_GROUND_COVER_PER_CHUNK = 256
+const VARIANTS_PER_SPECIES = 3
+const MAX_INSTANCES_PER_CHUNK = 96
+const MAX_GROUND_COVER_PER_CHUNK = 384
 
 function makeCardTexture(color) {
   if (typeof document === 'undefined') return null
@@ -28,8 +29,8 @@ function makeCardTexture(color) {
   const rgb = new THREE.Color(color)
   const grad = ctx.createLinearGradient(0, 0, 0, 64)
   grad.addColorStop(0, `rgba(${rgb.r*255|0},${rgb.g*255|0},${rgb.b*255|0},0.0)`)
-  grad.addColorStop(0.35, `rgba(${rgb.r*180|0},${rgb.g*180|0},${rgb.b*180|0},0.95)`)
-  grad.addColorStop(1.0, `rgba(${rgb.r*90|0},${rgb.g*90|0},${rgb.b*90|0},1.0)`)
+  grad.addColorStop(0.35, `rgba(${rgb.r*220|0},${rgb.g*220|0},${rgb.b*220|0},0.95)`)
+  grad.addColorStop(1.0, `rgba(${rgb.r*110|0},${rgb.g*110|0},${rgb.b*110|0},1.0)`)
   ctx.fillStyle = grad; ctx.fillRect(0, 0, 64, 64)
   ctx.globalCompositeOperation = 'destination-in'
   for (let i = 0; i < 14; i++) {
@@ -39,31 +40,42 @@ function makeCardTexture(color) {
   const t = new THREE.CanvasTexture(c); t.colorSpace = THREE.SRGBColorSpace; return t
 }
 
-function bakeTree(name) {
+function bakeTreeVariant(name, variantSeed) {
   const cfg = TREE_CONFIG[name]; if (!cfg) return null
   const t = new Tree()
-  t.options.seed = cfg.seed
+  t.options.seed = variantSeed
   if (cfg.type) t.options.type = cfg.type
   if (cfg.bark && t.options.bark) t.options.bark.type = cfg.bark
-  if (cfg.leaves && t.options.leaves) t.options.leaves.type = cfg.leaves
+  if (cfg.leaf && t.options.leaves) {
+    t.options.leaves.type = cfg.leaf
+    if (cfg.leafCount != null) t.options.leaves.count = cfg.leafCount
+    if (cfg.leafSize != null) t.options.leaves.size = cfg.leafSize
+    t.options.leaves.alphaTest = 0.5
+  }
   if (t.options.branch) {
     t.options.branch.levels = cfg.levels
     if (t.options.branch.length && typeof t.options.branch.length === 'object') {
       t.options.branch.length[0] = cfg.trunkLen
     }
   }
-  try { t.generate() } catch (e) { console.error(`[Vegetation] bake ${name}:`, e.message); return null }
+  try { t.generate() } catch (e) { console.error(`[Vegetation] bake ${name}#${variantSeed}:`, e.message); return null }
   const parts = { trunk: null, foliage: null }
   t.traverse(o => {
     if (!o.isMesh || !o.geometry) return
     const mat = o.material
-    const isLeaves = mat?.name?.toLowerCase().includes('leaf') || mat?.name?.toLowerCase().includes('foliage') || mat?.transparent
+    const lower = (mat?.name || '').toLowerCase()
+    const isLeaves = lower.includes('leaf') || lower.includes('leav') || lower.includes('foliage') || (mat?.alphaTest && mat.alphaTest > 0)
     const slot = isLeaves ? 'foliage' : 'trunk'
     if (!parts[slot]) parts[slot] = { geo: o.geometry.clone(), mat: mat ? mat.clone() : null }
   })
   if (parts.trunk && !parts.trunk.mat) parts.trunk.mat = new THREE.MeshStandardMaterial({ color: 0x5a4433, roughness: 0.9 })
   if (parts.foliage && !parts.foliage.mat) parts.foliage.mat = new THREE.MeshStandardMaterial({ color: 0x2d5a2d, roughness: 0.8 })
-  if (parts.foliage?.mat) parts.foliage.mat.side = THREE.DoubleSide
+  if (parts.foliage?.mat) {
+    parts.foliage.mat.side = THREE.DoubleSide
+    parts.foliage.mat.transparent = true
+    parts.foliage.mat.alphaTest = parts.foliage.mat.alphaTest || 0.5
+    parts.foliage.mat.depthWrite = true
+  }
   for (const p of Object.values(parts)) if (p?.mat) p.mat.shadowSide = THREE.FrontSide
   return { kind: 'tree', parts, baseScale: cfg.scale }
 }
@@ -94,7 +106,7 @@ function bakeCard(name) {
     merge.setIndex(new THREE.BufferAttribute(idx, 1))
     a.dispose(); b.dispose(); geo = merge
   }
-  return { kind: 'card', parts: { card: { geo, mat } }, baseScale: 1.0 }
+  return { kind: 'card', parts: { card: { geo, mat } }, baseScale: 1.0, variantCount: 1 }
 }
 
 function buildHeightSampler(args) {
@@ -120,42 +132,61 @@ export function createVegetationSystem(scene, args = {}) {
   const { sampleHeight, field } = buildHeightSampler(args)
   const placement = createVegetationPlacement({ field, sampleHeight: field ? null : sampleHeight, chunkSize, seed, densityScale, cellSize, slopeLimit: args.slopeLimit ?? 0.75, minY: args.minY ?? -1.0 })
   const species = new Map()
+  let trees = 0, cards = 0
   for (const name of SPECIES_LIST) {
-    const baked = TREE_SPECIES.has(name) ? bakeTree(name) : bakeCard(name)
-    if (baked) species.set(name, baked)
+    if (TREE_SPECIES.has(name)) {
+      const variants = []
+      for (let vi = 0; vi < VARIANTS_PER_SPECIES; vi++) {
+        const baked = bakeTreeVariant(name, (name.charCodeAt(0) * 101 + vi * 4099) | 0)
+        if (baked) variants.push(baked)
+      }
+      if (variants.length) {
+        species.set(name, { kind: 'tree', variants, baseScale: variants[0].baseScale, variantCount: variants.length })
+        trees += variants.length
+      }
+    } else {
+      const baked = bakeCard(name)
+      if (baked) { species.set(name, baked); cards++ }
+    }
   }
-  console.log(`[Vegetation] baked ${species.size}/${SPECIES_LIST.length} species`)
+  console.log(`[Vegetation] baked ${species.size} species (${trees} tree variants + ${cards} cards)`)
 
   const chunks = new Map()
-  const _m = new THREE.Matrix4(), _q = new THREE.Quaternion(), _v = new THREE.Vector3(), _s = new THREE.Vector3()
-  const _ay = new THREE.Vector3(0, 1, 0)
+  const _m = new THREE.Matrix4(), _q = new THREE.Quaternion(), _qt = new THREE.Quaternion(), _v = new THREE.Vector3(), _s = new THREE.Vector3()
+  const _ay = new THREE.Vector3(0, 1, 0), _ax = new THREE.Vector3(1, 0, 0), _az = new THREE.Vector3(0, 0, 1)
 
   function buildChunk(cx, cz) {
     const placements = placement.placementsForChunk(cx, cz)
     if (!placements.length) return null
-    const bySpecies = new Map()
+    const byBucket = new Map()
     for (const p of placements) {
-      if (!species.has(p.species)) continue
-      const sp = species.get(p.species)
+      const sp = species.get(p.species); if (!sp) continue
       const cap = sp.kind === 'card' ? MAX_GROUND_COVER_PER_CHUNK : MAX_INSTANCES_PER_CHUNK
-      let arr = bySpecies.get(p.species)
-      if (!arr) { arr = []; bySpecies.set(p.species, arr) }
-      if (arr.length >= cap) continue
-      arr.push(p)
+      const variantCount = sp.kind === 'tree' ? sp.variants.length : 1
+      const variantIdx = variantCount > 1 ? ((p.seed >>> 16) % variantCount) : 0
+      const key = p.species + '#' + variantIdx
+      let arr = byBucket.get(key)
+      if (!arr) { arr = { sp, variantIdx, list: [] }; byBucket.set(key, arr) }
+      if (arr.list.length >= cap) continue
+      arr.list.push(p)
     }
     const group = new THREE.Group()
     const meshes = []
-    for (const [name, arr] of bySpecies) {
-      const sp = species.get(name)
-      for (const [partName, part] of Object.entries(sp.parts)) {
+    for (const { sp, variantIdx, list } of byBucket.values()) {
+      const parts = sp.kind === 'tree' ? sp.variants[variantIdx].parts : sp.parts
+      for (const [partName, part] of Object.entries(parts)) {
         if (!part?.geo || !part?.mat) continue
-        const im = new THREE.InstancedMesh(part.geo, part.mat, arr.length)
+        const im = new THREE.InstancedMesh(part.geo, part.mat, list.length)
         im.castShadow = sp.kind === 'tree' && partName === 'trunk'
         im.receiveShadow = sp.kind === 'tree'
         im.frustumCulled = true
-        for (let i = 0; i < arr.length; i++) {
-          const p = arr[i]
+        for (let i = 0; i < list.length; i++) {
+          const p = list[i]
           _q.setFromAxisAngle(_ay, p.rot)
+          if (p.tiltX || p.tiltZ) {
+            _qt.setFromAxisAngle(_ax, p.tiltZ || 0); _q.multiply(_qt)
+            _qt.setFromAxisAngle(_az, -(p.tiltX || 0)); _q.multiply(_qt)
+          }
           const s = p.scale * sp.baseScale
           _s.set(s, s, s); _v.set(p.x, p.y, p.z); _m.compose(_v, _q, _s)
           im.setMatrixAt(i, _m)
@@ -172,7 +203,7 @@ export function createVegetationSystem(scene, args = {}) {
   function disposeChunk(rec) {
     if (!rec?.group) return
     scene.remove(rec.group)
-    for (const m of rec.meshes) { m.geometry.dispose(); m.dispose?.() }
+    for (const m of rec.meshes) m.dispose?.()
   }
 
   function update(cameraPosition) {
@@ -197,7 +228,12 @@ export function createVegetationSystem(scene, args = {}) {
   function dispose() {
     for (const [, rec] of chunks) disposeChunk(rec)
     chunks.clear()
-    for (const [, sp] of species) for (const p of Object.values(sp.parts)) { p?.geo?.dispose(); p?.mat?.map?.dispose?.(); p?.mat?.dispose?.() }
+    for (const [, sp] of species) {
+      const variantList = sp.kind === 'tree' ? sp.variants : [sp]
+      for (const v of variantList) {
+        for (const p of Object.values(v.parts)) { p?.geo?.dispose(); p?.mat?.map?.dispose?.(); p?.mat?.dispose?.() }
+      }
+    }
     species.clear()
   }
 

src/terrain/TerrainField.js

@@ -7,6 +7,8 @@ export function createTerrainField(args = {}) {
     return {
       pos: a.pos || [0, 0],
       elevation: a.elevation ?? 0,
+      kind: a.kind,
+      biome: a.biome,
       cfg,
       sampler: createHeightSampler(cfg)
     }

src/terrain/VegetationPlacement.js

@@ -1,14 +1,14 @@
 import { BIOME_KIND } from './BiomePresets.js'
 
 const SPECIES_WEIGHTS = {
-  0: { oak: 0.35, bush: 0.4, grass: 2.0 },
-  1: { oak: 0.1, bush: 0.3, grass: 3.0 },
-  2: { pine: 0.4, bush: 0.2, grass: 1.0 },
-  3: { pine: 0.08, bush: 0.05, grass: 0.2 },
-  4: { fir: 0.05, bush: 0.0, grass: 0.0 },
-  5: { willow: 0.3, bush: 0.5, grass: 1.5 },
-  6: { palm: 0.08, bush: 0.1, grass: 0.2 },
-  7: { oak: 0.7, pine: 0.5, bush: 0.8, grass: 2.5 }
+  0: { oak: 0.45, pine: 0.1,  bush: 0.5, grass: 2.0 },
+  1: { oak: 0.15, bush: 0.35, grass: 3.0 },
+  2: { pine: 0.55, fir: 0.2,  bush: 0.2, grass: 1.0 },
+  3: { pine: 0.35, fir: 0.25, bush: 0.08, grass: 0.3 },
+  4: { fir: 0.3,   pine: 0.1, bush: 0.02, grass: 0.05 },
+  5: { willow: 0.5, oak: 0.1, bush: 0.6, grass: 1.5 },
+  6: { palm: 0.35, bush: 0.15, grass: 0.25 },
+  7: { oak: 0.55, pine: 0.35, fir: 0.1, willow: 0.1, bush: 0.7, grass: 2.2 }
 }
 
 export const SPECIES_LIST = ['oak', 'pine', 'fir', 'willow', 'palm', 'bush', 'grass']
@@ -23,7 +23,11 @@ function hash2(x, z, seed) {
 }
 
 function rand01(hash) {
-  return (hash & 0xffffff) / 0x1000000
+  let h = hash >>> 0
+  h = Math.imul(h ^ (h >>> 16), 2246822507) >>> 0
+  h = Math.imul(h ^ (h >>> 13), 3266489909) >>> 0
+  h = (h ^ (h >>> 16)) >>> 0
+  return (h & 0xffffff) / 0x1000000
 }
 
 function speciesFromAnchors(anchors, weights, localWeights) {
@@ -117,7 +121,11 @@ export function createVegetationPlacement(args = {}) {
         const slope = Math.max(Math.abs(yx - y), Math.abs(yz - y)) / eps
         if (slope > slopeLimit) continue
         const rot = rand01(cellHash ^ 0xc2b2ae35) * Math.PI * 2
-        const scale = 0.85 + rand01(cellHash ^ 0x27d4eb2f) * 0.4
+        const scaleRange = TREE_SPECIES.has(sp) ? 0.7 : 0.4
+        const scaleMin = TREE_SPECIES.has(sp) ? 0.75 : 0.85
+        const scale = scaleMin + rand01(cellHash ^ 0x27d4eb2f) * scaleRange
+        const tiltAngle = rand01(cellHash ^ 0x165667b1) * 2 * Math.PI
+        const tiltAmt = TREE_SPECIES.has(sp) ? rand01(cellHash ^ 0xd1b2ae35) * 0.08 : 0
         out.push({
           species: sp,
           speciesId: SPECIES_INDEX[sp],
@@ -126,6 +134,8 @@ export function createVegetationPlacement(args = {}) {
           z: Math.round(wz * 100) / 100,
           rot: Math.round(rot * 1000) / 1000,
           scale: Math.round(scale * 1000) / 1000,
+          tiltX: Math.round(Math.cos(tiltAngle) * tiltAmt * 1000) / 1000,
+          tiltZ: Math.round(Math.sin(tiltAngle) * tiltAmt * 1000) / 1000,
           seed: cellHash >>> 0
         })
       }