@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-game-feel/references/recipes.md

@@ -0,0 +1,107 @@
+# Feel recipes
+
+Optional patterns for an action game. Choose the feedback the current brief needs; these examples
+do not require sound, shake or flashing in every game. Adjust the event self-test to the declared
+response, including intentional silence. Use timings for player readability, not screenshot scores.
+
+A game `funtools init` made already has all of this: `src/feel.ts` (the table and its self-test),
+`src/juice.ts` (flash, hitstop, capped shake, particles, the motion switch) and `src/sound.ts`
+(buses, mute, ducking). Change their rows and numbers; use these recipes elsewhere.
+
+Engine-free TypeScript; the renderer reads the numbers. Frame counts assume 60 fps and are turned
+into seconds once, so a 120 Hz phone feels the same.
+
+## The table as data, and its self-test
+
+The juice table in the design note and this file say the same thing. The self-test fails the moment
+the sim emits an event nobody designed an answer for.
+
+```ts
+// src/feel.ts
+export type Feel = { visual: string; sfx: string; hitstop?: number; trauma?: number; fullFlash?: boolean };
+export const FEEL: Record<string, Feel> = {
+  lit:   { visual: 'hullFlash', sfx: 'bell_tick' },
+  wreck: { visual: 'spray10', sfx: 'timber_crack', hitstop: 6, trauma: 0.3 },
+  home:  { visual: 'scorePop', sfx: 'harbour_chime' },
+  dawn:  { visual: 'sunrise', sfx: 'dawn_sting' },
+  dark:  { visual: 'lampOut', sfx: 'lamp_die', trauma: 0.45, fullFlash: true },
+};
+
+// wherever the hooks are exposed
+exposeHooks({ selftests: [{
+  name: 'juice: every event has a visual and a sound',
+  run: () => EVENT_KINDS.every((k) => FEEL[k]?.visual && FEEL[k]?.sfx),
+}] });
+```
+
+`EVENT_KINDS` is the list the sim's `step()` can return, exported beside it.
+
+## Hitstop on the bodies, not the loop
+
+```ts
+const FRAME = 1 / 60;
+function hitstop(bodies: { freeze: number }[], frames: number) {
+  for (const b of bodies) b.freeze = Math.max(b.freeze, frames * FRAME);
+}
+// in the fixed step, per body: skip its motion while frozen; input, particles and HUD still run
+if (body.freeze > 0) { body.freeze -= dt; continue; }
+```
+
+## Trauma shake with a cap
+
+```ts
+const shake = { trauma: 0, max: 24, decay: 1.8, scale: 1 }; // scale: the player's setting, 0 under reduced motion
+export const addTrauma = (t: number) => { shake.trauma = Math.min(0.6, shake.trauma + t); };
+export function shakeOffset(dt: number, time: number) {
+  shake.trauma = Math.max(0, shake.trauma - shake.decay * dt);
+  const a = shake.trauma * shake.trauma * shake.max * shake.scale;
+  return { x: a * Math.sin(time * 47.3), y: a * Math.sin(time * 61.7 + 1.3) }; // applied to the camera only
+}
+```
+
+Keep the `addTrauma(` call sites few and named in the note; each is a moment you chose.
+
+## Squash around a base scale
+
+```ts
+sprite.baseScale = 1;                       // set once, at load, from the art's fit
+function squash(s: Squashable, sx: number, sy: number, frames: number) {
+  s.squash = { sx, sy, left: frames * FRAME, total: frames * FRAME };
+}
+// each frame: ease back to 1 and multiply, never assign an absolute scale
+if (s.squash && (s.squash.left -= dt) <= 0) s.squash = undefined;
+const k = s.squash ? easeOutBack(1 - s.squash.left / s.squash.total) : 1;
+s.scale.set(s.baseScale * lerp(s.squash?.sx ?? 1, 1, k), s.baseScale * lerp(s.squash?.sy ?? 1, 1, k));
+```
+
+## Easing and smoothing
+
+```ts
+export const easeOutCubic = (t: number) => 1 - (1 - t) ** 3;
+export const easeOutBack = (t: number) => 1 + 2.7 * (t - 1) ** 3 + 1.7 * (t - 1) ** 2;
+// a follow that feels the same at 30, 60 or 120 fps
+export const follow = (v: number, target: number, sharpness: number, dt: number) =>
+  v + (target - v) * (1 - Math.exp(-sharpness * dt));
+```
+
+## A number that pops where it was earned
+
+```ts
+function popNumber(layer: Container, text: string, x: number, y: number) {
+  const n = pool.take(text);                 // pooled text, tabular digits
+  n.position.set(x, y); n.alpha = 1; n.baseScale = 1.3;
+  tween(n, { y: y - 40, baseScale: 1, alpha: 0 }, 0.6, easeOutCubic, () => pool.give(n));
+}
+```
+
+## Reduced motion
+
+```ts
+const reduce = matchMedia('(prefers-reduced-motion: reduce)');
+export const comfort = { shake: reduce.matches ? 0 : 1, fullFlash: !reduce.matches, particles: reduce.matches ? 0.5 : 1 };
+reduce.addEventListener('change', (e) => Object.assign(comfort, { shake: e.matches ? 0 : 1, fullFlash: !e.matches, particles: e.matches ? 0.5 : 1 }));
+// the settings screen writes the same object and saves it; the player's choice wins over the media query
+```
+
+Hitstop, the struck body's own flash and every sound are never behind `comfort`: they are the
+answer, not the motion.

package/plugins/codex/skills/funpixel-game-feel/references/unity.md

@@ -0,0 +1,73 @@
+# Game feel: motion, juice and haptics
+
+Feel bugs pass every test. One soccer game's sim (the engine-free rules, stepped at a fixed 60 Hz) was correct, but 1 frame in 8 advanced 0 or 2 sim ticks, so the ball stalled and then jumped all match; the owner called it trembling. This skill gives each moment a measured answer and names the effects that were built, then removed.
+
+## Tools
+
+Not in the kit: the Unity starter, coroutine tweens (a pop, a shake, eases), haptics by strength (iOS taptics through a native plugin, Android vibration effects, off with the player's setting), a frame-owner `GameDriver`, an interpolation blend with a trace flag, a near-miss tracker and the `moment_freq` check. Write those yourself:
+
+- A frame owner: one `MonoBehaviour` that reads input, steps the sim at a fixed rate (`sim.Update(dt)`), sends events to presenters and draws with `Render(alpha)`.
+- Interpolation and its trace: blend the drawn state between the last two ticks, and a dev-only launch flag that writes per-frame tick counts to a `trace.csv`.
+- A near-miss detector in the engine-free core, so bots can count it.
+- Frequency tests: bot batches in an Edit Mode test (`funtools unity run -- -nographics -runTests -testPlatform EditMode -testResults results.xml`, never with `-quit`: the test runner exits by itself), or `dotnet test` on an engine-free core, at 30 and 60 fps.
+
+No game uses DOTween (coroutine tweens do). One game's views branch aims its camera with Cinemachine 6.6 and plays its intro on Timeline; the rest drive the camera in code. Nothing checks sliding feet or loop pops.
+
+## Procedure
+
+1. Render interpolated between the last two fixed sim ticks. Check: 100% of frames with steps other than 1 are blended, and drawn-ball jerk p99 is under a threshold (value not in the report). A teleported or thrown ball blends for 0.18 s.
+2. Tie per-frame effects to sim steps, or scale them by dt (`1 - Math.Pow(0.4, dt*60)`). Check: headless runs at 60 and 120 Hz give the same end-state hash and effect counts per sim second.
+3. Buffer the main action. The soccer game's kick has a 200 ms buffer (`BufferMs`): a press arms it and the foot swings when the ball arrives.
+4. Answer each moment from the table.
+
+   | Moment | Answer | Duration |
+   |---|---|---|
+   | Button press | pop 0.18, light haptic, click | 0.22 s |
+   | Hit or smash | shake 0.08, particles, SFX pitch ±6%, medium or heavy haptic | 0.25 s shake |
+   | Pickup, coins | merged pop-ups, fly-to-counter | within 0.15 s |
+   | Callout | slam in from 1.4×; not replaced within 0.6 s | 0.6–0.8 s |
+   | Near miss | small callout, camera nudge, reaction pose, crowd ooh, haptic | 0.8 s; sound gate 600 ms |
+   | Win | 2 confetti waves, card pop, score counts up | about 1 s |
+   | Lose | "So close!" at 3 or fewer pieces left; no slow-mo | not in the report |
+   | Goal | net bulge, goal shake, the only big callout | no slow-mo |
+
+5. Map haptics by strength: a web vibration of 30 ms or more is heavy, 14 ms or more medium, else light. Throttle to 80–90 ms and merge pulses inside 120 ms into the strongest, so a light tap does not swallow a heavy one.
+6. Keep each tween's true rest scale (key it by Transform); otherwise a second pop records a mid-pop scale as the base.
+7. Draw particles from fixed pools; the pool is the budget. One 2D game: 2 quad batches, 600 particles. The soccer game: 220 sprites, 120 confetti, 14 rings in 6 batched meshes. At most 120 spawns per second, oldest recycled; ambient at most 40 live.
+8. Frequency-test every juice event with bot batches at 30 and 60 fps. The soccer game's targets: own goals at most 0.3 per match, misses and blocks 2–5 per 90 s.
+9. Keep in-match overlays minimal; do not freeze or slow play while the clock runs.
+10. Measure a camera change against the problem it is meant to fix, in frames.
+11. Honour the effects setting: shake is skipped when "Shake & flashes" is off, and the kickoff dolly (about 1/3 closer over the 1.5 s countdown) when screen effects are off.
+12. Animate by role:
+
+   | Role | How | Numbers |
+   |---|---|---|
+   | Hero | code; ports copy the web's procedural rig | pose tweens 0.22–0.4 s |
+   | Rigged cast (one game only) | Animator blend trees | transitions 0.12–0.15 s, exit time 0.9 |
+   | Crowd | vertex-animation textures, GPU instancing | 1,800 units in 18 draws |
+   | UI | coroutine tweens | defaults above |
+
+   Root motion is off everywhere: the sim owns positions.
+13. Show the owner a zoomed close-up on one asset before rolling out a style.
+14. Finish with a person playing on a phone: the soccer game's feel bugs came from the owner's TestFlight play.
+
+## Worked example
+
+A soccer game (a 3D port from three.js):
+
+1. A dev trace flag wrote `trace.csv`: at a 60 Hz sim, 1 frame in 8 (12%) advanced 0 or 2 ticks.
+2. A blend draws every frame between the last two ticks.
+3. A bot batch counted per match: OWN GOAL! 2.1 times (about 30% of goals), goal slow-mo 14 times.
+4. Own-goal detection depended on frame rate: 0.02 per match at 60 fps, 0.25 at 30 fps.
+5. The near-miss tracker's cooldown gives one moment per play; misses and blocks measured 4.2 per 90 s. Slow-mo was removed.
+
+## Common mistakes
+
+- Slow-mo on goals: fired 14 times a match, read as lag, and shipped in every TestFlight build until 1 Oct.
+- A follow camera showed both goals only 18–40% of the time; reverted to a fixed full-pitch view. With the next item, two rounds lost.
+- A camera lift for barks (a 2D game): changed 0 covered frames (2–8 of 165 either way) and added a 25–69 pt view shift; PR #11 was reverted in PR #12.
+- A sticker-border shader: a 2D mock-up style put on dogs, ball and goals before a close-up was shown. It did not transfer to 3D, broke static merging (dozens more draws), cost about 3 builds and was removed: "it was much better before". Four more decorations were reverted the same way in 24 h.
+- A 1.6 s freeze after goals read as "freezy".
+- Effects per render frame: at 120 Hz one game's bobs and sparkles ran twice as fast.
+- Concurrent pop tweens on one Transform: the cash pill grew huge (game not named).
+- "44 of 304 kicks connected" (the soccer game) is cited for this skill; its cause and fix are not in the report.

package/plugins/codex/skills/funpixel-game-logic/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: funpixel-game-logic
+description: Use when writing a game's rules, levels, scoring, escalation or balance, or when a run is too short, too easy or too thin to replay. Covers seeded engine-free logic with tests, solvable levels, balance bots and depth (endless, a local best). In Unity (rules that run in tests with no scene), follow references/unity.md.
+---
+
+# Game logic outside the renderer
+
+The rules are what players master. Threes spent 14 months on one rule; Brotato publishes its wave
+schedule; Slay the Spire shows every enemy's next move. Rules you can read, tune and play a
+thousand times in a second are where depth comes from. Kept in plain TypeScript (no engine, DOM or
+Preact), seeded and tested, they can be balanced by a bot and ported: two of our web games went
+native in about a day each, and the ports found four bugs the tests had missed (research 12).
+
+## Tools
+
+- `probe` runs the game's `__FPX_SELFTEST__` entries and its `__FPX_LEVELS__` solver on
+  Funpixel's browsers, as `npx @funpixel/tools verify` does locally: a failed invariant or an
+  unsolvable level shows as a FAIL.
+- `check_plan` flags a design note whose escalation is only speed.
+- `npm test` runs the logic's tests (`node --test test/*.test.ts` in a `funtools init` game);
+  `npx @funpixel/tools test` records the run for the Stop hook; `test --node` runs the files with
+  Node alone when npm test cannot start (a bundler missing from PATH).
+- `npx @funpixel/tools sim` plays the rules with five simple players (idle, naive, taught,
+  skilled, novice) and names standing still that wins, a missing skill ceiling and the best
+  staged moment ([references/probes.md](references/probes.md)).
+- `npx @funpixel/tools reach` fills each level kept as data (tiles or the 3D spec) from its spawn
+  with the game's own jump and names every exit, pickup or room nothing reaches, with the gap in
+  the way ([references/levels.md](references/levels.md)).
+- `npx @funpixel/tools smoke` warns when a file in `src/rules.ts`, `src/sim/`, `src/logic/` or
+  `src/rules/` imports an engine, Preact or the DOM, calls `Math.random()`, or decides a hit from
+  display objects' bounds. Each warning names a rule the renderer now owns; moving it into `src/sim/`
+  with a test is the usual answer.
+
+## One shape that works
+
+1. **`src/sim/` imports nothing visual** (no `pixi.js`, `three`, `preact` or `window`). State is plain
+   data; `step(state, input, dt)` advances it and returns events as data
+   (`{ type: 'hit', target, hp }`). The renderer and the audio read state and events and leave the
+   state alone, so a test can drive the sim with no screen.
+2. **One seeded random source, passed in.** A `Math.random()` in the sim means a daily seed stops
+   reproducing its level and a bug cannot be replayed:
+   ```ts
+   export function mulberry32(seed: number) {
+     return () => { seed |= 0; seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+       t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+   }
+   ```
+   Cosmetic randomness (particles, dust) can use `Math.random()`, since it does not shift gameplay.
+   `__FPX_STATE__()` exposes `seed`.
+3. **Rules as numbered, named constants** (`R1 jump height 3.2 tiles`, `R2 coyote 80 ms`) in
+   `src/sim/rules.ts`, listed in the design note, each proved by a test named after it
+   (`R2: a jump 70 ms after leaving a ledge still fires`). One game's rule ids let traversal tests
+   catch a ledge with 64 px of headroom (research 12); a change then moves the note, the constant and
+   the test together.
+4. **Determinism as a test.** Same seed and inputs, same state hash; a tiebreaker on every sort and a
+   fixed physics step keep it true.
+5. **Tests beside the rules, outside `src`:** `test/*.test.ts`. The platform type-checks only `src`,
+   so test imports stay out of its build.
+
+## Levels
+
+Levels kept as data (a file or seed each) can be re-solved after every edit. Generating backwards
+from a solved state makes boards solvable by construction. A breadth-first solver in
+`__FPX_LEVELS__` lets verify prove every level solvable and chart the curve. Jump reach, safe
+spawns, hard levels on a rhythm: [references/levels.md](references/levels.md). Many levels from
+hand-made anchors plus a seeded recipe the bots check: [references/content-at-scale.md](references/content-at-scale.md).
+
+## Escalation changes what the player does
+
+Faster alone leaves the game the same, only harder to read, and `check_plan` flags a ramp that is
+speed alone. One game's review found its ramp invisible: the area indicator was computed and not
+drawn. A ramp as a list of what changes, new things one at a time, waves with rests, and a ramp the
+player can see: [references/escalation.md](references/escalation.md).
+
+## Depth and replay
+
+A finished level still loses to the genre hit on depth: run length, what happens per minute,
+pressure early, and a reason for run two. [references/depth.md](references/depth.md) has run
+lengths by genre, density targets, score attack, endless, daily seeds and a local best, each as an
+option with its reason; the bots below measure them.
+
+## Balance before art
+
+A headless loop over `src/sim` plays thousands of runs in seconds, where a browser session plays
+one, so tuning from bots, a frozen novice floor, a bot that finishes the level in `npm test` (in
+one game it caught a speed change that starved a route), a blind phone player, a parameter sweep
+and a hunt for what bots never do all come cheap once the rules stand alone. Each, with its reason
+and where it came from: [references/balance.md](references/balance.md); the five probe players and
+`sim`: [references/probes.md](references/probes.md).
+
+## Worked example
+
+A sort puzzle (tap a tube, tap a target, matching colours merge):
+1. `src/sim/tubes.ts`: `type Board = number[][]`, `legalMoves(b)`, `apply(b, m)`, `isSolved(b)`.
+2. `src/sim/generate.ts`: from a solved board of `R3 = 4` colours, 40 random reverse moves from
+   `mulberry32(seed)`, rejecting boards the solver finishes in under `R5 = 6` moves.
+3. `test/tubes.test.ts`: `R1: a move onto a different colour is refused`;
+   `generate(7) twice gives the same board`; `levels 1-50 are solvable and mostly get harder`.
+4. `exposeHooks({ levels: { count: 50, solve } })`: verify solves all 50 and reports a rising curve.
+5. The renderer draws the sim's `Board` and plays a rising pitch per merge.
+
+## Common mistakes
+
+- A `Math.random()` in the sim: the daily seed no longer reproduces the level, and bugs cannot be
+  replayed.
+- Rules read from sprite positions: now the logic cannot be tested.
+- A self-test that assumes the starting state: checks run first and change it.
+- Tuning difficulty by playing it yourself five times; a bot plays thousands.
+- Tests that re-implement the rule they test; asserting the outcome of a scripted input catches more.
+
+Where this comes from: our own games (rule ids, bots, probes, solvable-by-construction; research
+12) and the hits in research 18; procedural and puzzle habits began in our platform's genre notes;
+review and escalation habits partly from Claude Code Game Studios (MIT).

package/plugins/codex/skills/funpixel-game-logic/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "funpixel-game-logic"
+  short_description: "writing a game's rules, levels, scoring, escalation or balance, or when a run is too short, too easy or too thin to repl"
+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-game-logic/references/balance.md

@@ -0,0 +1,88 @@
+# Balance before art
+
+Tuning by feel after the art is in means every change repaints something. With the rules in
+`src/sim/` and no renderer behind them, the numbers can be settled first, by bots, in seconds.
+Each practice below is an option with its reason; pick the ones the game needs and write what you
+chose into the design note.
+
+## Simulate before tuning
+
+A headless loop over `src/sim` plays thousands of runs in seconds, where a browser session plays
+one. Five of your own plays are an anecdote; a thousand bot runs are a distribution, and the worst
+case in it is usually the one a player meets.
+
+## Players beside the sharp bot
+
+A sharp bot tests exploits and mastery. It says little about a newcomer, so keep others beside it:
+
+- **A novice, for onboarding.** It reacts slowly, hesitates and misses, and uses only what a player
+  can see. Freezing its policy and seeds before tuning keeps the floor from moving with the
+  balance. For first-stage survival games, 80 of 100 fixed seeds that both survive and score is
+  the floor this kit's probes use; other genres name their own first success and deadline.
+- **An idle one, a naive one and one that does what the tutorial teaches.** They catch standing
+  still that wins, a missing skill ceiling and a tutorial that teaches a losing line
+  ([probes.md](probes.md) has each one's story and `npx @funpixel/tools sim`, which runs them).
+
+Saving the counts, the policy, the failing seeds and deaths by cause makes the next change
+comparable. Rerunning after each balance change, then on held-out seeds, shows whether the tuning
+fitted the seeds or the game. This floor is a regression check: it predicts no human success rate.
+
+## A bot that finishes the level, as a test
+
+`sim`'s probes describe and warn. A bot that plays the whole level or chapter inside `npm test`,
+and fails the suite when it no longer reaches the end, is the other half: a balance change that
+makes the level unfinishable turns the tests red at once. A `funtools init` game starts with one
+(`rules.test.ts`: `botRound` wins a round on seed 5); a longer game grows it. This is a lesson from
+one game (a 3D horror chapter, September 2026, gathered by its lane), and no
+first-try action game has tested it yet.
+
+Its chapter test (`chapter.test.ts`, "Contract H", named after the GDD's numbers) carried:
+
+- `median_bot_finishes` for each of two routes (seal every weldable door, or fight through) on five
+  seeds. The bot plays through the same intent a thumb produces, with a human reaction budget.
+- `weld_everything_bot_reaches_exit`: the route that welds everything finishes, with both welds.
+- `gas_ge_1_3x_median`: the chapter lays out at least 1.3 times the gas the worst of six bot runs
+  spends, so the shared resource has slack a real player needs.
+- `all_rooms_reach_exit_by_duct`: with every weldable door welded, every walkable cell still
+  reaches the exit, so no choice can soft-lock the chapter.
+- `same_seed_same_inputs_same_events`: a bot's intents replayed on a fresh sim give the same events
+  and state (what lets a run be replayed and filmed: skill `funpixel-game-spine`,
+  `references/replay.md`).
+
+**What it caught.** A mid-build request ("make her faster") raised walk and run from 2.5 / 4.5 to
+2.7 / 4.8 m/s, and it quietly broke the weld route: the bot rushed into extra fights, spent gas on
+them and could not afford the second weld. The finish test failed; the team settled on 2.5 / 4.5.
+Our reading: a faster hero feels like an improvement in the hand, so playing it would not have
+shown the cost (the movement table is in skill `funpixel-game-feel`, `references/contact.md`).
+
+Choices that made it useful, each an option:
+
+- **The failure message is the bot's trace** (`expect(r.done, trace.join(' | '))`), so a red test
+  says where the run stopped and what the bot was after.
+- **The tests keep one plain bot, fixed.** A keen `fighter` style that uses every weapon exists for
+  films only; changing the regression bot's policy moves the bar it checks, the same reason the
+  novice's policy is frozen above.
+- **Routes live with the level data**, with a fallback route (the gas, each objective top to bottom,
+  the exit) for a level that has none.
+
+A bot that finishes proves the level can be finished by that bot. It says nothing about whether a
+person finds the way or enjoys it; that is the blind phone player's job, below.
+
+## A blind phone player, judged apart
+
+A blind phone player tells three things apart: whether it found the goal, whether it could operate
+the controls, and whether it made progress. Expert wins do not cancel that player's confusion or
+deaths, since the expert already knows what the newcomer is missing. When the blind player
+struggles, controls, safe introductions and warning time are usually the cause; cutting every
+enemy's health hides the problem and flattens the game for everyone else.
+
+## Sweep one parameter
+
+Sweeping one parameter and writing the table (cost growth 1.10 against finish time, say) turns a
+guess into a choice: pick from the table, where the curve bends, rather than by feel.
+
+## What bots never do
+
+Bots play the game as written, so they miss a softlock only a human reaches and an offline payout
+that finishes the game overnight. Anything that accrues while the game is closed is worth a cap, or the first return
+visit ends the game.

package/plugins/codex/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/codex/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.