@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/npc-world.md

@@ -0,0 +1,623 @@
+# HELIX Instant — NPC Characters (the recipe)
+
+Follow this when the world needs someone in it who is **not a player**: a shopkeeper behind a counter, a quest
+giver, a guard on a post, a zombie that hunts you around a wall, a companion that follows you. NPCs are a
+**layer on the character system** — the same `humanoid-character` package the player is built on, with one seam
+swapped.
+
+> ## SCAFFOLD THE WORLD FIRST — THIS IS A LAYER, NOT A PROJECT
+>
+> NPCs go **into** a character world. Call `get_started({ kind: "character" })`, run the `helix init` command
+> `scaffold_world` returns, and edit the `src/main.ts` it wrote. Do not hand-write project files from this doc:
+> every snippet below is an addition to that generated boot flow, and every import comes from the **system
+> alias** `@helix/humanoid-character` — never an engine path, never a relative import into a package.
+>
+> **Read the API before you call it.** `get_package_manifest("humanoid-character")` → `capabilities.api` carries
+> the shipped signatures for `NpcScene`, `InteractionSpots`, `NavGrid` and `loadVaultCharacter`, and the
+> installed `.d.ts` carries the full types. Never invent an NPC API — there is no `npc.attack()`, no
+> `npc.patrol()`, no dialogue system. What exists is below.
+
+## 0. What an NPC is here *(humanoid-character ≥ 0.3.13)*
+
+**An NPC is a `Character` whose driver is your behaviour instead of the keyboard.** It is the same chassis the
+player runs on — the same config namespaces (`character.*`, `locomotion.*`), the same locomotion + animation
+graph, the same abilities, the same gestures, the same nameplate — built headless (no camera, no DOM). The one
+difference is the seam that feeds it intent: a player's `Character` reads real keys through
+`LocalInputDriver`, and an NPC's reads an **`AIDriver`** that writes *virtual* input onto the NPC's own private
+router, so every ability resolves that intent exactly as it resolves a player's and nothing downstream can tell
+the difference. You never build that plumbing: **`NpcScene`** owns the model clone, the private router, the
+body, the plate and the teardown, and you author two things — a `behaviour` callback and, when the player
+should be able to talk to it, an interaction spot.
+
+## 1. The five-minute shop NPC *(humanoid-character ≥ 0.3.13)*
+
+The smallest useful NPC: it stands at its counter, turns to watch whoever walks up, and says a line when you
+press interact.
+
+```ts
+import {
+  InteractionSpots, NpcScene, type AIBehaviour,
+} from '@helix/humanoid-character';
+
+// `assets` is what loadCharacterAssets returned (or `mp.assets` in a multiplayer world) — the shared base
+// model + locomotion clips. NpcScene SkeletonUtils-clones that model per NPC, so one load feeds every NPC.
+const npcs = new NpcScene({ scene, assets });
+
+const COUNTER = { x: 7, y: 1, z: 4 };
+const WATCH_RANGE_M = 6;
+
+// The behaviour runs FIRST inside the NPC's own update, once a frame, and steers through the driver's
+// public surface: seek / stop / face / jump / setCrouched, plus the `arrived` and `path` reads.
+const shopBehaviour: AIBehaviour = (npc) => {
+  const self = npc.position;                                    // the body's live feet position — copy it, never hold it
+  const near = Math.hypot(body.position.x - self.x, body.position.z - self.z) <= WATCH_RANGE_M;
+  npc.face(near ? body.position : COUNTER);                     // idle facing: a world point, or a yaw in DEGREES
+};
+
+const shop = await npcs.add({
+  id: 'shopkeeper',
+  at: { x: 7, y: 0, z: 5.2 },
+  facingDeg: 180,
+  body: 'stand',                 // the default — no physics world at all
+  behaviour: shopBehaviour,
+  name: 'Shopkeeper',            // omit for no nameplate; nameColor restyles it
+});
+
+// Proximity interaction: walk into range, an overhead pill offers `{interact} Talk`, the press calls back.
+const spots = new InteractionSpots({ body, input, scene });
+spots.register({                                                // returns its unregister closure — keep it if the NPC can leave
+  id: 'shopkeeper-talk',
+  label: 'Talk',                                                // the verb, sentence case
+  // A LIVE anchor, not a fixed point: the pill has to hang above wherever the NPC currently stands.
+  at: () => { const p = shop.driver.position; return { x: p.x, y: p.y + 2.1, z: p.z }; },
+  onInteract: () => showLine(nextShopLine()),                   // your own HUD + dialogue code, not an SDK API
+});
+
+renderer.setAnimationLoop(() => {
+  const dt = Math.min(clock.getDelta(), 0.1);
+  character.update(dt);   // the PLAYER first — it moves the body every NPC behaviour reads, and its driver
+                          // is what advances this frame's press edges on the shared router
+  npcs.update(dt);        // then every NPC (each one's behaviour + driver run inside its own character.update)
+  spots.update(dt);       // then the spots — the anchors they track just moved, and the interact edge is live
+  renderer.render(scene, camera);
+});
+
+// THE ONE LINE THAT MAKES NPCs MEASURABLE — the scaffold already calls world.ready at the end of boot; add
+// `npcs` to it and `inspect_npc` can measure every NPC in this world (§5). `npcState` is your OWN behaviour
+// machine, published per NPC and carried verbatim into every sample; optional, and everything else works without it.
+world.ready({ scene, body, spawn, npcs, npcState: (id) => brains.get(id) ?? null });
+```
+
+**The loop order is the recipe, not a preference.** `spots.update` reads `wasPressed('interact')` off the
+player's router, and that router advances its edges inside `character.update(dt)` — run the spots first and the
+press either misses by a frame or reads stale. NPCs go between the two so the pill tracks where the NPC is
+*this* frame rather than trailing it.
+
+**Pass `npcs` to `world.ready` the moment you build an `NpcScene`.** Without it the inspect helper installs no
+NPC surface at all, and the only way to find out what a behaviour is doing is to watch it with your eyes — which
+is exactly what §5 is about not doing. `npcState` is where your own state goes: whatever object you return for an
+id (`{ phase: "chase", cooldown: 0.4 }`) rides along on every sample, so a state machine that never leaves its
+wind-up shows up as a flat timeline instead of a mystery. Return `null` for an NPC you have nothing to say about.
+
+**The two body tiers:**
+
+| `body` | what it is | needs | walks? |
+|---|---|---|---|
+| `'stand'` *(default)* | `StandBody` — no physics world at all, so a standing NPC costs no simulation | nothing | **never.** `seek()` writes intent a stationary body ignores; `teleport()` is the only thing that moves it |
+| `'physics'` | its own Rapier world, with the level geometry mirrored in from the scene's `staticsFrom` | `staticsFrom` on the `NpcScene` | yes — and it routes over a `nav` grid when it has one (§3) |
+
+Everything else about the spot is a platform default: distance is **horizontal** (put the anchor at head
+height — about 2.1 m above the feet — for where the pill *draws*; the radius ignores `y`, so height costs you no
+reach), focus is taken at **2.2 m** and released only past **3.0 m** (per-spot hysteresis, so standing on the
+boundary cannot flicker), nearest wins with where the player is *looking* settling a near-tie inside 0.5 m, and
+the pill renders the **real keycap** for `interact` on the player's current device — `E`, an Xbox glyph, a pad
+prompt — because it composes the label through the router's own `format()`. `register()` throws on a duplicate
+id (a silent replace would re-point a verb the player is looking at) and returns its unregister closure.
+`interact` is *ensured* on the router: if the world never registered it, `InteractionSpots` does, because an
+offer nobody can take is worse than no offer.
+
+> **If the world also authors sit/lie spots, yield to them.** Pass `suppressed: () => mp.sitPrompt !== null`
+> (the multiplayer facade's live sit prompt) so an NPC pill and a chair pill never stack. While suppressed no
+> prompt shows and presses are ignored.
+
+## 2. A zombie that hunts *(humanoid-character ≥ 0.3.13)*
+
+A hunting NPC needs the `'physics'` tier, and that tier needs level geometry. Build the scene with
+`staticsFrom` pointed at the **player's own body** — the walls the NPC steers around are then literally the
+walls you walk on, mirrored into its private world:
+
+```ts
+const npcs = new NpcScene({ scene, assets, staticsFrom: body, nav });   // `nav`: §3
+```
+
+Skip `staticsFrom` and `add()` refuses before it builds anything:
+
+```
+NpcScene.add('zombie'): body 'physics' needs level geometry — build the NpcScene with staticsFrom
+```
+
+```ts
+const ATTACK_RANGE_M = 1.6;
+const ATTACK_COOLDOWN_S = 1.2;
+const RESEEK_M = 0.25;
+/** The point the standing seek was last issued for — see rule 2. */
+const sought = { x: Infinity, z: Infinity };
+let cooldown = 0;
+
+const zombieBehaviour: AIBehaviour = (npc, dt) => {
+  cooldown = Math.max(cooldown - dt, 0);
+  const self = npc.position;
+  const planar = Math.hypot(body.position.x - self.x, body.position.z - self.z);
+
+  // RULE 1 — read `arrived` BEFORE re-seeking.
+  if (npc.arrived && planar < ATTACK_RANGE_M && cooldown === 0) {
+    startAttack();                     // your wind-up state machine — see the attack doctrine below
+    cooldown = ATTACK_COOLDOWN_S;
+  }
+
+  // RULE 2 — re-seek only once the target actually MOVED.
+  if (Math.hypot(body.position.x - sought.x, body.position.z - sought.z) > RESEEK_M) {
+    sought.x = body.position.x;
+    sought.z = body.position.z;
+    npc.seek(body.position, { arriveM: 1.2 });     // arriveM = the stop radius (default 0.6); sprint: true runs
+  }
+};
+
+const zombie = await npcs.add({
+  id: 'zombie', at: { x: -15, y: 0.2, z: -15 }, body: 'physics',
+  behaviour: zombieBehaviour, name: 'Zombie', nameColor: '#ff5c5c',
+  config: { locomotion: { runSpeed: 3.2 } },   // per-NPC config, merged OVER the spawn this scene derives from `at`
+});
+```
+
+> **Rule 1 — read `arrived` before you re-seek, in the same behaviour.** `seek()` clears the arrived flag, so a
+> behaviour that seeks first and checks after reads `false` **every single frame** and the attack never fires
+> once. The symptom is an NPC that chases perfectly and is completely harmless.
+
+> **Rule 2 — re-seek only when the target actually moved.** `seek()` also resets the driver's stuck-progress
+> window, so re-issuing it every frame silently disables the sideways commit that rounds a wall: the NPC grinds
+> into the corner forever. (The A* plan itself is *not* the cost — a routed seek keeps its path unless the
+> target drifted more than 1 m, exactly so a behaviour can chase a shuffling player without replanning per
+> frame. The stuck detector is what you break.) A 0.25 m threshold is plenty.
+
+**What the driver does for you, and what it does not.** Built in: whisker obstacle avoidance (three rays from
+0.9 m eye height, 2.5 m lookahead, ±35°, turning harder the closer the hit) and a **stuck commit** — when a
+seek makes less than 0.35 m of progress in 1.5 s the NPC commits sideways for 1.2 s along the freer whisker,
+which is what gets it around an L-shaped wall. Those numbers are the shipped defaults and `npcs.add()` does not
+expose them; a world that must retune them constructs an `AIDriver` itself and hands it over with
+`character.setDriver(...)`. Not built in: attacking, patrolling, fleeing, dialogue, aggro, factions. All of
+that is your `behaviour` over the surface above.
+
+> ## THE ATTACK DOCTRINE — the animation never causes damage
+>
+> A clip is a *picture* of an attack. The behaviour owns the attack: a small state machine of **wind-up →
+> damage window → recovery**, each phase timed off `dt` against numbers you chose to match the clip, with the
+> damage applied on exactly one tick inside the window. Drive the visual with
+> `zombie.character.playAnimation('zombie-swipe')` (a world-authored pose-DSL gesture — construct the scene
+> with `gestures` and read `read_doc({ name: "character-animation" })`), but never hang a hit off the
+> animation's own timing: a clip that fades, blends or gets interrupted takes the hit with it, and two NPCs
+> mid-swipe are two different frames of the same clip.
+>
+> **Solo damage is `character.setHealth(...)` on the PLAYER** — requires `character: { health: { enabled: true,
+> maxHealth: 100 } }` (§8f of the character recipe), which brings `died`/`revived`/`healthChanged` and the
+> death ragdoll with it. **Multiplayer damage is never client-side** — it is a server rule; see §6.
+
+## 3. Pathfinding — `NavGrid` *(humanoid-character ≥ 0.3.13)*
+
+Without a grid a seek steers straight at its target and leans on the whiskers plus the stuck commit. With one,
+the seek is **routed**: A* over a rasterized walkable grid, string-pulled to a short waypoint list, with the
+whiskers still live over the route for whatever the grid cannot know about.
+
+```ts
+// Rasterized off the SAME collider roster staticsFrom mirrors into each NPC's private world — one source of
+// truth for what is walkable, so the planner can never promise a route the capsule cannot take.
+const nav = NavGrid.fromColliders(body.describeColliders());
+const npcs = new NpcScene({ scene, assets, staticsFrom: body, nav });
+```
+
+The scene's `nav` is inherited by **`'physics'` NPCs only** (the only tier that walks). A per-NPC `nav` on
+`add()` wins over it, *including* an explicit `nav: null`, which means "no routing even though the scene has a
+grid".
+
+**v1 is single-plane, and honest about it.** Defaults: `cellM` 0.5, `agentRadiusM` 0.4, `walkableY` 0,
+`floorBandM` 0.5, `stepM` 0.35, `heightM` 1.8. Colliders whose top sits within `floorBandM` of `walkableY`
+are **floor** (and floor classification wins, so a kerb inside the step band stays walkable instead of punching
+a hole in the map); anything overlapping the body band blocks. Only **cuboids** rasterize, and only
+axis-aligned or **yaw**-rotated ones — a tilted cuboid has no planar footprint. Everything else is skipped with
+one warning naming what it dropped:
+
+```
+NavGrid: skipped 2× trimesh, 1× ball — v1 rasterizes yaw-aligned cuboids only, so routes over that geometry degrade to direct steering
+```
+
+**Degradation is silent by design.** A route the grid cannot make (endpoints in different components, a target
+outside the floor bounds, geometry that never rasterized) leaves the plan null and the seek steers direct — no
+throw, no log. So when an NPC beelines into a wall, **check the console for that warn first**; the world is
+usually made of trimesh, or of a second storey the grid cannot represent.
+
+> **THE INFLATION CONSEQUENCE — corridors need more than `2 × agentRadiusM + cellM`.** Every blocker is
+> inflated by `agentRadiusM` plus half a cell's support (0.4 + 0.25 = **0.65 m** per side at defaults) before it
+> is stamped, so no cell centre survives in a gap narrower than **1.3 m** — that doorway rasterizes shut, and
+> the route through it degrades to direct steering. Author doorways and alleys at 1.5 m or wider, or lower
+> `cellM`/`agentRadiusM` deliberately and accept the cost (a finer grid is quadratically more cells;
+> `fromColliders` throws past a 1024 × 1024 budget). Size the geometry with `world_metrics` before you place
+> it — the player's own capsule and corridor numbers are the floor for the NPC's.
+
+Both endpoints of `findPath(from, to)` are **clamped onto the grid** first, so a target standing on a counter
+resolves to the floor beside it and `null` genuinely means "these two ends are disconnected". `clampToWalkable(p)`
+answers the same question for a spawn point before you place an NPC on it, and `npc.path` reads the live plan
+(cell centres, goal included) — read it, never hold it.
+
+## 4. Vault characters as NPC bodies *(humanoid-character ≥ 0.3.13)*
+
+An NPC does not have to wear the platform body. Any Vault **character** whose rig is a helix-humanoid can be
+the model, and the platform's shared locomotion clips drive it — the flow is search → verify the rig → install
+→ load → pass as `model`.
+
+1. **Search with `match: 'narrow'`** — it makes the query a hard FILTER, so an empty result is the honest
+   answer to "does the Vault have a zombie?" instead of the nearest confidently-irrelevant rows:
+   `search_assets({ query: "zombie", kinds: ["character"], match: "narrow", engine: "web" })`.
+2. **Read the row before you install.** `skeleton` says which rig the character carries,
+   `skeletonVerification` says whether the publish gate actually MEASURED that, and
+   `character.boneCount` / `character.skinned` say whether there is a rig at all. The browser runtime plays
+   humanoid rigs — a verified humanoid skeleton is what makes a character web-playable, and this row is the
+   cheapest place to find that out.
+3. **Install it** — `install_asset({ directory, assetId })` downloads the exact immutable version, verifies
+   the checksum and writes provenance. The file lands at `public/assets/vault/<assetId>/<slug>.glb`.
+
+```ts
+import { loadVaultCharacter } from '@helix/humanoid-character';
+
+// Resolve against the document — a root-absolute '/assets/...' 404s in production (character recipe §9).
+const url = new URL('assets/vault/<assetId>/<slug>.glb', document.baseURI).href;
+const { model } = await loadVaultCharacter(url, { renderer, transcoderPath: TRANSCODER_PATH });
+await npcs.add({ id: 'zombie-1', at: SPAWN, body: 'physics', behaviour: zombieBehaviour, model });
+```
+
+**The skeleton gate is the whole point.** Platform clips bind by bone NAME, so a foreign rig assembles
+perfectly and then stands there in its bind pose forever. Instead of that silent T-pose, `loadVaultCharacter`
+**throws** and names the fix — recognize this message and route to `import_character` (the CLI's
+`helix character import`), which conforms the mesh onto the canonical skeleton at its own proportions and
+generates the LOD chain; then install the converted result:
+
+```
+loadVaultCharacter: <url> is not a helix-humanoid rig — missing canonical bones: pelvis, hand_l. Convert it first (helix character import), then install it into the world.
+```
+
+The bones it checks are the core of `helix-humanoid@1`: `root`, `pelvis`, `spine_01`, `head`, `hand_l`,
+`hand_r`, `foot_l`, `foot_r` — few enough that a legitimately decimated LOD export still passes.
+
+A multi-scene GLB assembles as an LOD chain (scene *i* = level *i*, one skeleton, one mixer). A single-scene one
+loads as-is with `lod: null` and one warning — worth fixing for a crowd, harmless for one shopkeeper:
+
+```
+loadVaultCharacter: <url> is a single-scene GLB — no LOD chain, so its full-detail mesh renders at every distance. Re-export with one scene per LOD level.
+```
+
+Two more real details: **one model per NPC** — `NpcScene` clones the shared `assets.model` for every NPC that
+passes no `model`, but a model you *pass* is used as-is, so give each NPC its own load (handing the same object
+to two `add()` calls puts one body in two places). And when the page already built a character loader, pass
+`assetIO` so the whole page shares **one** KTX2 transcoder:
+
+```ts
+const io = createCharacterAssetIO({ renderer, transcoderPath: TRANSCODER_PATH });
+const assets = await loadCharacterAssets(SYSTEM_ASSET_BASE, { io });
+const guard = await loadVaultCharacter(url, { assetIO: io });
+```
+
+## 4a. Armed NPCs — a guard that shoots back *(humanoid-character ≥ 0.3.13 · `gun-control` ≥ 0.3 · asset pack `humanoid-character-assets` ≥ 0.1.6)*
+
+An NPC can carry a **real** gun: the same `gun-control` ability, the same weapon profile, the same FX and hit
+systems the player's gun runs on — the gun contract itself is `read_doc({ name: "shooter-worlds" })`, and this
+section is only what changes when the shooter is an NPC. The engine poses the body, plays the effects and
+resolves the ray. **When it pulls the trigger and what a hit costs are yours**, in the same behaviour loop §2
+put the zombie's attack in.
+
+**Arming happens inside `decorate`, in REPLICA mode, with the `net:*` keys registered up front:**
+
+```ts
+import {
+  AttachmentService, GunFxSystem, GunHitSystem, applyWeaponProfile, createCharacterAssetIO, hitBearingDeg,
+  loadInstalledAbilities, presetForCategory, resolveWeaponProfile, type NpcHandle,
+} from '@helix/humanoid-character';
+
+const GUN_URL = new URL('props/weapons/Pistol/Gaston.glb', document.baseURI).href;   // never root-absolute
+const OWNER = 'guard-brain';                     // blackboard owner tag for the keys this world synthesizes
+const profile = resolveWeaponProfile(GUN_URL);   // null = nothing resolved for that BASENAME (shooter-worlds §3)
+let fx: GunFxSystem;                             // built here, advanced in the frame loop below
+
+const arm = async (npc: NpcHandle): Promise<void> => {
+  await loadInstalledAbilities(modulesBaseUrl, npc.character);  // the ONLY window — see the three rules below
+  npc.character.services.config.set('gun-control.remoteDriven', true);
+  const bb = npc.character.blackboard;
+  for (const key of ['net:gunDrawn', 'net:aiming', 'net:reloading']) bb.register(key, 'boolean', OWNER);
+  bb.register('net:shotSeq', 'number', OWNER);
+  bb.set('net:shotSeq', 0);        // THE TRAP: the first observation only ANCHORS — start it here, count at fire time
+  const attachments = new AttachmentService(npc.character.services.sockets!, {
+    io: createCharacterAssetIO({ renderer }),    // the system's own IO — a bare GLTFLoader drops KTX2/meshopt props
+    gestures: npc.character.gestures,
+  });
+  const held = await attachments.attach(GUN_URL, 'hand_r.grip', { preset: presetForCategory(profile!.category) });
+  applyWeaponProfile(npc.character, profile!);   // cadence, clip, spread, grip family, placement — never hand-authored
+  fx = new GunFxSystem({ scene, camera, soundsBaseUrl, audio, flashPool, shells });   // the world's SHARED pools
+  fx.attachTo(npc.character);
+  fx.setWeapon(GUN_URL, held.object);            // BOTH halves — an FX system without setWeapon is silently inert
+  bb.set('net:gunDrawn', true);                  // on duty: the gun stays out, so engaging only changes the aim
+};
+
+const guard = await npcs.add({
+  id: 'guard', at: POST_A, body: 'physics', name: 'Guard',
+  // Catching here keeps an unarmable guard patrolling; let it throw and add() REJECTS with no NPC at all.
+  decorate: (npc) => arm(npc).catch((error: unknown) => console.warn('guard could not be armed:', error)),
+});
+```
+
+- **`remoteDriven`, never local mode.** The local lane's ADS reaches for the camera rig and a headless NPC has
+  none, so it throws on the first aim. The replica lane drives the identical stance/recoil/reload one-shots off
+  four blackboard keys instead — which is exactly the seam a behaviour can write.
+- **In `decorate`, nothing later.** `decorate` is awaited before the NPC joins the tick, and the first tick
+  starts its `AbilityManager`; a started manager refuses every install, so "right after `add()`" is already too
+  late.
+- **Register the `net:*` keys yourself.** On a player replica a `NetworkDriver` registers and writes them; an
+  NPC has no network lane, so your world **is** the driver. **`net:shotSeq` swallows its first observation on
+  purpose** (a late joiner must not replay a stranger's magazine) — register it at 0 in `decorate` and
+  increment it at fire time, or the first shot is anchored away instead of fired.
+
+**One set of FX pools per WORLD, never per NPC.** `GunAudio`, `MuzzleFlashPool` and `ShellEjector` are built
+once and injected into every `GunFxSystem` (the player's and each armed NPC's); their update is dt-driven, so a
+second system that also advances them decays every flash and shell twice as fast, and `GunAudio` opens an
+AudioContext browsers cap around six. Give the extra systems no-op `update`/`dispose` wrappers around the
+shared three — the same pattern the shooter templates use for replicas.
+
+**The behaviour loop owns the trigger.** `aimAt(point)` is the only driver surface a gun needs: a **sticky** aim
+triad the NPC holds while it keeps walking wherever `seek` sent it, so a guard patrols and tracks you at once
+(precedence `aimAt` > `face` > move heading; `null` clears it). Everything else is a counter in your tick:
+
+```ts
+// The gun's own numbers, read as DEFAULTS — a deliberate guard fires slower than its rpm, and may say so.
+const FIRE_COOLDOWN_S = Math.max(0.02, 60 / profile!.fire.rpm);
+const MAGAZINE = profile!.ammo.clip;
+const RELOAD_S = guard.character.services.config.get<number>('gun-control.reloadDuration');
+let clip = MAGAZINE, fireT = 0, reloadT = 0, shots = 0;
+
+const eye = new THREE.Vector3(), chest = new THREE.Vector3(), dir = new THREE.Vector3();   // scratch, reused
+
+/** Clear line from the eye to the point it wants to shoot — the SAME statics the shot ray resolves against. */
+const losClear = (from: THREE.Vector3, to: THREE.Vector3): boolean => {
+  const d = from.distanceTo(to);
+  return d < 1e-3 || body.castRay(from, dir.copy(to).sub(from).divideScalar(d), d) === null;
+};
+
+/** Runs AFTER npcs.update(dt): the aim, the proxy camera and the ray all read THIS frame's transforms. */
+const guardTick = (dt: number): void => {
+  const bb = guard.character.blackboard;
+  const self = guard.driver.position;
+  eye.set(self.x, self.y + 1.65, self.z);                                        // the NPC's eye
+  chest.set(body.position.x, body.position.y + 1.4, body.position.z);            // the point on you it aims at
+  const engaged = eye.distanceTo(chest) <= ENGAGE_RANGE_M && losClear(eye, chest);   // your range, your LoS policy
+  if (engaged) { guard.driver.stop(); guard.driver.aimAt(chest); }                // re-issued, so it tracks you
+  else { guard.driver.aimAt(null); if (guard.driver.arrived) guard.driver.seek(nextPost(), { arriveM: 0.8 }); }
+  bb.set('net:aiming', engaged);
+
+  reloadT = Math.max(0, reloadT - dt);
+  if (reloadT === 0 && bb.get<boolean>('net:reloading')) { bb.set('net:reloading', false); clip = MAGAZINE; }
+  if (!engaged || reloadT > 0) return;
+  fireT = Math.max(0, fireT - dt);
+  if (fireT > 0) return;
+  if (clip === 0) { bb.set('net:reloading', true); reloadT = RELOAD_S; return; }  // the reload one-shot plays itself
+  clip -= 1;
+  fireT = FIRE_COOLDOWN_S;
+  bb.set('net:shotSeq', (shots += 1));   // MONOTONIC: the ability reacts to the DELTA and re-anchors on anything else
+};
+```
+
+**Who controls how this guard fights? You do — all of it.** The engine owns exactly three things: the **pose**
+(stance, aim, recoil, the reload one-shot), the **FX** (flash, sound, shells, tracer) and the **hit math**
+(spread cone, capsule + head narrow phase, the wall ray). Every knob a player would call behaviour is a number
+in your loop:
+
+| Knob | Where it lives |
+|---|---|
+| **fire cadence, bursts, hesitation** | when your tick increments `net:shotSeq`. `profile.fire.rpm` is a default to read, not a rule |
+| **damage per hit** | whatever `onPlayerHit` subtracts below. The profile's number ×2 on a head is a CONVENTION, not policy |
+| **magazine & reload timing** | your counter and your timer, gated by `net:reloading`; `ammo.clip` / `gun-control.reloadDuration` are defaults |
+| **engage range** | your distance test — there is no aggro system |
+| **line of sight** | your `castRay` policy, including "no LoS check at all" |
+| **which gun** | any prop URL; the profile resolves by BASENAME (`aliasWeaponProfile` first for a hashed CDN URL) |
+| **accuracy** | `config.set('gun-control.spreadScale', …)` on that NPC — the authored dial into its cone |
+
+**Damage back at the player — one `GunHitSystem` per armed NPC.** It traces from a *camera*, and a headless NPC
+has none, so give it a proxy that stands at the eye and looks down the aim:
+
+```ts
+const DAMAGE = profile!.damage.base;                       // a default to READ — what a hit costs is the world's call
+const HEAD_MULTIPLIER = profile!.damage.headMultiplier;    // ×2 on a head is a convention, not platform policy
+const hp = (): number => character.blackboard.get<number>('health');
+const headAt = new THREE.Vector3();                        // scratch for the head read — consumed before the next
+// Never added to the scene — nothing renders through it; it exists to carry an origin and a direction.
+const guardEye = new THREE.PerspectiveCamera();
+
+const gunHit = new GunHitSystem({
+  camera: guardEye,
+  // The PLAYER's RapierBody: the only one carrying the level, so walls block the shot — and it excludes its own
+  // capsule, so the player is hit as a CANDIDATE, never as a wall. A 'stand' NPC's body has no statics at all.
+  body,
+  walkSpeedMps: guard.character.services.config.get<number>('locomotion.walkSpeed'),   // live config, never literals
+  maxSpeedMps: guard.character.services.config.get<number>('locomotion.runSpeed'),
+  muzzle: (out) => fx.muzzleWorld(out),          // arms the near-hit muzzle veto (shooter-worlds §4)
+  players: function* () {                        // the SHOOTER is the NPC, so the player is a legal candidate
+    if (character.blackboard.get<boolean>('dead')) return;
+    yield {
+      id: 'player',
+      position: character.model.position,        // FEET
+      crouched: body.isCrouched,
+      ragdolled: character.ragdoll?.active ?? false,
+      // getWorldPosition through the ancestors — the character tick leaves matrixWorld stale (§4b aims off this).
+      head: () => character.services.sockets?.anchorOf('head')?.getWorldPosition(headAt) ?? null,
+    };
+  },
+  onPlayerHit: ({ claim, part, point }) => {
+    if (!claim) return;                          // exactly ONE claim per trigger pull
+    character.hitReaction.setHint(hitBearingDeg(body.facingYaw, character.model.position, point));   // §4b
+    character.setHealth(hp() - DAMAGE * (part === 'head' ? HEAD_MULTIPLIER : 1));   // YOUR number, not the engine's
+  },
+});
+gunHit.attachTo(guard.character);   // latches `gunFired`, which the replica lane emits per shotSeq delta
+gunHit.setWeapon(GUN_URL);
+```
+
+**The frame order is a contract, exactly as it is for a player's gun** — everything gun resolves after the
+character ticks that moved the bodies:
+
+```ts
+character.update(dt);      // the player
+npcs.update(dt);           // every NPC (behaviours run inside)
+spots.update(dt);
+guardTick(dt);             // the attack machine, on transforms both ticks just settled
+guardEye.position.copy(eye); guardEye.lookAt(chest);   // the proxy rides the aim, so the traced shot IS the aim
+gunHit.update(dt);         // the ray fires against THIS frame's player transform
+fx.update(dt);             // latched shots resolve at THIS frame's muzzle
+```
+
+> **`character.health.enabled` is OFF by default — on the player and on every NPC.** Without
+> `character: { health: { enabled: true, maxHealth: 100 } }` on whoever is being shot, `setHealth` publishes
+> nothing, no `healthChanged` fires and no flinch plays: the guard aims, the muzzle flashes, the brass ejects,
+> and the hit lands on nobody. Turn it on for anything that can be hurt — a shootable NPC needs it too.
+
+**Publish the attack machine's phase through `npcState`** (§1) — `{ phase: engaged ? 'engaging' : 'patrol',
+clip, reloading }` — and every `inspect_npc` sample carries it (§5). That timeline is how you see a guard that
+engages and never fires (a swallowed `shotSeq`) or one that never leaves reload, neither of which a screenshot
+can show.
+
+## 4b. Hit reactions — the flinch layer *(humanoid-character ≥ 0.3.13 · asset pack `humanoid-character-assets` ≥ 0.1.6 — the ten hit takes)*
+
+**Every character already carries it and it is on by default** — the player, a replica, an NPC. Any health
+DECREASE the body survives plays a directional one-shot **additively** over whatever it is already doing
+(walking, aiming, mid-emote), so nothing about the gait or the grip is replaced. There is nothing to register
+and nothing to wire: `setHealth` is the trigger.
+
+- **Aim it with a bearing.** `character.hitReaction.setHint(bearingDeg)` **before** the `setHealth` that fires
+  it (that flinch consumes the hint): 0 = the hit came from ahead, +90 = the victim's right, ±180 = behind.
+  Compute it from the hit point with the exported `hitBearingDeg(facingYaw, victimPosition, from)` — the impact
+  point stands in for the shooter, because it is always on the side the ray came in from. Without a hint the
+  flinch falls through to the front family. **In multiplayer you author no bearing at all**: the platform
+  derives it from the attacker's seat when your damage rule writes the `lastHitBy` playerVar — declare that var
+  and set it in the rule, as the shooter templates already do.
+- **Scripted flinches** ignore health entirely: `character.hitReaction.play({ direction: 'back', intensity:
+  'heavy' })` (or `{ bearingDeg }`) for a shove, a melee that costs no hp, a cutscene beat.
+- **Tune with `character.hitReactions.*`** — `enabled`, `weight` (0-1, how much reaches the body), `blendInS` /
+  `blendOutS`, `cooldownS` (the pellet-storm guard: several damage events in one frame must not re-trigger at
+  frame 0 forever) and the `lightFraction` / `mediumFraction` damage thresholds the auto-trigger buckets on.
+  Read them from `get_package_manifest("humanoid-character")`, never guess.
+- **The coverage is honest: HEAVY is authored on the front only.** Heavy from a side or behind degrades to that
+  direction's medium rather than turning into a front flinch — the direction reads louder than the force. The
+  killing blow never flinches (the death stagger and the ragdoll own that body) and neither does a limp one.
+
+> **The FIRST health change per character is deliberately swallowed.** It is a multiplayer seeding guard — a
+> late joiner arriving at 40 hp must not flinch on frame one — and it applies to a solo world too, so the
+> session's first hit on a given body does not react. A world that cares burns the seed at spawn with a
+> scratch: `setHealth(maxHealth - 1)` (swallowed) then `setHealth(maxHealth)` (an increase never flinches), and
+> every real hit after it reacts.
+
+## 5. Budgets & verification *(humanoid-character ≥ 0.3.13)*
+
+**The budget is 16 live NPCs (`maxNpcs`), and going past it throws:**
+
+```
+NpcScene.add('guard-9'): NPC budget full (maxNpcs = 16) — remove one or raise maxNpcs
+```
+
+That is a refusal, not a silent degrade, because an NPC that never appears is a world-logic bug and you want to
+find it at `add()` rather than in a screenshot. The number is real cost, not ceremony: **each NPC is a full
+skinned character** — its own model clone, anim graph, mixer, router and driver, plus a private Rapier world for
+every `'physics'` one. Raising `maxNpcs` is a decision about your frame budget; a crowd of standing NPCs is far
+cheaper than a pack of hunting ones. Every refusal (duplicate id, full budget, physics without geometry) is
+decided **before the first await**, so a rejected `add()` has built and added nothing:
+
+```
+NpcScene.add: an NPC with id 'zombie' already exists
+```
+
+Housekeeping is symmetric: `npcs.get(id)` / `has` / `list()` / `ids()` / `count` read the pool, `remove(id)`
+tears one down completely (false if the id is unknown), `dispose()` frees all of them — model, body, private
+router, plate — and `unregister()` from `spots.register(...)` retires the pill that followed one.
+
+**Verifying NPCs** *(humanoid-character ≥ 0.3.13; `inspect_npc` and `capture_npc` additionally need the world
+**rebuilt** since §1's `world.ready({ …, npcs, npcState })` line — a bundle built before it exposes no NPC
+surface, and both tools fail naming the exact line and whether a reinstall is needed first)*:
+
+**Measure first, look second — the order is a rule, not a preference.** Every way an NPC goes wrong here is
+*silent*, and none of them is visible in a still frame: the chaser that never attacks (rule 1), the one grinding
+into a corner (rule 2), an NPC on `body: 'stand'` that physically cannot walk, a NavGrid that degraded to direct
+steering without a word (§3). A screenshot shows a character standing in a room in all four cases.
+
+1. **`inspect_npc({ directory: "<world>/dist", seconds: 10, target: [x, y, z] })`** — boots the built world
+   headlessly, watches it run, and reports per NPC: distance actually **walked** vs distance actually **gained**
+   (the progress ratio — 1.00 is a straight line), start/closest/final distance to `target` and how much ground
+   it **closed**, **stuck windows** on the driver's own rule (under 0.35 m in 1.5 s — the same stall its sideways
+   commit fires on), the **`arrived` edges** with timestamps, how much of the run held a planned nav path at all,
+   and the **locomotion + `npcState` timelines**. Pass `npc: "zombie"` to scope it to one.
+2. **Read the three that decide whether the behaviour works.** *Did it close on the target?* — a chase that moves
+   and never closes is rule 1. *Any stuck windows?* — rule 2, or a doorway the grid rasterized shut. *Was it ever
+   on a path?* — `nav path: 0%` while it moves means the grid produced no route and nobody said so.
+3. **`capture_npc({ directory: "<world>/dist", npc: "zombie" })`** — only once the numbers pass. A captioned
+   filmstrip of the running world: each frame carries the sample taken at that same instant, so "T-posing at
+   4 s" is answerable. It answers *presence, body, pose, surroundings* and nothing about distance — and it has
+   no camera control, so the frames are the world's own view, not a shot framed on the NPC.
+4. **`world_metrics({ projectDir })`** — **before** you place the geometry an NPC has to walk through: the step
+   height, slope and corridor clearances it reports for the player are the same envelope the NPC's capsule has,
+   and they are what §3's corridor rule is measured against.
+
+A failed capture or inspection is still diagnostic: page errors come back in the timeout message, which is where
+a `NpcScene.add` throw will be.
+
+## 6. Multiplayer — where NpcScene stops *(humanoid-character ≥ 0.3.13)*
+
+**`NpcScene` NPCs are client-local.** Nothing about them crosses the wire: each client that loads the world
+builds its own copy and runs its own behaviour. For a **stand** NPC that is exactly right — it never moves, so
+every client agrees about it for free, and a shopkeeper with a Talk spot needs no server involvement at all.
+For anything that *moves*, it is exactly wrong: four clients each run their own zombie chasing their own
+player, and no two players see the same fight. The multiplayer answer is to move the brain to the room and keep
+the humanoid as pure **rendering** — the enemy becomes a declared entity, and
+`humanoidEntities({ scene, assets: mp.assets })` is the `mp.entities` build fn that renders each one as a full
+headless character, deriving its locomotion animation from the replicated motion. Damage follows the same
+split: the entity carries a declared **zone** and a `zoneEnter` rule subtracts health server-side — the client
+never writes health, and the attack animation still causes nothing.
+
+```
+read_template({ name: "npc-wave" })
+```
+
+## The rules that matter (NPCs)
+
+- **Hand the pool to `world.ready`, then MEASURE before you look.** `world.ready({ scene, body, spawn, npcs,
+  npcState })` is what makes `inspect_npc` possible at all; every NPC failure mode on this system is silent, so
+  numbers first and `capture_npc` last (§5).
+- **An NPC is a Character whose driver is your behaviour.** Same chassis, same config, same abilities — do not
+  hand-roll a "monster" out of meshes and lerps, and do not invent an NPC API. Read `capabilities.api` from
+  `get_package_manifest("humanoid-character")`.
+- **Read `arrived` before you re-seek, and re-seek only when the target moved.** The first mistake makes a
+  harmless chaser; the second makes one that grinds into every wall. Both are silent.
+- **The animation never causes damage.** The behaviour owns wind-up → damage window → recovery; solo damage is
+  `setHealth`, multiplayer damage is a server rule.
+- **An armed NPC is `gun-control` in REPLICA mode, armed inside `decorate`.** `remoteDriven` (local mode's ADS
+  wants a camera an NPC has not got) plus the `net:*` keys you register yourself — `net:shotSeq` at 0, because
+  its first observation only anchors. Cadence, damage, magazine, range, LoS and accuracy are all your loop's;
+  the engine owns the pose, the FX and the hit math (§4a).
+- **Flinches are automatic on any survived health drop, on every character.** `setHint(bearingDeg)` before
+  `setHealth` aims one; the first health change per body is swallowed by design, and `character.health.enabled`
+  is off until you turn it on (§4b).
+- **`body: 'stand'` never walks** (a seek on it is inert; `teleport` is the only move) and **`body: 'physics'`
+  needs `staticsFrom`** — the scene refuses without it.
+- **One source of truth for the level.** Build the nav grid from the same `describeColliders()` roster
+  `staticsFrom` mirrors, or the planner will route through a wall the capsule cannot pass.
+- **NavGrid v1 is single-plane, yaw-aligned cuboids only, and degrades to direct steering in silence.** Check
+  the skipped-geometry warn before theorising, and keep corridors wider than `2 × agentRadiusM + cellM` (1.3 m
+  at defaults).
+- **Verify a Vault rig before you install it** (`skeleton` / `skeletonVerification` on the search row) and
+  recognize the convert-first throw: `import_character` first, install second.
+- **16 NPCs is the default budget and add() throws past it.** Each one is a full skinned character; a raised
+  cap is a frame-budget decision.
+- **Loop order: player → NPCs → spots.** The press edge and the pill anchors both depend on it.
+- **NpcScene NPCs never replicate.** Anything that moves and must be shared belongs to the room —
+  `read_template({ name: "npc-wave" })`.