sindicate 0.1.0 → 0.4.0

package/README.md

@@ -7,9 +7,70 @@
 - **Consumption:** games depend on `"sindicate": "github:<owner>/sindicate#vX.Y.Z"` (stable, lockfile-pinned) or `"file:../Sindicate"` (live engine hacking). Source ESM, no build step; `three` and `three-mesh-bvh` are peer dependencies.
 - **The rule:** engine code changes **only in this repo** — never copy engine files into a game to hack them.
 
-## Status
+## What's in the box
 
-Migration step 1 (of the plan in ENGINE_DESIGN.md §9): package scaffold + the verified-clean tier moved verbatim from western — core utils/quality/decals, collision + BVH worker, water/grass/wind/weather-uniform world modules, pooled shatter, and the patched FBXLoader (vendored; merges all FBX animation layers — pinned against three ^0.184).
+Migration steps 1–2 (of the plan in ENGINE_DESIGN.md §9): the verified-clean world/systems tier plus the complete core pipeline — rendering, assets, animation, retargeting, input — extracted from western, with game data arriving through registration calls instead of imports. Full reference: [`docs/api/`](./docs/api/).
+
+**Core**
+
+- [assets](./docs/api/assets.md) — Synty FBX/GLB loading, atlas binding with shared cached materials, multi-skeleton pack collapse, clip cooking to JSON, texture warm-up.
+- [anim](./docs/api/anim.md) — `Animator`/`RawAnimator` state machine: auto retargeting, bone-masked overlay layer, per-clip timing trims, safe one-shot callbacks.
+- [retarget](./docs/api/retarget.md) — bind-pose-delta retargeting so clips authored on one rig play on differently-named rigs.
+- [input](./docs/api/input.md) — keyboard + mouse + gamepad behind one API with edge detection, data-driven pad bindings, analog sticks.
+- [renderer](./docs/api/renderer.md) — WebGPU with WebGL2 fallback, opt-in TRAA, post-processing with a single game-supplied TSL screen-grade slot.
+- [quality](./docs/api/quality.md) — low/medium/high presets, per-game persistence, live apply, one-way FPS `AutoTuner`.
+- [utils & decals](./docs/api/utils-decals.md) — shared math/noise helpers plus `DecalField`, a ring-buffer-budgeted surface decal system.
+
+**World**
+
+- [collision](./docs/api/collision.md) — merged-static `MeshBVH` capsule collision, built sync or in a Web Worker for streamed tiles.
+- [grass](./docs/api/grass.md) — streaming instanced grass clumps: GPU wind, trampling with spring-back, dryness/wetness/snow.
+- [water](./docs/api/water.md) — see-through low-poly water: scene refraction with Beer–Lambert absorption, fresnel sky reflection.
+- [wind & weather uniforms](./docs/api/wind-weather-uniforms.md) — the single source of weather truth: CPU `Wind` sim + shared TSL uniform singletons.
+
+**Systems**
+
+- [shatter](./docs/api/shatter.md) — pooled prop debris: real shard meshes flung, bounced, settled and faded, pure CPU, nothing resident.
+
+**Vendor**
+
+- [FBXLoader](./docs/api/fbxloader.md) — vendored three.js FBXLoader patched to merge all FBX animation layers; pinned against three ^0.184.
+
+## Callable API
+
+Games plug in at explicit registration points — all boot-time, before first use (see each doc's gotchas for ordering):
+
+```js
+import {
+  setClipDefaults, setAtlasEmissiveHook, setQualityStorageKey,
+  Input, DEFAULT_PAD_BINDINGS, createRenderer, createPostProcessing, wantsTRAA,
+} from 'sindicate';
+
+// Per-game quality storage key — BEFORE the first getQuality read
+// (games sharing an origin in dev otherwise overwrite each other).
+setQualityStorageKey('mygame_quality');
+
+// Game animation data: per-clip timing trims + which source rig authored each clip.
+setClipDefaults({
+  timing: { swing: { start: 0.12, speed: 1.4, end: 0.85 } },
+  rigs:   { swing: 'syntyKnight' },
+});
+
+// TSL emissive term added into every atlas material — BEFORE the first
+// applyAtlas/instantiate (materials are cached).
+setAtlasEmissiveHook((albedo) => lampFieldTerm(albedo));
+
+// Unified input with the game's own pad layout (data, not code).
+const input = new Input(canvas, { padBindings: DEFAULT_PAD_BINDINGS });
+
+// Renderer + post pipeline; the grade is the game's one screen-look slot,
+// driven live via post.gradeAmount.value — never rebuilt at runtime.
+const { renderer } = await createRenderer(container);
+const post = createPostProcessing(renderer, scene, camera, {
+  traa: wantsTRAA(),
+  grade: Fn(([color, amount]) => /* identity at amount 0 */ color),
+});
+```
 
 ## Games on Sindicate
 

package/docs/api/README.md

@@ -0,0 +1,28 @@
+# Sindicate API reference
+
+One page per module, written from the actual source. Each page covers every export with real signatures, one realistic usage example, and a **gotchas** section preserving the hard-won knowledge from the source comments (perf rules, ordering constraints, bug history). Contracts — who owns what state, what a game must register — live in [`../contracts/`](../contracts/); these pages are the per-module mechanics.
+
+## Core (`src/core/`)
+
+- [`assets.md`](./assets.md) — model/texture/clip loading: Synty FBX + GLB-twin redirect, atlas binding with shared cached materials, multi-skeleton pack collapse, clip cooking to JSON, `warmTextures`, loading-progress hooks.
+- [`anim.md`](./anim.md) — `Animator`/`RawAnimator` state machine over `THREE.AnimationMixer`: auto retargeting per source rig, one bone-masked overlay layer, per-clip timing trims, safe one-shot callbacks; `setClipDefaults` registers game timing/rig tables.
+- [`retarget.md`](./retarget.md) — bind-pose-delta animation retargeting: play clips authored on one skeleton (Synty ANIMATION rig) on differently-named/oriented rigs (POLYGON packs), with a named-rig registry.
+- [`input.md`](./input.md) — keyboard + mouse + gamepad behind one API (`down`/`hit`/`held`/`consume`), data-driven pad bindings, analog `moveStick`/`stickLook`, UI-modal suppression and edge priming.
+- [`renderer.md`](./renderer.md) — WebGPU renderer with WebGL2 fallback (`?webgl`), opt-in TRAA (`?traa`), and `createPostProcessing` with the single game-supplied TSL "screen grade" slot driven by one uniform.
+- [`quality.md`](./quality.md) — `low`/`medium`/`high` presets, per-game `localStorage` persistence (`setQualityStorageKey`), live `applyQuality`, and the one-way `AutoTuner` FPS downgrader.
+- [`utils-decals.md`](./utils-decals.md) — shared math/noise helpers and scratch objects (`utils.js`), plus `DecalField`, a ring-buffer-budgeted ground/surface decal system (blood, scorch, footprints).
+
+## World (`src/world/`)
+
+- [`collision.md`](./collision.md) — merged-static-geometry `MeshBVH` collision (sync `buildBVH` and worker-based `buildBVHAsync`) that capsule-sweeps the player against real triangles; stairs and slopes just work.
+- [`grass.md`](./grass.md) — `GrassField`: instanced 4-blade clumps streamed in a ring around the player; wind, trampling with spring-back, dryness, wetness and snow all evaluated on the GPU in TSL.
+- [`water.md`](./water.md) — low-poly see-through water: refracts the rendered scene with per-channel Beer–Lambert absorption, fresnel sky reflection wired to the weather uniforms, faceted swell and shoreline foam.
+- [`wind-weather-uniforms.md`](./wind-weather-uniforms.md) — the single source of weather truth: `Wind` CPU simulation ticked once per frame, plus module-level TSL uniform singletons every weather-aware shader reads.
+
+## Systems (`src/systems/`)
+
+- [`shatter.md`](./shatter.md) — pooled debris for smashed props: clones the pack's real shard meshes, flings/bounces/settles/fades them with pure CPU integration — no physics engine, nothing resident.
+
+## Vendor (`src/vendor/`)
+
+- [`fbxloader.md`](./fbxloader.md) — vendored three.js `FBXLoader` with one local patch: merges **all** FBX animation layers per stack (stock three keeps only the first); pinned against three ^0.184.

package/docs/api/anim.md

@@ -0,0 +1,125 @@
+# anim — character animation state machine
+
+`src/core/anim.js`
+
+A thin state machine over `THREE.AnimationMixer` with automatic per-rig clip retargeting (via `./retarget.js`), a single persistent overlay layer for bone-masked composition, per-clip timing trims, and safe one-shot completion callbacks.
+
+## Exports
+
+```js
+import { setClipDefaults, Animator, RawAnimator } from './core/anim.js';
+```
+
+### `setClipDefaults({ timing = null, rigs = null } = {})`
+
+Registers game data with the engine, once at boot:
+
+- `timing` — `{ clipName -> { start?, speed?, end? } }`. Per-clip trim/speed defaults (fractions 0..1 for `start`/`end`; `speed` is a `timeScale`). Tuned via `/anim.html`.
+- `rigs` — `{ clipName -> sourceRigKey }`. Which source rig each clip was authored against; becomes the default `clipRigs` for every `Animator` constructed without an explicit one.
+
+Both are module-level tables, deliberately *game data, not engine code*. Unregistered, clips play untrimmed and every `Animator` needs explicit `clipRigs`. Passing `null`/omitting a field leaves the existing table untouched.
+
+### `class Animator`
+
+#### `new Animator(root, clips, clipRigs = null)`
+
+- `root` — the object the `AnimationMixer` binds to (the character's skinned model root).
+- `clips` — `{ name -> THREE.AnimationClip }`; each is registered (retargeted) at construction.
+- `clipRigs` — optional `{ clipName -> sourceRigKey }`; defaults to the table given to `setClipDefaults`. A clip is authored against ONE skeleton's bind pose; clips from a foreign pack (different bind, same bone names) must retarget from THAT bind or they play folded in half. One retarget context is built and cached per source rig (`_ctxByRig`).
+
+Public fields other code relies on: `mixer`, `root`, `actions` (`name -> AnimationAction`), `current` / `currentName` (base FSM action), `ctx` (the default retarget context — `null` on `RawAnimator`).
+
+#### `get needsRetarget` → `true`
+
+Overridden to `false` by `RawAnimator`. The constructor *asks* this before building a default retarget context, because `buildRetargetContext` throws if no source rig has been registered yet — see gotchas.
+
+#### `register(name, clip)`
+
+Retargets `clip` from its source rig (looked up in `clipRigs`, else the default rig) onto `root`'s skeleton and stores the resulting `mixer.clipAction`.
+
+#### `registerMasked(name, srcName, keepFn)`
+
+Builds a bone-masked copy of an already-registered clip: clones `srcName`'s clip and keeps only tracks whose bone name passes `keepFn(boneName)` (the `.position`/`.quaternion`/`.scale` suffix is stripped before the callback sees it). No-op if `srcName` isn't registered. Used to split locomotion across body halves — e.g. legs from `walk` + torso/arms from `blockLoop` so you can walk with the guard up.
+
+#### `play(name, opts = {})` → `AnimationAction | null`
+
+Fades the base FSM action to `name`. Returns the action, or `null` if unregistered.
+
+- `once` (default `false`) — `LoopOnce` + `clampWhenFinished`; otherwise `LoopRepeat`.
+- `fade` (default `0.18`) — crossfade seconds (`fadeIn` on the new action, `fadeOut` on the previous base).
+- `restart` (default `false`) — without it, re-`play`ing the current looping clip is a no-op (one-shots always restart).
+- `onDone` — one-shot completion callback (see gotchas for the per-action storage).
+- `startFrac` (default `CLIP_TIMING[name].start ?? 0`) — 0..1, skips into the clip past wind-up.
+- `timeScale` (default `CLIP_TIMING[name].speed ?? 1`).
+
+Explicit opts always override the `CLIP_TIMING` defaults.
+
+#### `setOverlay(name, opts = {})` → `AnimationAction | null`
+
+One persistent overlay action that plays *alongside* the base action — `play()` only fades `this.current`, never the overlay. Non-overlapping tracks compose. Pass `null`/falsy `name` to drop the overlay.
+
+- `restart` — force a reset even if `name` is already the overlay (otherwise same-overlay calls return early).
+- `once` — `LoopOnce` + `clampWhenFinished` on the overlay.
+- `fade` — when *swapping* overlays of the same mask: `crossFadeFrom` duration. When *dropping* the overlay: `fadeOut` duration, which MUST equal the fade the caller uses on its full-body base `play()` (see gotchas).
+
+Without `fade`, swaps and drops are instant (`stop()` + weight 0).
+
+#### `update(dt)`
+
+Advance the mixer, then enforce the current clip's `CLIP_TIMING.end` trim: when `action.time` passes `end * duration`, a one-shot clamps there, pauses, and fires its `onDone`; a loop cycles back to `start * duration`. Call every frame.
+
+#### `stopAll()`
+
+`mixer.stopAllAction()` and clears `current`, `currentName`, and the overlay reference.
+
+### `class RawAnimator extends Animator`
+
+For self-animated rigs (PolyPerfect creatures, like the horse) whose clips target the model's OWN skeleton. `needsRetarget` returns `false` and `register(name, clip)` is just `mixer.clipAction(clip)` — no retarget, no retarget context. Everything else (`play`, `setOverlay`, once-callbacks, end-trim) behaves identically.
+
+## Usage example
+
+```js
+import { setClipDefaults, Animator } from './core/anim.js';
+
+// Once at boot — game data, tuned in /anim.html:
+setClipDefaults({
+  timing: { swing: { start: 0.12, speed: 1.4, end: 0.85 } },
+  rigs:   { swing: 'syntyKnight' },        // authored on a foreign pack's bind pose
+});
+
+const anim = new Animator(model, { idle: idleClip, walk: walkClip, swing: swingClip, aim: aimClip });
+
+// Split the body: legs keep walking, upper body holds the bow.
+const isUpper = (b) => /Spine|Chest|Neck|Head|Shoulder|Arm|Hand/.test(b);
+anim.registerMasked('walkLower', 'walk', (b) => !isUpper(b));
+anim.registerMasked('aimUpper',  'aim',  isUpper);
+
+// Enter aim: swap the base to the lower-only mask and start the overlay in the SAME frame.
+anim.play('walkLower', { fade: 0.15 });
+anim.setOverlay('aimUpper');                 // instant start — weights stay summed to 1
+
+// Leave aim: fade the overlay out over EXACTLY the base's fade-in.
+anim.setOverlay(null, { fade: 0.15 });
+anim.play('walk', { fade: 0.15 });
+
+// One-shot with completion:
+busy = true;
+anim.play('swing', { once: true, onDone: () => { busy = false; } });
+
+// Every frame:
+anim.update(dt);
+```
+
+## Gotchas
+
+- **Weights must sum to 1 on every bone, always.** three's `PropertyMixer` fills any cumulative-weight deficit from the binding's ORIGINAL saved value — captured at the mixer's first activation, i.e. the model's BIND POSE. A weight gap does not blend between two poses: it blends toward a T-pose. History: a 0.12s overlay `fadeOut` racing a 0.18s base `fadeIn` dipped the sum to ~0.58 and flashed the arms 42% toward T-pose on every aim release. Discipline:
+  - Overlay swaps of the *same mask* crossfade (`opts.fade`) — `crossFadeFrom` keeps the pair summing to 1.
+  - *Starting* an overlay is instant, and the caller switches the base to the complementary mask in the same frame.
+  - *Dropping* an overlay fades it out over exactly the duration the caller fades its full-body base in (pass the same `fade` to both calls): upper body gets `overlay(1-t) + base(t) = 1`, lower gets `lowerBase(1-t) + base(t) = 1`. A plain `stop()` while the base is still lower-only leaves the upper body at zero weight — a ~0.2s T-pose flash at the end of every one-shot. A hard pose cut is survivable; a T-pose is not.
+- **One-shot callbacks are per-action (`action._onceDone`), not a shared slot.** With a single slot, any `play({once})` stomped the *previous* one-shot's pending callback — e.g. a bow release during a dodge wiped the dodge's `busy = false` and soft-locked the player. Per-action, each one-shot can only ever replace its own callback. Re-playing a clip as a loop clears any stale `_onceDone`. The end-trim path in `update()` fires and clears the same slot, so `onDone` fires exactly once whether the clip finishes naturally or hits its `end` trim.
+- **Retargeting is per source rig.** Clips authored against a different bind pose (same bone names) MUST retarget from *that* bind or they play folded in half — that's what `clipRigs` / `setClipDefaults({rigs})` maps. One context is built and cached per rig key.
+- **`RawAnimator` exists because building a retarget context can crash.** The base constructor used to always build a default context, and `buildRetargetContext` threw if no source rig had been registered yet. In the game that was invisible (the player registers the Synty rig long before a horse loads); anywhere else — a bench that only wants a horse — it was a hard crash on construction. Hence the `needsRetarget` getter: ask, don't assume. Other code reads `.ctx`, which is `null` on a `RawAnimator`.
+- **`reset()` must come first in `setOverlay`** — `AnimationAction.reset()` calls `stopFading()`, so any fade set up before it would be cancelled.
+- **`update(dt)` is where end-trims live.** `CLIP_TIMING.end < 1` only takes effect if you call `update` every frame; the mixer's own `finished` event never fires for a trimmed one-shot (it clamps and pauses at `end` instead).
+- **`play()` on the currently looping clip is a no-op** unless `restart: true` or `once: true` — safe to call from a per-frame locomotion FSM.
+- **Timing tables are defaults, not law.** Explicit `startFrac` / `timeScale` opts override `CLIP_TIMING`; the tables live in game data and are registered once via `setClipDefaults`.

package/docs/api/assets.md

@@ -0,0 +1,208 @@
+# assets — model, texture and clip loading
+
+`src/core/assets.js`
+
+The asset system loads Synty FBX models and animation clips, binds atlas textures (FBXLoader does not auto-link Synty's atlases), and caches everything. It also transparently redirects static FBX loads to faster `.glb` twins, dedups embedded GLB textures, collapses the pathological multi-skeleton character packs onto one skeleton, and cooks parsed animation clips to JSON so later boots skip main-thread FBX parsing.
+
+The module uses a patched `FBXLoader` from `src/vendor/FBXLoader.js` that merges **all** FBX animation layers per stack — the engine does not depend on a `node_modules` postinstall patch. The internal `GLTFLoader` has `MeshoptDecoder` installed; without it every `*_LOD*.glb` (EXT_meshopt-compressed) fails to load and trees/building LODs silently never appear, leaving only invisible colliders.
+
+All loaders cache **promises**, not resolved values — concurrent callers for the same key share one in-flight load.
+
+---
+
+## Loading models
+
+### `loadModel(url, { texture = null, scale, twin = false }) → Promise<THREE.Group>`
+
+Loads a model and returns the shared **master** copy (do not add it to the scene directly — use `instantiate`). Dispatches by extension:
+
+- `.fbx` → patched FBXLoader (main-thread parse; slow — see gotchas). Default scale `SYNTY_SCALE = 0.01` (Synty FBX are authored in centimetres).
+- `.glb` → GLTFLoader. Default scale `1` — fbx2gltf-converted GLBs already baked cm→m. The GLB's separate `g.animations` are copied onto `g.scene.animations` so the VAT bakers can read clips off the model just like FBX. Embedded textures are deduped (see below).
+
+After load: the group is scaled, any stray lights the file carries are stripped (Synty FBX embed a grey AmbientLight in their global settings — 7+ of them at intensity 1 washed out the whole scene, including the dungeon's dark mood; the world is lit explicitly, never by FBX), and if `texture` is given the atlas is loaded and `applyAtlas` is run on the whole group. GLB models get the atlas at `flipY: false` (glTF top-left-origin UV convention); FBX keeps the TextureLoader default `true`.
+
+**Cache key is `url|texture|scale` — by what actually varies, not url alone.** Keying by url alone meant the first caller to load a file decided its skin for the whole run; worse, a texture-less first caller cached a master whose materials never went through `applyAtlas`, leaving raw FBX `MeshLambertMaterial`s pointing at an unresolvable texture — which renders **BLACK** (it blacked out all 29 bodies in the casting bench, the coach's driver, mate, and every randomly-skinned fare). One body in two atlases is two masters; that is the correct amount of masters.
+
+A rejected load deletes its cache entry, so a transient 404 does not cache the rejection forever — retries re-fetch.
+
+Dev census: every URL that still parses through FBXLoader is pushed to `window.__fbxLoads`.
+
+### `resolveModelUrl(url, { texture = null, scale, twin = false }) → Promise<string>`
+
+The FBX→GLB redirect decision, exported on its own. `scripts/convert_runtime_statics.mjs` converts every runtime static FBX to a same-dir `.glb` twin (fbx2gltf `--binary`, **default V-flip** — a reverted batch used `--no-flip-v` and mirrored every atlas cell) and lists them in `/assets/glb-twins.json`. The redirect fires only when:
+
+- the url ends `.fbx`, **and**
+- an atlas `texture` is supplied (applyAtlas replaces the GLB's materials, so conversion material fidelity is irrelevant) **or** `twin: true` (an explicit opt-in for texture-less callers whose downstream discards the file's materials anyway, e.g. scatterTree UV-splits geometry and builds its own), **and**
+- the scale is "redirectable": `scale === undefined` (cm-authored pack; the twin is metres and loader default 1 fits), or `scale === 1` on a `/assets/dungeon/` url — the DUNGEON kit is metre-authored with cm FBX headers, its raw twins came out 100× small, so those twins carry a baked ×100 root rescale and `scale:1` loads them correctly.
+
+A missing manifest degrades to plain FBX loading.
+
+**Why it's exported:** callers that build their own materials from a model's flattened geometry (scatter / scatterResident) must know which format actually loaded — glTF-convention UVs need the atlas at `flipY:false`, FBX-convention at the default `true`. scatter() not knowing this was the mirrored-cell bug on every scatter-placed prop (the red wells, the washed stall tents) after the twins landed.
+
+### `loadGLB(url) → Promise<THREE.Group>`
+
+Loads a glodify LOD `.glb` through a separate cache (`gltfCache`, keyed by url). Units are preserved from the FBX source — **centimetres**, no scaling applied. Embedded textures are deduped. Used by `instantiate`'s `attach` path and by LOD systems.
+
+---
+
+## Instantiating
+
+### `instantiate(url, opts) → Promise<THREE.Object3D>`
+
+Returns an independent copy safe to add to the scene. Skinned models are cloned via `SkeletonUtils.clone`; static models via plain `.clone()` (shared geometry). `opts` is passed through to `loadModel` (`texture`, `scale`, `twin`) plus:
+
+- **`collapse: true`** — run `collapseSkeletons` on the **master, before the clone**, so a child is cloned with 51 bones and not with 5,082 to be pruned one at a time. Memoised inside; the second kid is free.
+- **`keep: string | string[]`** — for multi-character source files, drop every mesh whose (lowercased) name doesn't contain a keep substring. A lone string keeps the single-substring behaviour every adult uses; a child needs a list — he is five meshes (body, mouth, freckles, pupils, eyebrows). After the mesh drop, the **rival-skeleton prune** runs (see gotchas — this is the most expensive lesson in the file).
+- **`attach: string[]`** — seat static head props (dwarf beards/hair) on the Head bone, loaded from `/assets/characters/attach/<name>.glb`. The meshes are authored head-local and the pack's reorienting `Head_Attachments` node is pruned by fbx2gltf, so the bone's bind-pose world rotation is cancelled (`att.quaternion = inverse(bone world quat)` after `updateMatrixWorld`) — the attachment renders upright and rides the head.
+- **`hair: string[]`** — the kid pack's head props, one FBX per style in `/assets/characters/kids` (97 of them). A child's hair is **not** in his body mesh (an adult's is), so a kid with no entry here is bald. Hung off the Head bone resolved through `keep[0]` — the body mesh — and carry no materials of their own: the `applyAtlas` the caller runs next walks bones and their children too, so the hair picks up the body atlas and therefore the atlas's hair colour (the only colour it can have — every hair vertex sits on one texel of it).
+
+Hair/hat seating (internal `seatHeadProp`) has to classify each prop's authoring space, because hair and hats are authored in **different spaces** in the same pack and nothing in the file says which. Measured: `SM_Chr_Hair_Messy_01` spans Y 92.9–121.3 cm — absolute, drawn already sitting on a head standing on the floor (**rig space**) — while `SM_Chr_Attach_Hat_Cowboy_01` spans Y −3.8–24.4 cm, relative to the Head bone which binds at Y 100.1 (**head-local**). Classified by the mesh's own bounding-box centre against `RIG_SPACE_CM = 60` (a hat's centroid is ~10 cm, a rig-space hairstyle's ~107 — nothing is near 60): rig-space geometry gets the head's bind pose cancelled out (`inverse(head.world) · root.world`), head-local geometry is simply parented. The kid Head binds with an identity rotation, so there is no twist to undo either way.
+
+### `collapseSkeletons(model) → THREE.Skeleton | null`
+
+Collapse a multi-character pack onto **one** skeleton — the load-bearing step for POLYGON Kids, and the only way a child can be made of more than one mesh. Memoised on `model.userData.__collapsed`; returns the reference skeleton, or `null` if no ≥51-bone skinned mesh exists.
+
+Why it exists: the keep-path prune in `instantiate` is enough when a character **is** one mesh (every adult — Synty bakes hair and face into the body). A child is five meshes and the parts don't belong to him: the face/freckle decals are unskinned and hang off the Head bone of `SM_Chr_Kid_EASTERN_01` (whichever child you asked for), and the eyes/eyebrows are skinned to `Eyes_`/`Eyebrow_` bones of **another outfit's** copy of the skeleton. `Characters_Kids.fbx` carries 5,082 bones and **one hundred bones called 'Head'**. In the bind pose every skeleton coincides, so a standing child looks perfect — and the moment he walks, his body strides off and his face, eyes and eyebrows stay behind in the T-pose. The prune cannot fix that: it would cut the bones the face is hanging from, which is worse.
+
+What it does:
+
+1. Picks the reference skeleton: the ≥51-bone skeleton whose `Hips` sits nearest the root — the **shallowest**, because every rival is nested inside it, so its own bones cannot move when the rivals are cut. (`>= 51` skips the 2-bone eye/eyebrow skeletons.)
+2. Rebinds every skinned mesh: same-length outfits are pointed at the reference via `o.bind(ref, o.bindMatrix)`; 2-bone eyes/eyebrows are matched **by name inside the reference only** (`Eyes_Left`, `Eyebrow_Right`… are unique within the 51 — this is *not* the by-name lookup across the whole pack that the duplicate-bone trap punishes).
+3. Re-parents unskinned face decals (meshes parented to some bone) onto the reference's `Head` — transform-exact, they sit at local identity on a Head.
+4. Cuts the rivals at the boundary (a non-kept bone whose parent is kept) — each snip takes a whole nested subtree and can never orphan a bone still in use.
+
+Measured on all 106 meshes: 0.000 mm of drift, 5,082 bones → 51. Run once on the shared master, so every clone is born with 51 bones and cloning is cheap.
+
+---
+
+## Textures
+
+### `loadTexture(url, { flipY }) → Promise<THREE.Texture>`
+
+Loads and caches a texture. Sets `SRGBColorSpace`, `LinearMipmapLinearFilter` min / `LinearFilter` mag, and applies `flipY` only when explicitly passed.
+
+**The cache key is flipY-specific** (`url` alone when `flipY` is undefined, else `url|flip0/1`): a packed GLB dwarf atlas needs `flipY:false` (glTF UV convention) while the same-named atlas on an FBX model wants the TextureLoader default (`true`). Keying by url alone would let one flipY setting win for all consumers.
+
+Note the 2048 downscale cap is **retired** — even nearest-sampled, capped atlases came out wrong-coloured on small parts (mip-chain sampling of the resized canvas). The embedded-texture dedup carries the memory diet instead; `?fulltex` is dead.
+
+### `warmTextures(renderer) → Promise<number>`
+
+Force-uploads every cached texture to the GPU via `renderer.initTexture`, returning the count warmed. The boot warm's `compileAsync` compiles **pipelines** but does not upload textures — each was otherwise uploaded on first sight mid-play (~75 ms hitch apiece, measured by the freeze profiler as `tex:+1` records). Run it under the loading screen. Safe to call again later (phase-2): `initTexture` on an already-resident texture is a no-op. Failed loads are skipped silently.
+
+### Embedded-texture dedup (internal, automatic)
+
+Memory diet, part 2: character/castle GLBs each embed their **own copy** of shared atlases (`atlas_fantasykingdom` measured resident 3× ≈ 270 MB alone). Every GLB load (`loadModel` and `loadGLB`) runs `dedupEmbeddedTextures` on the scene: each embedded image on `map`/`emissiveMap`/`normalMap`/`roughnessMap`/`metalnessMap`/`aoMap`/`alphaMap` is keyed by `dims : 64×64 full-byte downsample hash : flipY : colorSpace`, and one `THREE.Texture` per unique image is shared; duplicates are **disposed before they ever reach the GPU**. The 64×64 full-byte hash (16k+ samples) means distinct atlases cannot realistically collide. Unreadable image types are kept as-is; the pass is a no-op outside a DOM environment.
+
+---
+
+## Atlas materials
+
+### `applyAtlas(root, tex, { emissive = null })`
+
+Replaces every mesh material under `root` with a shared `MeshStandardNodeMaterial` bound to the atlas `tex` (roughness 0.85, metalness 0), and turns on `castShadow`/`receiveShadow`.
+
+**One material per (atlas, emissive, transparency, skinned-flag), shared by every model.** This is not a memory nicety, it is a pipeline-compile fix: per-model fresh materials meant each first-seen model compiled its own WebGPU pipeline family (the shop's 2.7 s per-item hover stalls, `pipe:+10` in the freeze telemetry). With a shared instance plus the uniform Synty vertex layout, a new model reuses a pipeline the world already compiled at boot → `pipe:0`.
+
+**CONTRACT: these materials are shared game-wide — never mutate one on an instance; clone first** (see `player.applyMoralityLook`).
+
+Details:
+
+- **Statics are flat-shaded** (`flatShading: !o.isSkinnedMesh`): Synty meshes are authored flat, and merged vertex normals come out inverted on some env pieces — faces render pure black when the sun is on their front side (the villages sun-angle black-render; same fix that cured Bloodfang's black stairs, see `bloodfang.js`). Skinned meshes keep smooth normals — deformation needs them, and theirs aren't corrupted.
+- Source-material `transparent`/`opacity` are carried over into the cache key and the new material.
+- `emissive`, if given, becomes `emissiveMap` with white emissive colour.
+- Multi-material meshes map per-slot; a single-element array collapses back to a lone material.
+
+### `setAtlasEmissiveHook(fn)`
+
+Registers an optional TSL term added into every atlas material's `emissiveNode`. Signature: `(albedoNode) => node` — e.g. western's nearest-N lamp field, so props, faces and walls light for real after dark. **Register BEFORE the first `applyAtlas`/`instantiate` call — materials are cached**, and a material built before the hook exists never gets it. Any `emissive` map is preserved by **adding** the hook's term to it, never replacing it (a few atlas mats glow).
+
+### `applyFaceAtlas(root, mouthTex, freckleTex = null)` and `FACE_DECALS`
+
+The second texture. `applyAtlas` puts one map on a whole model, which is all an adult ever needs. A kid needs two: clothes/pupils/eyebrows/hair ride the body atlas, and his face is two decals on the **facial** atlases — a mouth, and a freckle spray, each drawn on transparent black. Run this **after** `applyAtlas`; it re-materials just the decals.
+
+The sheets are not interchangeable: the freckle mesh's UVs address the freckle sheet — hand it the mouth sheet and it samples a mouth at freckle UVs, a second mouth across the cheeks. So a child with no freckle texture has the decal **hidden** (`visible = false` — free, the renderer skips it), not mis-textured.
+
+Decal materials (cached per texture uuid) sit a hair's breadth off the face, so they must not sort and must not z-fight: `alphaTest: 0.5` (a hard cutout — no blending, no draw order) plus polygon offset (−2/−2) pulling them forward, `DoubleSide`. Decals do **not** cast shadows: a flat plane inside the head's own silhouette can only ever cast a wrong shadow, and skipping it saves two shadow draws per child.
+
+`FACE_DECALS` is the exported `Set` of the kid pack's two unskinned decal mesh names: `SM_Chr_Kid_Face_01` and `SM_Chr_Kid_Face_Freckles_01`. (`SM_Chr_Kid_Robot_Face_01` is the third — costume box, not cast, dropped by the keep list.)
+
+---
+
+## Animation clips
+
+### `loadClip(url, name) → Promise<THREE.AnimationClip>`
+
+Loads one clip, cached by url. Two paths:
+
+1. **Cooked JSON** (fast path): fetch `/assets/clips/<cooked-name>.json` and `THREE.AnimationClip.parse` it. Same cook-to-file scheme as the VAT/nav bins — FBXLoader parses on the main thread and the ~100 clip files dominate the loading bar's climb; a parsed `AnimationClip` round-trips losslessly through `toJSON`/`parse`.
+2. **FBX parse** (fallback): load the FBX and take the **longest** animation — MultiTake FBX (e.g. the gunslinger pack) lead with a 1-frame stub stack, and for single-take files the longest is `animations[0]` anyway. Throws if the file has no animation. In dev (`import.meta.env.DEV`), the parsed clip is cooked back to disk via `POST /__save-clipjson?name=…` (fire-and-forget; the live clip is returned regardless).
+
+The cooked filename is `<basename>-v<CLIP_JSON_VER>-<djb2(url) hex>.json`. **`CLIP_JSON_VER` (currently 2 — full-pack gsbake rebake, 97 clips, 2026-07-12) must be bumped after changing any source animation** — the name alone can't see content changes — or delete the `public/assets/clips` folder.
+
+The clip's `name` is set to the given `name`, falling back to the url basename without `.fbx`.
+
+### `loadClips(entries) → Promise<Record<string, THREE.AnimationClip>>`
+
+Loads a map of `{ name: url }` in parallel. **One bad/missing clip must not break the whole boot** — failures are warned and omitted from the result; the animator falls back to `'idle'`.
+
+---
+
+## Loading progress
+
+### `onProgress(cb)` / `expectLoads(n)`
+
+`expectLoads(n)` adds `n` to the expected total; every completed model/clip/GLB load ticks the counter and calls `cb(loadedCount, totalCount, msg)` where `msg` is the file basename or clip name. `loadTexture` does **not** tick.
+
+---
+
+## Example
+
+```js
+import {
+  expectLoads, onProgress, setAtlasEmissiveHook,
+  instantiate, applyAtlas, applyFaceAtlas, loadTexture, loadClips, warmTextures,
+} from './core/assets.js';
+
+// Order matters: hook before any material is built (materials are cached).
+setAtlasEmissiveHook((albedo) => lampFieldTerm(albedo));
+
+onProgress((done, total, msg) => loadingBar.set(done / total, msg));
+expectLoads(3);
+
+// A kid: five meshes out of a 100-character pack, collapsed to one skeleton.
+const kid = await instantiate('/assets/characters/kids/Characters_Kids.fbx', {
+  collapse: true,
+  keep: ['SM_Chr_Kid_Western_02', 'SM_Chr_Kid_Face_01', 'SM_Chr_Kid_Face_Freckles_01',
+         'SM_Chr_Eyes_Brown_01', 'SM_Chr_Eyebrows_01'],
+  hair: ['SM_Chr_Hair_Messy_01'],
+  texture: '/assets/characters/kids/PolygonKids_Texture_01_A.png',
+});
+// Face decals ride their own sheets, after applyAtlas has run (loadModel ran it).
+applyFaceAtlas(kid, await loadTexture('/assets/characters/kids/Face_Mouth_01.png'));
+scene.add(kid);
+
+const clips = await loadClips({ idle: '/assets/anims/Idle.fbx', walk: '/assets/anims/Walk.fbx' });
+
+// Under the loading screen — compileAsync does NOT upload textures.
+await warmTextures(renderer);
+```
+
+---
+
+## Gotchas
+
+- **Register `setAtlasEmissiveHook` before the first `applyAtlas`/`instantiate`.** Atlas materials are cached; ones built before the hook never receive the emissive term.
+- **Never mutate a shared atlas material on an instance — clone first.** One material per (atlas, emissive, transparency, skinned) is a WebGPU pipeline-compile fix, not just a memory saving; mutating it changes every model in the game.
+- **The model cache key is `url|texture|scale`.** Do not assume one url = one master. The url-only key was the all-bodies-render-black bug (raw `MeshLambertMaterial` with an unresolvable texture renders black, not tinted).
+- **flipY is part of the texture cache key, and it depends on what loaded.** GLB (glTF UVs) wants the atlas at `flipY:false`; FBX wants the default `true`. Callers that build their own materials from flattened geometry must call `resolveModelUrl` to learn which format actually loaded — skipping that was the mirrored-atlas-cell bug on every scatter-placed prop.
+- **Scale defaults differ by format and must.** FBX is cm-authored (`0.01`); converted GLBs are already metres (`1`). Applying `0.01` to a metre GLB shrank every tropical prop 100× — microscopic, invisible. Exception: the metre-authored dungeon kit's twins carry a baked ×100 rescale and load at `scale:1`.
+- **Never look bones up by name across a multi-character pack.** 21 bones answered to `Hips` in one western pack, 100 to `Head` in the kids pack, and the depth-first hit is not the one the mesh is skinned to — that was the contorted-limbs bug (arms flung overhead, hands inside out). Resolve bones through a named mesh's own skeleton (as `headBoneOfMesh` does), or from the mixer's own bindings (as `player.js`/`footsteps.js` do). Name lookup is only safe *inside one skeleton* where names are unique.
+- **`keep` must prune rival skeletons, and the prune must be transform-exact.** FBXLoader nests the pack's skeletons inside one another, one duplicate per bone name per body; the outermost copy carries the real bind offset and is the one `PropertyBinding` finds, every copy below is an identity pass-through. Three walks every Object3D every frame in `updateMatrixWorld`, visible or not — 23 children once put 117,000 dead bones in the graph at 32 ms/frame of render cost. After the prune+collapse: 276k scene nodes → 25k, render 42 ms → 6.6 ms. The identity tolerances in `isIdentity` are float-noise wide on purpose — a bone with a real offset must never be collapsed away.
+- **Multi-mesh characters need `collapse`, and it must run on the master, before cloning.** The keep-prune alone would cut the bones the face decals hang from; `collapseSkeletons` rebinds instead (0.000 mm drift, 5,082 → 51 bones) and is memoised so the second clone is free.
+- **`compileAsync` does not upload textures — call `warmTextures` under the loading screen**, or pay ~75 ms per texture on first sight mid-play.
+- **The 2048 atlas downscale is retired; the embedded-texture dedup is the memory diet now.** Downscaled atlases came out wrong-coloured on small parts (mip-chain sampling of the resized canvas). The original problem was real — ~8 GB of resident textures caused recurring spin-jolts (weak renderer object cache + GC evictions) and poisoned-bind-group black screens — but the fix moved to sharing one texture per unique embedded image.
+- **Bump `CLIP_JSON_VER` after changing any source animation** (or delete `public/assets/clips`) — the cooked-JSON filename hashes the url, not the content, so stale cooks are served forever otherwise.
+- **MultiTake FBX clip files lead with a 1-frame stub** — `loadClip` takes the longest take, not `animations[0]`.
+- **One bad clip must not kill a boot** — `loadClips` warns and omits; keep an `'idle'` fallback in the animator.
+- **FBX loads stack stray lights and parse on the main thread.** Embedded AmbientLights are stripped on load (they washed out the whole scene). Prefer GLB twins for anything batch-loaded — FBX parsing was the tropical-beach load hang. `window.__fbxLoads` lists what still parses FBX in dev.
+- **GLB twins were converted with fbx2gltf's default V-flip** — a batch converted with `--no-flip-v` mirrored every atlas cell and had to be reverted.

package/docs/api/collision.md

@@ -0,0 +1,101 @@
+# Collision (`src/world/collision.js`, `src/world/bvhWorker.js`)
+
+Unified mesh collision built on [`three-mesh-bvh`](https://github.com/gkjohnson/three-mesh-bvh). Static collider geometry is baked into **one merged, position-only, non-indexed `BufferGeometry`** (world transforms applied) and a `MeshBVH` is built over it. The player capsule is then swept against that BVH each frame (see `world.moveCapsule`), so stairs, walls and slopes "just work" as real triangles — no per-object 2D colliders or heightfield hacks. The merged mesh is never rendered.
+
+There are two builders with identical results:
+
+- `buildBVH()` — synchronous, on the main thread.
+- `buildBVHAsync()` — same bake+merge+BVH (the ~30–80 ms cost) in a Web Worker (`bvhWorker.js`), used for streamed tiles so collision never blocks the frame. Falls back to the sync path if the worker is unavailable or dies.
+
+Both are re-exported from the package root (`src/index.js`).
+
+## Peer dependencies
+
+`three-mesh-bvh` (`^0.9.10`) and `three` (`^0.184.0`) are **peer dependencies** — the host app must install them. `three-mesh-bvh` is geometry/math only (no renderer calls), so it is safe under the `three/webgpu` renderer and inside a worker; the module feeds it plain `BufferGeometry` data.
+
+## Exports
+
+### `buildBVH(objs = [], instanceGroups = []) → MeshBVH | null`
+
+Merges every mesh under `objs` (world matrices baked, position attribute only) and returns a `MeshBVH` over the result, or `null` if there is no geometry.
+
+- `objs`: array of `Object3D`s. Each is traversed (`updateMatrixWorld(true)` is called first) and every `Mesh` with a position attribute is baked at its **current** matrix:
+  - **Regular meshes** — geometry baked once at `matrixWorld`.
+  - **`InstancedMesh`** — the geometry is baked once **per instance** at `matrixWorld × instanceMatrix`.
+  - Meshes with `userData.noBVH` are skipped (see gotchas).
+- `instanceGroups`: array of `{ geometry, matrices: Float32Array(count*16), count }` — explicit LOD0 geometry plus the **full** instance set, baked from world matrices. Used for distance-LOD scatters (e.g. rocks), so collision always uses LOD0 — never the far LOD — across all instances, regardless of what LOD is currently rendered.
+
+Per-source geometry handling: the geometry is cloned, every attribute except `position` is deleted, the world matrix is applied, and indexed geometry is converted with `toNonIndexed()` so `mergeGeometries` doesn't mismatch indexed/non-indexed inputs.
+
+### `buildBVHAsync(objs = [], instanceGroups = []) → Promise<MeshBVH | null>`
+
+Same inputs and same collision result as `buildBVH()`, but the heavy work runs in a Web Worker. Returns a real `MeshBVH` that answers `.shapecast()` / `.raycastFirst()` identically — it's just built off the hot path.
+
+Flow:
+
+1. `extractParts()` gathers serializable data **without mutating or neutering the live geometry**: it copies each source `position` array and `index` array, and the **world** matrix of every instance, into fresh typed arrays. Parts are `{ positions, index|null, matrices, count }`.
+2. The parts are posted to the worker with all buffers **transferred** (zero-copy; safe because they are copies).
+3. The worker bakes every instance into one big position buffer, builds a `MeshBVH`, serializes it, and transfers the result back.
+4. The main thread reconstructs a position-only `BufferGeometry` and calls `MeshBVH.deserialize(serialized, geom, { setIndex: true, indirect: … })`.
+
+Fallback behavior:
+
+- Worker construction fails (`new Worker` throws) → the module is marked broken and **every** call, current and future, uses synchronous `buildBVH()`.
+- Worker fires `onerror` → all in-flight jobs resolve `null`, the module is marked broken; `buildBVHAsync` detects the death and rebuilds **synchronously** so the tile still collides. Later calls go straight to the sync path.
+- Worker replies `ok: false` for a single job (an error thrown inside `buildFromParts`, or empty geometry) → that call resolves `null`. There is **no** sync retry in this case — a per-job failure is not treated as a dead worker.
+- No parts extracted (no geometry) → resolves `null` without touching the worker.
+
+### `colliderWireframe(bvh) → THREE.Mesh | null`
+
+Dev visualization: a green (`0x00ff88`) wireframe `Mesh` of the merged collision geometry (`transparent`, `opacity: 0.4`, `depthTest: false`, `renderOrder: 999`), so the collider can be eyeballed without trusting the renderer's BVH helper. Returns `null` if `bvh` is falsy. Add it to the scene yourself; remember it shares the BVH's geometry, so don't dispose that geometry while the BVH is live.
+
+## Worker protocol (`bvhWorker.js`)
+
+Internal, but documented for maintenance. The main thread posts:
+
+```
+{ id, parts: [{ positions: Float32Array,
+                index: Uint16Array|Uint32Array|null,
+                matrices: Float32Array(count*16),   // WORLD transforms per instance
+                count }] }
+```
+
+The worker (`buildFromParts`) expands indexed parts to non-indexed, then bakes every instance of every part into **one** preallocated `Float32Array` using inlined matrix×point math — no per-instance geometry allocations (this mirrors `buildBVH` but avoids `clone()`/`mergeGeometries` overhead). It builds a `MeshBVH` (which creates a sequential index internally), serializes it with `{ cloneBuffers: false }`, and posts back:
+
+```
+{ id, ok: true, serialized, position }      // buffers transferred (zero-copy)
+{ id, ok: false, empty: true }              // no geometry
+{ id, ok: false, error: "…" }               // build threw
+```
+
+## Example
+
+```js
+import { buildBVHAsync, colliderWireframe } from 'sindicate/world/collision.js';
+
+// A streamed tile finished loading: buildings group + a rock scatter that
+// renders with distance LODs but must always collide as LOD0.
+const bvh = await buildBVHAsync(
+  [tile.buildingsGroup, tile.propsGroup],           // regular + instanced meshes
+  [{ geometry: rockLOD0Geometry,                    // LOD0 only — never the far LOD
+     matrices: rockWorldMatrices,                   // Float32Array, count*16
+     count: rockCount }],
+);
+tile.collider = bvh; // may be null (empty tile) — moveCapsule must tolerate that
+
+// Dev toggle: eyeball the collider.
+if (DEBUG_COLLIDERS && bvh) scene.add(colliderWireframe(bvh));
+```
+
+## Gotchas
+
+- **The BVH is baked once and frozen.** Anything that later moves would still be collided at the pose it had at boot — the door would swing open in front of you while its shut-pose triangles still stood in the doorway. Opt moving parts out with `userData.noBVH`. (The county's door leaves ride a `BatchedMesh` at the scene root, which the traversal never reaches, so the flag is belt and braces there; doors collide via the switchable slab in `world.collide()` — see `town.js` `doorsAt`.)
+- **Instances are baked at their current matrices.** `updateMatrixWorld(true)` is called on each root before traversal, but instance matrices are read as-is — build the BVH only after all instance transforms are final.
+- **Use `instanceGroups` for LOD scatters.** If you pass a distance-LOD `InstancedMesh` via `objs`, collision would use whatever LOD geometry that mesh happens to carry. Pass `{ geometry: LOD0, matrices, count }` instead so the collider is always the full-detail mesh across all instances.
+- **Position-only, non-indexed.** All other attributes are stripped and indexed geometry is expanded before merging (indexed/non-indexed inputs can't be mixed in `mergeGeometries`). Don't expect UVs/normals or the original index on `bvh.geometry`.
+- **Worker imports plain `'three'`, NOT `'three/webgpu'`.** The webgpu entry pulls in renderer/DOM code that has no `document`/`window` in a worker. `three-mesh-bvh` is pure math and worker-safe. The main-thread module uses `three/webgpu`; keep that split.
+- **Why the worker exists:** the tile streamer used to bake+merge+build synchronously in `World.update()` — ~30–80 ms **per tile**, which was the constant town/exploration stutter (the `world` phase in the freeze log). Don't move this work back to the hot path.
+- **`extractParts` copies before transferring.** Transferring the live geometry's buffers would neuter them (the rendered mesh would lose its vertex data). The copies are what gets transferred — keep it that way if you touch this code.
+- **`buildBVHAsync` can return `null`** for empty geometry *and* for a per-job worker error. Callers must handle a null collider.
+- **Worker fallback is one-way.** Once `_workerBroken` is set (construction failure or `onerror`), all subsequent builds are synchronous for the lifetime of the page; there is no retry/respawn.
+- **Deserialization must match serialization.** The main thread passes `{ setIndex: true, indirect: Boolean(serialized.indirectBuffer) }` to `MeshBVH.deserialize`; the worker serializes with `{ cloneBuffers: false }` and transfers `position`, `serialized.roots`, and the index/indirect buffers. If you change either side, change both.

package/docs/api/fbxloader.md

@@ -0,0 +1,50 @@
+# vendor/FBXLoader
+
+Vendored copy of three.js's `FBXLoader` (addons) with **one local patch**: `AnimationParser.parseAnimStacks` merges **all** animation layers in a stack into the clip, where stock three keeps only the first layer and discards the rest.
+
+This fork exists so the engine does **not** depend on a `node_modules` postinstall mutation (the approach western/fable used — it breaks under CI caches/pnpm and was anchored to an exact three source line). Engine code changes only here.
+
+## Why the patch exists
+
+Synty animation FBX files frequently store their curves across multiple `AnimationLayer` nodes per `AnimationStack`. Stock FBXLoader assumes one layer per stack ("in practice there always seems to be one"), takes the first, and ignores the rest — so the resulting `AnimationClip` loses the tracks that live in later layers and multi-layer Synty packs play back as a T-pose. The patch (marked `/* synty-all-layers */`, in `parseAnimStacks`) collects the curve nodes from every child layer instead:
+
+```js
+/* synty-all-layers */ const layer = [];
+for ( const child of children ) {
+    const l = layersMap.get( child.ID );
+    // layer arrays are SPARSE — spread turns holes into undefined,
+    // which crashes generateTracks. Filter them out.
+    if ( l ) layer.push( ...l.filter( ( n ) => n !== undefined ) );
+}
+```
+
+## Exports
+
+- `FBXLoader` — class, extends `THREE.Loader`.
+  - `constructor( manager? )`
+  - `load( url, onLoad, onProgress, onError )` — loads and parses; `onLoad` receives a `Group`.
+  - `parse( FBXBuffer, path )` → `Group` — parses an `ArrayBuffer` (binary FBX >= 6400 or ASCII >= 7.0). Clips arrive on `group.animations`.
+
+Re-exported from the engine root (`sindicate`), so games never import three's stock loader.
+
+## Usage
+
+```js
+import { FBXLoader } from 'sindicate'; // or '../vendor/FBXLoader.js'
+
+const loader = new FBXLoader();
+const group = await loader.loadAsync('assets/Chr_Cowboy_01.fbx');
+group.scale.setScalar(0.01);           // Synty FBX is authored in centimetres
+mixer.clipAction(group.animations[0]).play(); // all layers merged — no T-pose
+```
+
+(In practice, load characters through `core/assets.js`, which wraps this loader with caching, atlas binding, and cm→m scaling.)
+
+## Gotchas
+
+- **Pin: three `^0.184`. Re-verify on every three upgrade.** The fork is a snapshot of the r184 loader plus the patch; upstream FBXLoader drifts. three upgrades are engine events: upgrade in Sindicate first, re-diff this file against the new stock loader, re-apply the patch, and run against western's bench pages before rolling to games.
+- **The multi-layer warning is stale.** The stock `console.warn` ("multiple layers … Ignoring subsequent layers") still fires on multi-layer stacks, but the patched code *does* merge them. The message is wrong; the behavior is right.
+- **Layer arrays are sparse — keep the filter.** `layerCurveNodes` is indexed by model position and has holes. A bare spread turns holes into `undefined` entries, which crash `generateTracks`. The `.filter((n) => n !== undefined)` is load-bearing; preserve it on any re-apply.
+- **Main-thread parsing is slow.** FBX parsing hung batch scatter loads (the tropical-beach hang); the asset system dispatches to GLB twins where they exist and only falls back to this loader.
+- **Names are sanitized.** FBXLoader converts spaces to underscores in node names — retarget bone tables must match the sanitized names.
+- **Z-up→Y-up lives on container Object3Ds**, not in world transforms — code sampling bone transforms (retarget) must account for the container rotation.