sindicate 0.1.0 → 0.4.0

package/src/core/retarget.js

@@ -0,0 +1,282 @@
+// Retargeting from the ANIMATION-pack rig (PolygonSyntyCharacter:
+// Root/Hips/Spine_01/Shoulder_L…) onto Synty POLYGON character rigs.
+//
+// The rigs share structure and proportions, but bone names differ
+// (Pelvis/spine_01/UpperArm_L…) and the bone-local frames differ
+// (Unreal-style axis convention). We retarget with bind-pose deltas:
+//
+//   Δb       = Wb_animBind⁻¹ · Wb_targetBind        (world-rotation delta)
+//   q'b(t)   = Δparent(b)⁻¹ · qb(t) · Δb            (per quaternion key)
+//
+// which makes the target's world deformation match the source clip
+// exactly, regardless of local frame conventions.
+import * as THREE from 'three/webgpu';
+
+// ANIMATION rig bone -> POLYGON rig bone. Identity entries are implied
+// for rigs (e.g. Knights pack) that reuse the source names.
+const ANIM_TO_POLYGON = {
+  Hips: 'Pelvis',
+  Spine_01: 'spine_01', Spine_02: 'spine_02', Spine_03: 'spine_03',
+  Neck: 'neck_01', Head: 'head', Eyes: 'eyes', Eyebrows: 'eyebrows',
+  Clavicle_L: 'clavicle_l', Shoulder_L: 'UpperArm_L', Elbow_L: 'lowerarm_l', Hand_L: 'Hand_L',
+  Clavicle_R: 'clavicle_r', Shoulder_R: 'UpperArm_R', Elbow_R: 'lowerarm_r', Hand_R: 'Hand_R',
+  Thumb_01: 'thumb_01_l', Thumb_02: 'thumb_02_l', Thumb_03: 'thumb_03_l',
+  IndexFinger_01: 'indexFinger_01_l', IndexFinger_02: 'indexFinger_02_l',
+  IndexFinger_03: 'indexFinger_03_l', IndexFinger_04: 'indexFinger_04_l',
+  Finger_01: 'finger_01_l', Finger_02: 'finger_02_l', Finger_03: 'finger_03_l', Finger_04: 'finger_04_l',
+  Thumb_01_1: 'thumb_01_r', Thumb_02_1: 'thumb_02_r', Thumb_03_1: 'thumb_03_r',
+  IndexFinger_01_1: 'indexFinger_01_r', IndexFinger_02_1: 'indexFinger_02_r',
+  IndexFinger_03_1: 'indexFinger_03_r', IndexFinger_04_1: 'indexFinger_04_r',
+  Finger_01_1: 'finger_01_r', Finger_02_1: 'finger_02_r', Finger_03_1: 'finger_03_r', Finger_04_1: 'finger_04_r',
+  UpperLeg_L: 'Thigh_L', LowerLeg_L: 'calf_l', Ankle_L: 'Foot_L', Ball_L: 'ball_l', Toes_L: 'toes_l',
+  UpperLeg_R: 'Thigh_R', LowerLeg_R: 'calf_r', Ankle_R: 'Foot_R', Ball_R: 'ball_r', Toes_R: 'toes_r',
+};
+
+// Named SOURCE RIGS. Clips are authored against a specific skeleton's BIND POSE, and a clip
+// only plays correctly on a rig with that same bind. Unity hides this — its Humanoid/Mecanim
+// avatar retargets muscle-space, so any humanoid clip plays on any humanoid rig. three.js has
+// no such layer: it applies raw bone quaternions. So a pack whose bind differs (the Wild West
+// gunslinger pack's PreviewRig is ~90-107 deg off on Hips/Spine vs the Synty anim rig, despite
+// IDENTICAL bone names) must declare its own source bind, or it plays as a folded-in-half mess.
+// One global source bind was the bug: every clip was assumed to be authored on the Synty rig.
+const sourceRigs = new Map(); // key -> { bind, map }
+let defaultRigKey = null;
+
+// Malbers "Human" rig -> the ANIMATION rig. Used for the climb/ladder clips, which are authored on the
+// Malbers skeleton, not the Synty animation rig. We map onto ANIM-rig names (Hips/Spine_01/Shoulder_L…);
+// the existing ANIM_TO_POLYGON step in mapName() then carries it onto polygon characters automatically, so
+// ONE map serves both anim- and polygon-rigged targets. NOTE: FBXLoader sanitizes spaces->underscores, so
+// the bones load as R_L_Clavicle (not "R_L Clavicle").
+export const MALBERS_TO_ANIM = {
+  R_CG: 'Root',                                            // Malbers root (above pelvis) -> anim Root; without it the pelvis loses parent compensation and the body pitches 90°
+  R_Pelvis: 'Hips', R_Spine: 'Spine_01', R_Spine1: 'Spine_02', R_Spine2: 'Spine_03',
+  R_Neck: 'Neck', R_Head: 'Head',
+  R_L_Clavicle: 'Clavicle_L', R_L_UpperArm: 'Shoulder_L', R_L_Forearm: 'Elbow_L', R_L_Hand: 'Hand_L',
+  R_R_Clavicle: 'Clavicle_R', R_R_UpperArm: 'Shoulder_R', R_R_Forearm: 'Elbow_R', R_R_Hand: 'Hand_R',
+  R_L_Thigh: 'UpperLeg_L', R_L_Calf: 'LowerLeg_L', R_L_Foot: 'Ankle_L',
+  R_R_Thigh: 'UpperLeg_R', R_R_Calf: 'LowerLeg_R', R_R_Foot: 'Ankle_R',
+};
+
+const _bindP = new THREE.Vector3(), _bindS = new THREE.Vector3();
+const _posV = new THREE.Vector3();
+
+function captureBind(root) {
+  root.updateMatrixWorld(true);
+  // TRUE bind-pose world rotations from the SkinnedMesh inverse-bind matrices (boneInverses[i]⁻¹
+  // IS the bone's world matrix at bind), which are pose-independent ground truth. Reading the
+  // live getWorldQuaternion() instead silently poisons every delta if the model is captured
+  // mid-animation — e.g. a shared master that got posed before this clone (which is exactly why
+  // the SK_Chr_Soldier_* guards held their arms out: their arm deltas were ~30° off true bind).
+  const bindQ = new Map(); // bone name -> world quaternion at bind
+  root.traverse((o) => {
+    if (!o.isSkinnedMesh || !o.skeleton) return;
+    const { bones, boneInverses } = o.skeleton;
+    for (let i = 0; i < bones.length; i++) {
+      const b = bones[i];
+      if (!b || !boneInverses[i] || bindQ.has(b.name)) continue;
+      const q = new THREE.Quaternion();
+      boneInverses[i].clone().invert().decompose(_bindP, q, _bindS);
+      bindQ.set(b.name, q);
+    }
+  });
+  // OBJECT-CHAIN ROTATION. boneInverses are expressed in the SKELETON's container space —
+  // NOT world. FBXLoader parks the Z-up->Y-up conversion on the container Object3Ds for some
+  // packs (the Wild West gunslinger rig: root Group -90deg X, PreviewRig Group -180deg Z) and
+  // on a Root BONE for others (Synty: containers identity). Comparing a bind captured in one
+  // frame against a bind captured in the other tilts every delta by that rotation — the
+  // character animates lying on his back. Fold the container's world rotation in so both rigs
+  // are captured in the MODEL-ROOT frame. Identity for Synty-family rigs (no behaviour change);
+  // it is a static transform, so this stays safe for posed shared masters (unlike reading
+  // getWorldQuaternion off a live bone).
+  root.updateMatrixWorld(true);
+  let firstBone = null;
+  root.traverse((o) => { if (!firstBone && o.isBone) firstBone = o; });
+  let rootBone = firstBone;
+  while (rootBone?.parent?.isBone) rootBone = rootBone.parent;
+  const container = rootBone?.parent ?? null;
+  // ...MEASURED RELATIVE TO `root`, NOT TO THE WORLD. getWorldQuaternion() also picks up
+  // wherever the character happens to be STANDING — and a Character's model hangs under a root
+  // Group that is rotated to its HEADING. So the bind captured for a townsman facing south had
+  // his heading folded into it, and every delta computed from it was off by exactly that angle:
+  // measured across the town, chainQ came out at precisely |heading| for every NPC (Silas at
+  // heading π captured a 180° "bind" and stood with his arms straight up; the player and the
+  // barkeep face heading 0, which is the only reason they ever looked right). The container's
+  // rotation is only meaningful in the MODEL-ROOT frame — which is what this always meant to be.
+  const rootQinv = root.getWorldQuaternion(new THREE.Quaternion()).invert();
+  const chainQ = container
+    ? rootQinv.multiply(container.getWorldQuaternion(new THREE.Quaternion()))
+    : new THREE.Quaternion();
+
+  const map = new Map();
+  map.chainQ = chainQ;   // container rotation — position tracks live in this frame too
+  root.traverse((o) => {
+    if (!o.isBone) return;
+    const bq = bindQ.get(o.name);
+    const worldQ = bq
+      ? chainQ.clone().multiply(bq)                                  // container space -> model-root frame
+      : o.getWorldQuaternion(new THREE.Quaternion());                // fallback: bones with no skin weight
+    map.set(o.name, {
+      worldQ,
+      localP: o.position.clone(),
+      parentName: o.parent?.isBone ? o.parent.name : null,
+    });
+  });
+  return map;
+}
+
+// Register a source rig by key (its loaded pose = its bind pose). The FIRST one registered
+// becomes the default for clips that don't name a rig.
+export function addSourceRig(key, root, map = null) {
+  sourceRigs.set(key, { bind: captureBind(root), map });
+  if (!defaultRigKey) defaultRigKey = key;
+}
+
+// Back-compat: the original single-source API — registers the 'anim' (Synty) rig.
+export function setSourceRig(root, map = null) {
+  addSourceRig('anim', root, map);
+  defaultRigKey = 'anim';
+}
+
+export function detectRig(root) {
+  let rig = 'anim';
+  root.traverse((o) => { if (o.isBone && o.name === 'Pelvis') rig = 'polygon'; });
+  return rig;
+}
+
+// Per-character retarget context: bone deltas keyed by SOURCE bone name.
+// Characters sharing a rig signature can share a context, but contexts are
+// cheap; we just build one per loaded character master.
+export function buildRetargetContext(targetRoot, rigKey = null) {
+  const key = rigKey ?? defaultRigKey;
+  const srcRig = sourceRigs.get(key);
+  if (!srcRig) throw new Error(`source rig '${key}' not registered — call setSourceRig()/addSourceRig() first`);
+  const sourceBind = srcRig.bind, sourceMap = srcRig.map;
+  const rig = detectRig(targetRoot);
+  const targetBind = captureBind(targetRoot);
+  const deltas = new Map(); // source bone name -> THREE.Quaternion
+  const mapName = (src) => {
+    let n = sourceMap ? (sourceMap[src] || src) : src;                        // foreign source -> anim-rig name
+    if (rig === 'polygon' && ANIM_TO_POLYGON[n]) return ANIM_TO_POLYGON[n];   // ...then anim -> polygon for polygon targets
+    return n; // identity mapping (Knights-style rigs, or shared names)
+  };
+  for (const [srcName, src] of sourceBind) {
+    const tgtName = mapName(srcName);
+    const tgt = targetBind.get(tgtName);
+    if (!tgt) continue;
+    const delta = src.worldQ.clone().invert().multiply(tgt.worldQ);
+    // ROOT FIX. Each bone is compensated through its PARENT's delta. A source bone with no
+    // parent (packs whose root bone is Hips — no Root — e.g. the Wild West gunslinger rig)
+    // has no parent delta, and the old code fell back to IDENTITY. But the TARGET's Hips
+    // hangs under a Root bone carrying its own bind rotation, which then never cancels:
+    //   want  W_tgt(t) = W_src(t) · Δb ,  and  W_tgt = W_parent · q_local
+    //   so    q_local  = W_parent⁻¹ · q_src(t) · Δb
+    // i.e. the fallback must be the TARGET PARENT's inverse bind world rotation, not identity.
+    // With identity the whole character renders upside down / rolled by the root's bind.
+    let parentFix = null;
+    if (!src.parentName) {
+      const tp = tgt.parentName ? targetBind.get(tgt.parentName) : null;
+      if (tp) parentFix = tp.worldQ.clone().invert();
+    }
+    deltas.set(srcName, { delta, targetName: tgtName, parentFix });
+  }
+
+  // Root translation tracks are authored in the source rig's units (cm).
+  // Packs authored in metres need them rescaled or the pelvis flies 87m up.
+  const srcHips = sourceBind.get('Hips');
+  const tgtRootName = rig === 'polygon' ? 'Pelvis' : 'Hips';
+  const tgtRoot = targetBind.get(tgtRootName);
+  let posScale = 1;
+  if (srcHips && tgtRoot && Math.abs(srcHips.localP.y) > 0.001 && Math.abs(tgtRoot.localP.y) > 0.001) {
+    posScale = tgtRoot.localP.y / srcHips.localP.y;
+  }
+  // A TARGET whose Hips sits at its parent's origin (localP.y === 0 — true of the western
+  // Synty rigs, where Root and Hips are coincident) used to yield posScale = 0, which
+  // multiplied every Hips.position key by ZERO: the pelvis got pinned to the root and the
+  // character sank into the ground. Only rescale when BOTH hip heights are real; else 1:1.
+  if (!(posScale > 0.01 && posScale < 100)) posScale = 1;
+
+  // Same bone NAMES don't guarantee the same bind POSE: the Fantasy Rivals bosses each carry a
+  // custom rest stance (bent legs, etc.) on anim-rig bone names. The clip can only be used as-is
+  // when the bind pose ALSO matches — otherwise their legs break. bindMatches = every bone's
+  // bind-delta is ~identity (|w|≈1).
+  // Also fold a hash of the bind-deltas into the cache key: every custom-posed boss otherwise
+  // produces the SAME key (same rig/boneCount), so they'd share ONE retargeted clip — the first
+  // one computed — and wear each other's skeleton. The hash makes each distinct bind pose unique
+  // while still letting identical rigs (e.g. many goblins) share the cache.
+  let bindMatches = true, h = 0;
+  for (const e of deltas.values()) {
+    const d = e.delta;
+    if (Math.abs(Math.abs(d.w) - 1) > 0.002) bindMatches = false;
+    h = (Math.imul(h, 31) + ((d.x * 1e3) | 0) + Math.imul((d.y * 1e3) | 0, 7) + Math.imul((d.z * 1e3) | 0, 13)) | 0;
+  }
+
+  const needsRootFix = [...deltas.values()].some((e) => e.parentFix);
+  // position tracks are VECTORS in the source container's frame — convert them the same way
+  const posQ = (targetBind.chainQ ?? new THREE.Quaternion()).clone().invert()
+    .multiply(sourceBind.chainQ ?? new THREE.Quaternion());
+  return { rig, deltas, posScale, bindMatches, needsRootFix, posQ, sourceBind, rigKey: key, key: `${key}:${rig}:${posScale.toFixed(3)}:${deltas.size}:${bindMatches ? 1 : 0}:${h}` };
+}
+
+const clipCache = new Map(); // `${clip.uuid}:${ctx.key}` -> retargeted clip
+
+// Retarget a clip recorded on the ANIMATION rig to the target context.
+export function retargetClip(clip, ctx) {
+  // Identity rig with full bone coverage AND matching units (cm): use clip as-is.
+  // A metre-scale rig (e.g. the Modular Fantasy Hero) needs the root-position rescale below,
+  // so don't short-circuit it even though its bone names already match the source.
+  if (ctx.rig === 'anim' && ctx.bindMatches && !ctx.needsRootFix && Math.abs(ctx.posScale - 1) < 0.05) return clip;
+  const cacheKey = `${clip.uuid}:${ctx.key}`;
+  if (clipCache.has(cacheKey)) return clipCache.get(cacheKey);
+
+  const qa = new THREE.Quaternion();
+  const tracks = [];
+  for (const track of clip.tracks) {
+    const dot = track.name.lastIndexOf('.');
+    const node = track.name.slice(0, dot);
+    const prop = track.name.slice(dot + 1);
+    const entry = ctx.deltas.get(node);
+    if (!entry) continue; // not a character bone (e.g. bow-prop joints) -> drop
+
+    if (prop === 'quaternion') {
+      const src = ctx.sourceBind.get(node);
+      const parentEntry = src.parentName ? ctx.deltas.get(src.parentName) : null;
+      // parented bone → cancel the parent's delta; source-root bone → cancel the TARGET
+      // parent's bind world rotation (see ROOT FIX in buildRetargetContext)
+      const dParentInv = parentEntry ? parentEntry.delta.clone().invert()
+        : (entry.parentFix ? entry.parentFix.clone() : null);
+      const dBone = entry.delta;
+      const values = new Float32Array(track.values.length);
+      for (let i = 0; i < track.values.length; i += 4) {
+        qa.fromArray(track.values, i);
+        if (dParentInv) qa.premultiply(dParentInv);
+        qa.multiply(dBone);
+        qa.toArray(values, i);
+      }
+      const t = new THREE.QuaternionKeyframeTrack(`${entry.targetName}.${prop}`, Array.from(track.times), Array.from(values));
+      tracks.push(t);
+    } else if (prop === 'position') {
+      // Keep only the root (Hips) translation — drives bob/crouch —
+      // rescaled into the target rig's units.
+      if (node !== 'Hips') continue;
+      const t = track.clone();
+      t.name = `${entry.targetName}.${prop}`;
+      // The hips translation is a VECTOR in the source container's frame. Rotating only the
+      // quaternion tracks left it in the pack's Z-up space: the pelvis got driven to the
+      // floor (hipsY 0) while the body above it posed correctly. Rotate, then rescale.
+      const v = t.values;
+      const identityQ = Math.abs(ctx.posQ.w) > 0.999999;
+      if (!identityQ) {
+        for (let i = 0; i < v.length; i += 3) {
+          _posV.set(v[i], v[i + 1], v[i + 2]).applyQuaternion(ctx.posQ);
+          v[i] = _posV.x; v[i + 1] = _posV.y; v[i + 2] = _posV.z;
+        }
+      }
+      if (ctx.posScale !== 1) for (let i = 0; i < v.length; i++) v[i] *= ctx.posScale;
+      tracks.push(t);
+    }
+    // scale tracks dropped
+  }
+  const out = new THREE.AnimationClip(clip.name, clip.duration, tracks);
+  clipCache.set(cacheKey, out);
+  return out;
+}

package/src/index.js

@@ -9,18 +9,35 @@
 // facet contracts) land in later steps; step 1 files are byte-identical to
 // their proven originals on purpose.
 
-// core — math/utils, quality presets + auto-tuner, decals
+// 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';
+export * from './core/retarget.js';
+export { Input, DEFAULT_PAD_BINDINGS } from './core/input/index.js';
 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);
+  }
+}