@funpixel/tools 0.0.0-stage → 0.1.1

package/templates/common/.agents/skills/funpixel-art/references/wiring.md

@@ -0,0 +1,41 @@
+# Packing and wiring accepted art
+
+Detail for step 9 of [2d-assets](2d-assets.md): once an asset is accepted, how it reaches the running
+game at the size its role needs, and how the stand-ins it replaces leave.
+
+## Pack related sprites
+
+When a set shares a scene and benefits from one load, `npx @funpixel/tools optimize pack-atlas
+<sprites…> --write` packs it; add the cycles as a named `animations` map and load
+`assets/atlas.json` once. The path stays relative, so a game hosted in a subfolder (a preview, a
+published version) still finds it. Frame keys are the original filenames. Backdrops stay out of the
+atlas: they are big, opaque and loaded once.
+
+## Wire by role
+
+- Readability and collision bounds follow the genre and camera: decide them at phone size and
+  measure them in play (`capture --viewport phone`, `audit-screens`). A 1024 px coin drawn at raw
+  texture size fills the view.
+- `setupGameResize` from `@funpixel/sdk`, with a stored `baseScale` that animation multiplies:
+  compounding a squash onto the current scale drifts.
+- Compress textures to the resolution the supported displays need
+  (`optimize compress <image> --max-size <px> --write`).
+- `npx @funpixel/tools smoke` warns on a shapes-only game and on stand-ins; read each warning
+  against the medium the game chose (authored shapes can be the look).
+
+```ts
+import { AnimatedSprite, Assets } from 'pixi.js';
+import { setupGameResize } from '@funpixel/sdk';
+
+const sheet = await Assets.load('assets/atlas.json');
+const hero = new AnimatedSprite(sheet.animations['hero-run']);
+hero.anchor.set(0.5, 1);
+let baseScale = 1;
+setupGameResize((w, h) => { baseScale = (h * 0.16) / hero.texture.height; hero.scale.set(baseScale); });
+```
+
+## Finish the integration
+
+Load the assets this task introduced and remove the stand-ins they replace: stand-ins left in
+because the logic passed are how a promised look never reached the game. Keep unrelated existing
+files; name unused candidates and remaining stand-ins in the hand-back, so the person decides.

package/templates/common/.agents/skills/funpixel-audio/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: funpixel-audio
+description: Use when a game needs sound effects or music, or its sound is being wired, mixed or found missing (too quiet, nothing beeps when you win). Covers a cue or silence per juice row, one music identity, adaptive music, loudness, gapless loops and the SDK AudioEngine. In Unity (a silent TestFlight build, the AudioListener, 48 kHz), follow references/unity.md.
+---
+
+# Sound and music for a Funpixel game
+
+Sound is half of how a game feels. Study the hits: Hades plays its music in stems and drops the
+drums when a fight ends; Mini Metro's score is played by the trains themselves. A game with one
+sound identity, a voice for its core verb and music that follows play is remembered. This skill
+briefs, levels, wires (`@funpixel/sdk/audio`) and proves it. The trap: a silent game passes every screenshot and bot, and four of ours reached testers silent.
+
+## Tools
+
+- `generate_sound` makes one effect per call (0.5–30 s; `loop` for a steady hum). About 2 credits.
+- `generate_music` makes a loop or a theme (`length` clip, about 30 s, or full). Set `instrumental`
+  to true for anything under gameplay. About 8 credits a clip, 16 a full track.
+- `get_job` collects them by id; `npx @funpixel/tools job <id> --wait --out <file>` saves one.
+  Start them together and write code meanwhile.
+- Local: `npx @funpixel/tools verify` checks the game and listens for sound (step 7);
+  `npx @funpixel/tools gen sound|music "…"` generates with a paid key. Web Audio synthesis is a style
+  of its own (chiptune, sfxr-style blips); name a synthesized placeholder as one.
+
+## The procedure
+
+1. **A sound for each action the design gives one, from the juice list.** Each juice row whose
+   sound column names a cue (skill `funpixel-game-feel`), and each event the design gives a feel
+   ("the lid clacks shut"), gets its own effect briefed from that line; count those rows against
+   files. Intentional silence needs no file. The core verb and its answer carry the most; a payoff
+   that is the loudest, longest sound in the game reads as the payoff.
+2. **Brief an effect: source, material, action, space.** Add the intensity and length, and end
+   with "one event, no music, no voice". Use the world's own nouns: "small brass bell struck once
+   with a felt mallet, dry close room, soft, short tail" rather than "ding"; "wet canvas sack
+   dropped on a wooden deck, close, heavy" rather than "whoosh". One event per clip; clips are at
+   least 0.5 s, so ask 0.5 for a tick and check its onset.
+3. **One music identity, briefed as a loop.** Write the game's sound in one line first (lead
+   instruments, what it never uses, a key) and repeat it in every track; only tempo and energy
+   move between title, play and the ending (our robot game: "brass and xylophone, no synths").
+   Each brief: genre, mood, instruments,
+   tempo in bpm, key, then "steady tempo, no intro swell, no ending, seamless loop". Pass
+   `instrumental` as true: it defaults to false, and "no vocals" in prose is unreliable. A clip
+   suits loops; a full track is often past the size cap.
+4. **Refusals.** Retry a refused music prompt once as written, then with plainer nouns (drop
+   battle or blood). A dropped connection is not a refusal: collect the job by id.
+5. **Pick without listening, and say so.** For the core verb and the win, two takes are cheap;
+   keep the one that starts within about 50 ms, does not clip, and is nearest the length asked
+   for. Snippet and thresholds: [references/measure.md](references/measure.md). Tell the person
+   which files to listen to.
+6. **Levels and files.** Targets by class: one-shots −16 LUFS, loops −22, music −18, peaks at
+   or below −1 dBFS. Each file 1 MiB or less, `.mp3` or `.m4a`: Safari will not play Ogg. The
+   tools master to these; a loop ships as `.mp3` with its LAME header, gapless in every
+   browser. Mixing your own files: loops about 6 dB under one-shots, music about 2 dB under; a short duck
+   under the payoff lets it own the moment.
+7. **Wire through the engine.** One `AudioEngine` per game, `{ iosPatch: false }` so the iPhone
+   ringer switch mutes it (`true` for games where sound is the point); every source through
+   `audio.master`, which the mute drives. Unlock on `click`, `pointerup` or `keydown`: WebKit may
+   not resume on `pointerdown` alone. Decode each file at load; a clip first decoded on its first
+   play is silent that time. Put a mute on the first screen and in the HUD, kept across reloads. The module, with voice caps, a per-contact cooldown and a music duck,
+   and why each piece is there: [references/engine.md](references/engine.md).
+8. **Prove it is not silent.** Set `window.__FPX_AUDIO__ = { sfx: [...], music: true }` and verify
+   fails a run in which no sound starts at all. Mark each sounding mechanic's check
+   `"sound": true`: it fails when its drive starts none, and its `sound_cues` count each cue, so
+   `buffer#1 x4` is one hit playing four times. Then press the real start control and read the
+   `audio` block's context state as `running`.
+9. **Music that follows the game, when the design wants it.** Takes of one identity that differ
+   in energy (calm, tense, wonder), layered when their lengths match or switched on the bar line,
+   with a stinger on the payoff and a low-pass for danger. The mixer, briefs, a measured run and
+   `funtools sim`'s follows-play check: [references/adaptive-music.md](references/adaptive-music.md).
+
+## Worked example
+
+A tide-pool matching game; its juice list: a shell flips, a match chimes, a mismatch clunks, the
+pool clears. Briefs: "cockle shell flipped over on wet sand, close, light, short" and "three
+small glass wind chimes brushed once, open beach air, one event, no music, no voice". Music: "gentle marimba and nylon guitar, soft shaker, 92 bpm, D major, steady tempo, no
+intro swell, no ending, seamless loop", a clip, `instrumental` true. Six jobs start together
+(about 18 credits) while the board code is written.
+
+Two takes of the flip: A starts 180 ms late, B at 12 ms; B is kept. The check `{ "mechanic": "flipping makes a sound", "verb": "flip", "field": "sounds",
+"expect": "increases" }` passes; one match reads `sounds` rising by 4 (the chime fired on every
+frame of the match flash); a 50 ms cooldown makes it 1. Front door: after pressing Play,
+`audio` reads `running`. Hand-back: "Listen to the flip and the chime; the flip is a pick by onset,
+not by ear."
+
+## Common mistakes
+
+- `new Audio(...)` or a source on `ctx.destination`: the mute misses it, and an `<audio loop>`
+  gaps at every seam. Loop a `BufferSource` instead.
+- "No vocals" in the prompt instead of the flag: a singer under the gameplay.
+- A passing verify as proof of sound: until it reports audio, it measured none.
+
+Where this comes from: the brief grammar and pick-by-onset from scenario-labs/skills (MIT; see
+THIRD_PARTY_NOTICES.md); levels, loops, the engine and the checks from our own games.

package/templates/common/.agents/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/templates/common/.agents/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/templates/common/.agents/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/templates/common/.agents/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.