@funpixel/tools 0.0.0-stage → 0.1.1

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

package/plugins/cursor/skills/funpixel-game-spine/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: funpixel-game-spine
+description: Use when writing or restructuring a game's code (loop, screens, input, resize, camera, Pixi or Three) or changing an existing game, importing from @funpixel/sdk (signatures, or a type error naming an SDK symbol), or going multiplayer (co-op, versus, rooms, invite codes, a friend from their own house). Covers one loop and clock, one input path, change classes, the relay and performance (a low fps on a phone).
+---
+
+# The game's spine
+
+Great feel sits on a spine nobody notices: one clock, one input path, one screen state, so a
+changed jump number is felt the same minute on a phone and a desktop. What a weak spine does
+quietly: a game 60 times too fast, a control dead on phones, mirrored steering, a performance fix
+that deletes the art.
+
+## Tools
+
+- `build` and `preview` build on the platform; `screenshot` shows a screen at a chosen viewport.
+- Multiplayer: `publish_game` puts it where the relay is; locally `npx @funpixel/tools dev --relay`
+  and `verify --players 2`.
+- Local: `npx @funpixel/tools dev`, `doctor` (the platform's static rules, no browser), `verify`.
+
+## Layout
+
+```
+index.html          viewport meta with viewport-fit=cover; one #app element
+src/main.tsx        Preact: screens, HUD, menus (automatic JSX: a manual `import { h }` breaks the build)
+src/game.ts         startGame(): the renderer, the one loop, the __FPX_* hooks
+src/sim/            the rules, with no engine or DOM imports (skill funpixel-game-logic)
+src/input.ts        one function per player action; keys, touch and checks call it
+public/assets/      generated and optimized assets, referenced as /assets/<name>
+funpixel.json       metadata and checks
+```
+The platform builds with its own
+`tsconfig.json` and `vite.config.ts`, so edits to them and Vite plugins never reach its build; it
+bundles ESM packages, and a CDN script is a runtime fetch the build cannot see.
+
+## What holds a game together
+
+1. **One loop, one clock.** Everything advances from one `update(dt)` with dt in seconds, clamped:
+   `dt = Math.min(dt, 0.1)`. A backgrounded tab or a slow first load hands you one enormous frame.
+   Physics that must feel identical everywhere (jumps, projectiles) runs at a fixed step through an
+   accumulator. Pause on `visibilitychange`, and on `blur` clear held keys and pointers, because
+   their release events never arrive. Stepping this loop by hand replays a recorded run frame by
+   frame ([references/replay.md](references/replay.md)).
+2. **One input path.** Each action is one function. The key handler, the on-screen button (marked
+   `data-fpx-touch="<Key>"`) and `__FPX_VERBS__` all call it, so a passing check means the real
+   control works. Use `addEventListener`; assigning `onpointerdown` twice silently kills the first
+   control. Read taps on `pointerdown` and act the same frame.
+3. **One screen state.** A single `screen` value (`title`, `playing`, `paused`, `gameover`, …)
+   drives both the Preact screens and the loop, and `__FPX_STATE__()` returns it (optional feel
+   fields such as `hero`, `threats`, `dead`: skill `funpixel-game-feel`, `references/measure.md`). Each
+   `__FPX_VIEWS__` entry's `enter()` calls the same setter. Mark the title's start control
+   `data-fpx-start` (skill `funpixel-verify`).
+4. **Resize once, through the SDK.** `setupGameResize((w, h) => …)` after the renderer exists:
+   inside Funpixel the size can arrive as a Studio message, which `resizeTo: window` and a `resize`
+   listener miss, and two resizers fight. Size the canvas by CSS (`width: 100%`), not by
+   inline pixels, so fullscreen and the visual viewport cannot leave a dead band.
+5. **The camera is the last place a control can flip.** Pressing right should move the subject
+   right on screen. A failing sign lives in the camera basis or the input mapping; negating a state
+   field fixes the picture and breaks the rules and checks that read it. Recipes: [references/camera.md](references/camera.md).
+6. **Engine contracts.** Pixi and Three each have traps that build and fail silently:
+   [references/pixi.md](references/pixi.md), [references/three.md](references/three.md).
+7. **Keep the look, cut the cost**.
+   Pool what spawns, atlas sprites, instance repeats, cap the pixel ratio (2 in 2D, 1.5 in 3D):
+   each keeps what a frame shows. Judge a change on the same named scene and seed, before and after:
+   draw calls, triangles and texture memory (`npx @funpixel/tools scene --view <name>`), frame
+   p50/p95, the load size, and a capture. Headless frame times are not a phone. If only a visible cut
+   would help, report the number and let the creator choose
+   ([references/performance.md](references/performance.md)).
+
+## The SDK and multiplayer
+
+No model was trained on `@funpixel/sdk`, so a guessed name costs a build, and a guess that
+type-checks can do nothing at runtime: look it up in [references/sdk.md](references/sdk.md) or
+`node_modules/@funpixel/sdk/dist/*.d.ts`, never cast it. Pin it exactly (`"0.7.0"`). The six worth
+using: `setupGameResize` from `@funpixel/sdk` (the only root export), `AudioEngine` from
+`@funpixel/sdk/audio`, `SaveManager` from `@funpixel/sdk/save`, `initLiveParams` from
+`@funpixel/sdk/liveParams`, `safeArea` from `@funpixel/sdk/device`, and `Room`, `getGameKey`,
+`RoomError` from `@funpixel/sdk/multiplayer`. The relay is a forwarder: the first player is the
+host and owns what accumulates (`provideState`), every send echoes to its sender, the roster
+includes you, and a solo branch is what verify sees
+([references/multiplayer.md](references/multiplayer.md)).
+
+## Changing an existing game
+
+Naming the class of a change before touching code keeps it the size the person asked for (change
+classes from Claude Code Game Studios):
+
+| Class | Example | Do |
+|---|---|---|
+| Tuning | "jump higher" | Change one number; quote old and new; re-verify |
+| Tweak | "coins should magnetise" | Quote the old rule, state the new one, change one system |
+| Addition | "add a dash" | One new verb: its input, state field, check; backlog anything else |
+| New system | "add a shop" | Treat as a new slice: note, check, verify (skill `funpixel-gdd`) |
+| Refactor | "split `game.ts`" | Nothing a player sees changes: same views, run and tests before and after ([references/replay.md](references/replay.md)) |
+
+A request that crosses systems is two requests. Verify after each; green on the requested change
+is a natural place to hand back.
+
+## Worked example
+
+"The ship should drift after I let go." Class: tweak. Old rule: velocity is zero when no key is
+held; new rule: it decays by `exp(-3 * dt)`. One line in `src/sim/ship.ts`'s `step(dt)`; input,
+rendering and hooks unchanged. New check: `{ "mechanic": "ship drifts after release", "verb":
+"thrust", "field": "vx", "expect": "changed", "trace": 30 }`. Verify exits 0: stop, and hand back
+"the ship now drifts for about a second after you let go".
+
+## Common mistakes
+
+- Pixi `ticker.deltaTime` used as seconds: it is frames, so the game runs about 60 times too fast
+  or slow.
+- A second `requestAnimationFrame` loop for a menu or a network pause: two clocks, doubled speed.
+- Touch buttons that call different code from the keys: the check passes, the phone fails.
+- A camera shake written into the followed position: the follow logic and the checks read a moving
+  target. Shake a render offset.
+- Deleting shaders or post-processing because a headless run was slow.
+- Growing `game.ts` into the whole game, or `as any` over an SDK name error.
+
+Where this comes from: change classes adapted from Claude Code Game Studios (MIT;
+`THIRD_PARTY_NOTICES.md`); the rest is ours.

package/plugins/cursor/skills/funpixel-game-spine/references/camera.md

@@ -0,0 +1,94 @@
+# The camera
+
+The camera is the game's cinematographer: it decides what the player sees coming, how fast the
+world feels and where the drama lands. Choose it for the feeling you want, then make it steady.
+
+## What great cameras do
+
+- **Celeste** keeps most of its screens still: one room, framed whole, so every hazard is visible
+  before the first jump. A still camera says "this is a puzzle you can read".
+- **Hollow Knight** and most metroidvanias follow loosely, leading in the direction of travel and
+  holding still inside a dead zone, so small steps do not rock the world.
+- **Hades** uses one fixed isometric angle and composes every room for it; the camera never asks
+  the player to manage it.
+- **Mario Kart** sits low behind the kart and keeps it near the bottom of the frame, so the road
+  ahead fills the screen and the track rushes at you.
+- **Monument Valley** uses an orthographic view on purpose: without perspective, its impossible
+  geometry can connect.
+- **Vlambeer's shooters** (Nuclear Throne) are known for a camera that leans toward the aim and
+  shakes on heavy shots, with a player setting for how much, so the action feels loud without losing
+  the player.
+
+Questions worth answering in the GDD: how far ahead the player needs to see, whether the camera
+moves at all, where it goes at the big moment (a push in, a hold, a slow-down), and what it does on
+a phone held upright.
+
+## 2D follow with a dead zone and look-ahead
+
+The player roams a box in the middle of the screen; the camera moves only when they leave it, aims
+a little ahead of their motion, and eases with a time constant so it feels the same at any frame rate.
+
+```ts
+type Cam = { x: number; y: number };
+const cam: Cam = { x: 0, y: 0 };
+const box = { halfW: 0.12, halfH: 0.15 };   // fractions of the screen
+const LEAD = 80;                            // px ahead of the motion
+const EASE = 8;                             // higher follows tighter
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+function outside(delta: number, half: number) {
+  return Math.abs(delta) <= half ? 0 : delta - Math.sign(delta) * half;
+}
+
+export function followCamera(dt: number, hero: { x: number; y: number; vx: number }, w: number, h: number) {
+  const aimX = hero.x + LEAD * Math.sign(hero.vx);
+  const pull = 1 - Math.exp(-EASE * dt);
+  cam.x += outside(aimX - cam.x, box.halfW * w) * pull;
+  cam.y += outside(hero.y - cam.y, box.halfH * h) * pull;
+  cam.x = clamp(cam.x, level.left + w / 2, level.right - w / 2);   // never show past the level
+  world.position.set(Math.round(w / 2 - cam.x), Math.round(h / 2 - cam.y));  // whole pixels, no shimmer
+}
+```
+
+## 3D chase
+
+An offset behind and above the target, turned with it, eased the same way. The offset's sign
+depends on which way your model faces.
+
+```ts
+const OFFSET = new THREE.Vector3(0, 2.2, 6);   // behind a model whose nose points along -Z
+const LOOK = new THREE.Vector3(0, 1, 0);
+const want = new THREE.Vector3();
+
+export function chaseCamera(dt: number, target: THREE.Object3D) {
+  want.copy(OFFSET).applyQuaternion(target.quaternion).add(target.position);
+  camera.position.lerp(want, 1 - Math.exp(-5 * dt));
+  camera.lookAt(want.copy(target.position).add(LOOK));
+}
+```
+
+Speed feel is a camera job too: widen `camera.fov` a few degrees with speed (call
+`updateProjectionMatrix()` after) and pull the offset back slightly.
+
+## Shake that stays readable
+
+Keep a `trauma` value from 0 to 1: add to it on impact, let it fall by about 1.5 a second, and
+offset the drawn camera by `trauma² × max × noise(time)`. Squaring keeps small hits subtle and big
+ones loud. A cap near 12 px in 2D (about 0.3 units in 3D) keeps the player readable. The HUD does
+not shake, and flashes belong to the thing that was hit, not the whole frame.
+
+## Tap to world
+
+2D: `worldPoint = (tap - world.position) / world.scale`. 3D: `raycaster.setFromCamera(ndc, camera)`
+with `ndc.x = (x / width) * 2 - 1` and `ndc.y = -(y / height) * 2 + 1`, in CSS pixels rather than the
+canvas's backing-store pixels.
+
+## Checks that keep a camera honest
+
+- **The sign.** Pressing right moves the subject right on screen; jump moves it up (screen y grows
+  downward). A chase offset on the wrong side of the model mirrors X, and a racer ships with inverted
+  steering. After any camera change, press the real key once and read the projected position; verify
+  does this through the live camera. A quick basis test: nudge the target's x by 1 and it should move
+  right on screen. Fix the offset, the model's facing or the input mapping, never a state field.
+- **Shake on the draw, not the follow.** Add shake where the camera draws, never to the position it
+  follows, so the follow logic and the checks read a steady camera.