sindicate 0.1.0 → 0.2.0

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;
+}

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,7 +9,12 @@
 // 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 { 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';