@funpixel/tools 0.0.0-stage → 0.1.0

package/plugins/robin/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: Knockout Lap'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: Gallery Heist'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/robin/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/robin/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, Held Note (a third-person
+3D horror chapter in three.js, September 2026, hand-iterated over many agent sessions), gathered by
+the Held Note 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.
+
+- **Held Note'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 Held
+  Note 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. Held Note'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);
+}
+```
+
+Held Note's 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. Held Note's "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.** Held Note'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
+
+Held Note'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 Held Note: 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/robin/skills/funpixel-game-spine/references/room-api.md

@@ -0,0 +1,63 @@
+# Room API (`@funpixel/sdk/multiplayer`, SDK 0.6.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/robin/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/robin/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.6.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.

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

@@ -0,0 +1,62 @@
+# Three.js contracts
+
+Each of these builds cleanly and breaks the game or the checks when missed. Generated models have
+their own traps: skill `funpixel-3d`.
+
+- Export after setup: `window.THREE = THREE`, `window.__THREEJS_SCENE__ = scene`,
+  `window.__THREEJS_RENDERER__ = renderer` (what `profile` reads), `window.camera = camera`. Verify projects the player through that
+  camera to decide whether it can be seen.
+- Every mesh, group and light gets a `.name`, including loaded model roots
+  (`gltf.scene.name = 'player'`).
+- One loop: `renderer.setAnimationLoop(() => { const dt = Math.min(clock.getDelta(), 0.1); update(dt); renderer.render(scene, camera); })`.
+  With animated models, `mixer.update(dt)` runs every frame or the character freezes in its bind
+  pose.
+- Size by CSS: `renderer.setSize(w, h, false)` plus `canvas.style.width = canvas.style.height = '100%'`;
+  cap `renderer.setPixelRatio(Math.min(devicePixelRatio, 1.5))`, because a pixel ratio of 3 fills
+  nine times the pixels.
+- Decoders are required and same-origin: `DRACOLoader` with `setDecoderPath('/draco/')`,
+  `KTX2Loader` with `setTranscoderPath('/basis/')` and `detectSupport(renderer)` before any load,
+  and `setMeshoptDecoder(MeshoptDecoder)`. Vendor the decoder files into `public/`; without them
+  every model load fails and a fallback cube appears. A missing-module error on one of them means
+  fix the path, never delete the import.
+- Generated models need an environment map (they export metallic materials and render flat grey
+  without one) and tone mapping; with an environment map, cut analytic lights to at most three.
+- Colliders are simple proxies (a capsule, a box you size), never `Box3.setFromObject` on a skinned
+  mesh: the pose inflates it and every clip jitters the hitbox.
+- More copies of a rigged model use `SkeletonUtils.clone`, never `root.clone()`.
+- Instanced scenery: one `InstancedMesh` has one bounding sphere, so it is never culled in parts;
+  split huge fields into chunks.
+- three r186 (the scaffold's) removed `PCFSoftShadowMap`: it silently becomes `PCFShadowMap` with one
+  console warning, so code written for an older three changes its shadow look. Use `PCFShadowMap` and
+  soften with `light.shadow.radius`.
+- Phone budget: about 100 draw calls, at most three lights, no texture over 2048, shadows from the
+  key light only.
+
+## The 3D world starter
+
+`funtools init` gives a 3D line the world starter (`--framework three-world`), one small file per
+concern, each with its numbers in one table you tune rather than rewrite:
+
+- `rules.ts` + `layout.ts` + `bot.ts`: engine-free movement (`MOVE`: run speed, acceleration, air
+  control, a held jump higher than a tap, coyote and buffer 0.1 s, a dash), platforms and pillars
+  from a seed, a sharp bot; Node tests and `test/probes.ts` play them with no frame.
+- `shots.ts` (`SHOTS`) + `camera-rig.ts` (`RIG`): the camera plan as named shots (the title's
+  slow orbit over the play world, play's follow, a beat's `reveal`), each a lens, a height and a
+  distance, blended with `shoot(name, seconds)`; the rig follows with look-ahead on velocity, a ray
+  to the eye that pulls in fast and eases out slowly, and a steady yaw so the stick means the same
+  thing all round; upright phones pull back. `__FPX_CAMERA__` reports the shot and its numbers, so
+  `funtools score --target` prints moves such as `SHOTS.play.height 4.4 → 6.1`.
+- `world.ts` + `palette.ts`: ACES tone mapping, sRGB output, a gradient sky with fog in its horizon
+  colour, hemisphere + one shadowing key light + a cool rim, ground coloured by noise, instanced
+  scatter past the edge, drifting motes. Colours are the CSS tokens, so the UI and the world change
+  together.
+- `models.ts`: a `.glb` at `public/assets/models/<name>.glb` replaces its placeholder with no code;
+  placeholders are designed shapes in the palette and stay listed in `state.art.placeholders`
+  until their model lands. `assets/assets.json` lists them to generate, reference sheets first.
+- `controls.tsx` + `input.ts`: a stick born where the thumb lands, jump and dash in the right
+  thumb's arc, inside the safe areas; keys and a gamepad reach the same verbs.
+- `budget.ts` (`BUDGET`): 120 draw calls, 300k triangles, pixel ratio 1.5 at most, stepping the
+  shadows and then the pixel ratio down on long frames; `state.render` reports them.
+- `screens.tsx`: the title over the orbiting world, banners over a softened world, a stamped ending.
+
+Keep the shape when the game grows: new rules in engine-free files, their numbers in a table.

package/plugins/robin/skills/funpixel-gdd/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: funpixel-gdd
+description: Use when starting a game from an idea or in an empty folder (start here, with flow start), planning the whole game, writing or growing its design document (GDD, a design doc; a long game in chapters), or when a request changes the genre, core verb or win condition or asks for a complete game. Covers invention, genre cards, the first look and playable, the release bar and the hand-back.
+---
+
+# Starting and planning a game
+
+A GDD is where a game is decided before it is built, and where the next session or a critic
+learns what it is: a Part 1 that says what the game is and why, a Part 2 whose targets and named
+tests come before code. It is the contract: the owner decides what it holds; inside it, the how is
+yours to invent, and the creator's vision wins over any row here. While the GDD is being written, no gate applies: the template and the lint are a checklist
+to consult at the end, not the order to write in.
+
+One document, `design/GDD.md` (an older `design/README.md` reads the same). The hooks read its `## AD rules`, `## Actors`, `## Juice` and `## Fix round`.
+
+## Starting from an idea
+
+`npx @funpixel/tools flow start` names the next step; the path our complete games took is [references/start.md](references/start.md) and
+[references/the-path.md](references/the-path.md). In short: brief back; the first look (key art,
+the hero's sheet); a first playable from it, which the owner plays; the design around it, locked; then the slice through real input (skill
+`funpixel-verify`); then rounds against the plan's target frames until the owner says yes. A genre
+recipe (`references/genre-<card|platformer|puzzle|racing|rpg|shooter|simulation|strategy|survival>.md`)
+is a starting point; the creator's choices win. The release
+bar our best games shared is [references/floors.md](references/floors.md); the hand-back says what
+plays now with its literal controls, what is not in yet, and the next steps, with every
+stand-in named. An existing game's change goes to skill `funpixel-game-spine`; a missing `verify.json`
+is an evidence gap, not a rebuild.
+
+## Invent first, then fill the template
+
+A plan filled template-first lost 3 of 3 blind seats to one that spent its time on design (Gallery
+Heist, 1 Oct 2026). The order that won, in [references/invent-first.md](references/invent-first.md):
+
+1. **Six forcing questions**, in `## The invention`: what the core object means, why the verb
+   exists in this world, who wants what by name, what the twist costs in feeling and in play, the
+   one system that lives and reacts to the player, what only this game has. A generic answer means
+   the idea is not there yet.
+2. **A hit per axis** (mechanic, feel, touch controls, layout, surface satisfaction, readability,
+   market), each with take, avoid and a source link, in `## Hits, per axis`.
+3. **The studio pitch**: cards for genre and fidelity, depth, the core that burns, the story
+   standard, extras with their cost; pick each with why; the owner approves them at the lock
+   (`pitch ask` makes each theirs).
+4. **Worth building at this length?** Your numbers' minutes against the owner's target, beside the
+   first playable; recommend dropping a weak idea ([references/worth.md](references/worth.md)).
+5. **Named behaviour tests** in Part 2, before code.
+6. **Our lessons as defaults**: modelled places, a GPU tier, every attack tells, teach once at the
+   element, a camera that never fights the player, controls off the play.
+
+Places that differ, fun with depth, phone controls: [references/level-and-fun.md](references/level-and-fun.md).
+
+## Tools
+
+- `npx @funpixel/tools init <folder> --idea "<one line>"` picks engine, recipe and orientation,
+  seeds `design/GDD.md` and commits the game to git (never a temp folder);
+  `create_game` is for an agent with no local files.
+- `npx @funpixel/tools gdd`: the invention answered or generic, hits per axis, named tests, the
+  locked core, then missing sections; no score, since completeness is not quality.
+- `npx @funpixel/tools pitch`: the studio pitch's cards, picks and lock; `variety --within`: the
+  place pictures against each other.
+- `gdd page`: the living plan page (`design/GDD.html`), agreed a section at a time; `greenlight page`: the lock's. The studio's best pages and pages of its own: references/pages.md.
+- First look: `generate_image`, `generate_sound`, `generate_music` with the game's id; `loudness` measures the
+  cues against their targets. Sign-in: `funtools whoami`, `funtools login`.
+
+## What a great GDD holds
+
+Copy [references/gdd-template.md](references/gdd-template.md) to `design/GDD.md`. What makes each
+section strong is in [references/sections.md](references/sections.md).
+
+1. **The invention, the hits and the studio pitch** (above); **the promise**: one line, the thesis
+   in one frame or number, the 6-second ad; **pillars and decisions** against their alternatives.
+2. **The core loop and its numbers**: the three to five numbers that are the whole game, each with
+   why exactly that value, and the rule that stops the boring optimum.
+3. **The first minute and the hook**: first input by 0:05, a moment ladder, 2 to 4 wow moments.
+4. **Content**: kinds that each bend the core rule and read by silhouette, stages that each add one
+   thing, a climax; a counted content list and an art budget
+   ([references/plan-at-size.md](references/plan-at-size.md)).
+5. **Places and the living world**: each place its own shape, material, era and light, its rule
+   and a picture; one living system with a job in play; a rival whose want is half right ([references/world-and-identity.md](references/world-and-identity.md)).
+6. **Experience**, what stills miss ([references/experience.md](references/experience.md)).
+7. **Look, actors, audio, HUD and screens, juice, controls**: colour as assignment, AD rules
+   checkable in one frame, target frames; a phone mockup with every element numbered.
+8. **Scope, money model, build plan, risks**, and lessons that apply.
+9. **Part 2**: targets and named behaviour tests now; rewritten from the code once it runs, and from
+   then on it wins ([references/as-built.md](references/as-built.md)).
+
+Mid and deep games add `design/spec/`, data the game loads ([references/spec-folder.md](references/spec-folder.md)).
+
+## Design measures: advice
+
+`gdd` ends with six numbers and why: elements per hour (good games: 1.4–3), the spine, sources
+(`gdd --sources`), peers, length totals, Steam's refund window. Advice: you read and decide, the owner
+decides; a field the GDD lacks is not given ([references/design-measures.md](references/design-measures.md)).
+
+## Versions and the track
+
+v0.1 before code, v0.2 after the first look, one per stage or per request bending a pillar. The stages and what each leaves behind: [references/track.md](references/track.md).
+
+## The first look
+
+The key art and the hero's sheet first (the first playable is built from them); then, while
+planning, the whole game: `npx @funpixel/tools firstlook` names its set. Say each paid job's cost. Each piece: [references/first-look.md](references/first-look.md).
+
+**Image tools down?** Tell the owner, keep writing, stand in with marked code-drawn vignettes, and put
+"pictures owed" in `## Open questions`; never fake a picture.
+
+## Worked example
+
+Brief: "paper boats race down a rainy gutter". The boat is a child's message home, so a sunk boat
+loses a line of it; the living system is the rain, a clock that floods the shortcuts.
+
+## Common mistakes
+
+- Filling the template before inventing: complete, clear, forgettable.
+- One genre hit as the whole research; places that differ only in name.
+- Rules as prose instead of test names; a generated frame taken for the game.
+- Calling unfinished stand-ins a deliberate style, or leaving the GDD at its first draft.