jakciehan
302 lines
8.9 KiB
Markdown
302 lines
8.9 KiB
Markdown
# AudioManager 音效系统说明文档
|
||
|
||
> **文件路径**: `js/managers/AudioManager.js`
|
||
> **运行环境**: 微信小游戏 (WeChat Mini Game)
|
||
> **依赖 API**: `wx.createWebAudioContext()` (Web Audio API)
|
||
> **外部资源**: 无 — 所有音效通过 PCM 程序化合成生成
|
||
|
||
---
|
||
|
||
## 1. 架构概述
|
||
|
||
`AudioManager` 是坦克大战微信小游戏的音效管理模块，采用 **程序化音频合成** 方案，通过 Web Audio API 在运行时生成所有游戏音效的 PCM 缓冲区，无需加载任何外部音频文件。
|
||
|
||
### 设计决策
|
||
|
||
| 方案 | 优点 | 缺点 |
|
||
|------|------|------|
|
||
| ~~外部音频文件~~ | 音质高、可定制 | 需要额外资源文件，增加包体积 |
|
||
| **程序化合成 ✅** | 零资源依赖、包体极小、即时可用 | 音效较简单，适合复古风格游戏 |
|
||
|
||
### 模块关系
|
||
|
||
```
|
||
game.js (初始化)
|
||
└── AudioManager.init() ← 创建 WebAudioContext + 预生成所有音效缓冲区
|
||
│
|
||
├── GameScene.js (游戏场景)
|
||
│ ├── _playerFire() → playSFX('shoot')
|
||
│ ├── _enemyFire() → playSFX('shoot')
|
||
│ ├── _spawnExplosion() → playSFX('explosion_big' | 'explosion_small')
|
||
│ ├── _checkPowerUpPickup() → playSFX('powerup')
|
||
│ ├── _handlePlayerDestroyed() → playSFX('gameover')
|
||
│ ├── _handleBaseDestroyed() → playSFX('gameover')
|
||
│ └── _checkVictory() → playSFX('victory')
|
||
│
|
||
└── CollisionManager.js (碰撞管理)
|
||
└── 子弹击中装甲坦克(未摧毁) → playSFX('hit')
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 生命周期
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant G as game.js
|
||
participant AM as AudioManager
|
||
participant GS as GameScene
|
||
|
||
G->>AM: new AudioManager()
|
||
G->>G: GameGlobal.audioManager = audioManager
|
||
G->>AM: audioManager.init()
|
||
AM->>AM: wx.createWebAudioContext()
|
||
AM->>AM: _generateSounds() 预生成9种音效
|
||
Note over AM: 初始化完成，_initialized = true
|
||
|
||
GS->>AM: playSFX('shoot')
|
||
AM->>AM: createBufferSource() → connect → start
|
||
Note over AM: 播放音效
|
||
|
||
G->>AM: pauseAll() / resumeAll()
|
||
Note over AM: 前后台切换时暂停/恢复
|
||
|
||
G->>AM: destroy()
|
||
AM->>AM: audioCtx.close() + buffers.clear()
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 音效目录
|
||
|
||
### 3.1 完整音效列表
|
||
|
||
| 音效名 | 用途 | 时长 | 波形特征 | 触发位置 |
|
||
|--------|------|------|----------|----------|
|
||
| `shoot` | 坦克射击 | 80ms | 800→400Hz 下降正弦波 + 线性衰减 | `GameScene._playerFire()` / `_enemyFire()` |
|
||
| `explosion_small` | 小爆炸（子弹击中地形） | 200ms | 白噪声 + 120Hz 正弦波，二次衰减 | `GameScene._spawnExplosion(x, y, false)` |
|
||
| `explosion_big` | 大爆炸（坦克被摧毁） | 400ms | 白噪声 + 60Hz/90Hz 双正弦波，二次衰减 | `GameScene._spawnExplosion(x, y, true)` |
|
||
| `hit` | 子弹击中装甲（未摧毁） | 100ms | 1200Hz + 2400Hz 双正弦波，金属质感 | `CollisionManager` 子弹命中装甲坦克 |
|
||
| `hit_wall` | 子弹击中墙壁 | 60ms | 噪声 + 300Hz 正弦波混合 | 预留（当前未调用） |
|
||
| `powerup` | 拾取道具 | 250ms | 400→1200Hz 上升正弦波 + 泛音 | `GameScene._checkPowerUpPickup()` |
|
||
| `gameover` | 游戏结束 | 600ms | 400→150Hz 下降正弦波 | `GameScene._handlePlayerDestroyed()` / `_handleBaseDestroyed()` |
|
||
| `victory` | 通关胜利 | 500ms | C5→E5→G5 三音阶上升和弦 | `GameScene._checkVictory()` |
|
||
| `move` | 坦克移动 | 50ms | 80Hz 低频正弦波 | 预留（当前未调用） |
|
||
|
||
### 3.2 音效波形参数详解
|
||
|
||
#### shoot（射击）
|
||
```
|
||
时长: 0.08s
|
||
频率: 800Hz → 400Hz (线性下降)
|
||
包络: 线性衰减 (1 → 0)
|
||
振幅: 0.3
|
||
```
|
||
|
||
#### explosion_big（大爆炸）
|
||
```
|
||
时长: 0.4s
|
||
成分: 白噪声(50%) + 60Hz正弦(30%) + 90Hz正弦(20%)
|
||
包络: 二次衰减 (1-t)²
|
||
振幅: 0.4
|
||
```
|
||
|
||
#### victory（胜利）
|
||
```
|
||
时长: 0.5s
|
||
音符: C5(523Hz) → E5(659Hz) → G5(784Hz)
|
||
每段: 0.167s, 含 attack(10%) + decay(90%)
|
||
泛音: 基频 × 2, 振幅 0.15
|
||
```
|
||
|
||
---
|
||
|
||
## 4. API 参考
|
||
|
||
### 构造函数
|
||
|
||
```javascript
|
||
const audioManager = new AudioManager();
|
||
```
|
||
|
||
创建实例，默认 `soundEnabled = true`, `musicEnabled = true`。
|
||
自动监听 `GameGlobal.eventBus` 的 `settings:changed` 事件。
|
||
|
||
### init()
|
||
|
||
```javascript
|
||
audioManager.init();
|
||
```
|
||
|
||
初始化 WebAudio 上下文并预生成所有音效缓冲区。
|
||
- 幂等调用：多次调用只执行一次
|
||
- 如果 `wx.createWebAudioContext` 不可用，静默降级（无音效）
|
||
|
||
### playSFX(name)
|
||
|
||
```javascript
|
||
GameGlobal.audioManager.playSFX('shoot');
|
||
```
|
||
|
||
播放指定名称的音效。
|
||
- **参数**: `name` — 音效名称，见上方音效目录
|
||
- 如果音效未找到或音效已禁用，静默忽略
|
||
- 每次调用创建新的 `BufferSource`，支持同一音效并发播放
|
||
|
||
### register(name, path)
|
||
|
||
```javascript
|
||
audioManager.register('custom', 'path/to/file.mp3');
|
||
```
|
||
|
||
向后兼容接口，当前为空操作（No-op）。
|
||
|
||
### playBGM(path) / stopBGM()
|
||
|
||
背景音乐接口，当前未实现（需要外部音频文件）。
|
||
|
||
### pauseAll() / resumeAll()
|
||
|
||
暂停/恢复所有音频，用于应用前后台切换。
|
||
|
||
### destroy()
|
||
|
||
销毁音频上下文，释放所有缓冲区资源。
|
||
|
||
### 属性
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `soundEnabled` | `boolean` | 音效开关（getter/setter） |
|
||
| `musicEnabled` | `boolean` | 音乐开关（getter/setter） |
|
||
|
||
---
|
||
|
||
## 5. 集成指南
|
||
|
||
### 5.1 初始化（game.js）
|
||
|
||
```javascript
|
||
// game.js 第39行
|
||
const audioManager = new AudioManager();
|
||
|
||
// 第48行 - 挂载到全局
|
||
GameGlobal.audioManager = audioManager;
|
||
|
||
// 第131行 - LoadingScene._startLoading() 中初始化
|
||
audioManager.init();
|
||
```
|
||
|
||
### 5.2 在游戏逻辑中播放音效
|
||
|
||
```javascript
|
||
// 射击时
|
||
GameGlobal.audioManager.playSFX('shoot');
|
||
|
||
// 爆炸时（根据大小选择音效）
|
||
GameGlobal.audioManager.playSFX(isBig ? 'explosion_big' : 'explosion_small');
|
||
|
||
// 拾取道具
|
||
GameGlobal.audioManager.playSFX('powerup');
|
||
|
||
// 游戏结束
|
||
GameGlobal.audioManager.playSFX('gameover');
|
||
|
||
// 胜利
|
||
GameGlobal.audioManager.playSFX('victory');
|
||
```
|
||
|
||
### 5.3 添加新音效
|
||
|
||
在 `_generateSounds()` 方法中添加新的缓冲区生成：
|
||
|
||
```javascript
|
||
// 示例：添加一个"警报"音效
|
||
this._buffers.set('alarm', this._generateBuffer(sampleRate, 0.3, (i, len) => {
|
||
const t = i / len;
|
||
const freq = 600 + Math.sin(t * 20) * 200; // 颤音效果
|
||
const envelope = 1 - t;
|
||
return Math.sin(2 * Math.PI * freq * i / sampleRate) * envelope * 0.3;
|
||
}));
|
||
```
|
||
|
||
然后在需要的地方调用：
|
||
|
||
```javascript
|
||
GameGlobal.audioManager.playSFX('alarm');
|
||
```
|
||
|
||
### 5.4 前后台切换处理
|
||
|
||
```javascript
|
||
// game.js 中已配置
|
||
wx.onHide(() => { audioManager.pauseAll(); });
|
||
wx.onShow(() => { audioManager.resumeAll(); });
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 技术细节
|
||
|
||
### 6.1 PCM 缓冲区生成原理
|
||
|
||
每个音效通过 `_generateBuffer()` 方法生成：
|
||
|
||
1. 根据 `sampleRate`（通常 44100Hz）和 `duration` 计算总采样数
|
||
2. 创建单声道 `AudioBuffer`
|
||
3. 逐采样调用 `generator(sampleIndex, totalSamples)` 函数
|
||
4. 每个采样值范围 `[-1.0, 1.0]`
|
||
|
||
```
|
||
采样数 = sampleRate × duration
|
||
例: 44100 × 0.08 = 3528 个采样点 (shoot 音效)
|
||
```
|
||
|
||
### 6.2 播放机制
|
||
|
||
```javascript
|
||
playSFX(name) → createBufferSource() → connect(destination) → start(0)
|
||
```
|
||
|
||
- 每次播放创建新的 `BufferSource` 节点（Web Audio API 要求，BufferSource 是一次性的）
|
||
- 支持同一音效的多实例并发播放（如连续射击）
|
||
- 播放完成后 `BufferSource` 自动被垃圾回收
|
||
|
||
### 6.3 性能考量
|
||
|
||
| 指标 | 数值 |
|
||
|------|------|
|
||
| 预生成缓冲区数量 | 9 个 |
|
||
| 最大单个缓冲区大小 | ~26KB (explosion_big, 0.4s × 44100 × 4bytes) |
|
||
| 总内存占用 | ~80KB |
|
||
| 初始化耗时 | < 10ms |
|
||
| 播放延迟 | < 1ms (预生成缓冲区，无需解码) |
|
||
|
||
### 6.4 降级策略
|
||
|
||
```
|
||
wx.createWebAudioContext 可用?
|
||
├── 是 → 正常初始化，生成所有音效
|
||
└── 否 → _initialized = false, 所有 playSFX() 静默返回
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 已知限制与后续规划
|
||
|
||
### 当前限制
|
||
|
||
1. **无背景音乐** — `playBGM()` 为空实现，需要外部音频文件支持
|
||
2. **音效较简单** — 程序化合成适合复古风格，无法达到高保真音质
|
||
3. **`hit_wall` 和 `move` 音效已生成但未集成** — 预留接口，可在后续版本中启用
|
||
4. **`pauseAll()` / `resumeAll()` 为空实现** — WebAudio 的 suspend/resume 可在后续补充
|
||
|
||
### 后续可优化方向
|
||
|
||
- [ ] 实现 `pauseAll()` / `resumeAll()` 使用 `audioCtx.suspend()` / `audioCtx.resume()`
|
||
- [ ] 集成 `hit_wall` 音效到 `CollisionManager` 的墙壁碰撞逻辑
|
||
- [ ] 集成 `move` 音效到坦克移动逻辑（需注意节流，避免频繁触发）
|
||
- [ ] 添加音量控制（通过 `GainNode`）
|
||
- [ ] 支持外部音频文件加载，用于背景音乐
|
||
- [ ] 音效参数可配置化（从 JSON 配置文件读取波形参数）
|