sindicate 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
   "type": "module",
   "main": "src/index.js",
@@ -22,7 +22,8 @@
   ],
   "exports": {
     ".": "./src/index.js",
-    "./*": "./src/*"
+    "./*": "./src/*",
+    "./tools/*": "./tools/*"
   },
   "files": [
     "src",

package/src/audio/music.js

@@ -111,7 +111,7 @@ export class Music {
   _onEnded(t) {
     if (this._cur !== t) return;
     if (t === this.restSleep) return;             // asleep under the black; the wake cut takes over
-    if (t === this.restWake) { this._state = 'area'; this._playArea(this._area || 'desert'); return; }
+    if (t === this.restWake) { this._state = 'area'; this._playArea(this._area || Object.keys(this.areas)[0]); return; }
     if (this._state === 'sting') {
       const fb = this._stingFallback; this._stingFallback = null;
       this._state = 'area'; this._playArea(fb || this._area || this._half);
@@ -126,6 +126,16 @@ export class Music {
     if (this._unlocked) return;
     this._unlocked = true;
     this._ensureCtx();
+    // Pre-decode the catalogue's `resident` list (file names) so combat stings and
+    // exploration cuts start INSTANTLY — everything else decodes on first crossfade.
+    if (this._cat.resident?.length) {
+      const defs = [this.menu, ...this.attack, ...this.venue,
+        ...Object.values(this.areas).flat(), this.restSleep, this.restWake].filter(Boolean);
+      for (const name of this._cat.resident) {
+        const t = defs.find((d) => d.url.endsWith(`/${name}`));
+        if (t) this._decode(t).catch(() => { /* pre-decode is best-effort */ });
+      }
+    }
     if (this.ctx.state === 'suspended') this.ctx.resume().catch(() => {});
   }
 

package/src/core/assets.js

@@ -8,6 +8,11 @@ import { texture, uv } from 'three/tsl';
 // Register BEFORE the first applyAtlas/instantiate call (materials are cached).
 let atlasEmissiveHook = null;
 export function setAtlasEmissiveHook(fn) { atlasEmissiveHook = fn; }
+
+// The cooked-clip cache version tracks each GAME's animation sources (a rebake bumps
+// it), not the engine — register per game: setClipCacheVersion(2). Defaults to 2
+// (western's current rebake generation).
+export function setClipCacheVersion(v) { CLIP_JSON_VER = v; }
 // Patched loader from vendor/ — merges ALL FBX animation layers per stack. The
 // engine does NOT depend on a node_modules postinstall patch.
 import { FBXLoader } from '../vendor/FBXLoader.js';
@@ -532,7 +537,7 @@ export function applyAtlas(root, tex, { emissive = null } = {}) {
 // public/assets/clips/<name>.json on first parse (self-written via /__save-clipjson)
 // and read the JSON on every later boot. Bump CLIP_JSON_VER after changing any source
 // animation (the name alone can't see content changes), or delete the folder.
-const CLIP_JSON_VER = 2; // v2: full-pack gsbake rebake (97 clips, 2026-07-12)
+let CLIP_JSON_VER = 2; // v2: full-pack gsbake rebake (97 clips, 2026-07-12)
 function clipJsonName(url) {
   let h = 5381;
   for (let i = 0; i < url.length; i++) h = ((h << 5) + h + url.charCodeAt(i)) >>> 0;

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

package/tools/devPlugin.js

@@ -0,0 +1,232 @@
+// sindicateDevTools(config) — the engine's dev-server tooling suite, extracted from the
+// western game's vite config. Returns an array of vite plugins (all `apply: 'serve'` —
+// none of this exists in a production build):
+//
+//   • guarded SOURCE-WRITE endpoints — bench pages persist tuned data straight into the
+//     game's data files (grip/rig/map/LOD... whatever the game declares)
+//   • COOK-TO-FILE stores — the game bakes its own caches (VAT bins, nav grids, parsed
+//     animation clips, world cook bins, map PNGs) and every later boot is a file read.
+//     Each store serves its directory itself: the dirs are excluded from vite's watcher
+//     (writes must not full-reload the page), and vite 8's watcher-fed public registry
+//     404s files created after startup — so we bypass it.
+//   • PERF SINK — [PERF]/FREEZE samples append to a JSONL on disk, readable without the
+//     console (a backgrounded tab pauses rAF and CDP is flaky; disk is neither)
+//   • EDITOR + GAME COMMAND BUSES — queue {js|op} snippets over HTTP; the live page polls,
+//     executes, posts results back. Scripted playtests and editor drives with curl.
+//
+// Usage (a game's vite.config.js):
+//   import { sindicateDevTools } from 'sindicate/tools/devPlugin.js';
+//   plugins: [...sindicateDevTools({
+//     sourceWrites: [{ route: '/__save-grip', file: 'src/game/data/gripTuning.json',
+//                      json: true, mustInclude: 'revolver' }],
+//     assetLists:   [{ route: '/__list-assets', dir: 'public/assets/world', ext: 'fbx' }],
+//     perfSink: process.env.MY_PERF_SINK || '/tmp/mygame-perf.jsonl',
+//   })]
+import fs from 'node:fs';
+
+// Guard for the source-writing endpoints: only same-machine pages may write, and the
+// payload must look like the file it claims to be — an empty/garbage body used to be
+// written verbatim (truncating a committed src file to 0 bytes and breaking the boot via
+// HMR), and cross-origin simple POSTs from any open webpage could reach these routes.
+function guardOk(req, res, body, checks) {
+  const origin = req.headers.origin;
+  if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) {
+    res.statusCode = 403; res.end('cross-origin write refused'); return false;
+  }
+  if (!body || body.length < 20) { res.statusCode = 400; res.end('empty body refused'); return false; }
+  for (const [label, ok] of checks) {
+    if (!ok) { res.statusCode = 400; res.end(`payload failed check: ${label}`); return false; }
+  }
+  return true;
+}
+
+const readBody = (req) => new Promise((resolve) => {
+  const c = []; req.on('data', (d) => c.push(d)); req.on('end', () => resolve(Buffer.concat(c)));
+});
+const sendJson = (res, code, obj) => {
+  res.statusCode = code; res.setHeader('content-type', 'application/json'); res.end(JSON.stringify(obj));
+};
+
+// One guarded write-through-to-a-source-file endpoint (grip/rig/map/LOD tuners).
+function sourceWritePlugin({ route, file, json = false, mustInclude = null }) {
+  return {
+    name: `sindicate-write:${route}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(route, (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        let body = '';
+        req.on('data', (c) => { body += c; });
+        req.on('end', () => {
+          try {
+            const checks = mustInclude ? [[`payload mentions '${mustInclude}'`, body.includes(mustInclude)]] : [];
+            if (!guardOk(req, res, body, checks)) return;
+            if (json) JSON.parse(body);           // never write a malformed file
+            fs.writeFileSync(file, body);
+            res.statusCode = 200; res.end('ok');
+          } catch (e) { res.statusCode = 500; res.end(String(e)); }
+        });
+      });
+    },
+  };
+}
+
+// Directory listing for editor asset palettes.
+function assetListPlugin({ route, dir, ext }) {
+  const re = new RegExp(`\\.${ext}$`, 'i');
+  return {
+    name: `sindicate-list:${route}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(route, (req, res) => {
+        try {
+          const files = fs.readdirSync(dir).filter((f) => re.test(f)).map((f) => f.replace(re, '')).sort();
+          sendJson(res, 200, files);
+        } catch (e) { res.statusCode = 500; res.end('[]'); }
+      });
+    },
+  };
+}
+
+// Serve + accept a cook-to-file store (bins/JSON/PNG the game bakes for itself).
+function binStorePlugin({ name, serveRoute, saveRoute, dir, nameRe, contentType }) {
+  return {
+    name: `sindicate-store:${name}`,
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use(serveRoute, (req, res, next) => {
+        const file = (req.url || '').split('?')[0].replace(/^\//, '');
+        if (!nameRe.test(file)) return next();
+        try {
+          const buf = fs.readFileSync(`${dir}/${file}`);
+          res.setHeader('content-type', typeof contentType === 'function' ? contentType(file) : contentType);
+          res.end(buf);
+        } catch (e) { res.statusCode = 404; res.end('not cooked'); }
+      });
+      server.middlewares.use(saveRoute, async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        const file = new URL(req.url, 'http://x').searchParams.get('name') || '';
+        if (!nameRe.test(file)) { res.statusCode = 400; return res.end('bad name'); }
+        try {
+          fs.mkdirSync(dir, { recursive: true });
+          fs.writeFileSync(`${dir}/${file}`, await readBody(req));
+          res.statusCode = 200; res.end('ok');
+        } catch (e) { res.statusCode = 500; res.end(String(e)); }
+      });
+    },
+  };
+}
+
+// JSONL telemetry sink with size rotation.
+function perfSinkPlugin(sinkPath) {
+  return {
+    name: 'sindicate-perf-sink',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use('/__perf', (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        let body = '';
+        req.on('data', (c) => { body += c; });
+        req.on('end', () => {
+          try {
+            try { if (fs.statSync(sinkPath).size > 8_000_000) fs.renameSync(sinkPath, sinkPath + '.1'); } catch { /* no sink yet */ }
+            fs.appendFileSync(sinkPath, body.trim() + '\n'); res.statusCode = 200; res.end('ok');
+          } catch (e) { res.statusCode = 500; res.end(String(e)); }
+        });
+      });
+    },
+  };
+}
+
+// A poll/take command bus: POST {…} to /cmd → the page polls /poll → posts /result →
+// collect via /take?id=N. `originGuard` restricts /cmd to same-machine pages.
+function busPlugin({ name, prefix, originGuard = false }) {
+  return {
+    name: `sindicate-bus:${name}`,
+    apply: 'serve',
+    configureServer(server) {
+      const queue = [];
+      const results = new Map();
+      let nextId = 1;
+      server.middlewares.use(`${prefix}/cmd`, async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { err: 'POST only' });
+        if (originGuard) {
+          const origin = req.headers.origin;
+          if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(origin)) return sendJson(res, 403, { err: 'cross-origin refused' });
+        }
+        try {
+          const cmd = JSON.parse((await readBody(req)).toString());
+          cmd.id = nextId++; queue.push(cmd);
+          if (queue.length > 40) queue.splice(0, queue.length - 40);
+          sendJson(res, 200, { id: cmd.id });
+        } catch (e) { sendJson(res, 400, { err: String(e) }); }
+      });
+      server.middlewares.use(`${prefix}/poll`, (req, res) => sendJson(res, 200, { cmds: queue.splice(0) }));
+      server.middlewares.use(`${prefix}/result`, async (req, res) => {
+        if (req.method !== 'POST') return sendJson(res, 405, { err: 'POST only' });
+        try {
+          const r = JSON.parse((await readBody(req)).toString());
+          results.set(r.id, r);
+          if (results.size > 100) results.delete(results.keys().next().value);
+          sendJson(res, 200, { ok: 1 });
+        } catch (e) { sendJson(res, 400, { err: String(e) }); }
+      });
+      server.middlewares.use(`${prefix}/take`, (req, res) => {
+        const id = Number(new URL(req.url, 'http://x').searchParams.get('id') || 0);
+        if (!results.has(id)) return sendJson(res, 404, { pending: true });
+        const r = results.get(id); results.delete(id); sendJson(res, 200, r);
+      });
+    },
+  };
+}
+
+// Editor screenshot drop (ring-limited) + baked-map store.
+function editorShotsPlugin({ shotsDir, mapsDir }) {
+  return {
+    name: 'sindicate-editor-shots',
+    apply: 'serve',
+    configureServer(server) {
+      server.middlewares.use('/__save-editorshot', async (req, res) => {
+        if (req.method !== 'POST') { res.statusCode = 405; return res.end('POST only'); }
+        const name = new URL(req.url, 'http://x').searchParams.get('name') || '';
+        if (!/^[\w.-]+\.png$/.test(name)) { res.statusCode = 400; return res.end('bad name'); }
+        try {
+          fs.mkdirSync(shotsDir, { recursive: true });
+          fs.writeFileSync(`${shotsDir}/${name}`, await readBody(req));
+          const shots = fs.readdirSync(shotsDir).filter((f) => f.endsWith('.png'));
+          if (shots.length > 150) {
+            shots.map((f) => [f, fs.statSync(`${shotsDir}/${f}`).mtimeMs]).sort((a, b) => a[1] - b[1])
+              .slice(0, shots.length - 150).forEach(([f]) => { try { fs.unlinkSync(`${shotsDir}/${f}`); } catch { /* raced */ } });
+          }
+          res.end('ok');
+        } catch (e) { res.statusCode = 500; res.end(String(e)); }
+      });
+    },
+  };
+}
+
+export function sindicateDevTools({
+  sourceWrites = [],
+  assetLists = [],
+  perfSink = process.env.SINDICATE_PERF_SINK || '/tmp/sindicate-perf.jsonl',
+  cookStores = null,        // override to add/remove stores; null = the standard set below
+  editorShotsDir = 'public/editor-shots',
+  mapsDir = 'public/assets/maps',
+} = {}) {
+  const stores = cookStores ?? [
+    { name: 'vat', serveRoute: '/assets/vat', saveRoute: '/__save-vatbin', dir: 'public/assets/vat', nameRe: /^[\w-]+\.bin$/, contentType: 'application/octet-stream' },
+    { name: 'nav', serveRoute: '/assets/nav', saveRoute: '/__save-navbin', dir: 'public/assets/nav', nameRe: /^[\w.-]+\.bin$/, contentType: 'application/octet-stream' },
+    { name: 'clips', serveRoute: '/assets/clips', saveRoute: '/__save-clipjson', dir: 'public/assets/clips', nameRe: /^[\w.-]+\.json$/, contentType: 'application/json' },
+    { name: 'cook', serveRoute: '/assets/cook', saveRoute: '/__save-cookbin', dir: 'public/assets/cook', nameRe: /^[\w.-]+\.(bin|json)$/, contentType: 'application/octet-stream' },
+    { name: 'maps', serveRoute: '/assets/maps', saveRoute: '/__save-mappng', dir: mapsDir, nameRe: /^[\w.-]+\.(png|json)$/, contentType: (f) => (f.endsWith('.json') ? 'application/json' : 'image/png') },
+  ];
+  return [
+    ...sourceWrites.map(sourceWritePlugin),
+    ...assetLists.map(assetListPlugin),
+    ...stores.map(binStorePlugin),
+    perfSinkPlugin(perfSink),
+    busPlugin({ name: 'game', prefix: '/__game', originGuard: true }),
+    busPlugin({ name: 'editor', prefix: '/__editor' }),
+    editorShotsPlugin({ shotsDir: editorShotsDir, mapsDir }),
+  ];
+}