@hypersoniclabs/helix-mcp 0.2.5 → 0.2.12

package/skills/helix-world-qa/references/perf-budgets.md

@@ -0,0 +1,240 @@
+# Performance budgets — what was measured, and what it does not say
+
+Every number here came off one machine — **Apple M1 Pro, ANGLE Metal, headless Chromium,
+`gl.finish()` per frame, vsync off** — running two real published worlds. Where a limit is a
+guess, it says so. Where a hypothesis was refuted, the refutation is kept, because the wrong
+answer is the one an agent will reach for first.
+
+Raw evidence: `qa/perf.txt` in the Night Market and Skyward projects (ablation ladders,
+before/after tables, the light-count sweep).
+
+## The failure this exists to catch
+
+Night Market shipped at **25.5 ms p50 / 92.7 ms p95, 26% of frames over 33 ms** — 39 fps
+median, 11 fps when the player turned around. It passed every gate we had. QA measured
+triangles, bundle size and draw calls, printed frame rate as an informational line, and never
+failed on it. A world could run at 10 fps and be green.
+
+Frame time is the outcome. Triangles, draw calls and light counts are causes. Gate the outcome,
+report the causes.
+
+## The refuted hypothesis — do not reinstate it
+
+The obvious suspect was shadow-casting point lights: three renders the scene six times per
+frame for each one, so 2 of them were 13 of the 14 render passes, 392 draw calls and 728k
+triangles per frame.
+
+**Freezing the shadow maps removed all of that and made the world zero milliseconds faster.**
+
+```
+baseline                          86.7 ms
+freeze shadow maps (render once)  89.4 ms    -2.7 ms saved    0%
+disable shadows entirely          66.9 ms    19.8 ms saved   23%
+stop point lights casting         81.4 ms     5.3 ms saved    6%
+```
+
+Rendering the shadow maps was free. **Looking them up was not.** The entire 19.8 ms attributed
+to "shadows" is per-pixel PCF sampling in the fragment shader. Shadow-map rendering cost 6% and
+reads as 86% of the draw calls — which is why draw calls are a bad proxy for time.
+
+## The actual cause: analytic light COUNT
+
+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. Twenty-one local lights cost
+twenty-one lights per pixel across the whole screen.
+
+Removing all point lights alone saved **86%** of the frame.
+
+It is not a linear cost. It is an occupancy cliff — three unrolls every light into one fragment
+shader, and past ~14 lights the register pressure collapses GPU occupancy:
+
+| punctual lights | 0 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | 20 | 24 |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| p50 ms | 9.2 | 9.9 | 10.7 | 11.6 | 12.8 | 14.1 | 15.6 | 18.4 | 22.7 | **47.0** | **85.2** |
+| fps | 109 | 101 | 94 | 86 | 78 | 71 | 64 | 54 | 44 | **21** | **12** |
+| marginal ms/light | — | 0.35 | 0.40 | 0.45 | 0.60 | 0.65 | 0.75 | 1.40 | 2.15 | **6.08** | **9.55** |
+
+*(Night Market's material set, pixel ratio pinned to 2 = 5.18 M pixels, identical pinned pose
+and deterministic 360° yaw sweep per run, one page load per count.)*
+
+**The knee is between 12 and 16. The 21st light costs 13× the 4th.**
+
+Spot lights, same method: a spot costs about **1.3×** a point light before the cliff and reaches
+the cliff sooner (total 16 → 35.4 ms all-mixed vs 22.7 ms all-point). Which is why the gate
+counts **point + spot combined** rather than per type.
+
+## The limits
+
+| Limit | Value | Category |
+|---|---|---|
+| Frame p50 | **≤ 16.7 ms (60 fps sustained)** | blocking outcome |
+| Frame p95 | **≤ 33.3 ms (30 fps)** | blocking outcome |
+| Punctual lights (point + spot) | warn at **6**, fail at **12**, design target **8** | the cause |
+| Shadow-casting lights | **1 directional, 0 point, ≤1 spot** | the cause |
+| Shadow map size | **≤ 2048², 1024² recommended** | **memory, not time** |
+| Drawing-buffer pixels | **≤ 2.6 M**, as a derived ratio | the largest multiplier |
+| Draw calls | **≤ 300/frame** | CPU submission guard |
+| Triangles | **≤ 500k/frame** | CPU submission guard |
+| Decoded texture bytes | **≤ 256 MB** | **UNVALIDATED — warns, does not block** |
+
+### Punctual lights: 8 by design, 12 as a wall
+
+The design target is 8 because it leaves **2× headroom** for GPUs weaker than an M1 Pro. The
+wall is 12 because that is where the curve stops being linear — not because 13 lights is
+meaningfully worse than 12, but because past it you cannot predict the cost at all.
+
+### Shadow casters: gate the count, not the map size
+
+A shadow-casting **point** light renders the whole scene six times per frame. On Skyward one
+brazier flame was 85 of 141 draw calls and 233k of 424k triangles — for a shadow no player could
+read. Zero are allowed. One directional key light carries the shape read for the whole world.
+
+### Shadow map size is a MEMORY limit
+
+512 vs 1024 measured as **noise** (−1.3 ms, inside run-to-run variance, on the wrong side of
+zero). Shrinking a shadow map returns megabytes, not milliseconds. Say this out loud whenever
+you touch it, or the next agent will "optimise" it expecting frames back and conclude the
+profiler is broken when nothing changes.
+
+### Resolution: a budget, never a fixed DPR cap
+
+Halving the drawing buffer halved the frame — **69%**, the single largest lever measured. But it
+is a multiplier over every per-pixel cost, not an independent cause: it makes a badly-lit world
+cheaper without making it well-lit.
+
+Express it as a budget and derive the ratio:
+
+```ts
+// The largest pixel ratio (<=2, >=1) that keeps the drawing buffer under budget.
+const BUDGET_PX = 2.6e6;
+function pixelRatioFor(w: number, h: number, dpr = window.devicePixelRatio) {
+  return Math.max(1, Math.min(2, dpr, Math.sqrt(BUDGET_PX / (w * h))));
+}
+renderer.setPixelRatio(pixelRatioFor(innerWidth, innerHeight));
+// …and recompute it in the resize handler, not just at boot.
+```
+
+**A fixed `Math.min(devicePixelRatio, 2)` passes on the window you tested and falls off a cliff
+on a bigger one.** At 1440×900 the budget resolves to ratio 1.42; at 1920×1200 it resolves to
+1.06 — same 2.6 M pixels, same frame time, a bigger window. A fixed cap of 2 would have been
+9.2 M pixels and 3.5× the per-pixel cost. `helix world perf-gate` probes for exactly this by growing the
+window mid-run.
+
+### Draw calls and triangles: guards, not the thing that matters
+
+Say this plainly whenever you report them. **418 draw calls and 778k triangles per frame
+measured as costing nothing on this machine** — the frozen-shadow run removed 392 calls and 728k
+triangles and returned no time at all. The 300 / 500k limits are deliberately generous guards on
+CPU submission cost for machines weaker than an M1 Pro. A world failing only these is a world
+with a CPU-side risk, not a world that is slow here.
+
+### Decoded texture bytes: UNVALIDATED, and therefore not blocking
+
+256 MB is a precaution, not a measurement. Decoded texture memory was never observed to cost
+frame time on unified-memory Apple silicon; Skyward carried 252 MB at 500 fps. It is held as a
+budget because a 16 GB shared-memory machine running a browser, an editor and a world has other
+things to pay for. **Do not present it as measured, and never diagnose a slow world with it.**
+
+It **warns and does not block**, and the reason is a real result rather than a preference. On
+its first run this limit was blocking, and it failed Skyward at **279.7 MB while the world was
+rendering at 1.9 ms p50 (526 fps)** — a gate stopping a release over a number that has never
+been shown to cost anything. It also read 237 MB through the published shell and 279.7 MB
+locally on the *same bundle*: ~18% run-to-run spread, which is not gate-quality precision.
+
+A blocking gate on an unvalidated number teaches an agent to delete texture resolution chasing
+frames it will not get — the same error as "optimising" a shadow map, and the same confusion
+between causes and outcomes that let two worlds ship at 39 fps with everything green. **It
+becomes blocking the day someone measures texture memory costing a frame, and not before.**
+
+## When you hit the light ceiling, do this — not "delete lights"
+
+The ceiling is not an instruction to make the world flat. Night Market kept its atmosphere at
+**6 lights** while it had 21 before, and the hero plate is indistinguishable. Two techniques did
+that:
+
+### 1. A fixed light pool bound to emitters
+
+Every lantern, bulb, lamp and fire becomes an **emitter** — a description of a light, not a
+light. Each frame the emitters are ranked by distance to the camera and the nearest N are bound
+into a fixed pool of N real lights. Shader cost is then constant no matter how many lanterns the
+world grows.
+
+```ts
+type Emitter = { pos: THREE.Vector3; color: THREE.Color; intensity: number; range: number };
+
+const POOL = 6;
+const pool = Array.from({ length: POOL }, () => {
+  const l = new THREE.PointLight(0xffffff, 0, 1);
+  l.castShadow = false;                 // pooled lights never cast
+  scene.add(l);
+  return l;
+});
+
+function bindPool(emitters: Emitter[], camera: THREE.Camera) {
+  const cam = camera.getWorldPosition(new THREE.Vector3());
+  const ranked = emitters
+    .map((e) => ({ e, d: e.pos.distanceTo(cam) }))
+    .sort((a, b) => a.d - b.d)
+    .slice(0, POOL);
+  pool.forEach((light, i) => {
+    const hit = ranked[i];
+    if (!hit) { light.intensity = 0; return; }
+    // Fade to zero over the outer 28% of the emitter's own range, so an emitter can only
+    // enter or leave the pool while contributing nothing. A re-bind is then invisible —
+    // without this, walking down a street makes lanterns pop on and off.
+    const fade = 1 - Math.max(0, (hit.d - hit.e.range * 0.72) / (hit.e.range * 0.28));
+    light.position.copy(hit.e.pos);
+    light.color.copy(hit.e.color);
+    light.distance = hit.e.range;
+    light.intensity = hit.e.intensity * Math.min(1, Math.max(0, fade));
+  });
+}
+```
+
+Bind **after** any per-frame flicker/animation writes to the emitters, or the breathing is one
+frame stale.
+
+### 2. Instanced additive ground decals — this is what preserves the atmosphere
+
+A lantern that is *not* currently in the pool still needs to read as lit. Give every emitter site
+one instanced additive quad on the ground beneath it: a warm smear on wet asphalt, one draw call
+for all of them.
+
+```ts
+const decal = new THREE.InstancedMesh(
+  new THREE.PlaneGeometry(1, 1),
+  new THREE.MeshBasicMaterial({
+    map: radialFalloffTexture, transparent: true, blending: THREE.AdditiveBlending,
+    depthWrite: false, toneMapped: false, fog: true,
+  }),
+  emitters.length,          // 21 emitter sites, ONE draw call
+);
+decal.renderOrder = 2;      // after opaque, before other transparencies
+```
+
+Set each instance's matrix to the emitter's ground position, rotated flat and scaled to the pool
+radius, and its instance colour to the emitter colour. Unlit, so it costs nothing per light —
+and it is the pooled world's entire visual difference from the 21-light one.
+
+Other moves, in the order they cost least:
+- **Emissive materials.** A glowing bulb mesh reads as a light source without being one. A
+  street-lamp cone rebuilt from an emissive bulb inside its glass housing replaced four spot
+  lights.
+- **Raise ambient/hemisphere/`environmentIntensity`** to carry what the deleted always-on lights
+  used to. Night Market went hemisphere 0.34 → 0.46, bounce 0.40 → 0.47, environment 0.35 → 0.44.
+  Verify against the original hero plate, not by argument.
+- **Strip lights that arrive inside loaded GLBs.** An authored prop that ships its own
+  `PointLight` adds a per-pixel cost to every material in the world, invisibly and outside your
+  budget. Remove them on placement.
+
+## Reading a perf-gate result
+
+- **The renderer string is part of the result.** A frame time without the GPU that produced it is
+  not interpretable, and it is how you notice the ANGLE flags stopped working. If it says
+  SwiftShader, the run is void — the gate refuses rather than reporting it.
+- **`gl.finish()` per frame is what makes the number real.** Without it the CPU queues frames
+  ahead of the GPU and you measure JS. Skyward read 562 fps without it.
+- **p95 is the number players feel.** A world at 9 ms p50 and 90 ms p95 stutters exactly when the
+  player turns to look at something, which is exactly when they are paying attention.
+- **One change, then re-measure the same scenario.** A batch of seven optimisations tells you
+  nothing about which one worked, and one of them is usually a regression.

package/skills/helix-world-qa/references/perf-handle.md

@@ -0,0 +1,125 @@
+# The `?perf=1` handle — ship it in every world
+
+`helix world perf-gate` measures frame time, draw calls, triangles, passes, drawing-buffer pixels and
+decoded texture bytes by wrapping the WebGL context, so those work on **any** bundle, including
+one built before this file existed.
+
+Two things it cannot get that way:
+
+- **which** lights are in the scene — names, shadow flags, map sizes;
+- a shadow map's configured size, as opposed to the size of some render target.
+
+Without the handle those gates report `measured NOTHING`, which is a warning you then have to
+carry into the QA report. With it, a failure names the light.
+
+## Why not read the source instead
+
+We tried. `helix world source-audit` used to count `new THREE.PointLight(` across the source tree and
+print `PointLight×4 · SpotLight×1`. The scene it was describing contained **18 point lights and
+4 spot lights** — four constructor call sites, all inside loops. Skyward reported 3 and had 13.
+
+The one metric that would have caught the defect that shipped was **wrong by 4.5×**, and it was
+wrong in the direction that passes. A census has to walk the scene that is actually rendering.
+
+## The file
+
+Copy this to `src/perf.ts` and call `installPerfHandle` once, after the renderer and scene exist.
+It installs nothing unless the query flag is present, so it costs a `URLSearchParams` read during
+play.
+
+```ts
+import type * as THREE from 'three';
+
+/**
+ * Performance handle, gated behind `?perf=1`.
+ *
+ * Without this there is no way to attribute a frame to a cause: you can see that a world is
+ * slow, but not what fraction of the frame each light / shadow / material choice is worth. The
+ * handle exposes the renderer's own counters plus a light census, and lets a profiler pin a
+ * deterministic camera so two runs differ only by the one thing being ablated.
+ */
+export interface PerfDeps {
+  THREE: typeof THREE;
+  scene: THREE.Scene;
+  renderer: THREE.WebGLRenderer;
+  camera: THREE.Camera;
+  /** Physics body, so the profiler can park the player at a fixed, repeatable vantage point. */
+  body?: { teleport?(p: { x: number; y: number; z: number }): void };
+  /** Character facade, for camera yaw/pitch pinning. */
+  character?: unknown;
+}
+
+export interface LightCensusRow {
+  type: string;
+  name: string;
+  intensity: number;
+  castShadow: boolean;
+  mapSize: [number, number] | null;
+  /** three renders a shadow-casting point light SIX times per frame, one per cube face. */
+  passesPerFrame: number;
+}
+
+export function installPerfHandle(deps: PerfDeps): void {
+  if (typeof location === 'undefined') return;
+  if (!new URLSearchParams(location.search).has('perf')) return;
+
+  const { scene, renderer } = deps;
+
+  const lights = (): LightCensusRow[] => {
+    const rows: LightCensusRow[] = [];
+    scene.traverse((o) => {
+      const l = o as THREE.Light & { shadow?: THREE.LightShadow; castShadow?: boolean };
+      if (!(l as { isLight?: boolean }).isLight) return;
+      const cast = l.castShadow === true;
+      const isPoint = l.type === 'PointLight';
+      rows.push({
+        type: l.type,
+        name: l.name || '(unnamed)',
+        intensity: l.intensity,
+        castShadow: cast,
+        mapSize: l.shadow ? [l.shadow.mapSize.x, l.shadow.mapSize.y] : null,
+        passesPerFrame: cast ? (isPoint ? 6 : 1) : 0,
+      });
+    });
+    return rows;
+  };
+
+  const info = () => ({
+    render: {
+      calls: renderer.info.render.calls,
+      triangles: renderer.info.render.triangles,
+      frame: renderer.info.render.frame,
+    },
+    memory: { geometries: renderer.info.memory.geometries, textures: renderer.info.memory.textures },
+    programs: renderer.info.programs?.length ?? 0,
+    shadowPassesPerFrame: lights().reduce((a, r) => a + r.passesPerFrame, 0),
+  });
+
+  (globalThis as unknown as Record<string, unknown>).__helixPerf = {
+    THREE: deps.THREE, scene, renderer, camera: deps.camera,
+    body: deps.body, character: deps.character, lights, info,
+  };
+}
+```
+
+```ts
+// src/main.ts, once, after the renderer and scene exist:
+installPerfHandle({ THREE, scene, renderer, camera, body: character.services.body, character });
+```
+
+## Name your lights
+
+`light.name = 'lantern-pool-0'` costs nothing and turns a gate failure from *"3 point lights cast
+shadows"* into *"brazier-flame, relic-halo and lamp-3 cast shadows"*. The census prints whatever
+is there; `(unnamed)` is a self-inflicted wound.
+
+## What it unlocks beyond the gate
+
+`__helixPerf` also exposes `scene`, `renderer`, `camera` and `body`, which is what makes an
+**ablation ladder** possible: pin the player at one vantage point, run one page load per variant
+changing exactly one thing, and the frame-time delta between two runs is attributable to that one
+thing. That is how the light-count curve in `perf-budgets.md` was produced, and it is the only
+honest way to answer "what is this frame actually spent on".
+
+Rule for a ladder: **pin the pose and sweep the view identically in every run.** A variant that
+happens to face the skybox will look like a 60% win.

package/skills/helix-world-qa/references/visual-scorecard.md

@@ -0,0 +1,85 @@
+# Visual scorecard
+
+Score **active-play screenshots** at the framing a player actually gets — not an idle title
+card, not an isolated model on a turntable. Desktop and a 390×844 mobile viewport.
+
+## Read this before you use it
+
+This rubric is **advisory**, and saying so is the point. Four of its ten rows are backed by
+a script that exits non-zero (marked ⛔); those are gates. The other six are you grading your
+own screenshot, and an average you computed about your own work is not evidence. Record the
+scores, use them to find the next pass, and never present the average as a gate.
+
+The reference rubrics this one is adapted from gate entirely on self-report — an auditor
+that greps the agent's prose for the string "art direction" passes any agent that types the
+words. Everything here that can be measured has been moved into `helix world audit` and
+`helix world source-audit` instead.
+
+## Scale
+
+- **0** Placeholder. Default primitives, sparse world, unreadable state, or no evidence.
+- **1** Basic styled. Playable and themed, still obvious prototype assets or flat composition.
+- **2** Premium stylized. Authored silhouettes, real material/detail systems, readable state.
+- **3** Showcase. Strong direction, memorable hero and world, dense authored detail.
+
+## Categories
+
+| # | Category | 0 | 2 | 3 | Backed by |
+|---|---|---|---|---|---|
+| 1 | Art direction | no theme | theme reaches forms, materials, UI, feedback | one identity visible on every surface | — |
+| 2 | Hero / player | default body, untouched | authored silhouette, state cues | memorable, expressive | — |
+| 3 | Props & interactables | primitives | two+ authored forms with idle/active states | desirable and clearly valued in motion | ⛔ `composition.primitive-dominant` |
+| 4 | World / environment | flat plane, empty arena | layered kit with fore/mid/background and scale cues | dense authored world that aids readability | ⛔ `composition.no-loaded-models` |
+| 5 | Materials | flat colors | shared material roles, wear, trim, real maps | cohesive material language, measured texture cost | ⛔ `materials.default-plastic` |
+| 6 | Lighting & render | default lights, or unreadable dark | tone mapping, exposure, key/fill/rim, contact | cinematic but readable, disciplined post | ⛔ `lighting.ambient-only`, `lighting.unmotivated`, `render.tonemapping` |
+| 7 | Audio | silent | every interaction has a cue; ambience present | mixed, prioritised, spatially placed | ⛔ `audio.silent-interaction`, `audio.no-ambience` |
+| 8 | VFX & motion | none, or random particles | event-driven: pickup, hit, fail, spawn | clarifies gameplay, stays performant | — |
+| 9 | HUD | debug text, or under the shell chrome | genre-specific states, readable at mobile size | cohesive interface with real hierarchy | — |
+| 10 | Performance evidence | none after visual changes | renderer counters + desktop and mobile screenshots | baseline/post numbers, named bottleneck, budgets | — |
+
+Row 10's level 1 is *"seems fine"*. If that is what you have, write **1**.
+
+The craft rows 4–6 grade — layering with scale cues, material roles/wear/trim, authored contrast —
+is taught in `read_doc({ name: "world-look" })`; scoring low there is a pointer to that page, not to
+more post-processing.
+
+## Automatic failures
+
+Any one of these blocks a premium claim, regardless of the average. The first five are
+detected by script and are not negotiable; the rest you assess from the screenshot.
+
+- ⛔ The active screenshot is primitive-dominant, or contains zero loaded models.
+- ⛔ Authored surfaces are default white `MeshStandardMaterial`.
+- ⛔ Lighting is ambient-only, or a local light floats unattached to an emitter.
+- ⛔ `renderer.toneMapping` is unset, or there is no environment map.
+  *(Both lighting rows are lane-aware: a runtime-lit world — it calls `createVisualRuntime` and
+  authors `public/helix.visuals.json` — satisfies ambient-only / tone mapping / environment by
+  construction, because the visual runtime owns all three. The unattached-local-light rule
+  applies on both lanes.)*
+- ⛔ An interaction has no sound, or a declared cue ships no file.
+- The world is mostly stretched boxes, flat planes, or a sparse arena.
+- One repeated silhouette does duty for every prop or every enemy.
+- Fog, darkness, bloom or particles are hiding missing geometry rather than adding mood.
+- The HUD overlaps the play area, clips text, or sits under the shell's top-center chrome.
+- No active-play screenshot was captured, or the world was never driven by real input.
+
+## Report format
+
+```text
+Visual scorecard — <world>
+1  Art direction        before X / after Y   evidence:
+2  Hero / player        …
+3  Props                …
+4  World                …
+5  Materials            …
+6  Lighting & render    …
+7  Audio                …
+8  VFX & motion         …
+9  HUD                  …
+10 Performance evidence …
+Average (advisory):
+Automatic failures remaining:  <list, or none>
+Scripted gates:  world-audit exit N · source-audit exit N
+```
+
+If a category is below 2, name the exact next pass instead of declaring completion.