@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/robin/skills/funpixel-audio/references/adaptive-music.md

@@ -0,0 +1,204 @@
+# Music that follows the game
+
+Adaptive music the way the hits do it, sized for generated takes. The `Music` class below ran in a
+scratch scaffold against the real Web Audio graph (`@funpixel/sdk/audio` 0.6.0, Chrome): a threat
+at 1.0 took the tense layer from 0 to 1.00 and the calm one to 0.05 within 1.5 s; when it left,
+calm was back to 0.99 about 7 s later; `muffle(0)` closed the low-pass to 621 Hz in 0.6 s; a
+stinger ducked the bus from 0.80 to 0.40 and it returned to 0.80 after the stinger.
+
+## What the hits do
+
+- **Hades** (Darren Korb): stems of one track; drums and bass enter when enemies are in the room
+  and drop out on the last kill; a boss brings every stem in; a short tag closes the fight.
+- **Mini Metro** (Disasterpeace): the city writes the score; each line and train is a voice.
+- **Celeste, Hollow Knight**: an area has a theme; a set piece swaps to a variation of it; a
+  safe place has its own quiet music, so arrival is heard.
+- Common thread: one musical identity, several intensities of it, changes on musical boundaries,
+  and silence or a thin texture where tension should build.
+
+## What `generate_music` can make
+
+- One call = one take. `length: "clip"` is a ~30 s Lyria clip (about 8 credits); `"full"` is a
+  longer pro track (about 16) that often needs trimming to fit 1 MiB. No stems: layers come from
+  separate takes briefed to fit together.
+- Mastering cuts music to whole 4/4 bars at the tempo **named in the brief** ("… 96 bpm …") and
+  says so in the result: "cut to N bars at 96 BPM to loop seamlessly". Read that line: it is the
+  loop length you will mix against. Without a bpm in the brief the tempo is estimated.
+- Nothing makes two takes match: the brief asks for a key and tempo, the model is free, and the
+  mastering picks the bar count per take. Compare the "cut to N bars" lines and the durations
+  before choosing how to combine them (the table below).
+- `instrumental: true` for anything under play.
+
+## Briefing takes that layer
+
+Write one identity line and repeat it in every take; change only the energy words:
+
+```text
+calm:  "Warm dusk folk: nylon guitar, soft felt piano, low cello drone, 84 bpm, D minor, sparse, no drums, steady tempo, no intro swell, no ending, seamless loop"
+tense: "Warm dusk folk: nylon guitar, soft felt piano, low cello drone, 84 bpm, D minor, driving frame drum and pulsing low strings, urgent, steady tempo, no intro swell, no ending, seamless loop"
+wonder: "Warm dusk folk: nylon guitar, soft felt piano, low cello drone, 84 bpm, D major, rising choir pad and bells, open and bright, steady tempo, no intro swell, no ending, seamless loop"
+```
+
+Stingers: a two-to-four second `generate_sound` ("bright bell swell rising into a single held
+chord, one event, no music, no voice") or a short cut from a `wonder` take's first bar.
+
+## Two ways to put takes together
+
+| Takes | How | Why |
+|---|---|---|
+| Same bar count at the same tempo (durations match to a few ms) | `start()` all of them at one instant, `mix()` or `intensity()` their gains | layers stay locked; a fight fades drums in without a seam |
+| Different lengths | `switchOnBar()`: the new take starts from its top on the next bar line while the old fades over one bar | a change on the beat reads as intended; a mid-bar cut reads as a glitch |
+
+## The class
+
+```ts
+// Adaptive music over generate_music takes: layers that share a tempo play together and are mixed by
+// game state; takes that do not share a length are switched on the bar instead. A danger low-pass,
+// stingers with a duck, and an intensity that eases so the score does not flap.
+import type { AudioEngine } from '@funpixel/sdk/audio';
+
+export interface Take { id: string; buffer: AudioBuffer }
+
+export class Music {
+  readonly bus: GainNode;
+  readonly lowpass: BiquadFilterNode;
+  private layers = new Map<string, { src: AudioBufferSourceNode; gain: GainNode }>();
+  private t0 = 0;
+  private level = 0;          // the eased intensity, 0..1
+  constructor(private audio: AudioEngine, readonly bpm: number, private volume = 0.8) {
+    const ctx = audio.ctx;
+    this.lowpass = ctx.createBiquadFilter();
+    this.lowpass.type = 'lowpass'; this.lowpass.frequency.value = 20000;
+    this.bus = ctx.createGain(); this.bus.gain.value = volume;
+    this.lowpass.connect(this.bus).connect(audio.master);
+  }
+  /** Seconds in one 4/4 bar at the brief's tempo. */
+  get bar() { return 240 / this.bpm; }
+  /** The next bar line after now (plus a small lead so the start is scheduled, not late). */
+  nextBar(lead = 0.05) {
+    const ctx = this.audio.ctx, since = ctx.currentTime + lead - this.t0;
+    return this.t0 + Math.ceil(since / this.bar) * this.bar;
+  }
+  /** Start every layer at one instant so layers of equal length stay locked; only `on` is heard. */
+  start(takes: Take[], on: string) {
+    const ctx = this.audio.ctx;
+    this.t0 = ctx.currentTime + 0.1;
+    for (const t of takes) {
+      const src = ctx.createBufferSource(), gain = ctx.createGain();
+      src.buffer = t.buffer; src.loop = true;
+      gain.gain.value = t.id === on ? 1 : 0;
+      src.connect(gain).connect(this.lowpass);
+      src.start(this.t0);
+      this.layers.set(t.id, { src, gain });
+    }
+  }
+  /** Mix the layers toward target gains over `seconds` (equal-power-ish: setTargetAtTime). */
+  mix(target: Record<string, number>, seconds = 2) {
+    const now = this.audio.ctx.currentTime;
+    for (const [id, l] of this.layers) {
+      l.gain.gain.cancelScheduledValues(now);
+      l.gain.gain.setTargetAtTime(target[id] ?? 0, now, seconds / 3);
+    }
+  }
+  /** For takes of different lengths: fade the old out over one bar and start `id` from its top on the next bar line. */
+  switchOnBar(take: Take) {
+    const ctx = this.audio.ctx, at = this.nextBar();
+    for (const l of this.layers.values()) { l.gain.gain.setTargetAtTime(0, at, this.bar / 3); l.src.stop(at + this.bar * 2); }
+    this.layers.clear();
+    const src = ctx.createBufferSource(), gain = ctx.createGain();
+    src.buffer = take.buffer; src.loop = true; gain.gain.value = 0;
+    gain.gain.setTargetAtTime(1, at, 0.05);
+    src.connect(gain).connect(this.lowpass); src.start(at);
+    this.layers.set(take.id, { src, gain });
+  }
+  /**
+   * Call every frame with the raw threat 0..1. It rises fast and falls slow (a fight does not end
+   * the instant the last enemy blinks), then drives the calm/tense mix and the danger low-pass.
+   */
+  intensity(raw: number, dt: number, calm = 'calm', tense = 'tense') {
+    const k = raw > this.level ? 1 - Math.exp(-dt / 0.4) : 1 - Math.exp(-dt / 3);
+    this.level += (raw - this.level) * k;
+    const now = this.audio.ctx.currentTime, c = this.layers.get(calm), t = this.layers.get(tense);
+    if (c) c.gain.gain.setTargetAtTime(Math.cos(this.level * Math.PI / 2), now, 0.1);
+    if (t) t.gain.gain.setTargetAtTime(Math.sin(this.level * Math.PI / 2), now, 0.1);
+    return this.level;
+  }
+  /** Muffle the score (underwater, stunned, low health): 1 = open, 0 = about 400 Hz. */
+  muffle(open: number, seconds = 0.4) {
+    const hz = 400 * Math.pow(50, Math.max(0, Math.min(1, open)));
+    this.lowpass.frequency.setTargetAtTime(hz, this.audio.ctx.currentTime, seconds / 3);
+  }
+  /** A stinger on a payoff: the score ducks under it, then returns. `onBar` waits for the bar line. */
+  sting(buffer: AudioBuffer, { gain = 1, duck = 0.35, onBar = false } = {}) {
+    const ctx = this.audio.ctx, at = onBar ? this.nextBar() : ctx.currentTime;
+    const src = ctx.createBufferSource(), g = ctx.createGain();
+    src.buffer = buffer; g.gain.value = gain; src.connect(g).connect(this.audio.master); src.start(at);
+    this.bus.gain.setTargetAtTime(this.volume * (1 - duck), at, 0.03);
+    this.bus.gain.setTargetAtTime(this.volume, at + buffer.duration * 0.8, 0.25);
+    return at;
+  }
+}
+```
+
+Wiring it:
+
+```ts
+const audio = new AudioEngine({ iosPatch: false });
+const music = new Music(audio, 84);
+const [calm, tense] = await Promise.all(['calm', 'tense'].map(async (id) => ({ id, buffer: await audio.ctx.decodeAudioData(await (await fetch(`assets/music/${id}.mp3`)).arrayBuffer()) })));
+// Start after the first gesture (the title's Begin): audio.unlock() first.
+music.start([calm, tense], 'calm');
+// Each frame: the threat from the game, 0 (safe) to 1 (a boss in reach).
+music.intensity(Math.min(1, enemiesNear / 4), dt);
+// The payoff:
+music.sting(chimeBuffer, { duck: 0.35, onBar: true });
+// Underwater, stunned, or the moment before a reveal:
+music.muffle(0.2);
+```
+
+## Prove it follows play (free, before anyone listens)
+
+A mix driven by a timer reads as a playlist; one that never moves is a single loop with extra
+files. Keep the decision pure and beside the rules, as one game's `src/mix.ts` does:
+`musicMix(run, screen, lift) → { calm, swarm, lift }`, where `swarm` rises with the bugs on the
+field and sniffling ones count more. The `Music` class sets gains from it each frame, and a probe
+can chart the same function while a bot plays, with no browser and no audio device:
+
+```ts
+// test/probes.ts (the funtools scaffold's probe kit, skill funpixel-game-logic references/probes.md)
+const rows = timeline(game, skilled, 7, 60, 0.5, (run) => ({ threats: run.bugs.length, ...musicMix(run, 'playing', 0) }));
+timelines: [{ name: 'wave 3', follow: [{ layer: 'swarm', driver: 'threats' }], rows }]
+```
+
+`npx @funpixel/tools sim` then says, per layer: it never moved (warn), it moved but not with what
+it follows (note, with the correlation), or it follows (r and the sample count). That game's
+`music-timeline.ts` printed the same chart as bars per half second with the chain and bloom
+marks beside them, which is how its creator saw the lift arrive on the payoff. The numbers
+cannot say it sounds good; listen once the chart says it moves.
+
+## Tying music to the story
+
+- A place has a theme; a chapter has a variation (the same brief, a changed energy line).
+- Arrival at a safe place: let the tense layer fall away and the calm one open; the silence
+  between them is part of the music.
+- The set piece: `muffle()` down for a beat before it, `sting()` on the reveal, then
+  `switchOnBar()` to the `wonder` take, and leave it on while the player looks.
+- A score built on the game's own sound. A horror game (29 Sep 2026) built its music
+  on one sustained note that bends as an enemy nears and gains layers with the threat, per-room ambience
+  beds under it, stingers on reveals, and real silence between phrases; the silence is what
+  makes the next phrase land. Its radio voices were band-limited and driven like a small speaker
+  with line noise, so a recording sounds like a recording.
+- Expose the music state in `__FPX_STATE__` (`music: 'calm' | 'tense' | 'wonder'`, the eased
+  intensity) so a check can assert that the fight actually turns the score, and mark the sound
+  check `"sound": true` (skill `funpixel-verify`).
+
+## Play on the beat (beat maps)
+
+`npx @funpixel/tools beats` reads each music track the game ships (WAV directly, other formats through
+the local ffmpeg) and writes `<track>.beats.json` beside it: tempo, the first beat, the downbeat, every
+beat time and how clear the pulse is. A bed with no clear pulse says so and gets no invented tempo:
+sync it to events instead. In the game, `src/beat.ts` reads the map (`loadBeats(url)`) and answers
+against the music's own clock (`musicTime()` in `src/sound.ts`, never the frame clock):
+`beatAt(map, t)` for the beat, bar and phase (a light that pulses), `nearestBeat(map, t).offMs` to
+judge a press (rhythm games: within about ±80 ms is "on"), `nextBeat(map, t, true)` to start a wave on
+the next bar. Brief music for a game that syncs with a steady tempo named in bpm, so the map is clean.

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), one game 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 (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. One game (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,74 @@
+# 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
+
+Not shipped by the kit: 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.
+- A sound class of your own: 8 pooled one-shot sources with a pitch jitter of about 0.06, one looping music source at volume 0.45, an `AudioListener` added when none exists, and the player's Sound and Music toggles.
+- 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; have the sound class add one when none exists.
+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 |
+   |---|---|
+   | A 3D platformer | music −18.5 LUFS, peaks at most −1 dBFS |
+   | A casual game | SFX mean −18 to −28 dB; music volume 0.45, about 7 dB under SFX |
+   | An idle game | crowd bed −30 LUFS |
+
+8. Mix in code. No game uses an AudioMixer asset. One port carries over 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. One port: 468 events, 0 mismatches against the web.
+10. Re-render procedural web audio offline in C# instead of synthesising live. One game's 70 clips (17.7 s) warm in 64 ms at boot; another's 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, 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: one sports game's crowd volume swells near goals; another game crossfades and ducks on stingers. No game has layered adaptive music.
+
+## Worked example
+
+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: one game inherited `m_DisableAudio: 1`; the studio's upload pre-flight (proposed for the kit) caught it.
+- No 48 kHz setting: one game mixed at 24 kHz and sounded muffled.
+- MP3 or ADPCM for loops: gaps or clicks.
+- Uncommitted reimports: two review builds 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 one game had 19 frame gaps up to 0.85 s and 24 kHz audio, cost about 1 h and was cancelled.
+- Generated audio nobody heard: one game's 70 sounds, as of 29 Sep.
+- Many relaunches wedge the Simulator's CoreAudio (crash at audio init); a Simulator build with 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.7.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.