sindicate 0.1.0 → 0.4.0

package/src/core/engine.js

@@ -0,0 +1,284 @@
+// The Engine base: frame loop, the two clocks (rawDt vs scaled dt), the timeScale
+// contributor chain, game-time timers, feel (hitstop/shake), the culling frustum,
+// the single render path, warm-up, and the freeze profiler / perf census.
+// Contracts: docs/contracts/time-feel.md and docs/contracts/render.md.
+//
+//   const engine = new Engine({ renderer, scene, camera, input,
+//     post,                        // PostProcessing from createPostProcessing (or null)
+//     isPaused: () => ui.anyPanelOpen,   // holds sim: engine timers + game's gated blocks
+//     isUiModal: () => ui.anyPanelOpen,  // pad drives the UI, suppress game mappings
+//   })
+//   engine.addTimeScale(() => slowMo.scale)      // multiplicative, 1 = inactive
+//   engine.on('preScale', (ctx) => …)            // rawDt phase — decide THIS frame's scale
+//   engine.on('frame', (ctx) => …)               // ordered main-phase hooks: ctx = { dt,
+//                                                //   rawDt, paused, stamp, engine }
+//   engine.onFps((fps) => …)                     // 1s-window fps readout
+//   engine.start()                               // hands the loop to the renderer
+import * as THREE from 'three/webgpu';
+
+export class Engine {
+  constructor({ renderer, scene, camera, input, post = null, isPaused = () => false, isUiModal = () => false }) {
+    this.renderer = renderer;
+    this.scene = scene;
+    this.camera = camera;
+    this.input = input;
+    this.post = post;
+    this.isPaused = isPaused;
+    this.isUiModal = isUiModal;
+
+    // time
+    this.rawDt = 0;
+    this.worldDtScale = 1;         // exposed: the dev drive-bus asserts on it
+    this.playSeconds = 0;          // unpaused world time (save-slot playtime readout)
+    this._timers = [];
+    this._timeScales = [];
+    this._clockLast = performance.now();
+
+    // feel — hit-stop is a built-in contributor: combat refreshes the window, the
+    // world crawls at 0.12× while it runs (cheap, famous crunch)
+    this.hitstopT = 0;
+    this.addTimeScale(() => {
+      if (this.hitstopT > 0) { this.hitstopT -= this._frameDt; return 0.12; }
+      return 1;
+    });
+    this.shakeT = 0;
+
+    // culling frustum — built by buildCullFrustum() once per unpaused frame; MAY BE
+    // NULL and null means "don't cull" (a stale frustum mis-culls; see render contract)
+    this.cullFrustum = null;
+
+    this._hooks = { preScale: [], frame: [] };
+    this._fpsCb = null;
+    this._fps = { acc: 0, n: 0, t: 0 };
+    this._perf = null;
+    this._stampKeys = [];
+    this.__post = undefined;       // set false for a plain-render A/B
+
+    this.tick = this._tick.bind(this);
+  }
+
+  // ---- registration -------------------------------------------------------------------
+  on(phase, fn) {
+    if (!this._hooks[phase]) throw new Error(`Engine.on: unknown phase '${phase}'`);
+    this._hooks[phase].push(fn);
+    return fn;
+  }
+  addTimeScale(fn) { this._timeScales.push(fn); return fn; }
+  onFps(cb) { this._fpsCb = cb; }
+
+  // ---- time & feel --------------------------------------------------------------------
+  // schedule fn after `sec` seconds of GAME time — freezes with the pause menu (a pause
+  // can never eat a landing), stretches under slow-mo. Errors are caught, never thrown
+  // into the loop.
+  after(sec, fn) { this._timers.push({ t: sec, fn }); }
+  wait(sec) { return new Promise((r) => this.after(sec, r)); }
+  hitstop(sec) { this.hitstopT = Math.max(this.hitstopT, sec); }
+  shake(amount) { this.shakeT = Math.max(this.shakeT, amount); }
+  // camera shake — call at the point in the frame where the camera is FINAL (after every
+  // camera writer), not earlier: shake applied before an override is shake thrown away.
+  applyShake(dt) {
+    if (this.shakeT > 0) {
+      this.shakeT = Math.max(0, this.shakeT - dt * 1.8);
+      this.camera.position.x += (Math.random() - 0.5) * this.shakeT * 0.75;
+      this.camera.position.y += (Math.random() - 0.5) * this.shakeT * 0.75;
+    }
+  }
+
+  // ---- render path --------------------------------------------------------------------
+  // THE render path — one function so boot warm-up and the tick go through the SAME
+  // pipelines (a settle that warmed the plain path would leave the post path to compile
+  // its first frame in gameplay). engine.__post = false drops to plain render for an A/B.
+  renderFrame() {
+    if (this.post && this.__post !== false) this.post.render();
+    else this.renderer.render(this.scene, this.camera);
+  }
+
+  // Night dimming etc. via tone-map exposure. CRITICAL: only WRITE when it actually
+  // changes — writing renderer.toneMappingExposure every frame forces a WebGPU
+  // output-pipeline rebuild on some GPUs → freezes. The gate lives here so games can
+  // "set" it every frame safely.
+  setExposure(v) {
+    if (Math.abs(v - (this._lastExposure ?? -1)) > 0.008) { this.renderer.toneMappingExposure = v; this._lastExposure = v; }
+  }
+
+  // Build the per-frame culling frustum. Call ONCE per unpaused frame, after every
+  // camera writer that matters to culling. Consumers read engine.cullFrustum and MUST
+  // treat null as visible; a game may null it deliberately for a frame (paused dialogue
+  // ticking one NPC against a stale camera) — the next build repairs it.
+  buildCullFrustum() {
+    this.camera.updateMatrixWorld();
+    (this._camMWI ??= new THREE.Matrix4()).copy(this.camera.matrixWorld).invert();
+    (this._camProj ??= new THREE.Matrix4()).multiplyMatrices(this.camera.projectionMatrix, this._camMWI);
+    (this.cullFrustum ??= new THREE.Frustum()).setFromProjectionMatrix(this._camProj);
+    return this.cullFrustum;
+  }
+
+  // ---- warm-up (PERF LAW) -------------------------------------------------------------
+  // Force every hidden / frustum-culled / count-0-instanced mesh to compile its GPU
+  // pipeline NOW (at load) instead of on first sight — first-sight compile is the
+  // multi-frame freeze you get spinning the camera onto something you hadn't looked at.
+  // compileAsync, NOT render(): compiles off the main thread (render() blocked ~20s and
+  // tripped Chrome's 'page unresponsive'). Still awaited at boot — no travel freezes.
+  async warmRenderHidden(tag, root = this.scene) {
+    const warm = [];
+    root.traverse((o) => {
+      const mesh = o.isMesh || o.isInstancedMesh;
+      const hidI = mesh && o.isInstancedMesh && o.count === 0 && (o.instanceMatrix?.array?.length ?? 0) >= 16;
+      if (!(o.visible === false || hidI || (mesh && o.frustumCulled))) return;
+      warm.push({ o, vis: o.visible, cnt: o.isInstancedMesh ? o.count : null, fc: mesh ? o.frustumCulled : null });
+      o.visible = true; if (mesh) o.frustumCulled = false; if (hidI) o.count = 1;
+    });
+    const t0 = performance.now();
+    if (warm.length) { try { await this.renderer.compileAsync(this.scene, this.camera); } catch (e) { /* warm */ } }
+    console.log(`[warm:${tag}] ${Math.round(performance.now() - t0)}ms over ${warm.length} hidden/culled objs (off-thread compile)`);
+    for (const w of warm) { w.o.visible = w.vis; if (w.cnt !== null) w.o.count = w.cnt; if (w.fc !== null) w.o.frustumCulled = w.fc; }
+    return warm.length;
+  }
+
+  // ---- the loop -----------------------------------------------------------------------
+  start() {
+    this._clockLast = performance.now();
+    this.renderer.setAnimationLoop(this.tick);
+    // auto perf log — first at 6s (past load hitches), then periodic
+    setTimeout(() => { this.perfReport(); this._perfTimer = setInterval(() => this.perfReport(), 15000); }, 6000);
+  }
+  stop() {
+    this.renderer.setAnimationLoop(null);
+    if (this._perfTimer) clearInterval(this._perfTimer);
+  }
+
+  _tick() {
+    const now = performance.now();
+    let dt = Math.min((now - this._clockLast) / 1000, 0.1);
+    this._clockLast = now;
+    const rawDt = dt;   // wall-clock — the fps meter reads THIS (scaled dt inflates it during hit-stop)
+    this.rawDt = rawDt; // published for systems that must NOT slow down (camera look, aim IK)
+
+    this.input?.pollGamepad(this.isUiModal());   // panels drive the pad themselves; suppress game mappings
+
+    const paused = this.isPaused();
+    const stamps = (this._stamps = { t0: performance.now() });
+    const stamp = (key) => { stamps[key] = performance.now(); if (!(key in (this._perf ?? {}))) this._stampKeys.includes(key) || this._stampKeys.push(key); };
+    const ctx = { dt: 0, rawDt, paused, stamp, engine: this };
+
+    // PRE-SCALE (rawDt): systems that produce this frame's timeScale run first, so the
+    // scale they return lands on THIS frame (a slow-mo meter timed in slow-mo drains 3×
+    // slower the instant it activates).
+    for (const fn of this._hooks.preScale) fn(ctx);
+
+    // world-dt multiplier chain — every contribution lands on ONE dt, which then drives
+    // mixers, physics, AI, projectiles, VFX.
+    this._frameDt = dt;
+    let scale = 1;
+    for (const fn of this._timeScales) scale *= fn();
+    this.worldDtScale = scale;
+    dt *= scale;
+    ctx.dt = dt;
+
+    // game-time bookkeeping — first thing inside the pause gate, before any sim hook
+    if (!paused) {
+      this.playSeconds += dt;
+      for (let i = this._timers.length - 1; i >= 0; i--) {
+        const tm = this._timers[i];
+        tm.t -= dt;
+        if (tm.t <= 0) { this._timers.splice(i, 1); try { tm.fn(); } catch (e) { console.warn('[after]', e); } }
+      }
+    }
+
+    // MAIN PHASE — the game's ordered hooks. Pause-gating of individual blocks is the
+    // hook's business (ctx.paused); ordering between hooks is registration order.
+    for (const fn of this._hooks.frame) fn(ctx);
+
+    this.renderFrame();
+    stamps.render = performance.now();
+
+    this._accumulatePerf(stamps);
+    this._freezeProbe(stamps);
+
+    // fps meter — 1s window (a calmer readout; real spikes still show in the freeze log)
+    const f = this._fps;
+    f.acc += rawDt; f.n++; f.t += rawDt;
+    if (f.t > 1) {
+      this._fpsCb?.(Math.round(f.n / f.acc));
+      f.acc = 0; f.n = 0; f.t = 0;
+    }
+
+    this.input?.endFrame();
+  }
+
+  // ---- profiling ----------------------------------------------------------------------
+  _accumulatePerf(stamps) {
+    const P = (this._perfAcc ??= { n: 0, frame: 0, phases: {} });
+    P.n++; P.frame += stamps.render - stamps.t0;
+    let prev = stamps.t0;
+    for (const k of this._stampKeys) {
+      if (!(k in stamps)) continue;
+      P.phases[k] = (P.phases[k] ?? 0) + (stamps[k] - prev);
+      prev = stamps[k];
+    }
+    P.phases.render = (P.phases.render ?? 0) + (stamps.render - prev);
+  }
+
+  // FREEZE PROFILER: a SILENT ring buffer of slow frames + their phase breakdown, with
+  // frame-level cause attribution sampled EVERY frame so a freeze's deltas reveal WHAT
+  // it did: pipe = compiled-pipeline count (grows = a shader compiled this frame = a
+  // warm-coverage gap); geo/tex = uploads (a streamed tile). __dumpFreezeLog() downloads.
+  _freezeProbe(stamps) {
+    const frame = stamps.render - stamps.t0;
+    const _pipe = this.renderer._pipelines?.caches?.size ?? -1;
+    const _geo = this.renderer.info?.memory?.geometries ?? -1;
+    const _tex = this.renderer.info?.memory?.textures ?? -1;
+    const last = (this._fzLast ??= { pipe: _pipe, geo: _geo, tex: _tex });
+    if (frame > 55) {
+      const b = { ms: Math.round(frame), v: 5 };
+      let prev = stamps.t0;
+      for (const k of this._stampKeys) { if (k in stamps) { b[k] = +(stamps[k] - prev).toFixed(1); prev = stamps[k]; } }
+      b.render = +(stamps.render - prev).toFixed(1);
+      b.calls = this.renderer.info?.render?.drawCalls ?? -1;
+      b.tris = this.renderer.info?.render?.triangles ?? -1;
+      b.pipe = _pipe - last.pipe; b.geo = _geo - last.geo; b.tex = _tex - last.tex; b.pipeTotal = _pipe;
+      b.t = Math.round(stamps.render);
+      Object.assign(b, this._freezeExtra?.() ?? {});
+      const log = (window.__freezeLog ??= []); log.push(b); if (log.length > 300) log.shift();
+      if (import.meta.env?.DEV) { try { fetch('/__perf', { method: 'POST', body: JSON.stringify({ FREEZE: b }) }); } catch (e) { /* sink offline */ } }
+      window.__dumpFreezeLog ??= () => {
+        const a = document.createElement('a');
+        a.href = URL.createObjectURL(new Blob([JSON.stringify(window.__freezeLog, null, 2)], { type: 'application/json' }));
+        a.download = 'freeze-log.json'; a.click();
+      };
+    }
+    last.pipe = _pipe; last.geo = _geo; last.tex = _tex;
+  }
+  // game hook: extra fields for freeze records / perf reports (e.g. sky hour, player pos)
+  setPerfExtras({ freeze = null, report = null } = {}) { this._freezeExtra = freeze; this._reportExtra = report; }
+
+  // One-shot perf census: frame-time by phase, GPU load, what's resident/visible, exact
+  // render state. Prints to console when window.__perflog is set; always returns it.
+  perfReport() {
+    if (document.hidden) return null; // backgrounded tab: rAF paused, the sample is noise
+    const r = this.renderer, info = r.info;
+    let meshes = 0, skinned = 0, skinnedVis = 0, instanced = 0, instCount = 0, lights = 0, litOn = 0, sprites = 0;
+    this.scene.traverse((o) => {
+      if (o.isInstancedMesh) { instanced++; instCount += o.count; }
+      else if (o.isSkinnedMesh) { skinned++; if (o.visible && o.parent?.visible !== false) skinnedVis++; }
+      else if (o.isMesh) meshes++;
+      if (o.isSprite) sprites++;
+      if (o.isLight) { lights++; if (o.intensity > 0) litOn++; }
+    });
+    const P = this._perfAcc ?? { n: 1, frame: 0, phases: {} };
+    const n = Math.max(1, P.n), fps = Math.round(1000 / (P.frame / n || 16));
+    const phases = {};
+    for (const k of Object.keys(P.phases)) phases[k] = +(P.phases[k] / n).toFixed(2);
+    const rep = {
+      fps, frameMs: +(P.frame / n).toFixed(2), phases,
+      gpu: { calls: info.render?.drawCalls, ktris: +((info.render?.triangles ?? 0) / 1000).toFixed(0), geometries: info.memory?.geometries, textures: info.memory?.textures },
+      scene: { meshes, skinned, skinnedVisible: skinnedVis, instancedMeshes: instanced, instances: instCount, lights, litOn, sprites },
+      render: { postProcessing: !!this.post, shadows: r.shadowMap?.enabled, pixelRatio: +r.getPixelRatio().toFixed(2), cameraFar: this.camera.far },
+      ...(this._reportExtra?.() ?? {}),
+    };
+    if (window.__perflog) console.log(`%c[PERF] ${fps}fps · frame ${rep.frameMs}ms`, 'color:#4dd; font-weight:700', rep);
+    this._perfAcc = { n: 0, frame: 0, phases: {} };
+    if (import.meta.env?.DEV) { try { fetch('/__perf', { method: 'POST', body: JSON.stringify(rep) }); } catch (e) { /* sink offline */ } }
+    return rep;
+  }
+}

package/src/core/input/bindings.js

@@ -0,0 +1,30 @@
+// Gamepad bindings are DATA a game passes in: new Input(dom, { padBindings }).
+// This default is a sane third-person-action layout (standard mapping, PS names):
+// Cross(0) jump · Circle(1) dodge · Square(2) interact · Triangle(3) swap ·
+// R1(5) reload · L2(6) sprint · Share(8) tab-panel · Options(9) pause ·
+// L3(10) ability · D-pad UP(12) inventory · LEFT(14) finisher · RIGHT(15) slot 1 ·
+// D-pad DOWN(13)/touchpad(16,17) map · R2(7) fire (LMB) · L1(4) aim-hold (RMB).
+export const DEFAULT_PAD_BINDINGS = {
+  // pad button index -> key code the rest of the game reads via down()/hit()
+  buttonKeys: {
+    0: 'Space', 1: 'AltLeft', 2: 'KeyE', 3: 'KeyQ', 5: 'KeyR', 6: 'ShiftLeft',
+    8: 'Tab', 9: 'Escape', 10: 'ControlLeft', 12: 'KeyI', 14: 'KeyF', 15: 'Digit1',
+  },
+  // several buttons -> ONE key must be OR'd in a single write: routing them through
+  // buttonKeys makes them fight — the un-pressed ones clear the key the pressed one
+  // just set, so it re-fires every frame (a map-flicker bug this engine shipped once).
+  comboKeys: [{ key: 'KeyM', buttons: [13, 16, 17] }],
+  // analog trigger/bumper -> virtual mouse button (value-thresholded, not .pressed)
+  axisMouse: [
+    { mouseButton: 0, button: 7, threshold: 0.4 },   // R2 = fire
+    { mouseButton: 2, button: 4, threshold: 0.4 },   // L1 = aim (held; read via held(2))
+  ],
+  // left stick -> digital move keys (for consumers that only want on/off:
+  // jump run-up, dodge direction, anim gates — analog movement reads moveStick)
+  moveKeys: { up: 'KeyW', down: 'KeyS', left: 'KeyA', right: 'KeyD', threshold: 0.2 },
+  // response tuning. moveDeadzone is RADIAL and rescaled from the zone edge (a
+  // per-axis threshold is "dead to one side, then a lurch to full"). lookDeadzone
+  // is small + the magnitude is raised to lookExponent past it: slow near centre
+  // for fine aim, fast at the edge to whip the camera (the RDR2 feel).
+  curves: { moveDeadzone: 0.10, lookDeadzone: 0.06, lookExponent: 2, stickAxisDeadzone: 0.22 },
+};

package/src/core/input/gamepad.js

@@ -0,0 +1,92 @@
+// Gamepad device (PS5/Xbox via the standard mapping), folded into the same
+// key/button vocabulary as keyboard+mouse so game code reads ONE API.
+// Bindings are data (see bindings.js) — a game passes its own layout in.
+import { DEFAULT_PAD_BINDINGS } from './bindings.js';
+
+export class GamepadDevice {
+  constructor(bindings = DEFAULT_PAD_BINDINGS) {
+    this.bindings = bindings;
+    this.gpKeys = new Set();
+    this.gpPressed = new Set();
+    this.gpButtons = 0;            // virtual mouse-button bitmask
+    this.gpMousePressed = new Set();
+    this._gpLastT = -1e9;
+    this._gpPrime = false;
+    // right-stick look, deadzoned + curved (range −1..1). Kept separate from the
+    // mouse delta so the camera can apply it rate-based (framerate-independent).
+    this.stickLook = { x: 0, y: 0 };
+    // left-stick MOVE, analog (range −1..1, radial deadzone). Digital move-key faking
+    // still fires for on/off consumers, but MOVEMENT reads this so a light push walks
+    // and a full push runs — an analog stick was all-or-nothing on the key threshold.
+    this.moveStick = { x: 0, y: 0 };
+  }
+
+  // Poll once per frame and fold the pad into the input state.
+  poll(uiOpen = false) {
+    const pads = typeof navigator !== 'undefined' && navigator.getGamepads ? navigator.getGamepads() : null;
+    let gp = null;
+    if (pads) for (const p of pads) { if (p && p.connected) { gp = p; break; } }
+    this.gpPressed.clear();
+    this.gpMousePressed.clear();
+    if (!gp) { this.gpKeys.clear(); this.gpButtons = 0; this.stickLook.x = 0; this.stickLook.y = 0; this.moveStick.x = 0; this.moveStick.y = 0; return; }
+    const B = this.bindings, C = B.curves;
+    const DZ = C.stickAxisDeadzone;
+    const ax = (i) => { const v = gp.axes[i] || 0; return Math.abs(v) < DZ ? 0 : v; };
+    const lx = ax(0), ly = ax(1), rx = ax(2), ry = ax(3);
+    const bv = (i) => (gp.buttons[i] ? gp.buttons[i].value : 0);
+    const bp = (i) => !!(gp.buttons[i] && gp.buttons[i].pressed);
+    // LEFT STICK, ANALOG MOVE — radial deadzone (magnitude, not per-axis), rescaled so
+    // motion ramps from 0 the instant you clear the zone.
+    const rlx = gp.axes[0] || 0, rly = gp.axes[1] || 0;
+    const mMag = Math.hypot(rlx, rly), MDZ = C.moveDeadzone;
+    if (mMag > MDZ) { const s = ((mMag - MDZ) / (1 - MDZ)) / mMag; this.moveStick.x = rlx * s; this.moveStick.y = rly * s; }
+    else { this.moveStick.x = 0; this.moveStick.y = 0; }
+    // While a modal panel owns the screen the pad drives the UI — the panel polls the
+    // raw pad itself — NOT the game. Suppress the game mappings so a press doesn't leak
+    // into movement/fire/aim behind the panel; still mark the pad "active".
+    if (uiOpen) {
+      this.gpKeys.clear(); this.gpButtons = 0;
+      this.moveStick.x = this.moveStick.y = 0; this.stickLook.x = this.stickLook.y = 0;
+      if (gp.buttons.some((b) => b && b.value > 0.3) || lx || ly || rx || ry) this._gpLastT = (typeof performance !== 'undefined' ? performance.now() : 0);
+      this._gpPrime = true;   // next game frame: a button still held from driving the UI must NOT fire a fresh edge
+      return;
+    }
+    // FIRST FRAME BACK FROM A PANEL: the button the player is still holding — the one that
+    // dismissed the panel — would otherwise register as a fresh press the instant the game
+    // mappings switch back on (close-dialogue is ALSO jump → the player jumped as the talk
+    // ended). On this one frame PRIME the held state but suppress the edge, so only a
+    // genuine release-and-repress acts.
+    const prime = this._gpPrime; this._gpPrime = false;
+    // left stick -> digital move keys
+    const MK = B.moveKeys, MT = MK.threshold;
+    this._gpKey(MK.up, ly < -MT, prime); this._gpKey(MK.down, ly > MT, prime);
+    this._gpKey(MK.left, lx < -MT, prime); this._gpKey(MK.right, lx > MT, prime);
+    // RIGHT STICK -> LOOK: small radial deadzone, then magnitude raised to lookExponent —
+    // slow near centre (fine aim), fast at the edge (whip the camera round).
+    const rrx = gp.axes[2] || 0, rry = gp.axes[3] || 0, rMag = Math.hypot(rrx, rry), RDZ = C.lookDeadzone;
+    if (rMag > RDZ) {
+      const t = (rMag - RDZ) / (1 - RDZ);
+      const curved = Math.pow(t, C.lookExponent);
+      this.stickLook.x = (rrx / rMag) * curved;
+      this.stickLook.y = (rry / rMag) * curved;
+    } else { this.stickLook.x = 0; this.stickLook.y = 0; }
+    // buttons -> keys, per the game's bindings table
+    for (const i in B.buttonKeys) this._gpKey(B.buttonKeys[i], bp(+i), prime);
+    for (const combo of B.comboKeys) this._gpKey(combo.key, combo.buttons.some(bp), prime);
+    for (const am of B.axisMouse) this._gpBtn(am.mouseButton, bv(am.button) > am.threshold, prime);
+    // mark active if any meaningful input this frame (keeps the mouse re-lock fix
+    // working when a pad is merely connected but idle)
+    if (lx || ly || rx || ry || gp.buttons.some((b) => b && b.value > 0.3)) this._gpLastT = (typeof performance !== 'undefined' ? performance.now() : 0);
+  }
+  _gpKey(code, on, prime) {
+    const was = this.gpKeys.has(code);
+    if (on && !was) { this.gpKeys.add(code); if (!prime) this.gpPressed.add(code); }   // prime: adopt the held state without firing an edge
+    else if (!on && was) this.gpKeys.delete(code);
+  }
+  _gpBtn(btn, on, prime) {
+    const bit = 1 << btn, was = (this.gpButtons & bit) !== 0;
+    if (on && !was) { this.gpButtons |= bit; if (!prime) this.gpMousePressed.add(btn); }
+    else if (!on && was) this.gpButtons &= ~bit;
+  }
+  get active() { return (typeof performance !== 'undefined' ? performance.now() : 0) - this._gpLastT < 1500; }
+}

package/src/core/input/index.js

@@ -0,0 +1,62 @@
+// Unified input: keyboard + mouse + gamepad behind ONE API with per-frame edge
+// detection. Game code never talks to a device — it reads key codes and mouse
+// buttons; the gamepad folds itself into that same vocabulary via a bindings
+// table (data the game passes in — see bindings.js).
+//
+//   const input = new Input(canvas, { padBindings: MY_LAYOUT })
+//   input.pollGamepad(ui.anyPanelOpen)   // once per frame, BEFORE game reads
+//   if (input.hit('KeyE')) …             // true for keyboard E or bound pad button
+//   input.endFrame()                     // last thing in the frame
+import { KeyboardDevice } from './keyboard.js';
+import { MouseDevice } from './mouse.js';
+import { GamepadDevice } from './gamepad.js';
+export { DEFAULT_PAD_BINDINGS } from './bindings.js';
+
+export class Input {
+  constructor(domElement, { padBindings } = {}) {
+    this.dom = domElement;
+    this._kb = new KeyboardDevice();
+    this._ms = new MouseDevice(domElement);
+    this._gp = new GamepadDevice(padBindings);
+    // aliases: existing code reads these fields directly, and the devices own the
+    // live objects — same references, so writes/reads stay coherent either way.
+    this.keys = this._kb.keys;
+    this.pressed = this._kb.pressed;
+    this.mouse = this._ms.mouse;
+    this.mousePressed = this._ms.mousePressed;
+    this.gpKeys = this._gp.gpKeys;
+    this.gpPressed = this._gp.gpPressed;
+    this.gpMousePressed = this._gp.gpMousePressed;
+    this.stickLook = this._gp.stickLook;
+    this.moveStick = this._gp.moveStick;
+  }
+  get wheel() { return this._ms.wheel; }
+  get pointerLocked() { return this._ms.pointerLocked; }
+  get _gpButtons() { return this._gp.gpButtons; }
+
+  requestLock() { this._ms.requestLock(); }
+  releaseLock() { this._ms.releaseLock(); }
+  pollGamepad(uiOpen = false) { this._gp.poll(uiOpen); }
+
+  get gpActive() { return this._gp.active; }
+  // camera/combat enabled when mouse is captured OR a gamepad is in active use
+  get acting() { return this.pointerLocked || this.gpActive; }
+
+  down(code) { return this.keys.has(code) || this.gpKeys.has(code); }
+  hit(code) { return this.pressed.has(code) || this.gpPressed.has(code); }
+  mouseHit(btn) { return this.mousePressed.has(btn) || this.gpMousePressed.has(btn); }
+  held(btn) { return (((this.mouse.buttons | this._gp.gpButtons) >> btn) & 1) !== 0; }
+
+  // Drop a just-pressed code so a single button press isn't acted on twice — e.g.
+  // the UI confirms a dialogue option with E, then world-interaction must not see
+  // that same E and immediately re-open dialogue.
+  consume(code) { this.pressed.delete(code); this.gpPressed.delete(code); }
+  // Same, for a mouse button: slow-mo eats the LMB that looses its volley so the gun
+  // state machine doesn't ALSO read that click as a hip shot.
+  consumeMouse(btn) { this.mousePressed.delete(btn); this.gpMousePressed.delete(btn); }
+
+  endFrame() {
+    this._kb.endFrame();
+    this._ms.endFrame();
+  }
+}

package/src/core/input/keyboard.js

@@ -0,0 +1,16 @@
+// Keyboard device: held-key set + per-frame edge set.
+export class KeyboardDevice {
+  constructor() {
+    this.keys = new Set();
+    this.pressed = new Set();      // cleared each frame by the Input facade
+    window.addEventListener('keydown', (e) => {
+      if (e.repeat) return;
+      this.keys.add(e.code);
+      this.pressed.add(e.code);
+    });
+    window.addEventListener('keyup', (e) => this.keys.delete(e.code));
+    // a button held across alt-tab stayed 'held' forever (stuck block/bow)
+    window.addEventListener('blur', () => this.keys.clear());
+  }
+  endFrame() { this.pressed.clear(); }
+}

package/src/core/input/mouse.js

@@ -0,0 +1,48 @@
+// Mouse device: buttons/movement/wheel + pointer-lock management.
+export class MouseDevice {
+  constructor(domElement) {
+    this.dom = domElement;
+    this.mouse = { x: 0, y: 0, dx: 0, dy: 0, buttons: 0 };
+    this.mousePressed = new Set(); // button indices pressed this frame
+    this.wheel = 0;
+    this.pointerLocked = false;
+
+    domElement.addEventListener('mousedown', (e) => {
+      this.mouse.buttons |= (1 << e.button);
+      this.mousePressed.add(e.button);
+    });
+    window.addEventListener('mouseup', (e) => {
+      this.mouse.buttons &= ~(1 << e.button);
+    });
+    window.addEventListener('mousemove', (e) => {
+      if (this.pointerLocked) {
+        this.mouse.dx += e.movementX;
+        this.mouse.dy += e.movementY;
+      }
+      this.mouse.x = e.clientX;
+      this.mouse.y = e.clientY;
+    });
+    window.addEventListener('wheel', (e) => { this.wheel += Math.sign(e.deltaY); }, { passive: true });
+    // a button held across alt-tab stayed 'held' forever
+    window.addEventListener('blur', () => { this.mouse.buttons = 0; });
+
+    document.addEventListener('pointerlockchange', () => {
+      const wasLocked = this.pointerLocked;
+      this.pointerLocked = document.pointerLockElement === domElement;
+      // the click that re-acquires the lock (e.g. after closing dialogue) must not
+      // also register as an attack — drop any pending mouse press on lock-acquire.
+      if (this.pointerLocked && !wasLocked) { this.mousePressed.clear(); this.mouse.buttons = 0; }
+    });
+    domElement.addEventListener('contextmenu', (e) => e.preventDefault());
+  }
+
+  requestLock() { if (!this.pointerLocked) this.dom.requestPointerLock?.(); }
+  releaseLock() { if (this.pointerLocked) document.exitPointerLock?.(); }
+
+  endFrame() {
+    this.mousePressed.clear();
+    this.mouse.dx = 0;
+    this.mouse.dy = 0;
+    this.wheel = 0;
+  }
+}

package/src/core/quality.js

@@ -1,6 +1,10 @@
 // Graphics quality presets + auto-downgrade for weaker machines.
 // pixelRatio and culling apply live; antialias applies on next reload.
-const KEY = 'aldenvale_quality';
+// The localStorage key is per-game — register it at boot BEFORE the first
+// getQuality/getQualityName read, or two games sharing an origin (dev!)
+// will read each other's settings.
+let KEY = 'sindicate_quality';
+export function setQualityStorageKey(key) { KEY = key; }
 
 export const PRESETS = {
   low: {

package/src/core/renderer.js

@@ -0,0 +1,104 @@
+// Renderer: WebGPU with automatic WebGL2 fallback.
+// three's WebGPURenderer falls back to its WebGL2 backend when WebGPU
+// is unavailable, so one code path serves both.
+import * as THREE from 'three/webgpu';
+import { pass, mrt, output, velocity, uniform } from 'three/tsl';
+import { traa } from 'three/addons/tsl/display/TRAANode.js';
+import { getQuality, getQualityName } from './quality.js';
+
+// TRAA (temporal reprojection AA) is what makes the dithered LOD dissolve read
+// as a SMOOTH fade instead of a screen door: it jitters the camera sub-pixel
+// each frame and accumulates, so the dither's on/off stipple averages into a
+// gradient over time (the GTA / Unreal "dither + temporal AA" trick). It also
+// antialiases the whole image — so MSAA is turned OFF when TRAA runs, since the
+// two don't combine.
+// COST: TRAA adds a full-screen velocity MRT + a temporal-resolve pass — roughly
+// DOUBLES the per-frame GPU cost. Its ONLY unique job is smoothing the dithered LOD
+// dissolve (MSAA already antialiases edges, cheaper), so it's OFF by default now —
+// every tier runs the plain render path + MSAA and gets ~2× the fps. Opt in with
+// ?traa if the LOD stipple ever bothers you. (Was: on for Medium+High.)
+export function wantsTRAA() {
+  return new URLSearchParams(location.search).has('traa');
+}
+
+export async function createRenderer(container) {
+  // ?webgl forces the WebGL2 backend (also used when WebGPU is unavailable)
+  const forceWebGL = new URLSearchParams(location.search).has('webgl');
+  const q = getQuality();
+  const traaOn = wantsTRAA();
+  // MSAA must be disabled when TRAA is in use (TRAANode requirement); TRAA
+  // provides the anti-aliasing instead.
+  const renderer = new THREE.WebGPURenderer({ antialias: q.antialias && !traaOn, forceWebGL });
+  await renderer.init();
+
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio, q.pixelRatio));
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  // Shadow mapping retired at every preset (re-landed solo after the batch revert): the pass
+  // is a SECOND full scene render per frame — ~7.5ms CPU measured — and r184's node-based
+  // ShadowNode only honours per-LIGHT shadow.autoUpdate/needsUpdate, so the renderer-level
+  // throttle we ran for months was silently ignored (it rendered EVERY frame). Characters
+  // get instanced blob discs instead (world/blobShadows.js). Measured: 35 → 47.6fps.
+  renderer.shadowMap.enabled = false;
+  renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  renderer.toneMappingExposure = 1.05;
+  container.appendChild(renderer.domElement);
+
+  const backend = renderer.backend?.isWebGPUBackend ? 'WebGPU' : 'WebGL2';
+  console.log(`[renderer] backend: ${backend}${traaOn ? ' · TRAA' : ''}`);
+
+  window.addEventListener('resize', () => {
+    renderer.setSize(window.innerWidth, window.innerHeight);
+  });
+
+  return { renderer, backend };
+}
+
+// ---- SCREEN GRADE SLOT --------------------------------------------------------------
+// The whole screen look, as ONE game-supplied TSL Fn `grade([color, amount])` driven by
+// ONE uniform (post.gradeAmount 0..1). The grade must be mathematically identity at
+// amount 0 so it costs a single fullscreen mix when idle. It runs in LINEAR space
+// (outputColorTransform stays true: ACES tone map + sRGB apply AFTER it) — author
+// luminance recolours, not gamma-space curves, so the look survives the tone map.
+
+// Build the post-processing pipeline. The returned PostProcessing's .render() replaces
+// renderer.render(scene, camera) in the main loop, and it is now built ALWAYS — the Dead
+// Eye grade needs a full-screen pass, and swapping render paths at RUNTIME would compile a
+// fresh pipeline the first time Ctrl was pressed (a multi-second WebGPU freeze, exactly the
+// hazard this codebase documents). Building it at boot pays that cost on the loading screen.
+//
+// AA is NOT lost: PassNode takes its render target's sample count from renderer.samples,
+// which is 4 whenever the renderer was created with antialias — so MSAA still runs, inside
+// the pass. TRAA (?traa) still layers on top when asked for; the grade is the last link
+// either way.
+//
+// post.deadEyeAmount is the live uniform — deadeye.js writes .value each frame.
+export function createPostProcessing(renderer, scene, camera, { traa: traaOn = false, grade = null } = {}) {
+  const postProcessing = new THREE.PostProcessing(renderer);
+  const scenePass = pass(scene, camera);
+  let beauty;
+  if (traaOn) {
+    // TRAA needs a velocity (motion-vector) MRT so it can reproject the previous frame
+    scenePass.setMRT(mrt({ output, velocity }));
+    beauty = traa(
+      scenePass.getTextureNode('output'),
+      scenePass.getTextureNode('depth'),
+      scenePass.getTextureNode('velocity'),
+      camera,
+    );
+  } else {
+    beauty = scenePass.getTextureNode('output');
+  }
+  // outputColorTransform stays at its default (true): the chain renders linear and tone
+  // mapping + sRGB are applied once at the end. The grade (if any) is composed at BOOT —
+  // never swap outputNode at runtime, that compiles a fresh pipeline mid-play (a
+  // multi-second WebGPU freeze, exactly the hazard this codebase documents).
+  if (grade) {
+    const amount = uniform(0);
+    postProcessing.outputNode = grade(beauty, amount);
+    postProcessing.gradeAmount = amount;   // the game's one live dial (write .value)
+  } else {
+    postProcessing.outputNode = beauty;
+    postProcessing.gradeAmount = null;
+  }
+  return postProcessing;
+}