sindicate 0.1.0 → 0.4.0

package/src/systems/entity.js

@@ -0,0 +1,524 @@
+// Character: base for player, NPCs and enemies — a loaded Synty character
+// with an Animator, health, faction and simple physics on the terrain.
+import * as THREE from 'three/webgpu';
+import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+import { instantiate, loadTexture, applyAtlas, applyFaceAtlas, resolveModelUrl } from '../core/assets.js';
+import { Animator } from '../core/anim.js';
+// A game may register a dress pass run on the player model after load
+// (western: face surgery + modular beard). setCharacterDressHook(async (model) => …)
+let dressHook = null;
+export function setCharacterDressHook(fn) { dressHook = fn; }
+import { angleLerp, dist2D } from '../core/utils.js';
+
+const _gripV = new THREE.Vector3();
+const _cullSphere = new THREE.Sphere(new THREE.Vector3(), 2.2); // body sphere for the off-screen frustum test
+const _steerV = new THREE.Vector3();                            // walkDir's steered output (shared tmp)
+const _steerA = new THREE.Vector3(), _steerB = new THREE.Vector3(); // whisker segment endpoints
+const _WHISK_A = [0, 0.61, -0.61, 1.22, -1.22];                 // whisker fan: 0°, ±35°, ±70°
+const _WHISK_L = [2.3, 1.9, 1.9, 1.5, 1.5];                     // centre feeler longest — earliest warning
+
+// Collapse a character's visible body parts into ONE SkinnedMesh.
+// Synty modular characters ship the body as 6–10 separate SkinnedMeshes (head, torso, arms,
+// legs, hands…). They already share ONE skeleton and ONE atlas texture, so merging their
+// geometry is lossless but turns ~8 draw calls per character into 1 — and, crucially, ONE
+// shadow-caster instead of 8 (the shadow pass re-draws every caster). At 25 on-screen NPCs
+// that's ~200 draws → ~25. The bones/skeleton are untouched so the Animator keeps driving it.
+// Robust: any failure leaves the original separate meshes in place (never breaks a character).
+// NOT for the player — gear swaps re-run applyOutfit, which needs the individual part meshes.
+export function mergeCharacterBody(model) {
+  try {
+    const meshes = [];
+    model.traverse((o) => { if (o.isSkinnedMesh && o.visible) meshes.push(o); });
+    if (meshes.length < 2) return false;
+    const skeleton = meshes[0].skeleton;
+    if (!meshes.every((m) => m.skeleton === skeleton)) return false; // don't merge across skeletons
+    // A merged mesh carries ONE material, so split by transparency (ghost enemies are translucent).
+    const groups = new Map();
+    for (const m of meshes) {
+      const mat = Array.isArray(m.material) ? m.material[0] : m.material;
+      const key = mat && mat.transparent ? 't' : 'o';
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(m);
+    }
+    const parent = meshes[0].parent;
+    const bindMatrix = meshes[0].bindMatrix;
+    let mergedAny = false;
+    for (const grp of groups.values()) {
+      if (grp.length < 2) continue;
+      let merged;
+      try { merged = BufferGeometryUtils.mergeGeometries(grp.map((m) => m.geometry), false); }
+      catch { continue; } // attribute mismatch (e.g. some parts have vertex colors) → leave as-is
+      if (!merged) continue;
+      const proto = Array.isArray(grp[0].material) ? grp[0].material[0] : grp[0].material;
+      const mesh = new THREE.SkinnedMesh(merged, proto);
+      mesh.bind(skeleton, bindMatrix);
+      mesh.frustumCulled = false;
+      mesh.castShadow = grp[0].castShadow;
+      mesh.receiveShadow = grp[0].receiveShadow;
+      mesh.name = 'Chr_merged';
+      parent.add(mesh);
+      for (const m of grp) m.removeFromParent();
+      mergedAny = true;
+    }
+    return mergedAny;
+  } catch (e) {
+    console.warn('[mergeCharacterBody] failed, keeping separate parts', e);
+    return false;
+  }
+}
+
+export class Character {
+  constructor(game, { model, texture, clips, scale = null, speed = 3, health = 50, faction = 'neutral', name = '', outfit = null, keep = null, attach = null, texFlipY = false, collapse = false, hair = null, faceTex = null, freckleTex = null, playerLook = false }) {
+    this.game = game;
+    this.modelUrl = model;
+    this.textureUrl = texture;
+    this.clipSet = clips;
+    // Model scale by source units: fbx2gltf/Blender GLBs are metres (load 1:1); Synty FBX are cm
+    // (× 0.01 → metres). Default is URL-aware so a model can be swapped .fbx↔.glb without touching
+    // its scale, EXCEPT where an explicit cm tweak was given (those get ×100'd at the call site).
+    this._rawScale = scale;        // null = derive from the RESOLVED url at load (twin-aware)
+    this.scale = scale != null ? scale : (/\.glb$/i.test(model || '') ? 1 : 0.01);
+    this.outfit = outfit;          // modular character: { gender, parts:{slot:meshName} } or null
+    this.keep = keep;              // packed multi-char source: keep only this body mesh (dwarves, the western packs).
+                                   // A LIST for a CHILD — he is five meshes, and keep[0] is the body (see assets.js).
+    this.attach = attach;          // head props to seat on the Head bone (beard/hair GLB names)
+    this.texFlipY = texFlipY;      // atlas V-flip for the keep path: dwarf GLB=false, the fbx2gltf goblin GLB=true
+    this.collapse = collapse;      // rebind the whole pack onto ONE skeleton before cloning (POLYGON Kids: 5082 bones → 51)
+    this.hair = hair;              // kid-pack hair/hat FBX names, hung off the Head bone
+    this.faceTex = faceTex;        // the FACIAL atlas — the mouth decal. A second texture on the same model.
+    this.playerLook = playerLook;  // PLAYER only: shave the built-in beard + seat the modular one (playerLook.js)
+    this.freckleTex = freckleTex;  // the freckle sheet (its own UVs — see applyFaceAtlas). null = no freckles.
+    this.name = name;
+    this.faction = faction;        // 'player' | 'villager' | 'guard' | 'hostile'
+    this.speed = speed;
+    this.maxHealth = health;
+    this.health = health;
+    this.alive = true;
+    this.root = new THREE.Group(); // moved by gameplay; model hangs under it
+    this.heading = 0;              // facing angle (radians, around Y)
+    this.velocity = new THREE.Vector3();
+    this.radius = 0.45;
+    this.capsuleSteps = 2;         // capsule substeps (cheap for NPCs; player ups it)
+    this.busy = false;             // one-shot anim in progress (attack, hit...)
+    this.staggerT = 0;
+    this.dead = false;
+  }
+
+  async load() {
+    if (this.keep) {
+      // packed multi-character GLB (Dungeon Realms dwarves): extract one body, seat head
+      // attachments, and apply the atlas with flipY=false (glTF UV) PER INSTANCE so A/B/C
+      // outfit recolours vary between dwarves. (The FBX-model path below keeps its own atlas.)
+      this.model = await instantiate(this.modelUrl, {
+        keep: this.keep, attach: this.attach, collapse: this.collapse, hair: this.hair,
+      });
+      // ONE atlas over the whole model — clothes, pupils, eyebrows, AND the hair hanging off the
+      // head bone (applyAtlas walks a bone's children too, which is exactly how a child's hair gets
+      // its colour). The MOUTH is the one thing this map is wrong for; the face atlas lands below.
+      if (this.textureUrl) applyAtlas(this.model, await loadTexture(this.textureUrl, { flipY: this.texFlipY }));
+    } else {
+      // TWIN-AWARE SCALE (the 1.8cm travellers): an EXPLICIT ctor scale means the caller
+      // tuned for this exact format (MountedTraveller's cm FBX seat origin) — forwarding
+      // it BLOCKS the twin redirect, preserving that choice. A defaulted scale re-sniffs
+      // units from the RESOLVED url: .fbx defs that redirect to metre twins load at 1
+      // (the unresolved sniff gave them ×0.01 → microscopic walkers).
+      const resolved = await resolveModelUrl(this.modelUrl, { texture: this.textureUrl, scale: this._rawScale ?? undefined });
+      if (this._rawScale == null) this.scale = /\.glb$/i.test(resolved) ? 1 : 0.01;
+      this.model = await instantiate(this.modelUrl, { texture: this.textureUrl, ...(this._rawScale != null ? { scale: this._rawScale } : {}) });
+    }
+    this.model.scale.setScalar(this.scale);
+    if (this.outfit) applyOutfit(this.model, this.outfit); // show only the equipped part meshes
+    this.model.traverse((o) => {
+      if (o.isMesh) { o.castShadow = true; o.frustumCulled = false; }
+    });
+    // PLAYER face: shave the merged beard/moustache + seat the chosen modular beard on the Head bone.
+    // After the traverse (so the beard mesh it adds inherits castShadow) and before grounding (which
+    // measures bones only, so the beard never shifts the feet). CLONES the body geometry, so NPC cowboys
+    // keep theirs. Awaited: it fetches a 26 KB beard glb.
+    if (this.playerLook) await dressHook?.(this.model);
+    // THE SECOND TEXTURE, and it goes on AFTER that traverse on purpose: the mouth decal must NOT
+    // cast a shadow (a flat plane inside the head's own silhouette — its shadow can only ever be
+    // wrong), and the line above would have switched it back on. applyFaceAtlas clears it again.
+    if (this.faceTex) {
+      applyFaceAtlas(this.model,
+        await loadTexture(this.faceTex, { flipY: this.texFlipY }),
+        this.freckleTex ? await loadTexture(this.freckleTex, { flipY: this.texFlipY }) : null);
+    }
+    // Body-part merge is OFF by default: most Synty characters here are already a single skinned
+    // mesh, so it rarely helps, and merging skinned geometry risks a bind-matrix distortion. Opt in
+    // with ?mergebody only for content that ships multi-part bodies. (The real character win is the
+    // frustum/off-screen cull, not fewer parts.)
+    if (this.faction !== 'player' && new URLSearchParams(location.search).has('mergebody')) {
+      mergeCharacterBody(this.model);
+    }
+    this.root.add(this.model);
+    // lift the model so its feet sit on the ground from frame 1 (origin is at the hips). Known
+    // value → no spawn pop; falls back to the deferred measure if no feetDrop is given.
+    if (this.outfit?.feetDrop != null) { this.model.position.y = this.outfit.feetDrop; this._baseModelY = this.model.position.y; this._grounded = true; }
+    else { this._groundFeet(); } // instant approximate from bind pose — the settle re-measure only corrects millimetres, so no sink-then-pop
+    this.animator = new Animator(this.model, this.clipSet);
+    // A CADENCE, if this body has one. The mixer's own rate, so EVERY clip it will ever play slows
+    // together — a child who ambles down the street but panics at a grown man's frame rate is a
+    // puppet with two operators. Set by npc.js for children (0.81: see the arithmetic there).
+    if (this._animRate && this.animator.mixer) this.animator.mixer.timeScale = this._animRate;
+    this.animator.play('idle');
+    return this;
+  }
+
+  // Offset the model so its lowest bone sits at the root origin (the ground), measured from
+  // the bind pose via bones (skinned-mesh bounding boxes are unreliable).
+  _groundFeet() {
+    this.model.updateWorldMatrix(true, true);
+    let minY = Infinity; const v = new THREE.Vector3();
+    this.model.traverse((o) => { if (o.isBone) { o.getWorldPosition(v); minY = Math.min(minY, v.y); } });
+    if (isFinite(minY)) { this.model.position.y -= minY - this.root.position.y; this._baseModelY = this.model.position.y; }
+  }
+
+  // Attachment parent for a bone that compensates for the model scale, so cm-scale props
+  // (tuned for the 0.01 peasant rig) sit correctly on a metre-scale rig (the modular hero).
+  // At ~0.01 scale the factor is 1 → attach straight to the bone (unchanged for cm rigs).
+  gripNodeFor(bone) {
+    bone.updateWorldMatrix(true, false);
+    const ws = bone.getWorldScale(_gripV).x || 1;
+    const g = 0.01 / ws; // cm-tuned props → metres, whatever the rig's actual bone world-scale is
+    if (Math.abs(g - 1) < 0.02) return bone;
+    if (!bone.userData.gripNode) { bone.userData.gripNode = new THREE.Group(); bone.add(bone.userData.gripNode); }
+    bone.userData.gripNode.scale.setScalar(g);
+    return bone.userData.gripNode;
+  }
+
+  // Attach a held prop (a guard's spear, a tool…) to a hand bone via the grip node so it
+  // sits right on any rig. KitForge GLB pieces carry no usable atlas, so texture them the
+  // KitForge way (flipY-true) when a texture is passed. Returns the prop (also on .propObj).
+  async equipProp(url, { texture, texFlipY = false, pos, rot, scale, bone = 'Hand_R' } = {}) {
+    let b = null;
+    this.model.traverse((o) => { if (!b && o.isBone && o.name === bone) b = o; });
+    if (!b) return null;
+    const obj = await instantiate(url);
+    if (texture) {
+      // CLONE the cached atlas before touching flipY/colorSpace — loadTexture returns a SHARED
+      // instance, and mutating it corrupts every other mesh that uses the same atlas (a wrong-flipY
+      // clone once V-flipped the whole PolygonFantasyKingdom set — people, buildings, props).
+      const tex = (await loadTexture(texture)).clone();
+      tex.flipY = texFlipY; tex.colorSpace = THREE.SRGBColorSpace; tex.needsUpdate = true;
+      obj.traverse((o) => { if (o.isMesh && o.material) { o.material.map = tex; o.material.needsUpdate = true; } });
+    }
+    obj.traverse((o) => { if (o.isMesh) { o.castShadow = true; o.frustumCulled = false; } });
+    this.gripNodeFor(b).add(obj);
+    if (scale != null) Array.isArray(scale) ? obj.scale.set(scale[0], scale[1], scale[2]) : obj.scale.setScalar(scale);
+    if (pos) obj.position.set(pos[0], pos[1], pos[2]);
+    if (rot) obj.rotation.set(rot[0], rot[1], rot[2]);
+    this.propObj = obj;
+    return obj;
+  }
+
+  get position() { return this.root.position; }
+
+  setPosition(x, y, z) { this.root.position.set(x, y, z); }
+
+  faceToward(x, z, dt = 1, rate = 12) {
+    const target = Math.atan2(x - this.position.x, z - this.position.z);
+    this.heading = angleLerp(this.heading, target, Math.min(1, dt * rate));
+    this.root.rotation.y = this.heading;
+  }
+
+  // Move with terrain-follow + static collision. dir is normalized XZ.
+  // While airborne (jumping), Y is left to the jump physics.
+  // Capsule-vs-world-BVH movement, so people collide with buildings/rocks/props
+  // /stairs too. Cull-frozen far entities never reach here (entity.update returns
+  // early), so this only runs for nearby ones.
+  move(dir, speed, dt) {
+    this.game.world.moveCapsule(this, dir.x * speed * dt, dir.z * speed * dt, dt);
+  }
+
+  // ---- Human-ish walking: steer around obstacles + other walkers instead of barging ----
+  // Whisker model (Nick's spec): probe FORWARD and ±45°; blocked ahead → swing toward the
+  // clear side; plus a soft lateral push away from nearby walkers/horses/the player, with
+  // head-on encounters passing on the LEFT (this is alt-Britain).
+  // PERF CONTRACT (must not eat fps): the probe (3 short whisker checks + one neighbour scan)
+  // runs every ~0.2s per walker, phase-staggered so only a few probe on any given frame, and
+  // ONLY within 45m of the player (beyond that they're culled/invisible anyway). Between
+  // probes the cached angle is smoothed — the per-frame cost is two multiplies.
+  walkDir(dir, dt) {
+    const g = this.game, pl = g.player;
+    if (!pl) return dir;
+    const dx = this.position.x - pl.position.x, dz = this.position.z - pl.position.z;
+    if (dx * dx + dz * dz > 45 * 45) { this._steerAng = 0; this._steerTarget = 0; return dir; }
+    this._steerT = (this._steerT ?? Math.random() * 0.15) - dt;   // random phase → staggered probes
+    if (this._steerT <= 0) { this._steerT = 0.15; this._steerTarget = this._probeSteer(dir); }
+    const curAng = this._steerAng ?? 0;
+    this._steerAng = curAng + Math.min(1, dt * 7) * ((this._steerTarget ?? 0) - curAng);
+    if (Math.abs(this._steerAng) < 0.02) return dir;
+    const c = Math.cos(this._steerAng), s = Math.sin(this._steerAng);   // +angle = left turn
+    return _steerV.set(dir.x * c + dir.z * s, 0, dir.z * c - dir.x * s);
+  }
+
+  _probeSteer(dir) {
+    const g = this.game, px = this.position.x, pz = this.position.z, py = this.position.y;
+    // Separation ALWAYS applies (v1 only ran it when the whiskers were clear — in the stall-packed
+    // market everything reads blocked, so walkers never separated and still overlapped at 0m).
+    let push = 0, headOn = false;
+    const consider = (o) => {
+      if (o === this || !o?.position || o.dead) return;
+      const ox = o.position.x - px, oz = o.position.z - pz;
+      const d2 = ox * ox + oz * oz;
+      if (d2 > 6.76) return;                                 // only within 2.6m
+      if (d2 < 0.01) { push += (this.root.id & 1) ? 0.9 : -0.9; return; }  // standing INSIDE someone → force apart (stable per-entity side)
+      if (ox * dir.x + oz * dir.z < -0.2) return;            // behind us — ignore
+      const side = dir.z * ox - dir.x * oz;                  // + = they're to our left
+      push -= Math.sign(side || 1) * 0.9 * (1 - Math.sqrt(d2) / 2.6);     // steer away — strong enough to visibly swerve
+      if (o.heading !== undefined && (Math.sin(o.heading) * dir.x + Math.cos(o.heading) * dir.z) < -0.5) headOn = true;
+    };
+    for (const n of g.npcs) consider(n);
+    if (g.travellers) for (const t of g.travellers) consider(t);
+    if (g.horses) for (const h of g.horses) consider(h);
+    consider(g.player);
+    if (headOn) push += 0.4;                                 // pass on the LEFT — we're English
+    // CONTEXT WHISKERS (v3 — Nick: "every move they sense and adjust, not only when they walk
+    // into something"): five feelers (0°, ±35°, ±70°), the CENTRE one long (2.3m ≈ 1.3s of
+    // warning at walk pace) so walkers start CURVING well before contact. Each feeler scores
+    // graded openness (blocked-near 0 / blocked-far 0.5 / clear 1) minus a bias away from the
+    // desired line, and the walker leans toward the most-open direction — so an obstacle ahead
+    // bends the path early and smoothly instead of stopping it at the last step. If even the
+    // best direction reads blocked-near (boxed in — stall maze), _steerSlow flags the callers
+    // to drop to a hesitant pace while the turn happens: nobody barges at full speed.
+    // NB: world.collide() returns the CORRECTED position ({x,z}) — ALWAYS truthy. Blocked
+    // means the point MOVED. (Treating it as a boolean made every whisker read blocked
+    // everywhere → zero steering — the "not working at all" bug.)
+    const circleHit = (qx, qz) => {
+      const h = g.world.collide(qx, qz, 0.3, 0, py);
+      return !!h && (Math.abs(h.x - qx) > 1e-6 || Math.abs(h.z - qz) > 1e-6);
+    };
+    const probe = (a, L) => {   // graded by DISTANCE to first hit (0..1) — dense areas keep a gradient
+      const c = Math.cos(a), s = Math.sin(a);
+      const wx = dir.x * c + dir.z * s, wz = dir.z * c - dir.x * s;
+      if (circleHit(px + wx * L * 0.35, pz + wz * L * 0.35)) return 0;
+      _steerA.set(px, py + 0.9, pz); _steerB.set(px + wx * L * 0.5, py + 0.9, pz + wz * L * 0.5);
+      if (g.world.segmentBlocked(_steerA, _steerB)) return 0.15;                            // BVH near half
+      if (circleHit(px + wx * L * 0.7, pz + wz * L * 0.7)) return 0.4;
+      if (circleHit(px + wx * L, pz + wz * L)) return 0.7;
+      _steerB.set(px + wx * L, py + 0.9, pz + wz * L);
+      return g.world.segmentBlocked(_steerA, _steerB) ? 0.7 : 1;                            // BVH full
+    };
+    const scores = _WHISK_A.map((a, i) => probe(a, _WHISK_L[i]));
+    const centreScore = scores[0];
+    this._steerBlockAhead = centreScore < 0.35;                    // callers: treat a close goal as reached
+    let bestA = 0, bestScore = -9;
+    for (let i = 0; i < 5; i++) {
+      // NEVER pick "straight in": when the centre reads blocked-near, it is excluded — the walker
+      // MUST commit to a side (the old equal-scores tie kept centre → walked into things first).
+      if (i === 0 && centreScore < 0.35) continue;
+      const score = scores[i] - Math.abs(_WHISK_A[i]) * 0.14;      // mild preference for the desired line
+      if (score > bestScore) { bestScore = score; bestA = _WHISK_A[i]; }   // ties keep the EARLIER whisker — left sits before right in the fan, so ties pass LEFT
+    }
+    if (centreScore < 0.35 && bestScore < 0.1) {
+      // boxed in hard: turn to whichever ±70° side is less bad (tie → LEFT, we're English)
+      bestA = scores[3] >= scores[4] ? _WHISK_A[3] : _WHISK_A[4];
+    }
+    this._steerSlow = centreScore < 0.4;                           // hesitate whenever contact is near
+    // whisker lean + people separation, together. Centre clear = no lean (bestA 0).
+    return Math.max(-1.35, Math.min(1.35, bestA + Math.max(-0.6, Math.min(0.6, push))));
+  }
+
+  // ---- shared navgrid access — EVERYONE routes on the grids (townsfolk, knights, goblins…) ----
+  // Subclasses provide _navHome() (settlement centre / camp home); null = no pathing for this
+  // character. Grids bake lazily per region; until ready, callers fall back to direct+whiskers.
+  _navHome() { return null; }
+
+  _navRegion() {
+    if (this._navCx !== undefined) return;
+    const h = this._navHome();
+    if (!h) { this._navCx = null; return; }
+    this._navCx = h.x; this._navCz = h.z;
+    this._navKey = `r${Math.round(h.x / 80)}_${Math.round(h.z / 80)}`;   // ~one shared grid per area
+  }
+
+  _navGrid() {
+    const nav = this.game.nav;
+    if (!nav) return null;
+    this._navRegion();
+    if (this._navCx == null) return null;
+    const grd = nav.gridFor(this._navKey, this._navCx, this._navCz);
+    return grd.ready ? grd : null;
+  }
+
+  _requestPath(to) {
+    const nav = this.game.nav;
+    if (!nav) return null;
+    this._navRegion();
+    if (this._navCx == null) return null;
+    return nav.path(this._navKey, this._navCx, this._navCz, this.position, to);
+  }
+
+  // Current waypoint along the active path (advances as we reach each), else the raw goal.
+  _pathWaypoint(t) {
+    if (this._navPath && this._navI < this._navPath.length) {
+      let wp = this._navPath[this._navI];
+      if (dist2D(this.position.x, this.position.z, wp.x, wp.z) <= 0.8) {
+        this._navI++;
+        wp = this._navI < this._navPath.length ? this._navPath[this._navI] : t;
+      }
+      return wp;
+    }
+    return t;
+  }
+
+  // Smooth the VISUAL height on the way DOWN over micro-bumps (cobbles/steps/
+  // slopes), so descents aren't choppy from snap-to-ground stepping each frame.
+  // Same logic the player runs in player.update — but MUST be called AFTER the
+  // entity has moved this frame (so position.y is final), else the move re-adds
+  // the raw delta and the smoothing does nothing. Physics stay exact; ascents
+  // and big jumps (spawn/teleport/fall) track 1:1. The player does its own (it
+  // also drives the camera from _visualY), so this is for NPCs and enemies.
+  applyDescentSmoothing(dt) {
+    if (!this.model) return;
+    const py = this.position.y;
+    if (this.airborne || this._visualY === undefined || Math.abs(py - this._visualY) > 1.5) {
+      this._visualY = py;
+    } else if (py < this._visualY) {
+      this._visualY += (py - this._visualY) * Math.min(1, dt * 12); // ease down
+    } else {
+      this._visualY = py;
+    }
+    this._baseModelY ??= this.model.position.y;
+    this.model.position.y = this._baseModelY + (this._visualY - py);
+  }
+
+  takeDamage(amount, fromPos = null, opts = {}) {
+    if (!this.alive) return;
+    const { knockback = 0.5, softHit = false } = opts;   // `opts` also carries .power (heavy/flourish) — read below
+    this.health -= amount;
+    // softHit: damage only (a blocked hit chips health but must not break the guard).
+    // _poiseT: stagger cooldown — damage always lands, but mashing can't stun-lock a
+    // character; they get a swing off between staggers.
+    // poise tier (enemy.js def.poise): 0 staggers on any hit, 1 needs a heavy/
+    // flourish (opts.power 1), 2 shrugs everything — heavies finally have a job
+    // opts.parried: a timed deflect ALWAYS staggers, through any poise tier and any
+    // cooldown — the parry is the answer to armoured enemies, so it must never whiff
+    const interrupt = opts.parried || (!softHit && !(this._poiseT > 0) && (opts.power ?? 1) >= (this.poise ?? 0));
+    if (interrupt) {
+      this.staggerT = opts.parried ? 1.1 : 0.35;   // a parried enemy reels — the punish window
+      // 1.6s: long enough for a full windup+swing before the next stagger can land — the
+      // old 0.9s left ~0.5s of freedom, which light-attack spam ate entirely ("I hit them
+      // with sword and they never get to hit me"). First hit still staggers (feel), then
+      // they FIGHT THROUGH the combo (threat) — the AC pressure loop, phase 1.
+      this._poiseT = 1.6;
+      this._swing = null; // a hit interrupts their in-progress swing (game-time pending swing, enemy.js)
+      if (fromPos) {
+        const dx = this.position.x - fromPos.x, dz = this.position.z - fromPos.z;
+        const d = Math.hypot(dx, dz) || 1;
+        // Displace via the capsule controller so knockback DEPENETRATES against building/
+        // castle/goblin-camp/Ironkeep BVH walls and stays on the MESH floor it's standing
+        // on (bridge deck, castle walk, Ironkeep upper storey). The old path used the 2D
+        // collide() (trees/fences only) and then HARD-SET y to the terrain heightfield —
+        // teleporting entities through walls and dropping them through mesh floors.
+        this.game.world.moveCapsule(this, (dx / d) * knockback, (dz / d) * knockback, 1 / 60);
+      }
+    }
+    if (this.health <= 0) {
+      this.die();
+    } else if (interrupt && this.animator?.actions.hit) {
+      this.busy = true;
+      this._hitBusyT = 0.55;   // failsafe: creature rigs alias 'hit' to their IDLE clip — busy must not lock for its full length (audit m9)
+      this.animator.play('hit', { once: true, fade: 0.08, onDone: () => { this.busy = false; } });
+    }
+  }
+
+  die() {
+    if (!this.alive) return;
+    this.alive = false;
+    this.busy = true;
+    if (this.animator?.actions.death) {
+      this.animator.play('death', { once: true, fade: 0.1 });
+    }
+    this.deathT = 0;
+  }
+
+  update(dt) {
+    if (!this.alive) {
+      this.deathT = (this.deathT ?? 0) + dt;
+      if (this.deathT > 6 && !this.dead) {
+        this.dead = true; // flagged for removal by the entity manager
+      }
+    }
+    if (this.staggerT > 0) this.staggerT -= dt;
+    if (this._hitBusyT > 0) { this._hitBusyT -= dt; if (this._hitBusyT <= 0 && this.busy && this.alive) this.busy = false; }
+    if (this._poiseT > 0) this._poiseT -= dt;
+
+    const g = this.game;
+    // VAT proxy (vatRoster.js): while DEMOTED this character renders as a roster instance —
+    // the rig stays hidden and the Animator never runs (the two real per-character costs).
+    // PROMOTE to the rig within 8m of the player, or the moment the AI plays a clip that
+    // isn't in the baked ambient set (attack/hit/death/chat/sit — mappable() says no), or on
+    // death/stagger. DEMOTE back past 10m when ambient again (hysteresis so nothing flickers).
+    // The subclass AI runs after this either way — demoted characters keep moving/scheduling.
+    if (this.vatProxy?.ready && g.vatRoster && this.faction !== 'player' && g.player) {   // v1 ships no VAT roster — guard, don't assume
+      const roster = g.vatRoster;
+      const d = this.position.distanceTo(g.player.position);
+      const clipName = this.animator?.currentName ?? 'idle';
+      const ambient = this.alive && !this.busy && this.staggerT <= 0 && roster.mappable(clipName);
+      const rIn = this.vatProxy.promoteR ?? 8, rOut = this.vatProxy.demoteR ?? 10;
+      const asInstance = this._vatPromoted ? (ambient && d > rOut) : (ambient && d >= rIn);
+      this._vatPromoted = !asInstance;
+      if (asInstance) {
+        roster.write(this.vatProxy, this.position.x, this.position.y, this.position.z, this.heading, clipName);
+        if (this.model?.visible) this.model.visible = false;
+        this._animPhase = 0;
+        return; // no frustum test, no anim stride, no animator — the instance is the character
+      }
+      roster.hide(this.vatProxy);
+    }
+
+    // distance-based animation culling: far characters freeze (hidden by
+    // fog anyway), mid-range ones animate at half rate. Player always full.
+    if (this.faction !== 'player' && g.player && g.quality) {
+      const d = this.position.distanceTo(g.player.position);
+      if (d > (this.cullDist ?? g.quality.entityCull)) {   // road travellers raise cullDist so they don't pop out close
+        if (this.model) this.model.visible = false;
+        this._animPhase = 0;
+        return;
+      }
+      // Off-screen cull: characters are frustumCulled=false, so three draws every near character even
+      // behind the camera. Test the body sphere vs the shared per-frame frustum (built in main tick) —
+      // hide + skip the animator when off-screen. The subclass AI runs AFTER super.update, so the
+      // character keeps moving; it just isn't drawn or skinned until it re-enters view. No pop.
+      if (g._camFrustum) {
+        _cullSphere.center.set(this.position.x, this.position.y + 1, this.position.z);
+        if (!g._camFrustum.intersectsSphere(_cullSphere)) {
+          if (this.model) this.model.visible = false;
+          this._animPhase = 0;
+          return;
+        }
+      }
+      if (this.model && !this.model.visible) this.model.visible = true;
+      if (d > g.quality.animHalfRate) {
+        // Graded stride: 1/2 rate past animHalfRate, 1/3 past animMidRate, 1/4 in the outer band
+        // before the cull. _pendingDt accumulation keeps clip time exact, so gaits never drift —
+        // a far NPC just updates its pose less often (fog + distance hide the step).
+        const cull = this.cullDist ?? g.quality.entityCull;
+        const mid = g.quality.animMidRate ?? g.quality.animHalfRate * 1.5;
+        const stride = d > mid ? (d > cull * 0.85 ? 4 : 3) : 2;
+        this._animPhase = ((this._animPhase ?? 0) + 1) % stride;
+        if (this._animPhase) { this._pendingDt = (this._pendingDt ?? 0) + dt; return; }
+        dt += this._pendingDt ?? 0;
+        this._pendingDt = 0;
+      }
+    }
+    this.animator?.update(dt);
+    // ground the feet once the REAL idle pose has settled (model origin sits at the hips).
+    // Runs for EVERY rig without an explicit feetDrop — the western keep-extracts are
+    // hip-origined like the modular hero, so skipping them sank enemies to the waist.
+    if (!this._grounded && this.model) {
+      this._groundT = (this._groundT ?? 0) + dt;
+      if (this._groundT > 0.5) { this._grounded = true; this._groundFeet(); }
+    }
+  }
+}
+
+// Modular character: show only the equipped part meshes per slot, hide all the rest.
+// Exported so the equipment system can re-apply after armour part swaps (visibility
+// toggles on the one resident rig — never adds/removes meshes).
+export function applyOutfit(model, outfit) {
+  const wanted = new Set(Object.values(outfit.parts || {}));
+  model.traverse((o) => { if (o.isMesh && o.name.startsWith('Chr_')) o.visible = wanted.has(o.name); });
+}

package/src/systems/fistCurl.js

@@ -0,0 +1,38 @@
+// Bare-knuckle finger curl — the shared bit between the PLAYER (fists weapon mode, player.js) and the
+// brawler ENEMIES (ENEMY_TYPES … brawler:true, enemy.js). The punch MoCap clips leave the fingers slack;
+// a per-frame procedural curl — run AFTER the mixer so it wins — closes them into fists. Tuned live in
+// /fighttest.html; this file is the single home for the tuned numbers, so a re-tune lands in one place.
+//
+// Each knuckle flexes about its own local −Z; the thumb (Thumb_01/Thumb_02) folds across on a compound
+// euler with its tip (Thumb_03) left straight.
+import * as THREE from 'three/webgpu';
+
+export const FIST_CURL = 55 * Math.PI / 180;                                                          // per-knuckle flex, −Z
+export const FIST_THUMB = { x: 66 * Math.PI / 180, y: -18 * Math.PI / 180, z: -23 * Math.PI / 180 };  // Thumb_01/02 euler (Nick-tuned)
+
+const _z = new THREE.Vector3(0, 0, 1), _q = new THREE.Quaternion(), _e = new THREE.Euler();
+
+// The finger JOINT bones = finger-named bones that HAVE a finger-named child. On the player/enemy DOUBLED
+// skeleton these are the twin joints the skinning leaves ride on; on a COLLAPSED skeleton they're the
+// single finger chain — either way, rotating them cascades the whole digit and the mesh follows. Call at
+// REST (before the mixer poses the fingers); each entry keeps the bone's rest quaternion as `bind`.
+export function collectFistJoints(model) {
+  const out = [], isFinger = (n) => /Thumb|Finger|Index/i.test(n);
+  model.traverse((b) => {
+    if (!b.isBone || !isFinger(b.name)) return;
+    if (b.children.some((c) => c.isBone && isFinger(c.name)))
+      out.push({ bone: b, bind: b.quaternion.clone(), thumb: /thumb/i.test(b.name), tip: b.name === 'Thumb_03' });
+  });
+  return out;
+}
+
+// Pose the joints for this frame: curled → fist, else → open (rest bind). Overwrites LOCAL quaternions, so
+// it MUST run after the mixer. On the doubled skeleton the `false` branch also clears any residual curl on
+// the un-driven twin joints (the mixer never re-poses those), so a hand never sticks in a fist.
+export function applyFist(joints, curled) {
+  for (const f of joints) {
+    if (!curled || f.tip) f.bone.quaternion.copy(f.bind);
+    else if (f.thumb) f.bone.quaternion.copy(f.bind).multiply(_q.setFromEuler(_e.set(FIST_THUMB.x, FIST_THUMB.y, FIST_THUMB.z, 'XYZ')));
+    else f.bone.quaternion.copy(f.bind).multiply(_q.setFromAxisAngle(_z, -FIST_CURL));
+  }
+}