@funpixel/tools 0.0.0-stage → 0.1.0

package/plugins/robin/skills/funpixel-audio/references/engine.md

@@ -0,0 +1,78 @@
+# Wiring sound through the SDK's AudioEngine
+
+Detail for step 7 of `funpixel-audio`: a small module that plays every effect and loop through one
+`AudioEngine`, with class buses, a mute that survives a reload, voice caps and a music duck. Each
+line below answers a failure our games shipped with.
+
+## Why each piece is there
+
+- **One engine, `{ iosPatch: false }`.** The iPhone ringer switch then mutes the game, as players
+  expect; `true` plays through the switch, for games where sound is the point (rhythm, music). An
+  existing game keeps its choice: every rebuild pins the current SDK, so flipping the default would
+  change old games.
+- **Everything through `audio.master`.** A source connected to `ctx.destination`, or a
+  `new Audio(...)`, escapes the mute; an `<audio loop>` also gaps at every seam.
+- **Unlock on `click`, `pointerup` or `keydown`.** WebKit may not resume the context on
+  `pointerdown` alone, and `unlock()` latches on its first call, so a failed first unlock stays
+  failed. While `audio.ctx.state` is not `running`, resume on the next gesture. A synthetic
+  `pointerdown` is not a user gesture at all (research 08: audio never unlocked).
+- **Decode at load.** A clip first decoded on its first play is silent that time.
+- **A fresh `BufferSource` per hit, about 8 voices per sound, a short cooldown per contact.** One
+  sound per overlapping frame turns one hit into four (the tide-pool chime in the skill's worked
+  example read `sounds` +4 per match until a 50 ms cooldown made it 1). ±6% pitch jitter keeps a
+  repeated sound from reading as a loop. For the sounds a player hears most (footsteps, the core
+  hit), Held Note generated 2–4 takes and picked one at random per play with ±4% pitch and ±2 dB,
+  which hid the repeat better than jitter on one take.
+- **Voices over everything else.** Duck music and beds under a voice line, and let a sound
+  behind a wall go through a low-pass (Held Note's occlusion), so the voice and the room stay
+  legible.
+- **Mute where the player looks first.** Players who want silence look on the first screen and in
+  the HUD; a mute that resets on reload, or lives only in a settings menu, sends them away.
+- **Duck under the payoff** by about 30% for about 400 ms, so the payoff owns its moment.
+
+## The module
+
+```ts
+import { AudioEngine } from '@funpixel/sdk/audio';
+
+export const audio = new AudioEngine({ iosPatch: false }); // the ringer switch mutes the game
+const sfx = audio.ctx.createGain(); sfx.connect(audio.master);
+const music = audio.ctx.createGain(); music.gain.value = 0.8; music.connect(audio.master);
+let muted = false;
+try { muted = localStorage.getItem('tidepool:muted') === '1'; } catch {}
+audio.master.gain.value = muted ? 0 : 1;
+export function setMuted(m: boolean) {
+  muted = m; audio.master.gain.value = m ? 0 : 1;
+  try { localStorage.setItem('tidepool:muted', m ? '1' : '0'); } catch {}
+}
+const wake = () => { void audio.unlock(); if (audio.ctx.state !== 'running') void audio.ctx.resume(); };
+for (const t of ['click', 'pointerup', 'keydown']) addEventListener(t, wake);
+
+const bufs = new Map<string, AudioBuffer>(), live = new Map<string, number>(), last = new Map<string, number>();
+export let sounds = 0; // read by __FPX_STATE__
+export async function load(id: string, url: string) {
+  bufs.set(id, await audio.ctx.decodeAudioData(await (await fetch(url)).arrayBuffer()));
+}
+export function play(id: string, gain = 1) {
+  const buf = bufs.get(id), now = audio.ctx.currentTime;
+  if (!buf || (live.get(id) ?? 0) >= 8 || now - (last.get(id) ?? -1) < 0.05) return;
+  const src = audio.ctx.createBufferSource(), g = audio.ctx.createGain();
+  src.buffer = buf; src.playbackRate.value = 1 + (Math.random() * 2 - 1) * 0.06; g.gain.value = gain;
+  src.connect(g).connect(sfx);
+  live.set(id, (live.get(id) ?? 0) + 1); last.set(id, now); sounds++;
+  src.onended = () => live.set(id, (live.get(id) ?? 1) - 1);
+  src.start();
+}
+export function loopMusic(id: string) {
+  const src = audio.ctx.createBufferSource();
+  src.buffer = bufs.get(id)!; src.loop = true; src.connect(music); src.start();
+  return src;
+}
+export function duck(depth = 0.3, ms = 400) { // under the payoff: the music steps back, then returns
+  const g = music.gain, t = audio.ctx.currentTime;
+  g.cancelScheduledValues(t); g.setTargetAtTime(0.8 * (1 - depth), t, 0.02); g.setTargetAtTime(0.8, t + ms / 1000, 0.1);
+}
+```
+
+Music that follows play (layers, a stinger, a low-pass for danger) builds on the `music` bus here:
+[adaptive-music.md](adaptive-music.md).

package/plugins/robin/skills/funpixel-audio/references/measure.md

@@ -0,0 +1,101 @@
+# Measuring a sound you cannot hear
+
+Detail for steps 5 and 6 of `funpixel-audio`. The numbers pick between takes, catch duds and set
+levels. Taste stays with the person: they listen to the picks you name.
+
+## In the page
+
+Paste into the running game's page (`npx @funpixel/tools dev`, then your browser tool's evaluate
+step or the devtools console). It decodes the file with Web Audio and changes nothing.
+
+```js
+async function measureSound(url, { bpm } = {}) {
+  const ctx = new OfflineAudioContext(1, 1, 44100);
+  const buf = await ctx.decodeAudioData(await (await fetch(url)).arrayBuffer());
+  const ch = buf.getChannelData(0), sr = buf.sampleRate, db = (v) => 20 * Math.log10(Math.max(v, 1e-9));
+  let peak = 0, onset = -1;
+  const floor = 10 ** (-50 / 20); // −50 dBFS counts as silence
+  for (let i = 0; i < ch.length; i++) {
+    const a = Math.abs(ch[i]);
+    if (a > peak) peak = a;
+    if (onset < 0 && a > floor) onset = i;
+  }
+  const rms = (from, to) => {
+    let s = 0; for (let i = from; i < to; i++) s += ch[i] * ch[i];
+    return Math.sqrt(s / Math.max(1, to - from));
+  };
+  let loud = 0; const w = Math.floor(0.3 * sr); // loudest 300 ms window
+  for (let i = 0; i + w <= ch.length; i += Math.floor(w / 4)) loud = Math.max(loud, rms(i, i + w));
+  const edge = Math.floor(0.05 * sr); // first and last 50 ms, for loops
+  const bars = bpm ? buf.duration / ((60 / bpm) * 4) : null;
+  return {
+    seconds: +buf.duration.toFixed(2),
+    onsetMs: onset < 0 ? null : Math.round((onset / sr) * 1000),
+    peakDb: +db(peak).toFixed(1),
+    loudestRmsDb: +db(loud).toFixed(1),
+    loopJumpDb: +(db(rms(ch.length - edge, ch.length)) - db(rms(0, edge))).toFixed(1),
+    bars: bars && +bars.toFixed(2),
+    bytes: +(await (await fetch(url)).blob()).size,
+  };
+}
+// await measureSound('assets/sfx/flip-b.mp3')
+// await measureSound('assets/music/pool.mp3', { bpm: 92 })
+```
+
+## Reading it
+
+| Field | Keep | Reject or fix |
+|---|---|---|
+| `onsetMs` on a one-shot | under about 50 | over 150: the hit lands late; take the other take |
+| `peakDb` | −1 or lower | above −1 (clipping risk); lower its gain in code |
+| `loudestRmsDb` | anything above −40 | under −40: a dud, nearly silent; regenerate |
+| `seconds` on a one-shot | near the length you asked for | far longer: a tail or a second event crept in |
+| `loopJumpDb` on a loop or music | within about ±3 | a level step at the seam; try the other take or cut |
+| `bars` on music | close to a whole number | a fraction: the loop point falls mid-bar and the beat stumbles |
+| `bytes` | 1,048,576 or less | re-encode (below) or use a clip instead of a full track |
+
+For two takes of one effect, keep the one that passes every row with the earliest onset. Tell the
+person which you kept and why, and which file to listen to.
+
+## Levels in code
+
+The loudest-window RMS is a stand-in for loudness. Aim the classes relative to each other, since
+that is what the player hears:
+
+| Class | Target | In code, relative to one-shots |
+|---|---|---|
+| One-shot effects | −16 LUFS | 0 dB (gain 1) |
+| Music | −18 LUFS | about −2 dB (gain 0.8) |
+| Loops and ambience | −22 LUFS | about −6 dB (gain 0.5) |
+
+When two one-shots of the same class differ by more than about 4 dB in `loudestRmsDb`, give the
+louder one a per-sound gain so they sit together. Never raise a quiet file above gain 1 to match:
+lower the loud ones instead, so nothing clips.
+
+## With ffmpeg on the machine
+
+If `ffmpeg` is installed (check with `ffmpeg -version`; never add it to the game), you can master
+the file itself instead of compensating in code. Work on a copy, then replace the file under
+`public/assets/`:
+
+```sh
+# measure integrated loudness and true peak
+ffmpeg -hide_banner -i flip.mp3 -af loudnorm=print_format=summary -f null -
+# one-shot at −16 LUFS, peak −1, with leading silence trimmed
+ffmpeg -i flip.mp3 -af "silenceremove=start_periods=1:start_threshold=-50dB,loudnorm=I=-16:TP=-1" -b:a 128k flip-m.mp3
+# music at −18 LUFS, mono 96 kbps to fit under 1 MiB
+ffmpeg -i pool.mp3 -af loudnorm=I=-18:TP=-1 -ac 1 -b:a 96k pool-m.mp3
+```
+
+`loudnorm` cannot measure a clip under about 0.4 s (its integrated loudness needs longer blocks),
+and on short files it silently changes how it behaves. Held Note (29 Sep 2026) levelled its short
+sounds by their loudest 100 ms instead (the snippet above uses a 300 ms window; shorten `w` for
+clips that short), and kept `loudnorm` for music and loops.
+
+Trim silence on one-shots only; a loop trimmed at its start no longer loops. Do not encode to Ogg:
+Safari refuses it.
+
+## When nothing can be measured
+
+If the page cannot decode a file, that is a finding, not a skip: a file the browser cannot decode
+never plays. Regenerate it, and say in the hand-back which file failed and what stands in.

package/plugins/robin/skills/funpixel-audio/references/unity.md

@@ -0,0 +1,73 @@
+# Audio that plays, loops and sits at the right level
+
+The audio bug these games hit most was no sound at all. Four games went to TestFlight silent, because a camera made in code with `AddComponent<Camera>()` has no AudioListener and Simulator captures carry no audio, so nothing an agent looked at showed the fault. This skill makes silence, gapped loops and wrong levels fail a check, and ends with a person listening.
+
+## Tools
+
+The studio's `com.joydle.core` package carries the player side (funpixel-unity-game, `references/studio-packages.md`): `Sfx.Create(musicClip)` makes 8 pooled one-shot sources and one looping music source at volume 0.45 and calls `Sfx.EnsureListener()`, which adds an `AudioListener` when none exists; `Play(clip, volume)` jitters pitch by 0.06; `Settings.Sound` and `Settings.Music` are the player's toggles; `BuildTools.SimulatorMuted` builds a Simulator build with audio off for captures and restores the setting after. Not shipped by the kit or the package: the Unity starter, its checks and the studio scripts (the upload pre-flight, a music length check, a one-funnel effect tap, the audio import rule). Do those with what exists:
+
+- Generate into the project: `npx @funpixel/tools gen sound "<cue>" --unity .` (`gen music`, `gen line`; `--loop` for a bed), after `npx @funpixel/tools login`. It lands 48 kHz WAV (ffmpeg trims the MP3's encoder padding) in `Assets/_Game/Generated/Sfx/`, `Loops/`, `Music/` or `Voice/`, and a rule set once per file: effects mono, ADPCM, decompress on load, normalisation off; loops PCM; music Vorbis, streaming. The studio's `gen_sfx.py` and `gen_music.py` call the same providers with `.env` keys: no metering, no cost log.
+- Before every upload, read `ProjectSettings/AudioManager.asset` yourself: `grep "m_DisableAudio: 1"` must find nothing.
+- `npx @funpixel/tools loudness Assets/Audio` reads every cue against its loudness target (ffmpeg EBU R128); ffmpeg's `ebur128`, `volumedetect` and `silencedetect` filters do the same by hand. `npx @funpixel/tools beats Assets/Audio/Music` writes each track's beat map.
+- Music length: an Edit Mode test that compares each clip's `AudioClip.samples` with its reference length.
+- Route every sound, duck and haptic through one class of your own (an effect tap) so an audit runs headless.
+- Import rules in an `AssetPostprocessor` (`OnPreprocessAudio`) in `Assets/Editor/`.
+- ffprobe finds frame gaps in a recording.
+
+Checks: `audio_runtime` and `recording_check` are proposed, not built. The studio's scripts make effects and music with hosted generators; confirm the commercial terms of whichever one a game ships with.
+
+## Procedure
+
+1. Make exactly one AudioListener and assert it at startup. A scene generated by code gets none by default; `Sfx.Create` adds it (or call `Sfx.EnsureListener()`).
+2. Set the project through the setup script, not a copied file: audio on (`m_DisableAudio: 0`) and `m_SampleRate` 48000. A cloned project carried `m_DisableAudio: 1`, and the Simulator mixed at 24 kHz without the rate.
+3. Write import rules in code and change the rule, never the `.meta`. A size pass that edited 190 SFX metas by hand was silently reverted by the rule on the next import.
+
+   | Kind | Format | Load | Note |
+   |---|---|---|---|
+   | SFX | mono, ADPCM or Vorbis | decompress on load | normalize off |
+   | Loops | PCM or exact-length OGG | not in the report | ADPCM pads to 64-sample blocks and clicks; MP3 gaps |
+   | Music | Vorbis | streaming | |
+
+4. Turn import normalisation off: the `.meta` key is `normalize` (grep it), and through a `SerializedObject` the property is `m_Normalize` (read on 6000.6). Left on, it made quiet SFX about 7 dB too loud and positional sounds about 3 dB too loud. Check: `grep -r "normalize: 1"` under the SFX folder returns 0.
+5. Build loops as OGG at exact sample counts, from the web build's `.m4a` when porting. MP3 decodes 1,245–1,997 samples long from encoder padding. Check: decoded sample count equals the reference length for every music clip.
+6. Check each loop seam: the sample jump across the seam is under 0.005.
+7. Measure levels. The report has no shared target; these are the per-game figures to start from.
+
+   | Game | Figure |
+   |---|---|
+   | Pocket Crew | music −18.5 LUFS, peaks at most −1 dBFS |
+   | Stitch Pop | SFX mean −18 to −28 dB; music volume 0.45, about 7 dB under SFX |
+   | Noodle Nights | crowd bed −30 LUFS |
+
+8. Mix in code. No game uses an AudioMixer asset. Dead Letter ports its web mixer: buses, an 8-voice cap, round-robin variants, cooldowns, ±6% pitch, music crossfade, stinger ducks, and a tension loop that ducks music by 4 dB.
+9. In a port, route every sound through one tap so an audit runs headless. Pocket Crew: 468 events, 0 mismatches against the web.
+10. Re-render procedural web audio offline in C# instead of synthesising live. Dawg Ball's 70 clips (17.7 s) warm in 64 ms at boot; The Hot Gates' 41 cues and 3 loops match Chromium sample for sample (138 tests).
+11. Handle interruptions: an Ambient audio session (it respects the silent switch and other apps), sound held on pause and during the studio splash (`JoydleSplash` pauses the game's audio until it ends; start the title music once `JoydleSplash.Playing` is false), resumed after backgrounding, calls or Siri. `OnApplicationPause(true)` also fires on resign-active (Control Center, Siri, call banners, Face ID).
+12. Run `audio_runtime` in the player: 1 listener, 48 kHz output, music playing within 3 s (of the splash's end, when one plays).
+13. Before sharing or uploading any video, run `recording_check`: 0 frame gaps over 34 ms and audio at 44.1 kHz or higher.
+14. Run the numeric lint (LUFS, peak, seam), then have a person listen. An agent can measure audio but not hear it, so the listen is a required gate on every game's ship-blocker list.
+
+Music that follows play: Dawg Ball's crowd volume swells near goals; Dead Letter crossfades and ducks on stingers. No game has layered adaptive music.
+
+## Worked example
+
+Scrap Riot (a 2D port from Pixi), music loops and SFX levels:
+
+1. The MP3 loops decoded 1,245–1,997 samples long, so loops gapped.
+2. The loops were rebuilt as OGG from the web's `.m4a` at exact sample counts. Background music went 96 → 10 MB.
+3. A music check asserts decoded sample count equals the reference length per clip.
+4. Import normalisation had made quiet SFX about 7 dB too loud and positional sounds about 3 dB. The fix used the `normalize` key across all SFX metas.
+5. Still required after the numbers: a person's listen.
+
+## Common mistakes
+
+- A code-made camera with no AudioListener: all four first games reached TestFlight silent; it cost one TestFlight round for three of them. `funtools doctor` warns when nothing adds one.
+- A cloned ProjectSettings: Dead Letter inherited `m_DisableAudio: 1`; the studio's upload pre-flight (proposed for the kit) caught it.
+- No 48 kHz setting: The Hot Gates mixed at 24 kHz and sounded muffled.
+- MP3 or ADPCM for loops: gaps (Scrap Riot) or clicks.
+- Uncommitted reimports: two review builds (Dead Letter, Scrap Riot) carried 190 reimported `.wav.meta` files, so main no longer matched what Apple reviewed.
+- Showing a recording before measuring it: a `simctl recordVideo` capture of The Hot Gates had 19 frame gaps up to 0.85 s and 24 kHz audio, cost about 1 h and was cancelled.
+- Generated audio nobody heard: Dawg Ball's 70 sounds, as of 29 Sep.
+- Many relaunches wedge the Simulator's CoreAudio (crash at audio init); `BuildTools.SimulatorMuted` (audio off for that build only, restored after) avoids it for capture runs, and the upload pre-flight refuses any build with audio off.
+- `git commit -a` after a headless run: every run rewrites AudioManager.
+- The silent switch mutes Unity's Ambient session; accepted for casual games.

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

@@ -0,0 +1,163 @@
+---
+name: funpixel-brief
+description: "Use when starting, resuming or finishing work on a Funpixel game (a folder with a funpixel.json), before the first edit. The always-on brief: the loop, the silent failures, red flags, spending, hosted and local tools, and which skill covers each job."
+---
+
+<!-- funpixel-gdk:brief -->
+# Game development with the Funpixel toolkit
+
+Start with the creator's goal. An asset repair stays an asset repair; a new game gets the path
+below. The creator and host agent own scope, style and workflow. Recipes here and in the
+skills are defaults, not boundaries: keep locked choices, explore open ones, find another way when
+no recipe fits.
+
+Assets work in any engine; build, preview and publish target browser games (Pixi 8 or Three.js,
+Preact, the SDK).
+
+## The shelf
+
+Skills hold what great looks like, with numbers; each loads in one call (Skill tool or `SKILL.md`):
+- starting, planning or reshaping a game, the GDD: `funpixel-gdd`; code, the SDK, multiplayer:
+  `funpixel-game-spine`; rules, levels, balance, depth and replay: `funpixel-game-logic`
+- the look, 2D art, light and effects: `funpixel-art`; 3D models, the bench and levels: `funpixel-3d`
+- feel and payoffs: `funpixel-game-feel`; a place with a story: `funpixel-world-and-story`; sound
+  and music: `funpixel-audio`; phone HUD, touch: `funpixel-mobile-ui`
+- proving it plays, the panel and blind player: `funpixel-verify`; dev log: `funpixel-feedback`;
+  publish, trailer, store shots, playable ads: `funpixel-publish`; a store: `funpixel-store`;
+  Unity: `funpixel-unity-game`
+
+The session start names the few this game needs. Local hooks advise (`funpixel.json` `gdk.gate`:
+`"block"` or `"off"`; `FUNPIXEL_GDK_GATE`); no setting changes publishing's own checks.
+
+## The path
+
+For a complete game, the path our best games took: you are the person's copilot, not an autopilot.
+A plan made with them is a contract, target frames show what done looks like, and every round
+closes the gap between the two. The locked plan
+is the job; how you build it is yours. Why, tool and signal per step:
+`funpixel-gdd/references/the-path.md`.
+
+Start each session from `npx @funpixel/tools flow`: the owner's notes first (they outrank an
+agent's claim), then the one next step. After every step, a short status in the chat with a
+capture of the build: the owner watches and steers.
+
+1. **Brief back, one screen, one question.** A short brief (title, kind, verb, world, length,
+   failing, look, platforms), your calls in a line each, then one question: is it right? Decide
+   the rest and say it: their ask outranks a standing request.
+2. **First look, then a first playable.** The key art and the hero's reference sheet, shown in
+   the chat for the owner to steer. Then a playable built from them with real assets (the hero,
+   the place in the key art's light, title, music, the verb's sounds), sized by the game (short:
+   about 1 minute; long: 3 to 5), judged against the key art. They play: potential, or not.
+3. **Plan the whole game around it** (skill `funpixel-gdd`): the genre's best, pillars, story,
+   levels and maps, fun and wow moments, screens and HUD, a numbers contract with named tests,
+   the rest of the first look (target frames), the asset list with its price.
+4. **Lock** (`flow ask`): the owner's "looks good, let's build" (price shown; not a cap). It
+   stands until they say otherwise; a new direction is a new GDD version locked again; a
+   departure goes in "Where the build moved", with why.
+5. **Sim first** (`sim`, `test`), then **build with the assets as they land** in `public/assets/`,
+   each judged under the game's light. The slice: one verb, a win and a loss, progress, keys and
+   touch, `check` exits 0.
+6. **Each round, the look-dev loop**: capture at the target moments, set each beside its target
+   (`compare --target`), fix the biggest difference, then play it (`play`, `playtest`). Repeat
+   until each beat is close. Matching the targets is the job, never a style choice: only the owner
+   relaxes a target.
+7. **Extend** chapter by chapter (each to its targets, then the owner's yes); fold a new
+   request into the pillars first.
+8. **Finish when the person plays it and says yes.** Green means stop. When verify passes and the
+   goal is met, stop editing. No renames, restyles or polish nobody asked for; they break what
+   worked and hide which change did what.
+Hand back what plays now (keys and touch), what is out on purpose, the next two or three steps,
+and every stand-in. File the dev log with `report_feedback` before you finish.
+
+## A funtools scaffold
+
+A folder `funtools init` made is a finished frame around a demo round (`init --bare`: none). Replace
+the demo with your game (`rules.ts`, `session.ts`, `game.ts`, `feel.ts`, `hud.tsx`, `screens.tsx`,
+`look.json`, a check per mechanic in `funpixel.json`); keep the frame, host integration and checks.
+
+## Silent failures
+
+- dt is in seconds and clamped: `dt = Math.min(dt, 0.1)`. A background tab hands you one huge
+  frame and everything tunnels. Pixi: `ticker.deltaMS / 1000`, never `deltaTime`.
+- Resize with `setupGameResize((w, h) => …)` from `@funpixel/sdk`, never a `resize` listener or
+  `resizeTo: window`: those miss iframe resizes. It fires once at the call, so create the renderer
+  first.
+- Audio: one `new AudioEngine({ iosPatch: false })` from `@funpixel/sdk/audio`; connect every
+  source to `audio.master` and call `audio.unlock()` from the first click, pointerup or keydown.
+  `iosPatch: false` lets the iPhone ringer switch mute the game; pass `true`
+  only when sound is the game (rhythm, music). Keep an existing game's choice.
+- Pointer handlers use `addEventListener`. Assigning `onpointerdown = …` twice kills the first
+  control without an error.
+- Three: GLBs need `DRACOLoader`, `KTX2Loader` and the meshopt decoder with same-origin decoder
+  paths, an environment map (they render flat grey without one), and `mixer.update(dt)` every frame.
+- Pixi: every display object gets a `.label`; `window.__PIXI_APP__ = app` after `app.init()`.
+- Room codes, share codes and seeds carry `data-funpixel-selectable` (else they cannot be copied).
+- `@funpixel/sdk` is pinned exactly (`"0.6.0"`). Import the root only for `setupGameResize`;
+  everything else from a subpath. Multiplayer is `Room.autoJoin(getGameKey(), …)`, never a raw
+  WebSocket (skill `funpixel-game-spine`).
+- A performance fix changes how a frame is made (pooling, atlases, instancing), never what it shows.
+- Assets arrive as expiring URLs: `npx @funpixel/tools job <id> --wait --out public/assets/<file>`;
+  never base64 in code.
+- Hosts may refuse chains, loops, `sed -i`, heredocs and outside paths: use the edit tool, one
+  command per call (`doctor --host`); keep captures in `design/shots/`.
+
+## Red flags: thoughts before broken games
+
+- "It compiles, so it works." Verify it; a runtime crash builds green.
+- "I'll cast it to make the error go away." Look the name up (skill `funpixel-game-spine`); `as any` and
+  `?.` compile code that does nothing.
+- "The class exists, so the feature exists." Trace it from boot, the loop or an input handler, and
+  give it a check.
+- "The shapes will do for now." They won't: make the planned asset. A shape is only a fallback
+  until it lands; name every one still in the game at hand-back.
+- "The Play button surely works." Press it (skill `funpixel-verify`, front door).
+
+## Spending
+
+Scope, time and spend are the creator's: never shrink an agreed game to save them. The locked plan
+is the go-ahead for its assets: make them (pass `confirm_cost`); before each paid call say the
+route and its cost in one line. No budget unless the owner sets a cap. Out of credits is a pause: say so;
+they top up and you go on. Long jobs return an id: collect
+with `get_job`. Never end a session (headless `-p` too) while a background job, subagent
+or recording runs: a session that ends does not come back. Do the work in the session.
+
+## Hosted and local
+
+The Funpixel MCP does the paid and hosted work; `funtools` runs locally and free. When the MCP is
+not connected, use the local column and say which steps you could not do.
+
+| Job | MCP tool | Local (`npx @funpixel/tools …`) |
+|---|---|---|
+| New game | `create_game`, only with no local files (`init` mints the id) | `init` |
+| Build and preview | `build`, `preview` | `npm run build`, `dev` |
+| Check it plays | `probe`, `screenshot` (`click` presses Play) | `verify`, `verify --watch`, `verify --front-door` |
+| Look at a state | `capture_view`, `audit_screens`, `inspect_scene` | `capture` (`--all`: every view), `audit-screens`, `scene` |
+| Critic panel, blind player | `review`, `play` | `playtest`: `critic`, `player` agent seats |
+| Images, sprites, sheets | `generate_image`, `generate_sprite`, `edit_image`, `generate_spritesheet` | `gen image\|sprite\|edit\|sheet`, `assets gen` |
+| Sound and music | `generate_sound`, `generate_music` | `gen sound`, `gen music` |
+| 3D models | `generate_3d_model`, then the bench tools (skill `funpixel-3d`) | `gen model3d`, `model …` (`--local` on your Blender) |
+| Publish | `publish_game` | `publish` (needs `funtools login`) |
+| Dev log and feedback | `report_feedback` | lines in `.funtools/devlog.jsonl` |
+
+## In Robin
+
+**funtools is a tool here, not a command.** Robin has no shell; the plugin adds funtools as a local server named
+`funtools`, so every `npx @funpixel/tools <command>` in the skills is the `funtools.<command>` tool: `flow` →
+`funtools.flow`, `flow start` → `funtools.flow_start`, `flow ask` / `flow agree` / `flow round` → `funtools.flow_ask` /
+`funtools.flow_agree` / `funtools.flow_round`, `check`, `verify`, `test`, `sim`, `capture`, `compare`, `score`,
+`reel` as named, `compose render` → `funtools.compose_video`, `assets script` / `assets gen` →
+`funtools.assets_script` / `funtools.assets_gen`, `note add` /
+`note verdict` → `funtools.note_add` / `funtools.note_verdict`, `progress card` → `funtools.progress_card`, and any
+other command → `funtools.run` with its words. Every call names the game folder as `dir`, an absolute path.
+
+**Robin's own tools where they are better:** the game beside the chat is `funtools.dev` (it returns the address)
+opened with `browser.open` in Robin's browser; a picture into the chat is `funtools.image`; phone play is the
+iOS simulator (`sim.*`). Publishing stays the person's: prepare it, and they run `funtools publish`.
+
+**Lanes run at once through `agent.delegate`** (up to 4): `funtools.run` with `["lanes","start","--all"]` prints the
+call, one task per lane, each telling its worker that it has no shell and which checkout every `funtools.*` call names.
+Each lane keeps its own game running (`funtools.dev` in its checkout), so the Games bench shows every part live.
+
+Hosted tools, connected under the name Funpixel, are `funpixel.<tool>` (`funpixel.probe`,
+`funpixel.generate_3d_model`); if they are not offered, `kit.load` the `funpixel` kit or call one by name.
+Robin reads a game's AGENTS.md only to its first 6,000 bytes, so load this skill rather than trusting that copy.

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

@@ -0,0 +1,120 @@
+---
+name: funpixel-feedback
+description: Use when a step, test, dead end, lesson or decision happens while building a game, when the person changed the game by hand, and before ending a session that changed one. Covers the dev log with costs, the end-of-session report, the kit verdict and the game's memory (journal and decisions).
+---
+
+# The dev log and feedback
+
+Funpixel improves from what sessions report: which tool was missing, what the agent rebuilt by
+hand, which trap cost an hour. Our studio's dev log, which a
+Stop hook enforced and a person read, gathered 412 entries in two days (49 dead ends and 44
+lessons, most with a cost). This skill is that log, and the Stop hook reminds you of it until it is
+filed.
+
+## Tools
+
+- `report_feedback` files the session's entries, its report and the kit verdict with Funpixel. The
+  game is optional: a game the server has never seen is filed without one.
+- Without the MCP, or when the call fails: the same entries, one JSON object per line, in the
+  game's `.funtools/devlog.jsonl` (the kit verdict in `.funtools/kit-feedback.jsonl`), written with
+  your file tools, or one line per call: `npx @funpixel/tools feedback log "…" --kind lesson`.
+- `npx @funpixel/tools feedback collect <folders…>`: the owner first, what worked ranked by its
+  measured change, dead ends by hours burned, A/B records, kit tools; `--propose` drafts kit
+  edits, `--html page.html` writes one page.
+- The game's own memory, read at session start: `journal` (what the person changed and why) and
+  `decide` (choices against their alternative, `--supersedes` to replace one). Which record
+  goes where: [references/memory.md](references/memory.md).
+
+## 1. Log as you go
+
+One entry per event, written when it happens, not reconstructed at the end:
+
+| kind | When | Example text |
+|---|---|---|
+| `step` | a milestone reached; a progress card writes it (one event, not two) | "first slice passes verify: drag swings the cradle, windows score" |
+| `test` | a check added or a measurement taken | "levels 1-50 solvable; median solver depth 9 rising to 21" |
+| `dead-end` | something tried and abandoned | "keyed the pigeon sprite three times; the white feathers kept the green" |
+| `lesson` | a fact the next session needs | "Pixi deltaTime is frames; use deltaMS / 1000" |
+| `decision` | a choice with an alternative | "platformer card without a jump; the verb is swinging" |
+| `worked` / `didnt` | a change measured to help, or not | "lean AO masks: phone p95 34 -> 25.5 ms" |
+| `owner` | the owner's words or verdict | "the walk is still a cut-out; legs must stride" |
+
+Fields: `kind`, `text` (one or two sentences), and where known `cost_usd` (a number), `minutes`,
+`minutes_lost`, `evidence` (a path), `sha`, `test`, and for `worked`/`didnt` `metric`, `before`,
+`after`, `unit`. Unfound evidence reads as unverified. Dead ends carry their time and cost. More:
+[references/memory.md](references/memory.md).
+
+## 2. Report what was missing
+
+Before finishing, one report with one category per item:
+
+| category | Use when |
+|---|---|
+| `tool_gap` | a Funpixel tool was missing or too narrow |
+| `workaround` | you built something the platform should have done; say where it lives and what it cost |
+| `provider_failure` | a generation was refused, failed or came back wrong; say whether a retry cleared it |
+| `verification_gap` | something you could not prove with verify, probe or review |
+| `knowledge_gap` | a trap a skill would have prevented |
+| `platform_trap` | build or publish behaviour that silently broke the game |
+| `built_custom` | you hand-wrote a system a package or the SDK could have given |
+| `package_gap` | an npm package you wanted and could not use |
+| `prompt_feedback` | an instruction in this kit was wrong, unclear or contradicted another |
+| `quality_note` | anything else about the result's quality |
+
+Each item: `category`, `text`, and where they apply `pipeline_step` (plan, assets, code, verify,
+review, publish), `blocking` (true or false), `attempted_first`, `cost`, `evidence_path`, and
+`suggested_home` (`mcp_tool`, `cli`, `skill` or `server`). Nothing was missing is a valid report:
+say so in one `quality_note`, with what went well.
+
+## 3. File it
+
+With the MCP: one `report_feedback` call carrying the dev-log entries since the last report and the
+items above.
+
+Without it (or when the call fails), write lines to `.funtools/devlog.jsonl` in the game folder
+with the Write or Edit tool; hosts refuse a shell redirect and your home folder. It never ships.
+Each line carries the time, and the report goes in a line with `"kind": "feedback"`, which is what
+the Stop hook looks for:
+```json
+{"at":"2026-09-26T14:02:11Z","kind":"dead-end","text":"keyed the pigeon sprite three times; the white feathers kept the green","cost_usd":0.39}
+{"at":"2026-09-26T14:40:05Z","kind":"feedback","items":[{"category":"tool_gap","text":"no key for near-white sprites; drew the feathers in code instead","pipeline_step":"assets","blocking":false,"suggested_home":"mcp_tool"}]}
+```
+
+## 4. The kit verdict
+
+At the hand-back of a complete game (the Stop hook asks once; `/fp:playtest` ends with it) say how
+the kit did: the tools, skills, hooks and commands, not the game. Each item adds `kind` (`worked`,
+`hurt` or `missing`) and `tool` (what it is about: `verify`, `capture --all`, `funpixel-art`,
+the Stop hook). Pick the category that fits; one line with `tool` `kit` says whether the kit did
+well or let you down, and why. Honest either way: a tool that cost an hour is worth more to us
+than praise.
+```json
+{"at":"2026-09-29T18:02:11Z","kind":"kit-verdict","items":[{"category":"verification_gap","kind":"hurt","tool":"audit-screens","text":"flagged below-the-fold scroll content as clipped; paged the list to pass"},{"category":"quality_note","kind":"worked","tool":"kit","text":"Overall: did well; verify caught two real bugs"}]}
+```
+That line is the fallback in `.funtools/kit-feedback.jsonl`; with the MCP the same items go in the
+`report_feedback` call.
+
+## When a person played it
+
+Ask for, or record, four things: in the first five minutes, did they know the goal and the
+controls; where were they confused; what delighted them; their top three changes. Log their words as
+`owner` lines; they outrank any agent's claim.
+
+## Worked example
+
+A session added a boss to a shooter. The log gained: `step` "boss fight passes verify", `dead-end`
+"generated the boss as one sheet of 16 frames; frames 13-16 were one pose; regenerated as 4x3"
+(cost 0.26), `lesson` "sheets over 12 frames repeat poses". The report: `workaround` "wrote a
+frame-difference check to find repeated sheet frames" (suggested home `mcp_tool`, blocking false),
+`verification_gap` "verify cannot tell whether the boss's attack telegraph is readable". One
+`report_feedback` call filed both.
+
+## Common mistakes
+
+- Writing the log at the end from memory: the dead ends and their costs are gone.
+- "Everything worked" when you rebuilt a platform feature by hand: that is a `workaround`.
+- Costs typed as `$0.26` in a shell command: the shell expands `$0`.
+- Filing feedback about the person's idea; this is about the tools and the kit.
+- A `worked` line with no numbers or evidence: it ranks last and reads as unverified.
+
+Where this comes from: our studio's dev log and the kit-verdict loop.

package/plugins/robin/skills/funpixel-feedback/references/memory.md

@@ -0,0 +1,99 @@
+# The game's memory: what the person changed, what was decided
+
+A diff says what moved. It cannot say that the person slowed the ghosts on purpose because their
+kids kept losing, or that tap-to-jump beat swipe after a bus ride. Without that, the next session
+"fixes" the slow ghosts back to the design number, or re-opens the control question and quietly
+reverses it. Two small files carry the why across sessions; both are private (they never ship,
+and `funtools export` leaves them behind), and both are read at session start.
+
+| File | Holds | Written by |
+|---|---|---|
+| `.funtools/journal.jsonl` | one line per change a person made: who, what, why, when, files or values | `npx @funpixel/tools journal`, and the hooks when files moved between agent turns |
+| `design/decisions.md` | each choice against its alternative, with the reason, an id (`D3`) and a date | `npx @funpixel/tools decide`, or by hand |
+
+When neither file exists the session start says nothing about them; an empty memory is not a
+problem to fix.
+
+## The creator's journal
+
+For the person's own changes: a number tuned in the editor, a sprite they redrew, a level they
+reordered, a line of copy they rewrote.
+
+- The person, in a terminal: `npx @funpixel/tools journal "ghost speed 4 → 3.2" --why "my kids lost in 20 s" --values ghostSpeed=3.2 --files src/feel.ts`.
+- You, when the person tells you in chat what they changed by hand, may record it for them with
+  the same command; the entry says it came through the agent (the host's own shell says so, not
+  a guess), with `--by` naming the person if they gave a name.
+- Detected entries: the hooks keep what the files looked like when an agent last touched them
+  (every Stop, and each file a Write or Edit call wrote). When a session starts, or the person
+  sends a message, and shipping files or design notes differ from that, one entry is added,
+  marked detected: the files certainly moved, but who moved them and why is unknown (a person, a
+  `git pull`, a turn that was interrupted before its Stop). It names no person and invents no
+  reason.
+
+What the session start shows: the last five entries, then a short line. What to do with them is
+yours to judge; what worked in the studio's games:
+- Read a changed file again before editing it, rather than trusting a copy from earlier in the
+  conversation; the person may have moved things since.
+- Keep a told change unless the person asks otherwise. If it now fights the design, say so and
+  offer both, rather than reverting it.
+- A detected change is a fact about bytes, not about intent. When it matters (a tuned number, a
+  deleted level), one question settles it; when it is plainly a pull or a formatter, carry on.
+
+## The decisions log
+
+For choices a later session could plausibly reverse: the control scheme, the camera, the art
+medium, a number a playtest settled, a feature cut on purpose, a pillar bent at the person's
+request. Not every small call: if nobody would ever argue it, it is not a decision worth an id.
+
+`npx @funpixel/tools decide "tap anywhere to jump" --over "swipe up" --because "one thumb on a bus; swipes misfired at 60 fps"`
+appends `D<n>` to `design/decisions.md`. A decision reads best against what it beat (`--over`);
+one that names no alternative is the one that gets re-argued.
+
+Changing your mind is normal and creative freedom stays whole: a later decision may replace an
+earlier one with `--supersedes D3`. The old entry stays, marked `Superseded by: D5`, so anyone can
+see the path the design took and why. The session start lists only the live ones; `decide` with
+no text lists both, and `npx @funpixel/tools gdd` shows the live ones beside the GDD's score.
+
+Why a file of its own and not a GDD section: the GDD is rewritten whole at each version (v0.1,
+v0.2, as built) and states the design as it is now. The log keeps how it got there and survives
+every rewrite. The GDD's `Decision:` lines can cite an id ("Decision: D4, tap to jump"), so the
+two agree without repeating each other.
+
+## Where each record goes
+
+| Something happened | Where |
+|---|---|
+| The person changed the game by hand | the journal |
+| A design choice with a real alternative was settled | the decisions log (and the GDD's current text) |
+| A step, test, dead end or lesson of this session, with its cost | the dev log (`feedback log`) |
+| A finding the next game of this genre should start with | `lessons add` |
+
+One event can belong in two places: a choice settled after a dead end is a `dead-end` in the dev
+log and a decision in the log. The dev log is the session's story for Funpixel; the decisions log
+is the game's own record for whoever works on it next.
+
+## Measured outcomes, the owner and what logs itself
+
+The dev log is also how the kit learns which practices work. `npx @funpixel/tools feedback collect`
+ranks what worked by its measured change, so give a `worked` or `didnt` line its numbers:
+
+```
+npx @funpixel/tools feedback log "lean AO masks and skipping frozen rigs" --kind worked --metric "phone p95" --before 34 --after 25.5 --unit ms --evidence src/view/aoLean.ts
+npx @funpixel/tools feedback log "lighting passes on melted walls" --kind dead-end --minutes-lost 600
+npx @funpixel/tools feedback log "the walk is still a cut-out" --kind owner --verdict reject --screenshot design/shots/walk.png
+```
+
+- Evidence: `--evidence` (a path in the game), `--film`, `--sha` (a commit), `--test` (a test name);
+  each is checked to exist, at once and again by `collect`. A line whose evidence is not found reads
+  as unverified; words that name no file ("the deaths page") read as unverified too.
+- A lesson that says it fixed something ("…fixed it", "now always recovers") counts as worked, and a
+  "34 -> 25.5 ms" in its words is read as its measured change.
+- The owner outranks: owner lines and every game's open pipeline notes (`note add "…" --stage <s>`,
+  closed only by evidence, reopened by the owner's `note verdict N reject "…"`) lead the report.
+- What logs itself: `sim` (the naive bot's lost runs, its warnings), `play` (high defects), `hook`
+  and `life` (warnings, movers), `profile` (frame p95) and `playtest` (the panel's mean) append a
+  `measure` line with the last value as `before` (`FUNTOOLS_NO_AUTOLOG=1` turns it off). A game's
+  post-merge hook can run `npx @funpixel/tools feedback merged`: the merge becomes a `worked` line
+  with the numbers that moved since its merge base.
+- A/B records: `feedback ab "<game>" --routes gdk,non-gdk --overall 7.0,8.0 --axes "story=7.0/8.7"
+  --winner non-gdk --judges "3 blind seats"`; `collect` says where a route keeps losing.