@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-verify/references/unity.md

@@ -0,0 +1,60 @@
+# Proving a Unity build plays
+
+This skill is the order of checks that shows a build boots, plays to a win and a loss, and logs no exception. The failure it prevents is trusting what a capture shows: one game's tour log held 321 exceptions while every screenshot looked fine, and another's first TestFlight build drew every moving platform frozen after the first level, behind 1,118 green tests. A check sees only the path it runs, so these steps run the paths players take.
+
+## Tools
+
+Not shipped by the kit: the Unity starter, its one `check` command (exit codes 0 pass, 1 fail, 2 not observed, 3 error), the checks below and the studio scripts they were learned with (`unity_check.py`, `unity_sim.sh`, `smoke_sim.sh`, `pcplay.py`, `testflight.sh`'s pre-flight, per-game smoke, remote-play and perf scripts) are proposed. Until the starter ships, run each step with what exists:
+
+- Compile and test: `dotnet build` and `dotnet test` on the engine-free core (its `CoreTests~` project; Unity ships a `dotnet` under `Contents/Resources/Scripting/DotNetSdk/`), and Unity's test runner for the rest: `funtools unity run -- -nographics -runTests -testPlatform EditMode -testResults results.xml` (the machine-wide queue: one run per project across agents; never with `-quit`: the test runner exits by itself). Play Mode tests run the same way with `-testPlatform PlayMode`; one game's `unity/build.sh test` runs Edit Mode then Play Mode and reads the NUnit XML, the only project that does.
+- Build for the Simulator with the game's own build method: `funtools unity run -- -nographics -buildTarget iOS -executeMethod Setup.BuildSimulatorDev` (a development build: its dev flags and test ads work; keep a stripped release Simulator build beside it), then `xcodebuild -project Unity-iPhone.xcodeproj -scheme Unity-iPhone -sdk iphonesimulator build`; install and launch on a Simulator of your own (`udid=$(funtools sim lease)`) with `xcrun simctl install $udid <app>` and `xcrun simctl launch --console-pty $udid <bundle id> -smoke`, never `booted` (it may be another agent's), and `funtools sim release $udid` at the end. About 5–10 minutes a round.
+- A smoke run: a dev-only launch flag in your game that plays from the title to an ending and writes `smoke.txt` to the app's Documents; read it with `xcrun simctl get_app_container $udid <bundle id> data`.
+- Dev flags: launch arguments for dev builds that jump to a state or start a bot (the games used `-autoplay -startlevel N`, `-seed 7 -autoplay`, and a tour flag that writes every menu to PNG), read natively (Mono never sees `simctl launch` arguments) behind the game's own dev gate, with telemetry muted while a flag is on.
+- Hand play from a script: `npx @funpixel/tools unity play start`, then `play tap`, `drag`, `key`, `pad`, `state`, `ui`, `shot`, `record` and `end` (the kit's `com.funpixel.probe`, lifted from one game's remote play: real Input System device state, in the game's own upright coordinates). `unity probe --path path.json` plays a scripted path and measures it; `unity capture --all` shoots every registered view (funpixel-unity-game, `references/probe.md`).
+- Screens: `funtools sim shot $udid --out shot.png`, upright in the game's orientation; `funtools sim tap $udid x y` presses a point of that picture.
+
+## Checks
+
+| Check | Passes when | Status |
+|---|---|---|
+| `compile_fast` | 0 errors | proposed (a studio script, not in the kit) |
+| `core_tests` | 0 failures, count at or above baseline, csproj tracked in git | partial |
+| `flag_free_launch` | 0 exceptions in 40–60 s with no dev flags | proposed |
+| `smoke_to_ending` | ending reached, 0 errors, average 58 fps or more excluding capture frames | partial |
+| `entry_path` | view state equals sim (rules) state in a level entered as the second or later | proposed |
+| `console_exceptions` | 0 in the player log of any tour or autoplay | partial; tours not covered |
+| `audio_runtime` | 1 AudioListener, 48 kHz, music playing within 3 s | partial |
+| `frame_budget` | first entry under 34 ms, none over 20 ms after warm-up, p99 at most 17.5 ms | `funtools unity probe` (no phone measured yet) |
+| `invisible_work` | 0 world cameras behind full-screen menus, 1 pass in play | proposed |
+| `look_leak` | `RenderSettings` and shared materials identical before and after each level and warm-up | proposed |
+
+## Procedure
+
+1. Compile (`dotnet build` on the core, or a batch-mode Unity build). Read the full output: `| tail` hid a failing compile and a commit went through.
+2. Run the core tests: in the game's `CoreTests~` folder, run `dotnet test` (the SDK inside the Unity app, `Contents/Resources/Scripting/DotNetSdk/dotnet`, if none is on the PATH). Compare the count with the baseline.
+3. Build a stripped Simulator build onto your own Simulator, with your own port and scratch folder. One agent's install on a shared Simulator killed another's remote-play session.
+4. Launch once with no dev flags for 60 s and count exceptions. Dev flags mute telemetry, so a flagged launch skips code a player runs.
+5. Run the smoke to an ending and to a loss, and assert the ending itself.
+6. Enter at least one level through Next, Continue or Restart. Audits that start every level fresh at boot miss state the previous level left behind.
+7. Run the tour and require every registered screen. Fail the tour, and any autoplay, on one exception in the player log. `Debug.Log` on iOS goes to stdout, so launch with `--console-pty`.
+8. Run `audio_runtime`. Simulator captures carry no audio.
+9. Run the remaining Runtime checks in the table; funpixel-unity-game has the detail.
+10. End every fix loop by playing: `unity play` or a `unity probe --path` script, with a measured outcome such as kicks connected or falls per hop. This is the owner's direction, "verify it yourself by playing". Thresholds for those outcomes are not in the report.
+11. Run each new regression test against the parent commit and confirm it fails there.
+12. Before upload, run the archive pre-flight (funpixel-store says what it checks; the script is proposed).
+
+A person still checks feel on a real phone and audio by ear.
+
+## Worked example
+
+A three.js port with 26 levels. Build 1 went to TestFlight behind 1,118 green tests, and every level after the first of a session drew its movers frozen: a warm-up had left the views bound to a throwaway sim. Every audit had started levels fresh at boot, so none saw it. Once fixed, the audit's frozen category went from 219 to 0. A production gate (fresh install, every level through real flows, 7 kill-and-relaunch cycles, every setting persisted) found 4 more bugs behind 1,377 green tests. Hand play through the game's remote-play server found what bots had passed: fans that looked walkable, the smallest hero drawn as a speck, and threats under the buttons.
+
+## Common mistakes
+
+- Launching with dev flags every time. One game's dev flags muted telemetry, so a Firebase crash path first ran when the owner launched normally.
+- A smoke that asserts only "no errors". One game's bot failed to beat the boss for 11 minutes, then stood holding USE; the run now uses a god-mode flag, `DebugBossHit` and a walk-to-lever script.
+- Reading screenshots and skipping the log. In one game a NullReferenceException in `Hud.Pad` hung a demo match silently.
+- Trusting benches for boot. A static cache declared after the colours it used threw a TypeInitializationException and no build booted for about 7 h; which game is not in the report.
+- Hand-written `.csproj` files left ignored by git. One game's tests could not run from a fresh clone.
+- A regression test that passes on the old code, as one game's cheat test did.
+- Shipping without the audio check. All four first games reached TestFlight silent, because a camera made in code has no AudioListener (`funtools doctor` warns before the build).

package/plugins/codex/skills/funpixel-world-and-story/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: funpixel-world-and-story
+description: Use when a game should feel like a place with a story (a world to explore, an opening, characters who speak, a crowd that cheers), or its world reads empty, silent, static or aimless. Covers landmarks, kit dressing, a living world (people on task loops, creatures with gaits), atmosphere, story sized to the game and voice.
+---
+
+# World and story: a place worth being in
+
+A game can be correct and still feel like a box: a field of tiles, a goal in a sentence, nothing
+that says where you are or that anyone is watching. The acclaimed games put the story in the place.
+Pick what fits from this shelf; a tight arcade game may want none of it.
+
+## Tools
+
+- `generate_image` for key art, backdrops and vistas; `generate_sprite` and `generate_spritesheet`
+  for a kit of props and characters that move; `edit_image` for a variant (a lit and an unlit
+  lamp) so one kit tells a before and after.
+- `generate_skybox` for a 3D sky; `find_material` and `get_material` for free Poly Haven HDRIs,
+  textures and models; `generate_3d_model` for a hero prop or character; `build_level` when the
+  place is an interior or a set with a plan (skill `funpixel-3d`).
+- `generate_music` and `generate_sound` for the place's sound (skill `funpixel-audio`).
+- `capture_view` and `audit_screens` to see each beat at phone size; locally `capture`, `play`
+  (a blind player: ask it its goal), `profile`, `life` (ambient life) and `depth` (story beats
+  seen in play), all `npx @funpixel/tools`.
+
+## What the hits do
+
+- **Hollow Knight**: the world is the story. Ruins and inscriptions explain a fallen kingdom
+  without a cutscene; each area owns a colour, a sound and a silhouette. Landmarks you glimpse
+  early you reach late.
+- **Hades**: story rides the loop. Every death returns you home where characters remark on what
+  just happened, so losing is content. Text is short and voiced.
+- **Celeste**: each chapter is one place, one new mechanic and one feeling,
+  bracketed by a short scene. Postcards between chapters say what it is about.
+- **Silt & Signal** (Crayon, our web reference): a one-line promise on the title, a voiced beat
+  before control, then a chapter card and a goal with a waypoint; 7 chapters, 61 voiced lines in
+  12–15 minutes. Notes: [references/shelf.md](references/shelf.md).
+
+## Craft on the shelf
+
+1. **A place before a level.** Name the place in one line and give it one landmark the player can
+   see from most of the map (a tower, a tree, a lighthouse), two or three districts that differ in
+   colour and material, and a route the eye follows. Keep the play space readable: walkable ground
+   one value band, blocking things another, threats their own colour.
+2. **Dress from a kit, not a tile.** Six to twelve pieces in one style (rocks, bushes, flowers,
+   lamps, fences, crates) scattered by rule: dense at edges, clear on the route, a ring around
+   landmarks, jittered scale, flip and tint so repeats hide. Seeded, so it is the same place every
+   run. Code for Pixi and Three: [references/world-kit.md](references/world-kit.md).
+3. **Tell it with things.** Put two or three props per area that imply what happened (a cart on
+   its side by a broken bridge, dark lamps along a road with one lit). Change something the player
+   can see when they act: the lamp lights, the bridge mends, the music opens up.
+4. **Author the opening.** Title (name, one-line promise, one button) → a beat of a few seconds
+   that shows the world and the want (a pan, one or two lines, skippable) → the first control,
+   taught by the space → the first objective in words with a waypoint and a distance → a first
+   payoff inside a minute. Recipes: [references/opening-and-chapters.md](references/opening-and-chapters.md).
+5. **Chapters and objectives as data.** A chapter is a place plus one new idea; an objective has
+   words, a target and a done-test. The HUD shows the chapter and the current goal; the world
+   answers when one completes. Save progress with `@funpixel/sdk/save`. Many rooms:
+   `npx @funpixel/tools world forge --seed N` drafts them as data from `## Places` and the kit
+   (doors, a critical path, a light per room); `world check` proves each door and goal is reached:
+   [references/forged-world.md](references/forged-world.md).
+6. **Story at the game's size.** An opening beat, a goal said by a person, chapters whose lines
+   change as you go, an ending that changes the world; about 30–60 short lines for the 15 minutes a game plays at least,
+   or "declined" on purpose for an arcade round. One line at a time, clear of the controls.
+   Sizes, lines as data and the GDD's `## Story` table: [references/story-at-size.md](references/story-at-size.md).
+   Voice: the platform's `cast_voice` + `voice_line` (a story game's default offer, priced), a
+   voice in code, a murmur, or the creator's own text-to-speech: [references/voice.md](references/voice.md).
+7. **One set-piece.** Plant it early (a sealed door, a dark tower), pay it off with camera, light,
+   sound and a change the player keeps seeing. Lighting and effects: skill `funpixel-art`; music
+   that turns with it: skill `funpixel-audio`.
+8. **A living, made world.** Each person animates, walks a task loop, idles and answers the
+   player; a crowd is a few focused scenes along the path, never the hero's face; creatures have
+   gaits, flyers flap; a painted cut-out animates too, never a picture slid. What the camera
+   passes is built from the first look's kit, never a flat box, and stands on the ground:
+   [references/living-world.md](references/living-world.md). A world that notices:
+   [references/atmosphere.md](references/atmosphere.md). `npx @funpixel/tools check` (or `life`,
+   `walk`, `boxes`) shows what slides, clumps, floats or reads unfinished.
+9. **See it as a player would.** Capture title, beat and first goal at phone size; ask the blind
+   player its goal; profile the dressed view.
+
+## Worked example
+
+Brief: "a small valley at dusk, bring light back to it". Lantern Vale: a tower on the ridge, a
+road, lamps. In the lab a seeded `scatter` dressed a phone view with about 280 pieces, the road
+clear, a ring round the tower, in 3 draw calls. The opening: title
+"The Last Light / Every lamp in the valley went out but one", a pan under two lines from Ada, then
+`01 / THE LAST LIGHT` over "Reach the tower at the top of the valley" with an edge arrow reading 113 m.
+
+
+## Common mistakes
+
+- Scattering uniformly: repeats line up and the route disappears into clutter.
+- A goal only in text: players look for the thing on screen; give it a marker and a distance.
+- A cutscene before any control that runs long or cannot be skipped; keep the first beat short.
+- Story in a wall of text; one line at a time, and let the place say the rest.
+- A landmark that is never reached, or a world change the player never sees.
+- A strange number never explained. Voices placed by room and deed, cards that name what happened:
+  [references/opening-and-chapters.md](references/opening-and-chapters.md#a-radio-placed-rather-than-narrated).
+
+Where this comes from: the hits (research 18), Crayon's GDD (research 19), our own games, our lab.

package/plugins/codex/skills/funpixel-world-and-story/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "funpixel-world-and-story"
+  short_description: "a game should feel like a place with a story (a world to explore, an opening, characters who speak, a crowd that cheers)"
+policy:
+  allow_implicit_invocation: true
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

package/plugins/codex/skills/funpixel-world-and-story/references/atmosphere.md

@@ -0,0 +1,208 @@
+# Atmosphere: a world that notices the player
+
+A place feels alive when things in it move on their own and answer what the player does. Our
+racer (29 Sep) played well and still read as "a game of shapes": no one in the stands, nothing
+at the trackside, no moment at the finish. The owner's words: "environment and crowd cheers were
+missing". This page is a shelf of patterns per genre and the cheap code under them. Pick what the
+brief wants; a puzzle in an empty white room may want none of it, on purpose.
+
+## Three layers
+
+| Layer | What it is | Cheap build |
+|---|---|---|
+| Ambient life | things that move without the player: flags, birds, passers-by, a crowd shuffling, weather | instanced cards or impostors on a slow sine; a few particles; two or three looping sprites |
+| A bed | one quiet loop that says where you are: a crowd murmur, rain, a city hum, a room tone | one `generate_sound` with `loop: true`, 20–30 s, played under the music |
+| Reactions | the place answering a moment: a roar, a gasp, lights, a camera flash, a line from someone | the bed swells or hushes, a sting plays, the cards jump, one line of text or voice |
+
+Reactions carry the most for the least. A crowd that stands still but roars when you overtake reads
+as alive; a crowd that waves forever and never notices you reads as wallpaper.
+
+## Per genre
+
+| Genre | Ambient life | Bed | Reactions to the player |
+|---|---|---|---|
+| Racing | grandstands at the start, the finish and one bend; flags and banners on the fences; marshals; a blimp or birds overhead | crowd murmur by the stands, wind at speed | the roar swells as you pass a stand (by distance); a hush at the countdown, then a cheer on GO; a gasp on a crash; a cheer on a boost or an overtake; an announcer line at the start and the last lap; confetti, flashbulbs and fireworks at the line; rivals with a name, a colour and a one-line taunt |
+| Arena, sports | the crowd around the whole field, stadium light, a scoreboard | the stadium's roar, a chant loop | the crowd as a scoreboard of feeling: rises with a rally, groans at a miss, erupts on a goal; a chant after a streak; a replay of the best moment |
+| Theatre, stage | an audience in rows, stage light, a curtain | murmur before, silence during | laughs, gasps and applause timed to the act; a curtain call with the house on its feet; coughs in a flat patch tell the player they are losing the room |
+| City, adventure | passers-by on the pavement, traffic, birds on wires, laundry in the wind, lights switching on at dusk | traffic, voices, gulls, rain | people turn to look at a stunt, a shopkeeper calls out, a crowd gathers at a set piece; a street lights up when you fix it |
+| Horror | almost nothing, and that is the point | a low room tone and long silences | absence as atmosphere: distant sounds with long, uneven gaps; the bed drops out a beat before a threat speaks; one sound close behind the player |
+| Nature, journey | grass and trees in wind, herds, fish, fireflies at night | wind, water, birdsong by time of day | animals scatter or follow; a herd runs beside the player; birds lift when you land |
+| Puzzle, cosy | one companion or small creature, a window with weather | a soft room or garden loop | the companion looks at the piece you hold, cheers a clear, sighs at an undo |
+
+## A crowd that reacts (Three)
+
+Spectators as camera-facing cards in one `InstancedMesh`: a few hundred people in one draw call.
+Four poses on one sheet (generated with `generate_spritesheet`, or flat colour silhouettes), a
+per-person phase so they never bob in step, and an `excite` level every event can raise.
+
+```ts
+import * as THREE from 'three';
+
+/** A stand of people: one instanced quad per person, facing the camera, bobbing by excitement. */
+export class Crowd {
+  mesh: THREE.InstancedMesh;
+  excitement = 0.1;            // 0 idle … 1 on their feet; decays back to `idle`
+  idle = 0.1;
+  private base: THREE.Vector3[] = [];
+  private phase: number[] = [];
+  private m = new THREE.Matrix4(); private q = new THREE.Quaternion(); private s = new THREE.Vector3(1, 1, 1); private v = new THREE.Vector3();
+  constructor(sheet: THREE.Texture, rows: number, perRow: number, origin: THREE.Vector3, rowStep = new THREE.Vector3(0, 0.6, -0.9), seatStep = new THREE.Vector3(0.7, 0, 0)) {
+    const geo = new THREE.PlaneGeometry(0.6, 1.1);
+    geo.translate(0, 0.55, 0);                              // feet on the seat
+    const mat = new THREE.MeshBasicMaterial({ map: sheet, transparent: true, alphaTest: 0.5 });
+    this.mesh = new THREE.InstancedMesh(geo, mat, rows * perRow);
+    this.mesh.name = 'crowd';
+    const colors = [0xe85d4a, 0x3d7bd9, 0xf2c94c, 0x5cb85c, 0xf5f0e6];
+    let i = 0;
+    for (let r = 0; r < rows; r++) for (let c = 0; c < perRow; c++, i++) {
+      this.base.push(origin.clone().addScaledVector(rowStep, r).addScaledVector(seatStep, c + (r % 2) * 0.35));
+      this.phase.push(Math.random() * Math.PI * 2);
+      this.mesh.setColorAt(i, new THREE.Color(colors[(i * 7) % colors.length]));
+    }
+  }
+  /** Raise the crowd (a pass, a goal, the finish). Takes the higher of now and `level`. */
+  excite(level: number) { this.excitement = Math.max(this.excitement, level); }
+  update(t: number, dt: number, camera: THREE.Camera) {
+    this.excitement += (this.idle - this.excitement) * Math.min(1, dt * 0.8);   // settles over ~2 s
+    const hop = 0.02 + this.excitement * 0.35, rate = 2 + this.excitement * 8;
+    for (let i = 0; i < this.base.length; i++) {
+      const p = this.base[i];
+      const y = Math.max(0, Math.sin(t * rate + this.phase[i])) * hop;
+      this.q.copy(camera.quaternion);                         // billboard: face the camera
+      this.m.compose(this.v.set(p.x, p.y + y, p.z), this.q, this.s);
+      this.mesh.setMatrixAt(i, this.m);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+}
+```
+
+With a sheet of poses, pick the frame per person by offsetting UVs in a small `onBeforeCompile`, or
+build two meshes (sitting, arms up) and swap visibility above an excitement of 0.6. Far stands can
+be a single textured strip with a vertex wobble; only the near ones need people.
+
+Flags and banners: a plane with 8×2 segments whose vertices move by `sin(x * 3 + t * 6) * x * 0.1`
+each frame, or a sprite sheet of four frames. One colour per team or rival reads at phone size.
+
+## A crowd that reacts (Pixi)
+
+```ts
+import { Container, Sprite, Texture } from 'pixi.js';
+
+/** A row of spectators behind the track: sprites with their own phase, hopping by excitement. */
+export function crowdRow(textures: Texture[], count: number, width: number, baseY: number) {
+  const row = new Container({ label: 'crowd' });
+  const people = Array.from({ length: count }, (_, i) => {
+    const s = new Sprite(textures[i % textures.length]);
+    s.anchor.set(0.5, 1); s.x = (i + 0.5) * (width / count); s.y = baseY;
+    s.tint = [0xffffff, 0xffd9c2, 0xc2d9ff, 0xfff0a0][(i * 5) % 4];
+    row.addChild(s);
+    return { s, phase: Math.random() * Math.PI * 2 };
+  });
+  let excitement = 0.1;
+  return {
+    row,
+    excite(level: number) { excitement = Math.max(excitement, level); },
+    update(t: number, dt: number) {
+      excitement += (0.1 - excitement) * Math.min(1, dt * 0.8);
+      for (const p of people) p.s.y = baseY - Math.max(0, Math.sin(t * (2 + excitement * 8) + p.phase)) * (1 + excitement * 14);
+    },
+  };
+}
+```
+
+## One bed, swelled and ducked (Web Audio)
+
+One looped crowd bed plus a handful of stings covers a whole race. The bed's gain is the crowd's
+mood: it follows the nearest stand by distance, drops for the countdown, and jumps on a moment.
+Stings duck the music a little so they are heard.
+
+```ts
+/** The crowd's sound: a looped bed whose level follows events, and stings over it. */
+export class CrowdSound {
+  private bed: GainNode; private src?: AudioBufferSourceNode;
+  private level = 0.25; private target = 0.25;
+  constructor(private ctx: AudioContext, private out: AudioNode, private music?: GainNode) {
+    this.bed = ctx.createGain(); this.bed.gain.value = 0; this.bed.connect(out);
+  }
+  start(bedBuffer: AudioBuffer) {
+    this.src = this.ctx.createBufferSource();
+    this.src.buffer = bedBuffer; this.src.loop = true; this.src.connect(this.bed); this.src.start();
+  }
+  /** 0 silent … 1 roaring. Eases there over `secs`. */
+  set(level: number, secs = 0.8) {
+    this.target = level;
+    this.bed.gain.setTargetAtTime(level, this.ctx.currentTime, secs / 3);
+  }
+  /** A burst above the current level that falls back (a pass, a boost, a goal). */
+  swell(peak = 0.9, holdSecs = 1.2) {
+    const t = this.ctx.currentTime, g = this.bed.gain;
+    g.cancelScheduledValues(t); g.setTargetAtTime(peak, t, 0.08); g.setTargetAtTime(this.target, t + holdSecs, 0.6);
+  }
+  /** The hush before a start: the bed nearly out, then back with a cheer on GO. */
+  hush(secs = 0.6) { this.set(0.05, secs); }
+  /** A one-shot over the bed; the music dips under it and comes back. */
+  sting(buffer: AudioBuffer, gain = 1) {
+    const s = this.ctx.createBufferSource(), g = this.ctx.createGain();
+    s.buffer = buffer; g.gain.value = gain; s.connect(g).connect(this.out); s.start();
+    if (this.music) {
+      const t = this.ctx.currentTime, m = this.music.gain, was = m.value;
+      m.cancelScheduledValues(t); m.setTargetAtTime(was * 0.5, t, 0.05); m.setTargetAtTime(was, t + buffer.duration * 0.8, 0.4);
+    }
+  }
+}
+
+// Wiring for a race (numbers are a start, tune by ear):
+// each frame:  crowdSound.set(0.2 + 0.6 * Math.max(0, 1 - distToNearestStand / 40), 0.4);
+// countdown:   crowdSound.hush(); on GO: crowdSound.swell(1, 1.5); crowd.excite(1);
+// overtake:    crowdSound.swell(0.85); crowd.excite(0.7); __FPX_MOMENT__?.('overtake', 2);
+// crash:       crowdSound.sting(gasp); crowd.excite(0.5);
+// finish:      crowdSound.swell(1, 3); crowdSound.sting(finishCheer); crowd.excite(1); confetti();
+```
+
+Sounds to make with `generate_sound` (2 credits each): "a large stadium crowd murmuring, distant,
+steady, no announcer" with `loop: true`; "a crowd cheer rising and falling, 2 seconds"; "a crowd
+gasp, short"; "a crowd roar with whistles and applause, 4 seconds"; for horror, "a distant metal
+door creak in a large empty building". Keep the prompts free of words the model reads as music.
+The audio skill (`funpixel-audio`) has the mastering, loudness and loop rules; its adaptive-music
+reference has the duck and the stinger on the bar line.
+
+## The finish, the goal, the curtain: a set piece
+
+The end of a race or a round is the moment players remember, so stage it like the title:
+
+1. Slow the world for a beat (time scale 0.3 for 0.4 s) as the line is crossed.
+2. The crowd at its loudest, a sting, the stand on its feet.
+3. Light: flashbulbs (small white sprites flickering at random in the stands for 1.5 s), a burst of
+   confetti in the team colours, fireworks at night (particles: skill `funpixel-art`).
+4. Someone says something: the announcer ("And it's the blue boat by a nose!"), a rival's line, the
+   coach. One line, on screen and voiced if you have voice (see [voice.md](voice.md)).
+5. Then the result card over the still-cheering world, not over a black screen.
+
+Record the moment for the looks: `window.__FPX_MOMENT__?.('finish', 3)` at the instant the crowd
+erupts, and declare the view `moment: true` so capture shoots it as a burst.
+
+## Horror: absence as atmosphere
+
+Horror inverts the pattern: the world reacts by going quiet. Keep the bed low and let it drop out
+entirely about a second before a threat appears, so the silence is the warning. Space distant
+sounds unevenly (8–25 s apart, never on a timer the player can learn), pan them, and put one
+sound close and behind at the worst moment. One horror game's hum rising under the last recorder line is
+the model: the world answers the story, not the player's score.
+
+## Budget and cost
+
+- A stand of 400 instanced cards: one draw call; the per-frame matrix loop is under 0.2 ms on a
+  phone for that count. Past a few thousand people, move the bob into the vertex shader.
+- Update far crowds at half rate, and hide them when the camera is past them.
+- One bed and four stings is about 10 credits of sound for a whole game.
+- Check it with `npx @funpixel/tools profile --views <race>` before and after the crowd.
+
+## Hooks so a mirror can see it
+
+- Name the nodes (`crowd`, `flag`, `bird`, `passerby`): `funtools life` counts what moves that is
+  not the player, whether a bed loops, and whether anything answered your moment marks. It warns
+  when a great moment passes with nothing reacting; it never blocks.
+- Expose the mood in `__FPX_STATE__` (`crowd: 0.85`) so a play log shows the swell.
+- Declare the set piece as a view with `moment: true`.
+- The blind player and the experience seats score "world"; ask them what the place felt like.

package/plugins/codex/skills/funpixel-world-and-story/references/forged-world.md

@@ -0,0 +1,79 @@
+# A world forged as data
+
+For a game with several rooms or areas: a dungeon, a valley of districts, a run of chapters. One
+arena needs none of this. `world forge` drafts the place as data the game loads; it is a first
+draft you reshape, never an engine that owns the game, and it only uses the prop kinds the game
+names (or plain roles), so two games forged from two briefs do not look alike.
+
+## 1. Declare what the place is made of
+
+The forger reads the design document (or `--from brief.json`):
+
+- `## Places`: one row per chapter. The first column names it; a `Landmark` column gives the
+  thing each chapter is seen by.
+- `**Kit:** pine (cover), boulder (cover), lamp (light), bell tower (landmark), fern` — the
+  game's own kinds, each with a role. `cover` blocks and shelters, `landmark` is seen from afar
+  and blocks, `light` is a light source, `dressing` never collides, `marker` points the way. A
+  kind with no role is dressing.
+- `**Palette:** #1b2a4a, #e8b04a` — the first colour sets the fog, the second the sky.
+
+A JSON brief says the same: `{ "kind": "3d", "rooms": 8, "chapters": [{ "name": "Low Road",
+"landmark": "the bell tower" }], "props": ["fern", { "kind": "lamp", "role": "light" }],
+"palette": ["#1b2a4a"], "shapes": ["basin"], "step": 0.5 }`.
+
+## 2. Forge, and compare seeds before you keep one
+
+```
+npx @funpixel/tools world forge --seed 7            # 2D or 3D from funpixel.json; --kind to choose
+npx @funpixel/tools world forge --variety 8 --seed 1 # eight seeds side by side, nothing written
+```
+
+The same seed and brief give the same file. Each seed draws its own grammar: which room shapes the
+world leans on (halls, pillars, caves, crosses, split rooms, rings; or rolling, terraced, basin,
+ridge, plateau, dune ground in 3D), how dense, how branchy, how many loops, how far the light turns
+between chapters. `--variety` scores how far apart the seeds are and names near-twins; pick the
+seed that fits the game, not the first one.
+
+## 3. Reshape it, then check it
+
+Edit tiles, move props, rename rooms. A file changed by hand is kept: forge refuses to write over
+it without `--force`. After every edit, `npx @funpixel/tools world check`: every door is a door on
+both sides, each room's doors, goal and places are reached from its arrival (3D: no rise between
+cells over `movement.step`, solid props closed), every room is reached through the doors, and the
+instance and draw-call budgets hold. Exit 1 names the room and the cell.
+
+The check proves the data. Only play proves the game reads it: build collisions from the same
+tiles and heights you draw, never a copy kept in sync by hand, then `verify` and `walk`.
+
+## 4. Load it
+
+The starter's `src/world.ts` reads it with no engine:
+
+```ts
+import { loadWorld, room, eachTile, heightAt, place, lightOf, through } from './world';
+const world = loadWorld(import.meta.glob('../design/world/**/*.json', { eager: true, import: 'default' }))!;
+let here = room(world, world.critical_path[0]);
+// Pixi: one sprite per wall tile, the arrival as the spawn
+eachTile(here, (x, y, kind) => { if (kind === 'solid') walls.addChild(wall(x * TILE, y * TILE)); });
+// Three: ground vertices from the heightfield, props from the game's own models
+const y = heightAt(here, px, pz, world.cell);
+for (const i of here.instances) spawn(i.kind, i.pos, i.rot, i.scale);
+const light = lightOf(world, here);   // fog, light, sky and ambient for this room
+// A door the player walks through
+here = through(world, here, doorId) ?? here;
+```
+
+A missing room or place warns with the names that exist and falls back (the first room, the
+arrival), so a typo never throws while loading and never drops the player at the origin.
+
+## 5. Use the places
+
+- `arrival`: where the player enters (the door they came through, or the start).
+- `goal`: the last room of the critical path.
+- `reward`: the payoff of a side or secret room; make it worth the detour.
+- `vista`: the highest spot the player can stand on in a 3D room; a camera beat or a lookout.
+- `landmark`: the chapter's landmark, for the waypoint arrow and the distance in the HUD.
+
+Each room's `atmosphere` holds only what differs from the world's: a later chapter turns the sky,
+a secret room is dimmer, the goal room warmer. The forger keeps an ambient floor; keep it when you
+tune by hand, because a black room is unreadable, not moody.