@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/skills/helix-world-build/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: helix-world-build
+description: Author a HELIX Instant world the platform's way — discover the catalog before building anything, tune through manifest config rather than the class API, keep helix.json schema-valid, and prove placement by measurement instead of screenshots. Use when scaffolding a world, building or dressing a scene, configuring the character, wiring HUD or input, adding gestures, or fixing an existing world's layout, lighting or materials.
+---
+
+# HELIX World Build
+
+## Measure the first build
+
+Immediately after the first build or imported Scene exists, call `analyze_scene_performance` with the exact Scene v2 document. Act on its instancing, material, lighting, delivery, and missing-proof findings before polish. Repeat with the final Package, `inspect_world` snapshot, and runtime receipt. The static grade is estimated utilization of an existing reference profile, never predicted FPS; unknowns remain unknown. Read `read_doc({ name: "scene-performance" })` for the counter contract and visual comparison rules.
+
+The platform hands you a character system, a physics chassis, a camera rig, an input
+router, a loading screen and a measurement tool. Your job is the world: geometry, art
+direction, and the rules of the place. Everything the platform already owns, you configure
+— you do not rebuild it.
+
+## Non-negotiables
+
+These six are not taste. `helix-world-qa` fails the build on each of them, computed from
+artifacts, so building against them wastes a whole pass.
+
+1. **Real assets, not primitives.** The scaffold's grey plane and boxes are a starting
+   point, never a shippable one. Source or generate real geometry — see `helix-assets`.
+   A world whose visible meshes are all `BoxGeometry`/`PlaneGeometry`/`SphereGeometry`
+   fails QA automatically. Primitives are legitimate for collision proxies, invisible
+   volumes, and blockout during authoring; they are not a look.
+2. **Real PBR materials.** `new THREE.MeshStandardMaterial({ color })` with nothing else
+   is the default white plastic every unfinished world wears. Every material a player sees
+   carries `roughness` and `metalness`, and ideally a `map`. Reflections need an environment:
+   the visual runtime provides it on the default lane; on the opt-out lane set
+   `scene.environment` from a PMREM-processed environment yourself — without one, metalness
+   and roughness have nothing to reflect and PBR looks like flat paint. Consuming the platform
+   pack correctly — per-axis repeat, multiplier semantics, whole-ORM binding, the import
+   checklist for third-party assets — is `read_doc({ name: "world-look" })`.
+3. **Platform lighting by default — and no more than eight punctual lights either way.** The
+   default lane: hand the canvas to `createVisualRuntime` (pin `visual` in `systems`), declare
+   how the world is lit in `public/helix.visuals.json`, and place NO sun and NO ambient — the
+   runtime owns the renderer, sky, sun, tone mapping and grade, and bounded static worlds bake
+   at publish (`read_doc({ name: "lighting-world" })`). The opt-out lane — legitimate for a
+   world with its own deliberate visual identity (a custom post stack, a stylized look) — is
+   the classic doctrine in full: not one ambient light; key + fill + bounce; set
+   `renderer.toneMapping` and `toneMappingExposure` (three.js defaults to `NoToneMapping`,
+   which is why untouched worlds look washed out and clipped). ON BOTH LANES, local lights are
+   *motivated*: every `PointLight`/`SpotLight` is added as a **child of the mesh that appears
+   to emit it**, never to the scene root (a pooled light is the exception — see below).
+   **The motivation rule and the count ceiling are one rule.** On its own, "every lantern gets
+   its own light" is how a world reaches 21 lights and 11 fps.
+4. **Audio on every interaction.** Every player action, pickup, hit, UI press, state change
+   and ambience has a sound. Wire the call site as you write the interaction — retrofitting
+   audio at the end is how worlds ship silent. Route every cue through one `playSfx(name)`
+   so coverage is countable, and **name the cue after its file** — `playSfx('pickup')`
+   resolves to `pickup.mp3|ogg|wav` in the bundle, and a synthesised cue carries the
+   `synth:` prefix (`playSfx('synth:ui-press')`). That convention is what lets QA prove a
+   cue is not merely declared. Sources and the safety rail: `helix-assets`.
+5. **Keep the platform mobile controls mounted.** A fresh character-world scaffold already
+   mounts the generated touch HUD and ships its v1 controls contract. Configure or extend that
+   system from registered action metadata; replace it only when the world genuinely needs an
+   equivalent custom controller and you will prove every required touch capability.
+6. **The world runs at 60 fps.** Not "is optimised afterwards" — designed inside a budget.
+   See the next section; `helix world perf-gate` fails the build on frame time now.
+
+## Design inside the budget — it is not an optimisation pass
+
+A performance budget you consult after the world is built is a demolition order. These are the
+numbers you *design within*, decided before you place the first lantern.
+
+| Budget | Value | The constraint it puts on the design |
+| --- | --- | --- |
+| Punctual lights (point + spot) | **8 by design, 12 hard ceiling** | You get eight real lights for the whole world. Not eight per scene, per street, or per room — eight. |
+| Shadow casters | **1 directional, 0 point, ≤1 spot** | One key light carries the shape read. A shadow-casting point light renders the scene **six times per frame**. |
+| Drawing buffer | **≤2.6 M pixels**, as a derived ratio | Pick the ratio from the budget in your resize handler, never a fixed `Math.min(dpr, 2)`. |
+| Shadow map | **≤2048², 1024² recommended** | A **memory** limit. Shrinking it returns megabytes, not milliseconds. |
+| Draw calls / triangles | **≤300 / ≤500k per frame** | Each call costs ~15 µs of main-thread dispatch whatever it draws, so 300 is ~4.5 ms of a 16.7 ms frame. MESH count is the ceiling you hit first — instance repeated populations. |
+
+**Why eight.** three.js has no light culling: every light in the scene is evaluated in the
+fragment shader for **every lit pixel**, whether or not it reaches that pixel. The cost is not
+linear — it is a shader-occupancy cliff. Measured on an M1 Pro: ~0.45 ms per light up to 8,
+0.75 ms at 12, then 6.1 ms per light at 20 and 9.6 ms at 24. **The 21st light costs 13× the
+4th.** A night market with a real light in every lantern ran at 39 fps median and 11 fps when
+the player turned around. The full curve: `helix-world-qa/references/perf-budgets.md`.
+
+**Eight lights does not mean eight lit things.** The design pattern that keeps a lantern-lined
+street looking like one:
+
+- **A fixed light pool.** Every lantern, bulb, brazier and lamp is an *emitter* — a description
+  of a light, not a light. Each frame, rank emitters by distance to the camera and bind the
+  nearest six into a fixed pool of six real lights, fading over the outer ~28% of each
+  emitter's range so a re-bind never pops. Shader cost is then constant however many lanterns
+  the world grows.
+- **Instanced additive ground decals — this is the part that preserves the atmosphere.** One
+  instanced additive quad per emitter site, on the ground beneath it. A lantern that is not
+  currently in the pool still lays a warm smear on wet asphalt. 21 sites, **one draw call**,
+  unlit, no per-light cost.
+- **Emissive materials.** A glowing bulb mesh reads as a light source without being one. Four
+  street-lamp spot lights were replaced by an emissive bulb inside each lamp's glass housing.
+- **Raise ambient / hemisphere / `environmentIntensity`** to carry what the deleted always-on
+  lights used to, and check it against your original hero plate rather than by argument.
+- **Strip lights that arrive inside loaded GLBs**, on placement. An authored prop shipping its
+  own `PointLight` bills every material in the world and never shows up in your budget.
+
+Working code for the pool and the decals: `helix-world-qa/references/perf-budgets.md`.
+
+**The same trick generalises to scenery** — every repeated decorative population (city windows,
+star fields, foliage cards, crowds of repeated props) is one `InstancedMesh` per material family,
+never N meshes. Draw calls cost ~15 µs of dispatch each whatever the mesh's size, so an agent-built
+~1,200-mesh skyline — 72k triangles — burned 19.7 ms a frame and ran 45 fps facing it. The cost
+model and the remedy order: `read_doc({ name: "world-look" })`.
+
+**Resolution is a budget, not a cap** (opt-out lane — on the default lane the quality tier
+owns the pixel ratio and `visuals.setSize({ width, height })` is the only resize call):
+
+```ts
+const BUDGET_PX = 2.6e6;
+const ratioFor = (w: number, h: number, dpr = devicePixelRatio) =>
+  Math.max(1, Math.min(2, dpr, Math.sqrt(BUDGET_PX / (w * h))));
+renderer.setPixelRatio(ratioFor(innerWidth, innerHeight));   // and again on resize
+```
+
+At 1440×900 that resolves to 1.42; at 1920×1200, to 1.06 — the same 2.6 M pixels and the same
+frame time on a bigger window. A fixed cap of 2 would be 9.2 M pixels there, and it passes on
+whatever window you happened to test. `helix world perf-gate` grows the window mid-run specifically to
+catch that.
+
+**Ship the `?perf=1` handle** (`helix-world-qa/references/perf-handle.md`) — a ~40-line
+`src/perf.ts` that installs nothing unless the query flag is present. It is what turns "the
+world is slow" into "these three lights cost 74 ms", and what lets the QA gate name a light
+instead of reporting `measured NOTHING`. **Name your lights** while you are there;
+`(unnamed)` in a failure report is a self-inflicted wound.
+
+## Touch controls: configure the platform default
+
+`helix init` mounts `createMobileControls(input, { surface })` after abilities register and calls
+`mobileControls.update()` before `character.update()` each frame. The system activates by touch
+capability and provides a left movement stick, open-space drag look, concurrent two-finger pinch
+zoom (including the first/third-person transition), jump and every registered `button`/`hold`/`tap`
+action. It already owns safe-area layout, platform top offset, accessibility, capture cancellation,
+context changes and teardown. Do not copy it into world code.
+
+Standard actions generate their labels and widget types from the registry. Add a world verb by
+registering it on the same router, then safely relabel/reorder/place it through the controls config:
+
+```ts
+input.registerAction('world.scan', {
+  kind: 'button', context: 'gameplay', label: 'Scan', touch: 'hold', keys: ['KeyF']
+}, 'world');
+
+const mobileControls = createMobileControls(input, {
+  surface: renderer.domElement,
+  platformTopOffset: 0, // host-owned chrome offset; safe-area inset is added automatically
+  actions: [
+    { id: 'world.scan', label: 'Scan', order: 1 },
+    { id: 'cameraMode', placement: 'utility' },
+    { id: 'crouch', visible: false },
+  ],
+  theme: { accent: '#7dd3fc', scale: 1 },
+});
+```
+
+Labels are plain text and theme/layout values are constrained tokens—never pass markup or build a
+second HTML injection seam. Core move/look/zoom stay on unless the genre deliberately disables one
+with `core`. An equivalent custom controller remains valid: replace `public/helix.controls.json`
+provider with `custom`, keep the required move/look/zoom/jump capability list truthful, and preserve
+the same InputService/context/cleanup semantics.
+
+`supportsMobile: true` is still earned by evidence. `source-audit` validates that the controls
+contract is shipped rather than guessing from virtual-input regexes; G6/G7 must then drive the built
+HUD at 390×844 and 844×390, assert touch-only movement, look, pinch mode transition, jump apex and
+one custom action, and confirm keyboard/mouse/gamepad remain intact.
+
+## Typecheck, because `vite build` does not
+
+```bash
+npx tsc --noEmit      # the scaffold defines this as `npm run typecheck`
+```
+
+`npm run build` is `vite build`. It transpiles and throws types away — **a type error builds
+clean, publishes, and fails silently at runtime.** Run `tsc --noEmit` before every build you
+intend to keep, and treat a non-zero exit as a broken world, not as lint.
+
+**The defect this exists for**, because it is invisible any other way:
+
+| You call | The tunables key is |
+| --- | --- |
+| `CharacterMultiplayer.create({ … })` *(what the scaffold builds on)* | **`character:`** |
+| `Character.create({ … })` | **`config:`** |
+
+```ts
+// WRONG on CharacterMultiplayer — a type error, and nothing else complains
+await CharacterMultiplayer.create({ …, config: { locomotion: { runSpeed: 7 } } });
+// RIGHT
+await CharacterMultiplayer.create({ …, character: { locomotion: { runSpeed: 7 } } });
+```
+
+Every doc and recipe shows `Character.create({ config })`, so the wrong key is the natural
+guess. Vite ships it, the world runs, and **every value inside is silently ignored** —
+including the genre `allow*` gates below, so a "first-person" world still flips to third
+person on T and no artifact says why. `source-audit` flags this exact shape now; `tsc`
+catches the whole class of which it is one member.
+
+## Discover before you design
+
+`list_systems` → `list_abilities({ system: "humanoid-character" })` →
+`get_package_manifest({ slug })` for everything you will pin. The catalog grows; a flying
+game pins `fly`, an underwater game pins `swim`, a shooter pins `gun-control`. Writing a
+behavior that already exists as a published ability is the most expensive mistake available
+here.
+
+Engine `systems` are ALWAYS ranges (`^0.3`, `^0.1`) — never an exact `x.y.z`, and never pinned to get an
+unpromoted engine fix: publish refuses an exact pin; promote the fix instead.
+
+Pin each ability at the version `get_package_manifest` reports for the system line you pinned
+(`humanoid-character` `^0.3` today). An ability bundle declares the system range it was built
+against; outside it the system loads and the ability silently refuses at runtime.
+
+## Tunables live in the manifest `config`, not the TypeScript class API
+
+This is the single most common failure in HELIX world code. Speed, spawn, look sensitivity,
+initial facing, FOV, slope, jump feel, camera distance, movement axis — all of it is a
+config **value**.
+
+**The failure signature:** you read the `Character` or `LocomotionAbility` class, conclude
+"there is no setting for X", and write your own. You looked in the wrong place. The tunable
+surface is `get_package_manifest("humanoid-character").config`, and its `capabilities` block
+lists the runtime API, the events, the input actions and the reserved keys.
+
+Two ways to set a value, one runtime surface:
+
+```ts
+// initial
+Character.create({ config: { locomotion: { runSpeed: 7 }, character: { spawn: { x, z, facingDeg }, camera: { mode } } } })
+// live, read every tick — timed buffs, difficulty, cutscenes
+character.config.set('locomotion.runSpeed', 11);
+// runtime-only actions live in capabilities.api
+character.services.body.teleport({ x, y, z }); character.respawn(); character.camera?.addTrauma(0.6);
+```
+
+In `humanoid-character` 0.2.21+, `spawn.facingDeg` is durable (`0 = +Z`, `90 = +X`). Omit or set
+`camera.initialYaw` to `null` for the engine to derive the behind-character boom yaw as
+`facingDeg - 180`; locomotion and respawn preserve that relationship. A numeric `initialYaw`
+intentionally overrides the camera seed. Boom yaw `0` places the camera on `+Z` looking toward `-Z`.
+
+**Gate:** every config key you set must appear in the manifest's `config`. An invented key
+is silently ignored — it does not throw, so you will believe it worked. Diff your keys
+against the manifest before you build. The same is true one level up, for the *options* key
+the config block sits on — see "Typecheck, because `vite build` does not".
+
+## Match the controls to the genre — every `allow*` gate defaults to ON
+
+You do not enable controls, you **disable** the ones that do not belong. The classic
+shipped bug: a first-person game where pressing **T** still flips to third person, because
+`allowModeToggle` was left at its default `true`.
+
+| Genre | Required disables |
+| --- | --- |
+| First-person only | `character.camera.allowModeToggle: false` |
+| Third-person only | `allowModeToggle: false`, `allowShoulderSwap: false` |
+| Top-down / twin-stick | `allowModeToggle: false`, `allowRotate: false`, `allowZoom: false`; `initialPitch: -80`, `locomotion.facingMode: 'movement'` |
+| 2.5D side-on | `locomotion.movementAxis: 'x'` |
+| Walking sim / puzzle | `locomotion.allowJump: false` |
+
+`helix world source-audit` checks this against the genre you declared in the ledger. Full matrix
+and the camera/locomotion recipes: `references/config-gates.md`.
+
+## Never author these
+
+- **A renderer, a tone mapper or a sun — on the default lane.** `createVisualRuntime` owns
+  all three; author `public/helix.visuals.json` instead, and bake bounded static worlds at
+  publish (`read_doc({ name: "lighting-world" })`). A world that keeps its own visual
+  identity opts out deliberately and owns them again — that is the one exception, chosen,
+  never drifted into.
+- **A character controller or a skeleton.** The `humanoid-character` system owns the
+  chassis; `helix-humanoid@1` (68 bones, UE MetaHuman naming) is the canonical skeleton.
+  46 locomotion clips stream from the CDN.
+- **Server code.** Multiplayer is declarative — see `helix-multiplayer`.
+- **A login form.** `Helix.auth.requestLogin()` raises the shell's own overlay.
+- **A three.js version — or a Rapier build.** The platform pins both and injects them via the
+  import map that `install_world_packages` generates: each is a **devDependency** and the build
+  routes them out with a PREDICATE, `build.rollupOptions.external: (id) => id === 'three' ||
+  id === '@dimforge/rapier3d-compat' || id.startsWith('@helix/')`. The `@helix/` arm is not
+  optional — an externals array leaves the platform systems bundled and publish refuses the
+  build. The `humanoid-character` pin chooses the three version (`^0.3` → three 0.185.1; keep the
+  devDependency on that same line, since the jsm addons bundle from it); a publish targeting an
+  older three still goes through, with a warning. Two copies of three break `instanceof` and corrupt rendering
+  silently — no error, just wrong pixels; a bundled Rapier is a wasted ~2 MB in every world. Your
+  imports (`RapierBody` included) do not change — only the resolution does.
+- **Custom character animation as GLB.** Worlds author gestures as a **JSON pose DSL**
+  (sparse Euler keyframes by bone name), one clip per file under `src/gestures/`. It is for
+  short upper-body-led motion — waves, salutes, stances, flinches. Not dances, not fight
+  choreography, not anything where feet must plant or the character travels. There is no
+  root motion, no IK, no weight shift. If you are keying legs *and* arms *and* torso to one
+  beat, or on your third visual iteration, stop — the format cannot represent it.
+  `read_doc("character-animation")` before writing a single key.
+
+## The manifest is Ajv-validated with `additionalProperties: false`
+
+An invented field is a **rejection**, not a warning. So is a permission you did not need, a
+slug that collides, an entry file that is not in the bundle. Cross-field rules bite too:
+`maxPlayers > 1` requires the `multiplayer` permission, which forces `requiresAuth: true`;
+`voice.*` requires `multiplayer`. Read `read_doc("manifest")` and run `validate_world`
+rather than reasoning about what the schema probably allows.
+
+## Put all world geometry under one named root
+
+```ts
+const worldRoot = new THREE.Group();
+worldRoot.name = 'world';
+scene.add(worldRoot);   // every mesh you author goes in here
+```
+
+Costs nothing and buys a lot: the inspect roster becomes readable, and the QA composition
+gate can tell your geometry apart from the streamed character body. Without it the audit
+falls back to a name heuristic and says so.
+
+## Measure placement — do not look harder at a screenshot
+
+Distances and depth read off an image are unreliable on exactly the axis placement lives on.
+
+```
+world_metrics({ projectDir })                 → step height 0.35 m, 50° slope, jump envelope — BEFORE you place geometry
+inspect_world({ directory, focusNear:[x,y,z] })→ after each placement: exact position, size, facing, collider presence
+inspect_world({ directory })                   → the full findings pass
+capture_world_screenshot({ directory })        → ONCE at the end, for how it reads
+```
+
+**Findings are measurements, not verdicts.** A hovering pickup, a ramp embedded in the
+ground, walls overlapping at their corners — all warn on perfectly good worlds. The rule: a
+warn that matches what you meant needs no fix; a warn that surprises you is the bug. Never
+edit geometry to silence a finding. Once adjudicated, run `writeBaseline: true` — that is the
+normal step, not one to ask about. It makes the judgment durable so later runs report only
+what changed, and on a world whose premise generates warnings by construction it is the
+difference between an inspect report anyone reads and one everyone skims.
+
+`focusNear` also answers the orientation defect a screenshot hides: a chair rotated 180°
+from its table reads `faces: AWAY from table (0.8 m)`.
+
+## Loaders: GLTFLoader + KTX2Loader only
+
+A Draco- or meshopt-compressed model **fails to load at runtime**. Not degraded — absent.
+Check the whole asset tree before bundling, never after a player reports a missing model:
+
+```bash
+helix assets check-loaders public/assets   # exits non-zero on the first blocker
+```
+
+It reads **both** container forms — `.glb`'s binary header and plain-JSON `.gltf` + `.bin`,
+which is what Poly Haven ships. `helix world audit` runs the same check over `dist/` as a
+blocking gate, so this is the early warning, not the enforcement.
+
+Failure signatures to recognise: `THREE.GLTFLoader: No DRACOLoader instance provided` and
+`KHR_draco_mesh_compression` / `EXT_meshopt_compression` in `extensionsRequired`. The most
+common way to *create* one is `gltf-transform optimize`, which compresses with meshopt by
+default — see `helix-assets`.
+
+## Platform surfaces you must respect
+
+- **Top-center is the shell's.** A chrome bar (Exit / Save / helixOS) overlays the top
+  ~56px of every world. Anchor HUD to a corner or the bottom; full-width elements start
+  ≥64px down. UI at top-center renders behind the chrome.
+- **Input is the router, never `addEventListener`.** One world-owned `InputService`,
+  `registerStandardActions` for the ids you need, `pushContext('menu')` for pause. Raw
+  listeners bypass the context stack, get no gamepad or touch, and can never be rebound.
+  Reserved keys — Escape, KeyN, backtick — are never yours (KeyB is the `point` standard action now, bound, not free).
+- **Control text comes from the router**: `input.format('Drive with {move} · {interact} to grab')`,
+  re-rendered each frame. Hardcoding "press E" is wrong the moment a pad is picked up.
+- **The world must run standalone.** `Helix.init()` returns `embedded: false` outside the
+  shell and identity APIs return null. Never block rendering on identity.
+- **Test with `build` + `preview`, not `dev`.** The dev server rewrites bare imports and
+  hides whether the import map is correct.
+
+## Definition of done for this phase
+
+`npx tsc --noEmit` exits 0 · `npm run build` exits 0 · `validate_world` reports VALID ·
+`inspect_world` findings are adjudicated and a baseline is written · touch controls exist and
+were driven at a phone viewport, or `supportsMobile` is `false` · `helix world perf-gate` exits 0 on the
+built world (60 fps p50, 30 fps p95, inside the light and pixel budgets) · the six
+non-negotiables above hold, as measured by `helix-world-qa`, not as asserted here.

package/skills/helix-world-build/references/config-gates.md

@@ -0,0 +1,104 @@
+# Genre → config gates, and how to check yours against the manifest
+
+Every `allow*` gate on the `humanoid-character` system **defaults to `true`**. Matching a
+genre means turning controls **off**. This file is the lookup table plus the check that
+proves you did it.
+
+Authoritative source is always `get_package_manifest("humanoid-character")` → `config`.
+This table is the decision, not the contract — confirm key names and defaults there.
+
+## The gates
+
+| Gate | Removes |
+| --- | --- |
+| `character.camera.allowModeToggle` | the first↔third-person legs of the **T** camera cycle |
+| `character.camera.allowRotate` | orbit / mouse-look (fixed camera angle) |
+| `character.camera.allowZoom` | scroll-wheel zoom |
+| `character.camera.allowShoulderSwap` | the over-shoulder legs of the camera cycle |
+| `locomotion.allowJump` | the jump action |
+| `locomotion.allowCrouch` | the crouch action (frees KeyC / `faceRight`) |
+| `locomotion.allowSprint` | the sprint action |
+
+## Genre presets
+
+```ts
+// First-person only — T must NOT flip to third person.
+config: { character: { camera: { mode: 'first-person', allowModeToggle: false } } }
+
+// Third-person only — no FP toggle, no shoulder-swap clutter.
+config: { character: { camera: { mode: 'third-person', allowModeToggle: false, allowShoulderSwap: false } } }
+
+// 3D top-down / twin-stick / ARPG / MOBA — fixed framing, body faces movement.
+config: {
+  character: { camera: { mode: 'third-person', allowModeToggle: false, allowRotate: false,
+                         allowZoom: false, initialPitch: -80, tp: { distance: 15 } } },
+  locomotion: { facingMode: 'movement' },
+}
+
+// 2.5D side-on platformer — planar movement locked to one axis.
+config: { locomotion: { movementAxis: 'x' } }
+
+// Walking sim / puzzle / point-to-move — no jump.
+config: { locomotion: { allowJump: false } }
+```
+
+`initialYaw` / `initialPitch` are construct-time **seeds**. In `humanoid-character` 0.2.21+,
+omit or set `initialYaw` to `null` to derive a behind-character camera from durable
+`spawn.facingDeg` (`camera yaw = facingDeg - 180`). A numeric `initialYaw` intentionally overrides
+that camera seed. Camera yaw is boom azimuth: `0` places the camera on `+Z` looking toward `-Z`.
+To re-aim a live camera use `character.camera?.setYaw(deg)` / `setPitch(deg)`, not `config.set`.
+
+## Verify your config keys exist — the check that catches invented keys
+
+An invented config key does not throw. It is ignored, and you spend an hour wondering why
+`runSpeed` did nothing. Dump the manifest's key set and compare:
+
+```bash
+# 1. get_package_manifest({ slug: "humanoid-character" }) → save its `config` object to qa/character-config.json
+# 2. list every key you set in src/, flattened to dotted form
+grep -oE "config\.set\('[a-zA-Z0-9_.]+'" src/*.ts | grep -oE "'[^']+'" | tr -d "'" | sort -u
+```
+
+Then confirm each dotted key resolves in `qa/character-config.json`. Keys set through the
+nested `Character.create({ config })` object flatten the same way
+(`{ locomotion: { runSpeed } }` → `locomotion.runSpeed`).
+
+## Runtime API — what config cannot express
+
+From `capabilities.api`, not from guessing:
+
+```ts
+character.services.body.teleport({ x, y, z });          // move now
+character.services.body.applyImpulse({ x, y, z });      // jump pad, knockback, explosion
+character.respawn(/* optional checkpoint */);           // teleport + zero velocity + stand + reface
+character.setEnabled(false);                            // hard pause for a cutscene
+character.camera?.addTrauma(0.6);                       // camera shake, 0..1
+```
+
+Events via `character.events.on(name, cb)`: `landed` (`{ impactSpeed, fallDistance, speed }`
+— `impactSpeed` is the fall-damage number), `fell`, `respawned`, `jumped`, `stateEntered`.
+Each is an interaction, so each needs a sound.
+
+## Input placement, in order of preference
+
+1. A **genre-freed plain button** — reuse the slot of a standard action this world can
+   never register. A card game has no gunplay, so `reload`'s KeyR/`faceUp` and the triggers
+   are free. Note the reuse in a comment at the registration site.
+2. `pad: 'dpadUp'` — always free, but a fallback, not a first pick.
+3. A `withModifier` chord. **Reserved chords, never claim:** modifier+right stick (camera
+   zoom), modifier+bumperR (`voicePTT`), modifier+bumperL (reserved).
+4. Keyboard-only — debug conveniences only. A pad or touch player can never reach it.
+
+To reuse an always-on action's source, **disable the owner first** via its genre gate
+(`locomotion.allowCrouch: false` frees KeyC). Never bind over a live action.
+
+Paired verbs share one symmetric group — bumperL/bumperR, dpadUp/dpadDown,
+faceLeft/faceRight, triggerL/triggerR. Never split a pair across groups.
+
+## Loading screen
+
+`src/loading.ts` hooks `THREE.DefaultLoadingManager`, the same instance the engine's
+loaders use, so every three.js load counts on the bar automatically. For a non-three asset
+(audio, a raw fetch) wrap it: `const t = loading.task(); … t.done();`. Dismiss after the
+**first rendered frame**, never on `manager.onLoad` — that fires on the transient 2/2 blip
+before the clips enqueue.