sindicate 0.4.0 → 0.5.0

package/src/systems/crime.js

@@ -0,0 +1,582 @@
+// THE LAW — Dustwater's four-star wanted system.
+//
+// A counter is not a wanted system. What makes it a game is that the town has EYES: shoot a man
+// on Main Street in front of six people and the sheriff knows your face within the minute; shoot
+// the same man out in the creosote with nobody inside a hundred yards and it is a rumour. So heat
+// is scored per crime and then WEIGHTED BY WITNESSES (living townsfolk with line of sight), and
+// it only cools while nobody — no lawman, no townsman — can see you. That is the whole loop:
+// break contact, get out of town, wait it out.
+//
+// THE LAWMEN ARE PRE-BUILT. PERF LAW: a skinned mesh may never enter or leave the scene during
+// play (WebGPU pipeline builds → multi-second freezes). So the posse — 4 deputies + 2 marshals —
+// is spawned ONCE on the loading screen through combat.spawn() and parked at Fort Copperhead's
+// parade ground (OUTPOSTS 'fort', 470m north: past the entity cull, so they are invisible, their
+// animators frozen, their AI striding at 1/4 rate — they cost nothing). "Dispatching" a lawman is
+// moving a man who already exists to a muster point and provoking him; "the heat dying" is walking
+// him back to the fort. Nothing is ever created, added, or removed.
+//
+// They are ordinary Enemy instances running the ordinary Enemy FSM (wander→chase→shoot) — no new
+// AI. Two things follow from that and are deliberate:
+//   * faction 'hostile', NOT 'ally'. combat.js's friendly-bullet loop SKIPS faction 'ally'
+//     (combat.js:404) — an "ally" lawman would be unshootable, and a wanted system whose police
+//     cannot be shot is not a wanted system. 'hostile' also means lawmen and outlaws ignore each
+//     other (same TEAM in enemy.js); the law is here for YOU, and teaching foes() a third team
+//     would mean editing enemy.js, which this system does not own.
+//   * their ENEMY_TYPES defs are REGISTERED from here (below). enemy.js keeps its defs inline and
+//     there is no data/enemies.js; registering into the exported table is how the law gets bodies
+//     without forking the Enemy class.
+import * as THREE from 'three/webgpu';
+import { ENEMY_TYPES } from './enemy.js';   // read-only here: the game registers law tiers with the roster
+import { alarmTown } from './npc.js';
+// where the off-screen law bench parks is game data: setLawBench({ x, z })
+let BENCH = { x: 40, z: -470 };
+export function setLawBench(p) { if (p) BENCH = p; }
+import { dist2D } from '../core/utils.js';
+
+const _v = new THREE.Vector3();   // module-local temp: tmpV1 is shared with combat's bullet loop
+
+// ── the bodies ──────────────────────────────────────────────────────────────────────────────
+// Same idiom as enemy.js's `outlaw()`/`townOutlaw()` helpers: one multi-char FBX, keep-filter a
+// body, the pack's atlas, texFlipY (FBX UVs). The Sheriff body is the one characters.js reserves
+// for the law ("keep out of the outlaw roster"); the marshals ride on the frontier pack's Hunter
+// body so a posse doesn't read as six clones of the same man.
+// Law-tier defs are registered with the rest of the game's roster (data/enemyTypes.js).
+
+// ── the ledger ──────────────────────────────────────────────────────────────────────────────
+// Heat per crime, BEFORE witnesses. A scuffle is a scuffle; a body in the street is a hanging
+// offence; the coach is the county's money and brings the law down hard; a dead lawman is worse
+// than all of it — one killing puts you straight to three stars even unseen.
+const HEAT = {
+  assault: 7,
+  murder: 26,
+  robbery: 12,        // going through a dead man's pockets
+  theft: 14,          // pulling a man off his horse and taking it — a hanging offence out here
+  coachRobbery: 34,
+  lawman: 55,
+  // POINTING A GUN AT A CHILD. Cannot hurt him — he takes no damage, ever (npc.js) — but it
+  // frightens him and the street sees you do it. Deliberately just under a star's worth at five
+  // witnesses (5 x 1.88 = 9.4 against the 10 a star costs): do it once on Main Street and you get
+  // a black look; do it twice and the law wants a word. Unseen it is 1.1 heat and nothing happens,
+  // because nothing was seen to happen.
+  menace: 5,
+};
+// heat → stars. Derived, never set: the level can only move because heat moved.
+const STARS = [10, 30, 60, 100, 150];
+const MAX_HEAT = 200;                       // headroom above 5 stars so it doesn't drop the instant you stop
+
+// Cooling, per star. Nothing cools while you are SEEN (see _spotted). Higher levels cool slower —
+// 1 star is gone in ~10s of quiet, 4 stars takes ~100s of unbroken evasion (it decays through the
+// lower tiers on the way down, each at its own rate).
+// ONE ENTRY PER STAR, AND THERE ARE FIVE. These are indexed BY LEVEL, so a five-star level reading
+// a four-long table gets `undefined` — and `x > undefined` is false, so the heat would simply never
+// cool again. Permanently wanted, with no way to tell why. An off-by-one in a tuning table is
+// invisible until it is the whole game.
+const COOL_DELAY = [0, 4, 6, 9, 13, 18];         // seconds of not-seen, not-offending before heat moves
+const COOL_RATE = [0, 4.5, 2.4, 1.3, 0.75, 0.5]; // heat per second once it does
+
+// Who comes. Level 1 is one deputy taking an interest; level 4 is a posse with rifles.
+const RESPONSE = [
+  { deputies: 0, marshals: 0 },
+  { deputies: 1, marshals: 0 },
+  { deputies: 2, marshals: 0 },
+  { deputies: 3, marshals: 1 },
+  { deputies: 4, marshals: 2 },
+  { deputies: 4, marshals: 2 },     // five stars: everything the county has, and it comes for you
+];
+const DISPATCH_GAP = [0, 9, 7, 5, 3.5, 2.5];   // seconds between men leaving the jail
+const POOL = { law_deputy: 4, law_marshal: 2 };
+
+// WITNESSES. 26m is about as far as a townsman will swear to a face; line of sight is the real
+// gate (world.losBlocked — the same test combat uses so you can't be shot through a wall).
+const WITNESS_R = 26;
+const TATTLE_R = 18;                        // a witness this close keeps pointing you out: heat won't cool
+
+// WHERE THE LAW COMES FROM. Real places, so nobody materialises at your elbow: the two ends of the
+// jail's boardwalk (jail_1 sits at 15.96,-11.99, its door facing west onto the street) and the two
+// ends of Main Street, for men riding in. MIN_MUSTER keeps a spawn off-camera-ish; MAX_MUSTER is
+// the point past which "from the jail" becomes a five-minute walk and we muster a posse near the
+// player instead (they rode out after you — that is what a posse IS).
+const LAW_POSTS = [
+  { x: 12.6, z: -14.6 },   // outside the jail, south end of its deck
+  { x: 12.6, z: -9.4 },    // outside the jail, north end
+  { x: 1, z: -46 },        // north end of Main Street
+  { x: -1, z: 46 },        // south end of Main Street
+];
+const MIN_MUSTER = 22;      // never closer to the player than this
+const MAX_MUSTER = 150;     // past this the jail is useless — ride a posse out to him
+const POSSE_R = 58;         // and put them down this far out, behind him if we can
+
+
+
+export class Crime {
+  constructor(game) {
+    this.game = game;
+    this.heat = 0;
+    this.level = 0;
+    this.lawmen = [];          // the resident pool (Enemy instances, all in combat.enemies for life)
+    this._coolT = 0;
+    this._dispatchT = 0;
+    this._retargetT = 0;
+    this._lastKnown = new THREE.Vector3();   // where the law thinks you are — only refreshed while they can see you
+    this._lawKillT = 0;        // de-dup window: this system self-detects lawman deaths (see report)
+    this._buildHUD();
+  }
+
+  // Built on the LOADING SCREEN. Must run after combat.populate() (it needs combat.clips) — see
+  // the wiring block at the bottom of this file.
+  async build() {
+    const c = this.game.combat;
+    if (!c) { console.warn('[crime] no combat system — the law will never ride'); return this; }
+    let i = 0;
+    for (const [type, count] of Object.entries(POOL)) {
+      for (let n = 0; n < count; n++, i++) {
+        const a = (i / 6) * Math.PI * 2;
+        const x = BENCH.x + Math.sin(a) * 6, z = BENCH.z + Math.cos(a) * 6;
+        try {
+          // leashR 3 + passive: benched men mill about the parade ground and never aggro. They are
+          // 470m from town — past quality.entityCull, so Character.update hides them and freezes
+          // their animator on frame one. (If the player rides all the way to the fort he'll find
+          // the garrison standing about. They won't start anything. Shooting one is a crime.)
+          const e = await c.spawn(type, x, z, { leashR: 3, passive: true });
+          e.lawman = true;               // other systems can tell a badge from an outlaw
+          this.lawmen.push(e);
+        } catch (err) { console.warn('[crime] lawman failed to muster', type, err); }
+      }
+    }
+    return this;
+  }
+
+  // ── the public ledger ─────────────────────────────────────────────────────────────────────
+  // kind: 'assault' | 'murder' | 'robbery' | 'coachRobbery' | 'lawman'
+  report(kind, position) {
+    const base = HEAT[kind];
+    if (base == null) return;
+    // Killing a badge is self-detected below (a lawman leaving combat.enemies alive-ledger), so a
+    // combat.js that ALSO reports it can't double-charge you for the same corpse.
+    if (kind === 'lawman') {
+      if (this._lawKillT > 0) return;
+      this._lawKillT = 0.6;
+    }
+    const at = position ?? this.game.player?.position;
+    if (!at) return;
+
+    const w = this._witnesses(at);
+    // Unseen ≠ free: a body still turns up. But it is a quarter of the price, and that gap is the
+    // entire reason to think about WHERE you do a thing.
+    let mult = w > 0 ? 1 + 0.22 * Math.min(w - 1, 4) : 0.22;
+    // Two exceptions to "nobody saw it": the law already hunting you knows your face (no quiet
+    // murders once the posse is out), and a dead lawman is always missed by his own.
+    if (this.level > 0 || kind === 'lawman') mult = Math.max(mult, 1);
+
+    const before = this.level;
+    this.heat = Math.min(MAX_HEAT, this.heat + base * mult);
+    this._coolT = 0;
+    this._syncLevel(before);
+
+    // the street empties: a gunshot and a scream carry further than a face does
+    const small = kind === 'assault' || kind === 'menace';
+    if (kind !== 'robbery') alarmTown(this.game, at.x, at.z, small ? 14 : 22, small ? 2.5 : 4.5);
+  }
+
+  clear() {
+    this.heat = 0;
+    this._coolT = 0;
+    const before = this.level;
+    this.level = 0;
+    for (const e of this.lawmen) this._bench(e, true);   // force: called on death/reload, nobody's watching
+    if (before) this._paintStars();
+  }
+
+  isLawman(e) { return !!e?.lawman; }
+
+  // ── frame ─────────────────────────────────────────────────────────────────────────────────
+  update(dt) {
+    const p = this.game.player;
+    if (!p) return;
+    // Wall-clock-ish time, not the scaled dt: Dead Eye's slow-mo must not slow the cooldown to a
+    // crawl (the same reasoning main.js uses to tick deadEye on rawDt).
+    const rt = this.game.rawDt ?? dt;
+    if (this._lawKillT > 0) this._lawKillT -= rt;
+
+    this._tickBodies(rt);
+
+    const before = this.level;
+    if (this.heat > 0) {
+      // THROTTLED TO 4 Hz, and this is not a micro-optimisation. _spotted() walks every living
+      // soul in the county and fires a BVH line-of-sight ray at each one inside TATTLE_R — at
+      // fourteen townsfolk that was free, and at a hundred and fifty, standing in a crowded
+      // street, it is a fistful of raycasts EVERY FRAME just to ask whether anyone is looking.
+      // COOL_DELAY is 4-18 seconds and COOL_RATE is at most 4.5 heat/s, so a quarter-second of
+      // granularity is worth at most one heat and is invisible.
+      this._seenT = (this._seenT ?? 0) - rt;
+      if (this._seenT <= 0) { this._seenT = 0.25; this._seenC = this._spotted(); }
+      const seen = this._seenC;
+      if (seen) this._coolT = 0; else this._coolT += rt;
+      if (this._coolT > COOL_DELAY[this.level]) {
+        this.heat = Math.max(0, this.heat - COOL_RATE[this.level] * rt);
+        this._syncLevel(before);
+      }
+    }
+    this._dispatchUpdate(rt);
+    this._paintStars();
+  }
+
+  // ── heat → stars ──────────────────────────────────────────────────────────────────────────
+  _syncLevel(before) {
+    let lv = 0;
+    while (lv < 5 && this.heat >= STARS[lv]) lv++;
+    if (lv === this.level) return;
+    this.level = lv;
+    if (lv > before) {
+      this.game.audio?.play('aggro');
+      // the grace beat between "they know" and the first badge appearing — short at high stars
+      this._dispatchT = lv >= 3 ? 1.2 : 2.5;
+      const line = ['', 'A deputy is asking after you.', 'The sheriff has men on the street.',
+        'Marshals. They are hunting you now.', 'Every badge in the county wants you.',
+        'They have stopped trying to arrest you.'][lv];
+      if (lv === 4) {
+        this.game.ui?.questBanner?.('A POSSE RIDES');
+        this.game.ui?.toast?.('Every badge in the county wants you dead.', 5000);
+      } else if (line) this.game.ui?.toast?.(line, 3400);
+    } else if (lv === 0) {
+      this.game.ui?.toast?.('The law has lost your trail.', 3000);
+    }
+  }
+
+  // ── witnesses ─────────────────────────────────────────────────────────────────────────────
+  // Living townsfolk (game.npcs) and any coach crew who can SEE the spot. Coach riders are read
+  // defensively: they only became shootable people this wave and may not carry .position yet.
+  _witnesses(at) {
+    let n = 0;
+    for (const t of this.game.npcs ?? []) {
+      if (!t.alive) continue;
+      if (dist2D(t.position.x, t.position.z, at.x, at.z) > WITNESS_R) continue;
+      if (this.game.world.losBlocked(t.position, at)) continue;
+      n++;
+    }
+    // A NEUTRAL OUTFIT'S GUN IS A WITNESS TOO. He is an Enemy by mechanism (so that he can shoot
+    // back) and a civilian by law (enemy.js `civilian`), and he is standing four feet from the man
+    // you just shot. Without this line the drover's own partner does not see his murder.
+    for (const e of this.game.combat?.enemies ?? []) {
+      if (!e.alive || !e.civilian) continue;
+      if (dist2D(e.position.x, e.position.z, at.x, at.z) > WITNESS_R) continue;
+      if (this.game.world.losBlocked(e.position, at)) continue;
+      n++;
+    }
+    for (const c of this.game.coaches?.coaches ?? []) {
+      for (const r of c.riders ?? []) {
+        if (!r?.alive || !r.position || r.pivot?.visible === false) continue;
+        if (dist2D(r.position.x, r.position.z, at.x, at.z) > WITNESS_R) continue;
+        if (this.game.world.losBlocked(r.position, at)) continue;
+        n++;
+      }
+    }
+    return n;
+  }
+
+  // Are you being watched? A lawman inside his aggro range with a clear line, or a townsman close
+  // enough to keep pointing. Either one freezes the cooldown — this is "break line of sight, get
+  // out of town", made literal.
+  _spotted() {
+    const p = this.game.player;
+    if (!p.alive) return false;
+    for (const e of this.lawmen) {
+      if (!e.alive || !e._onDuty) continue;
+      const d = dist2D(e.position.x, e.position.z, p.position.x, p.position.z);
+      if (d > e.def.aggroR) continue;
+      if (this.game.world.losBlocked(e.position, p.position)) continue;
+      this._lastKnown.copy(p.position);   // the law only ever knows where it last SAW you
+      return true;
+    }
+    for (const t of this.game.npcs ?? []) {
+      if (!t.alive) continue;
+      if (dist2D(t.position.x, t.position.z, p.position.x, p.position.z) > TATTLE_R) continue;
+      if (this.game.world.losBlocked(t.position, p.position)) continue;
+      return true;
+    }
+    return false;
+  }
+
+  // ── the pool: corpses, recycling, and the one perf trap ───────────────────────────────────
+  // combat.js EVICTS a body 6 seconds after death (scene.remove + splice out of combat.enemies).
+  // For an outlaw that's fine; for a pooled lawman it would tear a resident skinned mesh out of the
+  // scene — and putting him back would be exactly the pipeline stall the perf law exists to stop.
+  // So a dead lawman never reaches that flag: his deathT is held below the 6s eviction while the
+  // player is anywhere near (the corpse lies in the street, lootable, as a corpse should), and once
+  // the player is well clear he is quietly recycled back to the fort — indistinguishable from the
+  // corpse eviction the player already sees for outlaws.
+  _tickBodies(dt) {
+    const p = this.game.player;
+    for (let i = this.lawmen.length - 1; i >= 0; i--) {
+      const e = this.lawmen[i];
+      if (e.dead) { this.lawmen.splice(i, 1); continue; }   // combat got him first (a dt spike) — he's gone; the county is short a man
+      if (e.alive) continue;
+      if (!e._deathSeen) {
+        e._deathSeen = true;
+        // SELF-DETECTED: killing a badge is a crime, and this system is the only one that knows
+        // which enemy was a badge. combat.js does not need to know about the law at all.
+        this.report('lawman', e.position.clone());
+      }
+      const d = dist2D(e.position.x, e.position.z, p.position.x, p.position.z);
+      if (d > 70) this._bench(e, true);
+      else if (e.deathT > 4.5) e.deathT = 4.5;   // hold the body: never let combat's 6s eviction fire
+    }
+  }
+
+  // ── dispatch ──────────────────────────────────────────────────────────────────────────────
+  _dispatchUpdate(dt) {
+    const p = this.game.player;
+    const want = RESPONSE[this.level];
+    let onDuty = 0, dep = 0, mar = 0;
+    for (const e of this.lawmen) {
+      if (!e._onDuty || !e.alive) continue;
+      onDuty++;
+      if (e.type === 'law_marshal') mar++; else dep++;
+    }
+
+    // Keep the hunt honest: while they're on you, re-home the chase on your last known position so
+    // enemy.js's leash can't yank a chasing man back to the muster point mid-street. When they lose
+    // you they converge on that spot and cast about — which is what makes running work.
+    this._retargetT -= dt;
+    if (this._retargetT <= 0 && onDuty) {
+      this._retargetT = 1.0;
+      for (const e of this.lawmen) {
+        if (!e._onDuty || !e.alive) continue;
+        e.home.x = this._lastKnown.x; e.home.z = this._lastKnown.z;
+        if (e.state === 'wander' && this.level > 0) e.provoke();   // reacquire — he's not done with you
+      }
+    }
+
+    // Stand men down as the heat falls — but only ones far enough out that nobody sees a deputy
+    // wink out of existence.
+    const surplus = onDuty - (want.deputies + want.marshals);
+    if (surplus > 0) {
+      let n = surplus;
+      for (const e of this.lawmen) {
+        if (n <= 0) break;
+        if (!e._onDuty || !e.alive) continue;
+        if (this._bench(e, false)) n--;
+      }
+    }
+
+    if (this.level === 0) return;
+    this._dispatchT -= dt;
+    if (this._dispatchT > 0) return;
+    const needM = want.marshals - mar, needD = want.deputies - dep;
+    if (needM <= 0 && needD <= 0) return;
+    const type = needM > 0 ? 'law_marshal' : 'law_deputy';
+    const man = this.lawmen.find((e) => e.type === type && e.alive && !e._onDuty)
+             ?? this.lawmen.find((e) => e.alive && !e._onDuty);   // out of marshals? send whoever's left
+    if (!man) return;
+    this._dispatchT = DISPATCH_GAP[this.level];
+    const spot = this._muster();
+    this._send(man, spot);
+  }
+
+  // Where the next man appears. The jail first (it's where lawmen ARE), unless the player is
+  // standing on top of it or two counties away; then a posse rides out to him — behind him if the
+  // camera allows, never in his face.
+  // WHERE THE LAW GOES — the last place it SAW you, not the place you actually are.
+  //
+  // This used to muster on the player's live position, and it made the wanted level inescapable:
+  // every new man rode out to wherever you were standing at that instant, arrived, saw you, and
+  // reset the cooldown — so the heat could never fall, no matter how far or how cleverly you ran.
+  // Measured: two stars, six hundred metres of empty desert, not a witness alive for half a mile,
+  // and the heat sat at 52 for a solid minute. The law was not hunting you; it was teleporting to
+  // you. A posse converges on where the trail went cold, and if you are not there, they cast about
+  // and lose you. That is the whole game of running.
+  _muster() {
+    const p = this._lastKnown ?? this.game.player.position;
+    let best = null, bestD = Infinity;
+    for (const s of LAW_POSTS) {
+      const d = dist2D(s.x, s.z, p.x, p.z);
+      if (d < MIN_MUSTER || d > MAX_MUSTER) continue;
+      const off = this._offCamera(s.x, s.z) ? 0 : 35;   // an out-of-shot post is worth 35m of walking
+      if (d + off < bestD) { bestD = d + off; best = s; }
+    }
+    if (best) return best;
+
+    // the posse: ring the player at POSSE_R, prefer off-camera and standing on open ground
+    let pick = null, pickScore = -Infinity;
+    for (let i = 0; i < 8; i++) {
+      const a = (i / 8) * Math.PI * 2;
+      const x = p.x + Math.sin(a) * POSSE_R, z = p.z + Math.cos(a) * POSSE_R;
+      let score = this._offCamera(x, z) ? 100 : 0;
+      // don't put a man inside a wall: world.collide returns the CORRECTED point, so "blocked"
+      // means it MOVED (the trap entity.js documents at _probeSteer)
+      const c = this.game.world.collide(x, z, 0.5, 0, this.game.world.groundAt(x, z));
+      if (Math.abs(c.x - x) > 1e-6 || Math.abs(c.z - z) > 1e-6) score -= 500;
+      score -= dist2D(x, z, 0, 0) * 0.02;   // all else equal, come from the town side
+      if (score > pickScore) { pickScore = score; pick = { x, z }; }
+    }
+    return pick ?? LAW_POSTS[0];
+  }
+
+  _offCamera(x, z) {
+    const f = this.game._camFrustum;
+    if (!f) return true;
+    _v.set(x, this.game.world.groundAt(x, z) + 1.0, z);
+    return !f.containsPoint(_v);
+  }
+
+  _send(e, spot) {
+    e.setPosition(spot.x, this.game.world.groundAt(spot.x, spot.z), spot.z);
+    e.home = { x: spot.x, z: spot.z };
+    e.leashR = 70;                     // long rein — the chase re-homes on _lastKnown every second
+    e.wanderTarget = null;
+    e._navPath = null;
+    e.target = null;
+    e._onDuty = true;
+    e.provoke();                       // passive off, straight into chase
+    e.faceToward(this.game.player.position.x, this.game.player.position.z);
+    this._lastKnown.copy(this.game.player.position);
+  }
+
+  // Back to the fort. `force` bypasses the "is anyone watching" test (death recycle, clear()).
+  // Returns true if he actually went.
+  _bench(e, force) {
+    const p = this.game.player;
+    if (!force && e.alive) {
+      const d = dist2D(e.position.x, e.position.z, p.position.x, p.position.z);
+      if (d < 50 && !this._offCamera(e.position.x, e.position.z)) return false;   // not while he's in shot
+    }
+    const i = this.lawmen.indexOf(e);
+    const a = (Math.max(0, i) / 6) * Math.PI * 2;
+    const x = BENCH.x + Math.sin(a) * 6, z = BENCH.z + Math.cos(a) * 6;
+    // full reset: a recycled corpse is a fresh man at the fort. Everything here is state the
+    // Enemy/Character FSM owns — clear all of it or he comes back mid-death-animation, staggered,
+    // with a swing still pending on someone who is now 500m away.
+    e.alive = true;
+    e.dead = false;
+    e.deathT = 0;
+    e.health = e.maxHealth;
+    e.busy = false;
+    e.staggerT = 0;
+    e._poiseT = 0;
+    e._hitBusyT = 0;
+    e._swing = null;
+    e._deathSeen = false;
+    e._onDuty = false;
+    e.passive = true;
+    e.state = 'wander';
+    e.target = null;
+    e.wanderTarget = null;
+    e._navPath = null;
+    e._token = undefined;
+    e.setPosition(x, this.game.world.groundAt(x, z), z);
+    e.home = { x, z };
+    e.leashR = 3;
+    e.animator?.play('idle');
+    return true;
+  }
+
+  // ── the HUD: four stars, top right ────────────────────────────────────────────────────────
+  // ui.js is not ours to edit, so the wanted block builds its own DOM into #hud — same idiom the
+  // rest of the HUD uses (one <style>, cached nodes, and EVERY DOM write behind a change check;
+  // this runs every frame). Dark empty stars, gold when lit, and the whole strip blinks while the
+  // heat is actually cooling — the GTA tell that says "keep it up and they're gone".
+  _buildHUD() {
+    if (document.getElementById('wanted')) return;
+    const css = document.createElement('style');
+    css.textContent = `
+      /* UNDER the money badge, not UNDERNEATH IT. Both this and the money counter were written to
+         the same corner (top:74px right:24px) by two hands that never met, so the stars rendered
+         behind the cash and you could not see them at all. The money block is 30px tall from 74,
+         so the law starts below it. */
+      #wanted { position:absolute; top:214px; right:26px; display:flex; flex-direction:column; align-items:flex-end; gap:3px;
+        opacity:0; transition:opacity 0.35s; filter:drop-shadow(0 2px 4px rgba(0,0,0,0.6)); }
+      #wanted.on { opacity:1; }
+      #wanted .wlbl { font-size:10px; letter-spacing:4px; color:#c9a24a; text-shadow:0 1px 3px #000; }
+      #wanted .wstars { display:flex; gap:2px; }
+      #wanted .wstar { width:24px; height:24px; background:center/contain no-repeat;
+        /* the real sprite out of INTERFACE_Military_Combat_HUD (Badge_Element_Star_01_Gold) — the
+           previous path pointed at a fantasy-warrior icon that does not exist in this project, so
+           every star was an empty box and a 404. It is already gold, so the LIT state does nothing
+           to it and the unlit state is the same star with the life drained out of it. */
+        background-image:url(/assets/ui/star_gold.png);
+        filter:grayscale(1) brightness(0.4); opacity:0.5; transition:filter 0.25s, opacity 0.25s, transform 0.25s; }
+      #wanted .wstar.lit { opacity:1;
+        filter:brightness(1.08) drop-shadow(0 0 6px rgba(240,200,90,0.8)); }
+      #wanted .wstar.new { animation: wstarpop 0.45s ease-out; }
+      @keyframes wstarpop { 0% { transform:scale(2.1) rotate(-25deg); } 60% { transform:scale(0.92); } 100% { transform:scale(1); } }
+      /* cooling: the law is losing you — the stars flutter (same beat as the Dead Eye pulse) */
+      #wanted.cooling .wstar.lit { animation: wstarblink 0.85s ease-in-out infinite; }
+      @keyframes wstarblink { 0%,100% { opacity:1; } 50% { opacity:0.3; } }
+    `;
+    document.head.appendChild(css);
+    const el = document.createElement('div');
+    el.id = 'wanted';
+    el.innerHTML = `<span class="wlbl">WANTED</span><div class="wstars">${'<i class="wstar"></i>'.repeat(5)}</div>`;
+    (document.getElementById('hud') ?? document.getElementById('app'))?.appendChild(el);
+    this._hud = el;
+    this._stars = [...el.querySelectorAll('.wstar')];
+    this._hudLvl = 0;
+    this._hudCool = false;
+  }
+
+  _paintStars() {
+    if (!this._hud) return;
+    if (this.level !== this._hudLvl) {
+      const rising = this.level > this._hudLvl;
+      this._hudLvl = this.level;
+      this._hud.classList.toggle('on', this.level > 0);
+      for (let i = 0; i < 5; i++) {
+        const lit = i < this.level;
+        this._stars[i].classList.toggle('lit', lit);
+        this._stars[i].classList.remove('new');
+        if (lit && rising && i === this.level - 1) {
+          void this._stars[i].offsetWidth;             // restart the keyframe on a re-lit star
+          this._stars[i].classList.add('new');
+        }
+      }
+    }
+    const cooling = this.level > 0 && this._coolT > COOL_DELAY[this.level];
+    if (cooling !== this._hudCool) {
+      this._hudCool = cooling;
+      this._hud.classList.toggle('cooling', cooling);
+    }
+  }
+}
+
+// ── WIRING (main.js — this file does not touch it) ───────────────────────────────────────────
+//
+// 1. import, with the other game systems at the top of main.js:
+//
+//        import { Crime } from './game/crime.js';
+//
+// 2. CONSTRUCT + BUILD on the loading screen, immediately after `this.deadEye = new DeadEye(this);`
+//    (main.js ~line 210). It MUST come after `await this.combat.populate(clips)` (the pool spawns
+//    through combat.spawn, which needs combat.clips) and after `this.ui = new UI(this)` (the star
+//    HUD attaches to #hud). Both already happen above that line:
+//
+//        this.crime = await new Crime(this).build();   // THE LAW: wanted level + the resident posse
+//
+//    (`build()` is async because it loads six skinned bodies — that is the whole point of doing it
+//     here, on the loading screen, and never again.)
+//
+// 3. TICK it once per frame inside the `if (!paused)` block, next to the other entity systems —
+//    e.g. right before `_fz.ent = performance.now();` (main.js ~line 619), after combat/npcs:
+//
+//        this.crime.update(dt);
+//
+// 4. WIPE it when the run resets — in newGame() (main.js ~441) and wherever player death is
+//    handled (onPlayerDeath):
+//
+//        this.crime?.clear();
+//
+// 5. REPORTING (combat.js's job, not main.js's). combat.js must call, from the friendly-bullet /
+//    melee paths, when a CIVILIAN (townsfolk NPC or coach rider — anything with .civilian) is hit:
+//
+//        this.game.crime?.report('assault', e.position);         // hurt a civilian
+//        this.game.crime?.report('murder', e.position);          // killed a civilian
+//        this.game.crime?.report('coachRobbery', e.position);    // killed a coach driver/mate/fare
+//
+//    and loot.js, when a corpse is robbed:
+//
+//        game.crime?.report('robbery', corpse.position);
+//
+//    Killing a LAWMAN needs NO call — Crime watches its own pool and reports it itself. (If
+//    combat.js reports it anyway, a 0.6s de-dup window in report() swallows the double.)
+//
+// NOTHING ELSE. No enemy.js edit is needed (the law rides as faction 'hostile'); no ui.js edit is
+// needed (the stars build their own DOM); no scene churn ever happens after boot.

package/src/systems/encounters.js

@@ -54,7 +54,7 @@ export class Encounters {
 
     // ── the neutral outfits. The men are real NPCs (civilians: shootable, lootable, witnesses);
     // the one gun in the outfit is a passive Enemy who never starts anything on his own.
-    for (const o of [...OUTFITS]) {
+    for (const o of [...ET.outfits]) {
       const grp = { id: o.id, name: o.name, kind: 'outfit', x: o.x, z: o.z, members: [], guns: [] };
       this.groups.set(o.id, grp);
       await Promise.all(o.men.map(async (m, i) => {