# 11 · 音频系统规范

> **所属文档集** [← 返回索引](./README.md)  
> **摘要**：音频分层架构、自适应音乐系统、音效触发契约与音量管理。

---

## 目录

1. [音频设计原则](#1-音频设计原则)
2. [音频分层架构](#2-音频分层架构)
3. [自适应音乐系统](#3-自适应音乐系统)
4. [音效（SFX）规范](#4-音效sfx规范)
5. [音频总线与混音](#5-音频总线与混音)
6. [音频事件目录](#6-音频事件目录)

---

## 1. 音频设计原则

| 原则 | 说明 |
|------|------|
| **情境响应** | 音乐随战斗/探索状态自动切换层级 |
| **游戏反馈优先** | 每个玩家动作都有清晰音效反馈（攻击/受伤/弹反）|
| **非侵入性** | 非战斗状态音乐保持安静，不与游戏音效竞争 |
| **数据驱动** | 音频配置和触发条件通过数据定义，不硬编码 |

---

## 2. 音频分层架构

```
AudioSystem（协调器）
├── MusicPlayer          ← 背景音乐、自适应分层
├── AmbiencePlayer       ← 环境音效（风声、水声等）
├── SFXPool              ← 音效池，管理 SFX 实例
└── VoicePlayer          ← 对话/语音（若有）
```

---

## 3. 自适应音乐系统

### 3.1 音乐状态机

```
[Silence] ──加载区域──► [Exploration]
[Exploration] ──感知敌人──► [CombatIntro]
[CombatIntro] ──0.5s──► [Combat]
[Combat] ──清场/脱战─────► [CombatOutro]
[CombatOutro] ──1.0s────► [Exploration]
[Exploration] ──进入Boss房间──► [BossIntro]
[BossIntro] ──播放完毕──► [BossPhase1]
[BossPhase1] ──阶段转换──► [BossPhase2]
[BossPhase2] ──Boss死亡──► [BossVictory]
[BossVictory] ──播放完毕──► [Exploration]
```

### 3.2 音乐分层（Layer）

每首区域音乐由多个同步的音频层叠加：

| 层 | 说明 | 探索 | 战斗 |
|----|------|:----:|:----:|
| Base | 旋律主干 | ✓ | ✓ |
| Percussion | 打击乐 | 弱 | ✓ |
| Tension | 紧张弦乐 | ✗ | ✓ |
| Ambient | 环境填充 | ✓ | ✗ |
| BossLayer | Boss 专属 | ✗ | Boss战 |

层级混合通过音量淡入淡出（crossfade）实现，切换时间可配置。

### 3.3 音乐数据模型

```
DataModel MusicData {
    musicId         : ID
    regionId        : ID                  // 归属区域
    ──────────────────────────────────
    layers          : Map<MusicLayer, AudioID>  // 各层音频资源
    bpm             : Integer             // 用于节拍同步切换
    loopStart       : Duration
    loopEnd         : Duration
    ──────────────────────────────────
    transitionMode  : TransitionMode      // 即时/等待小节/淡入淡出
    crossfadeDuration: Duration
}
```

---

## 4. 音效（SFX）规范

### 4.1 音效触发契约

```
Interface IAudioTrigger {
    playOneShot(audioId: AudioID, position: Optional<Vector2>) → Void
    playLooping(audioId: AudioID, handle: out AudioHandle) → Void
    stopLooping(handle: AudioHandle) → Void
    playWithVariation(audioId: AudioID, pitchRange: {min,max}) → Void
}
```

### 4.2 玩家动作音效列表

| 动作 | 音效 | 变调范围 |
|------|------|---------|
| 普通攻击 1/2/3 | `sfx_attack_1/2/3` | ±0.05 |
| 受伤 | `sfx_hurt` | ±0.1 |
| 死亡 | `sfx_death` | — |
| 弹反成功 | `sfx_parry_success` | — |
| 弹反失败（时机错误）| `sfx_parry_fail` | — |
| 跳跃 | `sfx_jump` | ±0.08 |
| 双跳 | `sfx_double_jump` | ±0.05 |
| 冲刺 | `sfx_dash` | — |
| 空中冲刺 | `sfx_aerial_dash` | — |
| 下冲落地 | `sfx_plunge_land` | — |
| 墙跳 | `sfx_wall_jump` | ±0.05 |
| 形态切换 | `sfx_form_switch_{formId}` | — |
| 技能施放 | `sfx_skill_{skillId}` | — |
| 灵泉使用 | `sfx_spring_use` | — |
| 拾取 Geo | `sfx_geo_collect` | ±0.1 |

### 4.3 音效变调规则

- **随机变调**（pitchVariation）：相同音效连续触发时，随机微调音调，避免"机器声"感
- **连击变调**：攻击 1→2→3 音效各自递进（音调略微提升，体现连击感）

---

## 5. 音频总线与混音

### 5.1 音频总线层级

```
Master Bus
├── Music Bus
│   ├── Exploration Layer
│   ├── Combat Layer
│   └── Boss Layer
├── SFX Bus
│   ├── Player SFX
│   ├── Enemy SFX
│   └── World SFX
└── UI Bus
    ├── Menu SFX
    └── Notification SFX
```

### 5.2 音量控制规范

| 总线 | 用户可调 | 默认值 |
|------|---------|--------|
| Master Bus | ✓ | 100% |
| Music Bus | ✓ | 80% |
| SFX Bus | ✓ | 100% |
| UI Bus | ✓ | 90% |

> 所有用户音量设置持久化到 UserSettings（独立于 SaveData）

---

## 6. 音频事件目录

音频系统监听以下事件执行音频响应：

| 监听事件 | 音频响应 |
|---------|---------|
| `OnPlayerAttack` | 播放攻击音效 |
| `OnPlayerHurt` | 播放受伤音效 |
| `OnPlayerDied` | 播放死亡音效，切换到 Silence |
| `OnParrySuccess` | 播放弹反成功音效 + 子弹时间音效处理 |
| `OnFormChanged` | 播放形态切换音效 |
| `OnBonfireRested` | 播放存档音效 |
| `OnBossEncounterBegin` | 切换到 BossIntro 音乐 |
| `OnBossPhaseChanged` | 切换音乐层/音乐轨道 |
| `OnBossDefeated` | 播放 BossVictory 音乐 |
| `OnRoomTransitionBegin` | 淡出当前音乐 |
| `OnRoomTransitionComplete` | 根据新房间/区域加载新音乐 |
| `OnCollectiblePickedUp` | 播放拾取音效（按类型）|
| `OnEnemyDied` | 播放敌人死亡音效 |