@funpixel/tools 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,67 @@
+# The review rubric
+
+Seven axes and an overall, scored 1 to 10 per surface (phone and desktop apart), one decimal
+allowed: the calibrated panel's axes, so an in-loop verdict
+and the milestone panel use the same fields. Revised presentation anchors require fresh
+comparative calibration; historical numbers are context, not a demonstrated equivalent scale. The declared style is the standard: a flat two-colour
+puzzle can earn an 8. Scores describe what is visible in a frame; frame rate is never part of one.
+
+| Score | Means |
+|---|---|
+| 5 | substantial visible gaps |
+| 6 | mostly coherent with noticeable gaps |
+| 7 | coherent and readable with minor gaps |
+| 8 | strong execution of the declared style |
+| 9–10 | exceptional execution in the supplied evidence |
+
+| Axis | The question |
+|---|---|
+| `lookAndFeel` | One world from title to end card? Art direction, coherence, coherent assets, readable state changes |
+| `readability` | Can you read the state of play at a glance: you, the threats, what just happened? |
+| `intuitiveness` | Would a new player know what to do and why? |
+| `juice` | Do impacts, feedback and payoffs land? |
+| `fun` | Does the loop offer decisions, as far as the frames show it? |
+| `mobile` | Not its own rubric: the seat's overall on the phone shots, the same axes re-read for a hand (thumbs, safe areas, text at arm's length, the orientation it is held in). Touch controls are never clutter for being there |
+| `hud` | HUD and UI placement, clutter, overlaps, one system |
+| `overall` | The critic's own verdict, not an average |
+
+The gate (BAR.md, R1): the seats' `overall` mean at least 6.0 and their `lookAndFeel` mean at
+least 7.0 on standard captures. 7.3 overall is the aim, on a curated capture set: our bar games sit
+at 6.05–6.60 overall and 7.28–7.42 look-and-feel on standard captures.
+
+Scores do not predict enjoyment, store readiness or commercial success. Use blind play for
+controls and timing, and actual player evidence for engagement.
+
+**Severity.** `high`: the game cannot be played or presented from this frame (text that does not
+read as words, a control that cannot be reached, a screen that never changes). `medium`: degraded
+but playable. `low`: polish. Measure before filing a `high`: a bounding box or a contrast ratio,
+at a stated viewport.
+
+**Before a verdict is final**, write down what would prove it wrong ("is the heart really 18 px,
+or was that the desktop frame?") and check each against the frames and measurements. Revise and
+say so.
+
+## Output
+
+```json
+{
+  "surface": "phone 390x844",
+  "persona": "UX designer",
+  "prior": [
+    { "id": "P1", "status": "fixed", "note": "hearts 28px, ink on bone" }
+  ],
+  "findings": [
+    { "id": "P3", "severity": "medium", "view": "playing", "where": ".hud-score",
+      "issue": "score digits 12px at 390 wide", "change": "clamp(18px, 5vmin, 28px)" }
+  ],
+  "scores": { "lookAndFeel": 7.3, "readability": 6.8, "intuitiveness": 6.5, "juice": 5.8, "fun": 6.2,
+    "mobile": 6.5, "hud": 6, "overall": 6.4 },
+  "bar": { "art_direction": "met", "consistency": "met", "motion": "met",
+    "juice": "missing", "fun": "met", "screens": "met", "hud": "met", "sound": "unseen", "input": "met" }
+}
+```
+The panel means are the mean of the seats' `overall` and of their `lookAndFeel`
+([bar.md](bar.md)). Ids continue across rounds so the next review can
+settle them. Return both surfaces with every score, `findings` (even when empty), and at least
+`art_direction`, `consistency`, `motion`, `juice`, `screens` in `bar`. Carry unresolved high findings
+in `findings` as well as `prior`; passing means do not cancel missing bar items or high findings.

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

@@ -0,0 +1,49 @@
+# Named test scenes
+
+`window.__FPX_VIEWS__` is the game's library of repeatable scenes. Add one whenever a state is
+slow to reach by hand — `boss-arrival`, `late-swarm`, `last-life`, the busiest moment of the
+third wave — each entered through the game's own rules and a fixed seed, so every capture,
+measurement and repair of that state starts from the same place.
+
+```js
+window.__FPX_VIEWS__ = {
+  playing: { motion: true, enter() { startRun({ seed: 7 }); } },
+  'late-swarm': { enter() { startRun({ seed: 7 }); skipToWave(9); } },
+  'boss-arrival': { moment: true, enter() { startRun({ seed: 7 }); spawnBoss(); } },
+};
+```
+
+Expose the counters that say what a scene holds in `__FPX_STATE__` (enemies alive, particles,
+pooled objects, the wave, the frame budget in use). They turn "it felt heavy" into a number the
+next change can be compared against on the same scene (skill `funpixel-game-spine`, performance).
+
+An `enter()` that does nothing is worse than no entry: the checker believes it. A staged view
+shows a state real play reaches, with numbers that agree: an end view gets there through a short
+seeded run, so its card reads that run, and `playing` and `paused` sit over a live board. Our
+generated games' staged cards read "0:00 · 0", "Score 0" over a full basket and a typed-in "1234",
+and every blind critic cited them first. Leave a screen you cannot reach directly undeclared.
+
+## Repeatable frames
+
+`funtools capture` (with `--all`, and `score --target`, `compare --target`) holds the page's clock
+from before your first line and moves it in fixed 1/60 s frames from one seed, so two captures of a
+view are the same frame and a round's before and after differ only by what the round changed. It
+needs no code; what keeps your game repeatable under it:
+
+- Seed every round from `window.__FPX_SEED__` (the starters' `rules.ts`); `--seed 7` plays another.
+- Run the loop on `requestAnimationFrame` or timers and read time from `performance.now()` or the
+  frame's timestamp. `AudioContext.currentTime`, a Worker or `new Date()` run free.
+- Let `enter()` reset what it shows: a fresh round, and the camera CUT to a named shot, never left
+  blending from the last one. Report the shot in `window.__FPX_CAMERA__()` as `{ shot }` (the 3D
+  starter's `shots.ts`).
+
+Each shot says how it was framed: "repeatable: held clock, seed 1, … camera "play"", or
+"free-running" with why (`--free-running` asks for the wall clock). `compare` names a pair that
+was not framed alike as not comparable; read only a pair framed alike as before and after.
+
+What a scene proves is limited: it reproduces a state; it says nothing about whether a player can
+reach it. Acceptance is a separate journey from the visible start through the real controls:
+`npx @funpixel/tools verify --front-door` presses the real start control, `funtools play`
+gives a blind player only the screen, and `funtools journey` keeps a path as a script that replays
+on the same seed and compares run to run ([journeys.md](journeys.md)). A staged victory is a test
+fixture, never evidence of a winnable game.

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: a Dawg Ball tour log held 321 exceptions while every screenshot looked fine, and Pocket Crew'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`; Floe Jam's `unity/build.sh test` runs Edit Mode then Play Mode (`FloeJam.PlayTests`) and reads the NUnit XML, the only project that does.
+- Build for the Simulator with the studio's `com.joydle.core` (funpixel-unity-game, `references/studio-packages.md`): `funtools unity run -- -nographics -buildTarget iOS -executeMethod Joydle.Core.Editor.BuildTools.SimulatorDev` (a development build: its dev flags and test ads work; `Simulator` is the stripped release build), 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`, `-hg-seed 7 -hg-autoplay`, and a tour flag that writes every menu to PNG), read through `LaunchArgs.Get()` behind the game's own dev gate, with `Telemetry.Muted` set while a flag is on. A launch with any flag also skips the studio splash (`-splash` forces it).
+- 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 Pocket Crew'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
+
+Pocket Crew, 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, Tiny Pip drawn as a speck, and threats under the buttons.
+
+## Common mistakes
+
+- Launching with dev flags every time. Dawg Ball's `-db-*` flags muted telemetry, so a Firebase crash path first ran when the owner launched normally.
+- A smoke that asserts only "no errors". Scrap Riot's bot failed to beat the boss for 11 minutes, then stood holding USE; the run now uses `-lgr-god`, `DebugBossHit` and a walk-to-lever script.
+- Reading screenshots and skipping the log. In Dawg Ball 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. Dead Letter's tests could not run from a fresh clone.
+- A regression test that passes on the old code, as a Dawg Ball 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), Held Note, 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. Saltwake
+(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 Saltwake 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. Held Note'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.