@funpixel/tools 0.0.0-stage → 0.1.1

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

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

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