sindicate 0.1.0 → 0.4.0

package/src/world/scatter.js

@@ -0,0 +1,1077 @@
+// Instanced scatter: merges a Synty FBX into one geometry and stamps it
+// across the world with InstancedMesh — forests cost a few draw calls.
+import * as THREE from 'three/webgpu';
+import {
+  uniform, float, positionWorld, cameraPosition, smoothstep, oneMinus,
+  Fn, attribute, vec2, vec3, vec4, positionGeometry, uv, modelViewMatrix,
+  cameraProjectionMatrix, normalize, abs, floor, texture, max,
+  sin, hash, instanceIndex, time,
+} from 'three/tsl';
+import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+import { loadModel, loadTexture, loadGLB, resolveModelUrl } from '../core/assets.js';
+import { uDayness, uWindDir, uWindStr } from './weatherUniforms.js';
+import { waterNoiseTexture } from './waterNoise.js';
+import { getQualityName, getQuality } from '../core/quality.js';
+// Per-game LOD tables — register before any LOD chain is built:
+//   configureScatterLod(lodConfigJson, defaultTiers)
+let LOD_CONFIG = {};
+let DEFAULT_TIERS = null;
+export function configureScatterLod(config, tiers) { LOD_CONFIG = config ?? {}; DEFAULT_TIERS = tiers ?? null; }
+
+// Dithered LOD cross-fade runs on Medium and High; only Low hard-swaps.
+// (Node materials + alphaHash cost more, and the dither can read as stippling
+// on the WebGL2 fallback on older GPUs — Low skips it entirely, and the
+// auto-tuner still steps down to Low if Medium can't hold framerate.)
+const FADE = () => getQualityName() !== 'low';
+
+// ---- distance LOD registry: scatterLOD() pairs a detailed near mesh with
+// a glodify-generated far mesh; updateScatterLODs() rebuckets instances
+// around the player every few hundred ms.
+const lodGroups = [];
+
+// LOD-dirty handshake for the caller's stationary skip (world.update): new chains/trees start
+// UNBUCKETED (a fresh chain shows impostors-everywhere until its first rebucket), so a stream-in
+// must force the next few updater calls even if the player is standing still. 3 runs = one full
+// cycle of the amortized third-per-call round-robin updaters.
+let _lodDirtyRuns = 3;
+export function markLodDirty() { _lodDirtyRuns = 3; }
+export function consumeLodRun() { if (_lodDirtyRuns > 0) { _lodDirtyRuns--; return true; } return false; }
+
+// Conservative whole-group bounding sphere over every placement (+margin for the model's own size).
+// Assigned to each LOD tier mesh ONCE at build so the per-rebucket computeBoundingSphere (a full
+// pass over the repacked instance matrices, every tier, every rebucket) can be dropped — the
+// sphere always covers every instance the tier could hold, so frustum culling stays correct.
+function groupSphere(placements, margin = 14) {
+  let minX = 1e9, maxX = -1e9, minY = 1e9, maxY = -1e9, minZ = 1e9, maxZ = -1e9;
+  for (const p of placements) {
+    const y = p.y ?? 0;
+    if (p.x < minX) minX = p.x; if (p.x > maxX) maxX = p.x;
+    if (y < minY) minY = y; if (y > maxY) maxY = y;
+    if (p.z < minZ) minZ = p.z; if (p.z > maxZ) maxZ = p.z;
+  }
+  const c = new THREE.Vector3((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
+  const r = Math.hypot(maxX - minX, maxY - minY, maxZ - minZ) / 2 + margin;
+  return new THREE.Sphere(c, r);
+}
+
+// Flattened-geometry cache. flattenToGeometry merges an FBX/GLB into one BufferGeometry; the result
+// is identical for a given (url, lod) regardless of placements. So cache it — a streamed tile then
+// builds just an InstancedMesh over the SHARED geometry (cheap; no per-tile re-merge), which also
+// cuts VRAM (one geometry, not one per tile). Cached geometries are tagged so disposeScatterGroup
+// never frees them (they're shared across every tile that uses that model).
+const geometryCache = new Map();
+function flattenCached(url, group, lod = 0) {
+  const key = `${url}#${lod}`;
+  let flat = geometryCache.get(key);
+  if (flat === undefined) {
+    flat = flattenToGeometry(group, { lod });
+    if (flat?.geometry) flat.geometry.userData.cached = true;
+    geometryCache.set(key, flat ?? null);
+  }
+  return flat ?? null;
+}
+
+// Materials are identical per scatter TYPE (same texture + params) across every streamed tile, but
+// were rebuilt on each tile load — a real per-tile hitch (measured: ~150-240ms/boundary even with
+// geometry cached, largely the TSL tint node-graph construction). Cache + SHARE them across tiles,
+// marked userData.cached so disposeScatterGroup keeps them resident (it now skips cached materials).
+// Keyed by texture uuid + the params that change the material, so only truly-identical mats share.
+const _matCache = new Map();
+function cachedMat(key, make) {
+  let m = _matCache.get(key);
+  if (!m) { m = make(); m.userData.cached = true; _matCache.set(key, m); }
+  return m;
+}
+
+// LOD0 collision data for distance-LOD scatters: the NEAR (full-detail) geometry
+// plus EVERY instance matrix, independent of the live near/far bucketing.
+// Collision only matters where LOD0 renders (close to the player); anything on a
+// far LOD is out of reach, so the far meshes are never baked into the collider.
+export function getLODColliderGroups() {
+  return lodGroups.filter((g) => g.tiers?.[0]?.mesh).map((g) => ({
+    name: g.tiers[0].mesh.name,
+    geometry: g.tiers[0].mesh.geometry,
+    matrices: g.matrices,
+    count: g.count,
+  }));
+}
+
+// Tile unload: free a scatterChain Group — drop its lodGroups entry (so updateScatterLODs stops
+// touching disposed instances) and dispose every tier's geometry + material. Also works on a plain
+// InstancedMesh (no scatterEntry → just disposes). Textures are loadTexture-cached/shared and are
+// NOT disposed (Material.dispose doesn't touch them). No skinned meshes ever pass through here.
+export function disposeScatterGroup(obj) {
+  const entry = obj.userData?.scatterEntry;
+  if (entry) { const i = lodGroups.indexOf(entry); if (i >= 0) lodGroups.splice(i, 1); }
+  const tEntry = obj.userData?.treeLodEntry;
+  if (tEntry) { const i = treeLodGroups.indexOf(tEntry); if (i >= 0) treeLodGroups.splice(i, 1); }
+  obj.traverse((o) => {
+    if (o.isInstancedMesh) o.dispose?.();                        // frees the instance buffers (instanceMatrix)
+    if (!o.geometry?.userData?.cached) o.geometry?.dispose?.();   // shared cached geometry stays resident
+    const mats = Array.isArray(o.material) ? o.material : (o.material ? [o.material] : []);
+    for (const m of mats) if (!m.userData?.cached) m.dispose?.();  // shared cached material stays resident (reused across tiles)
+  });
+}
+
+// Shared transition band (metres) for the dithered LOD swap. The detailed NEAR
+// mesh DISSOLVES OUT across [lo, hi]: the shader reads per-fragment camera
+// distance and alphaHash turns its fractional opacity into a stable screen-door
+// dither (order-independent — no transparency sorting). The FAR LOD stays SOLID
+// underneath, so the dither holes reveal the LOD, never the sky. (Dithering
+// both meshes with a shared hash punches holes clean through both → speckle.)
+// updateScatterLODs() drives these each tick; lo===hi (Low quality) = hard swap.
+const bandLo = uniform(54);
+const bandHi = uniform(54.01);
+const camDist = positionWorld.sub(cameraPosition).length();
+const fadeOut = oneMinus(smoothstep(bandLo, bandHi, camDist)); // 1 near → 0 far
+
+// Per-tree tonal variation (braffolk's per-instance hue/value jitter, re-keyed to
+// WORLD SPACE so it survives our LOD rebucketing with no per-instance attribute):
+// two smooth noise scales — broad stand-to-stand tone drift + tree-to-tree change.
+// A gradient across one 6 m crown is imperceptible at this amplitude; between
+// neighbouring trees it reads as individuals instead of copy-paste.
+function tintAt(xz) {
+  const t = texture(waterNoiseTexture(), xz.mul(1 / 59)).r.mul(0.55)
+    .add(texture(waterNoiseTexture(), xz.mul(1 / 13.7)).g.mul(0.45));
+  return vec3(t.mul(0.22).add(0.90), float(1.04).sub(t.mul(0.10)), float(1.06).sub(t.mul(0.12)));
+}
+
+// Material for one LOD side. `fading: 'near'` dithers out the detailed mesh;
+// `fading: 'far'` is left fully solid (it's what the holes reveal).
+function fadeMaterial({ map = null, vertexColors = false, fading }) {
+  const mat = new THREE.MeshStandardNodeMaterial({
+    roughness: vertexColors ? 1 : 0.9,
+    metalness: 0,
+  });
+  if (map) mat.map = map;
+  if (vertexColors) mat.vertexColors = true;
+  if (fading === 'near') {
+    mat.opacityNode = fadeOut;   // dissolve the detailed mesh away with distance
+    mat.alphaHash = true;        // stochastic dither — stable per world position
+  }
+  return mat;
+}
+
+// ---- per-object (non-instanced) dissolve, used for buildings ----
+// Same dither, but the band edges are baked constants (each building has its
+// own switch distance), so no shared uniform/bucketing is needed — the shader
+// dissolves by live camera distance and updateBuildingLODs() just culls the
+// fully-faded mesh so we don't draw both everywhere.
+const buildingLODs = []; // { near, far, x, z, lo, hi }
+
+// Clone a mesh's material into a dithered dissolve node material, preserving look.
+function toFadeMaterial(src, ramp) {
+  const s = Array.isArray(src) ? src[0] : src;
+  const mat = new THREE.MeshStandardNodeMaterial({
+    roughness: s?.roughness ?? 0.9,
+    metalness: s?.metalness ?? 0,
+  });
+  if (s?.map) mat.map = s.map;
+  if (s?.vertexColors) mat.vertexColors = true;
+  if (s?.color) mat.color.copy(s.color);
+  mat.opacityNode = ramp;
+  mat.alphaHash = true;
+  return mat;
+}
+
+// Dissolve the detailed meshes under `root` OUT across [near, far] (metres) with
+// a stochastic dither. Only the near object is dithered — its LOD stays solid.
+function applyObjectFade(root, { near, far }) {
+  const ramp = oneMinus(smoothstep(float(near), float(far), camDist));
+  root.traverse((o) => {
+    if (o.isMesh) o.material = toFadeMaterial(o.material, ramp);
+  });
+}
+
+// Register a building's near (full) → far (LOD3 mesh) → optional impostor chain.
+// near dissolves out at switchDist; if an impostor is given, the LOD3 stays solid
+// until d2 then dissolves out over the (solid) impostor behind it. All objects must
+// already be in the scene at the same transform.
+export function registerBuildingLOD(near, far, x, z, switchDist, band, impostor = null, d2 = 0) {
+  const lo = band > 0 ? switchDist - band : switchDist;
+  const hi = band > 0 ? switchDist + band : switchDist;
+  if (band > 0) applyObjectFade(near, { near: lo, far: hi });
+  const entry = { near, far, impostor, x, z, lo, hi };
+  if (impostor) {
+    entry.d2lo = band > 0 ? d2 - band : d2;
+    entry.d2hi = band > 0 ? d2 + band : d2;
+    if (band > 0) applyObjectFade(far, { near: entry.d2lo, far: entry.d2hi }); // LOD3 dissolves into the impostor
+  }
+  buildingLODs.push(entry);
+  markLodDirty(); // phase-2 castle etc. register while the player may be standing still
+}
+
+// A single-building octahedral impostor billboard (non-instanced): centre/size as
+// uniforms. Always camera-facing, samples the baked atlas by view angle.
+export async function buildingImpostor(impJsonUrl, x, y, z, scale = 1, flipV = false) {
+  const desc = await fetch(impJsonUrl).then((r) => r.json());
+  const dir = impJsonUrl.slice(0, impJsonUrl.lastIndexOf('/'));
+  const albedo = await loadTexture(`${dir}/${desc.maps.albedo}`);
+  const S = 0.01;
+  const sz = (desc.billboardSize ?? 200) * S * scale;
+  const cy = (desc.bounds?.center?.[1] ?? 0) * S * scale;
+  const mat = impostorMaterial(albedo, desc, flipV, uniform(new THREE.Vector3(x, y + cy, z)), uniform(new THREE.Vector2(sz, sz)));
+  const mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), mat);
+  mesh.frustumCulled = false; mesh.castShadow = false; mesh.receiveShadow = false;
+  mesh.name = `buildingImpostor:${impJsonUrl.split('/').pop()}`;
+  return mesh;
+}
+
+// Cull whichever tier has fully faded; render adjacent tiers only inside their band.
+export function updateBuildingLODs(px, pz) {
+  for (const b of buildingLODs) {
+    const d = Math.hypot(b.x - px, b.z - pz);
+    b.near.visible = d < b.hi; // near fades out by hi
+    if (b.impostor) {
+      b.far.visible = d > b.lo && d < b.d2hi; // LOD3 lives between the two switches
+      b.impostor.visible = d > b.d2lo;        // impostor takes over in the deep distance
+    } else {
+      b.far.visible = d > b.lo;
+    }
+  }
+}
+
+// Merge meshes in an FBX group (transforms applied) into one geometry.
+// Synty files often stack LOD0/LOD1/LOD2 meshes at the same spot (LOD2 is
+// a flat imposter card) — merge ONLY the highest-detail LOD of each.
+// Returns { geometry, hasColor }. hasColor is true when the merged meshes
+// carried a COLOR_0 attribute (glodify's baked far-LOD vertex colors), so the
+// caller renders vertex colors instead of the atlas texture.
+// `split` (RegExp or name predicate): meshes whose NAME matches are pulled OUT of the merge and
+// returned separately as `parts: [{ name, geometry }]`, in the same file-local frame. That is how a
+// door leaf escapes the building weld — town.js merges a whole building into one geometry
+// (and one BVH), which is exactly why a baked-in door can never swing or open. A predicate,
+// because the caller's rule is "every door EXCEPT the ones on a see-through shell".
+export function flattenToGeometry(group, { lod = 0, split = null } = {}) {
+  group.updateMatrixWorld(true);
+  const meshes = [];
+  group.traverse((o) => { if (o.isMesh) meshes.push(o); });
+  if (!meshes.length) return null;
+
+  const lodOf = (m) => {
+    const match = m.name.match(/_LOD(\d+)/i);
+    return match ? +match[1] : 0;
+  };
+  // pick the requested LOD, clamped to what the file actually has
+  // (LOD3 is usually a flat imposter card — never auto-pick beyond LOD2)
+  const lods = [...new Set(meshes.map(lodOf))].sort((a, b) => a - b);
+  const usable = lods.filter((l) => l <= Math.max(lod, 0) && l <= 2);
+  const chosen = usable.length ? usable[usable.length - 1] : lods[0];
+
+  // A baked far-LOD carries per-vertex color; keep it only if EVERY merged
+  // mesh has one (mergeGeometries requires matching attribute sets).
+  const all = meshes.filter((o) => lodOf(o) === chosen);
+  const hit = !split ? null : (typeof split === 'function' ? split : (n) => split.test(n));
+  const chosenMeshes = hit ? all.filter((o) => !hit(o.name)) : all;
+  const splitMeshes = hit ? all.filter((o) => hit(o.name)) : [];
+  const keepColor = chosenMeshes.every((o) => o.geometry.attributes.color);
+
+  const geos = [];
+  const parts = [];
+  for (const o of [...chosenMeshes, ...splitMeshes]) {
+    const g = o.geometry.clone();
+    // De-quantize int-packed attributes (KHR_mesh_quantization on the glodify glbs)
+    // to float BEFORE baking the matrix: applyMatrix4 writes transformed floats back
+    // into the attribute array, and an int16 buffer truncates them to garbage —
+    // collapsing the mesh into a tiny "box". getComponent() respects normalization.
+    for (const key of ['position', 'normal']) {
+      const a = g.attributes[key];
+      if (a && !(a.array instanceof Float32Array)) {
+        const out = new Float32Array(a.count * a.itemSize);
+        for (let i = 0; i < a.count; i++) for (let c = 0; c < a.itemSize; c++) out[i * a.itemSize + c] = a.getComponent(i, c);
+        g.setAttribute(key, new THREE.BufferAttribute(out, a.itemSize));
+      }
+    }
+    g.applyMatrix4(o.matrixWorld);
+    const allow = keepColor ? ['position', 'normal', 'uv', 'color'] : ['position', 'normal', 'uv'];
+    for (const key of Object.keys(g.attributes)) {
+      if (!allow.includes(key)) g.deleteAttribute(key);
+    }
+    if (!g.attributes.uv) {
+      g.setAttribute('uv', new THREE.BufferAttribute(new Float32Array(g.attributes.position.count * 2), 2));
+    }
+    if (splitMeshes.includes(o)) parts.push({ name: o.name, geometry: g });
+    else geos.push(g);
+  }
+  if (!geos.length) return null;
+  const geometry = geos.length === 1 ? geos[0] : BufferGeometryUtils.mergeGeometries(geos, false);
+  return { geometry, hasColor: keepColor, parts };
+}
+
+// tint (vegetation): world-space tonal jitter — needs a node material. alphaTest
+// relies on the sampled alpha, which colorNode's rgb path drops, so never both.
+// Cached + shared across tiles (world-space nodes → identical everywhere); this was the per-tile hitch.
+function scatterMat(tex, alphaTest, tint, doubleSide, sway = false) {
+  return cachedMat(`${tex.uuid}|${alphaTest}|${tint}|${doubleSide}|${sway}`, () => {
+    const nodeMat = sway || (tint && !alphaTest);   // sway also needs a node material (positionNode)
+    const mm = nodeMat
+      ? new THREE.MeshStandardNodeMaterial({ map: tex, roughness: 0.9, metalness: 0 })
+      : new THREE.MeshStandardMaterial({ map: tex, roughness: 0.9, metalness: 0 });
+    if (tint && !alphaTest) mm.colorNode = texture(tex, uv()).rgb.mul(tintAt(positionWorld.xz));
+    if (alphaTest) { mm.alphaTest = alphaTest; mm.transparent = false; }
+    if (doubleSide) mm.side = THREE.DoubleSide;
+    if (sway) {
+      // WIND SWAY (crops): roots planted, tips nod on the GLOBAL wind (uWindDir/uWindStr). Amplitude
+      // grows with height² above the base (positionGeometry.y) and with the gust; a per-plant wobble
+      // keeps them out of lockstep. The lean is uWindDir, but each plant's own Y-rotation spins it a
+      // little, so a field reads as a RUSTLE stirring in the breeze rather than a rigid uniform lean.
+      const yb = positionGeometry.y.max(0);
+      const ph = hash(instanceIndex).mul(6.2832);
+      const wobble = sin(time.mul(1.7).add(ph)).mul(0.4).add(0.75);
+      const amp = yb.mul(yb).mul(0.032).mul(uWindStr.mul(1.4).add(0.3)).mul(wobble);
+      mm.positionNode = positionGeometry.add(vec3(uWindDir.x.mul(amp), float(0), uWindDir.y.mul(amp)));
+    }
+    return mm;
+  });
+}
+
+// Create an InstancedMesh of `url` at the given placements.
+// placements: [{x, y, z, ry, s}]
+export async function scatter(url, textureUrl, placements, { castShadow = true, alphaTest = 0, doubleSide = false, lod = 0, texture: texOverride = null, tint = false, sway = false } = {}) {
+  const master = await loadModel(url, { texture: textureUrl });
+  const flat = flattenCached(url, master, lod);
+  if (!flat) throw new Error(`no geometry in ${url}`);
+  const geo = flat.geometry;
+  // `texture` opt lets the caller pass a pre-built texture (e.g. the composited palm
+  // bark+leaf albedo with its own repeat/wrap) instead of loading one from a URL.
+  // atlas flip must match the RESOLVED master format: the twin redirect hands scatter
+  // glTF-convention geometry, and a default-flip (FBX-convention) atlas mirrors every
+  // palette cell — the red wells / washed market tents bug.
+  const isGLBMaster = /\.glb$/i.test(await resolveModelUrl(url, { texture: textureUrl }));
+  const tex = texOverride ?? await loadTexture(textureUrl, isGLBMaster ? { flipY: false } : {});
+  const mat = scatterMat(tex, alphaTest, tint, doubleSide, sway);
+
+  const mesh = new THREE.InstancedMesh(geo, mat, placements.length);
+  composeInto(mesh.instanceMatrix.array, 0, placements);
+  mesh.castShadow = castShadow;
+  mesh.receiveShadow = true;
+  mesh.instanceMatrix.needsUpdate = true;
+  mesh.name = `scatter:${url.split('/').pop()}`;
+  // Origin-placed (every instance carries its own world transform) → the mesh matrix is identity
+  // forever. Freeze it so scene.updateMatrixWorld (run inside the render phase) stops recomposing it
+  // every frame. Safe for streamed tiles too — same identity transform.
+  mesh.matrixAutoUpdate = false; mesh.updateMatrix();
+  return mesh;
+}
+
+// RESIDENT plain scatter: one InstancedMesh for the LIFE of the app, capacity-sized and empty;
+// tiles stream in/out as slice writes (see SliceTable). Same cached geometry/material as scatter()
+// — identical cachedMat key, so eager settlement props share the very same pipelines. `allPl` is
+// every placement the spec can ever hold (the conservative frustum sphere; instances beyond the
+// live window simply never render because count bounds them).
+export async function scatterResident(url, textureUrl, cap, allPl, { castShadow = true, alphaTest = 0, doubleSide = false, lod = 0, texture: texOverride = null, tint = false, sway = false } = {}) {
+  const master = await loadModel(url, { texture: textureUrl });
+  const flat = flattenCached(url, master, lod);
+  if (!flat) throw new Error(`no geometry in ${url}`);
+  // atlas flip must match the RESOLVED master format: the twin redirect hands scatter
+  // glTF-convention geometry, and a default-flip (FBX-convention) atlas mirrors every
+  // palette cell — the red wells / washed market tents bug.
+  const isGLBMaster = /\.glb$/i.test(await resolveModelUrl(url, { texture: textureUrl }));
+  const tex = texOverride ?? await loadTexture(textureUrl, isGLBMaster ? { flipY: false } : {});
+  const mesh = new THREE.InstancedMesh(flat.geometry, scatterMat(tex, alphaTest, tint, doubleSide, sway), cap);
+  mesh.count = 0; // instanceMatrix is born zero-filled → the boot warm's count=1 flash draws a scale-0 instance (nothing)
+  mesh.castShadow = castShadow;
+  mesh.receiveShadow = true;
+  mesh.name = `scatter:${url.split('/').pop()}`;
+  mesh.boundingSphere = groupSphere(allPl); // conservative over every possible placement — never recomputed
+  mesh.matrixAutoUpdate = false; mesh.updateMatrix(); // origin-placed, instances carry transforms
+  const slices = new SliceTable(mesh.name, cap, [{ a: mesh.instanceMatrix.array, s: 16 }]);
+  return {
+    group: mesh,
+    colliderName: mesh.name,
+    colliderGeometry: flat.geometry, // LOD0 — the tile BVH bakes this × the tile's matrix slice
+    write(key, pl) {
+      const off = slices.alloc(key, pl.length);
+      if (off < 0) return null;
+      composeInto(mesh.instanceMatrix.array, off, pl);
+      mesh.count = slices.count;
+      mesh.instanceMatrix.needsUpdate = true;
+      return mesh.instanceMatrix.array.slice(off * 16, (off + pl.length) * 16); // per-tile copy for the tile BVH (survives compaction)
+    },
+    free(key) {
+      if (!slices.free(key)) return;
+      mesh.count = slices.count;
+      mesh.instanceMatrix.needsUpdate = true;
+    },
+  };
+}
+
+// ── Synty Nature-Biomes trees ──────────────────────────────────────────────
+// These use the custom "Foliage" shadergraph: ONE mesh, ONE UV0, but TWO
+// textures — _Trunk_Texture (opaque bark atlas) for the trunk/branch faces and
+// _Leaf_Texture (a .tga with alpha, converted to PNG) for the leaf-card faces.
+// The two face sets sit in DIFFERENT UV regions of the same 0..1 space (trunk
+// clusters in a corner spot u<~0.15, leaves in the sprite rectangles). We split
+// the LOD0 geometry by UV and stamp TWO InstancedMeshes: opaque trunk + alphaTest
+// cutout leaves. (Proven in /treetest.html.) Returns a Group for the tile system.
+const _treeTexCache = {};
+function treeTex(url, kind = 'trunk', isTwin = false) {
+  // kind: 'trunk' (opaque bark atlas — mipped + anisotropic), 'leaf' (sprite cutout —
+  // no mipmaps so alpha edges don't alias into rainbow bands), 'card' (the terminal
+  // LOD's pre-rendered billboard atlas — like leaf but flipY=TRUE: it's authored
+  // crown-up, and the whole-sprite card makes the flip visible, unlike the tiny
+  // bark/leaf spots the mesh faces sample). See [[nature-biome-trees]].
+  // isTwin: the tree geometry resolved to a GLB twin (glTF V convention) — flips invert.
+  const key = `${url}#${kind}#${isTwin ? 'g' : 'f'}`;
+  if (!_treeTexCache[key]) _treeTexCache[key] = new THREE.TextureLoader().loadAsync(url).then((t) => {
+    t.colorSpace = THREE.SRGBColorSpace; t.wrapS = t.wrapT = THREE.ClampToEdgeWrapping;
+    // flip follows the RESOLVED geometry format: these constants were tuned against FBX
+    // trees (2026-07-04); the twin redirect inverted V, rendering every twinned tree's
+    // distance BILLBOARD upside-down (audit: card-mesh V correlation flips sign in twins).
+    // XOR restores the tuned texels for both formats; tropical trees have no twins
+    // (protected) and keep the FBX behaviour.
+    t.flipY = (kind === 'card') !== isTwin;
+    if (kind === 'leaf' || kind === 'card') {
+      t.generateMipmaps = false; t.minFilter = THREE.LinearFilter; t.magFilter = THREE.LinearFilter;
+    } else { t.anisotropy = 4; }
+    t.needsUpdate = true; return t;
+  });
+  return _treeTexCache[key];
+}
+// GPU-upload every cached tree texture at boot (same tex:+1 first-sight hitch as assets.warmTextures).
+export async function warmTreeTextures(renderer) {
+  let n = 0;
+  for (const p of Object.values(_treeTexCache)) { try { renderer.initTexture(await p); n++; } catch (e) { /* skip */ } }
+  return n;
+}
+// Split by per-triangle UV SPAN (not centroid): Synty foliage LEAF cards map a
+// whole needle sprite → large UV bbox; TRUNK/branch faces sample a tiny flat bark
+// spot → small UV bbox. Centroid-u splitting misclassified leaf cards straddling
+// low-u (they sampled the bark atlas → rainbow branches). `splitU` is the span
+// threshold: span > splitU → leaf sprite, else → trunk/branch bark. Proven in
+// /treetest.html — see [[nature-biome-trees]].
+function splitGeoByUV(geo, splitU) {
+  const uvA = geo.attributes.uv, idx = geo.index;
+  const n = idx ? idx.count : geo.attributes.position.count;
+  const trunk = [], leaf = [];
+  for (let i = 0; i < n; i += 3) {
+    const vi = (k) => idx ? idx.getX(i + k) : i + k;
+    let umin = 9, umax = -9, vmin = 9, vmax = -9;
+    for (let k = 0; k < 3; k++) { const u = uvA.getX(vi(k)), v = uvA.getY(vi(k)); umin = Math.min(umin, u); umax = Math.max(umax, u); vmin = Math.min(vmin, v); vmax = Math.max(vmax, v); }
+    const span = Math.max(umax - umin, vmax - vmin);
+    (span > splitU ? leaf : trunk).push(vi(0), vi(1), vi(2));
+  }
+  const mk = (ind) => { const g = geo.clone(); g.setIndex(ind); return g; };
+  return { trunkGeo: trunk.length ? mk(trunk) : null, leafGeo: leaf.length ? mk(leaf) : null };
+}
+// Merge same-LOD meshes (world transforms applied) into ONE geometry, keeping only
+// position/normal/uv (matches flattenToGeometry's attribute policy so mergeGeometries
+// never trips on mismatched attribute sets).
+function mergeMeshGeos(meshes) {
+  const geos = [];
+  for (const o of meshes) {
+    const g = o.geometry.clone();
+    g.applyMatrix4(o.matrixWorld);
+    for (const key of Object.keys(g.attributes)) if (!['position', 'normal', 'uv'].includes(key)) g.deleteAttribute(key);
+    if (!g.attributes.uv) g.setAttribute('uv', new THREE.BufferAttribute(new Float32Array(g.attributes.position.count * 2), 2));
+    geos.push(g);
+  }
+  if (!geos.length) return null;
+  return geos.length === 1 ? geos[0] : BufferGeometryUtils.mergeGeometries(geos, false);
+}
+
+// Build (and cache) the per-LOD split geometry for a biome tree. The Synty FBX ships
+// LOD0..LODn; the terminal ~12-tri LOD is a crossed BILLBOARD card that samples its
+// own pre-rendered atlas (not the trunk/leaf sprite atlas) so it's kept whole. Every
+// real mesh LOD is split trunk-vs-leaf by UV span. Returns
+//   [{ level, tris, trunkGeo, leafGeo, cardGeo }]  (only one of {trunk+leaf}|card set)
+// All geos are userData.cached so disposeScatterGroup never frees them (shared across
+// every streamed tile that stamps this tree — one geometry set, many InstancedMeshes).
+const CARD_TRI_MAX = 64;
+const _treeTierCache = new Map();
+function treeLODTiers(cacheKey, group, splitU) {
+  let tiers = _treeTierCache.get(cacheKey);
+  if (tiers) return tiers;
+  group.updateMatrixWorld(true);
+  const byLevel = new Map();
+  group.traverse((o) => {
+    if (!o.isMesh) return;
+    const lv = +((o.name.match(/_LOD(\d+)/i) || [])[1] ?? 0);
+    if (!byLevel.has(lv)) byLevel.set(lv, []);
+    byLevel.get(lv).push(o);
+  });
+  tiers = [];
+  for (const lv of [...byLevel.keys()].sort((a, b) => a - b)) {
+    const geo = mergeMeshGeos(byLevel.get(lv));
+    if (!geo) continue;
+    const tris = (geo.index ? geo.index.count : geo.attributes.position.count) / 3;
+    let trunkGeo = null, leafGeo = null, cardGeo = null;
+    if (tris <= CARD_TRI_MAX) {
+      cardGeo = geo;                                  // billboard card — no split
+    } else {
+      ({ trunkGeo, leafGeo } = splitGeoByUV(geo, splitU));
+      geo.dispose?.();                                // split clones out; drop the merged source
+    }
+    for (const g of [trunkGeo, leafGeo, cardGeo]) if (g) g.userData.cached = true;
+    tiers.push({ level: lv, tris, trunkGeo, leafGeo, cardGeo });
+  }
+  _treeTierCache.set(cacheKey, tiers);
+  return tiers;
+}
+
+// Per-tree-type hard-swap switch distances (m) by tier count. Tuned so the near
+// full-detail mesh only shows close, then the reduced meshes, then the 12-tri
+// billboard takes over in the deep distance where a flat card is imperceptible.
+const TREE_DISTS = { 1: [], 2: [70], 3: [50, 110], 4: [46, 88, 135], 5: [42, 78, 118, 165] };
+
+// Tree tier materials — shared via cachedMat between scatterTree and scatterTreeResident.
+const treeCardMat = (cardTex, alphaTest) => cachedMat(`treecard|${cardTex.uuid}|${alphaTest}`, () => { const m = new THREE.MeshStandardMaterial({ map: cardTex, roughness: 1, metalness: 0, side: THREE.DoubleSide }); m.alphaTest = Math.min(alphaTest, 0.4); m.transparent = false; return m; });
+const treeTrunkMat = (trunkTex) => cachedMat(`treetrunk|${trunkTex.uuid}`, () => new THREE.MeshStandardMaterial({ map: trunkTex, roughness: 0.9, metalness: 0 }));
+const treeLeafMat = (leafTex, alphaTest) => cachedMat(`treeleaf|${leafTex.uuid}|${alphaTest}`, () => { const m = new THREE.MeshStandardMaterial({ map: leafTex, roughness: 0.9, metalness: 0, side: THREE.DoubleSide }); m.alphaTest = alphaTest; m.transparent = false; return m; });
+
+// Synty Nature-Biomes tree: builds a per-tree LOD chain from the FBX's OWN LOD meshes.
+// Each real mesh LOD → two InstancedMeshes (opaque trunk + alphaTest leaf, UV-split);
+// the terminal billboard LOD → one InstancedMesh on the card atlas. Instances hard-swap
+// between tiers by camera distance (updateTreeLODs), so a dense Scotland forest costs a
+// handful of near LOD0 trees + cheap cards for everything beyond. Returns a Group for
+// the tile system. cardTexUrl may be null (billboard tier is then dropped).
+export async function scatterTree(url, trunkTexUrl, leafTexUrl, cardTexUrl, placements, { splitU = 0.12, alphaTest = 0.5, castShadow = true, dists = null } = {}) {
+  const master = await loadModel(url, { texture: null, twin: true }); // no atlas (per-part textures below) — twin ok: geometry is UV-split, file materials discarded
+  const tierGeos = treeLODTiers(url + '#tree', master, splitU);
+  if (!tierGeos.length) throw new Error(`no geometry in ${url}`);
+  const isTwin = /\.glb$/i.test(await resolveModelUrl(url, { twin: true }));
+  const [trunkTex, leafTex, cardTex] = await Promise.all([
+    trunkTexUrl ? treeTex(trunkTexUrl, 'trunk', isTwin) : null,
+    treeTex(leafTexUrl, 'leaf', isTwin),
+    cardTexUrl ? treeTex(cardTexUrl, 'card', isTwin) : null,
+  ]);
+  const base = url.split('/').pop();
+  const N = placements.length;
+  const mats = composeMatrices(placements);
+  const group = new THREE.Group();
+  group.name = `tree:${base}`;
+
+  const mkInst = (geo, mat, tag, ti) => {
+    const mesh = new THREE.InstancedMesh(geo, mat, N);
+    mesh.instanceMatrix.array.set(mats);
+    mesh.count = ti === 0 ? N : 0;               // tier0 shows all until the first rebucket
+    mesh.instanceMatrix.needsUpdate = true;
+    mesh.castShadow = castShadow && ti === 0;    // only the near tier casts shadows
+    mesh.receiveShadow = true;
+    mesh.name = `scatter:${base}:L${ti}:${tag}`;
+    mesh.matrixAutoUpdate = false; mesh.updateMatrix(); // origin-placed, instances carry transforms
+    group.add(mesh);
+    return mesh;
+  };
+
+  const tiers = [];
+  tierGeos.forEach((tg, ti) => {
+    const tier = {};
+    if (tg.cardGeo) {
+      if (!cardTex) return;                        // billboard LOD with no card atlas → drop the tier
+      tier.card = mkInst(tg.cardGeo, treeCardMat(cardTex, alphaTest), 'card', ti);
+    } else {
+      if (tg.trunkGeo && trunkTex) tier.trunk = mkInst(tg.trunkGeo, treeTrunkMat(trunkTex), 'trunk', ti);
+      if (tg.leafGeo) tier.leaf = mkInst(tg.leafGeo, treeLeafMat(leafTex, alphaTest), 'leaf', ti);
+    }
+    if (tier.trunk || tier.leaf || tier.card) tiers.push(tier);
+  });
+
+  const d = dists ?? TREE_DISTS[tiers.length] ?? Array.from({ length: Math.max(0, tiers.length - 1) }, (_, i) => 50 + i * 45);
+  const entry = { tiers, matrices: mats, positions: flatXZ(placements), count: N, dists: d };
+  const sph = groupSphere(placements, 16); // trees are tall — generous margin
+  for (const t of tiers) for (const m of [t.trunk, t.leaf, t.card]) if (m) m.boundingSphere = sph;
+  treeLodGroups.push(entry);
+  markLodDirty(); // fresh group starts tier0-everything — force the next rebucket cycle
+  group.userData.treeLodEntry = entry;
+  return group;
+}
+
+// RESIDENT biome tree: scatterTree's tiers (trunk+leaf per LOD + billboard card) at window
+// capacity, born empty, slice-streamed. Trees collide via their per-placement trunk circles
+// only (never the tile BVH — same as the per-tile builds), so no collider geometry is exposed.
+export async function scatterTreeResident(url, trunkTexUrl, leafTexUrl, cardTexUrl, cap, allPl, { splitU = 0.12, alphaTest = 0.5, castShadow = true, dists = null } = {}) {
+  const master = await loadModel(url, { texture: null, twin: true }); // no atlas (per-part textures) — twin ok, see scatterTree
+  const tierGeos = treeLODTiers(url + '#tree', master, splitU);
+  if (!tierGeos.length) throw new Error(`no geometry in ${url}`);
+  const isTwin = /\.glb$/i.test(await resolveModelUrl(url, { twin: true }));
+  const [trunkTex, leafTex, cardTex] = await Promise.all([
+    trunkTexUrl ? treeTex(trunkTexUrl, 'trunk', isTwin) : null,
+    treeTex(leafTexUrl, 'leaf', isTwin),
+    cardTexUrl ? treeTex(cardTexUrl, 'card', isTwin) : null,
+  ]);
+  const base = url.split('/').pop();
+  const group = new THREE.Group();
+  group.name = `tree:${base}`;
+  const sph = groupSphere(allPl, 16);
+
+  const mkInst = (geo, mat, tag, ti) => {
+    const mesh = new THREE.InstancedMesh(geo, mat, cap); // instanceMatrix born zero-filled (warm-flash safe)
+    mesh.count = 0;
+    mesh.castShadow = castShadow && ti === 0;    // only the near tier casts shadows
+    mesh.receiveShadow = true;
+    mesh.name = `scatter:${base}:L${ti}:${tag}`;
+    mesh.boundingSphere = sph;
+    mesh.matrixAutoUpdate = false; mesh.updateMatrix(); // origin-placed, instances carry transforms
+    group.add(mesh);
+    return mesh;
+  };
+
+  const tiers = [];
+  tierGeos.forEach((tg, ti) => {
+    const tier = {};
+    if (tg.cardGeo) {
+      if (!cardTex) return;
+      tier.card = mkInst(tg.cardGeo, treeCardMat(cardTex, alphaTest), 'card', ti);
+    } else {
+      if (tg.trunkGeo && trunkTex) tier.trunk = mkInst(tg.trunkGeo, treeTrunkMat(trunkTex), 'trunk', ti);
+      if (tg.leafGeo) tier.leaf = mkInst(tg.leafGeo, treeLeafMat(leafTex, alphaTest), 'leaf', ti);
+    }
+    if (tier.trunk || tier.leaf || tier.card) tiers.push(tier);
+  });
+
+  const d = dists ?? TREE_DISTS[tiers.length] ?? Array.from({ length: Math.max(0, tiers.length - 1) }, (_, i) => 50 + i * 45);
+  const matrices = new Float32Array(cap * 16), positions = new Float32Array(cap * 2);
+  const entry = { tiers, matrices, positions, count: 0, dists: d };
+  treeLodGroups.push(entry); // registered EMPTY (count=0) until tiles write slices
+  group.userData.treeLodEntry = entry;
+
+  const slices = new SliceTable(group.name, cap, [{ a: matrices, s: 16 }, { a: positions, s: 2 }]);
+  return {
+    group,
+    colliderName: null,
+    colliderGeometry: null, // trunk circles only
+    write(key, pl) {
+      const off = slices.alloc(key, pl.length);
+      if (off < 0) return null;
+      composeInto(matrices, off, pl);
+      for (let i = 0; i < pl.length; i++) { positions[(off + i) * 2] = pl[i].x; positions[(off + i) * 2 + 1] = pl[i].z; }
+      entry.count = slices.count;
+      markLodDirty();
+      return true; // success — but trees contribute nothing to the tile BVH (trunk circles only)
+    },
+    free(key) {
+      if (!slices.free(key)) return;
+      entry.count = slices.count;
+      markLodDirty();
+    },
+  };
+}
+
+// ---- biome-tree LOD registry: mirrors lodGroups/updateScatterLODs, but each tier
+// can carry a PAIR of instanced meshes (trunk + leaf) plus the billboard card, and
+// swaps are HARD (no dither) — alphaTest cutouts + alphaHash dissolve fight over the
+// same alpha, and a hard pop on a dense conifer at its switch distance is invisible.
+const treeLodGroups = [];
+let _treeLodCursor = 0;
+export function updateTreeLODs(px, pz) {
+  const n = treeLodGroups.length;
+  if (!n) return;
+  // instances beyond the camera far plane are clipped anyway — skip them entirely so the
+  // GPU never processes their vertices (residents hold a whole 5×5 window; without this the
+  // out-of-range majority still drew: 12.9M tris mid-countryside at LOW's 200m far plane)
+  const cull = (getQuality().cameraFar ?? 800) + 30;
+  const slice = Math.ceil(n / 3);                 // amortize: a third of the groups per call
+  const start = _treeLodCursor % n;
+  _treeLodCursor = (start + slice) % n;
+  for (let gi = 0; gi < slice; gi++) {
+    const g = treeLodGroups[(start + gi) % n];
+    const T = g.tiers.length;
+    const counts = new Array(T).fill(0);
+    for (let i = 0; i < g.count; i++) {
+      const dx = g.positions[i * 2] - px, dz = g.positions[i * 2 + 1] - pz; // flat [x,z] pairs
+      const dist = Math.sqrt(dx * dx + dz * dz);
+      if (dist > cull) continue;
+      let t = 0; while (t < g.dists.length && dist >= g.dists[t]) t++;
+      if (t >= T) t = T - 1;                        // instances past the last edge → farthest tier
+      const k = counts[t]++;
+      const tier = g.tiers[t];
+      const src = g.matrices.subarray(i * 16, i * 16 + 16);
+      if (tier.trunk) tier.trunk.instanceMatrix.array.set(src, k * 16);
+      if (tier.leaf) tier.leaf.instanceMatrix.array.set(src, k * 16);
+      if (tier.card) tier.card.instanceMatrix.array.set(src, k * 16);
+    }
+    for (let t = 0; t < T; t++) {
+      const tier = g.tiers[t];
+      for (const m of [tier.trunk, tier.leaf, tier.card]) {
+        if (!m) continue;
+        m.count = counts[t];
+        m.visible = counts[t] > 0;   // skip count:0 tiers from the per-frame render-list walk
+        m.instanceMatrix.needsUpdate = true;
+        // boundingSphere: the conservative whole-group sphere assigned at build covers every
+        // bucketing, so no per-rebucket computeBoundingSphere (a full matrix pass per tier).
+      }
+    }
+  }
+}
+
+const _cm = new THREE.Matrix4(), _cq = new THREE.Quaternion(), _cUP = new THREE.Vector3(0, 1, 0);
+const _cv = new THREE.Vector3(), _cs = new THREE.Vector3();
+// Compose placement transforms into `arr` starting at instance `offset` (16 floats/instance).
+function composeInto(arr, offset, placements) {
+  for (let i = 0; i < placements.length; i++) {
+    const p = placements[i];
+    _cq.setFromAxisAngle(_cUP, p.ry ?? 0);
+    _cm.compose(_cv.set(p.x, p.y, p.z), _cq, _cs.setScalar(p.s ?? 1));
+    arr.set(_cm.elements, (offset + i) * 16);
+  }
+}
+function composeMatrices(placements) {
+  const arr = new Float32Array(placements.length * 16);
+  composeInto(arr, 0, placements);
+  return arr;
+}
+// Flat [x0,z0, x1,z1, …] positions — the rebucketers' distance source. Flat (not array-of-pairs)
+// so resident entries can copyWithin it during slice compaction.
+function flatXZ(placements) {
+  const a = new Float32Array(placements.length * 2);
+  for (let i = 0; i < placements.length; i++) { a[i * 2] = placements[i].x; a[i * 2 + 1] = placements[i].z; }
+  return a;
+}
+
+// ---- RESIDENT scatter: the slice-table allocator --------------------------------
+// r184 WebGPU pays ~3 pipeline-cache entries per new InstancedMesh OBJECT (getNodeBuilderState +
+// pipeline + bind-group) even with fully shared geometry/material/texture — per-tile mesh churn was
+// the 150-500ms boundary hitch. Resident meshes are created ONCE (empty, zero-filled buffers) and
+// streamed INTO: each tile owns a contiguous slice of the instance arrays; tile enter appends a
+// slice, tile leave compacts it out (copyWithin over every parallel array). Capacity = the max any
+// 5×5 tile window can hold (computed by TileField.buildResidents), so overflow means a bug — shout
+// rather than clamp (silent overflow = vanishing forests).
+class SliceTable {
+  constructor(name, cap, arrays) { this.name = name; this.cap = cap; this.count = 0; this.list = []; this.arrays = arrays; } // arrays: [{a: TypedArray, s: stride}]
+  alloc(key, len) {
+    if (this.count + len > this.cap) { console.error(`[resident] ${this.name}: slice overflow (${this.count}+${len} > cap ${this.cap}) — tile content dropped`); return -1; }
+    const offset = this.count;
+    this.list.push({ key, offset, len });
+    this.count += len;
+    return offset;
+  }
+  free(key) {
+    const i = this.list.findIndex((sl) => sl.key === key);
+    if (i < 0) return false; // idempotent — a tile disposed mid-build frees before its slice exists
+    const { offset, len } = this.list[i];
+    for (const { a, s } of this.arrays) a.copyWithin(offset * s, (offset + len) * s, this.count * s);
+    for (let j = i + 1; j < this.list.length; j++) this.list[j].offset -= len;
+    this.list.splice(i, 1);
+    this.count -= len;
+    return true;
+  }
+}
+
+// ---- octahedral-impostor billboard material (hard-swap tier; no distance fade) ----
+// `center`/`size` are TSL nodes: instanced attributes for scatter, uniforms for a
+// single building. Always camera-facing; samples the baked atlas by view angle.
+function impostorMaterial(albedo, desc, flipV, center, size, tint = false) {
+  const mat = new THREE.MeshBasicNodeMaterial(); // unlit: the atlas already has light baked
+  mat.side = THREE.DoubleSide;
+  const grid = float(desc.grid);
+
+  // view-space billboard: instance centre → view space, offset by the quad corner
+  // along the camera-aligned X/Y axes, then project. Always faces the camera.
+  mat.vertexNode = Fn(() => {
+    const mv = modelViewMatrix.mul(vec4(center, 1.0));
+    const corner = positionGeometry.xy; // PlaneGeometry → [-0.5, 0.5]
+    const p = vec4(mv.x.add(corner.x.mul(size.x)), mv.y.add(corner.y.mul(size.y)), mv.z, float(1.0));
+    return cameraProjectionMatrix.mul(p);
+  })();
+
+  // hemi-octahedral cell from the model→camera direction (descriptor encoding)
+  const d = normalize(cameraPosition.sub(center));
+  const an = max(abs(d.x).add(abs(d.y)).add(abs(d.z)), float(1e-4));
+  const n = d.div(an);
+  const u = n.x.add(n.z).mul(0.5).add(0.5);
+  const v = n.z.sub(n.x).mul(0.5).add(0.5);
+  const cell = floor(vec2(u, v).mul(grid)).clamp(float(0), grid.sub(1));
+  // billboard top (uv.y=1) → tree top within its cell. flipV flips the WITHIN-cell V.
+  const qy = flipV ? oneMinus(uv().y) : uv().y;
+  const auv = cell.add(vec2(uv().x, qy)).div(grid);
+  const samp = texture(albedo, auv);
+  // the atlas has DAYLIGHT baked in — scale toward moonlit blue at night, or distant
+  // impostors glow brighter than the lit foreground ("distance brighter than close").
+  // Night floor tuned DOWN + moon-blue (was 0.30/0.34/0.48 — impostors read warm-bright
+  // against real walls lit by the 0x9fb4e0 moon); the day term keeps day at exactly 1.
+  let col = samp.rgb.mul(vec3(0.17, 0.21, 0.34).add(vec3(0.83, 0.79, 0.66).mul(uDayness)));
+  if (tint) col = col.mul(tintAt(center.xz)); // same world-keyed field as the mesh tiers — no pop at the swap
+  mat.colorNode = col;
+  mat.opacityNode = samp.a;
+  mat.alphaHash = true;
+  return mat;
+}
+
+// Cross-fade ramp for a tier: dither IN above nearEdge, OUT above farEdge (either
+// may be null at the chain ends). `distNode` is per-fragment camera distance.
+function tierRamp(nearEdge, farEdge, B, distNode) {
+  let ramp = null;
+  if (nearEdge != null) ramp = smoothstep(float(nearEdge - B), float(nearEdge + B), distNode);
+  if (farEdge != null) {
+    const out = oneMinus(smoothstep(float(farEdge - B), float(farEdge + B), distNode));
+    ramp = ramp ? ramp.mul(out) : out;
+  }
+  return ramp; // null → no fade (single-tier object)
+}
+
+// Default tier switch distances (metres) by tier count — full mesh near, reduced
+// glodify meshes through the mid range, impostor billboard in the deep distance.
+const DEFAULT_DISTS = { 2: [62], 3: [48, 108], 4: [40, 80, 140], 5: [36, 68, 105, 145] }; // one notch nearer than the originals — a few ms of LOD0 tris back, swaps hidden by the dither fades
+
+// Impostor descriptors were re-fetched on EVERY scatterChain call (per tile, pre-resident) —
+// cache the JSON promise per URL. Descriptors are read-only.
+const _impJsonCache = new Map();
+function fetchImpJson(url) {
+  let p = _impJsonCache.get(url);
+  if (!p) { p = fetch(url).then((r) => r.json()); _impJsonCache.set(url, p); }
+  return p;
+}
+
+// PASS 1 (shared by scatterChain + scatterChainResident) — gather every mesh tier's GEOMETRY
+// plus the impostor descriptor/albedo. Materials wait for pass 2: the LOD fade distance depends
+// on the FINAL tier count, and each tier's material (fade baked in) is cached and SHARED across
+// tiles. Fresh NodeMaterials per tile were the measured freeze source — every new node graph is
+// a new pipeline cache key, so streamed tiles COMPILED pipelines mid-play (freeze profiler:
+// pipe:+20 on a boundary) even though the boot warm had compiled this type.
+async function chainParts(url, lodUrls, impJsonUrl, textureUrl, { lod = 0, tint = false } = {}) {
+  const _isGLB = /\.glb$/i.test(await resolveModelUrl(url, { texture: textureUrl }));
+  const [master, tex] = await Promise.all([loadModel(url, { texture: textureUrl }), loadTexture(textureUrl, _isGLB ? { flipY: false } : {})]);
+  const lod0 = flattenCached(url, master, lod);
+  if (!lod0) throw new Error(`no geometry for ${url}`);
+  const base = url.split('/').pop().replace(/\.fbx$/i, '');
+  const geoTiers = [{ geo: lod0.geometry, name: `scatter:${base}`, key: `chain0|${tex.uuid}|${tint}`, hasColor: false }];
+  for (const lu of (lodUrls || [])) {
+    try {
+      const scene = await loadGLB(lu); scene.scale.setScalar(0.01);
+      const flat = flattenCached(lu, scene, 0);
+      if (!flat) continue;
+      geoTiers.push({ geo: flat.geometry, name: `scatterLOD:${lu.split('/').pop()}`, key: `chainL|${flat.hasColor ? 'vc' : tex.uuid}|${tint}`, hasColor: flat.hasColor });
+    } catch { /* missing LOD glb → skip this tier */ }
+  }
+  let imp = null;
+  if (impJsonUrl) {
+    try {
+      const desc = await fetchImpJson(impJsonUrl);
+      const dir = impJsonUrl.slice(0, impJsonUrl.lastIndexOf('/'));
+      const albedo = await loadTexture(`${dir}/${desc.maps.albedo}`);
+      imp = { desc, albedo };
+    } catch { /* missing impostor → skip */ }
+  }
+  return { tex, base, geoTiers, imp };
+}
+
+// PASS 2 tier material via the shared cache. ONLY the nearer tier dithers OUT at each boundary;
+// the farther tier stays SOLID and is revealed through the holes (dithering both punches holes
+// clean through → speckle). The fade opacityNode is baked INTO the cached material, keyed by
+// (texture|vertexColor, tint, farEdge) — identical tiers across every caller share ONE
+// material/pipeline, and a different fade distance can never leak between types.
+function chainTierMat(g, tex, tint, farEdge, B) {
+  return cachedMat(`${g.key}|${farEdge}`, () => {
+    const mm = g.hasColor
+      ? new THREE.MeshStandardNodeMaterial({ vertexColors: true, roughness: 1, metalness: 0 })
+      : new THREE.MeshStandardNodeMaterial({ map: tex, roughness: 0.9, metalness: 0 });
+    if (tint) mm.colorNode = (g.hasColor ? attribute('color', 'vec3') : texture(tex, uv()).rgb).mul(tintAt(positionWorld.xz));
+    if (farEdge != null) { mm.opacityNode = oneMinus(smoothstep(float(farEdge - B), float(farEdge + B), camDist)); mm.alphaHash = true; }
+    return mm;
+  });
+}
+
+// Billboard quad with per-instance centre/size attributes sized to `cap` (zero-filled).
+function impQuad(cap) {
+  const quad = new THREE.PlaneGeometry(1, 1);
+  quad.setAttribute('iCenter', new THREE.InstancedBufferAttribute(new Float32Array(cap * 3), 3));
+  quad.setAttribute('iSize', new THREE.InstancedBufferAttribute(new Float32Array(cap * 2), 2));
+  return quad;
+}
+
+// Multi-tier LOD chain: LOD0 (full FBX) → LOD1/2/3 (glodify meshes) → LOD4 impostor.
+// Instances hard-swap between tiers by camera distance (updateScatterLODs). lodUrls
+// = ordered [LOD1.glb, LOD2.glb, LOD3.glb] (missing ones are skipped); impJsonUrl
+// optional (adds the impostor as the farthest tier).
+export async function scatterChain(url, lodUrls, impJsonUrl, textureUrl, placements, { castShadow = true, lod = 0, dists, flipV = false, tint = false } = {}) {
+  const { tex, base, geoTiers, imp } = await chainParts(url, lodUrls, impJsonUrl, textureUrl, { lod, tint });
+  const N = placements.length;
+  const matrices = composeMatrices(placements);
+  const tierCount = geoTiers.length + (imp ? 1 : 0);
+  const d = dists ?? DEFAULT_DISTS[tierCount] ?? Array.from({ length: tierCount - 1 }, (_, i) => 50 + i * 50);
+  const B = 14; // cross-fade half-width (m)
+
+  const tiers = [];
+  geoTiers.forEach((g, t) => {
+    const mesh = new THREE.InstancedMesh(g.geo, chainTierMat(g, tex, tint, t < d.length ? d[t] : null, B), N);
+    mesh.castShadow = t === 0 && castShadow; mesh.receiveShadow = true; mesh.name = g.name;
+    mesh.instanceMatrix.array.set(matrices); mesh.count = 0;
+    tiers.push({ mesh });
+  });
+  if (imp) {
+    const quad = impQuad(N);
+    const iCenter = quad.getAttribute('iCenter').array, iSize = quad.getAttribute('iSize').array;
+    const srcCenter = new Float32Array(N * 3), srcSize = new Float32Array(N * 2);
+    const S = 0.01, bw = imp.desc.billboardSize * S, cy = (imp.desc.bounds?.center?.[1] ?? 0) * S;
+    placements.forEach((p, i) => {
+      const sc = p.s ?? 1;
+      srcCenter[i * 3] = p.x; srcCenter[i * 3 + 1] = (p.y ?? 0) + cy * sc; srcCenter[i * 3 + 2] = p.z;
+      srcSize[i * 2] = bw * sc; srcSize[i * 2 + 1] = bw * sc;
+    });
+    iCenter.set(srcCenter); iSize.set(srcSize); // initial: show all as impostors until first rebucket
+    const impMat = cachedMat(`imp|${imp.albedo.uuid}|${flipV}|${tint}`, () => impostorMaterial(imp.albedo, imp.desc, flipV, attribute('iCenter', 'vec3'), attribute('iSize', 'vec2'), tint));
+    const impMesh = new THREE.InstancedMesh(quad, impMat, N);
+    impMesh.frustumCulled = false; impMesh.castShadow = false; impMesh.receiveShadow = false;
+    impMesh.count = N; impMesh.name = `impostor:${base}`;
+    tiers.push({ imp: impMesh, iCenter, iSize, srcCenter, srcSize });
+  }
+
+  const entry = { tiers, matrices, positions: flatXZ(placements), count: N, dists: d, band: B };
+  const sph = groupSphere(placements);
+  for (const t of tiers) if (t.mesh) t.mesh.boundingSphere = sph; // (impostors are frustumCulled=false — no sphere needed)
+  lodGroups.push(entry);
+  markLodDirty(); // fresh chain shows impostors-everywhere until bucketed — force the next cycle
+
+  const group = new THREE.Group();
+  for (const t of tiers) { const m = t.mesh ?? t.imp; m.matrixAutoUpdate = false; m.updateMatrix(); group.add(m); } // origin-placed
+  group.userData.scatterEntry = entry; // lets disposeScatterGroup drop the lodGroups entry on tile unload
+  return group;
+}
+
+// RESIDENT chain: the same tiers/cached-materials as scatterChain, but capacity-sized, born
+// empty, and slice-streamed — created ONCE at boot, no meshes ever created/destroyed at tile
+// boundaries. New slices surface on the next rebucket cycle (markLodDirty): tiles enter at
+// ≥360m, past the 320m max fog, so the ≤1s bucket latency is invisible.
+export async function scatterChainResident(url, lodUrls, impJsonUrl, textureUrl, cap, allPl, { castShadow = true, lod = 0, dists, flipV = false, tint = false } = {}) {
+  const { tex, base, geoTiers, imp } = await chainParts(url, lodUrls, impJsonUrl, textureUrl, { lod, tint });
+  const tierCount = geoTiers.length + (imp ? 1 : 0);
+  const d = dists ?? DEFAULT_DISTS[tierCount] ?? Array.from({ length: tierCount - 1 }, (_, i) => 50 + i * 50);
+  const B = 14;
+  const matrices = new Float32Array(cap * 16);  // zero-filled: the boot warm's count=1 flash draws a scale-0 instance
+  const positions = new Float32Array(cap * 2);
+  const sph = groupSphere(allPl);
+  const group = new THREE.Group();
+
+  const tiers = [];
+  geoTiers.forEach((g, t) => {
+    const mesh = new THREE.InstancedMesh(g.geo, chainTierMat(g, tex, tint, t < d.length ? d[t] : null, B), cap);
+    mesh.castShadow = t === 0 && castShadow; mesh.receiveShadow = true; mesh.name = g.name;
+    mesh.count = 0;
+    mesh.boundingSphere = sph;
+    mesh.matrixAutoUpdate = false; mesh.updateMatrix();
+    group.add(mesh);
+    tiers.push({ mesh });
+  });
+  let impData = null;
+  if (imp) {
+    const quad = impQuad(cap);
+    const S = 0.01;
+    impData = { srcCenter: new Float32Array(cap * 3), srcSize: new Float32Array(cap * 2), bw: imp.desc.billboardSize * S, cy: (imp.desc.bounds?.center?.[1] ?? 0) * S };
+    const impMat = cachedMat(`imp|${imp.albedo.uuid}|${flipV}|${tint}`, () => impostorMaterial(imp.albedo, imp.desc, flipV, attribute('iCenter', 'vec3'), attribute('iSize', 'vec2'), tint));
+    const impMesh = new THREE.InstancedMesh(quad, impMat, cap);
+    impMesh.frustumCulled = false; impMesh.castShadow = false; impMesh.receiveShadow = false;
+    impMesh.count = 0; impMesh.name = `impostor:${base}`;
+    impMesh.matrixAutoUpdate = false; impMesh.updateMatrix();
+    group.add(impMesh);
+    tiers.push({ imp: impMesh, iCenter: quad.getAttribute('iCenter').array, iSize: quad.getAttribute('iSize').array, srcCenter: impData.srcCenter, srcSize: impData.srcSize });
+  }
+
+  const entry = { tiers, matrices, positions, count: 0, dists: d, band: B };
+  lodGroups.push(entry); // registered EMPTY — the boot world-BVH bake reads entry.count (must be 0 until after it)
+  group.userData.scatterEntry = entry;
+
+  const arrays = [{ a: matrices, s: 16 }, { a: positions, s: 2 }];
+  if (impData) arrays.push({ a: impData.srcCenter, s: 3 }, { a: impData.srcSize, s: 2 });
+  const slices = new SliceTable(`chain:${base}`, cap, arrays);
+  return {
+    group,
+    colliderName: `scatter:${base}`,
+    colliderGeometry: geoTiers[0].geo, // LOD0 collides across the tile's FULL instance set (as before)
+    write(key, pl) {
+      const off = slices.alloc(key, pl.length);
+      if (off < 0) return null;
+      composeInto(matrices, off, pl);
+      for (let i = 0; i < pl.length; i++) { positions[(off + i) * 2] = pl[i].x; positions[(off + i) * 2 + 1] = pl[i].z; }
+      if (impData) {
+        for (let i = 0; i < pl.length; i++) {
+          const p = pl[i], sc = p.s ?? 1, j = off + i;
+          impData.srcCenter[j * 3] = p.x; impData.srcCenter[j * 3 + 1] = (p.y ?? 0) + impData.cy * sc; impData.srcCenter[j * 3 + 2] = p.z;
+          impData.srcSize[j * 2] = impData.bw * sc; impData.srcSize[j * 2 + 1] = impData.bw * sc;
+        }
+      }
+      entry.count = slices.count;
+      markLodDirty();
+      return matrices.slice(off * 16, (off + pl.length) * 16); // per-tile copy for the tile BVH (survives compaction)
+    },
+    free(key) {
+      if (!slices.free(key)) return;
+      entry.count = slices.count;
+      markLodDirty(); // stale tier packing self-heals on the next rebucket (the freed tile is behind fog)
+    },
+  };
+}
+
+// Back-compat: 2-tier (LOD0 + one glodify LOD mesh), no impostor — used for paths.
+export async function scatterLOD(url, lodUrl, textureUrl, placements, opts = {}) {
+  return scatterChain(url, [lodUrl], null, textureUrl, placements, opts);
+}
+
+// Full chain ending in an impostor. Which tiers actually get built is read per item
+// from lodConfig.json (edited in /lodconfig.html); LOD0 is always on.
+function impostorTierUrls(impJsonUrl) {
+  const path = impJsonUrl.replace(/_LOD4_impostor\.json$/i, '');
+  const name = path.split('/').pop();
+  const cfg = LOD_CONFIG[name] ?? DEFAULT_TIERS;
+  const lodUrls = [];
+  if (cfg.includes('lod1')) lodUrls.push(`${path}_LOD1.glb`);
+  if (cfg.includes('lod2')) lodUrls.push(`${path}_LOD2.glb`);
+  if (cfg.includes('lod3')) lodUrls.push(`${path}_LOD3.glb`);
+  return { lodUrls, imp: cfg.includes('impostor') ? impJsonUrl : null };
+}
+export async function scatterImpostor(url, impJsonUrl, textureUrl, placements, opts = {}) {
+  const { lodUrls, imp } = impostorTierUrls(impJsonUrl);
+  return scatterChain(url, lodUrls, imp, textureUrl, placements, opts);
+}
+
+// Resident variants of the back-compat wrappers (the zones manifest uses these).
+export async function scatterLODResident(url, lodUrl, textureUrl, cap, allPl, opts = {}) {
+  return scatterChainResident(url, [lodUrl], null, textureUrl, cap, allPl, opts);
+}
+export async function scatterImpostorResident(url, impJsonUrl, textureUrl, cap, allPl, opts = {}) {
+  const { lodUrls, imp } = impostorTierUrls(impJsonUrl);
+  return scatterChainResident(url, lodUrls, imp, textureUrl, cap, allPl, opts);
+}
+
+// Rebucket every chain around the player: each instance lands in exactly one tier
+// by camera distance (hard swap). One pass of distance checks + row/attribute copies.
+let _lodCursor = 0;
+export function updateScatterLODs(px, pz) {
+  // Amortized: rebucket a THIRD of the groups per call (round-robin). Doing all
+  // of them in one frame every 0.35s was a visible saw-tooth spike; each group
+  // still refreshes about once a second, well inside the cross-fade bands.
+  const n = lodGroups.length;
+  if (!n) return;
+  const cull = (getQuality().cameraFar ?? 800) + 30; // beyond the far plane = clipped anyway — never bucket it
+  const slice = Math.ceil(n / 3);
+  const start = _lodCursor % n;
+  _lodCursor = (start + slice) % n;
+  for (let gi = 0; gi < slice; gi++) {
+    const g = lodGroups[(start + gi) % n];
+    const T = g.tiers.length, B = g.band ?? 0;
+    const counts = new Array(T).fill(0);
+    for (let i = 0; i < g.count; i++) {
+      const dx = g.positions[i * 2] - px, dz = g.positions[i * 2 + 1] - pz; // flat [x,z] pairs
+      const dist = Math.sqrt(dx * dx + dz * dz);
+      if (dist > cull) continue;
+      // an instance renders in every tier whose [nearEdge-B, farEdge+B] contains it —
+      // so it appears in BOTH tiers across a boundary band and the ramps cross-fade.
+      for (let t = 0; t < T; t++) {
+        const lo = t > 0 ? g.dists[t - 1] - B : -Infinity;
+        const hi = t < g.dists.length ? g.dists[t] + B : Infinity;
+        if (dist < lo || dist > hi) continue;
+        const tier = g.tiers[t], k = counts[t]++;
+        if (tier.imp) {
+          tier.iCenter.set(tier.srcCenter.subarray(i * 3, i * 3 + 3), k * 3);
+          tier.iSize.set(tier.srcSize.subarray(i * 2, i * 2 + 2), k * 2);
+        } else {
+          tier.mesh.instanceMatrix.array.set(g.matrices.subarray(i * 16, i * 16 + 16), k * 16);
+        }
+      }
+    }
+    for (let t = 0; t < T; t++) {
+      const tier = g.tiers[t];
+      if (tier.imp) {
+        tier.imp.count = counts[t];
+        tier.imp.visible = counts[t] > 0;   // count:0 impostor tiers are frustumCulled=false → skip the render-list walk
+        tier.imp.geometry.getAttribute('iCenter').needsUpdate = true;
+        tier.imp.geometry.getAttribute('iSize').needsUpdate = true;
+      } else {
+        tier.mesh.count = counts[t];
+        tier.mesh.visible = counts[t] > 0;
+        tier.mesh.instanceMatrix.needsUpdate = true;
+        // boundingSphere: whole-group sphere assigned at build — no per-rebucket recompute.
+      }
+    }
+  }
+}