sindicate 0.2.0 → 0.5.0

package/src/systems/npc.js

@@ -0,0 +1,880 @@
+// NPC — the townsfolk of Dustwater. Two behaviours, chosen by the def (data/npcs.js):
+//
+//   POSTED  (def.post)   the barkeep behind his counter, the piano player at the keys, a hand
+//                        of poker that never ends, the sheriff watching the street. Holds a
+//                        mark and a heading, drifts through a small pool of role idles, clocks
+//                        the player when he comes near, and walks back if he gets shoved off it.
+//   WANDER  (def.wander) strolls a route of street points, lingering at each on a social idle,
+//                        and occasionally strikes up a STAGED TWO-PERSON CONVERSATION with
+//                        another free wanderer (NC.convTakes: matched A/B takes played in sync
+//                        while the pair stand facing each other, turn-taking for 3–5 exchanges).
+//
+// Villagers are NOT COMBATANTS: faction 'villager' is deliberately absent from enemy.js's TEAM
+// map, so foes() never returns true for them and no outlaw will ever shoot one. But they ARE
+// SHOOTABLE — combat.js's bullet loop and the melee arc test game.npcs alongside the outlaws
+// (they expose the same .position/.alive/.maxHealth/.takeDamage contract, plus .civilian). A man
+// who takes a round cries out, reels, and RUNS; a man who takes the last one goes down where he
+// stands and stays there. Killing him is a MURDER (crime.js) and spills his purse (loot.js) —
+// the town does not forget, and the town does not stand still and watch.
+//
+// PERF CONTRACT (main.js:118): every NPC is built ONCE on the loading screen and stays resident
+// and scene-attached for life. Nothing here ever adds, removes, or toggles a skinned mesh —
+// visibility is only ever driven by Character.update's own distance/frustum cull, which is the
+// mechanism the renderer already expects. Do not "spawn" an NPC during play.
+import { Character } from './entity.js';
+// NPC content is GAME data — register at boot, before populateTown/County:
+//   setNpcContent({ clipSubset, villagerClips, socialIdles, convTakes, convClips,
+//                   getCharacter, npcDefs, wanderRoutes, countyDefs })
+let NC = {
+  clipSubset: (c) => c, villagerClips: [], socialIdles: [], convTakes: [], convClips: [],
+  getCharacter: () => null, npcDefs: [], wanderRoutes: {}, countyDefs: [],
+};
+export function setNpcContent(c) { NC = { ...NC, ...c }; }
+import { dist2D, tmpV1 } from '../core/utils.js';
+import { steerCarrot } from './pathFollow.js';
+
+const _fDir = tmpV1.clone();       // mission-follow steering scratch (own vector — tmpV1 is shared)
+const _fAim = { x: 0, z: 0 };      // the carrot point steerCarrot hands a following NPC
+
+const CONV_DIST = 1.5;   // comfortable centre-to-centre talking distance for a staged conversation
+const CONV_MAX = 3;      // cap on simultaneous conversations — a lively town, not one frozen in pairs
+const AI_RANGE = 60;     // beyond this the AI itself sleeps (Character.update has already hidden them)
+// A child's pace, and the cadence that keeps his boots on the ground with it — see the `child` branch
+// below for the arithmetic. An adult townsman walks at 1.7.
+const CHILD_SPEED = 0.85;
+const CHILD_CADENCE = 0.81;
+const TALK_R = 3.0;      // within this the nearest civilian becomes the E-to-talk target (main.js reads
+                         // game._talkCand). Sits just inside the 3.2 m mount reach so a man and his horse
+                         // both offer a prompt and the nearer one wins.
+const FLEE_R = 13;       // an engaged outlaw this close sends the unarmed running
+const PANIC_SECS = 7;    // a man who has just been SHOT runs for this long — twice as long as a
+                         // man who merely heard a shot. Being hit is not the same as being startled.
+const WITNESS_R = 12;    // and everyone who saw it happen runs with him
+const ROAM_PTS = 9;      // wander points sampled inside a roam disc — enough that a ranch hand's
+                         // circuit doesn't read as a loop, few enough that the navgrid can bake it
+
+export class NPC extends Character {
+  constructor(game, def, clips) {
+    const body = NC.getCharacter(def.char);
+    if (!body) throw new Error(`[npc] unknown character '${def.char}' for '${def.id}'`);
+
+    // Clip budget per NPC: the shared villager set, plus whatever situational idles THIS
+    // townsperson actually uses (the drunk's sway, the priest's prayer), plus — for wanderers
+    // only — the 18 paired conversation takes. A posted barkeep never talks to anyone, so he
+    // doesn't pay for them.
+    // CONVERSATIONS ARE RATIONED TO THE TWO TOWNS. The 18 paired takes are 18 more AnimationActions
+    // on a mixer, and a talking pair can never be a VAT instance (its clip isn't in the bake) — so
+    // a chatting man is a real skinned rig for as long as he chats. Dustwater's street and
+    // Perdition's ask for them (def.talk); a miner at Bonebreak does not.
+    const talks = !!(def.wander || def.talk);
+    const extra = [def.idle, ...(def.idles ?? [])].filter(Boolean);
+    const names = [...new Set([
+      ...NC.villagerClips,
+      ...extra,
+      ...(talks ? NC.convClips : []),
+      // a GUNHAND (the ride-along crew) carries the fighting clips: the aim/fire pair for the
+      // ally-shoot, the boxing guard for flavour. Costs a few AnimationActions on six mixers.
+      ...(def.gunhand ? ['gunAim', 'gunFire', 'punchIdle'] : []),
+    ])];
+
+    super(game, {
+      model: body.src,
+      texture: def.tex ?? body.tex,   // a def may pick a recolour: the model cache is keyed url|texture|scale,
+                                      // so the same body in a second atlas is a second-looking man for a clone
+      clips: NC.clipSubset(clips, names, { strip: true, kid: !!body.child }),   // strip: no finger/toe/eye tracks. kid: rescale the pelvis (clips.js)
+      speed: 1.7,
+      health: 60,
+      faction: 'villager',       // NOT in enemy.js's TEAM map → never a valid combat target
+      name: def.name,
+      keep: body.keep,           // multi-body western FBX → base load() keep-filters + atlases it.
+                                 // A LIST for a child: he is five meshes (characters.js).
+      texFlipY: true,            // FBX UVs (characters.js: "load with flipY = true")
+      // THE THREE THINGS A CHILD NEEDS AND AN ADULT DOES NOT. All three are undefined on an adult
+      // def, so this costs the other 127 souls nothing. See characters.js's kid() for what each is.
+      collapse: !!body.collapse, // 5,082 bones and 100 'Head's → one 51-bone skeleton
+      hair: body.hair,           // his hair or his hat — an adult's is baked into his body mesh
+      faceTex: body.faceTex,     // the FACIAL atlas: his mouth
+      freckleTex: body.freckleTex,
+    });
+
+    this.def = def;
+    this.fleeT = 0;
+    this.posted = !!def.post;
+    this.civilian = true;      // the SHOOTABLE-PEOPLE contract: combat/crime tell these from outlaws by this flag
+
+    // A CHILD CANNOT BE HARMED, AND THAT IS A PROPERTY OF THE ENTITY — not a special case
+    // sprinkled through combat.js. `noTarget` is honoured at every place a body is GATHERED
+    // (aim.js nearestBody, which serves BOTH the reticle and the shot convergence; combat.js's
+    // bullet loop and melee arc; deadeye's tag list), and takeDamage() below REFUSES outright.
+    // takeDamage is the only path to `health -=` and the only caller of die() (entity.js), and
+    // the purse drop lives inside die() — so a child who refuses damage cannot lose health,
+    // cannot die, cannot be looted and cannot be finished. If someone writes a sixth gathering
+    // site next year without reading this, the entity still says no.
+    // A CHILD IS HALF THE SPEED OF A GROWN MAN, AND HIS LEGS GO AT A CHILD'S CADENCE.
+    //
+    // He was set to 2.1 — FASTER than the adults' 1.7 — so the county's children outran their own
+    // parents down the street. Half of 1.7 is 0.85, and that is what he gets.
+    //
+    // But halving the ground speed alone would moonwalk him: the clip is authored for an adult's
+    // stride, and this rig's legs are shorter (KID_HIP = 0.62 — clips.js rescales the pelvis by it),
+    // so at playback rate 1.0 a kid's stride already covers only 0.62 of an adult's ground. That
+    // means his no-slide speed at rate 1.0 is 1.7 x 0.62 = 1.05 m/s, and to walk at 0.85 without his
+    // boots skating he must play at 0.85 / 1.05 = 0.81. Set on the MIXER, not the clip, so his idle,
+    // his walk and his run all slow together — a child who ambles but panics at adult speed is a
+    // puppet with two operators.
+    if (body.child) {
+      this.child = true;
+      this.noTarget = true;
+      this.speed = CHILD_SPEED;
+      this._animRate = CHILD_CADENCE;
+    }
+
+    // Idle pool: the poses this one drifts between while standing. A def that names an `idle`
+    // but no `idles` holds that single pose (a barkeep is a barkeep); a bare wanderer gets a
+    // random personal handful of the NC.socialIdles so the street isn't full of clones.
+    if (def.idles?.length) this._idlePool = def.idles.slice();
+    else if (def.idle) this._idlePool = [def.idle];
+    else {
+      const pool = NC.socialIdles.slice();
+      this._idlePool = [];
+      for (let i = 0; i < 3 && pool.length; i++) this._idlePool.push(pool.splice((Math.random() * pool.length) | 0, 1)[0]);
+    }
+    this._idleClip = this._idlePool[0];
+    this._idleT = 3 + Math.random() * 7;
+
+    if (this.posted) {
+      const p = def.post;
+      this.post = { x: p.x, z: p.z, y: p.y ?? null, face: p.face ?? null };
+      // An authored y is an EXACT indoor floor datum (the saloon's 1.051 world floorboards, measured):
+      // keep it, and let settle() leave it untouched. Everyone else takes the walk surface at his mark
+      // — terrain, boardwalk deck or building floor (world.walkSurfaceAt / town.js plinthAt).
+      this._authoredY = p.y != null;
+      this.setPosition(p.x, p.y ?? game.world.walkSurfaceAt(p.x, p.z), p.z);
+      // start ON the post's heading — never caught slowly swinging round when the player first walks in
+      if (p.face != null) { this.heading = p.face; this.root.rotation.y = p.face; }
+    } else {
+      // ROAM (def.roam = {x, z, r}): the county's other fourteen places have no authored street
+      // route and do not need one — a ranch hand's beat is "the yard", a soldier's is "the parade
+      // ground". Sample points on the disc and hand them to the SAME wanderer that walks Dustwater:
+      // wanderUpdate already jitters each point, validates it on the navgrid, and discards anything
+      // unreachable, so a point only has to be roughly right. sqrt() spreads them by AREA, not by
+      // radius, or everyone crowds the middle.
+      this._wanderPts = def.roam
+        ? Array.from({ length: ROAM_PTS }, () => {
+          const a = Math.random() * Math.PI * 2, d = Math.sqrt(Math.random()) * def.roam.r;
+          return { x: def.roam.x + Math.cos(a) * d, z: def.roam.z + Math.sin(a) * d };
+        })
+        : NC.wanderRoutes[def.wander] ?? NC.wanderRoutes.street ?? [];
+      this.canTalk = talks;                          // only these carry NC.convClips — see the ctor note
+      this.convo = null;                             // active staged conversation (shared object) or null
+      this.convoCooldown = 6 + Math.random() * 24;   // stagger first attempts so the town doesn't pair up at once
+      this._convoScanT = Math.random();
+      this.wanderPause = Math.random() * 3;
+      const p = this._wanderPts[(Math.random() * this._wanderPts.length) | 0] ?? { x: 0, z: 0 };
+      const x = p.x + (Math.random() - 0.5) * 3, z = p.z + (Math.random() - 0.5) * 3;
+      this.setPosition(x, game.world.walkSurfaceAt(x, z), z);
+      this.heading = Math.random() * Math.PI * 2;
+      this.root.rotation.y = this.heading;
+    }
+  }
+
+  // Seat onto whatever we're actually standing on — the terrain, a boardwalk deck, or a building's
+  // floorboards — by a VERTICAL query (world.walkSurfaceAt = max(groundAt, plinthAt)). Run ONCE after
+  // load(), on the loading screen.
+  //
+  // This USED to drop the 0.45 m controller capsule and let it fall onto the BVH. That capsule's
+  // radius caught up-facing edges BESIDE the feet, not just under them — so a man authored a pace off
+  // the church plinth was hauled up onto its lip and left hanging half a metre in the air off the edge
+  // of it (Nick: "hovering people"). A column query cannot: on the floor it seats him on the floor,
+  // off it he stands on the dirt, and nothing lifts him onto a plinth he is not over.
+  settle() {
+    this.vy = 0;
+    this._capGrounded = true;
+    // A POST INSIDE A PROP IS A WAR THE MAN CANNOT WIN: postedUpdate walks him back onto the mark
+    // every frame while the collider shoves him off it, and he stands embedded forever (the soak
+    // monitor caught the Otts and Bram Coe doing exactly this at the farms). If the authored mark
+    // itself corrects, adopt the corrected point as the mark — once, here, for every post in the
+    // county, present and future.
+    if (this.post) {
+      const c = this.game.world.collide(this.post.x, this.post.z, 0.4, 0, this.position.y);
+      if (c && Math.hypot(c.x - this.post.x, c.z - this.post.z) > 0.05) {
+        this.post.x = c.x; this.post.z = c.z;
+        this.position.x = c.x; this.position.z = c.z;
+      }
+    } else {
+      // roamers too: a roam ANCHOR inside a farm building leaves the man embedded-from-boot,
+      // frozen there until the player walks close enough to wake his AI (the soak kept finding
+      // them at the far farms). Correct the spawn once, here, where every NPC passes.
+      const c = this.game.world.collide(this.position.x, this.position.z, 0.4, 0, this.position.y);
+      if (c && Math.hypot(c.x - this.position.x, c.z - this.position.z) > 0.05) {
+        this.position.x = c.x; this.position.z = c.z;
+      }
+    }
+    // an authored indoor y (the measured saloon floorboards) is exact — never re-derive it
+    if (this.post && this._authoredY) return;
+    this.position.y = this.game.world.walkSurfaceAt(this.position.x, this.position.z);
+    if (this.post) this.post.y = this.position.y;
+  }
+
+  // Nav home (Character._navRegion): wanderers centre their grid on their route's centroid.
+  // POSTED NPCs never path (they stand, or take two steps back to their mark) → no grid, no bake.
+  _navHome() {
+    if (!this._wanderPts?.length) return null;
+    let sx = 0, sz = 0;
+    for (const p of this._wanderPts) { sx += p.x; sz += p.z; }
+    return { x: sx / this._wanderPts.length, z: sz / this._wanderPts.length };
+  }
+
+  // Drift between this NPC's personal ambient idles so they aren't statues.
+  socialIdle(dt) {
+    this._idleT -= dt;
+    if (this._idleT <= 0) {
+      let n; do { n = this._idlePool[(Math.random() * this._idlePool.length) | 0]; }
+      while (this._idlePool.length > 1 && n === this._idleClip);
+      this._idleClip = n;
+      this._idleT = 5 + Math.random() * 10;
+    }
+    this.play(this._idleClip);
+  }
+
+  // Play a clip, falling back to 'idle' if this NPC's subset doesn't carry it (a def naming a
+  // situational idle that never made it into CLIP_URLS must not wedge the animator).
+  play(name, opts) {
+    this.animator?.play(this.animator.actions[name] ? name : 'idle', opts);
+  }
+
+  // Something frightened them (a gunfight, an alarm). Runs for wanderers only —
+  // the sheriff and the saloon staff hold their ground (def.flee === false, or a post).
+  //
+  // `force` is what a BULLET does. A barkeep is posted so that he doesn't abandon his counter
+  // because two men are arguing in the street — not so that he keeps polishing glasses while a
+  // man is shot dead in front of him. So force overrides the POST (he leaves it, and postedUpdate
+  // walks him back once he stops running) but never overrides def.flee === false: the sheriff
+  // holds his ground on purpose, and he holds it through this too.
+  scare(x, z, secs = 2.5, force = false) {
+    if (!this.alive) return;
+    if (this.def.flee === false) return;
+    if (this.posted && !force) return;
+    this._fleeFrom = { x, z };
+    this.fleeT = Math.max(this.fleeT, secs);
+    if (this.convo) this._endConversation();
+  }
+
+  // SHOT, OR PUNCHED. He has no fight in him — Character.takeDamage does the arithmetic, the
+  // stagger and the 'hit' clip exactly as it does for an outlaw, and then he does the only thing
+  // an unarmed man does: he cries out and he RUNS. (Reuses the flee above — forced, so a man shot
+  // behind his own counter leaves the counter.)
+  //
+  // opts.attacker is who pulled the trigger (combat.js sets it). It is the ONLY thing that decides
+  // whether this is a crime: an outlaw's stray round is not the player's murder. Unknown attacker
+  // is treated as the player, because today nothing else in the world can hurt a townsman.
+  takeDamage(amount, fromPos = null, opts = {}) {
+    if (!this.alive) return;
+    const g = this.game;
+    // THE BACKSTOP. Nothing in this game can gather a child as a target (see the ctor), but this
+    // is the line that makes it IMPOSSIBLE rather than merely unlikely: no health arithmetic runs,
+    // so a child cannot be hurt, cannot die, cannot drop a purse and cannot be finished — whatever
+    // any future caller does. He is frightened by whatever tried, and he runs.
+    if (this.child) {
+      const f = fromPos ?? g.player?.position ?? this.position;
+      this.scare(f.x, f.z, PANIC_SECS, true);
+      alarmTown(g, this.position.x, this.position.z, WITNESS_R, 4);
+      return;
+    }
+    // PLOT ARMOR. A campaign principal (def.plot — stamped at registration in main.js) cannot DIE:
+    // a stray round in a street fight killing Sheriff Bracken would softlock every mission that
+    // ever talks to him, forever, in the save. He takes the hit, reels, bleeds to a knee's worth of
+    // health — everything a body does short of dying — and the crime is still a crime.
+    if (this.def?.plot && this.health - amount <= 0) {
+      amount = Math.max(0, this.health - 1);
+      if (!amount) {   // already at the floor: flinch and flee, no arithmetic
+        const f = fromPos ?? g.player?.position ?? this.position;
+        this.scare(f.x, f.z, PANIC_SECS, true);
+        return;
+      }
+    }
+    this._killer = opts.attacker ?? null;      // die() runs INSIDE super.takeDamage — stash it first
+    super.takeDamage(amount, fromPos, opts);
+    if (!this.alive) return;                   // he died of it: die() below did the reporting
+    g.audio?.play('hurt');
+    const f = fromPos ?? g.player?.position ?? this.position;
+    this.scare(f.x, f.z, PANIC_SECS, true);
+    if (this._byPlayer()) {
+      g.crime?.report('assault', this.position.clone());
+      g.encounters?.provokeGroup(this);   // a drover's outfit does not stand and watch (encounters.js)
+    }
+    alarmTown(g, this.position.x, this.position.z, WITNESS_R, 4);   // and everyone who saw it goes with him
+  }
+
+  _byPlayer() { return this._killer == null || this._killer === this.game.player; }
+
+  // DOWN. Character.die() plays the villager 'death' clip (NC.villagerClips carries one) and stops
+  // the AI dead — NPC.update returns on !alive — and the body STAYS: nothing here ever removes a
+  // skinned mesh from the scene (main.js:118). A corpse in the street is the point.
+  die() {
+    if (!this.alive) return;
+    const g = this.game;
+    // let go of a conversation FIRST: _endConversation plays 'idle' on both partners, and on a
+    // dead man that idle would stomp the death clip he is about to be given.
+    if (this.convo) this._endConversation();
+    this.fleeT = 0;
+    super.die();
+    const at = this.position.clone();
+    g.audio?.play('hurt');
+    if (this._byPlayer()) {
+      g.crime?.report('murder', at);
+      // WHAT HE WAS ACTUALLY CARRYING. This used to drop a flat [2,14] on everybody, so a
+      // stationmaster, a ranch hand and a card player all fell with the same money in their
+      // pockets — and purse.js's whole ALIAS table, written for exactly this, was never reached
+      // from the NPC path. `def.purse` overrides; otherwise the def's id resolves through it.
+      g.loot?.dropFor?.(this.def.purse ?? this.def.id, at);
+      g.encounters?.provokeGroup(this);
+    }
+    // A BODY IN THE STREET. Close enough to have watched it happen and even the posted men run
+    // (forced — the saloon empties); further out, the street clears the ordinary way.
+    alarmTown(g, at.x, at.z, 9, 7, true);
+    alarmTown(g, at.x, at.z, 26, 5);
+  }
+
+  // Is a fight happening on top of us? (No morality system in the west — fear is just proximity
+  // to an outlaw who has stopped wandering and started hunting.)
+  // WHAT ACTUALLY FRIGHTENS A MAN: someone HUNTING, not someone standing about.
+  //
+  // This used to run from any enemy whose state was not literally 'wander' — and an outlaw who has
+  // not been provoked yet is 'passive', not 'wander'. So from the moment the game loaded, the four
+  // outlaws posted around town terrified every townsman within FLEE_R, and you walked into a
+  // Dustwater whose entire population was already running away from nothing. The street was empty
+  // before a shot had been fired.
+  //
+  // A man is frightened by a man who is CHASING, SHOOTING or SWINGING at someone. An outlaw leaning
+  // on a fence is just an outlaw leaning on a fence.
+  _danger() {
+    for (const e of this.game.combat?.enemies ?? []) {
+      if (!e.alive || e.dead || e.passive) continue;
+      if (e.state !== 'chase' && e.state !== 'attack' && e.state !== 'shoot') continue;
+      if (dist2D(this.position.x, this.position.z, e.position.x, e.position.z) < FLEE_R) return e.position;
+    }
+    return null;
+  }
+
+  // ---- Staged two-person conversations (the paired NC.convTakes) ------------------------------
+  // Two lingering wanderers settle to a comfortable distance facing each other, then play a
+  // MATCHED PairA/PairB take in sync — one talks while the other listens, gestures interlock —
+  // alternating the speaker for 3–5 exchanges, then part and wander on.
+
+  _seekConversation() {
+    const g = this.game;
+    if (!this.canTalk) return;
+    if ((g._activeConvos ?? 0) >= CONV_MAX) return;
+    let best = null, bd = 2.8;
+    for (const n of g.npcs) {
+      if (n === this || !n.alive || !n.canTalk || n.convo) continue;
+      if (n.convoCooldown > 0 || !(n.wanderPause > 0) || n.busy || n.fleeT > 0) continue;
+      const d = dist2D(this.position.x, this.position.z, n.position.x, n.position.z);
+      if (d < bd && d > 0.9) { bd = d; best = n; }
+    }
+    if (best) this._startConversation(best);
+  }
+
+  // Seat both of us at CONV_DIST either side of our midpoint, then approach → talk.
+  _startConversation(partner) {
+    const mx = (this.position.x + partner.position.x) / 2;
+    const mz = (this.position.z + partner.position.z) / 2;
+    let dx = partner.position.x - this.position.x, dz = partner.position.z - this.position.z;
+    const dl = Math.hypot(dx, dz) || 1; dx /= dl; dz /= dl;
+    const h = CONV_DIST / 2;
+    const convo = {
+      master: this, a: this, b: partner, phase: 'approach', t: 0, talkDur: 8,
+      take: null, exchanges: 3 + ((Math.random() * 3) | 0), done: 0, prevLead: null,
+      spotA: { x: mx - dx * h, z: mz - dz * h },
+      spotB: { x: mx + dx * h, z: mz + dz * h },
+    };
+    this.convo = convo; partner.convo = convo;
+    this.wanderTarget = null; partner.wanderTarget = null;
+    this.game._activeConvos = (this.game._activeConvos ?? 0) + 1;
+  }
+
+  // Alternate the active speaker so it reads as turn-taking: open on a both-engaged take,
+  // then A-leads / B-leads flip each exchange.
+  _nextTake() {
+    const c = this.convo;
+    const want = c.prevLead == null ? 'both'
+      : c.prevLead === 'a' ? 'b'
+      : c.prevLead === 'b' ? 'a'
+      : (Math.random() < 0.5 ? 'a' : 'b');   // after a 'both', pick a side to lead
+    let pool = NC.convTakes.filter((t) => t.lead === want);
+    if (!pool.length) pool = NC.convTakes;
+    let take;
+    do { take = pool[(Math.random() * pool.length) | 0]; } while (pool.length > 1 && take === c.take);
+    c.prevLead = take.lead;
+    return take;
+  }
+
+  // One exchange = one matched take, played on both partners in sync.
+  _playExchange() {
+    const c = this.convo;
+    c.take = this._nextTake();
+    c.t = 0;
+    c.a.play(c.take.a, { once: true, fade: 0.3 });
+    c.b.play(c.take.b, { once: true, fade: 0.3 });
+    const dur = c.a.animator.actions[c.take.a]?.getClip().duration ?? 6;
+    c.talkDur = Math.min(dur, 12);
+  }
+
+  // Master locks both partners face-to-face, then kicks off the first exchange.
+  _beginTalk() {
+    const c = this.convo;
+    c.phase = 'talk';
+    for (const [npc, spot, other] of [[c.a, c.spotA, c.b], [c.b, c.spotB, c.a]]) {
+      const hd = Math.atan2(other.position.x - spot.x, other.position.z - spot.z);
+      npc.heading = hd; npc.root.rotation.y = hd;   // lock facing; the clip animates relative to it
+    }
+    this._playExchange();
+  }
+
+  updateConversation(dt) {
+    const c = this.convo;
+    const partner = c.a === this ? c.b : c.a;
+    if (!partner.alive || this.busy || this.fleeT > 0 || partner.fleeT > 0) { this._endConversation(); return; }
+    const mySpot = c.a === this ? c.spotA : c.spotB;
+
+    if (c.phase === 'approach') {
+      const d = dist2D(this.position.x, this.position.z, mySpot.x, mySpot.z);
+      if (d > 0.16) {
+        const dir = tmpV1.set(mySpot.x - this.position.x, 0, mySpot.z - this.position.z).normalize();
+        this.move(dir, Math.min(this.speed, 1.2), dt);
+        this.faceToward(mySpot.x, mySpot.z, dt);
+        this.play('walk');
+      } else {
+        this.faceToward(partner.position.x, partner.position.z, dt, 6);
+        this.socialIdle(dt);
+      }
+      // the master owns the phase clock: talk once both are ~in place (or after a short grace)
+      if (this === c.master) {
+        c.t += dt;
+        const inPlace = dist2D(c.a.position.x, c.a.position.z, c.spotA.x, c.spotA.z) < 0.3 &&
+                        dist2D(c.b.position.x, c.b.position.z, c.spotB.x, c.spotB.z) < 0.3;
+        if (inPlace || c.t > 2.5) this._beginTalk();
+      }
+      return;
+    }
+
+    // 'talk': heading was locked to the partner at talk-start — let the baked clip drive the
+    // body (a faceToward here would fight the take's own gestures). The master chains the
+    // exchanges and ends the conversation after the last one.
+    if (this === c.master) {
+      c.t += dt;
+      if (c.t >= c.talkDur) {
+        c.done += 1;
+        if (c.done >= c.exchanges) this._endConversation();
+        else this._playExchange();
+      }
+    }
+  }
+
+  // Release both partners back to wandering (idempotent — guarded on this.convo).
+  _endConversation() {
+    const c = this.convo;
+    if (!c) return;
+    this.game._activeConvos = Math.max(0, (this.game._activeConvos ?? 1) - 1);
+    for (const npc of [c.a, c.b]) {
+      if (npc.convo !== c) continue;
+      npc.convo = null;
+      npc.convoCooldown = 25 + Math.random() * 30;   // don't immediately re-pair
+      npc.wanderPause = 0.5 + Math.random();
+      npc.wanderTarget = null;
+      npc.play('idle', { fade: 0.3 });
+    }
+  }
+
+  // A neighbour who's also lingering → they turn to face each other, so a knot of stopped
+  // wanderers reads as a conversation even without the paired clips.
+  _chatMate() {
+    let best = null, bd = 3.2;
+    for (const n of this.game.npcs) {
+      if (n === this || !n.alive || !n._wanderPts || n.convo || !(n.wanderPause > 0)) continue;
+      const d = dist2D(this.position.x, this.position.z, n.position.x, n.position.z);
+      if (d < bd && d > 0.8) { bd = d; best = n; }
+    }
+    return best;
+  }
+
+  update(dt) {
+    super.update(dt);
+    if (!this.alive) return;
+
+    const player = this.game.player;
+    if (!player) return;
+    const pd = dist2D(this.position.x, this.position.z, player.position.x, player.position.z);
+
+    // NEAREST TALKABLE — the cheap way (WESTERN SEAMS §3). main.js zeroes game._talkCand right before
+    // this loop; every NPC already holds `pd` here, so offering himself as an E-to-talk target is a
+    // couple of compares, not a second O(169) scan. THE ARRAY IS THE FACTION TEST: outlaws and the
+    // law-when-hostile are Enemy instances in combat.enemies / crime.lawmen, never in game.npcs, so a
+    // man iterated here can never be one. A fleeing, reeling or dead man is not offered; a child IS
+    // (the boy asking whether you've ever shot anyone is the whole point).
+    { const g = this.game;
+      if (this.alive && this.civilian && !this.busy && this.fleeT <= 0 && pd < TALK_R && pd < (g._talkCandD ?? Infinity)) {
+        g._talkCandD = pd; g._talkCand = this;
+      } }
+    // FAR NPCs SLEEP ENTIRELY — no capsule sweep, no steering probe, no navgrid. That is what makes
+    // a hundred and fifty of them affordable: a sleeper costs the two distanceTo calls it took to
+    // find out he was asleep (this one and Character.update's), and 90-odd sleepers together are
+    // ~0.02 ms of the measured 2.0 ms npcs phase.
+    //
+    // Park him on idle on the way out, though, and this is not cosmetic pedantry: AI_RANGE is 60 m
+    // and the entity cull is 45 / 70 / 110 by quality (core/quality.js). At medium and high the body
+    // between those two lines is STILL DRAWN while its AI is asleep — so a man frozen mid-stride
+    // keeps his walk cycle turning over and moonwalks on the spot. Once, on the transition; never
+    // again until he wakes. (At LOW the cull is nearer than AI_RANGE, which is why fourteen
+    // townsfolk in a town you only ever saw at low quality never showed it.)
+    //
+    // …and `aiRange` is the ONE way that 60 can be argued with. A ROAD TRAVELLER (traveller.js) is
+    // drawn out to 140 m because there is nothing in front of him but desert, and a man DRAWN but
+    // ASLEEP is a statue standing in the middle of an empty road — the exact moonwalk bug above, in
+    // its worst form. So he raises this to his own cull distance and walks for as long as he is seen.
+    // Every other NPC in the county leaves it undefined and gets 60.
+    // MISSION FOLLOW (missions.js stage `follow:`): on the player's heel — an escortee, a recruit
+    // being walked home. BEFORE the far-sleep gate, so a man you're escorting never freezes when you
+    // pull ahead; A* around statics via steerCarrot (the riders' pattern), whiskers for the crowd.
+    if (this._follow) {
+      this._asleep = false;
+      // ALLY-SHOOT — a GUNHAND on your heel fights: nearest AWAKE hostile engaged near the player
+      // (never aggroing the county on his own), inside 30m with a clear line. He stands his ground,
+      // faces it, and fires on a lazy cooldown with an honest miss rate — support fire, not an
+      // aimbot; your fight stays yours.
+      if (this.def.gunhand) {
+        this._allyScanT = (this._allyScanT ?? 0) - dt;
+        if (this._allyScanT <= 0) {
+          this._allyScanT = 0.4;
+          let best = null, bd = 30;
+          for (const e of this.game.combat?.enemies ?? []) {
+            if (!e.alive || e.faction === 'ally' || e.passive) continue;
+            const de = dist2D(this.position.x, this.position.z, e.position.x, e.position.z);
+            const dp = dist2D(e.position.x, e.position.z, player.position.x, player.position.z);
+            if (de < bd && dp < 32) { bd = de; best = e; }
+          }
+          this._allyTarget = best;
+        }
+        const t = this._allyTarget;
+        if (t?.alive && !this.game.world.losBlocked?.(this.position, t.position)) {
+          this.heading = Math.atan2(t.position.x - this.position.x, t.position.z - this.position.z);
+          this.root.rotation.y = this.heading;
+          this._allyFireT = (this._allyFireT ?? 0.9) - dt;
+          if (this._allyFireT <= 0) {
+            this._allyFireT = 1.7 + Math.random() * 0.9;
+            this.animator?.play?.('gunFire', { once: true, fade: 0.08, onDone: () => {} });
+            const mz = tmpV1.set(this.position.x, this.position.y + 1.35, this.position.z);
+            this.game.vfx?.muzzleFlash?.(mz, null);
+            this.game.audio?.play('gunshot_far');
+            if (Math.random() < 0.38) t.takeDamage(12, this.position, { attacker: this });
+          } else if (!this.animator?.actions?.gunFire?.isRunning?.()) this.play('gunAim');
+          return;                                   // standing his ground — no follow-move this frame
+        }
+      }
+      if (pd > 2.6) {
+        let ax = player.position.x, az = player.position.z;
+        if (steerCarrot(this, this.game, player.position, this.position.x, this.position.z, ax, az, _fAim,
+          { dt, arrive: 1.4, lookahead: 2.5 })) { ax = _fAim.x; az = _fAim.z; }
+        const dx = ax - this.position.x, dz = az - this.position.z, L = Math.hypot(dx, dz) || 1;
+        const sd = this.walkDir(_fDir.set(dx / L, 0, dz / L), dt);
+        this.heading = Math.atan2(sd.x, sd.z);
+        this.root.rotation.y = this.heading;
+        const spd = pd > 9 ? 5.2 : Math.min(this.speed ?? 2, 2.2);   // jog to catch up, walk at heel
+        this.move(sd, spd, dt);
+        this.play(spd > 3 ? 'run' : 'walk');
+      } else this.play(this._idleClip ?? 'idle');
+      return;
+    }
+    if (pd > (this.aiRange ?? AI_RANGE)) {
+      if (!this._asleep) { this._asleep = true; this.play('idle', { fade: 0.4 }); }
+      return;
+    }
+    this._asleep = false;
+
+    // BEING SPOKEN TO. ui/dialogue.js owns the panel and the talk camera; the NPC's whole side of
+    // the contract is three lines — turn to the lens, hold an attentive idle, and stop wandering off
+    // mid-sentence. (ui.currentNPC is set on open, nulled on close.) Hoisted ABOVE flee/wander so a
+    // posted man obeys it too, and so a gunfight two streets over can't walk him out of frame while
+    // you talk; a bullet still ends it the other way — player.js closes the panel when he's hit.
+    const ui = this.game.ui;
+    if (ui?.dialogueOpen && ui.currentNPC === this) {
+      this.faceToward(player.position.x, player.position.z, dt, 6);
+      this.wanderTarget = null;
+      if (this.convo) this._endConversation();
+      this.socialIdle(dt);
+      this.applyDescentSmoothing(dt);
+      return;
+    }
+
+    // fear: an outlaw hunting nearby sends the unarmed running (posted NPCs and the sheriff hold)
+    if (this.fleeT <= 0 && !this.posted && this.def.flee !== false) {
+      const d = this._danger();
+      if (d) this.scare(d.x, d.z);
+    }
+    if (this.fleeT > 0) {
+      this.fleeT -= dt;
+      // A MAN WHO HAS JUST BEEN HIT REELS BEFORE HE RUNS. takeDamage set busy and started the 'hit'
+      // clip; playing 'run' on the same frame threw that reaction straight in the bin — he was
+      // sprinting away before the bullet had visibly landed. Hold still until the reel is done.
+      if (this.busy) { this.applyDescentSmoothing(dt); return; }
+      const from = this._fleeFrom ?? player.position;
+      const dir = tmpV1.set(this.position.x - from.x, 0, this.position.z - from.z);
+      if (dir.lengthSq() < 1e-6) dir.set(1, 0, 0);
+      dir.normalize();
+      const sd = this.walkDir(dir, dt);
+      this.move(sd, 3.6, dt);
+      this.faceToward(this.position.x + sd.x, this.position.z + sd.z, dt);
+      this.play('run');
+      this.applyDescentSmoothing(dt);
+      if (this.fleeT <= 0) { this.wanderTarget = null; this._navPath = null; this.wanderPause = 1 + Math.random(); }
+      return;
+    }
+
+    if (this.posted) this.postedUpdate(dt, player, pd);
+    else if (this.convo) this.updateConversation(dt);
+    else this.wanderUpdate(dt, player, pd);
+
+    this.applyDescentSmoothing(dt);
+  }
+
+  // POSTED: hold the mark. The player can physically shove NPCs around (player.separateFromPeople),
+  // so a barkeep CAN be pushed off his spot — walk back to it rather than serving from the middle
+  // of the room forever.
+  postedUpdate(dt, player, pd) {
+    // MID YARD-TALK (main.js schedules the takes on the housed crew): stand your ground, face your
+    // partner, let the take run — both the walk-back-to-post branch and socialIdle would stomp it.
+    if (this._yardChat) { this.faceToward(this._yardChat.x, this._yardChat.z, dt, 4); return; }
+    const p = this.post;
+    const d = dist2D(this.position.x, this.position.z, p.x, p.z);
+    if (d > 0.4) {
+      const dir = tmpV1.set(p.x - this.position.x, 0, p.z - this.position.z).normalize();
+      this.move(dir, Math.min(this.speed, 1.3), dt);   // short, slow steps back — no pathing indoors
+      this.faceToward(p.x, p.z, dt, 6);
+      this.play('walk');
+      return;
+    }
+    // A NOD FOR THE PASSER-BY. Now and then a posted townsperson greets the man walking past —
+    // a raised hand, nothing said — the small-town reflex every western street runs on. Rare
+    // (a per-soul cooldown measured in minutes), never from a seated man, and the wave holds
+    // via the same guard the yard-talk uses so socialIdle can't stomp it a frame in.
+    this._greetCd = Math.max(0, (this._greetCd ?? Math.random() * 60) - dt);
+    if (pd < 3.2 && !this.def.seatedNoTurn && this._greetCd <= 0 && this.animator?.actions?.idleWave) {
+      this._greetCd = 90 + Math.random() * 120;
+      this._yardChat = { x: player.position.x, z: player.position.z };
+      this.animator.play('idleWave', { once: true, fade: 0.2, onDone: () => { this._yardChat = null; } });
+      return;   // the fall-through would hand the frame straight to socialIdle and stomp the wave
+    }
+    // On the mark: clock the player when he's close, else hold the post's authored heading
+    // (the sheriff keeps watching the street; the barkeep keeps facing his room). A seatedNoTurn
+    // man (the pianist at the keys) never swings round — his legs are under the piano — so he
+    // always holds his authored heading no matter how close you stand.
+    if (pd < 4.5 && !this.def.seatedNoTurn) this.faceToward(player.position.x, player.position.z, dt, 3);
+    else if (p.face != null) this.faceToward(this.position.x + Math.sin(p.face), this.position.z + Math.cos(p.face), dt, 3);
+    this.socialIdle(dt);
+  }
+
+  // WANDER: roam the route, lingering at each point; occasionally stage a real conversation.
+  wanderUpdate(dt, player, pd) {
+    if (this.convoCooldown > 0) this.convoCooldown -= dt;
+
+    if (this.wanderPause > 0) {
+      this.wanderPause -= dt;
+      // NEVER STAND INSIDE A THING. Every pause path funnels through here, and a stood man runs no
+      // capsule move to push him out of a prop edge he drifted into — corrected once per stand
+      // (the soak kept catching farm roamers wintering in their own barn walls).
+      if (!this._standFixed) {
+        this._standFixed = true;
+        const c0 = this.game.world.collide(this.position.x, this.position.z, 0.4, 0, this.position.y);
+        if (c0 && Math.hypot(c0.x - this.position.x, c0.z - this.position.z) > 0.02) {
+          this.position.x = c0.x; this.position.z = c0.z;
+        }
+      }
+      // Polite step-aside: steering only runs while WALKING, so two NPCs who came to rest inside
+      // each other would stay there forever. A paused NPC someone is standing on takes a step apart.
+      this._sepT = (this._sepT ?? Math.random() * 0.3) - dt;
+      if (this._sepT <= 0) {
+        this._sepT = 0.3;
+        for (const n of this.game.npcs) {
+          if (n === this || !n.alive) continue;
+          const dx = this.position.x - n.position.x, dz = this.position.z - n.position.z;
+          const d2 = dx * dx + dz * dz;
+          if (d2 < 0.45) {   // < ~0.67m — inside each other's bodies
+            const d = Math.sqrt(d2) || 1;
+            const stacked = d2 < 1e-4;   // perfectly overlapped → stable per-entity pick, or they'd both step the same way
+            this._sepDir = stacked ? { x: (this.root.id & 1) ? 1 : -1, z: 0.3 } : { x: dx / d, z: dz / d };
+            this._sepWalk = 0.5;
+            break;
+          }
+        }
+      }
+      if (this._sepWalk > 0) {
+        this._sepWalk -= dt;
+        tmpV1.set(this._sepDir.x, 0, this._sepDir.z).normalize();
+        this.move(tmpV1, 1.2, dt);
+        this.faceToward(this.position.x + tmpV1.x, this.position.z + tmpV1.z, dt, 6);
+        this.play('walk');
+        return;
+      }
+      // occasionally strike up a full staged conversation with a nearby free idler
+      this._convoScanT -= dt;
+      if (this._convoScanT <= 0) {
+        this._convoScanT = 0.5;
+        if (this.convoCooldown <= 0 && Math.random() < 0.5) { this._seekConversation(); if (this.convo) return; }
+      }
+      const mate = this._chatMate();
+      if (mate) this.faceToward(mate.position.x, mate.position.z, dt, 3);   // stop and pass the time of day
+      else if (pd < 4) this.faceToward(player.position.x, player.position.z, dt, 3);
+      this.socialIdle(dt);
+      return;
+    }
+
+    if (!this.wanderTarget) {
+      const pts = this._wanderPts;
+      if (!pts.length) { this.wanderPause = 5; return; }
+      // DON'T PICK A POINT WE JUST FAILED TO REACH. Off the nav grids (a farm, a fenced field)
+      // reachability can't be pre-checked, so a fence across the roam disc made an NPC walk into
+      // the same corner, stall, give up, and pick the same doomed point forever (Nick saw her).
+      // Recent failures (the no-progress give-up below records them) poison a 6m radius for a
+      // couple of minutes; a pick that can't avoid them takes the LONGEST pause instead of a walk.
+      const fails = (this._wanderFails ??= []);
+      const now = this.game._playSeconds ?? 0;
+      while (fails.length && now - fails[0].t > 120) fails.shift();
+      let p = null;
+      for (let tries = 0; tries < 6 && !p; tries++) {
+        const cand = pts[(Math.random() * pts.length) | 0];
+        if (!fails.some((f) => dist2D(f.x, f.z, cand.x, cand.z) < 6)) p = cand;
+      }
+      if (!p) { this.wanderPause = 6 + Math.random() * 6; return; }   // everywhere near here is poisoned — stand a while
+      // Personal offset around the shared point — several NPCs picking the SAME point would
+      // otherwise finish standing INSIDE each other. VALIDATE the offset on the NAVGRID (which
+      // knows about the BVH: crates, water troughs, porch posts), falling back to the circle
+      // collider test while the grid is still baking.
+      const grd = this._navGrid();
+      let tx = p.x, tz = p.z;
+      for (let i = 0; i < 4; i++) {
+        const cx = p.x + (Math.random() - 0.5) * 2.4, cz = p.z + (Math.random() - 0.5) * 2.4;
+        let ok;
+        if (grd) ok = grd.walkable(cx, cz) === true;
+        else {
+          const cor = this.game.world.collide(cx, cz, 0.45, 0, this.position.y);
+          ok = !cor || (Math.abs(cor.x - cx) < 1e-6 && Math.abs(cor.z - cz) < 1e-6);
+        }
+        if (ok) { tx = cx; tz = cz; break; }
+      }
+      this.wanderTarget = { x: tx, z: tz };
+      this._navPath = this._requestPath(this.wanderTarget);   // A* around the statics (null until the grid bakes)
+      this._navI = 0;
+      // grid ready but no route → the goal is unreachable (a walled yard, a sealed pocket):
+      // DISCARD it. Walking blind at an unreachable goal is how you get an NPC nose-first
+      // into a wall for the rest of the game.
+      if (!this._navPath && grd) { this.wanderTarget = null; this.wanderPause = 0.3; return; }
+      this._wanderCheck = 0;
+      this._wanderLastX = this.position.x;
+      this._wanderLastZ = this.position.z;
+    }
+
+    const t = this.wanderTarget;
+    const td = dist2D(this.position.x, this.position.z, t.x, t.z);
+    // arrive EARLY when the goal is close but the way ahead reads blocked (the porch the point
+    // sits beside): stopping 2.4m out reads as "reached the store", not as walking into its wall.
+    if (this._steerBlockAhead && td <= 2.4) {
+      // same don't-settle-INSIDE check as the true arrival below — this early-out was the one way
+      // to come to rest embedded in a prop edge (the soak caught seven farmhands doing it)
+      const cor0 = this.game.world.collide(this.position.x, this.position.z, 0.4, 0, this.position.y);
+      if (cor0 && (Math.abs(cor0.x - this.position.x) > 1e-6 || Math.abs(cor0.z - this.position.z) > 1e-6)) {
+        this.position.x = cor0.x; this.position.z = cor0.z;
+      }
+      this.wanderPause = 2 + Math.random() * 4; this.wanderTarget = null; return;
+    }
+    if (td <= 1.5) {
+      // don't settle INSIDE an obstacle — collide() returns the CORRECTED position (always
+      // truthy); "inside" means the point MOVED. Shuffle on to a fresh spot instead.
+      const cor = this.game.world.collide(this.position.x, this.position.z, 0.4, 0, this.position.y);
+      if (cor && (Math.abs(cor.x - this.position.x) > 1e-6 || Math.abs(cor.z - this.position.z) > 1e-6)) { this.wanderTarget = null; return; }
+      this.wanderPause = 2 + Math.random() * 5;   // linger at the boardwalk / the rail / the door
+      this.wanderTarget = null;
+      return;
+    }
+
+    // Give up on a destination we're making no progress toward, rather than shoving into it forever.
+    this._wanderCheck += dt;
+    if (this._wanderCheck > 1) {
+      const moved = dist2D(this.position.x, this.position.z, this._wanderLastX, this._wanderLastZ);
+      this._wanderCheck = 0;
+      this._wanderLastX = this.position.x;
+      this._wanderLastZ = this.position.z;
+      if (moved < 0.4) {
+        // record WHERE we were headed when we stalled — the picker refuses it for a couple of
+        // minutes, which is what breaks the fence-corner loop (walk, stall, same point, forever)
+        const fails = (this._wanderFails ??= []);
+        fails.push({ x: this.wanderTarget.x, z: this.wanderTarget.z, t: this.game._playSeconds ?? 0 });
+        if (fails.length > 4) fails.shift();
+        this.wanderTarget = null; this._navPath = null; this.wanderPause = 1.2 + Math.random() * 2; return;
+      }
+    }
+    if (!this._navPath) {
+      this._navRetryT = (this._navRetryT ?? 0) - dt;   // the grid may still be baking — retry occasionally
+      if (this._navRetryT <= 0) {
+        this._navRetryT = 1.5;
+        this._navPath = this._requestPath(t); this._navI = 0;
+        if (!this._navPath && this._navGrid()) { this.wanderTarget = null; this.wanderPause = 0.3; return; }
+      }
+    }
+    this._standFixed = false;           // walking again — the next stand re-checks its ground
+    const wp = this._pathWaypoint(t);
+    const dir = tmpV1.set(wp.x - this.position.x, 0, wp.z - this.position.z).normalize();
+    const sd = this.walkDir(dir, dt);   // whiskers: DYNAMIC avoidance (people) — the statics are pre-avoided by the path
+    this.move(sd, this.speed * (this._steerSlow ? 0.55 : 1), dt);
+    this.faceToward(this.position.x + sd.x, this.position.z + sd.z, dt);
+    this.play('walk');
+  }
+}
+
+// Alarm every townsperson within `r` of a point — a gunshot, a brawl, a body in the street.
+// Called from combat.fireBullet (every shot fired anywhere scatters the street), from a townsman's
+// own death, and from the coach when its driver is shot off the box. `force` drags even the posted
+// men off their marks — see scare(): keep it for things that happen ON TOP of somebody.
+// Cheap: ~13 townsfolk, and only ever on an EVENT (a shot, a death), never per frame.
+export function alarmTown(game, x, z, r = 18, secs = 3, force = false) {
+  for (const n of game.npcs ?? []) {
+    if (!n.alive) continue;
+    if (dist2D(n.position.x, n.position.z, x, z) < r) n.scare(x, z, secs, force);
+  }
+}
+
+// THE WHOLE COUNTY, built ONCE on the loading screen — every NPC resident and scene-attached for
+// life (adding or toggling skinned meshes during play is a WebGPU pipeline build and a
+// multi-second freeze). Mirrors combat.spawn(): construct → await load() → scene.add → push.
+//
+// BATCHED, not serial. The old populateTown awaited each body in turn — fine for 14, and 0.9s of
+// dead wall-clock for 170 (a marginal body from an already-cached pack costs 2.5-3.5 ms, measured
+// off the boot sink). The loads share ONE model cache, so N in flight cost roughly the slowest,
+// not the sum. 16 at a time keeps the FBX parses from stampeding each other on the first pack.
+const BATCH = 16;
+export async function populateCounty(game, clips, defs = NC.countyDefs) {
+  game.npcs ??= [];
+  game.children ??= [];    // the children, as their own list: player.js aims a separate ray at it
+  let failed = 0;
+  for (let i = 0; i < defs.length; i += BATCH) {
+    await Promise.all(defs.slice(i, i + BATCH).map(async (def) => {
+      try {
+        const npc = new NPC(game, def, clips);
+        await npc.load();
+        npc.settle();                 // drop onto the terrain / the deck / the saloon floorboards
+        game.scene.add(npc.root);
+        game.npcs.push(npc);
+        if (npc.child) game.children.push(npc);
+      } catch (e) {
+        failed++;
+        console.warn('[npc] spawn failed', def.id, e);   // one bad def must never take the boot down
+      }
+    }));
+  }
+  const kids = game.children.length;
+  console.log(`[npc] the county is peopled: ${game.npcs.length} souls (${kids} children)${failed ? ` — ${failed} FAILED` : ''}`);
+  return game.npcs;
+}
+
+// Dustwater only — kept for anything that still wants just the town (and for a quick A/B).
+export const populateTown = (game, clips, defs = NC.npcDefs) => populateCounty(game, clips, defs);