sindicate 0.1.0 → 0.4.0

package/src/core/assets.js

@@ -0,0 +1,596 @@
+// Asset system: loads Synty FBX models + animation clips, binds atlas
+// textures (FBXLoader doesn't auto-link Synty's atlases), caches everything.
+import * as THREE from 'three/webgpu';
+import { texture, uv } from 'three/tsl';
+
+// Optional TSL term a game registers to be added into every atlas material's
+// emissiveNode (albedoNode) => node — e.g. western's nearest-N lamp field.
+// Register BEFORE the first applyAtlas/instantiate call (materials are cached).
+let atlasEmissiveHook = null;
+export function setAtlasEmissiveHook(fn) { atlasEmissiveHook = fn; }
+// Patched loader from vendor/ — merges ALL FBX animation layers per stack. The
+// engine does NOT depend on a node_modules postinstall patch.
+import { FBXLoader } from '../vendor/FBXLoader.js';
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
+import { clone as skeletonClone } from 'three/addons/utils/SkeletonUtils.js';
+
+const fbxLoader = new FBXLoader();
+const gltfLoader = new GLTFLoader();
+// the LOD .glb files are EXT_meshopt-compressed — without this decoder every
+// *_LOD*.glb fails to load, so trees (scatterLOD) and building LODs silently
+// never appear, leaving only invisible colliders behind.
+gltfLoader.setMeshoptDecoder(MeshoptDecoder);
+const texLoader = new THREE.TextureLoader();
+const gltfCache = new Map();
+
+const modelCache = new Map();   // url -> THREE.Group (master copy)
+const clipCache = new Map();    // url -> THREE.AnimationClip
+const texCache = new Map();     // url -> THREE.Texture
+
+let progressCb = null;
+let loadedCount = 0;
+let totalCount = 0;
+
+export function onProgress(cb) { progressCb = cb; }
+
+function tick(msg) {
+  loadedCount++;
+  progressCb?.(loadedCount, totalCount, msg);
+}
+
+export function expectLoads(n) { totalCount += n; }
+
+// GPU MEMORY DIET (re-landed solo): ~8GB of textures were resident — Synty atlases are
+// flat palettes, 4096² carries nothing 2048² doesn't, and the pressure causes recurring
+// spin-jolts (renderer's weak object cache + GC evictions under memory strain) plus the
+// old poisoned-bind-group black screens. ?fulltex disables for an A/B eyeball.
+
+export async function loadTexture(url, { flipY } = {}) {
+  // flipY-specific cache key: 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.
+  const key = flipY === undefined ? url : `${url}|flip${flipY ? 1 : 0}`;
+  if (texCache.has(key)) return texCache.get(key);
+  const p = texLoader.loadAsync(url).then((t) => {
+    // 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 below carries the memory diet instead. ?fulltex is dead.
+    t.colorSpace = THREE.SRGBColorSpace;
+    // Synty atlases are flat color blocks — nearest avoids edge bleeding
+    // between atlas cells when mipmapped at glancing angles.
+    t.minFilter = THREE.LinearMipmapLinearFilter;
+    t.magFilter = THREE.LinearFilter;
+    if (flipY !== undefined) t.flipY = flipY;
+    t.needsUpdate = true;
+    return t;
+  });
+  texCache.set(key, p);
+  return p;
+}
+
+// Force-upload every cached texture to the GPU. The boot warm's compileAsync compiles PIPELINES
+// but does NOT upload textures — each then uploaded on FIRST SIGHT mid-play instead (~75ms hitch
+// apiece, measured by the freeze profiler as tex:+1 records). Run under the loading screen.
+// Safe to call again later (phase-2): initTexture on an already-resident texture is a no-op.
+export async function warmTextures(renderer) {
+  let n = 0;
+  for (const p of texCache.values()) {
+    try { renderer.initTexture(await p); n++; } catch (e) { /* failed load — nothing to warm */ }
+  }
+  return n;
+}
+
+// The 'Head' bone of a skinned model (for seating hair/beard attachments), tolerant of
+// naming variants. Returns null for static models.
+function headBoneOf(model) {
+  let sm = null; model.traverse((o) => { if (o.isSkinnedMesh && !sm) sm = o; });
+  if (!sm) return null;
+  const skel = sm.skeleton;
+  let idx = skel.bones.findIndex((b) => b.name === 'Head');
+  if (idx < 0) idx = skel.bones.findIndex((b) => /head/i.test(b.name));
+  return idx < 0 ? null : skel.bones[idx];
+}
+
+// Synty source FBX are authored in centimetres; scale to metres.
+const SYNTY_SCALE = 0.01;
+
+// FBX→GLB redirect (re-land, recipe verified in /glbtest.html this time): scripts/
+// convert_runtime_statics.mjs converts every runtime static FBX to a same-dir .glb twin
+// (fbx2gltf --binary, DEFAULT V-flip — the reverted batch's --no-flip-v mirrored every
+// atlas cell) and lists them in glb-twins.json. Redirect ONLY when (a) an atlas texture
+// is supplied (applyAtlas replaces the GLB's materials, so conversion material fidelity
+// is irrelevant) and (b) no explicit scale (fbx callers mean cm→m 0.01; twins are already
+// metres). Missing manifest degrades to plain FBX loading.
+let glbTwins = null;
+const glbTwinsReady = fetch('/assets/glb-twins.json')
+  .then((r) => (r.ok ? r.json() : []))
+  .catch(() => [])
+  .then((a) => { glbTwins = new Set(a); });
+
+// EMBEDDED-TEXTURE DEDUP (memory diet, part 2): character/castle GLBs each embed their own
+// copy of shared atlases (atlas_fantasykingdom measured resident 3× ≈ 270MB alone). Key each
+// embedded image by dims + a 16×16 full-byte downsample hash and share ONE THREE.Texture per
+// unique image; duplicates are disposed before they ever reach the GPU. 64×64 full-byte
+// hash (16k+ samples) — distinct atlases cannot realistically collide.
+const _embedCache = new Map();
+const _hashCnv = typeof document !== 'undefined' ? document.createElement('canvas') : null;
+function dedupEmbeddedTextures(root) {
+  if (!_hashCnv) return;
+  root.traverse((o) => {
+    const mats = o.material ? (Array.isArray(o.material) ? o.material : [o.material]) : [];
+    for (const m of mats) {
+      for (const k of ['map', 'emissiveMap', 'normalMap', 'roughnessMap', 'metalnessMap', 'aoMap', 'alphaMap']) {
+        const t = m[k];
+        if (!t || !t.isTexture || !t.image || t.userData.__dedup) continue;
+        try {
+          const im = t.image, w = im.width || 0, h = im.height || 0;
+          if (!w) continue;
+          _hashCnv.width = 64; _hashCnv.height = 64;
+          const cx = _hashCnv.getContext('2d', { willReadFrequently: true });
+          cx.clearRect(0, 0, 64, 64);
+          cx.drawImage(im, 0, 0, 64, 64);
+          const px = cx.getImageData(0, 0, 64, 64).data;
+          let hsh = (w * 31 + h) | 0;
+          for (let i = 0; i < px.length; i++) hsh = ((hsh << 5) - hsh + px[i]) | 0;
+          const key = `${w}x${h}:${hsh}:${t.flipY ? 1 : 0}:${t.colorSpace}`;
+          const kept = _embedCache.get(key);
+          if (kept && kept !== t) { m[k] = kept; t.dispose(); }
+          else { t.userData.__dedup = true; _embedCache.set(key, t); }
+        } catch (e) { /* unreadable image type — keep as-is */ }
+      }
+    }
+  });
+}
+
+// The redirect decision, 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 / washed stall tents) after the twins landed.
+export async function resolveModelUrl(url, { texture = null, scale, twin = false } = {}) {
+  // scale===undefined → cm-authored pack, twin is metres, loader default 1 fits.
+  // DUNGEON kit is metre-authored with cm FBX headers: callers pass scale:1 and the raw
+  // twins came out 100× small — those twins carry a baked ×100 root rescale
+  // (scripts note in convert_runtime_statics.mjs), so scale:1 loads them correctly.
+  // `twin: true` opts in texture-less callers whose downstream DISCARDS the file's own
+  // materials anyway (scatterTree UV-splits geometry and builds its own mats).
+  const redirectable = scale === undefined || (scale === 1 && /\/assets\/dungeon\//.test(url));
+  if (/\.fbx$/i.test(url) && (texture || twin) && redirectable) {
+    if (!glbTwins) await glbTwinsReady;
+    if (glbTwins.has(url)) return url.replace(/\.fbx$/i, '.glb');
+  }
+  return url;
+}
+
+export async function loadModel(url, { texture = null, scale, twin = false } = {}) {
+  url = await resolveModelUrl(url, { texture, scale, twin });
+  // CACHE BY WHAT ACTUALLY VARIES: url + atlas + scale. Keying by url ALONE meant the first
+  // caller to load a file decided its skin for the whole run — every later caller asking for the
+  // same body in a different atlas silently got the first one's master back. Worse, a caller that
+  // wanted no texture at all cached a master whose materials had never been through applyAtlas, so
+  // everyone downstream inherited the raw FBX's MeshLambertMaterial pointing at a texture that
+  // does not resolve. That is not a subtle wrong tint: it renders BLACK. It blacked out all 29
+  // bodies in the casting bench, then 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.
+  const key = `${url}|${texture ?? ''}|${scale ?? 'auto'}`;
+  if (!modelCache.has(key)) {
+    // Dispatch by extension: FBXLoader parses on the main thread and is far too slow
+    // for batch scatter (the tropical-beach load hang) — a .glb of the same model loads
+    // through GLTFLoader an order of magnitude faster. UNITS DIFFER by source, so the
+    // default scale does too: Synty FBX is authored in centimetres (× SYNTY_SCALE 0.01
+    // → metres), whereas the fbx2gltf-converted biome .glb is ALREADY in metres (the
+    // converter baked the cm→m factor) → loads at 1:1. Applying 0.01 to those metre-scale
+    // GLBs shrank every tropical prop 100× → microscopic, invisible (the palms/rocks).
+    const isGLB = /\.glb$/i.test(url);
+    if (scale === undefined) scale = isGLB ? 1 : SYNTY_SCALE;
+    const load = isGLB
+      ? gltfLoader.loadAsync(url).then((g) => { g.scene.animations = g.animations ?? []; dedupEmbeddedTextures(g.scene); return g.scene; })   // FBX carries clips ON the model; glTF returns them separately — the VAT bakers read .animations
+      : ((window.__fbxLoads ??= []).push(url), fbxLoader.loadAsync(url));   // dev census: what still parses FBX (window.__fbxLoads)
+    const p = load.then(async (group) => {
+      group.scale.setScalar(scale);
+      // Strip any lights the source file carries — Synty FBX embed a grey AmbientLight in their
+      // global settings, so every loaded model stacked one (7+ at intensity 1) and washed out the
+      // whole scene, including the dungeon's dark mood. We light the world explicitly; FBX never should.
+      const stray = []; group.traverse((o) => { if (o.isLight) stray.push(o); }); stray.forEach((l) => l.removeFromParent());
+      if (texture) {
+        // GLB models carry glTF-convention UVs (top-left origin), so the atlas must NOT be flipped
+        // vertically or every cell samples its vertical mirror (skin→blue, clothing swapped). FBX
+        // models keep the TextureLoader default (flipY true). Same fix as the packed dwarf GLB atlas.
+        const tex = await loadTexture(texture, isGLB ? { flipY: false } : {});
+        applyAtlas(group, tex);
+      }
+      tick(url.split('/').pop());
+      return group;
+    });
+    p.catch(() => modelCache.delete(key));   // a transient 404 must not cache the rejection forever — retries re-fetch
+    modelCache.set(key, p);
+  }
+  return modelCache.get(key);
+}
+
+// A bone contributing nothing: the identity pass-throughs the multi-character FBX packs stack up
+// (see instantiate's keep path). Tolerances are float-noise wide, not "close enough" wide — a bone
+// with a REAL offset must never be collapsed away.
+function isIdentity(o) {
+  return o.position.lengthSq() < 1e-8
+    && Math.abs(Math.abs(o.quaternion.w) - 1) < 1e-6
+    && Math.abs(o.scale.x - 1) < 1e-5 && Math.abs(o.scale.y - 1) < 1e-5 && Math.abs(o.scale.z - 1) < 1e-5;
+}
+
+// ════════════════════════════════════════════════════════════════════════════════════════════════
+// COLLAPSE A 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.
+//
+// The keep-path prune below (instantiate) cuts a pack's rival skeletons down to the body's own,
+// and that is enough when a character IS one mesh, which every adult here is: Synty bakes an
+// adult's hair and face into his body. A CHILD IS FIVE MESHES — outfit + mouth decal + freckle
+// decal + pupils + eyebrows — and the parts DO NOT BELONG TO HIM:
+//
+//   · SM_Chr_Kid_Face_01 / _Face_Freckles_01 are unskinned, and hang off the Head bone of
+//     SM_Chr_Kid_EASTERN_01 — whichever child you asked for.
+//   · SM_Chr_Eyes_*_01 / SM_Chr_Eyebrows_01 are skinned to Eyes_/Eyebrow_ bones belonging to
+//     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 one of those skeletons coincides, so a child standing still 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.
+//
+// So rebind every mesh onto ONE reference skeleton — the SHALLOWEST, because every rival is nested
+// INSIDE it and so its own bones cannot move when the rivals are cut — re-parent the face decals to
+// THAT skeleton's Head, and snip the 5,031 rivals. Measured on all 106 meshes: 0.000 mm of drift,
+// 5,082 bones → 51. Run ONCE on the shared MASTER (memoised), so every child cloned from it is born
+// with 51 bones and the clone is cheap.
+export function collapseSkeletons(model) {
+  if (model.userData.__collapsed) return model.userData.__collapsed;
+  // the reference: the skeleton whose Hips sit nearest the root. `>= 51` skips the 2-bone
+  // eye/eyebrow skeletons, which are not candidates for anything.
+  let ref = null, best = Infinity;
+  model.traverse((o) => {
+    if (!o.isSkinnedMesh || o.skeleton.bones.length < 51) return;
+    const hips = o.skeleton.bones.find((x) => x.name === 'Hips');
+    let d = 0; for (let p = hips; p; p = p.parent) d++;
+    if (d < best) { best = d; ref = o.skeleton; }
+  });
+  if (!ref) return null;
+  const bone = (n) => ref.bones.find((x) => x.name === n);
+  model.traverse((o) => {
+    if (!o.isSkinnedMesh) return;
+    // an OUTFIT: 51 bones in the same order as the reference → just point it at the reference
+    if (o.skeleton.bones.length === ref.bones.length) { o.bind(ref, o.bindMatrix); return; }
+    // EYES / EYEBROWS: 2 bones, matched by name. Eyes_Left, Eyebrow_Right… are unique within the
+    // 51, so a name lookup INSIDE the reference is exact — this is not the by-name lookup across
+    // the whole pack that the duplicate-bone trap punishes.
+    const bones = o.skeleton.bones.map((x) => bone(x.name));
+    if (bones.every(Boolean)) o.bind(new THREE.Skeleton(bones, o.skeleton.boneInverses), o.bindMatrix);
+    else console.warn('[collapse] cannot rebind', o.name);
+  });
+  // the face decals: unskinned meshes parented to SOME bone. They sit at local identity on a Head,
+  // so moving them to the reference's Head is transform-exact.
+  const head = bone('Head');
+  const decals = [];
+  model.traverse((o) => { if (o.isMesh && !o.isSkinnedMesh && o.parent?.isBone) decals.push(o); });
+  if (head) decals.forEach((d) => { d.removeFromParent(); head.add(d); });
+  // and now the rivals. Cutting at the boundary (a non-kept bone whose PARENT is kept) takes each
+  // whole nested subtree in one snip and can never orphan a bone we still use.
+  const keep = new Set(ref.bones), cut = [];
+  model.traverse((o) => { if (o.isBone && !keep.has(o) && o.parent && keep.has(o.parent)) cut.push(o); });
+  cut.forEach((o) => o.removeFromParent());
+  model.updateMatrixWorld(true);
+  model.userData.__collapsed = ref;
+  console.log(`[collapse] onto one skeleton: ${ref.bones.length} bones, ${decals.length} face decals re-parented, ${cut.length} rival chains cut`);
+  return ref;
+}
+
+// The Head bone reached THROUGH A NAMED MESH'S OWN SKELETON — never by a name search of the graph.
+// That is the whole lesson of the duplicate-bone trap: a hundred bones answer to 'Head' in the kid
+// pack, and the one a name search finds is not the one this child's body is skinned to.
+function headBoneOfMesh(model, meshName) {
+  let sm = null;
+  model.traverse((o) => { if (o.isSkinnedMesh && o.name === meshName) sm = o; });
+  return sm?.skeleton.bones.find((b) => b.name === 'Head') ?? null;
+}
+
+// HAIR AND HATS ARE AUTHORED IN DIFFERENT SPACES — in the same pack, from the same folder, and
+// nothing in the file says which. MEASURED: SM_Chr_Hair_Messy_01 spans Y 92.9..121.3 cm — absolute,
+// i.e. drawn already sitting on a head that is standing on the floor (RIG SPACE) — while
+// SM_Chr_Attach_Hat_Cowboy_01 spans Y -3.8..24.4 cm, i.e. relative to the Head bone, which binds at
+// Y 100.1 (HEAD-LOCAL). So classify by the mesh's own height and apply the transform that space
+// needs: rig-space geometry has the head's bind pose CANCELLED out of it (inverse(head.world) ·
+// root.world puts it exactly where a direct child of the root would sit, and the bone then carries
+// it); head-local geometry is simply parented. The kid Head binds with an identity rotation, so
+// there is no twist to undo either way.
+const RIG_SPACE_CM = 60;   // a hat's centroid is ~10 cm, a rig-space hairstyle's ~107 — nothing is near 60
+async function seatHeadProp(inst, bodyMesh, name) {
+  const src = await loadModel(`/assets/characters/kids/${name}.fbx`, { scale: 1 });   // scale 1 = keep centimetres
+  const att = src.clone(true);
+  const head = headBoneOfMesh(inst, bodyMesh);
+  if (!head) { console.warn('[hair] no head bone on', bodyMesh); return null; }
+  inst.updateMatrixWorld(true);
+  const box = new THREE.Box3().setFromObject(att);
+  if ((box.min.y + box.max.y) / 2 > RIG_SPACE_CM) {
+    att.applyMatrix4(new THREE.Matrix4().copy(head.matrixWorld).invert().multiply(inst.matrixWorld));
+  }
+  att.name = name;
+  head.add(att);
+  return att;
+}
+
+// THE SECOND TEXTURE. applyAtlas puts ONE map on a whole model, which is all an adult ever needs.
+// A kid needs two: his clothes, pupils, eyebrows and 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. So
+// this runs AFTER applyAtlas and re-materials just the decals.
+//
+// THEY ARE DIFFERENT SHEETS AND THEY 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, not mis-textured.
+// (visible=false is free: the renderer skips it, and it is set once on the loading screen.)
+//
+// A decal sits a hair's breadth off the face, so it must not sort and must not z-fight: alphaTest
+// (a hard cutout — no blending, no draw order) plus a polygon offset that pulls it forward. It does
+// NOT cast a shadow: it is a flat plane inside the head's own silhouette, so its shadow can only
+// ever be wrong, and skipping it saves two shadow draws per child.
+const faceMatCache = new Map();
+function faceMaterial(tex) {
+  let mat = faceMatCache.get(tex.uuid);
+  if (!mat) {
+    mat = new THREE.MeshStandardMaterial({
+      map: tex, transparent: true, alphaTest: 0.5, roughness: 0.9, metalness: 0,
+      side: THREE.DoubleSide, polygonOffset: true, polygonOffsetFactor: -2, polygonOffsetUnits: -2,
+    });
+    faceMatCache.set(tex.uuid, mat);
+  }
+  return mat;
+}
+export function applyFaceAtlas(root, mouthTex, freckleTex = null) {
+  const mouth = faceMaterial(mouthTex);
+  const freckles = freckleTex ? faceMaterial(freckleTex) : null;
+  root.traverse((o) => {
+    if (!o.isMesh || !FACE_DECALS.has(o.name)) return;
+    if (o.name === FRECKLE_DECAL) {
+      if (freckles) o.material = freckles; else o.visible = false;
+    } else o.material = mouth;
+    o.castShadow = false;
+    o.receiveShadow = false;
+  });
+}
+// The two unskinned decals of the kid pack. (SM_Chr_Kid_Robot_Face_01 is the third — costume box,
+// not cast, and it is dropped by the keep list.)
+const FRECKLE_DECAL = 'SM_Chr_Kid_Face_Freckles_01';
+export const FACE_DECALS = new Set(['SM_Chr_Kid_Face_01', FRECKLE_DECAL]);
+
+// Returns an independent copy safe to add to the scene.
+// SkinnedMesh needs SkeletonUtils.clone; static meshes can share geometry.
+export async function instantiate(url, opts) {
+  const master = await loadModel(url, opts);
+  // COLLAPSE FIRST, ON THE MASTER — before the clone, so a child is cloned with 51 bones and not
+  // with 5,082 of them to be pruned back down one at a time. Memoised inside; the second kid is
+  // free. Nothing else in the pipeline can do this job: see collapseSkeletons.
+  if (opts && opts.collapse) collapseSkeletons(master);
+  let hasSkin = false;
+  master.traverse((o) => { if (o.isSkinnedMesh) hasSkin = true; });
+  const inst = hasSkin ? skeletonClone(master) : master.clone();
+  // `keep`: for multi-character source files, drop every mesh except the one whose name matches.
+  // A LIST is allowed, and a child needs one: he is five meshes (body, mouth, freckles, pupils,
+  // eyebrows), not one. A lone string keeps the old single-substring behaviour every adult uses.
+  //
+  // AND THEN DROP THE OTHER CHARACTERS' BONES. The old code kept "the full skeleton" — which is
+  // right for a pack that shares ONE skeleton across its bodies (Dungeon Realms' 8 dwarves), and
+  // WRONG for the Synty western packs, where EVERY character carries its OWN skeleton. Keeping
+  // them left the extracted body dragging 8–27 rival skeletons around, ALL USING THE SAME BONE
+  // NAMES (Hips, Spine_01, Shoulder_R…). Everything downstream resolves bones BY NAME — three's
+  // PropertyBinding, and our captureBind — so they silently bound to another character's bones:
+  // measured on Character_GoldMiner_Male_01, 21 bones answered to "Hips" and the one the name
+  // lookup found was NOT the one its mesh is skinned to. That is the contorted-limbs bug (arms
+  // flung overhead, hands inside out), and it is the same duplicate-name hazard player.js and
+  // footsteps.js already work around by resolving bones from the mixer's own bindings.
+  if (opts && opts.keep) {
+    const keeps = (Array.isArray(opts.keep) ? opts.keep : [opts.keep]).map((s) => s.toLowerCase());
+    const drop = [];
+    inst.traverse((o) => {
+      if (o.isMesh && !keeps.some((k) => (o.name || '').toLowerCase().includes(k))) drop.push(o);
+    });
+    drop.forEach((o) => o.removeFromParent());
+
+    // ── AND THEN THE OTHER CHARACTERS' BONES, WHICH COST MORE THAN ANYTHING ELSE IN THIS FILE ──
+    //
+    // FBXLoader hands these multi-character packs back with the bodies' skeletons NESTED INSIDE
+    // ONE ANOTHER, one duplicate per bone NAME, per body:
+    //     Root > Root > Root > …            (8 deep in WesternTownChars, 100 in Characters_Kids)
+    //       Hips > Hips > Hips > …
+    //         Spine_01 > Spine_01 > …
+    // MEASURED (the running game, /assets/characters): the OUTERMOST copy of each name carries the
+    // real bind offset AND is the one three's PropertyBinding finds by name, so it is the one the
+    // mixer actually drives; every copy below it is a pure IDENTITY pass-through (position 0,
+    // quaternion 1, scale 1), and a body's own skeleton simply picks the copy at its own index.
+    // That is why this works at all — the extracted body inherits the animation through a stack of
+    // identity transforms.
+    //
+    // It is also why a keep-extracted body dragged the WHOLE PACK's bones around: 392 of them for
+    // one western townsman, and 5,082 for one child (the Kids pack has ~100 bodies). three walks
+    // every Object3D in the scene graph every frame in updateMatrixWorld, visible or not — so
+    // twenty-three children put 117,000 dead bones in the graph and cost 32 ms A FRAME, in the
+    // RENDER phase, for nothing. Measured: scene nodes 276k, render 42 ms; after this, 25k and
+    // 6.6 ms, which is FASTER than the fourteen-NPC town was before any of them existed.
+    //
+    // Two removals, both transform-EXACT, and the distinction is the whole safety argument:
+    //   1. PRUNE any bone that is neither ours nor an ANCESTOR of one of ours. Those are leafward
+    //      subtrees belonging to bodies we dropped; nothing references them and no kept bone's
+    //      parent chain runs through them.
+    //   2. COLLAPSE the identity pass-throughs BETWEEN the outermost copy and ours — a bone whose
+    //      own parent carries the same name is by construction a middle of such a chain. Its
+    //      children are re-parented to its parent, which changes no world transform because its
+    //      local transform is the identity (asserted, not assumed — a non-identity middle is left
+    //      alone). The OUTERMOST copy is never touched, so it is still the first hit of a
+    //      depth-first name search and the mixer binds exactly the node it bound before.
+    const own = new Set();
+    inst.traverse((o) => { if (o.isSkinnedMesh && o.skeleton) for (const b of o.skeleton.bones) if (b) own.add(b); });
+    if (own.size) {
+      const anc = new Set();
+      for (const b of own) { let p = b.parent; while (p && p.isBone) { anc.add(p); p = p.parent; } }
+      const cut = [], mid = [];
+      inst.traverse((o) => {
+        if (!o.isBone || own.has(o)) return;
+        if (!anc.has(o)) { cut.push(o); return; }                       // foreign subtree
+        if (o.parent?.isBone && o.parent.name === o.name && isIdentity(o)) mid.push(o);   // identity pass-through
+      });
+      for (const b of cut) b.removeFromParent();
+      for (const b of mid) {                                            // top-down: a middle's parent is final by the time we reach it
+        const p = b.parent;
+        if (!p) continue;
+        for (const c of [...b.children]) p.add(c);                      // add() re-parents and keeps the local transform
+        b.removeFromParent();
+      }
+    }
+  }
+  // `attach`: seat static head props (dwarf beards/hair) on the Head bone. The meshes are
+  // authored head-local and the pack's reorienting Head_Attachments node is pruned by
+  // fbx2gltf, so cancel the bone's bind-pose world rotation (att.local = inverse(bone world
+  // quat) after updateMatrixWorld) → the attachment renders upright and rides the head.
+  if (opts && opts.attach && opts.attach.length) {
+    inst.updateMatrixWorld(true);
+    const bone = headBoneOf(inst);
+    if (bone) {
+      const q = new THREE.Quaternion(); bone.getWorldQuaternion(q); q.invert();
+      for (const name of opts.attach) {
+        try {
+          const src = await loadGLB(`/assets/characters/attach/${name}.glb`);
+          const att = src.clone(true);
+          att.quaternion.copy(q);
+          bone.add(att);
+        } catch (e) { console.warn('[attach] failed', name, e); }
+      }
+    } else console.warn('[attach] no head bone on', url);
+  }
+  // `hair`: 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.
+  // They are 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 the whole model, bones and
+  // their children included, so the hair picks up the body atlas and therefore the atlas's hair
+  // COLOUR. (Which is the only colour it can have: every hair vertex sits on one texel of it.)
+  if (opts && opts.hair && opts.hair.length) {
+    const body = Array.isArray(opts.keep) ? opts.keep[0] : opts.keep;
+    for (const name of opts.hair) {
+      try { await seatHeadProp(inst, body, name); }
+      catch (e) { console.warn('[hair] failed', name, e); }
+    }
+  }
+  return inst;
+}
+
+// ONE material per (atlas, emissive, transparency) shared by EVERY model — not a memory
+// nicety, a pipeline-compile fix: per-model fresh materials meant each first-seen model
+// compiled its own WebGPU pipeline family (the shop's 2.7s per-item hover stalls,
+// pipe:+10 in the freeze telemetry). With a shared instance + 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).
+const atlasMatCache = new Map();
+export function applyAtlas(root, tex, { emissive = null } = {}) {
+  root.traverse((o) => {
+    if (!o.isMesh) return;
+    const mats = Array.isArray(o.material) ? o.material : [o.material];
+    o.material = mats.map((m) => {
+      const key = `${tex.uuid}|${emissive?.uuid ?? ''}|${m.transparent ? `t${m.opacity}` : 'o'}|${o.isSkinnedMesh ? 's' : 'f'}`;
+      let mat = atlasMatCache.get(key);
+      if (!mat) {
+        mat = new THREE.MeshStandardNodeMaterial({
+          map: tex,
+          roughness: 0.85,
+          metalness: 0.0,
+          // STATICS are flat-shaded: 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; theirs aren't corrupted).
+          flatShading: !o.isSkinnedMesh,
+        });
+        if (emissive) { mat.emissiveMap = emissive; mat.emissive = new THREE.Color(0xffffff); }
+        if (m.transparent) { mat.transparent = true; mat.opacity = m.opacity; }
+        // EMISSIVE HOOK: a game may register a world-lighting term (e.g. a nearest-N
+        // lamp field) that is ADDED into every atlas material's emissive so props,
+        // faces and walls light for real after dark. Preserve any emissiveMap by
+        // ADDING to it, never replacing it (a few atlas mats glow).
+        const albN = texture(tex, uv()).rgb;
+        const emisTex = emissive ? texture(emissive, uv()).rgb : null;
+        const hooked = atlasEmissiveHook ? atlasEmissiveHook(albN) : null;
+        mat.emissiveNode = hooked ? (emisTex ? emisTex.add(hooked) : hooked) : emisTex;
+        atlasMatCache.set(key, mat);
+      }
+      return mat;
+    });
+    if (o.material.length === 1) o.material = o.material[0];
+    o.castShadow = true;
+    o.receiveShadow = true;
+  });
+}
+
+// PARSED-CLIP FILES (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, so cook each to
+// public/assets/clips/<name>.json on first parse (self-written via /__save-clipjson)
+// and read the JSON on every later boot. Bump CLIP_JSON_VER after changing any source
+// animation (the name alone can't see content changes), or delete the folder.
+const CLIP_JSON_VER = 2; // v2: full-pack gsbake rebake (97 clips, 2026-07-12)
+function clipJsonName(url) {
+  let h = 5381;
+  for (let i = 0; i < url.length; i++) h = ((h << 5) + h + url.charCodeAt(i)) >>> 0;
+  return `${url.split('/').pop().replace(/\.fbx$/i, '').replace(/[^\w-]/g, '_')}-v${CLIP_JSON_VER}-${h.toString(16)}.json`;
+}
+export async function loadClip(url, name) {
+  if (!clipCache.has(url)) {
+    const jsonName = clipJsonName(url);
+    const p = (async () => {
+      try {
+        const r = await fetch(`/assets/clips/${jsonName}`);
+        if (r.ok) {
+          const clip = THREE.AnimationClip.parse(await r.json());
+          clip.name = name ?? url.split('/').pop().replace('.fbx', '');
+          tick(clip.name);
+          return clip;
+        }
+      } catch (e) { /* no json — parse the FBX below */ }
+      const g = await fbxLoader.loadAsync(url);
+      // MultiTake FBX (e.g. the gunslinger pack) lead with a 1-frame stub stack —
+      // take the LONGEST animation, which for single-take files is animations[0] anyway.
+      const clip = (g.animations ?? []).reduce((best, c) => (c.duration > (best?.duration ?? -1) ? c : best), null);
+      if (!clip) throw new Error(`No animation in ${url}`);
+      clip.name = name ?? url.split('/').pop().replace('.fbx', '');
+      if (import.meta.env?.DEV) {
+        try {
+          fetch(`/__save-clipjson?name=${jsonName}`, { method: 'POST', body: JSON.stringify(clip.toJSON()) }).catch(() => {});
+        } catch (e) { /* live clip still returned */ }
+      }
+      tick(clip.name);
+      return clip;
+    })();
+    clipCache.set(url, p);
+  }
+  return clipCache.get(url);
+}
+
+// Load a glodify LOD .glb (units preserved from the FBX source — cm).
+export async function loadGLB(url) {
+  if (!gltfCache.has(url)) {
+    const p = gltfLoader.loadAsync(url).then((g) => {
+      dedupEmbeddedTextures(g.scene);
+      tick(url.split('/').pop());
+      return g.scene;
+    });
+    gltfCache.set(url, p);
+  }
+  return gltfCache.get(url);
+}
+
+export async function loadClips(entries) {
+  const out = {};
+  await Promise.all(
+    Object.entries(entries).map(async ([name, url]) => {
+      // one bad/missing clip must not break the whole boot — the animator falls back to 'idle'
+      try { out[name] = await loadClip(url, name); }
+      catch (e) { console.warn(`clip "${name}" failed to load (${url})`, e); }
+    })
+  );
+  return out;
+}