game-audio

SKILL.md

Game Audio Engineer (Web Audio API)

You are an expert game audio engineer. You use the Web Audio API for both background music (looping sequencer) and one-shot sound effects. Zero dependencies — everything is built into the browser.

Performance Notes

Take your time with each step. Quality is more important than speed.

Do not skip validation steps — they catch issues early.

Read the full context of each file before making changes.

Test every sound in the browser. Web Audio timing is different from what you expect.

Reference Files
For detailed reference, see companion files in this directory:

sequencer-pattern.md — BGM sequencer function, parsePattern(), example patterns, anti-repetition techniques

sfx-engine.md — playTone(), playNotes(), playNoise(), all SFX presets

mute-button.md — Mute state management, drawMuteIcon(), UIScene button, localStorage persistence

bgm-patterns.md — Strudel BGM pattern examples

strudel-reference.md — Strudel.cc API reference

mixing-guide.md — Volume levels table and style guidelines per genre

Tech Stack

Purpose
Engine
Package

Background music
Web Audio API sequencer
Built into browsers

Sound effects
Web Audio API one-shot
Built into browsers

Synths
OscillatorNode (square, triangle, sawtooth, sine)
—

Effects
GainNode, BiquadFilterNode, ConvolverNode, DelayNode
—

No external audio files or npm packages needed — all sounds are procedural.

File Structure

src/
├── audio/
│   ├── AudioManager.js    # AudioContext init, BGM sequencer, play/stop
│   ├── AudioBridge.js     # Wires EventBus → audio playback
│   ├── music.js           # BGM patterns (sequencer note arrays)
│   └── sfx.js             # SFX (one-shot oscillator + gain + filter)

AudioManager (BGM Sequencer + AudioContext)

The AudioManager owns the AudioContext (created on first user interaction for autoplay policy) and runs a simple step sequencer for BGM loops.

// AudioManager.js — Web Audio API BGM sequencer + SFX context

class AudioManager {
  constructor() {
    this.ctx = null;
    this.currentBgm = null; // { stop() }
    this.masterGain = null;
  }

  init() {
    if (this.ctx) return;
    this.ctx = new (window.AudioContext || window.webkitAudioContext)();
    this.masterGain = this.ctx.createGain();
    this.masterGain.connect(this.ctx.destination);
  }

  getCtx() {
    if (!this.ctx) this.init();
    return this.ctx;
  }

  getMaster() {
    if (!this.masterGain) this.init();
    return this.masterGain;
  }

  playMusic(patternFn) {
    this.stopMusic();
    try {
      this.currentBgm = patternFn(this.getCtx(), this.getMaster());
    } catch (e) {
      console.warn('[Audio] BGM error:', e);
    }
  }

  stopMusic() {
    if (this.currentBgm) {
      try { this.currentBgm.stop(); } catch (_) {}
      this.currentBgm = null;
    }
  }

  setMuted(muted) {
    if (this.masterGain) {
      this.masterGain.gain.value = muted ? 0 : 1;
    }
  }
}

export const audioManager = new AudioManager();

BGM Sequencer Pattern

See sequencer-pattern.md for the full sequencer function, parsePattern(), example BGM patterns, and anti-repetition techniques.

SFX Engine (Web Audio API -- one-shot)

See sfx-engine.md for playTone(), playNotes(), playNoise(), and all common game SFX presets (score, jump, death, click, powerUp, hit, whoosh, select).

AudioBridge (wiring EventBus -> audio)

import { eventBus, Events } from '../core/EventBus.js';
import { audioManager } from './AudioManager.js';
import { gameplayBGM, gameOverTheme } from './music.js';
import { scoreSfx, deathSfx, clickSfx } from './sfx.js';

export function initAudioBridge() {
  // Init AudioContext on first user interaction (browser autoplay policy)
  eventBus.on(Events.AUDIO_INIT, () => audioManager.init());

  // BGM transitions
  eventBus.on(Events.MUSIC_GAMEPLAY, () => audioManager.playMusic(gameplayBGM));
  eventBus.on(Events.MUSIC_GAMEOVER, () => audioManager.playMusic(gameOverTheme));
  eventBus.on(Events.MUSIC_STOP, () => audioManager.stopMusic());

  // SFX (one-shot)
  eventBus.on(Events.SCORE_CHANGED, () => scoreSfx());
  eventBus.on(Events.PLAYER_DIED, () => deathSfx());
}

Mute State Management

See mute-button.md for mute toggle event handling, drawMuteIcon() Phaser Graphics implementation, UIScene button creation, and localStorage persistence.

Integration Checklist

Create src/audio/AudioManager.js — AudioContext + sequencer + master gain

Create src/audio/music.js — BGM patterns as note arrays + sequencer calls

Create src/audio/sfx.js — SFX using Web Audio API (oscillator + gain + filter)

Create src/audio/AudioBridge.js — wire EventBus events to audio

Wire initAudioBridge() in main.js

Emit AUDIO_INIT on first user click (browser autoplay policy)

Emit MUSIC_GAMEPLAY, MUSIC_GAMEOVER, MUSIC_STOP at scene transitions

Add mute toggle — AUDIO_TOGGLE_MUTE event, UI button, M key shortcut

Test: BGM loops seamlessly, SFX fire once and stop, mute silences everything

Important Notes

Zero dependencies: Everything uses the built-in Web Audio API. No npm packages needed for audio.

Browser autoplay: AudioContext MUST be created/resumed from a user click/tap. The AUDIO_INIT event handles this.

Master gain for mute: Route everything through a single GainNode. Setting gain.value = 0 mutes all audio instantly.

Sequencer timing: The look-ahead scheduler (schedules 100ms ahead, checks every 25ms) gives sample-accurate timing with no drift. This is the standard Web Audio scheduling pattern.

No external audio files needed: Everything is synthesized with oscillators.

SFX are instant: Web Audio API fires immediately with zero scheduler latency.

Optional: Strudel.cc Upgrade

For richer procedural BGM with pattern language support, you can optionally install @strudel/web:

npm install @strudel/web

Note: Strudel is AGPL-3.0 — projects using it must be open source. See strudel-reference.md and bgm-patterns.md in this directory for Strudel-specific patterns.

The Strudel upgrade replaces the Web Audio sequencer for BGM only. SFX always use Web Audio API directly.