sindicate 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.5.0",
+  "version": "0.7.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/ambience.js

@@ -0,0 +1,65 @@
+// Layered ambient beds — looping environment loops streamed as HTMLAudio, each with a
+// target volume set by context (time of day). Volumes ramp toward their targets every
+// frame so beds fade in/out naturally. Desert v1: a constant wind bed (stronger at night)
+// plus dawn birdsong. Kept separate from the SFX synth (one-shots) and the streamed music.
+
+
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+export function smoothstep(edge0, edge1, x) {
+  const t = clamp01((x - edge0) / (edge1 - edge0));
+  return t * t * (3 - 2 * t);
+}
+
+export class Ambience {
+  // beds/paths/targets are GAME data:
+  //   new Ambience(game, { beds: ['wind'], base, computeTargets: (game, beds) => {...}, storageKey })
+  constructor(game, { beds = [], base = '/assets/audio/ambience', computeTargets = null, storageKey = 'av_volAmb' } = {}) {
+    this._bedIds = beds;
+    this._base = base;
+    this._computeFn = computeTargets;
+    this._storageKey = storageKey;
+    this.game = game;
+    this.enabled = true;
+    this.master = +(localStorage.getItem(this._storageKey) ?? 0.6);   // Ambience slider (0..1); persists
+    this.beds = {};        // id -> { el, vol, target }
+    this._built = false;
+    this._t = 999;         // force an immediate target compute on first update
+  }
+
+  _build() {
+    this._built = true;
+    const A = this._base;
+    for (const id of this._bedIds) {
+      const el = new Audio(`${A}/${id}.wav`);
+      el.loop = true; el.preload = 'none'; el.volume = 0;
+      this.beds[id] = { el, vol: 0, target: 0 };
+    }
+  }
+
+  setEnabled(on) {
+    this.enabled = on;
+    if (!on) for (const b of Object.values(this.beds)) { b.el.pause(); b.vol = 0; b.el.volume = 0; }
+  }
+  setMuted(on) { for (const b of Object.values(this.beds)) b.el.muted = on; }
+  setVolume(v) { this.master = clamp01(v); }
+
+  update(dt) {
+    if (!this.game.audio?.ctx || !this.enabled) return;   // wait for the unlock gesture
+    if (!this._built) this._build();
+    this._t += dt;
+    if (this._t >= 0.5) { this._computeTargets(); this._t = 0; }
+    for (const b of Object.values(this.beds)) {
+      const step = dt * 0.5;                                // ~2s fade in/out
+      b.vol += Math.sign(b.target - b.vol) * Math.min(Math.abs(b.target - b.vol), step);
+      if (b.target > 0 && b.el.paused) { try { b.el.currentTime = 0; } catch { /* not seekable yet */ } b.el.play().catch(() => {}); }
+      b.el.volume = clamp01(b.vol * this.master);
+      if (b.vol < 0.004 && b.target === 0 && !b.el.paused) b.el.pause();   // free the stream once silent
+    }
+  }
+
+  _computeTargets() {
+    for (const id of this._bedIds) this.beds[id].target = 0;
+    this._computeFn?.(this.game, this.beds);
+  }
+
+}

package/src/audio/music.js

@@ -0,0 +1,244 @@
+// Music — WEB AUDIO, decode-ahead. Every track's mp3 is FULLY decoded to a PCM AudioBuffer BEFORE it
+// plays (ctx.decodeAudioData), so nothing decodes during playback and no track garbles its opening.
+// (The old HTML-<audio> path decoded WHILE streaming → a stuttered/garbled first ~half-second on the
+// initial play of every cut — Nick: "decode before playing not while playing".)
+//
+// A shared master GainNode carries the music volume + mute. Each playing track gets its own GainNode
+// for crossfades and the saloon's distance mix. Buffers are decoded on demand and freed when a track
+// stops, so memory stays bounded — the mp3s live in the browser's HTTP cache, so a re-decode is cheap.
+//
+// Catalogue: a title cut (menu), a wander pool under the open world (areas.desert), the saloon's own
+// band (venue, mixed by distance via setVenue), and the campfire rest cuts. Every path no-ops on an
+// empty pool, and the whole thing stays silent until unlock() resumes the context on a user gesture.
+
+export class Music {
+  constructor({ base = '/assets/audio/music', catalogue = {}, storageKey = 'av_volMusic' } = {}) {
+    this._base = base;
+    this._cat = catalogue;
+    this._storageKey = storageKey;
+    this.enabled = true;
+    this.volume = +(localStorage.getItem(this._storageKey) ?? 0.55);
+    this.fadeMs = 1600;
+    this._muted = false;
+    this._state = 'idle';       // idle | menu | explore | area | sting | combat
+    this._cur = null;           // foreground track def
+    this._venueTrack = null;    // the saloon track currently carrying the bar
+    this._venueGain = 0;
+    this._duck = 1;             // 1 - venueGain (how loud the world music is UNDER the bar)
+    this._half = 'south';
+    this._area = null;
+    this._stingFallback = null;
+    this._unlocked = false;
+    this.ctx = null; this.master = null;
+
+    // the catalogue is GAME data: { menu, attack: [], venue: [], areas: {id: []}, restSleep, restWake } (file names)
+    const cat = this._cat;
+    this.menu = cat.menu ? this._def(cat.menu) : null;
+    this.attack = (cat.attack ?? []).map((n) => this._def(n));
+    this.venue = (cat.venue ?? []).map((n) => this._def(n));
+    this.areas = Object.fromEntries(Object.entries(cat.areas ?? {}).map(([k, v]) => [k, v.map((n) => this._def(n))]));
+    this.restSleep = cat.restSleep ? this._def(cat.restSleep) : null;
+    this.restWake = cat.restWake ? this._def(cat.restWake) : null;
+  }
+
+  _def(file) { return { url: `${this._base}/${file}`, buffer: null, _decoding: null, node: null, gain: null }; }
+
+  _ensureCtx() {
+    if (this.ctx) return;
+    const Ctx = window.AudioContext || window.webkitAudioContext;
+    this.ctx = new Ctx();
+    this.master = this.ctx.createGain();
+    this.master.gain.value = (this.enabled && !this._muted) ? this.volume : 0;
+    this.master.connect(this.ctx.destination);
+  }
+
+  // fetch + FULLY decode to PCM before it can be played. cached on the track; re-fetch hits HTTP cache.
+  async _decode(t) {
+    if (t.buffer) return t.buffer;
+    if (!t._decoding) {
+      t._decoding = fetch(t.url)
+        .then((r) => r.arrayBuffer())
+        .then((ab) => this.ctx.decodeAudioData(ab))
+        .then((buf) => { t.buffer = buf; t._decoding = null; return buf; })
+        .catch((e) => { t._decoding = null; throw e; });
+    }
+    return t._decoding;
+  }
+
+  _play(t, loop, target, buffer) {
+    const src = this.ctx.createBufferSource();
+    src.buffer = buffer; src.loop = loop;
+    const g = this.ctx.createGain(); g.gain.value = 0;
+    src.connect(g).connect(this.master);
+    const now = this.ctx.currentTime;
+    g.gain.setValueAtTime(0, now);
+    g.gain.linearRampToValueAtTime(target, now + this.fadeMs / 1000);
+    src.onended = () => { if (!src._manual) this._onEnded(t); this._free(t); };
+    src.start();
+    t.node = src; t.gain = g;
+  }
+
+  _stop(t, fade = this.fadeMs) {
+    if (!t || !t.node) return;
+    const src = t.node, g = t.gain;
+    src._manual = true;
+    const now = this.ctx.currentTime;
+    try { g.gain.cancelScheduledValues(now); g.gain.setValueAtTime(g.gain.value, now); g.gain.linearRampToValueAtTime(0, now + fade / 1000); } catch { /* */ }
+    try { src.stop(now + fade / 1000 + 0.05); } catch { /* */ }
+    t.node = null; t.gain = null;
+  }
+
+  // release a track's decoded PCM once nothing is using it (keeps memory bounded)
+  _free(t) {
+    if (t.node || t === this._cur || t === this._venueTrack) return;
+    t.buffer = null;
+  }
+
+  async _crossfade(t, loop) {
+    if (!t) return;
+    if (t === this._cur) { if (t.node) t.node.loop = loop; return; }
+    const prev = this._cur;
+    this._cur = t;
+    this._ensureCtx();
+    let buffer;
+    try { buffer = await this._decode(t); } catch { if (this._cur === t) this._cur = prev; return; }
+    if (this._cur !== t) return;                 // superseded by a newer crossfade during the decode
+    if (prev && prev !== t) this._stop(prev, this.fadeMs);
+    this._play(t, loop, this._duck, buffer);
+  }
+
+  // natural end of a non-loop foreground track → carry on with the state's next cut
+  _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 || 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);
+    } else if (this._state === 'area' || this._state === 'explore') {
+      this._playArea(this._area || this._half);
+    } else if (this._state === 'combat') {
+      this.enterCombat();
+    }
+  }
+
+  unlock() {
+    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(() => {});
+  }
+
+  playMenu() { this._state = 'menu'; this._crossfade(this.menu, true); }
+  startExploration() { this._state = 'explore'; this._area = this._half; this._playArea(this._half); }
+
+  playSting(poolName, fallback) {
+    const pool = this.areas[poolName]; if (!pool || !pool.length) return;
+    this._state = 'sting'; this._stingFallback = fallback;
+    this._crossfade(pool[Math.floor(Math.random() * pool.length)], false);
+  }
+  stingActive() { return this._state === 'sting'; }
+
+  _playArea(name) {
+    const pool = this.areas[name]; if (!pool || !pool.length) return;
+    const loop = pool.length === 1;
+    let i = Math.floor(Math.random() * pool.length);
+    if (pool[i] === this._cur) i = (i + 1) % pool.length;   // don't repeat the same track back-to-back
+    this._crossfade(pool[i], loop);
+  }
+
+  setArea(name) {
+    name = name || null;
+    if (name === this._area) return;
+    this._area = name;
+    if (this._state === 'combat') return;
+    if (name) { this._state = 'area'; this._playArea(name); }
+    else { this.startExploration(); }
+  }
+  setNearbyAreas() { /* Web Audio decodes on demand + frees on stop — no manual streaming to manage */ }
+
+  // THE BAR, mixed by distance. gain 0..1 = how loud the saloon is from where the player stands.
+  // The band plays on its own source under the world music, which we duck by the same amount.
+  async setVenue(gain) {
+    gain = Math.max(0, Math.min(1, gain || 0));
+    this._venueGain = gain;
+    this._duck = 1 - gain;
+    this._ensureCtx();
+    if (gain > 0.01) {
+      if (!this._venueTrack) await this._nextVenue();
+      else this._rampGain(this._venueTrack, gain, 180);
+    } else if (this._venueTrack) {
+      this._stop(this._venueTrack, 400); this._venueTrack = null;
+    }
+    if (this._cur) this._rampGain(this._cur, this._duck, 180);
+  }
+
+  async _nextVenue() {
+    const pool = this.venue.filter((a) => a !== this._venueTrack);
+    const t = pool[Math.floor(Math.random() * pool.length)] ?? this.venue[0];
+    if (!t) return;
+    if (this._venueTrack && this._venueTrack !== t) this._stop(this._venueTrack, 300);
+    this._venueTrack = t;
+    let buffer;
+    try { buffer = await this._decode(t); } catch { if (this._venueTrack === t) this._venueTrack = null; return; }
+    if (this._venueTrack !== t) return;
+    const src = this.ctx.createBufferSource(); src.buffer = buffer; src.loop = false;
+    const g = this.ctx.createGain(); g.gain.value = 0;
+    src.connect(g).connect(this.master);
+    const now = this.ctx.currentTime;
+    g.gain.setValueAtTime(0, now); g.gain.linearRampToValueAtTime(this._venueGain, now + 0.3);
+    src.onended = () => { const wasBar = this._venueTrack === t; t.node = null; t.gain = null; this._free(t); if (!src._manual && wasBar && this._venueGain > 0.01) this._nextVenue(); };
+    src.start();
+    t.node = src; t.gain = g;
+  }
+
+  _rampGain(t, target, ms) {
+    if (!t || !t.gain) return;
+    const now = this.ctx.currentTime;
+    try { t.gain.gain.cancelScheduledValues(now); t.gain.gain.setValueAtTime(t.gain.gain.value, now); t.gain.gain.linearRampToValueAtTime(target, now + ms / 1000); } catch { /* */ }
+  }
+
+  enterCombat() {
+    if (!this.attack.length) return;
+    this._state = 'combat';
+    this._crossfade(this.attack[Math.floor(Math.random() * this.attack.length)], true);
+  }
+  exitCombat() {
+    if (this._state !== 'combat') return;
+    if (this._area) { this._state = 'area'; this._playArea(this._area); }
+    else this.startExploration();
+  }
+
+  // campfire rest: fall-asleep cut on E, wake cut on waking — both fully decoded, so no garbled start.
+  // The wake cut is decoded now (at E) so it's ready by the time we wake ~15s later.
+  playRestSleep() { this._state = 'sting'; this._ensureCtx(); this._decode(this.restWake).catch(() => {}); this._crossfade(this.restSleep, false); }
+  playRestWake() { this._state = 'sting'; this._crossfade(this.restWake, false); }
+
+  setMuted(on) { this._muted = on; this._applyMaster(); }
+  setEnabled(on) { this.enabled = on; if (this.ctx && on) this.ctx.resume?.().catch(() => {}); this._applyMaster(); }
+  setMusicVolume(v) {
+    this.volume = Math.max(0, Math.min(1, +v || 0));
+    try { localStorage.setItem(this._storageKey, this.volume); } catch { /* private mode */ }
+    this._applyMaster();
+  }
+  setVolume(v) { this.setMusicVolume(v); }
+
+  _applyMaster() {
+    if (!this.master) return;
+    const target = (this.enabled && !this._muted) ? this.volume : 0;
+    const now = this.ctx.currentTime;
+    try { this.master.gain.cancelScheduledValues(now); this.master.gain.setValueAtTime(this.master.gain.value, now); this.master.gain.linearRampToValueAtTime(target, now + 0.08); } catch { this.master.gain.value = target; }
+  }
+
+  unloadMenu() { /* buffers free themselves on stop */ }
+}

package/src/audio/synth.js

@@ -0,0 +1,228 @@
+// SFX engine: real recordings where we have them, WebAudio synthesis where we don't.
+// Gun sounds are synthesized (no recordings in the packs) — they live in the play()
+// switch so a future recorded swap is a this._sfx data entry, zero call-site churn.
+
+// SFX that have REAL recorded variants (loaded by loadSfx). play() prefers these over the synth.
+// { b: base sample name, n: variant count, g: gain, j: pitch-jitter (0 keeps musical clips in tune) }.
+// Sources: Fighting Sounds (swing/hit), Deadly Kombat (block), Explosion pack (spell booms),
+// Casual Game SFX (ui/coin/orb/heal/quest/level-up) — all real recordings, no synth beeps.
+// The recorded-SFX table and sample dirs are GAME data — pass at construction:
+//   new AudioSystem({ sfx, muted, sfxDirs, storageKey })
+
+
+export class AudioSystem {
+  constructor({ sfx = {}, muted = [], sfxDirs = { combat: '/assets/audio/combat', ui: '/assets/audio/ui' }, storageKey = 'av_volSfx' } = {}) {
+    this._sfx = sfx;
+    this._muted = new Set(muted);
+    this._sfxDirs = sfxDirs;
+    this._storageKey = storageKey;
+    this.ctx = null;
+    this.master = null;
+    this.musicGain = null;
+    this.sfxGain = null;
+    this.enabled = true;
+    this.mode = 'day'; // day | night | danger | dungeon
+    this.muted = false;
+    this.samples = {};   // decoded AudioBuffers for the few real recorded SFX (horse etc.)
+    this.deadEyeLP = null;     // master lowpass — Dead Eye ducks the world underwater (phase 2)
+    this.sampleRateScale = 1;  // global sample pitch scale — Dead Eye slow-mo hook; 1 = neutral
+    this.sfxVolume = +(localStorage.getItem(this._storageKey) ?? 0.85);  // Sound FX slider (0..1) → sfxGain
+  }
+
+  // Sound-FX volume (System-menu slider). Applied to sfxGain; persists.
+  setSfxVolume(v) {
+    this.sfxVolume = Math.max(0, Math.min(1, v));
+    if (this.sfxGain) this.sfxGain.gain.value = this.sfxVolume;
+    localStorage.setItem(this._storageKey, this.sfxVolume);
+  }
+
+  // Load & cache a set of {name: url} audio files as AudioBuffers. Idempotent per name.
+  // Everything else in this system is synthesized; these are the exceptions where a real
+  // recording reads far better than an oscillator (horse neighs/hoofsteps/breathing).
+  async loadSamples(map) {
+    this.ensure();
+    if (!this.ctx) return;
+    await Promise.all(Object.entries(map).map(async ([name, url]) => {
+      if (this.samples[name]) return;
+      try {
+        const arr = await (await fetch(url)).arrayBuffer();
+        this.samples[name] = await this.ctx.decodeAudioData(arr);
+      } catch (e) { console.warn('[audio] sample load failed', name, e); }
+    }));
+  }
+
+  // Fire a one-shot (or looping) sample. Returns { src, g } so a loop can be stopped/faded.
+  sample(name, { gain = 1, rate = 1, loop = false, dest = this.sfxGain } = {}) {
+    if (!this.enabled || !this.ctx) return null;
+    const buf = this.samples[name];
+    if (!buf) return null;
+    const src = this.ctx.createBufferSource();
+    src.buffer = buf; src.loop = loop; src.playbackRate.value = rate * this.sampleRateScale;
+    const g = this.ctx.createGain(); g.gain.value = gain;
+    src.connect(g).connect(dest || this.sfxGain);
+    src.start();
+    return { src, g };
+  }
+
+  setMuted(on) { this.muted = on; if (this.master) this.master.gain.value = on ? 0 : 0.5; }
+
+  ensure() {
+    if (this.ctx) return;
+    this.ctx = new (window.AudioContext || window.webkitAudioContext)();
+    this.master = this.ctx.createGain();
+    this.master.gain.value = 0.5;
+    // Dead Eye lowpass sits between master and the speakers — wide open (neutral) until
+    // setDeadEye() ramps it down, so it costs nothing when unused.
+    this.deadEyeLP = this.ctx.createBiquadFilter();
+    this.deadEyeLP.type = 'lowpass';
+    this.deadEyeLP.frequency.value = 20000;
+    this.deadEyeLP.Q.value = 0.0001;
+    this.master.connect(this.deadEyeLP).connect(this.ctx.destination);
+    this.musicGain = this.ctx.createGain();
+    this.musicGain.gain.value = 0.32;
+    this.musicGain.connect(this.master);
+    this.sfxGain = this.ctx.createGain();
+    this.sfxGain.gain.value = this.sfxVolume;
+    this.sfxGain.connect(this.master);
+    this.loadSfx();   // decode all the recorded SFX (combat + ui/pickup/spell) now the context exists
+  }
+
+  // Dead Eye (phase 2): 0 = normal, 1 = full slow-mo. Muffles the world (20kHz -> 700Hz,
+  // exponential so the sweep sounds even) and slows sample pitch a touch. Safe pre-ensure().
+  setDeadEye(amount) {
+    const a = Math.max(0, Math.min(1, amount));
+    this.sampleRateScale = 1 - 0.25 * a;
+    if (!this.deadEyeLP) return;
+    const f = 20000 * Math.pow(700 / 20000, a);
+    this.deadEyeLP.frequency.setTargetAtTime(f, this.ctx.currentTime, 0.08);
+  }
+
+  setVolume(v) { if (this.master) this.master.gain.value = v; }
+
+  // ----- tiny synth helpers -----
+  osc(type, freq, t0, dur, gainEnv, dest = this.sfxGain, detune = 0) {
+    const o = this.ctx.createOscillator();
+    o.type = type; o.frequency.value = freq; o.detune.value = detune;
+    const g = this.ctx.createGain();
+    g.gain.setValueAtTime(0, t0);
+    for (const [dt, v] of gainEnv) g.gain.linearRampToValueAtTime(v, t0 + dt);
+    o.connect(g).connect(dest);
+    o.start(t0); o.stop(t0 + dur + 0.05);
+    return o;
+  }
+
+  noise(t0, dur, { freq = 1200, q = 1, env = [[0, 0.6], [0.15, 0]] } = {}, dest = this.sfxGain) {
+    const len = Math.ceil(this.ctx.sampleRate * dur);
+    const buf = this.ctx.createBuffer(1, len, this.ctx.sampleRate);
+    const d = buf.getChannelData(0);
+    for (let i = 0; i < len; i++) d[i] = Math.random() * 2 - 1;
+    const src = this.ctx.createBufferSource();
+    src.buffer = buf;
+    const f = this.ctx.createBiquadFilter();
+    f.type = 'bandpass'; f.frequency.value = freq; f.Q.value = q;
+    const g = this.ctx.createGain();
+    g.gain.setValueAtTime(0, t0);
+    for (const [dt, v] of env) g.gain.linearRampToValueAtTime(v, t0 + dt);
+    src.connect(f).connect(g).connect(dest);
+    src.start(t0); src.stop(t0 + dur);
+  }
+
+  // Lazily load all recorded SFX (combat swing/hit/block/boom + ui/coin/orb/heal/quest/level-up).
+  // Called from ensure() once the context exists; sample() no-ops until they finish decoding.
+  loadSfx() {
+    const C = this._sfxDirs.combat, U = this._sfxDirs.ui;
+    const map = {};
+    for (let i = 1; i <= 6; i++) { map[`swing${i}`] = `${C}/swing${i}.wav`; map[`hit${i}`] = `${C}/hit${i}.wav`; }
+    for (let i = 1; i <= 3; i++) map[`block${i}`] = `${C}/block${i}.wav`;
+    for (let i = 1; i <= 4; i++) map[`boom${i}`] = `${C}/boom${i}.wav`;
+    map.uiclick1 = `${U}/uiclick1.wav`;
+    for (let i = 1; i <= 2; i++) map[`coin${i}`] = `${U}/coin${i}.wav`;
+    for (let i = 1; i <= 3; i++) map[`orb${i}`] = `${U}/orb${i}.wav`;
+    for (const e of ['heal', 'quest', 'questDone', 'renown', 'levelup']) map[`${e}1`] = `${U}/${e}1.wav`;
+    this.loadSamples(map);
+  }
+
+  // gainMul (default 1) scales the sound's volume — the hook for distance-attenuated one-shots: a
+  // caller with a world position computes (1 − d/range) and passes it, exactly as _idleVoice does with
+  // sample(). It applies on the recorded path (where the fight SFX live); the synth fallbacks are UI/gun
+  // cues played at fixed spots, so they ignore it.
+  play(name, gainMul = 1) {
+    if (!this.enabled || !this.ctx || gainMul <= 0) return;
+    // real recorded variants take priority over the synth fallback (once decoded)
+    const r = this._sfx[name];
+    if (r && this.samples[`${r.b}1`]) {
+      const k = 1 + ((Math.random() * r.n) | 0);
+      this.sample(`${r.b}${k}`, { gain: r.g * gainMul, rate: (r.r ?? 1) * (r.j ? 0.94 + Math.random() * 0.12 : 1) });
+      return;
+    }
+    if (this._muted.has(name)) return;   // no recorded source yet — silent, never a synth beep
+    const t = this.ctx.currentTime + 0.001;
+    switch (name) {
+      // ---- guns (synthesized — no recordings; a this._sfx entry later swaps these out) ----
+      case 'gunshot': {
+        const j = 0.92 + Math.random() * 0.16;   // slight per-shot drift so volleys don't machine-gun
+        this.noise(t, 0.08, { freq: 3200 * j, q: 0.4, env: [[0, 1.0], [0.08, 0]] });           // crack
+        this.noise(t, 0.25, { freq: 170 * j, q: 0.7, env: [[0, 0], [0.02, 0.85], [0.25, 0]] }); // lowpassed boom tail
+        this.osc('sine', 62 * j, t, 0.2, [[0, 0.5], [0.2, 0]]);                                 // chest thump
+        break;
+      }
+      case 'gunshot_far': {   // distant/muffled report — enemy fire across the street
+        const j = 0.9 + Math.random() * 0.2;
+        this.noise(t, 0.45, { freq: 130 * j, q: 0.8, env: [[0, 0], [0.04, 0.4], [0.45, 0]] });
+        this.osc('sine', 55 * j, t, 0.35, [[0, 0.25], [0.35, 0]]);
+        break;
+      }
+      case 'ricochet': {      // descending whine off rock/wood; randomized start pitch
+        const f0 = 1900 + Math.random() * 1400;
+        const o = this.ctx.createOscillator();
+        o.type = 'sine';
+        o.frequency.setValueAtTime(f0, t);
+        o.frequency.exponentialRampToValueAtTime(f0 * 0.28, t + 0.2);
+        const g = this.ctx.createGain();
+        g.gain.setValueAtTime(0, t);
+        g.gain.linearRampToValueAtTime(0.22, t + 0.015);
+        g.gain.linearRampToValueAtTime(0, t + 0.2);
+        o.connect(g).connect(this.sfxGain);
+        o.start(t); o.stop(t + 0.25);
+        this.noise(t, 0.05, { freq: 2600, q: 1.5, env: [[0, 0.3], [0.05, 0]] });   // impact ping
+        break;
+      }
+      case 'dryfire': this.noise(t, 0.03, { freq: 2400, q: 2, env: [[0, 0.3], [0.03, 0]] }); break;
+      case 'reload':          // two hammer/cylinder clicks
+        this.noise(t, 0.035, { freq: 1700, q: 2.5, env: [[0, 0.35], [0.035, 0]] });
+        this.noise(t + 0.12, 0.04, { freq: 1300, q: 2.5, env: [[0, 0.4], [0.04, 0]] });
+        break;
+      case 'swing': this.noise(t, 0.18, { freq: 900, q: 0.8, env: [[0, 0], [0.04, 0.5], [0.18, 0]] }); break;
+      case 'swingHeavy': this.noise(t, 0.3, { freq: 500, q: 0.8, env: [[0, 0], [0.06, 0.7], [0.3, 0]] }); break;
+      case 'hit': this.noise(t, 0.12, { freq: 350, q: 1.5, env: [[0, 0.9], [0.12, 0]] }); this.osc('square', 90, t, 0.1, [[0, 0.5], [0.1, 0]]); break;
+      case 'hurt': this.osc('sawtooth', 160, t, 0.18, [[0, 0.4], [0.18, 0]]); break;
+      case 'block': this.osc('triangle', 1200, t, 0.1, [[0, 0.5], [0.1, 0]]); this.noise(t, 0.08, { freq: 2400, q: 3, env: [[0, 0.4], [0.08, 0]] }); break;
+      case 'whoosh': this.noise(t, 0.25, { freq: 600, q: 0.6, env: [[0, 0], [0.1, 0.4], [0.25, 0]] }); break;
+      case 'bow': this.osc('triangle', 220, t, 0.12, [[0, 0.5], [0.12, 0]]); this.noise(t, 0.15, { freq: 1500, q: 2, env: [[0, 0.3], [0.15, 0]] }); break;
+      case 'fireball': this.noise(t, 0.5, { freq: 300, q: 0.5, env: [[0, 0], [0.15, 0.6], [0.5, 0]] }); break;
+      case 'boom': this.noise(t, 0.6, { freq: 120, q: 0.4, env: [[0, 1], [0.6, 0]] }); this.osc('sine', 55, t, 0.5, [[0, 0.8], [0.5, 0]]); break;
+      case 'lightning': this.noise(t, 0.3, { freq: 3500, q: 0.5, env: [[0, 0.8], [0.3, 0]] }); this.osc('sawtooth', 80, t, 0.25, [[0, 0.5], [0.25, 0]]); break;
+      case 'push': this.osc('sine', 70, t, 0.4, [[0, 0.9], [0.4, 0]]); this.noise(t, 0.3, { freq: 250, q: 0.7, env: [[0, 0.5], [0.3, 0]] }); break;
+      case 'heal': this.arp(t, [523, 659, 784], 0.09, 'sine', 0.25); break;
+      case 'orb': this.osc('sine', 880 + Math.random() * 220, t, 0.18, [[0, 0.25], [0.18, 0]]); break;
+      case 'quest': this.arp(t, [392, 523, 659, 784], 0.13, 'triangle', 0.3); break;
+      case 'questDone': this.arp(t, [523, 659, 784, 1046, 784, 1046], 0.12, 'triangle', 0.32); break;
+      case 'levelup': this.arp(t, [392, 494, 587, 784, 988], 0.1, 'square', 0.18); break;
+      case 'renown': this.arp(t, [330, 392, 494, 659], 0.15, 'triangle', 0.28); break;
+      case 'aggro': this.osc('sawtooth', 110, t, 0.3, [[0, 0.25], [0.3, 0]]); break;
+      case 'ui': this.osc('sine', 660, t, 0.06, [[0, 0.2], [0.06, 0]]); break;
+      case 'coin': this.osc('square', 1320, t, 0.08, [[0, 0.15], [0.08, 0]]); this.osc('square', 1760, t + 0.06, 0.08, [[0, 0.12], [0.08, 0]]); break;
+      case 'door': this.noise(t, 0.4, { freq: 180, q: 1, env: [[0, 0.5], [0.4, 0]] }); break;
+    }
+  }
+
+  arp(t0, freqs, step, type = 'sine', vol = 0.25) {
+    freqs.forEach((f, i) => {
+      this.osc(type, f, t0 + i * step, step * 1.8, [[0, vol], [step * 1.8, 0]]);
+    });
+  }
+
+  setMode(mode) {
+    if (this.mode !== mode) this.mode = mode;
+  }
+}

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;