@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/docs/shooter-worlds.md

@@ -0,0 +1,537 @@
+# Shooter worlds — guns, damage, death & ragdoll (the combat recipe)
+
+Read this when a world needs GUNS: aiming, firing, ammo, hit detection, damage, death and respawn — first
+person or third person, single-player or multiplayer. The platform ships the whole gun stack: the
+**`gun-control`** ability (stance, ADS, fire modes, ammo, reload, recoil), a **weapon-profile** data layer
+(a gun is DATA, not code), world-side **FX/hit systems** (muzzle flash, tracers, shells, positional audio, a
+spread-reflecting crosshair), a **health/death chassis** driven by server rules, and a physics **ragdoll**
+that finishes every death. You write no netcode and no server code — gun state and damage ride the same
+declarative room as everything else.
+
+**Prerequisites:** installed `humanoid-character` `^0.3` and the `gun-control` ability `^0.3` (run
+`check_for_updates` + `get_package_manifest("gun-control")` first — the configSchema is the authoritative
+knob list). The room half needs a multiplayer world (`get_started({ kind: "multiplayer" })`); the worked
+room config is the **`shooter-range`** template (`read_template({ name: "shooter-range" })`).
+
+## 1. Install gun-control — the one bundle-layout rule
+
+Pin the ability in `helix.json` next to the system pin, then `install_world_packages`:
+
+```json
+"systems": { "humanoid-character": "^0.3" },
+"abilities": { "gun-control": "^0.3" }
+```
+
+Take the gun-control version `get_package_manifest({ slug: "gun-control" })` reports for the system line you
+pinned — an ability declares the system range it was built against and refuses to load at runtime outside it.
+
+Load it in world code BEFORE the first `mp.update()` — the ability manager starts on the character's first
+update and refuses bundles after that:
+
+```ts
+import { loadInstalledAbilities } from '@helix/humanoid-character';
+const modulesBaseUrl = new URL('helix_modules/', document.baseURI).href;
+await loadInstalledAbilities(modulesBaseUrl, mp.local);
+```
+
+> **The bundle must be served where vite TRANSFORMS it — the world root, not `public/`.** gun-control's
+> entry imports bare `three`; static serving from `public/` cannot resolve that import and the ability
+> silently never loads (holstered forever, no error). If your `helix_modules/` landed under `public/`, move
+> it to the project root (keep `installed.json` beside it) so the dev server and build both transform the
+> entry. Replicas load the SAME bundle (§7), so this rule decides whether other players see gun stances
+> at all.
+
+## 2. The gun-control contract — config, blackboard, events, actions
+
+**Config** (29 keys — read them from `get_package_manifest("gun-control")`, never guess): fire
+(`fireCooldown`, `fireMode`, `magazineSize`, `reserveAmmo`, `reloadDuration`), ADS (`adsFovScale`,
+`adsShoulder`, `aimYawDeadzoneDeg`, …), shooter movement rules (`firingSpeedTier`, `firingSpeedTailS`,
+`adsSpeedTier`, `sprintToFireDelayS` — creator-tunable speed policy while fighting), baked camera recoil
+(`recoilPitchDeg`, `recoilPatternSeed`, …), `spreadScale` (a world-global accuracy dial), `grip`
+(`one-handed`/`two-handed` stance family), and `remoteDriven` (replica mode — §7; never set it on the local
+player). Set initial values via `Character.create` config or live via `config.set('gun-control.key', v)`.
+
+**Blackboard it publishes** (read with `character.blackboard.get`, guarded — the keys exist only once the
+bundle loaded):
+
+| Key | Type | Meaning |
+|---|---|---|
+| `gunDrawn` | boolean | gun up (drawn) vs holstered |
+| `aiming` | boolean | ADS intent (secondary held) |
+| `aimFraction` | number | the eased 0..1 ADS blend — gate UI on it, not on `aiming` |
+| `firing` | boolean | ONE-TICK pulse per shot — subscribe to the `gunFired` event instead of polling this |
+| `weaponEngaged` | boolean | actively fighting (ADS or recent fire) — drives stance/facing |
+| `reloading` | boolean | the reload window |
+| `oneHanded` | boolean | the active stance family |
+| `ammoInClip` / `ammoReserve` | number | **−1 = not tracked** (ammo off or holstered); reserve −1 with ammo ON = infinite |
+| `spreadScale` | number | the live accuracy dial (config × any runtime writes) |
+
+**Events on `character.events`:** `gunFired` (per shot — payload-less BY DESIGN; resolve muzzle/aim AFTER
+`mp.update()`, §4), `gunDryFired`, `gunReloadStarted`.
+
+**Actions:** it binds the STANDARD ids `primary` (fire), `secondary` (ADS), `reload` — so pads and touch
+work with zero effort — plus its own `gun-control.equip` draw/holster toggle, which **defaults to Digit1 and
+collides with the equip tracker's `ability1`**. Any world using equip slots must remap it in the chassis
+`bindings` config (the range uses `KeyH`).
+
+**There is no `drawn` config.** Draw/holster is action-owned state. To force the shooter state from world
+code (equip a gun already drawn, re-draw after respawn), tap the action through the input router — one edge,
+no key involved:
+
+```ts
+const drawSoon = () => {
+  if (bb('gunDrawn') === true) return;
+  mp.local.services.input.setVirtualButton('gun-control.equip', true);
+  mp.local.services.input.setVirtualButton('gun-control.equip', null);
+};
+```
+
+## 3. A gun is DATA — weapon profiles
+
+A weapon profile carries everything per-gun: cadence + fire mode, clip/reserve, the damage block, the spread
+model, per-gun placement/sway patches, grip seating, FX points and sounds. The engine resolves profiles **by
+asset URL basename** and applies them at equip:
+
+```ts
+import { registerWeaponProfile, aliasWeaponProfile, resolveWeaponProfile, applyWeaponProfile, listWeaponProfiles } from '@helix/humanoid-character';
+
+registerWeaponProfile(myProfile);            // world-supplied gun (or override a stock one by name)
+const p = resolveWeaponProfile(gunUrl);      // by URL or bare name
+if (p) applyWeaponProfile(mp.local, p);      // writes gun-control config + the ADS/sway placement patches
+listWeaponProfiles();                        // the whole arsenal (a gun wall, a loadout menu)
+```
+
+- **`aliasWeaponProfile(source, weapon)` is MANDATORY for opaque URLs.** Every resolve site keys off the
+  attachment URL's basename; a CDN URL whose basename is a hash resolves to NOTHING — the gun renders but
+  fires silently with default spread and no per-gun feel. Published gun definitions (§8) alias for you;
+  hand-registered CDN guns must call it before `attach()`.
+- **`category` does most of the work.** Naming `Rifle` / `Pistol` / `SMG` / `Shotgun` / `Sniper` / `LMG`
+  inherits the calibrated spread model, reload foley, grip preset, one/two-handed default and shell class.
+  A conventionally-authored mesh + a category is a playable gun; per-gun `hold`/`ads`/`sway` blocks are
+  polish, not function. `Launcher` and `Grenade` are the explosive pair: they carry a `fire.kind`
+  (`projectile` / `thrown`) that decides which system flies the round, and their blast is world-authored (§9).
+- **Re-apply on every swap.** `applyWeaponProfile` writes the FULL effective set (a gun silent on a field
+  gets the baseline, never the previous gun's value) and resets the placement caches so locators re-resolve
+  against the prop just attached. Call it after each `attach`, not once at boot.
+- The profile's `damage` block is CLIENT-REFERENCE ONLY on the client (`pellets`, `maxRangeM`,
+  `sweepRadiusM` feed the hit ray). Actual damage is server-side — the room reads the PUBLISHED
+  definition's damage block through `weaponItems` + the `weaponDamage` op (see the `shooter-range`
+  template). A client can never name its own damage number.
+
+**Sounds ride one of two lanes — and `@helix/humanoid-character` ships NO audio bytes, ever.** A profile
+carries relative path *strings*; the lane decides where those bytes must actually exist:
+
+| | Stock lane | Items lane |
+|---|---|---|
+| Source of truth | the stock profile tables — refs like `Pistol/Fierro/A_Fierro_Shot_001.wav` | the published definition, audio as vault refs |
+| Where the bytes live | YOUR world's `public/fx/sounds/`, uploaded with the bundle | the Vault CDN; nothing bundled per world |
+| Resolved by | `GunFxSystem`, against the `soundsBaseUrl` you pass it (§4) | `installWeaponItem`, which rewrites the refs to CDN URLs (§8) |
+| Cost | the whole pack ships with the world, even for one gun in use | per definition pinned; audio deduped across guns |
+
+> **NEVER hand-author a `WeaponProfile` object.** Use `resolveWeaponProfile('<Name>')` for a stock gun (merge
+> your own damage/spread ON TOP of what it returns) or `installWeaponItem` for a published definition. Mixing
+> lanes — a Vault prop mesh plus a typed-out profile — loses the audio SILENTLY: `GunFxSystem` plays exactly
+> what the profile lists, an empty `sounds.shots` array plays nothing, and nothing warns. A LIVE world shipped
+> precisely that (`sounds: { shots: [] }`) while every WAV that gun needed sat reachable in the same build.
+
+## 4. The world-side systems — FX, hit chain, crosshair
+
+Seven composable systems ship with the engine. A minimal shooter wires four (`GunFxSystem`, `GunHitSystem`,
+the crosshair, `TracerPool`); the rest are injectable shared pools for multi-character worlds:
+
+```ts
+import { GunAudio, GunFxSystem, GunHitSystem, MuzzleFlashPool, ShellEjector, TracerPool, createSpreadCrosshair } from '@helix/humanoid-character';
+
+const gunFx = new GunFxSystem({ scene, camera, soundsBaseUrl });
+gunFx.attachTo(mp.local);
+const gunHit = new GunHitSystem({
+  camera,
+  body,                                                       // your RapierBody — static geometry for the ray
+  // READ these from live config, never literals — hardcoding desyncs the moment locomotion is retuned:
+  walkSpeedMps: mp.local.services.config.get('locomotion.walkSpeed'),
+  maxSpeedMps: mp.local.services.config.get('locomotion.runSpeed'),
+  muzzle: (out) => gunFx.muzzleWorld(out),
+  players: function* () { /* yield { id, position, crouched, ragdolled, head } per replica — see below */ },
+  onPlayerHit: ({ id, point, claim, part }) => { if (claim) mp.room?.sendAction('claimHit', { target: id, bodyPart: part }); },
+  onWorldHit: ({ id, point, claim }) => { /* impact FX; claim → dmg?.hit(id, point) */ },
+  onMiss: ({ end }) => { /* tracer to end */ },
+});
+gunHit.attachTo(mp.local);
+const tracers = new TracerPool({ scene });
+const crosshair = createSpreadCrosshair({
+  spreadDeg: () => gunHit.spreadDeg,
+  fovYDeg: () => camera.fov,
+  visible: () => bb('gunDrawn') === true,
+});
+```
+
+**The candidate shape decides whether cover works.** Each `players` entry is
+`{ id, position, crouched?, ragdolled?, head? }`. `position` is the FEET. `crouched` shrinks the hit
+capsule (1.8 → 1.2 m by default) so a player ducked behind cover is actually safe; `ragdolled` lays it
+down low — feed the WIRE flag (`mp.room.player(id)`'s `ragdolled`), not the replica's own rig state, since
+the sender's corpse-follow is what put the replicated position at the pelvis. `head: () => Vector3 | null`
+is a live head-socket read (`services.sockets.anchorOf('head').getWorldPosition(...)` — recompute through
+ancestors, the character tick leaves `matrixWorld` stale) that arms the headshot sphere; `onPlayerHit`
+then reports `part: 'head' | 'body'`. Omit the flags and every target tests as a standing capsule — the
+"crouched behind the crate but still dying" bug. Send the part on as the `bodyPart` ENUM arg, never a
+number: the ROOM owns every multiplier (§ damage ops below).
+
+**The same generator is how an NPC shoots BACK** — an armed NPC runs its own `GunHitSystem` whose one
+candidate is the player, traced from a proxy camera standing at the NPC's eye:
+`read_doc({ name: "npc-world" })` §4a.
+
+All of these systems ride `mp.local` and survive a mid-room avatar swap — never re-attach or rebuild them
+on `Helix.avatar` events (see `character-world.md`, "Mid-room avatar swaps").
+
+**The frame-order contract** — `gunFired` latches mid-ability-tick against LAST frame's matrices, so
+everything gun resolves AFTER the character tick:
+
+```ts
+mp.update(dt);        // characters tick — shots latch
+gunFx.update(dt);     // latched shots resolve against THIS frame's muzzle
+gunHit.update(dt);    // the shot ray fires against current replica transforms
+tracers.update(dt);
+crosshair.update(dt); // the arms describe THIS frame's cone
+```
+
+**On weapon change call `setWeapon` on BOTH** (`gunFx.setWeapon(url, propObject)`,
+`gunHit.setWeapon(url)`) — same profile, different consumers (FX points/sounds vs spread/range).
+
+**Shell casings come from the weapon itself.** Every official-arsenal weapon prop embeds its ejected casing
+as a `Shell` node; `setWeapon` finds it, hides it on the held gun, and ejects copies of it — no
+configuration, this works in any world. `shellsBaseUrl` (serving `SM_<class>shell.glb` per shell class) is
+the FALLBACK lane for props without the node; with neither, shell ejection is silently absent while every
+other effect still fires — so a gun with flash and sound but no brass means the prop predates embedded
+shells and the world serves no fallback. A custom weapon opts in by authoring a mesh-less node named `Shell`
+(exact name — not `ShellChamber`) at ZERO scale, with the casing mesh at real size in a child node, seated at
+the eject port. Zero scale keeps the casing invisible on display/rack props (only the held gun runs the FX
+resolve); the engine re-arms the ejected template to unit scale, and the profile's `fx.shellEjectM` still
+overrides the node's position when authored.
+
+**The one-claim rule.** A trigger pull may be several rays (a shotgun cartridge is 9 pellets — FX fire per
+pellet) but flags **exactly one** `claim`. Send exactly one declared action per claim.
+**The room strikes senders that exceed the declared action rate — claiming per pellet gets the player
+kicked.** The predicted hitmarker (`crosshair.hit('hit')`) may over-report (the server can still refuse);
+treat the server broadcast (`down` etc.) as the authoritative kill marker (`crosshair.hit('lethal')`).
+
+**Destructible world objects:** register them with `const dmg = mp.damageables({ action: 'claimTargetHit' })`
+— `dmg.register(id, { object3d, onHit, onDestroyed })`, and `dmg.hit(id, point)` sends the one claim.
+Server-owned targets come through `mp.entities()` with their hp in entity vars; the `shooter-range` template
+shows both plus the respawn rules.
+
+## 5. Health, death & respawn — the room owns the number
+
+Enable the chassis mirror and declare the var; the facade wires them together on the local player AND every
+replica:
+
+```ts
+// world code (Character config):
+character: { health: { enabled: true } }
+```
+
+```json
+// multiplayer.json: the room OWNS health — rules mutate it, clients only read
+"state": { "playerVars": { "health": { "type": "number", "default": 100 } } }
+```
+
+The chassis then gives you: blackboard `health` / `dead` / `deathDir`, events `healthChanged{value,previous}`,
+`died`, `revived`, `respawned`, and `character.setHealth(v)` for single-player worlds (in multiplayer never
+write health client-side — send claims, let rules subtract). Death gates input, plays the directional stagger
+and hands the body to the ragdoll (§6); the respawn rule's server move lands through the reconciler.
+The full claim → damage → death → respawn rule anatomy lives in the `shooter-range` template.
+
+## 6. Ragdoll — death physics AND a world mechanic
+
+Every character carries a client-side physics ragdoll (Rapier), **on by default in any world with health**:
+at the death instant physics takes the body and the stagger cross-fades into the fall — no config needed.
+Tune or disable via the chassis block:
+
+```ts
+character: { ragdoll: { enabled: true, blendSeconds: 0.35, launchSpeed: 2.5, deathCamera: 'third-person' } }
+```
+
+`deathCamera: 'third-person'` pulls a first-person victim out to watch their own body fall (`'none'` opts
+out). The kill shove direction comes from the attacker automatically in multiplayer.
+
+**Ragdoll is also a WORLD MECHANIC**, not just death:
+
+```ts
+mp.local.ragdoll.enter({ launch: { x: 1, z: 0 }, speedMps: 4 });  // go limp (knockout, launch pad, comedy)
+mp.local.ragdoll.exit();                                          // get back up (instant)
+mp.local.ragdoll.active                                           // is physics holding the body?
+```
+
+`enter()` refuses while dead (death owns that body); `exit()` no-ops while dead (revive restores). While
+limp, locomotion input is gated — the player cannot walk the capsule away. The state **replicates
+automatically**: other players see the body go limp, late joiners see an already-limp player, and any world
+can READ it — `room.state.players[id].ragdolled` — to build mechanics on top (a medic reviving downed
+players, a "wake up" minigame).
+
+**Never wrap a ragdoll/knockout in an input-context push** (`input.pushContext(...)`). Suspending the
+`look` action deliberately releases pointer lock — that is the menu rule, and re-acquiring needs a real
+user click, so the victim's cursor pops out and they must click the world to keep playing. Movement is
+already gated while `ragdolled`; if the camera must freeze too, set
+`config.set('character.camera.allowRotate', false)` for the duration and restore it on exit — that never
+touches the lock (only toggle it while the lock is held: while false, click-to-relock refuses).
+
+## 7. Multiplayer — what replicates, and the replica recipe
+
+Gun state rides the normal state upload — you send nothing by hand. Replicated per player and readable by
+any world: `gunDrawn`, `aiming`, `reloading` (booleans), `shotSeq` (a monotonic shot counter), `ragdolled`.
+**`shotSeq` semantics:** state is coalesced at 10/20 Hz, so react to the DELTA (fire `min(delta, cap)` FX),
+never assume +1, and re-anchor when the delta is non-positive (a reconnect restarts it).
+
+For other players to show gun STANCES (not just the prop), each replica runs the SAME gun-control bundle in
+`remoteDriven` mode — the wire drives its stance instead of local input. The recipe, inside
+`replica.decorate` — keep `player` in a per-replica record, the weapon poll below needs it:
+
+```ts
+const replicaFx = new Map();  // id → { character, player, fx, url, prop }
+
+decorate: (character, player, id) => {
+  character.setEnabled(false);                       // freeze until the bundle registers
+  const fx = new GunFxSystem({ scene, camera, soundsBaseUrl, audio: sharedAudio, flashPool: sharedFlash, shells: sharedShells });
+  fx.attachTo(character);
+  const entry = { character, player, fx, url: null, prop: null };
+  replicaFx.set(id, entry);
+  void loadInstalledAbilities(modulesBaseUrl, character)
+    .then(() => character.services.config.set('gun-control.remoteDriven', true))
+    .finally(() => character.setEnabled(true));      // stance converges a few frames late, by design
+  return { dispose: () => { fx.dispose(); if (replicaFx.get(id) === entry) replicaFx.delete(id); } };
+}
+```
+
+**The recipe above is HALF of replica guns — the weapon must also be SET, every frame.** A `GunFxSystem`
+that never got `setWeapon` is silently inert (no muzzle flash, no shot sound, no shells — `shotSeq` still
+drives the recoil animation, which makes the omission easy to miss), and a replica whose profile was never
+applied keeps `gun-control.grip` at the `two-handed` schema default — a pistol held like a rifle. The wire
+URL arrives with the attachment set but the prop GLB loads asynchronously, so poll the PAIR each frame
+(after `mp.update`) and re-resolve on either edge:
+
+```ts
+const gripAsset = (player) => {               // player.attachments is an Iterable, not an array
+  for (const a of player?.attachments ?? []) if (a.socket === 'hand_r.grip') return a.asset;
+  return null;
+};
+
+for (const r of replicaFx.values()) {
+  const url = gripAsset(r.player);
+  const prop = r.character.services.sockets?.anchorOf('hand_r.grip')?.children[0] ?? null;
+  if (url !== r.url || prop !== r.prop) {
+    r.url = url; r.prop = prop;
+    const ready = url !== null && prop !== null;
+    const profile = url !== null ? resolveWeaponProfile(url) : null;
+    r.fx.setWeapon(ready ? url : null, ready ? prop : null);      // muzzle point, shot sounds, shell class
+    if (profile !== null) {
+      try { applyWeaponProfile(r.character, profile); }           // stance family (one-handed!), placement, sway
+      catch (err) { console.warn('replica profile failed:', err); } // untrusted item data — config.set throws
+    }
+  }
+  r.fx.update(dt);
+}
+```
+
+The shared pools (`GunAudio`, `MuzzleFlashPool`, `ShellEjector`) are constructed ONCE for the world and
+injected into every `GunFxSystem` via the `audio`/`flashPool`/`shells` options — `GunAudio` lazily opens an
+AudioContext (browsers cap those around six, so per-replica pools break at seven players), and only the
+local system advances them (their update is dt-driven; ticking them per character decays FX N× too fast).
+The held gun itself replicates through the attachments system (§ below).
+
+## 8. Where guns come from — three lanes
+
+1. **Published gun definitions (the platform lane).** A gun published as an `interactive_item` Vault asset
+   carries its mesh, sounds and full profile. **Prefer OFFICIAL definitions**:
+   `search_assets({ kinds: ["interactive_item"], official: true })` first — that tier is platform-vouched
+   (bench-calibrated profiles, convention-correct meshes and locators, mono sounds) — and widen to community
+   definitions only when the official set has no fit; a community gun deserves a placement pass on the range
+   before shipping (`item-def inspect` shows the `OFFICIAL` badge). Consume:
+
+   ```ts
+   import { installWeaponItem } from '@helix/humanoid-character';
+   const { propUrl, preset } = installWeaponItem(descriptor, assetUrls); // validates, registers, ALIASES the URL
+   await mp.attach(propUrl, 'hand_r.grip', { preset });
+   ```
+
+   `installWeaponItem` must run BEFORE `attach()` (grip seating resolves at attach time). It refuses the
+   config keys a definition may not set (`remoteDriven`, `spreadScale`) and degrades a definition with no
+   gun payload to a cosmetic held item. Existing published definitions remain consumable and inspectable;
+   the retired `item-def publish` route must not be used to upload bytes or mint a definition. New content
+   follows the sealed Continuum Package workflow in `read_doc({name: "continuum"})`; its typed Item projection
+   command is upcoming and is not yet available through this MCP. Updating an existing definition likewise
+   requires an approved Package/version workflow, not a direct Vault version upload.
+   `check_for_updates({ projectDir })` audits a world's `weaponItems` pins against the vault and names
+   any that have fallen behind (re-pin steps: `read_doc({ name: "upgrades" })`).
+2. **World-supplied profiles (the self-contained lane).** Bundle a GLB in `public/props/`, register a
+   profile whose `weapon` matches the basename, attach with an ABSOLUTE URL. No platform dependency.
+3. **The stock arsenal** exists for platform test worlds; treat it as reference data, not a dependency.
+
+**Mesh convention** (all lanes): grip point at the ORIGIN, +y up, **+z out the barrel**, meters. Locators
+(`Muzzle`, `IronSight`, `Left_hand`) are optional — every one has a numeric profile fallback
+(`fx.muzzlePointM`, `ads.aimPointM`/`sightDistM`, `ads.foregripPointM`). Sounds should be MONO
+(positional audio degrades on stereo).
+
+## 9. Explosive weapons — the item carries the WEAPON, the world carries the GAME
+
+A rocket launcher and a grenade are ORDINARY gun definitions: same `interactive_item` descriptor and
+`--category Launcher` or `--category Grenade`. New products follow the sealed Continuum Package workflow
+described in §8; do not use the retired Item-first `item-def publish` route.
+What a definition can carry stops at the weapon — the blast is GAME logic and no item carries game logic, so
+budget for both halves. Reference implementation: the engine's **`multiplayer-shooter-range`** world
+(`src/main.ts` + `public/multiplayer.json`); every snippet below is lifted from it.
+
+| The ITEM carries (published, immutable) | The WORLD carries (yours to author) |
+|---|---|
+| the prop mesh + grip preset, ALIASED to the profile at install | ~6 DSL rules: the claim gate + AoE fanout, the throw spawn, the fuse, the refill |
+| `fire.kind: "projectile"` + the `projectile` block (speed, gravity, `blastRadiusM`, range) | `entities.grenade` — the thrown body's physics + authority |
+| `fire.kind: "thrown"` + the `thrown` block (`releaseS`, `speedMps`, `upBias`) | the `grenades` playerVar (the pouch the ROOM owns) |
+| the `damage` block (`base`, `pellets`) — the number the room resolves | the explosion FX pool + its TEXTURES, and the knockback/trauma feel |
+| `sounds.shots`, `sounds.dry`, **`sounds.explosion`** (the detonation takes) | the client wiring: `ProjectileSystem`, `ThrowableSystem`, the claim |
+
+**The room half.** The launcher's blast is claimed by the shooter (one claim per detonation, §4); the
+grenade's is the room's own, because nothing client-side simulates a thrown grenade to completion:
+
+```json
+{ "when": { "on": "action", "name": "claimExplosion" },
+  "if": { "op": "and", "of": [
+    { "op": "<", "a": { "op": "distance", "a": { "var": "self.position" }, "b": { "var": "action.args.at" } }, "b": 160 },
+    { "op": "==", "a": { "op": "timerRemaining", "timer": "explodeCooldown", "key": "self" }, "b": 0 } ] },
+  "then": [
+    { "do": "startTimer", "timer": "explodeCooldown", "seconds": 0.5, "key": "self" },
+    { "do": "broadcast", "event": "exploded", "to": "all", "payload": { "at": { "var": "action.args.at" }, "by": "self" } },
+    { "do": "forEachPlayer", "as": "p",
+      "where": { "op": "<", "a": { "op": "distance", "a": { "var": "action.args.at" }, "b": { "ref": "p", "var": "position" } }, "b": 6 },
+      "then": [
+        { "do": "setRef", "target": { "ref": "p", "var": "lastHitBy" }, "to": "self" },
+        { "do": "add", "target": { "ref": "p", "var": "health" },
+          "by": { "op": "*",
+                  "a": { "op": "*", "a": -1, "b": { "op": "weaponDamage", "of": "self", "default": 100 } },
+                  "b": { "op": "-", "a": 1, "b": { "op": "/",
+                         "a": { "op": "distance", "a": { "var": "action.args.at" }, "b": { "ref": "p", "var": "position" } },
+                         "b": 6 } } } } ] } ] }
+```
+
+The distance gate is a SANITY gate (a claim from across the map is a lie), the cooldown is the rate fence, and
+the `forEachPlayer` fanout is where the falloff shape lives. The other five rules, compactly:
+
+- **`throwGrenade`** (action, args `origin` + `vel`) — gate on `self.grenades > 0`, a sanity distance from the
+  thrower to `origin`, and a throw cooldown; then `add self.grenades by -1` and
+  `{ "do": "spawnEntity", "kind": "grenade", "at": …, "vars": { "vel0": { "var": "action.args.vel" } } }`.
+- **`entitySpawn` / kind `grenade`** → `startTimer` the fuse. The timer is ENTITY-keyed:
+  `"timers": { "grenadeFuse": { "keyed": "entity:grenade" } }`, `"key": "self"` — one live fuse per grenade,
+  not one per player.
+- **`timerElapsed` / `grenadeFuse`** → `destroyEntity self`. Detonation IS destruction.
+- **`entityDestroy` / kind `grenade`** → `broadcast grenadeExploded` with `at: { "var": "self.position" }` and
+  `by: { "op": "controllerOf", "entity": "self" }` (the thrower, for kill credit), then the same
+  `forEachPlayer` fanout keyed off `self.position`.
+- **`refillGrenades`** (action, cooldown-gated) → `set self.grenades to 3`; the respawn rule sets it too, or
+  a player comes back empty.
+
+The thrown body is an owner-authority physics entity — the thrower's client simulates it and uploads, everyone
+else renders that stream:
+
+```json
+"entities": { "grenade": {
+  "authority": "owner", "maxSpeed": 30, "transferPolicy": "fixed", "ownerLifecycle": "despawnWithOwner",
+  "vars": { "vel0": { "type": "vec3", "default": [0, 0, 0] } },
+  "physics": { "bodyType": "dynamic", "shape": { "type": "capsule", "halfHeight": 0.025, "radius": 0.035 },
+               "mass": 0.4, "restitution": 0.3, "friction": 0.5, "linearDamping": 0.2, "angularDamping": 2.5 } } },
+"state": { "playerVars": { "grenades": { "type": "number", "default": 3 } } }
+```
+
+**The client half.** `installWeaponItem` returns the definition's `kind`, and that is the routing switch — a
+thrown definition is NEVER rack-equipped:
+
+```ts
+const slot = installWeaponItem(descriptor, assetUrls);   // { propUrl, profile, preset, kind, category, warnings }
+if (slot.kind === 'thrown') throwables.setGrenade(slot.profile);  // the pouch: never equipped, never applied as a gun
+else arsenal.push(slot);                                          // hitscan AND projectile guns rack normally
+```
+
+The throw itself is gun-control's: action **`gun-control.throw`** (default `KeyG`) plays the overarm toss over
+whatever gun is held, and config **`gun-control.throwEnabled`** is the world mirroring its own count in — while
+false the press emits `throwDenied` instead of `throwStarted`, so an empty pouch answers with a dry click and no
+swing. On `throwStarted` attach the wind-up prop (through `mp.attach`, so replicas see it); `ThrowableSystem`'s
+`onThrow({ origin, velocity })` then sends the `throwGrenade` action — a server action, never a local spawn.
+`ProjectileSystem` needs no such switch: it stays subscribed to the same shot events as `GunHitSystem` and
+self-gates on `fire.kind: "projectile"`, so a racked launcher flies rounds, and its `onExplosion` sends the one
+`claimExplosion`.
+
+FX is one `createExplosionFx(scene, { textures })` pool for the world. Spawn it on the `grenadeExploded`
+broadcast (nothing local drew that blast) but on the ROUND's own `onExplosion` for a rocket — the server's
+`exploded` broadcast must draw nothing, or the shooter sees two fireballs. Blast audio prefers the weapon's own
+`profile.sounds.explosion` and falls back to the world's set. Explosion **textures cannot ride the item** (the
+publish walker resolves meshes, audio and clips only — no image reference site), so the world ships them; a
+procedural fallback exists. Knockback and camera trauma ride the same broadcast handler: they are FEEL, and
+retuning them can never desync health, because the room owns the damage.
+
+**Damage ops: `weaponDamage` for HELD weapons, `itemDamage` for THROWN ones.** Both resolve a PUBLISHED
+definition server-side — a client never names a damage number — and the world only picks which one:
+
+- `{"op":"weaponDamage","of":<ref>,"target":<ref>?,"default":<n>?}` — the damage of the gun that player is
+  HOLDING right now. Correct for the launcher: at `claimExplosion` the RPG is still in the shooter's grip.
+- `{"op":"itemDamage","item":"<vaultAssetId>@<version>","default":<n>?}` — the damage of the definition that
+  literal PIN names, regardless of what anyone holds. Returns `damage.base × (pellets ?? 1)`; any miss
+  (unresolved pin, no definition) yields `default ?? 0`. The pin **must also appear in
+  `multiplayer.weaponItems`** or the world fails publish validation. It has **no falloff leg by design**:
+  `weaponDamage`'s falloff is shooter→target, but a blast's distance term is blast-point→victim, which your
+  `forEachPlayer` rule already computes — the op contributes the NUMBER, the rule owns the SHAPE.
+
+```json
+"weaponItems": ["1c9f6a2e-0b34-4e11-9c5d-8f4f2a6d7b01@3"],
+"by": { "op": "*",
+        "a": { "op": "*", "a": -1, "b": { "op": "itemDamage", "item": "1c9f6a2e-0b34-4e11-9c5d-8f4f2a6d7b01@3", "default": 100 } },
+        "b": { "op": "-", "a": 1, "b": { "op": "/",
+               "a": { "op": "distance", "a": { "var": "self.position" }, "b": { "ref": "p", "var": "position" } },
+               "b": 4.5 } } }
+```
+
+> **`weaponDamage` inside a grenade rule is a SILENT wrong number.** The fuse elapses seconds after the throw,
+> when the hand is back on the rifle — so the op returns the RIFLE's damage, no error and no warning, and your
+> grenade quietly does 11. A thrown weapon is `itemDamage`, keyed by pin.
+
+**Headshots: the client names the PART, the definition names the MULTIPLIER.** Declare the enum on the claim —
+`"claimHit": { "args": { "target": { "type": "ref", "of": "player" }, "bodyPart": { "type": "string", "enum": ["head", "body"] } } }`
+— then pick the rule shape that matches how the world's guns arrive:
+
+- **Definition-resolved guns** (players hold weapons that resolve through `weaponItems` pins — vault-equipped
+  arsenals): ONE `claimHit` rule, with the part fed straight into the op —
+  `{"op":"weaponDamage","of":"self","target":{"var":"action.args.target"},"part":{"var":"action.args.bodyPart"},"default":20}`.
+  A `part` resolving to `"head"` multiplies the resolved damage (after falloff) by the definition's
+  `damage.headMultiplier` — publish-capped 1..3, absent = ×1 (the official arsenal ships 2.0 on every hitscan
+  category and nothing on launcher/thrown). Any other part value — `"body"`, a typo, an unset var — is ×1.
+- **World-attached guns** (props the world attaches itself, so nothing matches a `weaponItems` pin and
+  `weaponDamage` answers its `default`): the part has no definition to multiply through — branch at RULE level
+  instead: two `claimHit` rules split on `action.args.bodyPart`, the head rule applying a world literal
+  (`{"op":"*","a":-2,...}` vs `-1`). The `shooter-range` template is this shape.
+
+`crouched` and `ragdolled` are read-only player BUILT-INS in the DSL now (and reserved names — a `playerVars`
+entry named either fails publish). They are plausibility levers, e.g. a world where downed bodies are immune
+gates its `claimHit` rule on the target's `ragdolled` being false.
+
+**The hand-duplicated numbers.** Nothing reconciles these; a radius changed in one place gives you a blast that
+LOOKS like it connected and does nothing (or damage with no fireball). Grep the literal, fix every site:
+
+| Number | Every place it lives |
+|---|---|
+| blast radius | the definition's `projectile.blastRadiusM`, the rule's `where` distance AND its falloff divisor, the client feel literal |
+| the thrown body (radius, half-height, max speed) | `entities.grenade.physics`, the client's own dynamic body, and the upload clamp |
+| fuse seconds, cooldowns, pouch size | the rules, the respawn refill, and any HUD that counts them |
+
+**And a world's multiplayer config exists TWICE.** `public/multiplayer.json` is what the ROOM fetches through
+the signed `configUrl`; the inline `multiplayer` block in `helix.json` is what the PUBLISH validator reads.
+Rules, entities, timers, playerVars, events and `weaponItems` must be identical in both — a pin added only to
+`helix.json` publishes clean and resolves to nothing at runtime.
+
+**The never-hand-author-a-profile rule (§3) binds hardest here.** Install the definition (§8) or resolve the
+stock profile by name: a typed-out profile silently loses the sounds, and on an explosive it also drifts from
+`sounds.explosion` and from the damage number the room resolves through the pin.
+
+## 10. Verify like a shooter
+
+- Two clients, always: fire on A, confirm B sees the muzzle flash + tracer + stance; kill B, confirm the
+  ragdoll falls on A's screen and B respawns cleanly.
+- `spreadDeg`/`heat` off `gunHit` + the HUD ammo counters are the numeric feel instruments — assert them in
+  smokes instead of eyeballing.
+- The equip tracker + gun-control key collision (§2) is the #1 setup mistake; the silent-`helix_modules`
+  layout (§1) is #2; a missing `aliasWeaponProfile` on CDN guns (§3) is #3. All three fail SILENT — check
+  them first when "the gun does nothing".