sindicate 0.2.0 → 0.4.0

package/docs/contracts/time-feel.md

@@ -0,0 +1,52 @@
+# Contract: time & feel
+
+**Status:** draft (step 3 — extraction from western main.js in progress). Field names final, wiring lands with the Engine base.
+
+## The two clocks
+
+Every frame has TWO dt values, and using the wrong one is a shipped-bug class:
+
+- **`rawDt`** — wall-clock frame time, never scaled. Consumers: camera look, aim IK (aiming stays crisp inside slow-mo), the fps meter (scaled dt inflates it during hit-stop), and any *meter that must drain in real time* (a slow-mo meter timed in slow-mo drains 3× slower the instant it activates — the engine's slow-mo system runs on rawDt for exactly this reason).
+- **`dt`** — the world dt: `rawDt × Π(timeScale contributions)`, clamped at 0.1s. Drives mixers, physics, AI, projectiles, VFX, game-time timers.
+
+## timeScale contributions (the multiplier chain)
+
+Systems never write loop fields. They register contributors; the engine multiplies them in registration order each frame *after* the pre-scale phase:
+
+```js
+engine.time.addTimeScale(() => (hitstopActive ? 0.12 : 1))   // combat's hit-stop
+engine.time.addTimeScale(() => slowMo.scale)                  // Dead-Eye-style slow-mo
+```
+
+- Contributors run every frame; return 1 when inactive.
+- Systems that *decide* the frame's scale (e.g. slow-mo reading its meter) update in the **pre-scale phase** on rawDt, so the scale they return lands on THIS frame, not the next.
+- `engine.time.worldDtScale` exposes the product (read-only; the dev drive-bus asserts on it).
+
+## Game-time timers
+
+`engine.time.after(seconds, fn)` — one-shots that tick on **world dt inside the unpaused guard**: they freeze with the pause menu (a pause can never eat a death-beat landing) and stretch under slow-mo. Not setTimeout. Errors in `fn` are caught and logged, never thrown into the loop.
+
+`engine.time.playSeconds` — accumulated unpaused world time (save-slot playtime readout).
+
+## Feel write APIs
+
+- `engine.feel.hitstop(seconds)` — refreshes the hit-stop window (max with current, never additive stacking).
+- `engine.feel.shake(strength)` — camera shake impulse, consumed by the camera phase.
+
+## Frame phases (execution order is the contract)
+
+1. **frame-start** — clock advance, input `pollGamepad(ui.anyPanelOpen)`.
+2. **pre-scale** *(rawDt)* — systems that produce this frame's timeScale.
+3. **scale** — multiplier chain → world dt.
+4. **ui-modal** — global keys, panel nav, modal key routing (see ui contract). May consume input.
+5. **sim** *(world dt, skipped when paused)* — timers, world update, then game-registered sim hooks in registration order.
+6. **actors** — player update (writes the follow camera), then game actor hooks. Runs even paused (movement is pause-gated inside the player; a hand-ticked NPC keeps breathing during dialogue).
+7. **camera-overrides** — ordered, **last writer wins**, after everything that can move a platform or a vehicle seat: dialogue two-shot → scripted scenes → cinematics (each registered with an order key). The engine builds the culling frustum AFTER this phase, once, when unpaused (`engine.render.frustum`; null while a stale frustum would mis-cull — see render contract).
+8. **late-sim** *(unpaused)* — combat resolution, missions, crowd systems, ambient ticks.
+9. **render** — exposure write-gating, `renderFrame()` (the ONE render path shared by boot warm-up and the loop), freeze-profiler phase stamps.
+
+The pause predicate is supplied by the ui facet (`ui.anyPanelOpen`) and holds phases 5 and 8; 6, 7 and 9 always run.
+
+## Why this shape
+
+Western's main.js encoded all of the above as a single 400-line closure with ordering comments ("It runs HERE — not one line earlier"). The phases make the ordering *structural*: a system registered in the wrong phase is a visible design error, not a subtle frame-lag bug discovered in play.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.2.0",
+  "version": "0.4.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/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/index.js

@@ -10,6 +10,7 @@
 // their proven originals on purpose.
 
 // core — rendering, assets, animation, retargeting, input, quality, decals, utils
+export { Engine } from './core/engine.js';
 export { createRenderer, createPostProcessing, wantsTRAA } from './core/renderer.js';
 export * from './core/assets.js';
 export * from './core/anim.js';
@@ -19,13 +20,24 @@ export * from './core/utils.js';
 export { PRESETS, getQuality, getQualityName, setQualityName, applyQuality, AutoTuner } from './core/quality.js';
 export { DecalField } from './core/decalField.js';
 
-// world — collision (sync + worker BVH), water materials, grass, wind, shared weather uniforms
+// world — streaming tiles, scatter/LOD, collision, sky/weather stack, lighting, ground dressing
 export * from './world/collision.js';
+export * from './world/tileManager.js';
+export * from './world/scatter.js';
+export * from './world/sky.js';
+export * from './world/weather.js';
+export * from './world/clouds.js';
 export * from './world/water.js';
 export * from './world/grass.js';
 export * from './world/wind.js';
 export * from './world/weatherUniforms.js';
 export * from './world/waterNoise.js';
+export * from './world/flora.js';
+export * from './world/lampField.js';
+export * from './world/lampGlow.js';
+export * from './world/blobShadows.js';
+export * from './world/walkHumps.js';
+export * from './world/footprints.js';
 
 // systems — pooled debris shatter
 export * from './systems/shatter.js';

package/src/systems/aim.js

@@ -0,0 +1,114 @@
+// WHERE THE ROUND ACTUALLY GOES — the one copy of the maths.
+//
+// This module exists because the same geometry was being written twice, in two files, by two hands,
+// and the two copies disagreed. The reticle said one thing (player.js), the bullet did another
+// (combat.js), and the argument between them was invisible: the green light came on, the gun went
+// off, and the man did not fall. Now there is one body model and one intersection test, and the
+// aim, the reticle and the round are all reading from it. /shoottest.html fires the same functions
+// at a measured range, so what you tune there is what the game does.
+//
+// TWO FACTS THIS ENCODES, both learned the hard way:
+//
+// 1. A MAN IS A CAPSULE, NOT A BALL AT HIS STERNUM. The first version tested a sphere at chest
+//    height. A crosshair resting on his HEAD is 0.68m from that point — outside the tolerance — so
+//    the aim found nobody, converged on a default distance far behind him, and the round went under
+//    his chin. Headshots weren't failing to register; they were never headshots.
+//
+// 2. THE CROSSHAIR IS THE CAMERA'S RAY, AND THE BULLET LEAVES THE GUN. Those are two different
+//    lines. The camera sits over the player's shoulder — measured 4.45m behind and 2m above the
+//    muzzle — so firing "along the camera direction" from the muzzle produces a shot PARALLEL to
+//    the crosshair that never meets it, landing a fixed step low at every range. The round must be
+//    aimed AT the point the crosshair is over, not merely in the same direction.
+import * as THREE from 'three/webgpu';
+
+// The body, as the guns see it. Feet-relative: `position` is on the ground, by the convention every
+// entity in this game already follows (combat.js's HEAD_Y test depends on it, and the coach
+// publishes the datum a seated man's feet WOULD be on so the same numbers work on him).
+export const BODY = {
+  lo: 0.25,     // ankles
+  hi: 1.80,     // crown
+  r: 0.42,      // half a man's shoulders, and generous by a hair — a western is about hitting people
+  head: 1.50,   // above this and it went in over the collar
+};
+// The AIM is a shade more forgiving than the bullet: the crosshair should never light green on a
+// shot that misses, but it may stay dark on one that grazes. Err that way round.
+export const AIM_R = 0.50;
+
+const _v = new THREE.Vector3();
+
+// Where a ray crosses a standing body. Returns the distance along the ray, or null.
+// The body's axis is VERTICAL, so this is a 2D problem in x/z with the height riding along the ray
+// — no general 3D segment-segment solve, and no allocation.
+export function rayCapsule(ox, oy, oz, dx, dy, dz, feet, radius = BODY.r) {
+  if (!feet || !Number.isFinite(feet.x) || !Number.isFinite(feet.y) || !Number.isFinite(feet.z)) return null;
+  const ax = ox - feet.x, az = oz - feet.z;
+  const h = dx * dx + dz * dz;
+  const t = h > 1e-9 ? -(ax * dx + az * dz) / h : 0;
+  if (!(t > 0)) return null;                                   // behind us (NaN-safe: !(NaN > 0) is true)
+  const hx = ax + dx * t, hz = az + dz * t;
+  if (!(hx * hx + hz * hz <= radius * radius)) return null;    // the ray goes past him
+  const y = oy + dy * t - feet.y;                              // where it crosses, above his feet
+  if (!(y >= BODY.lo && y <= BODY.hi)) return null;            // over his head, or into the dirt
+  return { t, hitY: y };
+}
+
+// The nearest body a ray crosses. `bodies` is any iterable of things with .position (at the feet)
+// and .alive. Used by the reticle AND by the aim — so the light and the lead agree by construction.
+//
+// `e.noTarget` (a child, npc.js) is invisible to this function, and BECAUSE this one function
+// serves both the light and the lead, that single word is what makes the reticle refuse to sit on
+// a child AND the round refuse to converge on one. There is no second copy of this to forget.
+export function nearestBody(origin, dir, bodies, { skip = null, maxT = 600, radius = AIM_R } = {}) {
+  let best = null, bestT = Infinity;
+  for (const e of bodies) {
+    if (!e || e === skip || e.alive === false || e.noTarget) continue;
+    const hit = rayCapsule(origin.x, origin.y, origin.z, dir.x, dir.y, dir.z, e.position, radius);
+    if (!hit || hit.t >= bestT || hit.t > maxT) continue;
+    best = e; bestT = hit.t;
+  }
+  return best ? { e: best, t: bestT, } : null;
+}
+
+// THE POINT THE CROSSHAIR IS OVER. A body if there is one, otherwise a long way down the ray.
+// `fallback` matters more than it looks: it is the distance the shot converges at when you are
+// aiming at nothing, and a shot fired at a target 25m away while converging on 140m still carries
+// most of its parallax error. So: converge on the man when there is a man.
+export function aimPoint(out, camPos, dir, bodies, { skip = null, fallback = 140 } = {}) {
+  const hit = nearestBody(camPos, dir, bodies, { skip });
+  const t = hit && Number.isFinite(hit.t) ? hit.t : fallback;
+  return out.copy(camPos).addScaledVector(dir, t);
+}
+
+// The direction a round leaves the gun on: from the MUZZLE, AT the aim point. Optionally scattered.
+// The jitter goes in the plane ACROSS the shot, so `spread` radians means that much off the line
+// you actually took, whichever way you happen to be facing.
+export function shotDir(out, muzzle, aim, spread = 0, rnd = Math.random) {
+  out.copy(aim).sub(muzzle).normalize();
+  if (spread > 0) {
+    _v.set(0, 1, 0).cross(out).normalize();                     // right, across the shot
+    const up = _v.clone().cross(out).normalize();               // and up, across it the other way
+    out.addScaledVector(_v, (rnd() - 0.5) * 2 * spread)
+      .addScaledVector(up, (rnd() - 0.5) * 2 * spread)
+      .normalize();
+  }
+  return out;
+}
+
+// Where a bullet's FLIGHT SEGMENT (p1→p2, one frame of travel) crosses a body. Returns the height
+// above his feet, or null. Segment-based on purpose: a round does 90m/s and we step at 1/60s, so it
+// jumps 1.5 METRES between frames — a point test against a 1m ball can step clean over a man at
+// range (that is the "I shot him and nothing happened" bug), and lands at the ball's near edge when
+// it doesn't (that is the "my headshot did 25 damage" bug).
+export function segmentCapsule(p1, p2, feet, radius = BODY.r) {
+  if (!feet || !Number.isFinite(feet.x)) return null;
+  const dx = p2.x - p1.x, dy = p2.y - p1.y, dz = p2.z - p1.z;
+  const ax = p1.x - feet.x, az = p1.z - feet.z;
+  const a = dx * dx + dz * dz;
+  let t = a > 1e-9 ? -(ax * dx + az * dz) / a : 0;
+  t = t < 0 ? 0 : t > 1 ? 1 : t;                                 // stay on THIS frame's step
+  const hx = ax + dx * t, hz = az + dz * t;
+  if (!(hx * hx + hz * hz <= radius * radius)) return null;
+  const y = p1.y + dy * t - feet.y;
+  if (!(y >= BODY.lo - 0.15 && y <= BODY.hi + 0.15)) return null;
+  return { hitY: y, at: t };
+}

package/src/systems/campfire.js

@@ -0,0 +1,150 @@
+// A lit campsite fire the player can REST at (walk up → E → sit → sleep → skip 5h + heal → wake).
+// The prop is the real Synty campfire (SM_Prop_Campfire_01, frontier pack); the flame + smoke are
+// the Synty-style emissive-orb VFX ported from Fable's torchfire.js. Everything is created ONCE at
+// boot and resident for life (PERF LAW: no scene churn mid-play) — the light is toggled by INTENSITY
+// only, never .visible (toggling a light's presence recompiles every lit material on WebGPU).
+//
+// The sit/sleep sequence itself lives in Game.startRest() (main.js) so it can reach the sky clock +
+// player health + the fade overlay; this file owns the fire object and its look. Prototyped whole in
+// /campfire.html (src/tools/campfire.js) — see [[survival-animset-retarget]].
+import * as THREE from 'three/webgpu';
+import { attribute } from 'three/tsl';
+import { loadGLB, loadTexture } from '../core/assets.js';
+
+const FIRE_STOPS = [
+  { t: 0.00, c: new THREE.Color(1.00, 0.97, 0.80) },
+  { t: 0.30, c: new THREE.Color(1.00, 0.68, 0.20) },
+  { t: 0.70, c: new THREE.Color(0.96, 0.30, 0.06) },
+  { t: 1.00, c: new THREE.Color(0.72, 0.12, 0.02) },
+];
+const _m = new THREE.Matrix4(), _q = new THREE.Quaternion(), _p = new THREE.Vector3(), _s = new THREE.Vector3(), _c = new THREE.Color();
+function fireColor(t, out) {
+  for (let i = 1; i < FIRE_STOPS.length; i++) {
+    if (t <= FIRE_STOPS[i].t) { const a = FIRE_STOPS[i - 1], b = FIRE_STOPS[i]; return out.lerpColors(a.c, b.c, (t - a.t) / (b.t - a.t)); }
+  }
+  return out.copy(FIRE_STOPS[FIRE_STOPS.length - 1].c);
+}
+
+class CampFlame {
+  constructor(count = 46, size = 0.16) {
+    this.size = size; this._pool = [];
+    const geo = new THREE.IcosahedronGeometry(1, 0);
+    const mat = new THREE.MeshBasicNodeMaterial({ toneMapped: false });
+    this.mesh = new THREE.InstancedMesh(geo, mat, count);
+    this.mesh.instanceColor = new THREE.InstancedBufferAttribute(new Float32Array(count * 3), 3);
+    this.mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    this.mesh.frustumCulled = false;
+    for (let i = 0; i < count; i++) { const f = this._spawn({}); f.age = Math.random() * f.life; this._pool.push(f); }
+    this.update(0);
+  }
+  _spawn(f) {
+    const z = this.size;
+    f.age = 0; f.life = 0.5 + Math.random() * 0.4;
+    f.x = (Math.random() - 0.5) * z * 2.4; f.z = (Math.random() - 0.5) * z * 2.4;
+    f.vy = z * (2.0 + Math.random() * 1.4); f.sz = z * (0.5 + Math.random() * 0.45);
+    return f;
+  }
+  update(dt, bright = 1) {
+    for (let i = 0; i < this._pool.length; i++) {
+      const f = this._pool[i]; f.age += dt;
+      if (f.age >= f.life) this._spawn(f);
+      const t = f.age / f.life;
+      _p.set(f.x * (1 - t * 0.6), t * f.vy, f.z * (1 - t * 0.6));
+      _s.setScalar(Math.max(0.001, f.sz * Math.sin(Math.min(1, t * 1.3) * Math.PI)));
+      this.mesh.setMatrixAt(i, _m.compose(_p, _q, _s));
+      this.mesh.setColorAt(i, fireColor(t, _c).multiplyScalar(bright));
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+    if (this.mesh.instanceColor) this.mesh.instanceColor.needsUpdate = true;
+  }
+}
+
+class CampSmoke {
+  constructor(count = 120, size = 0.16) {
+    this.size = size; this._pool = [];
+    const geo = new THREE.IcosahedronGeometry(1, 0);
+    const mat = new THREE.MeshBasicNodeMaterial({ transparent: true, depthWrite: false, toneMapped: false });
+    this.alpha = new THREE.InstancedBufferAttribute(new Float32Array(count), 1);
+    geo.setAttribute('iAlpha', this.alpha);
+    mat.opacityNode = attribute('iAlpha', 'float');
+    this.mesh = new THREE.InstancedMesh(geo, mat, count);
+    this.mesh.instanceColor = new THREE.InstancedBufferAttribute(new Float32Array(count * 3), 3);
+    this.mesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
+    this.mesh.frustumCulled = false; this.mesh.renderOrder = 3;
+    for (let i = 0; i < count; i++) { const s = this._spawn({}); s.age = s.life; this._pool.push(s); this.alpha.array[i] = 0; }  // start empty
+    this.update(0, 0);
+  }
+  _spawn(s) {
+    const z = this.size;
+    s.age = 0; s.life = 2.2 + Math.random() * 1.4;
+    s.x = (Math.random() - 0.5) * z * 0.5; s.z = (Math.random() - 0.5) * z * 0.5;
+    s.vy = z * (5.5 + Math.random() * 3.5); s.drift = (Math.random() - 0.5) * z * 1.2;
+    s.sz0 = z * 0.5; s.sz1 = z * (1.6 + Math.random() * 0.5); s.base = z * 4.0;   // start above the flame tip
+    return s;
+  }
+  // emit = fire level (respawn rate); doused -> the column clears upward, no downward shrink.
+  update(dt, emit = 1, bright = 1) {
+    for (let i = 0; i < this._pool.length; i++) {
+      const s = this._pool[i]; s.age += dt;
+      if (s.age >= s.life) {
+        if (Math.random() < emit) this._spawn(s);
+        else { this.alpha.array[i] = 0; continue; }
+      }
+      const t = s.age / s.life;
+      _p.set(s.x + s.drift * t, s.base + t * s.vy, s.z + s.drift * t * 0.6);
+      _s.setScalar(Math.max(0.001, s.sz0 + (s.sz1 - s.sz0) * t));
+      this.mesh.setMatrixAt(i, _m.compose(_p, _q, _s));
+      this.alpha.array[i] = Math.max(0, Math.min(t * 6, (1 - t) * 10, 1)) * 0.34;
+      const g = (0.4 + t * 0.06) * bright;
+      this.mesh.setColorAt(i, _c.setRGB(g * 1.05, g, g * 0.97));
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+    this.alpha.needsUpdate = true;
+    if (this.mesh.instanceColor) this.mesh.instanceColor.needsUpdate = true;
+  }
+}
+
+export class Campfire {
+  // starts UNLIT — just the wood pile. The player's rest lights it (Game.startRest) and douses it on
+  // leaving; `level` eases toward `lit` so it catches + dies out over a few seconds.
+  constructor(game, x, z) { this.game = game; this.x = x; this.z = z; this.group = new THREE.Group(); this.t = 0; this.lit = false; this.level = 0; }
+  light() { this.lit = true; }
+  douse() { this.lit = false; }
+
+  async build() {
+    const g = this.game;
+    const y = g.world.groundAt?.(this.x, this.z) ?? 0;
+    this.group.position.set(this.x, y, this.z);
+    // real Synty prop (GLB is in METRES ~3.3m -> 0.3 ≈ 1m; its shipped map is a 1x1 stub, so apply the atlas)
+    try {
+      const prop = (await loadGLB('/assets/frontier/SM_Prop_Campfire_01.glb')).clone();
+      prop.scale.setScalar(0.3);
+      const atlas = await loadTexture('/assets/textures/atlas_westernfrontier.png', { flipY: false });
+      prop.traverse((o) => { if (o.isMesh) { o.castShadow = false; o.frustumCulled = false; if (o.material) { o.material.map = atlas; o.material.color?.setScalar(1); o.material.needsUpdate = true; } } });
+      this.group.add(prop);
+    } catch (e) { console.warn('[campfire] prop failed', e); }
+    this.flame = new CampFlame(); this.flame.mesh.position.y = 0.04; this.group.add(this.flame.mesh);
+    this.smoke = new CampSmoke(); this.group.add(this.smoke.mesh);
+    // warm light added once, toggled by intensity only (never .visible — that recompiles lit materials).
+    // NOTE: named warmLight, NOT `light` — that would clobber the light() method above.
+    this.warmLight = new THREE.PointLight(0xff7a2a, 0, 16, 2); this.warmLight.position.set(0, 0.35, 0); this.group.add(this.warmLight);
+    g.scene.add(this.group);
+    // walk-up-and-press-E REST prompt (same registry as doors/coach/NPCs)
+    g.interactables.push({ x: this.x, z: this.z, r: 2.6, label: 'E — Rest at the campfire', action: () => g.startRest(this) });
+  }
+
+  update(dt) {
+    if (!this.flame) return;
+    this.t += dt;
+    this.level += ((this.lit ? 1 : 0) - this.level) * Math.min(1, dt * (this.lit ? 0.5 : 2.2));   // catch slow, die quicker
+    const lvl = this.level;
+    const flick = 0.75 + 0.25 * Math.sin(this.t * 24) * Math.sin(this.t * 13.3 + 1.7);
+    this.warmLight.intensity = lvl * (7 + flick * 4);
+    this.flame.mesh.scale.setScalar(lvl < 0.02 ? 0 : 0.12 + 0.88 * lvl);   // fully gone when unlit (else a tiny orb lingers)
+    // keep the unlit-tone-mapped flame a constant brightness through the night-exposure dimmer (torch trick)
+    const exp = this.game.renderer?.toneMappingExposure ?? 1;
+    const bright = Math.min(10, Math.max(1, 1 / exp));
+    this.flame.update(dt, bright);
+    this.smoke.update(dt, lvl, bright);
+  }
+}