sindicate 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
   "type": "module",
   "main": "src/index.js",

package/src/systems/climbing.js

@@ -11,7 +11,10 @@ import * as THREE from 'three/webgpu';
 const CLIMB_SPEED = 1.7;   // m/s along the rungs (match the up/down loop cadence)
 const ANIM_SPEED = 2;      // clip playback ×; the mocap loops are slow, so 2× keeps the hands with the movement
 const BODY_OFF = 0.30;     // player root sits this far back from the ladder line (gripping side)
-const FACE_SIGN = 1;       // +1 for western's ladder props (fable used −1); flips which side the climber grips + faces
+// Which side of the ladder the climber grips + faces is a property of the GAME's
+// ladder props: setClimbContent({ faceSign: 1 }) — western +1, fable −1.
+let FACE_SIGN = 1;
+export function setClimbContent({ faceSign = null } = {}) { if (faceSign != null) FACE_SIGN = faceSign; }
 const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
 const _axis = new THREE.Vector3(), _face = new THREE.Vector3();
 
@@ -133,4 +136,39 @@ export class Climbing {
     this.mode = 'off'; this.ladder = null;
     p.busy = false; p.vy = 0; p.airborne = false; p._visualY = p.position.y;
   }
+
+  // ---- fable-lineage conveniences (unioned): ladder scan + input-driven mount ----
+  _ladders() { return this.game.world?.castle?.ladders || null; }
+
+  nearby() {
+    const ls = this._ladders(); if (!ls || !ls.length) return null;
+    const p = this.player.position; let best = null, bd = REACH * REACH;
+    for (const l of ls) {
+      const dy = p.y - l.base.y;
+      if (dy < -1.0 || dy > l.height + 1.0) continue;
+      const dx = l.base.x - p.x, dz = l.base.z - p.z, d = dx * dx + dz * dz;
+      if (d < bd) { bd = d; best = l; }
+    }
+    return best;
+  }
+
+  tryMount(input) {
+    if (this.active || !input.hit('KeyE')) return false;
+    const l = this.nearby(); if (!l) return false;
+    const atTop = this.player.position.y > l.base.y + l.height - 1.2;
+    this._solve(l);
+    this.ladder = l; this.mode = 'mounting'; this.h = atTop ? l.height : 0;
+    this._place(); this.player.busy = true;
+    this.player.animator.play('climbMount', { once: true, fade: 0.12, onDone: () => { if (this.mode === 'mounting') this.mode = 'climbing'; } });
+    return true;
+  }
+
+  debugTeleport() {
+    const ls = this._ladders(); if (!ls || !ls.length) { console.log('[climb] no ladders loaded yet'); return; }
+    this._dbg = ((this._dbg ?? -1) + 1) % ls.length;
+    const l = ls[this._dbg], p = this.player;
+    p.position.set(l.base.x, l.base.y, l.base.z); p._visualY = l.base.y; p.vy = 0; p._capGrounded = false;
+    console.log(`[climb] -> ladder ${this._dbg + 1}/${ls.length} ${l.file} base=(${l.base.x.toFixed(1)},${l.base.y.toFixed(1)},${l.base.z.toFixed(1)}) h=${l.height.toFixed(1)} — press E to mount`);
+  }
+
 }

package/src/systems/footsteps.js

@@ -4,7 +4,7 @@
 // Real recordings (cplomedia Footsteps pack) via audio.loadSamples/sample. Six surfaces × six variants.
 import * as THREE from 'three/webgpu';
 // register the road query before surface classification: setFootstepTerrain({ roadDistance })
-let FT = { roadDistance: () => 1e9 };
+let FT = { roadDistance: () => 1e9, classify: null };   // classify(x,z) -> surface replaces the built-in ground read
 export function setFootstepTerrain(t) { FT = { ...FT, ...t }; }
 
 const _fv = new THREE.Vector3();
@@ -59,6 +59,7 @@ export class Footsteps {
     // a coach roof is boards, and there is no board set: 'stone' is the hard-packed one (SURFACES)
     const d = this.game.player?.platform;
     if (d) return d.deck.surface ?? 'stone';
+    if (FT.classify) return FT.classify(x, z);   // the game's own surface model (fable: plazas/swamp/sand/snow)
     return groundSurface(this.game, x, z);
   }
 

package/src/systems/vat.js

@@ -21,7 +21,9 @@
 // /__save-vatbin, already registered in vite.config.js). Playing once cooks everything.
 import * as THREE from 'three/webgpu';
 import { Fn, texture, attribute, uniform, uniformArray, vec2, int, float, floor, mod, uv } from 'three/tsl';
-import { loadModel, instantiate, loadTexture } from '../core/assets.js';
+import { loadModel, instantiate, loadTexture, applyAtlas, resolveModelUrl } from '../core/assets.js';
+import { buildRetargetContext, retargetClip } from '../core/retarget.js';
+import { mergeCharacterBody } from './entity.js';
 
 // Stack N coat textures side-by-side into one atlas, so a herd can show a different colour per
 // individual (a per-instance aLayer offsets U). Horizontal keeps V/flipY identical to the original.
@@ -287,6 +289,14 @@ export async function loadSpeciesVAT(def) {
     console.warn(`[vat] ${def.rig.split('/').slice(-2)[0]}: no clip and no alias for "${n}" — it will play clip 0`);
     clipIndex[n] = 0;
   }
+  // SINGLE-TAKE RIGS (fable's seagull ships one unnamed "Take 001" reel): when no regex
+  // matched anything, bake the first source clip so the reel itself is clip 0 — the
+  // missing-pass then aliases everything onto it (flySegment clamps it to the flying part).
+  if (!baked.length && srcClips.length) {
+    const first = Object.keys(def.clips)[0] ?? 'idle';
+    clipIndex[first] = 0;
+    baked.push(trimClip(srcClips[0], first));
+  }
   if (!baked.length) throw new Error(`no clips to bake for ${def.rig}`);
   // idles at 15 fps — halves the rows they cost in the VAT texture, and a sway does not need 30
   for (const c of baked) if (!/^(walk|run)$/.test(c.name)) (c.userData ??= {}).bakeFps = 15;
@@ -294,6 +304,66 @@ export async function loadSpeciesVAT(def) {
   const vat = await bakeVATCached(`${def.rig}|${def.anims ?? ''}`, rig, skinned, baked);
   vat.playFps = vat.fps * (def.playRate ?? 1);
 
+  // Single-take rigs (the seagull ships ONE "Take 001" reel: fly + perch + preen…) play the
+  // WHOLE reel — mid-air birds folded their wings ("wings in a diagonal shape around the
+  // body"). flySegment:'auto' scans the baked frames for the longest run of near-max WINGSPAN
+  // and clamps every clip window to it, so airborne playback stays inside the flying section.
+  if (Array.isArray(def.flySegment) && vat.table.length) {
+    // explicit window (frames, picked with animaltest's loop sliders) — clamp every clip to it.
+    // The END is a HINT: an arbitrary slice of a longer reel rarely lands on a perfect cycle,
+    // so the wrap popped ("cutting weirdly"). Snap to the frame near the hint whose POSE best
+    // matches the start frame (RMS over sampled verts of the baked data) → seamless loop.
+    const [fs, feHint] = def.flySegment;
+    const d = vat.data ?? vat.tex.image.data, W = vat.W, RPF = vat.rowsPerFrame;
+    const dist = (a, b) => {
+      let s = 0, n = 0;
+      for (let i = 0; i < vat.vCount; i += 7) {
+        const ia = ((a * RPF) * W + i) * 4, ib = ((b * RPF) * W + i) * 4;
+        const dx = d[ia] - d[ib], dy = d[ia + 1] - d[ib + 1], dz = d[ia + 2] - d[ib + 2];
+        s += dx * dx + dy * dy + dz * dz; n++;
+      }
+      return s / n;
+    };
+    let fe = feHint, bd = Infinity;
+    const maxF = vat.table[0].frames - 1;
+    for (let k = Math.max(fs + 8, feHint - 7); k <= Math.min(maxF, feHint + 7); k++) {
+      const dd = dist(fs, k);
+      if (dd < bd) { bd = dd; fe = k; }
+    }
+    console.log(`[vat] ${def.rig.split('/').pop()} window ${fs}..${feHint} → loop-snapped to ${fs}..${fe}`);
+    const bl = Math.max(2, fe - fs);
+    for (const e of vat.table) { e.start += fs; e.frames = Math.min(bl, e.frames - fs); }
+  } else if (def.flySegment === 'auto' && vat.table.length) {
+    const d = vat.data ?? vat.tex.image.data, W = vat.W, RPF = vat.rowsPerFrame;
+    const block = vat.table[0];                       // all blocks are copies of the same take
+    const spans = [];
+    let mx = 0;
+    for (let f = 0; f < block.frames; f++) {
+      const base = (block.start + f) * RPF * W * 4;
+      let mnX = 1e9, mxX = -1e9, mnZ = 1e9, mxZ = -1e9;
+      const cnt = Math.min(vat.vCount, W * RPF);
+      for (let i = 0; i < cnt; i += 3) {
+        const x = d[base + i * 4], z = d[base + i * 4 + 2];
+        if (x < mnX) mnX = x; if (x > mxX) mxX = x;
+        if (z < mnZ) mnZ = z; if (z > mxZ) mxZ = z;
+      }
+      const s = Math.max(mxX - mnX, mxZ - mnZ);
+      spans.push(s); if (s > mx) mx = s;
+    }
+    const th = mx * 0.6;   // 0.82 cut the flap DIPS (wings mid-beat) and left a 9-frame stutter;
+                           // 0.6 keeps whole flap cycles in and still rejects folded-wing sections (~0.4×)
+    let bs = 0, bl = 0, cs = -1;
+    for (let f = 0; f <= spans.length; f++) {
+      const ok = f < spans.length && spans[f] >= th;
+      if (ok && cs < 0) cs = f;
+      if (!ok && cs >= 0) { if (f - cs > bl) { bl = f - cs; bs = cs; } cs = -1; }
+    }
+    if (bl >= 10) for (const e of vat.table) { e.start += bs; e.frames = bl; }
+    console.log(`[vat] ${def.rig.split('/').pop()} flySegment auto: frames ${bs}..${bs + bl} of ${block.frames}`);
+    // DEV: post the frame profile to the perf sink so the reel structure is readable from disk
+    if (import.meta.env?.DEV) { try { fetch('/__perf', { method: 'POST', body: JSON.stringify({ FLYSEG: { rig: def.rig, chosen: [bs, bs + bl], spans: spans.map((s) => +s.toFixed(2)) } }) }); } catch (e) { /* sink offline */ } }
+  }
+
   // Size and ground the species from THE BAKE ITSELF (frame-0 posed positions) — the exact space
   // vatMaterial renders from. Bind-space geometry.boundingBox is a trap on GLB rigs: the bind
   // geometry sits in a different space than the posed skin, which pins def.height against the wrong
@@ -325,3 +395,67 @@ export async function loadSpeciesVAT(def) {
   geometry.setAttribute('vertexId', new THREE.BufferAttribute(vid, 1));
   return { vat, geometry, albedo, layers, scale, clipIndex, walkSpeed, runSpeed, footY: box.min.y * scale, size };
 }
+
+// ---- HUMANOID CROWD BAKING (unioned from fable) -------------------------------------
+// Humanoid crowd bake (VAT_CROWD_PLAN step 1): a Synty character variant → VAT. Differs from
+// loadSpeciesVAT in exactly two ways: (a) modular bodies are COLLAPSED to one SkinnedMesh first
+// (mergeCharacterBody — the bake reads a single geometry), and (b) the clips are the game's
+// SHARED anim-rig clips, retargeted onto this rig (the same buildRetargetContext/retargetClip
+// path every live NPC uses), then baked. `def`: { model, texture, clips: {name: AnimationClip},
+// height?, scale? }. clips insertion order defines the aClip indices (clipIndex maps names).
+export async function loadVillagerVAT(def) {
+  // packed multi-character GLBs (dwarves, war-camp humans) use the keep-filter + explicit atlas
+  // path, exactly like Character.load — so any roster character can be baked from its own fields.
+  let rig;
+  if (def.keep) {
+    rig = await instantiate(def.model, { keep: def.keep, attach: def.attach });
+    if (def.texture) applyAtlas(rig, await loadTexture(def.texture, { flipY: def.texFlipY ?? false }));
+  } else {
+    rig = await instantiate(def.model, { texture: def.texture });
+  }
+  mergeCharacterBody(rig); // multi-part bodies → 1 mesh (no-op when already single; never throws)
+  let skinned = null;
+  let parts = 0;
+  rig.traverse((o) => {
+    if (!o.isSkinnedMesh || !o.visible) return;
+    parts++;
+    if (!skinned || o.geometry.attributes.position.count > skinned.geometry.attributes.position.count) skinned = o;
+  });
+  if (!skinned) throw new Error(`no SkinnedMesh in ${def.model}`);
+  if (parts > 1) console.warn(`[vat] ${def.model.split('/').pop()}: ${parts} skinned parts after merge — baking the largest only`);
+  skinned.normalizeSkinWeights?.();
+  const ctx = def.raw ? null : buildRetargetContext(rig);
+  const baked = [], clipIndex = {};
+  for (const [name, clip] of Object.entries(def.clips)) {
+    if (!clip) continue;
+    clipIndex[name] = baked.length;
+    // raw rigs (PolyPerfect creatures, cathedral court): the clips already target this rig's own
+    // bones — bake directly, no retarget. Clone so the bakeFps tag never leaks onto live clips.
+    const rc = def.raw ? clip.clone() : retargetClip(clip, ctx); // bakeVAT strips .position (in-place)
+    if (name !== 'walk' && name !== 'run') (rc.userData ??= {}).bakeFps = 15; // idles at 15fps — halves rows, imperceptible on sways
+    baked.push(rc);
+  }
+  if (!baked.length) throw new Error(`no clips to bake for ${def.model}`);
+  // key the bake by the RESOLVED model: the twin redirect silently swaps .fbx villagers to
+  // GLB rigs whose vertex ORDER differs — a bin cooked from the FBX rig applied to the GLB
+  // geometry renders a scrambled half-buried character (Nick's floor-flickering villager:
+  // garbled VAT instance when demoted, correct skinned rig when promoted, thrash at the
+  // boundary). Resolved key → the redirected rigs cook fresh bins on first sight.
+  const resolvedModel = await resolveModelUrl(def.model, { texture: def.texture });
+  const vat = await bakeVATCached(`${resolvedModel}|${def.keep ?? ''}`, rig, skinned, baked);
+  vat.playFps = vat.fps * (def.playRate ?? 1);
+  // size/ground in bind space, same rules as species (GLB characters are metres → scale ≈ 1;
+  // def.scale pins it exactly to the live-NPC scale for a seamless promote swap later)
+  skinned.geometry.computeBoundingBox();
+  const box = skinned.geometry.boundingBox;
+  const size = box.getSize(new THREE.Vector3());
+  const scale = def.scale ?? (def.height ?? 1.75) / (size.y || 1);
+  const walkSpeed = clipIndex.walk != null
+    ? (rootMotionSpeed(baked[clipIndex.walk], scale) || footSlideSpeed(vat, clipIndex.walk, scale) || 1.4)
+    : 1.4;
+  const albedo = (Array.isArray(skinned.material) ? skinned.material[0] : skinned.material)?.map ?? null;
+  const geometry = skinned.geometry.clone();
+  const vid = new Float32Array(vat.vCount); for (let i = 0; i < vat.vCount; i++) vid[i] = i;
+  geometry.setAttribute('vertexId', new THREE.BufferAttribute(vid, 1));
+  return { vat, geometry, albedo, layers: 1, scale, clipIndex, walkSpeed, footY: box.min.y * scale, size };
+}

package/src/systems/vatRoster.js

@@ -0,0 +1,149 @@
+// VATRoster: EVERY ambient character (named NPCs, travellers, later knights/goblins/dwarves)
+// renders as a VAT instance while "demoted" — its real skinned rig stays boot-built but hidden,
+// and its Animator never runs. The character PROMOTES to the rig within arm's-reach distance or
+// the moment its AI plays a clip that isn't in the baked ambient set (attacks, hit, death, chat
+// takes, sits) — so combat/dialogue correctness is automatic. Demote reverses when far + ambient.
+// One InstancedMesh per (model|keep|texture) variant for the whole roster: ~150 characters cost
+// ~a dozen draws + zero animator CPU while demoted. Design: VAT_CROWD_PLAN.md (Kiwi port).
+import * as THREE from 'three/webgpu';
+import { vatMaterial, loadVillagerVAT } from './vat.js';
+// the ambient bake set + clip subsetting are GAME data:
+//   setRosterContent({ bakeClips, idleClips, clipSubset })
+let RC = { bakeClips: [], idleClips: [], clipSubset: (c) => c };
+export function setRosterContent(c) { RC = { ...RC, ...c }; }
+
+const _m = new THREE.Matrix4(), _q = new THREE.Quaternion(), _p = new THREE.Vector3(), _s = new THREE.Vector3(), _UP = new THREE.Vector3(0, 1, 0);
+
+export class VATRoster {
+  constructor(game) {
+    this.game = game;
+    this._pending = [];      // [{ proxy, char }] until build()
+    this.variants = new Map(); // key → { mesh, geo, mat, aClip, v, n }
+  }
+
+  // Register a character. Before build(): queued, its variant is baked on the loading screen.
+  // After build() (runtime spawns — warbands, knight patrols, respawns): claims a free slot on
+  // an EXISTING variant immediately; unknown variants return null (the char just stays real —
+  // never bake or create meshes mid-play). opts: { bakeClips, promoteR, demoteR } — enemies use
+  // a wide promote radius so their attached weapons (not in the bake) are never missed up close.
+  register(char, opts = {}) {
+    const at = Array.isArray(char.attach) ? char.attach.join('+') : (char.attach ?? '');
+    const key = `${char.modelUrl}|${char.keep ?? ''}|${at}|${char.textureUrl ?? ''}`;
+    const proxy = { key, slot: -1, variant: null, ready: false, shown: false, promoteR: opts.promoteR ?? 8, demoteR: opts.demoteR ?? 10 };
+    if (this.built) {
+      const variant = this.variants.get(key);
+      if (!variant) {
+        // unknown variant after boot (late populations — hold-dwarves): queue it; the char stays
+        // real (proxy.ready=false) until the owner calls buildLate() once its cohort is loaded.
+        this._pending.push({ proxy, char, bakeClips: opts.bakeClips ?? null, raw: opts.raw ?? false });
+        return proxy;
+      }
+      const slot = variant.free.length ? variant.free.pop() : (variant.used < variant.n ? variant.used++ : -1);
+      if (slot < 0) return null;                    // variant full — char stays real
+      proxy.variant = variant; proxy.slot = slot; proxy.ready = true;
+      return proxy;
+    }
+    this._pending.push({ proxy, char, bakeClips: opts.bakeClips ?? null, raw: opts.raw ?? false });
+    return proxy;
+  }
+
+  // A removed character (enemy death cleanup, despawned patrol member) returns its slot.
+  release(proxy) {
+    if (!proxy?.ready) return;
+    this.hide(proxy);
+    proxy.ready = false;
+    proxy.variant.free.push(proxy.slot);
+  }
+
+  // Bake every registered variant + create its InstancedMesh (capacity = registrations + spare
+  // for same-variant late joiners). Run on the loading screen BEFORE the boot warm render.
+  async build(clips) {
+    if (!this._pending.length) return;
+    const bakeClips = RC.clipSubset(clips, RC.bakeClips);
+    const byKey = new Map();
+    for (const e of this._pending) { let l = byKey.get(e.proxy.key); if (!l) byKey.set(e.proxy.key, (l = [])); l.push(e); }
+    await Promise.all([...byKey.entries()].map(async ([key, entries]) => {
+      const c = entries[0].char;
+      let v = null;
+      try {
+        v = await loadVillagerVAT({ model: c.modelUrl, texture: c.textureUrl, keep: c.keep, attach: c.attach, texFlipY: c.texFlipY, clips: entries[0].bakeClips ?? bakeClips, scale: c.scale, raw: entries[0].raw });
+      } catch (err) { console.warn('[roster] bake failed (chars stay real):', key.split('|')[0].split('/').pop(), err); return; }
+      const n = entries.length + 4;
+      const geo = v.geometry.clone();
+      const aClip = new Float32Array(n);
+      const aClipAttr = new THREE.InstancedBufferAttribute(aClip, 1);
+      aClipAttr.setUsage(THREE.DynamicDrawUsage);
+      geo.setAttribute('aClip', aClipAttr);
+      const aPhase = new Float32Array(n), aTint = new Float32Array(n * 3);
+      for (let i = 0; i < n; i++) { aPhase[i] = Math.random() * 6; aTint[i * 3] = aTint[i * 3 + 1] = aTint[i * 3 + 2] = 1; }
+      geo.setAttribute('aPhase', new THREE.InstancedBufferAttribute(aPhase, 1));
+      geo.setAttribute('aTint', new THREE.InstancedBufferAttribute(aTint, 3));
+      const mat = vatMaterial(v.vat, v.albedo, 1);
+      const mesh = new THREE.InstancedMesh(geo, mat, n); // count stays n; parked slots are scale-0 (draw nothing)
+      // r184 initialises instance matrices to IDENTITY — an unwritten slot would render the rig
+      // at scale 1 at the origin (a 180-unit colossus for cm-baked FBX variants). Park them all.
+      _m.compose(_p.set(0, -900, 0), _q.identity(), _s.set(0, 0, 0));
+      for (let i = 0; i < n; i++) mesh.setMatrixAt(i, _m);
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.frustumCulled = false;
+      mesh.castShadow = false; mesh.receiveShadow = false;
+      mesh.name = `roster:${key.split('|')[0].split('/').pop()}`;
+      mesh.matrixAutoUpdate = false; mesh.updateMatrix();
+      this.game.scene.add(mesh);
+      const variant = { mesh, geo, mat, aClip, v, n, used: 0, free: [] };
+      this.variants.set(key, variant);
+      for (const e of entries) { e.proxy.variant = variant; e.proxy.slot = variant.used++; e.proxy.ready = true; }
+    }));
+    this._pending.length = 0;
+    this.built = true;
+    console.log(`[roster] ${[...this.variants.values()].reduce((a, x) => a + x.used, 0)} characters VAT-backed · ${this.variants.size} variants/draws`);
+  }
+
+  // Is this animator clip renderable as a VAT instance? idles map to a baked idle,
+  // walk/run map directly; anything else forces the real rig (promote).
+  mappable(name) { return !name || name.startsWith('idle') || name === 'walk' || name === 'run' || name === 'sprint'; }
+
+  _clipIndex(v, name) {
+    if (!name) return v.clipIndex.idle ?? 0;
+    if (name === 'walk') return v.clipIndex.walk ?? 0;
+    if (name === 'run' || name === 'sprint') return v.clipIndex.run ?? v.clipIndex.walk ?? 0;
+    if (name.startsWith('idle')) {
+      if (v.clipIndex[name] != null) return v.clipIndex[name];
+      let h = 0; for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0; // unbaked idle → stable stand-in
+      return v.clipIndex[RC.idleClips[h % RC.idleClips.length]] ?? 0;
+    }
+    return v.clipIndex.idle ?? 0;
+  }
+
+  // Demoted character → write its instance (position/heading/clip). Called from Character.update.
+  write(proxy, x, y, z, heading, clipName) {
+    const variant = proxy.variant;
+    _q.setFromAxisAngle(_UP, heading);
+    const sc = variant.v.scale;
+    variant.mesh.setMatrixAt(proxy.slot, _m.compose(_p.set(x, y - variant.v.footY, z), _q, _s.set(sc, sc, sc)));
+    variant.mesh.instanceMatrix.needsUpdate = true;
+    const ci = this._clipIndex(variant.v, clipName);
+    if (variant.aClip[proxy.slot] !== ci) { variant.aClip[proxy.slot] = ci; variant.geo.getAttribute('aClip').needsUpdate = true; }
+    proxy.shown = true;
+  }
+
+  // Promoted (or dead) → park the instance (scale-0 draws nothing; the rig takes over).
+  hide(proxy) {
+    if (!proxy.shown) return;
+    proxy.shown = false;
+    const variant = proxy.variant;
+    variant.mesh.setMatrixAt(proxy.slot, _m.compose(_p.set(0, -900, 0), _q.identity(), _s.set(0, 0, 0)));
+    variant.mesh.instanceMatrix.needsUpdate = true;
+  }
+
+  // Build variants queued AFTER boot (late populations). New meshes/pipelines are created
+  // mid-play, so call this while a background loading window is already open (the dwarves
+  // load inside phase-2's shadow) — never on a travel frame.
+  async buildLate(clips) {
+    if (!this._pending.length) return;
+    this.built = false;            // reuse build()'s queue path
+    await this.build(clips);
+  }
+
+  update(dt) { for (const variant of this.variants.values()) variant.mat.userData.uTime.value += dt; }
+}

package/src/world/flora.js

@@ -68,8 +68,14 @@ export function clumpField(x, z, salt = TREE_SALT) {
   return w;
 }
 
-/** analytic moisture 0..1 — desert-low: faint drift, a lusher corridor along the creek */
-export function moistureAt(x, z) {
+// moisture/forest fields are GAME data — register per game: setFloraFields({ moistureAt, forestness }).
+// Defaults: the desert-low moisture model below, and no forest.
+export function setFloraFields({ moistureAt: m = null, forestness: f = null } = {}) {
+  if (m) moistureAt = m;
+  if (f) forestness = f;
+}
+/** analytic moisture 0..1 — desert-low default: faint drift, a lusher corridor along the creek */
+export let moistureAt = function moistureAtDefault(x, z) {
   let m = 0.12 + TERRAIN.fbm(x + 191, z - 87, 3, 2, 0.5, 0.012) * 0.1;
   const ri = TERRAIN.riverInfo(x, z);
   if (ri.dist < ri.w + 30) m += 0.35 * (1 - Math.max(0, ri.dist - ri.w) / 30);
@@ -79,9 +85,9 @@ export function moistureAt(x, z) {
   }
   m -= Math.max(0, (TERRAIN.heightAt(x, z) - 12) * 0.012);
   return Math.min(1, Math.max(0, m));
-}
+};
 
-/** no forest on the desert plain — always 0 (signature kept for the field consumers) */
-export function forestness(x, z) {
+/** default: no forest (a game registers its own via setFloraFields) */
+export let forestness = function forestnessDefault(x, z) {
   return 0;
-}
+};

package/src/world/sky.js

@@ -42,7 +42,8 @@ function blendPhase(hour, a, b, out, t) {
 }
 
 export class Sky {
-  constructor(scene) {
+  constructor(scene, { hemiGround = 0xc9b18a, ambientLift = 1.5 } = {}) {
+    this._hemiGround = hemiGround; this._ambientLift = ambientLift;
     this.scene = scene;
     this.hour = 10;             // start mid-morning
     this.speed = 24 / 900;      // game-hours per real second (15-minute full day)
@@ -105,7 +106,7 @@ export class Sky {
     this.sun.shadow.bias = -0.0004;
     scene.add(this.sun, this.sun.target);
 
-    this.hemi = new THREE.HemisphereLight(0xbdd3e8, 0xc9b18a, 0.85); // ground bounce = desert sand, not Albion grass
+    this.hemi = new THREE.HemisphereLight(0xbdd3e8, this._hemiGround, 0.85); // ground bounce (game option: desert sand / Albion grass)
     scene.add(this.hemi);
 
     // sun/moon discs — the sun gets a warm gold core (0xfff4cc read as pure white through the
@@ -333,7 +334,7 @@ export class Sky {
     this.sun.color.copy(NIGHT.sun).lerp(p.sun, dayness);   // EASE the key-light colour across the horizon crossing — the old hard `dayness>0.5` switch snapped the ground colour in one frame at ~sunset (Nick: "at 9:15 the ground colour changed in a blink")
     this.sun.intensity = lerp(NIGHT.sunI, p.sunI, dayness);
 
-    this.hemi.intensity = p.ambI * 1.5; // desert lift: dark western wood crushed to black at Albion ambient levels
+    this.hemi.intensity = p.ambI * this._ambientLift; // ambient lift (game option: desert wood needs 1.5; Albion sits at 1)
     this.hemi.color.copy(p.sky).lerp(WHITE, 0.4);
 
     const discR = this.skyR * 0.94;   // inside the dome AND the far plane (LOW clips past 200m)

package/src/world/weather.js

@@ -17,12 +17,12 @@ const BOX = 28;            // disk radius around the player (m)
 const TOP = 18, BOT = 5;   // column extent above / below the player (drops pass through eye level)
 const SPAN = TOP + BOT;
 const FALL = 30;           // rain fall speed (m/s); snow is ~7× slower
-const SNOWLINE = 500;      // terrain height (m) where precipitation turns to snow — above every mesa: it never snows on Dustwater
 const STORM_GREY = new THREE.Color(0x4a4f57);
 
 export class Weather {
-  constructor(scene, { shelterObjects = null, indoorAt = null } = {}) {
+  constructor(scene, { shelterObjects = null, indoorAt = null, snowline = 500 } = {}) {
     this._shelterObjects = shelterObjects; this._indoorAt = indoorAt;
+    this._snowline = snowline;   // terrain height (m) where precipitation turns to snow
     this.scene = scene;
     this.intensity = 0;          // 0 clear … 1 storm (smoothed)
     this.target = 0;
@@ -230,7 +230,7 @@ export class Weather {
     this.exposure += (this._expTarget - this.exposure) * Math.min(1, dt * 2.5);
 
     const cold = this._snowForce != null ? this._snowForce
-      : world?.groundAt ? THREE.MathUtils.smoothstep(world.groundAt(playerPos.x, playerPos.z), SNOWLINE - 8, SNOWLINE + 8) : 0;
+      : world?.groundAt ? THREE.MathUtils.smoothstep(world.groundAt(playerPos.x, playerPos.z), this._snowline - 8, this._snowline + 8) : 0;
     this._snow += (cold - this._snow) * Math.min(1, dt * 0.5);
     this.uSnow.value = this._snow;
     // cloud deck LEADS precipitation: full-heavy while rain is still building (x1.75), lingers