add-audio

性能说明

• 请花时间彻底完成
• 质量比速度更重要
• 不要跳过验证步骤

添加音频

为现有游戏添加程序生成的音乐和音效。背景音乐（BGM）使用 Web Audio API 步进音序器循环播放乐段。音效（SFX）直接使用 Web Audio API，实现真正的单次播放。无需音频文件或 npm 包，所有内容都在浏览器中合成。

说明

分析 $ARGUMENTS 中的游戏（如果未提供路径，则分析当前目录）。

首先，加载 game-audio 技能，了解完整的 Web Audio 模式和集成指南。

步骤 1：审查

• 阅读 src/core/EventBus.js，了解有哪些游戏事件（拍翅、得分、死亡等）
• 阅读所有场景文件，了解游戏流程（游戏过程、游戏结束）
• 确定适合游戏类型和氛围的音乐与音效

步骤 2：规划

提供计划音频表：

事件 / 场景	音频类型	风格	描述
GameScene	BGM	芯片音乐	欢快的方波旋律 + 低音 + 鼓点
GameOverScene	BGM	忧郁	缓慢下行的旋律
玩家动作	SFX	复古	快速音高滑动
得分	SFX	复古	双音提示声
死亡	SFX	复古	下行的失真音符

用通俗的英语解释：“背景音乐会在每个场景中自动循环播放。执行跳跃、得分或死亡等操作时会播放音效。首次点击或轻触时，音频系统会启动（浏览器要求用户先进行交互，才能播放声音）。”

步骤 3：实现

1. 创建 src/audio/AudioManager.js — 初始化 AudioContext、主增益节点、播放 / 停止 BGM 音序器
2. 创建 src/audio/AudioBridge.js — 将 EventBus 事件连接到 AudioManager，以控制 BGM；直接调用 SFX 函数
3. 创建 src/audio/music.js，为每个场景编写 BGM 乐段（Web Audio 步进音序器 — 循环播放的音符数组）
4. 创建 src/audio/sfx.js，为每个事件编写 SFX（Web Audio API — 使用 OscillatorNode + GainNode + BiquadFilterNode 实现真正的单次播放）
5. 如果 EventBus.js 中尚不存在，则添加音频事件（AUDIO_INIT、MUSIC_GAMEPLAY、MUSIC_GAMEOVER、MUSIC_STOP、AUDIO_TOGGLE_MUTE）
6. 在 main.js 中连接 initAudioBridge()
7. 首次用户交互时触发 AUDIO_INIT（游戏立即开始，没有菜单）
8. 在场景切换时触发音乐事件，在游戏操作时触发 SFX 事件
9. 添加静音切换功能 — AUDIO_TOGGLE_MUTE 事件、UI 按钮、M 键快捷键

步骤 4：验证

• 运行 npm run build，确认没有错误
• 列出所有新建 / 修改的文件
• 提醒用户：“点击或轻触一次以激活音频，之后就能听到音乐。”

使用示例

完整音频处理

/add-audio examples/flappy-bird

结果：创建 src/audio/AudioManager.js、music.js（游戏过程 + 游戏结束 BGM 乐段）、sfx.js（拍翅、得分、死亡、按钮 SFX）→ 通过 AudioBridge 连接 → 添加 M 键静音切换。首次点击时激活音频。

故障排除

没有声音

原因： 用户交互后未恢复 AudioContext（浏览器自动播放策略）。 解决方法： 确保在首次用户输入（点击 / 轻触 / 按键）时调用 AudioContext.resume()。检查 AUDIO_INIT 事件是否已连接。

音频导致卡顿

原因： 每帧都创建新的 OscillatorNode。 解决方法： SFX 应单次播放（创建、连接、启动、停止）。BGM 使用单个循环音序器。绝不要在 update() 中创建节点。

下一步

告诉用户：

你的游戏现在有音乐和音效了！接下来，运行 /game-creator:qa-game，添加自动化测试，以验证游戏能否正确启动、场景能否正常切换、计分是否有效，以及视觉效果是否完好。

流水线进度： /viral-game → /design-game → /add-audio → /qa-game → /review-game

（这是 /viral-game 的一次性流水线，不是 /make-game 的多会话、按里程碑推进的工作流。）