@funpixel/tools 0.0.0-stage → 0.1.0

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 | Gesundheit: 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 | Gesundheit `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? | Gesundheit `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 | Blue Freight r4: 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 (Blue Freight r4'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 (Gesundheit'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 Riad Rush'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 (Iron Line'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 (Gesundheit'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 Gesundheit (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. Pocket Crew's first
+TestFlight build drew every moving platform frozen after the first level behind 1,118 green
+tests, and Porcelain Panic 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 Floe Jam's `FloeJam.PlayTests` do,
+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: Hot Gates |
+| `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: Dawg Ball, one level only |
+| `difficulty_bots` | sharp bot ≥ 2 shots past onboarding; noisy bot ≥ 75% clears per section | partial: Porcelain Panic |
+| `softlock_bot` | 0 states with no valid action | partial: Dead Letter level tests |
+| `economy_pacing` | time to finish in band; offline pay ≤ next purchase | partial: Noodle Nights, Dawg Ball |
+| `physics_fuzz` | 0 inside-solid, tunnel, NaN or stuck | partial: Pocket Crew |
+
+`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 | Koi Out: 600 levels by reverse removal, 29 tests |
+   | Generated, fitted to a bot | budgets fitted to sharp-bot shots, then capped from human play | Porcelain Panic |
+   | Data from the web build | level laws as tests | every port |
+
+   Level laws are properties held as tests. Pocket Crew'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. Porcelain
+   Panic 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: Dawg Ball 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 Dawg Ball).
+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 Hot Gates 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 Dawg Ball
+    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
+    Pocket Crew 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. Dawg Ball'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
+
+Dawg Ball'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: Porcelain Panic'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: a Dawg Ball head then spread 15–76% at Alpha.
+- Leaving offline pay out of the economy sim: Noodle Nights 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 Noodle Nights).
+- Starting every level fresh at boot: Pocket Crew's movers drew frozen in every level after the
+  first; the audit's frozen count went 219 → 0 once fixed.
+- Skipping the physics fuzz: Pocket Crew had 1,988 respawns inside solid geometry on 24 of 26
+  levels.
+- A test that never asserts: Dawg Ball's "always ends with a winner" did not.

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

package/plugins/robin/skills/funpixel-game-spine/references/multiplayer.md

@@ -0,0 +1,101 @@
+# Multiplayer on the Funpixel relay
+
+The best multiplayer moments are other people: a friend's cursor on a shared canvas, a rival
+passing on the last lap, a room code shouted across a sofa. The relay is a forwarder with no state
+or authority; the first player in a room is the host and owns the world (`Room`, from
+`@funpixel/sdk/multiplayer`). Silent failures: a frozen twin of your avatar, a host nobody can hit,
+a late joiner in an empty world, a "private" room strangers enter. The connection is platform fact;
+the rest is what our multiplayer games learned (research 08).
+
+## Tools
+
+- `build`, `preview` and `publish_game` put the game where the relay is reachable; `probe` checks
+  its solo branch the same way as any game.
+- Local: `npx @funpixel/tools dev --relay` runs the game with a local relay; two tabs of
+  `/__funpixel/play` meet in the game's dev room, and `--bots 3` seats three headless players
+  (pressing your `__FPX_VERBS__`). `npx @funpixel/tools verify --players 2` checks it headless:
+  both join, the guest sees the host act, a late joiner gets the state, the room survives the host
+  leaving. Both need the `funpixel-relay` binary and a Redis.
+
+## The connection
+
+1. `import { Room, getGameKey, RoomError } from '@funpixel/sdk/multiplayer'`. The relay admits only
+   a one-use ticket the platform posts into the game's frame, which the SDK asks for, and it speaks
+   JSON in text frames; a raw WebSocket, WebRTC or a token of your own is refused (a security fact:
+   tickets are how the relay knows who may enter a room).
+2. `Room.autoJoin(getGameKey(), { game: '<slug>', maxPlayers })` joins; the relay refuses
+   `Room.connect` for games. A `try/catch` around it keeps Play alive: `e.code === 'ROOM_FULL'` is
+   worth saying; anything else can start the solo game with a toast. An unhandled rejection
+   leaves a dead Play button.
+3. `maxPlayers` comes from the design (2 duel, 4 co-op, 8 arena, at most 16). The first join fixes
+   a room's capacity for as long as the room lives, so changing the number later affects new rooms
+   only. Full rooms spill into overflow rooms, which splits the crowd.
+
+It connects inside a Funpixel host (the Studio preview, the published player) or on `localhost`
+under `funtools dev --relay`; anywhere else there is no ticket. The platform's checker has no relay
+either, so a solo branch is what verify and the reviewers see: without one, a game is judged on
+its failure screen.
+
+## What our multiplayer games learned
+
+4. **Host owns what accumulates.** Boards, scores, placed blocks: the host registers
+   `room.provideState(() => world)` and every client applies `room.onState(s => …)`. `sync` sends
+   only changes made after a player joined, so without a snapshot a late joiner starts blank.
+5. **Your own echo, one way.** `room.send` and `room.sendBuffered` are delivered to everyone in the room,
+   the sender included, with `peerId === room.playerId`. Pick one: apply your own action at once and
+   skip your own echo, or apply it only when the echo arrives. Both double-applies it; neither made
+   Rush Arena's host immortal, because hits addressed to itself were never applied (research 08).
+   `room.sync` does not echo. An event aimed at a player (a hit), keyed by the target's id, is applied
+   wherever that state lives, the host's own included.
+6. **The roster includes you.** `room.players` lists every player, you among them. When spawning
+   peers already in the room, skip `room.playerId`, or a frozen twin of your avatar stands at the
+   spawn and counts as alive.
+7. **Rate (a relay fact).** 60 messages a second per player; the rest are dropped. Per-frame data
+   fits `room.sync(key, getter)` (sampled at 20 Hz, change only) or `sendBuffered`; `send` suits
+   discrete events. A send from `pointermove` or the render loop runs into the cap within a second.
+8. **Payloads are plain objects** (the wire is JSON). A number arrives as `{ value }`, an array as
+   index-keyed fields. Names starting with `_` are the SDK's.
+9. **Smooth remote values.** They arrive at 20 Hz and render at 60: store a target and ease toward
+   it in `update(dt)`, `x += (tx - x) * (1 - Math.exp(-rate * dt))`.
+10. **Reconnects and host migration.** The SDK reconnects by itself (up to four tries) and replaces
+    the roster without join or leave events; a new host re-registers `provideState` from its local
+    mirror. The handlers, `SUPERSEDED` and the Rejoin button are in
+    [room-api.md](room-api.md#reconnects-and-host-migration).
+
+The full API surface and five worked patterns are in [room-api.md](room-api.md)
+and [patterns.md](patterns.md). Room modes (a lobby, invite codes, or drop-in
+with no rooms at all) are in [room-modes.md](room-modes.md).
+
+## Testing it
+
+- Solo branch: `funtools verify` as usual; `__FPX_VIEWS__.playing` lets it reach play.
+- Two players: `funtools verify --players 2` locally (the host acts through `__FPX_VERBS__`, and
+  what the guest sees is read from `__FPX_STATE__`). On the platform, build (`build` then
+  `preview`, or publish a draft) and join from two accounts or devices: two tabs of one account
+  replace each other (`SUPERSEDED`).
+- A ticket mint or relay stub of your own maps the platform's auth into the game, so it stays out
+  of what ships (our games' mint servers had to be kept out by hand, research 08).
+  `funtools dev --relay` is the local one, and it mints only dev tickets, for this machine.
+
+## Worked example
+
+A two-player tank duel:
+1. Title button "Roll out" calls `Room.autoJoin(getGameKey(), { game: 'tank-duel', maxPlayers: 2 })`;
+   the catch starts a bot duel with the toast "Playing offline".
+2. Each tank syncs its own `{ x, y, angle }` with `room.sync('tank', …)`; peers ease toward it.
+3. Firing: the shooter draws its shell at once and sends `fire`; the handler returns early when
+   `peerId === room.playerId`.
+4. Hits: the host resolves them and sends `hit` with `{ target, hp }`. Every client, the host
+   included, applies it from the echo, so the host's own tank can be hit.
+5. `provideState` returns both tanks' `hp` and the round; a player who reconnects mid-round gets it.
+6. Verify passes on the offline bot duel; two accounts on the published draft confirm the duel.
+
+## Common mistakes
+
+- Spawning a peer for every roster entry, yourself included: a frozen twin.
+- Skipping every own echo, including events that change your own state: an immortal host.
+- Promising a private room. Invite codes bring a friend into this game's rooms; they do not keep
+  strangers out.
+- A lobby whose offline branch is a dead card: verify and every reviewer see only that card.
+- Assigning remote positions directly: visible stepping at 20 Hz.
+- Reading `maxPlayers` changes as a fix for crowded rooms: existing rooms keep their capacity.

package/plugins/robin/skills/funpixel-game-spine/references/patterns.md

@@ -0,0 +1,103 @@
+# Five patterns
+
+Each is complete against the API in [room-api.md](room-api.md), with the audit fixes applied: the
+roster includes you, `send` echoes, reconnects replace the roster silently, and a promoted host
+re-registers everything the old host owned.
+
+## Shared canvas (state that accumulates)
+
+```ts
+let strokes: { x: number; y: number; by: string }[] = [];
+const room = await Room.autoJoin(getGameKey(), { game: 'paint', maxPlayers: 8 });
+
+onPointerMove((pt) => {
+  const s = { ...pt, by: room.playerId };
+  strokes.push(s); draw(s);                 // own input applied at once…
+  room.sendBuffered('stroke', s);
+});
+room.on('stroke', (peerId, s) => {
+  if (peerId === room.playerId) return;     // …so its echo is skipped
+  strokes.push(s as typeof strokes[number]); draw(s);
+});
+room.provideState(() => ({ strokes }));     // the host answers late joiners
+room.onState((st) => { strokes = (st as { strokes: typeof strokes }).strokes; redrawAll(strokes); });
+```
+
+## Host-authoritative score
+
+```ts
+let scores: Record<string, number> = {};
+const registerHost = () => {
+  room.sync('scores', () => scores);        // only the host broadcasts
+  room.provideState(() => ({ scores }));
+};
+if (room.isHost) registerHost();
+room.onSync('scores', (_id, v) => { scores = v as typeof scores; renderScores(scores); });
+room.onState((st) => { scores = (st as { scores: typeof scores }).scores; renderScores(scores); });
+room.onHostChange((_id, youAreHost) => { if (youAreHost) registerHost(); });  // re-register after migration
+
+function onGoal(scorer: string) {
+  if (!room.isHost) return;
+  scores[scorer] = (scores[scorer] ?? 0) + 1; // the 20 Hz sync picks it up
+}
+```
+
+## Hits the host resolves (and can take)
+
+```ts
+room.on('hit', (_peerId, d) => {
+  const { target, hp } = d as { target: string; hp: number };
+  tanks.get(target)!.hp = hp;               // applied from the echo on every client, the host included
+});
+function hostResolvesHit(target: string, damage: number) {
+  if (!room.isHost) return;
+  const hp = Math.max(0, tanks.get(target)!.hp - damage);
+  room.send('hit', { target, hp });         // do not also set hp here: the echo does it
+}
+```
+
+## Turns
+
+```ts
+let turn: string | null = null;
+room.on('turn', (_id, d) => { turn = (d as { playerId: string }).playerId; renderTurn(turn); });
+room.on('move', (peerId, move) => {
+  if (peerId !== room.playerId) applyMove(peerId, move);
+  if (room.isHost) advanceTurn();           // the host alone decides who is next
+});
+function submitMove(move: Move) {
+  if (turn !== room.playerId) return;
+  applyMove(room.playerId, move);
+  room.send('move', move);
+}
+function advanceTurn() {
+  const ids = [...room.players.keys()];     // includes the host itself
+  const next = ids[(ids.indexOf(turn ?? ids[0]) + 1) % ids.length];
+  room.send('turn', { playerId: next });
+}
+```
+
+## Reconnect and presence
+
+```ts
+const peers = new Map<string, Peer>();
+const reconcile = () => {
+  for (const id of [...peers.keys()]) if (!room.players.has(id)) { peers.get(id)!.destroy(); peers.delete(id); }
+  for (const p of room.players.values()) if (p.id !== room.playerId && !peers.has(p.id)) peers.set(p.id, spawnPeer(p));
+};
+reconcile();                                          // peers already in the room, never yourself
+room.onPlayerJoin((p) => { if (p.id !== room.playerId && !peers.has(p.id)) peers.set(p.id, spawnPeer(p)); });
+room.onPlayerLeave(({ id }) => { peers.get(id)?.destroy(); peers.delete(id); });
+
+let paused = false;                                    // read inside the game's own update(dt); no second loop
+room.onDisconnect(() => { paused = true; showBadge('Reconnecting…'); });
+room.onReconnect(() => { paused = false; hideBadge(); reconcile(); });   // the roster was replaced silently
+room.onReconnectFailed(() => showConnectionLost());
+room.onError((code) => { if (code === 'SUPERSEDED') { room.leave(); showRejoin(); } });
+```
+
+## Testing in the dev room
+
+Under `npx @funpixel/tools dev --relay` a full reload waits while two or more pages are in the room
+(two tabs, or you and the bots), so saving a file never ends the match you are testing; it goes out as
+soon as the room empties, or after ten minutes. `--no-hold` sends every reload at once.