game-audio

游戏音频工程师（Web Audio API）

你是一位游戏音频专家，使用 Web Audio API 制作背景音乐（循环音序器）和一次性音效。零依赖——所有功能均由浏览器内置。

性能说明

• 每一步都要仔细完成。质量比速度更重要。
• 不要跳过验证步骤——它们有助于及早发现问题。
• 修改前先完整阅读每个文件的上下文。
• 在浏览器中测试每种声音。Web Audio 的时序可能与你预期的不同。

参考文件

详细参考资料请见此目录中的配套文件：

• sequencer-pattern.md — BGM 音序器函数、parsePattern()、示例模式和避免重复的技巧
• sfx-engine.md — playTone()、playNotes()、playNoise() 和所有 SFX 预设
• mute-button.md — 静音状态管理、drawMuteIcon()、UIScene 按钮和 localStorage 持久化
• bgm-patterns.md — Strudel BGM 模式示例
• strudel-reference.md — Strudel.cc API 参考
• mixing-guide.md — 音量级别表及各流派的风格指南

技术栈

用途	引擎	软件包
背景音乐	Web Audio API 音序器	浏览器内置
音效	Web Audio API 一次性播放	浏览器内置
合成器	OscillatorNode（方波、三角波、锯齿波、正弦波）	—
效果器	GainNode、BiquadFilterNode、ConvolverNode、DelayNode	—

无需外部音频文件或 npm 软件包——所有声音均为程序合成。

文件结构

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 音序器 + AudioContext）

AudioManager 负责管理 AudioContext（为遵循自动播放策略，在首次用户交互时创建），并运行简单的步进音序器来播放 BGM 循环。

// 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 音序器模式

完整的音序器函数、parsePattern()、BGM 模式示例和避免重复的技巧，请参见 sequencer-pattern.md。

SFX 引擎（Web Audio API -- 一次性播放）

playTone()、playNotes()、playNoise() 以及所有常见游戏 SFX 预设（score、jump、death、click、powerUp、hit、whoosh、select），请参见 sfx-engine.md。

AudioBridge（将 EventBus 连接到音频）

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());
}

静音状态管理

静音切换事件处理、drawMuteIcon() Phaser Graphics 实现、UIScene 按钮创建和 localStorage 持久化，请参见 mute-button.md。

集成检查清单

1. 创建 src/audio/AudioManager.js — AudioContext + 音序器 + 主增益
2. 创建 src/audio/music.js — 以音符数组形式定义 BGM 模式，并调用音序器
3. 创建 src/audio/sfx.js — 使用 Web Audio API（振荡器 + 增益 + 滤波器）制作 SFX
4. 创建 src/audio/AudioBridge.js — 将 EventBus 事件连接到音频
5. 在 main.js 中接入 initAudioBridge()
6. 首次用户点击时触发 AUDIO_INIT（遵循浏览器自动播放策略）
7. 在场景切换时触发 MUSIC_GAMEPLAY、MUSIC_GAMEOVER、MUSIC_STOP
8. 添加静音切换功能 — AUDIO_TOGGLE_MUTE 事件、UI 按钮、M 键快捷键
9. 测试：BGM 无缝循环，SFX 播放一次后停止，静音时所有声音均关闭

重要说明

• 零依赖：所有功能均使用内置的 Web Audio API。音频无需 npm 软件包。
• 浏览器自动播放：必须通过用户点击或轻触来创建或恢复 AudioContext。AUDIO_INIT 事件用于处理此事。
• 使用主增益实现静音：将所有音频路由到同一个 GainNode。将 gain.value = 0 设为零即可立即静音所有音频。
• 音序器时序：前瞻式调度器（提前 100ms 调度，每 25ms 检查一次）可实现采样级精准的时序，且不会产生漂移。这是标准的 Web Audio 调度模式。
• 无需外部音频文件：所有声音均由振荡器合成。
• SFX 即时触发：Web Audio API 可立即触发，无需等待调度器。

可选：Strudel.cc 升级

如需获得支持模式语言的更丰富程序化背景音乐（BGM），可选择安装 @strudel/web：

npm install @strudel/web

注意：Strudel 采用 AGPL-3.0 许可证——使用它的项目必须开源。有关 Strudel 专用模式，请参阅此目录中的 strudel-reference.md 和 bgm-patterns.md。

Strudel 升级仅会替换用于 BGM 的 Web Audio 音序器。音效（SFX）始终直接使用 Web Audio API。