@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/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/codex/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/codex/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/codex/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/codex/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/codex/skills/funpixel-feedback/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "funpixel-feedback"
+  short_description: "a step, test, dead end, lesson or decision happens while building a game, when the person changed the game by hand, and "
+policy:
+  allow_implicit_invocation: true
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"