@funpixel/tools 0.0.0-stage → 0.1.1

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

package/plugins/codex/skills/funpixel-game-spine/references/performance.md

@@ -0,0 +1,96 @@
+# Load time and frame time, without touching the look
+
+A game that takes twenty seconds to start, or freezes for one, loses players before the first
+minute. Most of that time is work done at the wrong moment or drawn for nobody: a whole game
+decoded before the title, a model drawn while off screen. Fixing it rarely needs a smaller
+texture or a simpler model.
+
+## The rule: change when and how things load and draw, never what is seen
+
+- Speed is never bought with smaller textures, simpler models or a lower resolution. When only a
+  visible cut would help, keep the look, report the number and let the owner choose (rule 7).
+- Each change is proved on the same named views before and after: the frame cost per scene, and
+  a still of each view. The stills match.
+- Fewer triangles come from not drawing what is hidden, never from drawing less of what shows.
+- Anything streamed in later is ready before the player reaches it; when it is not, the game says
+  so (a short wait card, never a pop-in).
+- A compressed texture format (KTX2) is checked side by side with its source, and the source
+  format stays wherever the compressed one looks worse.
+- New content may choose its own cheap behaviour (an obstacle that rises out of the road as the
+  player nears it): nothing that already existed changed.
+
+## Measure like a phone
+
+- A landscape phone: 844x390 at a pixel ratio of 3, the CPU slowed 4x, a Fast 4G network (9 Mbps,
+  60 ms). `npx @funpixel/tools profile --throttle 4 --viewport phone` gives the frame;
+  `npx @funpixel/tools phone` runs the game in Mobile Safari on a simulator.
+- For loading: the time to Play, the bytes fetched before it, every long task, and a CPU profile of
+  the load.
+- Builds are compared alternately (A, B, A, B), never one run each: a throttled machine varies more
+  than most fixes save. Other work on the machine skews every number; say what else was running.
+- A profile of a view that moves is not a benchmark: what reaches the screen during the sample
+  changes the count. Pin the camera, or say what was on screen.
+- A headless browser's frame time comes from a software renderer, and a desktop GPU hides fill
+  cost: there, read draw calls, triangles and the CPU stages, not milliseconds.
+
+## Find where the frame goes, before changing anything
+
+1. **Budget the frame by stage.** Mark the end of each stage (simulation, world, animation,
+   culling, render submit), keep a running average and the worst case, and read them as
+   `window.__FPX_PROF__()` and on screen behind a `#prof` switch. When the game's logic is a small
+   share and the renderer's CPU side the rest, the work is in draw calls, state changes and
+   hitches, not in the logic. A worst case far above the average during play is often a shader
+   compiling.
+2. **Break the scene down by named group:** triangles and draw calls per group, skinned and
+   instanced marked. Totals say how much; groups say where.
+3. **Fix the biggest thing, capture the same view before and after, profile again,** and repeat.
+   The before and after numbers of each step keep the work honest.
+
+A rewrite into an entity system pays only with thousands of like objects stepped every frame; a
+handful of characters and some dozens of props spend about a millisecond in simulation.
+
+## Load: get to Play sooner, and never freeze
+
+- **Decoding and uploading every texture in one task is the freeze.** Decode pictures with
+  `createImageBitmap` (off the main thread). Warm up in slices: a few texture uploads and
+  `renderer.compileAsync` calls (with `KHR_parallel_shader_compile`) per frame, only for the render
+  targets the scene really uses. Mesh merges, lightmaps and environment maps run as sliced async
+  steps too.
+- **The first minute is all that loads before Play.** The rest streams behind play: a dynamic-import
+  chunk per level, and a low fetch priority for audio and models needed later.
+- **GLBs ship as binary;** base64 inside JSON is a third bigger and slow to parse. When the host
+  does not compress them, gzip them under a `.glbz` extension and read them through
+  `DecompressionStream`; a `.gz` extension gets mangled by some static servers.
+- **GPU memory a level left is freed** (`dispose()` its textures and geometry). Meshopt compression
+  and quantization stay on; KTX2 is the next step, checked as above.
+
+## Frame: draw less of what nobody sees
+
+- **Rigged meshes need their own culling.** A skinned mesh's bounds are its rest pose, so the usual
+  fix is `frustumCulled = false`, and then it is drawn everywhere, in the main pass and the shadow
+  pass. Give each a root bounding sphere large enough to cover its shadow and cull by that. Audit
+  every `frustumCulled = false`.
+- **The shadow pass is not culled by the main camera.** What is behind the player still costs a
+  draw there.
+- **Inverted-hull outlines thinner than about half a device pixel are dropped.** At that size nobody
+  sees them, and each is a second draw of the mesh.
+- **Particles draw as one instanced billboard batch on one sheet,** sorted far to near, not one
+  sprite per particle.
+- **Small repeated parts keep one material.** A part with three material groups is three draw
+  calls, three more in the shadow pass, times every copy; remap its UVs so one material serves.
+- **A material made inside a placement loop is a material per object.** Share it.
+- **Instancing draws every instance, always,** when the batch is not culled. For things spread
+  across the level, single culled meshes beat one batch; for things usually on screen together,
+  the batch wins. Measure which.
+- A fix that would show at all (dropping small shadows) is the owner's to decide.
+
+## Worked examples
+
+- The per-stage frame budget: one racer's `src/game/prof.ts`, with its marks in
+  `src/game/loop.ts` (private repository; copy the approach). It reads as `window.__FPX_PROF__()`
+  and on screen behind `#prof`.
+- Measuring a load: one game's repository (private; copy the approach, not a dependency) keeps
+  the measuring scripts in `game/tools/perf/`: `phone-load.mjs` (the throttled load: time to Play,
+  bytes before it, long tasks and 20 s of play, as one JSON line), `phone-ab.sh` (builds
+  alternated), `phone-profile.mjs` (a CPU profile of the load) and `gpu-mem.mjs` with `gputrack.js`
+  (the biggest GPU textures per room). They take playwright-core from the game's own `node_modules`.

package/plugins/codex/skills/funpixel-game-spine/references/pixi.md

@@ -0,0 +1,26 @@
+# Pixi 8 contracts
+
+Each of these builds cleanly and breaks the game or the checks when missed.
+
+- `import * as PIXI from 'pixi.js'`. Never a window global or a CDN script.
+- Initialisation is async: `const app = new PIXI.Application(); await app.init({ … })`, then mount
+  `app.canvas`. Set `window.__PIXI_APP__ = app` after `init`, so verify and the inspector can find
+  the stage.
+- Every display object gets a `.label` (lowercase with underscores). Pixi's lookups read `.label`,
+  not `.name`, and an unlabelled player cannot be found by a check's `subject`.
+- dt in seconds: `app.ticker.add((t) => game.update(Math.min(t.deltaMS / 1000, 0.1)))`.
+  `ticker.deltaTime` is a frame ratio, and `dt * (1000 / 60)` is the same mistake.
+- Resize with `setupGameResize((w, h) => { app.renderer.resize(w, h); layout(w, h); })`, not
+  `resizeTo: window`.
+- `FillGradient` takes the options form `{ type, start, end, colorStops }` in local 0 to 1 space;
+  the positional constructor renders a flat slab in 8.5 and later.
+- Remove a child with `container.removeChild(sprite)`. A `Container` has no `.contains()`; that is
+  a DOM method and throws.
+- Many similar sprites: one `ParticleContainer` or one atlas-backed batch per family. Three or more
+  sprites in a scene means pack an atlas before writing the loading code, because the atlas
+  changes how you load (skill `funpixel-art`).
+- Move the world container for the camera, never the player; the HUD lives in a sibling container
+  or in the DOM so it never moves.
+- Round the world container's position to whole pixels for pixel art, or it shimmers.
+- Animate scale by multiplying a stored `baseScale`, never by assigning `scale` directly: two
+  overlapping "pop" tweens otherwise leave a sprite permanently enlarged.

package/plugins/codex/skills/funpixel-game-spine/references/replay.md

@@ -0,0 +1,102 @@
+# Replaying a run, and proving a split
+
+Two options for a game whose rules already step from input (skill `funpixel-game-logic`: seeded,
+engine-free, a fixed step): keep a run as data and play it back frame by frame, and prove a
+refactor changed nothing a player sees. Both are lessons from one game (a third-person
+3D horror chapter in three.js, September 2026, hand-iterated over many agent sessions), gathered by
+its lane. No first-try action game has tested them yet; read them as options with the
+reasons they earned, not as a procedure.
+
+## What the kit already does
+
+Point at these before building anything:
+
+- `npx @funpixel/tools journey` keeps a player's path through the real controls as a script,
+  replays it on one seed, holds the clock at each mark and sets the run beside the last one (skill
+  `funpixel-verify`, `references/journeys.md`). `feel --journey` traces every frame of it.
+- The scaffold's `replayTo(game, policy, seed, seconds)` (`src/probe-kit.ts`, the kit `sim` runs)
+  plays a bot's run of the rules to a second, which is how a moment view reaches a payoff the game
+  really reaches (skill `funpixel-game-logic`, `references/probes.md`).
+- `capture --all`, then `compare --baseline` before a change and `compare` after, sets each view's
+  before beside its after and says how much of it changed.
+- `profile --compare` reads a run against the last run made the same way.
+
+What they do not do: stop a long 3D run on one exact frame, every time, and step it a frame at a
+time. That part is the game's own hook, below.
+
+## A run as data: recorded intents
+
+If the sim advances one fixed step per intent (what the hands asked for this step: move, aim,
+dodge), a run is the list of intents plus the seed and any setting that changes the sim. Replaying
+it means feeding that list instead of live input.
+
+- **That game's shape.** Its chapter bots produce intents; a small script wrote a bot run's intents
+  to JSON, and the game read them from a window global in place of the controls, through the real
+  renderer, camera and sound. One test made the replay trustworthy:
+  `same_seed_same_inputs_same_events` plays a bot's intents again on a fresh sim with the same seed
+  and asserts the same event list and the same final snapshot.
+- **Record everything that changes the sim.** An assist setting (the automatic dodge side) changed
+  what a step did; turning it on by default silently broke every recorded replay. The game now
+  turns the assist off whenever a replay runs. Store such settings with the recording.
+- **Re-record after a sim change.** A recording holds intents, not positions: a tuned run speed
+  moves where she stands when the next intent arrives, and the replay drifts. The symptom the
+  game learned to read: a still of her staring at a wall is usually a stale recording.
+- **A recorder in the game.** A key saves a person's run the same way, with its long frames,
+  camera jumps and errors marked. The game's note says a human run beats any bot for feel; when it
+  was written, no human run had been replayed yet.
+
+## Film mode: the same frame every time
+
+A flag stops the page's own clock, and a hook advances the one loop by a fixed step and renders:
+
+```ts
+const w = window as unknown as { __FILM__?: boolean; __TICK__?: (dt: number) => void };
+let filmT = 0, last = performance.now();
+w.__TICK__ = (dt) => { filmT += dt; game.frame(dt, filmT); };   // the same update the loop calls
+function loop(now: number) {
+  if (!w.__FILM__) game.frame(Math.min((now - last) / 1000, 0.1), now / 1000);
+  last = now; requestAnimationFrame(loop);
+}
+```
+
+Its stills script replayed an intent file, ticked 1/60 s at a time until the sim's clock
+reached each requested second, held the sim for about 20 frames so the camera settled, then shot.
+A still at 36.8 s was the same picture every run, so:
+
+- **A moment can be debugged a frame at a time.** Replay to just before it, tick, read
+  `__FPX_STATE__` and `funtools inspect --at x,y` on each frame. Its "what is that white
+  ball?" was found this way: at one fixed frame, hide one thing at a time (the torch light, the
+  enemy, the particles, the beam) until it goes. It was an additive beam seen down its own axis
+  (skill `funpixel-art`, `references/frames.md`).
+- **An A/B at a frame only means something if the frame keeps it.** The game's torch and emissive
+  materials were re-posed every frame, so turning them off in a debug step did nothing, while the
+  albedo, which nothing re-set, could be tested. Turn a thing off where the frame reads it from.
+- **Wall-clock work does not follow the film clock.** CSS transitions and timers ran in real time;
+  the script waited about a second before shooting screens that used them.
+
+This is the spine's one loop and one clock with a second driver, not a second loop.
+
+## Proving a refactor or a split
+
+The game's `sim.ts`, `station.ts` and `game.ts` each grew past 800 to 1,100 lines and were split
+into small modules with typed seams. A split that should change nothing was accepted on four
+agreements, each an option:
+
+| Evidence | With the kit |
+|---|---|
+| Golden stills of the same views, pixel-diffed before and after | `capture --all` and `compare --baseline` before; `capture --all` and `compare` after. For a refactor the reading turns over: every view unchanged is the proof, and a changed view is the finding |
+| Identical bot traces | the determinism test above on a recorded run, or `journey replay` on the same seed: the counters at each mark should not move |
+| The tests | `npm test`; a test named after a rule still passing means the rule still holds |
+| An unchanged profile | `profile --compare` against the run made the same way before |
+
+`compare` calls a view unchanged below 0.5% of pixels changed. A view that animates, or reads the
+wall clock, can differ between two captures of one build; capture the same build twice first, and
+treat a later difference no larger than that as noise (the same idea as `journey replay --repeat 2`).
+With film mode the stills can be identical to the pixel, and then any difference is real.
+
+The case for it, from that game: after the game split, the capture hook reached the game through a
+loose cast, the replay cursor and the intro timer had moved, and every capture view silently sat at
+t = 0 behind the opening shot. A blind panel scored that round 4.9 ("no enemy in any capture").
+Typing the seam (no cast) and logging an error when a view misses its beat fixed it; on real
+captures the next panel scored 6.55. Our reading: views compared against their pre-split stills
+would have shown every one changed before any critic saw them.

package/plugins/codex/skills/funpixel-game-spine/references/room-api.md

@@ -0,0 +1,63 @@
+# Room API (`@funpixel/sdk/multiplayer`, SDK 0.7.0)
+
+```ts
+import { Room, getGameKey, RoomError } from '@funpixel/sdk/multiplayer';
+
+// Joining. All static, all return promises.
+Room.autoJoin(getGameKey(), { game, maxPlayers })  // create-or-join this game's room; the first player hosts
+Room.auto({ game, maxPlayers })                    // joins only when the URL has ?room=CODE, else resolves null
+Room.join(code, { username? })                     // an existing room of THIS game, by its 8-character code
+// Room.connect is refused for games (the relay answers FORBIDDEN). Never call it.
+
+// World state for late joiners and reconnects (the host answers)
+room.provideState(() => state)        // host: the snapshot source (the SDK re-asks it on each join)
+room.onState((state) => {})           // everyone: apply a full snapshot
+
+// Continuous own state: sampled 20 Hz, sent on change, never echoed
+room.sync(key, () => ({ x, y }))
+room.onSync(key, (peerId, value) => {})
+
+// Events: delivered to everyone in the room, the sender included
+room.send(name, data)                 // discrete events, a few per second; data is a plain object
+room.sendBuffered(name, item)         // high-frequency lane, batched; receivers get one callback per item
+room.on(name, (peerId, data) => {})   // peerId === room.playerId on your own echo
+
+// Presence and lifecycle
+room.onPlayerJoin((player) => {})     // player: { id, username, isHost }
+room.onPlayerLeave(({ id }) => {})
+room.onHostChange((newHostId, youAreHost) => {})
+room.onDisconnect(() => {}); room.onError((code, message) => {})
+room.onReconnecting((attempt) => {}); room.onReconnect(() => {}); room.onReconnectFailed(() => {})
+room.isHost; room.players /* Map, includes you */; room.playerId; room.code
+room.connected; room.ping; room.maxPlayers; room.playerCount
+room.leave()                          // also stops the automatic reconnect
+```
+
+**Join errors** reject the promise as a `RoomError` with `.code`: `ROOM_FULL`, `NOT_FOUND`,
+`FORBIDDEN`, or an auth failure when no ticket arrived (opened outside a Funpixel host).
+
+**Runtime errors** arrive on `onError`: `RATE_LIMITED` (move that send to `sendBuffered`, which
+throttles itself) and `SUPERSEDED` (this connection was replaced: call `room.leave()` and offer a
+Rejoin button).
+
+**Payload shapes.** `send('score', 5)` arrives as `{ value: 5 }`; an array arrives as an object
+with keys `0, 1, …`. Wrap values: `send('score', { points: 5 })`. Keys and event names starting
+with `_` (`_sync`, `_evt`, `_batch`, `_state_req`, `_state_snap`) belong to the SDK.
+
+**Limits.** 60 messages a second per player plus a burst of 120, the excess dropped silently. A
+state snapshot over about 200 KB is not sent (the SDK logs one warning): keep the world lean.
+
+**Keys.** `getGameKey()` reads the host name: the preview or published game's key on Funpixel,
+`'local'` on `localhost`. Pass it through untouched; never invent or hard-code a key.
+
+## Reconnects and host migration
+
+- **Reconnects.** The SDK reconnects by itself (up to four tries). After it does, the roster is
+  replaced without join or leave events: reconcile peers in `onReconnect`. Pause input on
+  `onDisconnect`, resume on `onReconnect`, show "connection lost" on `onReconnectFailed`; the
+  render loop that was running keeps running (a second one doubles the speed). `SUPERSEDED` means
+  this connection was replaced (another tab of the same account, or the owner removed the
+  player): `room.leave()` then a Rejoin button, since otherwise the SDK reconnects and steals the
+  slot back.
+- **Host migration.** When `onHostChange` says you are the host, register `provideState` and
+  every host-only `sync` again from your local mirror, which is why every client keeps one.

package/plugins/codex/skills/funpixel-game-spine/references/room-modes.md

@@ -0,0 +1,40 @@
+# Room modes
+
+Pick one from the design and say which in the design note. The relay offers one thing: this game's
+shared rooms, filled lowest first, with overflow rooms when one is full. A code brings a friend into
+the room you are in. No mode makes a room private, so never promise privacy in copy or UI.
+
+| Mode | When | The player sees |
+|---|---|---|
+| Lobby (default) | Matches with a start: duels, co-op runs, party games | A join button named with the game's own verb, a waiting screen with the players, the host's Start |
+| Invite codes | Playing with friends is the point | Join, plus "Join with code"; the code as a large copyable element; an invite link |
+| Drop-in | A shared world with no matches: a lounge, a sandbox, a persistent board | Nothing: the game joins during loading and others simply appear |
+
+## Lobby
+
+- The primary button calls `autoJoin`; label it the way a player of this world would say it.
+- The host starts the match with `room.send('game_start', {})`; every client starts on
+  `room.on('game_start', …)`, guarded by a local `started` flag.
+- The room code, if shown, carries `data-funpixel-selectable` (or is a real `<input readonly>`), or
+  players cannot copy it.
+- Offline: the solo game, never a dead card. It is what verify sees.
+
+## Invite codes
+
+- Two entries: "Play" (`autoJoin`, which joins this game's shared room) and "Join with code" (a
+  real `<input>` into `Room.join(code)`: uppercase, 8 characters, inline "No room with that code"
+  on `NOT_FOUND` or `FORBIDDEN`).
+- A URL with `?room=CODE` skips the title: `Room.auto({ game, maxPlayers })` joins directly.
+- After joining, show the code large and selectable with a copy-link button writing
+  `${location.origin}${location.pathname}?room=${room.code}`.
+- `ROOM_FULL` on a code join: say the room is full; never drop the player into another room.
+- Game keys stay off while the code input has focus: skip keydown when
+  `e.target instanceof HTMLInputElement`.
+
+## Drop-in
+
+- No lobby, no code, no waiting gate. Call `autoJoin` behind the loading screen and start at once.
+- The world is complete with one player; others appearing or leaving is ambient (a subtle cue,
+  never a modal).
+- `ROOM_FULL`: a small "World is full, retrying" toast and a retry every 10 seconds.
+- Any failure: solo play with one small toast. Sharing is the game's URL itself.

package/plugins/codex/skills/funpixel-game-spine/references/sdk.md

@@ -0,0 +1,114 @@
+# The @funpixel/sdk surface
+
+No model was trained on this package, so guessing its API costs a build, and a guess that
+type-checks can do nothing at runtime. This skill is the short list worth using, from the studio's budget
+audit. Everything else the package exports is optional: use
+the web platform (`localStorage`, `requestFullscreen`, `screen.orientation`, the engine's loader
+and tweens).
+
+## Tools
+
+- No MCP tool teaches the SDK; this skill is the reference. `build` or `probe` show whether it
+  works in the platform's browser.
+- Local: `npx @funpixel/tools doctor` warns on an unpinned SDK; `npx @funpixel/tools verify` runs
+  the game.
+- A name error is a lookup: find the name below or in `node_modules/@funpixel/sdk/dist/*.d.ts`.
+  A cast, `?.` or widened type that makes a wrong name compile hides it until runtime, where it
+  does nothing.
+
+## The surface
+
+1. Pin it exactly: `"@funpixel/sdk": "0.7.0"`, no caret. The root export is `setupGameResize`
+   only; everything else comes from a subpath (`/audio`, `/multiplayer`, `/save`, `/liveParams`,
+   `/device`).
+2. **Resize.** `setupGameResize(cb: (width: number, height: number) => void, win?: Window): () => void`
+   from `@funpixel/sdk`.
+   - It calls `cb` once, synchronously, at the call: create the renderer first.
+   - Size from `w, h`, never `innerWidth`; a Studio message can carry a different size.
+   - Remove Pixi `resizeTo: window` and any `resize` listener: they miss iframe resizes, and two
+     resizers fight. Zero and unchanged sizes are dropped. It returns a teardown.
+3. **Audio.** `new AudioEngine(opts?: { ctx?: AudioContext; iosPatch?: boolean })` from
+   `@funpixel/sdk/audio`, with `.ctx`, `.master`, `init()` and `unlock(): Promise<void>`.
+   - The iPhone ringer switch is the game's call. `iosPatch: false` respects it (the switch mutes
+     the game, the casual-game norm, and what a new game passes); `true`, the default for games
+     made before this was a choice, plays through it, for games where sound is the point. Keep
+     an existing game's choice.
+   - Connect every source to `audio.master`: the mute toggle drives it, and under `iosPatch: true`
+     anything on `ctx.destination` is muted by the switch anyway.
+   - `unlock()` latches on its first call even if resuming failed. Call it from `click`,
+     `pointerup`, `keydown` or `touchend` (WebKit did not resume on `pointerdown`); while
+     `audio.ctx.state !== 'running'`, call `audio.ctx.resume()` on the next gesture.
+   - There is no play or load API: decode once with `ctx.decodeAudioData`, one `BufferSource` per
+     hit. One engine per game; a second `AudioContext` escapes the patch.
+4. **Multiplayer**, only when the design is multiplayer:
+   `Room.autoJoin(getGameKey(), { game, maxPlayers })` from `@funpixel/sdk/multiplayer`. The
+   [multiplayer](multiplayer.md) reference has the echo, roster and host-state traps.
+5. **Save.** `new SaveManager<T>({ key, version, defaults, migrations?, onSaveError?, debounceMs? })`
+   from `@funpixel/sdk/save`, with `.data`, `update(partial)`, `flush(): { ok, error? }` and
+   `reset()`.
+   - `update` persists 500 ms later: `flush()` at the end of a run and on `visibilitychange`.
+   - The merge is shallow: a nested object is replaced, not merged.
+   - A corrupt save loads as `defaults`, silently. Migrations are keyed by the target version; a
+     gap stops migration silently.
+   - `onSaveError` fires only on the debounced path: check `flush().ok` and tell the player.
+6. **Live tuning.** `initLiveParams(schema)` from `@funpixel/sdk/liveParams`, where each entry is
+   `{ type: 'number' | 'boolean' | 'color' | 'select', value, min?, max?, step?, options?, name? }`;
+   it returns `get(key)`, `subscribe(key, (v, prev) => …)`, `set(key, v)` and `all()`.
+   - A misspelt key returns `undefined` and the physics become `NaN`.
+   - A value copied into a constant at load never updates: read `get()` in the loop, or subscribe.
+   - A bad schema entry leaves the params empty, silently: check `Object.keys(params.all())`.
+     Values change live only in the Studio preview.
+7. **Safe area on a canvas.** `safeArea.insets(): { top, right, bottom, left }` from
+   `@funpixel/sdk/device` reads zeros unless the CSS sets
+   `:root { --sai-top: env(safe-area-inset-top); … }` for all four sides and the viewport meta has
+   `viewport-fit=cover`. Re-read after rotation. A DOM HUD uses
+   `max(16px, env(safe-area-inset-*))` in CSS instead.
+
+## What not to reach for
+
+| Export | Use instead | Why |
+|---|---|---|
+| `haptics` | `navigator.vibrate?.(ms)` | It is exactly that, and a no-op on every iPhone |
+| `fullscreen`, `orientation` | the platform calls with `.catch()` | The wrapper only swallows the rejection |
+| `Grid`, `findPath` | your own A*, or `easystarjs` | Four-neighbour only and slow on big grids |
+| `fx` shake, pop, flash | a render offset or a tween | Overlapping calls leave the stage offset or tinted for good |
+| `leaderboard()`, `host` | nothing yet | Only the Studio answers; published games wait 1.5 to 2 s for nothing |
+| `gameState()`, `motion`, `preload`, `register` | `SaveManager`, `sensors`, the engine loader | Duplicates, or no host acts on them |
+
+## Worked example
+
+A runner that saves its best distance and tunes gravity live:
+```ts
+import { setupGameResize } from '@funpixel/sdk';
+import { AudioEngine } from '@funpixel/sdk/audio';
+import { SaveManager } from '@funpixel/sdk/save';
+import { initLiveParams } from '@funpixel/sdk/liveParams';
+
+await app.init({ background: '#101018' });          // renderer first: the resize fires at once
+setupGameResize((w, h) => { app.renderer.resize(w, h); game.layout(w, h); });
+
+const audio = new AudioEngine({ iosPatch: false });  // the ringer switch mutes it
+addEventListener('pointerup', () => audio.unlock(), { once: true });
+
+const save = new SaveManager({ key: 'runner', version: 1, defaults: { best: 0 } });
+const params = initLiveParams({ gravity: { type: 'number', value: 1800, min: 600, max: 3000 } });
+if (!Object.keys(params.all()).length) console.error('live params rejected');
+
+function onRunEnd(distance: number) {
+  if (distance > save.data.best) save.update({ best: distance });
+  if (!save.flush().ok) showToast('Could not save your best run');
+}
+// in update(dt): vy += (params.get<number>('gravity') ?? 1800) * dt;
+```
+
+## Common mistakes
+
+- `leaderboard.submit(score)`: `leaderboard` is a factory, so the call throws.
+- A caret on the SDK version: the platform build and your build resolve different code.
+- `import { AudioEngine } from '@funpixel/sdk'`: only `setupGameResize` is at the root.
+- Connecting a sound straight to `ctx.destination`: the mute toggle misses it, and a rhythm game
+  on `iosPatch: true` goes quiet on a silenced iPhone.
+- Treating `safeArea.insets()` zeros as "no notch".
+- Relying on `haptics` for feedback: nothing happens on iPhone, so pair it with a visible cue.
+
+Where this comes from: ours, from the SDK and its budget audit; a few device notes began in our platform prompts.