sindicate 0.1.0 → 0.2.0

package/docs/api/quality.md

@@ -0,0 +1,159 @@
+# quality
+
+Graphics quality presets plus an automatic downgrade path for weaker machines.
+
+Source: `src/core/quality.js`
+
+The module owns three things:
+
+1. **`PRESETS`** — the `low` / `medium` / `high` tier definitions.
+2. **Persistence** — the selected tier name is stored in `localStorage` under a configurable key (see `setQualityStorageKey`).
+3. **Runtime application** — `applyQuality` pushes everything that can change live onto a running game, and `AutoTuner` steps the tier down when measured FPS says the machine can't keep up.
+
+Note the split between live and reload-only settings: `pixelRatio` and culling values apply live; `antialias` only takes effect on the next reload (the renderer is created with it).
+
+## Exports
+
+### `PRESETS`
+
+```js
+export const PRESETS = { low: {...}, medium: {...}, high: {...} };
+```
+
+Each preset is a plain object with the following fields:
+
+| Field | Type | Controls |
+|---|---|---|
+| `label` | string | Display name for UI (`'Low'`, `'Medium'`, `'High'`). |
+| `pixelRatio` | number | Upper bound on render pixel ratio. `applyQuality` uses `Math.min(window.devicePixelRatio, pixelRatio)`. |
+| `antialias` | boolean | Renderer antialiasing. **Reload-only** — read at renderer creation, not applied live. |
+| `shadows` | boolean | Shadow mapping. Currently `false` on every tier — see gotchas. |
+| `shadowSize` | number | Shadow map resolution (512 / 1024 / 2048). Vestigial while `shadows` is false. |
+| `entityCull` | number | Distance in metres beyond which characters are hidden and frozen. |
+| `animHalfRate` | number | Distance beyond which characters animate every other frame. |
+| `animMidRate` | number | Distance beyond which characters animate every 3rd frame (every 4th near the cull edge). |
+| `maxLamps` | number | Maximum active lamp lights. |
+| `fogScale` | number | Fog distance multiplier; smaller pulls fog in, which means less overdraw. Forwarded to `world.sky.fogScale`. |
+| `cameraFar` | number | Camera far plane. `applyQuality` sets it and calls `updateProjectionMatrix()`. |
+
+Tier values as of now:
+
+| Field | low | medium | high |
+|---|---|---|---|
+| `pixelRatio` | 1 | 1.5 | 1.5 |
+| `antialias` | false | true | true |
+| `shadows` | false | false | false |
+| `entityCull` | 45 | 70 | 110 |
+| `animHalfRate` | 22 | 32 | 55 |
+| `animMidRate` | 33 | 48 | 80 |
+| `maxLamps` | 2 | 6 | 15 |
+| `fogScale` | 0.45 | 0.8 | 1 |
+| `cameraFar` | 200 | 420 | 800 |
+
+### `setQualityStorageKey(key)`
+
+```js
+export function setQualityStorageKey(key)
+```
+
+Replaces the `localStorage` key (default `'sindicate_quality'`) used to persist the tier name. **Call this at boot, before the first `getQuality`/`getQualityName` read.** The key must be per-game: two games served from the same origin — which is exactly the dev setup — will otherwise read and overwrite each other's quality setting.
+
+### `getQualityName()`
+
+```js
+export function getQualityName() // -> 'low' | 'medium' | 'high'
+```
+
+Reads the stored tier name from `localStorage`. Returns `'medium'` when nothing valid is stored — a safe default; the auto-tuner adjusts downward from there if needed.
+
+### `getQuality()`
+
+```js
+export function getQuality() // -> preset object
+```
+
+Convenience: `PRESETS[getQualityName()]`.
+
+### `setQualityName(name)`
+
+```js
+export function setQualityName(name)
+```
+
+Persists `name` to `localStorage`. Silently ignores names that aren't a key of `PRESETS`. Persistence only — does not touch the renderer; use `applyQuality` for that.
+
+### `applyQuality(game, name)`
+
+```js
+export function applyQuality(game, name)
+```
+
+Persists the tier (via `setQualityName`) and applies everything that can change live:
+
+- `renderer.setPixelRatio(Math.min(window.devicePixelRatio, q.pixelRatio))` and `renderer.setSize(innerWidth, innerHeight)`
+- `camera.far = q.cameraFar` + `camera.updateProjectionMatrix()`
+- `game.quality = q`, `game.qualityName = name`
+- `game.__traa = true` — a live A/B override only; TRAA now exists solely when opted in via `?traa` (`renderer.wantsTRAA`), and the default is the plain render path on every tier
+- if `game.world` exists: `world.quality = q`, and `world.sky.fogScale = q.fogScale` when a sky exists
+
+It deliberately does **not** touch shadows — see gotchas.
+
+### `AutoTuner`
+
+```js
+export class AutoTuner {
+  constructor(game)
+  update(dt)   // call once per frame with delta time in seconds
+}
+```
+
+Rolling FPS monitor that steps quality *down* (never up) when the machine can't keep up. Behavior of `update(dt)`:
+
+1. **Grace period** — the first ~6 seconds are ignored entirely, so loading hitches don't count.
+2. **5-second windows** — frames and elapsed time accumulate; every 5 seconds the average FPS for the window is computed and the accumulators reset.
+3. **Downgrade rule** — if the window averaged under 24 FPS *and* a lower tier exists (`high → medium → low`), a bad-window counter increments. Only after **two consecutive bad windows** does it call `applyQuality(game, nextLowerTier)` and show a toast via `game.ui?.toast(...)` ("Performance: graphics set to … (change in Esc menu)").
+4. **Settling** — any window at or above 24 FPS sets `done = true` and the tuner stops evaluating permanently ("stable — stop fiddling"). Note this also means a downgrade that fixes the frame rate ends tuning; it will not later re-upgrade.
+
+## Usage example
+
+```js
+import {
+  setQualityStorageKey, getQualityName, getQuality,
+  applyQuality, AutoTuner, PRESETS,
+} from './core/quality.js';
+
+// Boot — BEFORE any getQuality read, so this game doesn't share
+// settings with other games on the same origin during dev.
+setQualityStorageKey('mygame_quality');
+
+const name = getQualityName();          // 'medium' on first run
+const q = getQuality();
+const game = createGame({ antialias: q.antialias }); // reload-only setting
+
+applyQuality(game, name);               // live settings: pixelRatio, far plane, fog…
+
+const tuner = new AutoTuner(game);
+
+// In the frame loop:
+function tick(dt) {
+  tuner.update(dt);                     // may auto-drop to a lower tier
+  // ...
+}
+
+// Settings menu:
+for (const [key, preset] of Object.entries(PRESETS)) {
+  addMenuOption(preset.label, () => applyQuality(game, key));
+}
+```
+
+## Gotchas
+
+- **Register the storage key first.** `setQualityStorageKey` must run at boot before the first `getQuality`/`getQualityName` read. The key is per-game on purpose: two games sharing an origin (the normal dev situation) will read each other's settings under the default key.
+- **`antialias` is reload-only.** `pixelRatio` and culling apply live; antialiasing only changes on the next reload.
+- **Shadow mapping is retired on every tier** — and it was retired *again* after being re-landed solo. The shadow pass is a **second full scene render every frame** (~7.5 ms), and three.js r184 ignores the renderer-level throttle flags that would have amortized it. Characters get blob discs instead (`world/blobShadows.js`). Don't re-enable `shadows: true` without re-checking that cost.
+- **Never mutate shadow maps live.** Shadows are configured once at startup (`renderer.js` / `sky.js`). Mutating shadow state at runtime corrupts the WebGPU backend's shadow state and the sun renders everything as shadowed — the world goes dark at noon. This is why `applyQuality` doesn't touch shadows.
+- **High tier caps `pixelRatio` at 1.5, not 2.** Full retina cost ~1.5 ms/frame for an imperceptible gain at TRAA.
+- **`game.__traa` in `applyQuality` is a live A/B override only.** TRAA is opt-in via the `?traa` query flag (`renderer.wantsTRAA`); the default render path is plain on every tier.
+- **AutoTuner requires two consecutive bad 5-second windows before downgrading.** `applyQuality`'s `setPixelRatio` + `setSize` is itself a big hitch, so a single loading burst must not trigger a mid-play downgrade.
+- **AutoTuner is one-way and one-shot.** It only steps down, and the first stable window (≥ 24 FPS) sets `done` and stops it for good. It never restores a higher tier — users do that from the Esc menu (the toast tells them so).
+- **`getQualityName` falls back to `'medium'`**, not `'low'` — a deliberate safe default, since the auto-tuner will pull weak machines down from there.

package/package.json

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

package/src/core/anim.js

@@ -0,0 +1,184 @@
+// Character animation state machine over THREE.AnimationMixer,
+// with automatic retargeting per character rig.
+import * as THREE from 'three/webgpu';
+import { buildRetargetContext, retargetClip } from './retarget.js';
+// Per-clip timing (start/speed/end trims) and the clip->source-rig table are GAME
+// DATA, not engine code — a game registers them once at boot:
+//   setClipDefaults({ timing: CLIP_TIMING, rigs: CLIP_RIGS })
+// Unregistered, clips play untrimmed and every Animator needs explicit clipRigs.
+let CLIP_TIMING = {};
+let CLIP_RIGS = null;
+export function setClipDefaults({ timing = null, rigs = null } = {}) {
+  if (timing) CLIP_TIMING = timing;
+  if (rigs) CLIP_RIGS = rigs;
+}
+
+export class Animator {
+  get needsRetarget() { return true; }   // RawAnimator says no (see the bottom of this file)
+
+  // clipRigs: optional { clipName -> sourceRigKey }. A clip is authored against ONE
+  // skeleton's bind pose; clips from a foreign pack (different bind, same bone names)
+  // must retarget from THAT bind or they play folded in half. One ctx per source rig.
+  constructor(root, clips, clipRigs = null) {
+    this.mixer = new THREE.AnimationMixer(root);
+    this.root = root;
+    this.clipRigs = clipRigs ?? CLIP_RIGS;
+    this._ctxByRig = new Map();
+    // A RawAnimator's clips target the model's OWN skeleton, so it needs no retarget context —
+    // and building one THREW if no source rig had been registered yet. In the game that was
+    // invisible (the player registers the Synty rig long before a horse loads); anywhere else —
+    // a bench that only wants a horse — it was a hard crash on construction. Ask, don't assume.
+    this.ctx = this.needsRetarget ? this._ctxFor(null) : null;   // (other code reads .ctx)
+    this.actions = {};
+    this.current = null;
+    this.currentName = null;
+    this._overlay = null;
+    for (const [name, clip] of Object.entries(clips)) this.register(name, clip);
+
+    // completion callbacks are PER-ACTION (action._onceDone), not a shared slot: with a
+    // single slot, any play({once}) stomped the PREVIOUS one-shot's pending callback —
+    // e.g. a bow release during a dodge wiped the dodge's busy=false and soft-locked
+    // the player. Per-action, each one-shot can only ever replace its own callback.
+    this.mixer.addEventListener('finished', (e) => {
+      const cb = e.action._onceDone;
+      e.action._onceDone = null;
+      cb?.();
+    });
+  }
+
+  _ctxFor(rigKey) {
+    const k = rigKey ?? '__default';
+    let c = this._ctxByRig.get(k);
+    if (!c) { c = buildRetargetContext(this.root, rigKey); this._ctxByRig.set(k, c); }
+    return c;
+  }
+
+  register(name, clip) {
+    const ctx = this._ctxFor(this.clipRigs?.[name] ?? null);
+    const action = this.mixer.clipAction(retargetClip(clip, ctx));
+    this.actions[name] = action;
+  }
+
+  // Build a bone-masked copy of an already-registered clip (keeps only tracks whose
+  // bone passes keepFn). Used to split locomotion across body halves — e.g. legs
+  // from `walk` + torso/arms from `blockLoop` so you can walk with the guard up.
+  registerMasked(name, srcName, keepFn) {
+    const src = this.actions[srcName];
+    if (!src) return;
+    const clip = src.getClip().clone();
+    clip.tracks = clip.tracks.filter((t) => keepFn(t.name.replace(/\.(position|quaternion|scale)$/, '')));
+    clip.name = name;
+    this.actions[name] = this.mixer.clipAction(clip);
+  }
+
+  // A persistent overlay action that plays ALONGSIDE the base FSM action (play()
+  // only fades `this.current`, never the overlay). Non-overlapping tracks compose.
+  //
+  // WEIGHTS MUST SUM TO 1 ON EVERY BONE, ALWAYS. three's PropertyMixer fills any
+  // cumulative-weight deficit from the binding's ORIGINAL saved value — captured at the
+  // mixer's first activation, i.e. the model's BIND POSE. So a weight gap does not blend
+  // between two poses: it blends toward a T-POSE. A 0.12s overlay fadeOut racing a 0.18s
+  // base fadeIn dipped the sum to ~0.58 and flashed the arms 42% toward T-pose on every
+  // aim release. Hence: overlay swaps of the SAME mask crossfade (sum stays 1); starting
+  // or dropping an overlay is INSTANT, and the caller switches the base to/from the
+  // complementary mask in the SAME frame. A hard pose cut is survivable; a T-pose is not.
+  setOverlay(name, opts = {}) {
+    const next = name ? this.actions[name] : null;
+    const prev = this._overlay;
+    if (prev === next && !opts.restart) return next;
+    if (next) {
+      next.reset();                                  // reset() calls stopFading() — so it MUST come first
+      if (opts.once) { next.setLoop(THREE.LoopOnce, 1); next.clampWhenFinished = true; }
+      else next.setLoop(THREE.LoopRepeat, Infinity);
+      next.enabled = true;
+      next.setEffectiveWeight(1);
+      next.play();
+      // same-mask swap (aim -> fire -> aim): crossFadeFrom keeps the pair summing to 1
+      if (prev && prev !== next && opts.fade) next.crossFadeFrom(prev, opts.fade, false);
+      else if (prev && prev !== next) { prev.stop(); prev.setEffectiveWeight(0); }
+    } else if (prev) {
+      // DROPPING the overlay. stop() zeroes its weight instantly — but the base is still the
+      // LOWER-only mask for a beat, so the upper body is left with ZERO cumulative weight and
+      // three fills it from the bind pose: a ~0.2s T-POSE flash at the end of every one-shot.
+      // Instead fade it out over EXACTLY the duration the caller fades its full-body base in
+      // (opts.fade). Upper: overlay(1-t) + base(t) = 1. Lower: lowerBase(1-t) + base(t) = 1.
+      const d = opts.fade ?? 0;
+      if (d > 0) prev.fadeOut(d);
+      else { prev.stop(); prev.setEffectiveWeight(0); }
+    }
+    this._overlay = next;
+    return next;
+  }
+
+  // play(name) — loop. play(name, {once, fade, timeScale, onDone}) — one-shot.
+  // startFrac (0..1) skips into the clip past wind-up. CLIP_TIMING (tuned via
+  // /anim.html) supplies per-clip start/speed DEFAULTS; explicit opts override.
+  play(name, opts = {}) {
+    const action = this.actions[name];
+    if (!action) return null;
+    const tm = CLIP_TIMING[name] || {};
+    const once = opts.once ?? false;
+    const fade = opts.fade ?? 0.18;
+    const restart = opts.restart ?? false;
+    const onDone = opts.onDone ?? null;
+    const startFrac = opts.startFrac ?? tm.start ?? 0;
+    const timeScale = opts.timeScale ?? tm.speed ?? 1;
+    if (this.currentName === name && !restart && !once) return action;
+
+    action.reset();
+    if (startFrac > 0) action.time = action.getClip().duration * startFrac;
+    action.timeScale = timeScale;
+    if (once) {
+      action.setLoop(THREE.LoopOnce, 1);
+      action.clampWhenFinished = true;
+      action._onceDone = onDone;
+    } else {
+      action.setLoop(THREE.LoopRepeat, Infinity);
+      action._onceDone = null; // re-played as a loop: drop any stale one-shot callback
+    }
+    action.fadeIn(fade).play();
+    if (this.current && this.current !== action) this.current.fadeOut(fade);
+    this.current = action;
+    this.currentName = name;
+    this._curTiming = tm;       // for end-trim handling in update()
+    this._curOnce = once;
+    return action;
+  }
+
+  stopAll() {
+    this.mixer.stopAllAction();
+    this.current = null;
+    this.currentName = null;
+    this._overlay = null;
+  }
+
+  update(dt) {
+    this.mixer.update(dt);
+    // CLIP_TIMING end-trim: cut the tail of the clip. One-shots clamp at `end`
+    // (and fire onDone there); loops cycle back to `start`.
+    const a = this.current, tm = this._curTiming;
+    if (a && tm && tm.end != null && tm.end < 1) {
+      const dur = a.getClip().duration;
+      if (a.time >= tm.end * dur) {
+        if (this._curOnce) {
+          a.time = tm.end * dur;
+          a.paused = true;
+          const cb = a._onceDone; a._onceDone = null; cb?.();
+        } else {
+          a.time = (tm.start ?? 0) * dur;
+        }
+      }
+    }
+  }
+}
+
+// Self-animated rigs (PolyPerfect creatures, like the horse): the clips target the
+// model's OWN skeleton, so registration skips the Synty retarget entirely — everything
+// else (play/overlay/once-callbacks/end-trim) behaves identically.
+export class RawAnimator extends Animator {
+  get needsRetarget() { return false; }   // its clips already speak this skeleton's language
+
+  register(name, clip) {
+    this.actions[name] = this.mixer.clipAction(clip);
+  }
+}