@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/robin/skills/funpixel-game-logic/references/content-at-scale.md

@@ -0,0 +1,147 @@
+# Content at scale: more levels, areas and waves without writing each one
+
+The experience bar found the same gap in every game we measured: the design claimed content that
+play never reached, because each level was hand-built and the budget ran out at two. A game that
+plays 5–15 minutes needs 8–30 distinct stretches. This page is the authoring side: content as data,
+a recipe that makes more of it, and bots that check each piece before a player sees it. How long a
+run should be and how steep the curve is live in `depth.md` and `escalation.md`.
+
+## Hand-made anchors, generated fill
+
+| Piece | Made how | Why |
+|---|---|---|
+| The first level, each chapter's opening, each set piece, the finale | by hand, as data | these teach and these are remembered; a generator's randomness costs most here |
+| The stretches between them | from a recipe with a seed, kept once they pass the checks | variety at low cost; the recipe's knobs are the difficulty |
+| Endless or daily play | the recipe live, seeded by date | replay without new writing |
+
+Keep a generated piece as a file once it passes (`levels/07.json`), rather than regenerating it on
+every load: a kept file can be named, tuned and rechecked; a live seed changes when the recipe does.
+
+## Levels as files a check can read
+
+```ts
+// levels/*.json: one file per stretch; the same shape whether a person or a recipe wrote it.
+export interface LevelFile {
+  id: string;                 // 'ch2-03'
+  chapter: number;
+  name: string;               // what the content list and the chapter card call it
+  made: 'hand' | 'recipe';
+  seed?: number;              // the recipe's seed, when made by one
+  knobs?: Record<string, number>;   // the recipe's inputs: gaps, enemies, pickups, length
+  tiles?: string[];           // side or top view rows ('#' solid, '.' air, 'S' spawn, 'E' exit)
+  waves?: Array<{ at: number; kind: string; count: number; from: string }>;
+  beat?: string;              // the story beat this level plays, if any (story-at-size.md)
+}
+```
+
+`funtools reach` reads tile levels directly (declare them in `funpixel.json` `reach`); a wave
+file is checked by the probes.
+
+## A recipe from chunks (platformer, runner, top-down rooms)
+
+Author ten to twenty small chunks by hand (a gap, a stair, a moving platform, a ledge with an enemy),
+each tagged with how hard it is and what it teaches. A level is a walk through chunks chosen by the
+seed within a difficulty band, always joined floor to floor.
+
+```ts
+export interface Chunk { id: string; rows: string[]; difficulty: number; teaches?: string }
+
+function rng(seed: number) { return () => ((seed = (seed * 1664525 + 1013904223) >>> 0) / 2 ** 32); }
+
+/** A level from chunks: `length` chunks whose difficulty rises from lo to hi, no chunk twice in a row. */
+export function fromChunks(chunks: Chunk[], seed: number, length: number, lo: number, hi: number, needs?: string): string[] {
+  const r = rng(seed), picked: Chunk[] = [];
+  for (let i = 0; i < length; i++) {
+    const want = lo + (hi - lo) * (i / Math.max(1, length - 1));
+    const fit = chunks.filter((c) => Math.abs(c.difficulty - want) <= 1 && c.id !== picked.at(-1)?.id);
+    // The chunk that teaches this level's new idea goes second, alone, before it is mixed in.
+    const teach = i === 1 && needs ? chunks.find((c) => c.teaches === needs) : undefined;
+    picked.push(teach ?? fit[Math.floor(r() * fit.length)] ?? chunks[0]);
+  }
+  const h = Math.max(...picked.map((c) => c.rows.length));
+  return Array.from({ length: h }, (_, y) => picked.map((c) => (c.rows[y - (h - c.rows.length)] ?? '.'.repeat(c.rows[0].length))).join(''));
+}
+```
+
+## A recipe from a budget (waves, arenas, rounds)
+
+Each enemy kind has a cost. A wave spends a budget that grows by a set step; a new kind debuts
+alone in a quiet wave before it is mixed with others, and every few waves is a rest.
+
+```ts
+export interface Kind { id: string; cost: number; debut: number }   // debut: the first wave it may appear in
+
+export function waves(kinds: Kind[], count: number, seed: number, start = 6, step = 3, restEvery = 5) {
+  const r = rng(seed), out: Array<{ wave: number; spawns: Record<string, number>; note: string }> = [];
+  for (let w = 1; w <= count; w++) {
+    const debut = kinds.find((k) => k.debut === w);
+    if (debut) { out.push({ wave: w, spawns: { [debut.id]: 3 }, note: 'debut: ' + debut.id + ', alone' }); continue; }
+    if (w % restEvery === 0) { out.push({ wave: w, spawns: { [kinds[0].id]: 2 }, note: 'rest' }); continue; }
+    let budget = start + step * w; const spawns: Record<string, number> = {};
+    const open = kinds.filter((k) => k.debut < w);
+    while (budget > 0 && open.length) {
+      const k = open[Math.floor(r() * open.length)];
+      if (k.cost > budget) { if (open.every((o) => o.cost > budget)) break; continue; }
+      spawns[k.id] = (spawns[k.id] ?? 0) + 1; budget -= k.cost;
+    }
+    out.push({ wave: w, spawns, note: '' });
+  }
+  return out;
+}
+```
+
+## Areas and chapters from a table
+
+For a journey or an adventure, the unit is an area: a place with a palette, a kit of props, one
+new idea and a few objectives. Write the table first; each row becomes a file and a chapter card.
+
+| Id | Name | Palette and light | New idea | Objectives | Beat |
+|---|---|---|---|---|---|
+| ch1 | The Drowned Market | noon, teal water, red awnings | jump between roofs | 3 | goal |
+| ch2 | The Wire District | dusk, cables, sodium lamps | slide along wires | 4 | ch2 |
+
+Dress each area from its kit with the seeded scatter in `funpixel-world-and-story`
+(`world-kit.md`); the table's palette row keeps the areas distinct.
+
+## Keep only what passes
+
+Every generated piece goes through the same checks before it is kept, and the recipe's seed moves
+on when one fails. Log what was rejected, so a recipe that rejects most of its output is fixed at
+the recipe.
+
+1. **Reachable**: `funtools reach` for tile levels; the solver in `__FPX_LEVELS__` for boards.
+2. **Finishable by a bot in a sane time**: the game's probes (`references/probes.md`) play each
+   level; a level the skilled bot cannot finish, or the naive bot finishes as fast as the skilled
+   one, goes back.
+3. **Different from its neighbours**: compare the chunk ids or the spawn mix with the level before;
+   two levels that share most of their parts read as one.
+4. **In the band**: its measured difficulty sits where the curve wants it (lane of `escalation.md`).
+
+```ts
+// scripts/make-levels.ts, run by the agent, not the game: keep the first seed per slot that passes.
+for (const slot of plan) {                         // plan: [{ id, chapter, lo, hi, length, needs }]
+  for (let seed = slot.seedFrom ?? 1, tries = 0; tries < 50; seed++, tries++) {
+    const tiles = fromChunks(CHUNKS, seed, slot.length, slot.lo, slot.hi, slot.needs);
+    const verdict = check(tiles);                  // reach + probe + neighbour + band, each a small function
+    if (verdict.ok) { writeLevel({ ...slot, made: 'recipe', seed, tiles }); break; }
+    rejected.push({ slot: slot.id, seed, why: verdict.why });
+  }
+}
+```
+
+## Reached in play, filled by play
+
+The GDD's content list has a `Reached in play` column. Leave it for play to fill: run the blind
+player (`funtools play --long 10`) or a journey, then `funtools depth --fill` writes what real
+play reached into that column ("4 of 12 levels (blind round 2)"), and the story table's `Seen in
+play` beside it. Expose the place in `__FPX_STATE__` (`level`, `area`, `chapter` or `wave`) so the
+play log names it. A count that play never reached is the finding, not the count on paper.
+
+## Common mistakes
+
+- Generating at load time with `Math.random()`: no two players see the same level, and none can be
+  rechecked.
+- A recipe with no teach step: the new chunk appears first mixed with three others.
+- Keeping every generated level: the checks exist to throw most of them away.
+- Thirty levels that differ only in length; change the chunk mix, the palette or the idea.
+- Counting files as content. The content list counts what a player reaches.

package/plugins/robin/skills/funpixel-game-logic/references/depth.md

@@ -0,0 +1,89 @@
+# Depth and replay
+
+What a player gets from a game over ten minutes, and what brings them back for run two. A slice made
+in one session can match a hit on feel per second; the next thing it loses on is depth. In our
+head-to-heads against the genre hits (29 Sep), the player seat chose the hit almost every time and
+said why: "a dense, escalating ten-minute score attack against a single sparse maze, a 1:38 run"
+(a maze game against Pac-Man CE DX), "the early basket is too sparse, there is no packing pressure"
+(a merge game against Suika Game), "no endless mode, no leaderboard" (an arcade game). Depth here is
+structure and numbers, not content volume, so it is within a session's reach. Everything below is an
+option with its reason; pick what serves the game and write the choice into the design note.
+
+## Run length
+
+How long one run lasts for a player who is trying. Too short and a run is a demo; too long for the
+genre and the phone gets put down mid-run. Starting targets (sourced in research 18 unless marked
+estimated):
+
+| Genre | One run | First reward | Reference |
+|---|---|---|---|
+| Arcade, maze chase | a timed score attack of 5 or 10 minutes (estimated) | an eat or a pickup within 2 s | Pac-Man CE DX |
+| Merge or drop puzzle | until the container overflows, 3–10 minutes (estimated) | a first merge within the first few drops | Suika Game |
+| Survivor, wave survival | 20 waves: 20 s, +5 s a wave to a 60 s cap, a 90 s boss, about 17 minutes | the first upgrade within 20 s | Brotato, Vampire Survivors (30 minutes) |
+| Precision platformer | a screen or room per attempt, 20–60 s (estimated); respawn in about 1 s | the first clear inside a minute | Celeste |
+| Card run, roguelike | 10–20 minutes (estimated) | a choice in the first hand | Balatro, Slay the Spire |
+| Day loop, sim | one day of about 14 minutes | the first harvest or sale inside the first day | Stardew Valley |
+| Racing | 3 laps of 30–60 s (estimated) | the first gate or overtake within 5 s | — |
+
+Measure it: the novice and skilled bots (the game-logic skill's balance section) report the run
+length they reach on fixed seeds; `npx @funpixel/tools sim` prints it with events a minute. A novice run under a minute in a genre whose target is five means
+the ramp bites too early or too hard; a skilled run that never ends means there is no ceiling.
+
+## Density: what happens per minute
+
+Count what the player causes or answers per minute from the sim's event stream, over a bot run: eats,
+merges, kills, pickups, decisions. Starting targets (estimated): an arcade chase scores something
+every second or two and asks for a turn decision every 1–2 s; a drop puzzle drops every 1–3 s and
+merges on most early drops; a survivor levels up every 20–40 s early and every minute or two later.
+Compare minute one with minute five: the fifth should be denser or different, never emptier. A long
+empty stretch (clearing the last dots of a maze, waiting for a spawn) reads as the game running out.
+
+Options that raise density without new content: more pickups of smaller value; a field that refills
+on a visible schedule; a second source of score (a combo, a chain, a train of chasers); spawns tied
+to the player's progress instead of a clock.
+
+## Pressure in the first 30 seconds
+
+The first real threat or decision arrives early, so the first minute is play, not setup. Options:
+a board that starts partly filled from the seed; a tighter container, a faster clock or an awake
+chaser from the first second; a timer visible from the start. Pressure is not difficulty: the novice
+bot still clears the first stage (the game-logic skill's 80-of-100 floor for survival games, or the
+genre's own first success).
+
+## Structures after the level
+
+A complete level is the first thing to finish; one of these turns it into a game someone replays.
+
+- **Score attack.** A fixed timer (2, 5 or 10 minutes), score as the goal, speed and multiplier
+  climbing with success, and a panic button that costs score (CE DX's bomb lowers speed and the
+  multiplier). Reason: two runs are comparable, so a stranger can try to beat the last one.
+- **Endless.** The level loops and the ramp keeps going: a wave or cycle counter that never stops,
+  one new idea every few cycles, then a ceiling where it plays as survival. Reason: the run ends on
+  the player's mistake, never on the content running out.
+- **Stages.** Three stages, each debuting one idea alone before combining it (research 18, property
+  8). Reason: the fifth minute looks unlike the first.
+- **Daily seed.** The same board for everyone that day (the seed from the date), with a share card.
+  Reason: a reason to come back tomorrow, at no content cost.
+- **One thing carried to run two.** An unlock, a starting perk, the next mode opened by the first
+  clear. Reason: losing moves something forward (Hades, Vampire Survivors).
+
+## A local best
+
+`SaveManager` from `@funpixel/sdk/save` keeps the best per mode on the device (skill `funpixel-game-spine`;
+the SDK's `leaderboard()` has no service behind it yet, so do not wire it). The results screen shows
+this run beside the best, a new best gets its own moment (its own sound and a longer hold), and a
+local table of the top five runs with dates gives a reason to try again. Expose `best` in
+`__FPX_STATE__`, and give verify a check that it rises after a finished run.
+
+## Replay hooks
+
+- Restart in under 2 s from the results screen, one tap (research 18, property 7).
+- Show the near miss: "412 short of your best", the line you almost reached (Vampire Survivors' 30
+  minutes makes falling short the reason for run two).
+- The results screen names one thing to try next (a mode, a route, an unused power).
+
+## In the design note
+
+One line under Loops: `Depth: run length <m:ss> · events per minute <n> · first pressure at <s> ·
+after the level: <score attack | endless | stages | daily seed> · best: <what is saved>`. Fill it
+from bot runs, not guesses, and update it when the ramp changes.

package/plugins/robin/skills/funpixel-game-logic/references/escalation.md

@@ -0,0 +1,41 @@
+# Escalation that changes what the player does
+
+Detail for the escalation section of the game-logic skill. Faster alone leaves the game the same,
+only harder to read. One game's review found its ramp invisible: the area indicator was computed
+and not drawn. What has worked:
+
+1. A ramp written as a list of what changes: a new enemy type, a pattern, a narrower gap, a second
+   resource, with speed riding along.
+2. One new thing at a time, first met with no threat nearby, so the player learns it before it
+   bites (adapted from Claude Code Game Studios, MIT).
+3. Intensity in waves with a rest after each peak; a run that only climbs exhausts.
+4. A ramp the player can see: a wave number, an area name, a colour shift, exposed in
+   `__FPX_STATE__` so a check can prove it moves.
+
+
+## The curve per level, and the shape each genre wants
+
+`funtools sim` splits the probe run by `level(run)` (a level, stage, wave or cup): for the naive,
+novice and skilled players, how many clear each level, how many lose there and how long they spend.
+It warns on four shapes that lost players on 30 Sep:
+
+- **Flat**: everyone clears it, nobody loses, in under 45 s (one game's first garden gave three
+  stars in 35 s). A first level may teach; a flat level mid-ramp is time with nothing to learn.
+- **A wall for people**: the skilled bot clears it only at 60 decisions a second (one racer's last
+  cup). Wrap the sharp policy in `humanRate` (12 decisions a second, 200 ms to react; a thumb makes
+  10–15) and read both: a level the twin cannot clear asks for superhuman input.
+- **Cannot be lost**: no player lost a run over minutes of play (one of our games). A puzzle or toy on purpose
+  says so; else a threat, a clock or a resource can end a run.
+- **No ramp**: the novice loses no more and takes no longer later than early.
+
+The default shape is a ramp with breathers: each step a little harder, a calmer stretch after a
+spike, the hardest near the end, and an ending worth reaching. Per genre, as offers:
+
+- **Waves (survivors-like, brawler, shooter):** the first minute safe, each wave a little denser,
+  a lighter wave after each new enemy kind, a boss as the peak; a run of 5–15 minutes.
+- **Levels (platformer, puzzle):** each idea met alone, then twisted twice, then combined with the
+  last; a short breather level when a new idea arrives; a checkpoint before each spike.
+- **Cups and races:** each cup a step up in rival pace, every cup clearable at a human rate.
+- **Board pressure (drop, merge, falling blocks):** the curve is the spawn mix and the board
+  filling, not the speed; the score attack carries the minutes.
+- **Chase (maze, stealth):** speed and aggression step per level with a short rest between.

package/plugins/robin/skills/funpixel-game-logic/references/levels.md

@@ -0,0 +1,61 @@
+# Levels a solver can check
+
+Detail for the Levels section of the game-logic skill: how to prove every level can be finished
+and how hard it is, before anyone plays it.
+
+## Data, not code paths
+
+One file or seed per level (tiles, spawn, exit, hazards). A level written as code branches cannot
+be rechecked after an edit; a level as data can be re-solved by the same function every time.
+
+## Solvable by construction
+
+Generate backwards from a solved state: start from the goal, apply reverse moves, and record the
+intended order. A board that dead-ends by chance reads as unfair, not hard. In Stitch, a test that
+inferred the order from duplicate spools failed until the generator recorded it (research 12).
+
+## Checked by a solver
+
+- A breadth-first search from the start proves the exit is reachable.
+- For platformers, every gap and ledge is within the jump's reach, computed from the `R` constants
+  for run speed, gravity and jump velocity, and every spawn stands on ground. Falling out of the
+  world respawns the player. `funtools reach` (below) measures both from the level files.
+- The solver goes in `__FPX_LEVELS__`; every other invariant is a `__FPX_SELFTEST__` entry:
+  `{ name: 'spawns stand on ground', run: () => levels.every(safeSpawn) }`.
+
+## Difficulty, measured
+
+`exposeHooks({ levels: { count, solve: (i) => ({ solvable, moves }) } })` lets verify run the solver
+over every level (engine-free, 2 s each): an unsolvable level fails, and a flat or inverted curve is
+reported. Hard levels on a rhythm (every 7th or 10th) with an easier one after each read as
+designed; hard levels at random read as noise.
+
+Density targets can be unreachable: solvable boards seal off cells, so measure the fill a generator
+actually achieves before promising one.
+
+## Reach, measured
+
+One option when levels are data: `npx @funpixel/tools reach` fills each level from its spawn and
+names every exit, pickup, checkpoint or room nothing reaches, with what is in the way. It runs
+locally and free and reads files only, so it catches a sealed room or a jump one tile too wide
+before anyone plays; how the level feels to cross is still a play test's question.
+
+- **What it reads.** `design/level.json` (the `build_level` spec) and `design/levels/*.json`, or
+  the files `funpixel.json` names in `"reach": { "levels": [...] }`. A tile level is
+  `{ "name", "view": "side" | "top", "tiles": ["#..S", ...] }`, or many under `"levels"`. The
+  default legend: `#` solid, `S` spawn, `E` exit, `*` pickup, `C` checkpoint, `^` hazard, `=`
+  one-way platform, `H` ladder; `"legend"` renames any character.
+- **The jump is the game's own.** `"reach": { "movement": { ... } }` gives `jump_height` and
+  `jump_distance` in level units, or `gravity` with `jump_velocity` and `run_speed`; any value can
+  name a rules constant (`"jump_height": "JUMP_H"`, read from `src/sim/rules.ts`) so the check and
+  the game share one number. `air_jumps`, `dash`, `step`, `size` and `unit` (movement units per tile)
+  are optional; `"jump": false` says there is none. Nothing is guessed: a side view with no movement
+  reports "not observed".
+- **What it says.** Each unreached target comes with its gap: the tiles or metres on either side,
+  how far across and how high, and what the jump clears at that rise; or "something solid is in
+  the way" when the jump is long enough on paper; or, in 3D, a wall with no opening the body fits.
+  A gap within a hair of the limit is reported too: a perfect-takeoff jump reads as a miss.
+- **Places meant to be seen, not entered** (a vault behind glass) go in `"reach": { "sealed": [...] }`.
+- Exit 0 all reached, 1 something unreachable, 2 not observed (no level data, no spawn, no
+  movement for a side view); the record is `.funtools/reach.json`. Props are not read; the 3D
+  bench's collider audit already names one that blocks a door.

package/plugins/robin/skills/funpixel-game-logic/references/probes.md

@@ -0,0 +1,122 @@
+# Probes: bots on your own rules
+
+A playtest finds a degenerate line late, after art and juice are built around it. A probe finds it
+in seconds: five simple players over 100 seeds each, on the engine-free rules, with no browser.
+Each is an option with its reason; none is a gate. `npx @funpixel/tools sim` runs
+`test/probes.ts` and reads what it prints. A `funtools init` game has both files: `src/probe-kit.ts`
+(`cohort`, `stageMoment`, `replayTo`, `timeline`) and `test/probes.ts` wired to the demo round.
+
+**The rules and their probe are one piece.** When you replace the demo's rules, rewrite
+`test/probes.ts` in the same step: its game (`newRun`, `step`, `outcome`, `progress`, and `level`
+when the game has levels) and its five players. Of eight GDK games only one had a probe that ran
+on its own rules; the others measured nothing, or the demo. Set the seconds per run past the length
+the game means to have, so a good run can end on its own.
+
+## The five players, and what each one caught
+
+| Role | Plays | Finds | Where it came from |
+|---|---|---|---|
+| `idle` | never presses | standing still wins, or waves clear themselves | one arcade game: the blind phone player idled ~12 s reading the screen and wave 3 cleared itself; `idle-probe.ts` then measured it on 40 seeds per wave |
+| `naive` | steers straight at the nearest target, human-slow | no skill ceiling: the objective set holds no challenge | Research 19 §15 lesson 9: if a naive steer-to-marker bot clears everything, the design note says so on purpose |
+| `taught` | does exactly what the tutorial teaches, with ~0.2 s reaction | a tutorial that teaches a losing line; a mechanic that hurts the player who uses it | the same game's `core-metrics.ts`: "tap a bug, wait for the wedge to go white, slip sideways out"; it measured how often the bee was safe from its own chain and whether the chain's reward reached it |
+| `skilled` | the sharp line, fast | exploits, and whether a win is reachable at all | every bar game's balance bot |
+| `novice` | slow, hesitates, one press in five wrong, only what a player sees | onboarding: does a newcomer reach the first success? | the same game's `novice.ts`: frozen policy and policy hash, 100 fixed seeds plus 100 held out, deaths by cause |
+| `middle` (optional) | SOME of what is taught (leans and rests, never takes cover) | a difficulty cliff: half the lesson loses like none of it | one game's round 4: the careless and the careful bots, nothing between |
+
+Each player sees only what a player could see: positions, marks, the HUD, never the rules'
+private state. A policy that clones the run or simulates seconds ahead (that round's sharp bot:
+`glare()` looked 4–7 s ahead) is not a person at any rate: say so with `foresight: '<what it
+knows>'` on the policy, and sim does not count its wins as a careful player's at a human pace. Freeze the novice (its code, its seeds) before tuning, or the floor moves with
+the balance.
+
+## What `sim` reports
+
+- **warn**: standing still wins or gets half as far as the sharp bot; the taught line does worse
+  than the naive one, or wins under half its seeds when the sharp bot wins (r4: 4/20 is not "the
+  lesson pays"); only a policy with `foresight` wins at a human pace; the novice reaches the first success on fewer than 80 of 100 seeds (the
+  floor in the skill; name your own first success in `ProbeGame.firstSuccess`); a `broken()` check
+  failed (NaN, off the map, inside a wall), with the seed and time to replay.
+- **note**: no skill ceiling. The naive player wins as often, and as fast, as the sharp one; or
+  wins as often and skill shows only as time. Fine for a toy, a relaxed game or a race against
+  the clock: say so in the design note. Otherwise give the verb something to master: a risk that
+  pays (the arcade game's chain that reaches the bee), a line to read, a combo that holds.
+- **length**: how long the sharp bot's run lasts (with its spread over seeds, and the second it
+  reached each level when `level(run)` is given) against 15 minutes (funpixel.json
+  `play_min_minutes` moves it) and the design doc's `Play length:` line. Under it is a warn: a game
+  is at least 15 minutes of real play by a first-time player; a smaller scope is a choice the
+  play-length line states "on purpose". A probe that stops runs before the bar says so instead of guessing.
+- **ending**: `ended(run)` on the game names the ending (the last content reached, an end screen; a
+  won outcome counts too), and the cohort reports `ended` (seeds) and `endedAt` (the mean second)
+  apart from losses. A skilled run that never ends warns "no ending reached in 900 s" (content that
+  loops, as one game's three mazes did); an endless score attack says "on purpose" on its line.
+- **curve** (with `level(run)`): clear rate, loss rate and time per level for each player. A flat
+  level, a wall, a run nothing loses and a missing ramp are named ([escalation.md](escalation.md)).
+  A human-rate twin of the sharp player (`humanRate(skilled, game.dt, { rest: 0 })` from `src/probe-human.ts`, 12 decisions a
+  second with 200 ms to react) shows a wall only a 60 Hz bot gets past; without one the human rate is
+  "not measured". When the design doc's content list names more areas, levels or waves than the
+  skilled bot reaches (half or fewer), that is a warn.
+- **bot broken**: the sharp bot made no progress, or a naive or idle player gets clearly further.
+- **human-win** names the policy that won at a human pace (`sharp@12hz (the sharp policy …)`), and
+  the taught policy's own count beside it when it trails.
+- **middle**: with a `middle` policy, one that loses like the naive player while the careful one wins
+  is a difficulty cliff (a note); without one, and with careless and careful far apart, it is "not
+  measured". Add one: `{ name: 'middle', role: 'middle', says: 'leans and rests, never takes cover',
+  make }` in `test/probes.ts`.
+  The bot is measured then, not the game: fix it before reading the ceiling, length or moments.
+- **depth**: for the sharp and the novice player, how long a run lasts and what happens per minute
+  (the events your `step` returns, by type), the two numbers [depth.md](depth.md) asks for. A
+  novice whose runs mostly end lost inside a minute is a note: in most genres that is a demo, not a
+  run. Count what the player causes or answers (eats, pickups, near misses, decisions) as events.
+- **not measured**: a player you did not write. It is never a pass.
+
+A game made before the probes (or whose rules moved to `src/sim/`) has no `test/probes.ts`;
+`funtools upgrade` leaves a skeleton on the game's own rules module beside it as
+`test/probes.ts.funtools-new` (it names what the rules export and marks the five places to fill).
+Copy it and fill them (vite-style imports without `.ts` resolve under `sim`): that is the whole
+wiring, and it replaces a hand-written bot script. A probe still importing the demo's names says
+so when `sim` runs it; `--timeout` gives a campaign probe more than 300 s, and anything the probe
+prints to stderr is shown.
+
+The worst case matters, not the average (one game's playtest tracked the deepest overlap and
+the longest stuck time over 240 s of AI against AI). What should not happen at all goes in `broken()`.
+
+## Stage the signature moment from the rules
+
+Critics judge stills, and a moment view that fakes its payoff shows a frame play cannot reach.
+`stageMoment(game, skilled, { seeds, at: [6, 8, 10, 12], window: 6, score })` plays each seed to
+each start time, then scores the events in the window after (the arcade game's `moment.ts`: the longest
+real chain within 6 s). `sim` prints the best seed and time. The moment view replays it through
+the rules:
+
+```ts
+const views = {
+  moment: { moment: true, enter: () => { session.run = replayTo(game, skilled, 23, 8); go('playing'); } },
+};
+```
+
+`capture` then shoots a payoff the game really reaches, and a later rules change that breaks the
+moment shows up as a lower score in `sim`, not as a stale picture.
+
+## Numbers from one arcade game (its own probes, 100 seeds unless named)
+
+- Idle: the blind phone player idled about 12 s and wave 3 cleared itself. On today's rules an
+  idle bee clears 0 of 40 seeds in every combat wave and lives 17 to 28 s (`idle-probe.ts`, 29 Sep).
+- Taught, before and after one creator session's rules change: chains the bee survived 19.1% →
+  92.5%; chains whose reward reached the bee 2.3% → 99% (`metrics-before.json`,
+  `metrics-after.json`). The tuning could not quietly make the taught line worse.
+- Novice (frozen policy): through practice and the first combat wave alive and scoring, 32 → 97 of
+  100 seeds over the same change.
+
+## Music that follows play
+
+`timeline(game, skilled, seed, seconds, 0.5, (run, events) => ({ threats: …, ...musicMix(run) }))`
+samples the game's own mix while a bot plays. Declare what each layer follows,
+`{ name: 'wave 3', follow: [{ layer: 'swarm', driver: 'threats' }], rows }`, and `sim` says whether
+the layer moved and how closely (skill `funpixel-audio`, references/adaptive-music.md).
+
+## What the rules alone cannot show
+
+Probes play the rules with no renderer and no clock a player watches, so they cannot say how long a
+tell shows on screen, whether a hit holds a readable beat, how fast control comes back or whether an
+actor changes pose by state. `funtools feel` measures those in the built page from `__FPX_STATE__`
+while a script plays the real controls (skill `funpixel-game-feel`, `references/measure.md`).

package/plugins/robin/skills/funpixel-game-logic/references/unity.md

@@ -0,0 +1,108 @@
+# Game logic in a Unity game
+
+Rules kept in plain C#, outside the engine, can be tested in seconds and played by bots thousands
+of times. That only helps when the tests and bots see what a player sees. A 3D platformer's first
+TestFlight build drew every moving platform frozen after the first level behind 1,118 green
+tests, and a ball puzzle was tuned twice against bots that aimed worse than a person, who then
+cleared level 62 in one shot.
+
+## Tools
+
+Not shipped by the kit: the Unity starter, these Code-stage checks and the studio scripts they were
+learned with (`unity_check.py` among them) are proposed. "Partial" below means a version exists in one
+studio's games, not in the kit. Until the starter ships, run what exists: `dotnet test` on an
+engine-free core (seconds, many agents at once), Unity's own test runner for the rest
+(`funtools unity run -- -nographics -runTests -testPlatform EditMode -testResults results.xml`,
+or `-testPlatform PlayMode` for tests that need a running scene, as one game's `PlayTests` assembly does,
+queued one run per project across agents, and never with `-quit`: the test runner exits by itself), and each check below as an ordinary test in your own project.
+
+| Check | Pass | Status and tool |
+|---|---|---|
+| `compile_fast` | 0 errors, about 2 s | proposed (a studio script, not in the kit); until then `dotnet build` on the core |
+| `core_tests` | 0 failures, count ≥ baseline, csproj tracked | partial: a `CoreTests~` project; count and csproj checks proposed |
+| `core_engine_free` | no `UnityEngine` in Core | partial: compiler-enforced, no lint guards the flag |
+| `determinism_lint` | 0 uses of `Math.Round`, `List.Sort`, `Mathf.*` and similar outside the JS-math shims | proposed |
+| `web_goldens` | 0 diffs against web traces | partial: one port |
+| `rules_guard` | `Rules.Mobile` with fix flags off equals `Rules.WebParity` | partial: branches |
+| `alloc_quiet` | 0 B per warm sim step | partial: an allocation test in one game |
+| `balance_gate` | every character 40–60% at every AI level, N ≥ 200 per pairing | partial: one game, one level only |
+| `difficulty_bots` | sharp bot ≥ 2 shots past onboarding; noisy bot ≥ 75% clears per section | partial: one game |
+| `softlock_bot` | 0 states with no valid action | partial: one game's level tests |
+| `economy_pacing` | time to finish in band; offline pay ≤ next purchase | partial: two games |
+| `physics_fuzz` | 0 inside-solid, tunnel, NaN or stuck | partial: one game |
+
+`Rules` flags are default-off switches in the Core for experiments and mobile fixes. The report
+defines `Rules.WebParity` and `Rules.Mobile` only through `rules_guard`.
+
+## Procedure
+
+1. Put the rules in `Scripts/Core` with an asmdef set to `noEngineReferences: true`. Unity allows
+   one Editor per project, so agents cannot run Unity tests in parallel; plain .NET tests they
+   can.
+2. Keep numbers in `Scripts/Core/Config.cs`, and each experiment as a default-off `Rules` flag so
+   it runs headless. There is no live tuning: a number changes only with a build.
+3. After each change build the core, then run its tests from the game's `CoreTests~` folder:
+   `dotnet test` (Unity ships a `dotnet` inside the Editor, under `Contents/Resources/Scripting/DotNetSdk/`,
+   if none is on the PATH).
+4. Pick how levels are made:
+
+   | Pattern | Proof | Game |
+   |---|---|---|
+   | Generated, solvable by construction | a solver test | a puzzle game: 600 levels by reverse removal, 29 tests |
+   | Generated, fitted to a bot | budgets fitted to sharp-bot shots, then capped from human play | the ball puzzle |
+   | Data from the web build | level laws as tests | every port |
+
+   Level laws are properties held as tests. The platformer's: widest gap, dock distance, player at
+   least 9% of screen height, every attack at least 0.6 s after its tell, plus a journey bot
+   that frees all crew on 5 seeds.
+5. Set difficulty with two bots and a person. A sharp bot plays like a sharp player and gives
+   the floor; a noisy bot gives the clear rate; the cap comes from a person playing. The ball
+   puzzle ended at budget = bot estimate × 0.5, capped at 10 balls (one room) and 14 (two).
+6. Gate balance at every AI level, on unseen seeds, one change at a time. Four matches per
+   pairing is ±5 points of noise, so use 200. Run the sweep before building art for a rule
+   change: a soccer game built two rounds of goal art first.
+7. Judge a power-up with paired seeds at large N. Pass: the holder's goal delta is under 0.3
+   either way (2,400 pairs, about 10 minutes, in the soccer game).
+8. Simulate the economy with offline earnings and a spend-everything bot.
+9. Hold the warm sim step at 0 B of garbage with a test: a 40-robot chain went from 4 KB to 0 B
+   (game not in the report), and one port holds 0 B over 600 frames.
+10. Fuzz physics per level: a short fuzz every run, a deep fuzz before TestFlight.
+11. Test levels the way players reach them: enter each as a second or later level through Next,
+    Continue or Restart (the check `entry_path`, proposed).
+12. Run each new regression test against the parent commit, where it must fail. A soccer-game
+    cheat test passed on the old server too.
+13. Play by hand through remote input after the bots pass. Bots miss readability: hand play in
+    the platformer found fans that looked walkable.
+14. Test the save: migration from every earlier format and corruption (the games test 12 kinds of
+    bad JSON). Unity's NUnit is old (no `Assert.Multiple`, no `Does.Contain` on an enum), so write
+    those tests for the plain .NET project or keep to the old asserts.
+15. Treat a hit you are measuring against as a reference, not a target: measure it frame by frame
+    (the owner's recording at `ffmpeg -vf fps=1`, contact sheets, a timed log) before copying a
+    number. The soccer game's ball was 40% too big and play 1.6× faster than Head Ball 2's; a taller goal
+    to match it added 15–20% goals and was rejected ("if it makes scoring too easy, don't"). A tempo
+    of 0.75 matched its 10.5 goals per 90 s.
+
+## Worked example
+
+The soccer game's balance gate (a three.js port with several characters and AI levels):
+1. A narrower pitch with ground goals looked fine at the "good" AI level.
+2. At the Alpha level it spread 33–68%.
+3. The dead end cost about 220,000 simulated matches.
+4. The gate that held: 13,200 matches, 200 per pairing, one change at a time.
+5. Final: every character at 41–56% at every AI level, inside the 40–60% pass band.
+
+## Common mistakes
+
+- Tuning against a weak bot: the ball puzzle's random-aim bot won 90–100% everywhere, and its
+  "human-style" bot left 33 balls on level 72. Two redesigns in two days.
+- Calibrating at one AI level: one head then spread 15–76% at Alpha.
+- Leaving offline pay out of the economy sim: an idle city game paid about $50K for two hours away
+  at minute 5, about the price of the whole city. Offline pay is now ≤ the next pad's cost, and
+  cost growth 1.12 gives a 162-minute city.
+- A bot that takes only legal actions: it missed food picked up with nowhere to deliver it
+  (reported with the idle game).
+- Starting every level fresh at boot: the platformer's movers drew frozen in every level after the
+  first; the audit's frozen count went 219 → 0 once fixed.
+- Skipping the physics fuzz: the platformer had 1,988 respawns inside solid geometry on 24 of 26
+  levels.
+- A test that never asserts: the soccer game's "always ends with a winner" did not.