zeling_v2/Docs/DesignSpec/11_AudioSystem.md

11 · 音频系统规范

所属文档集 ← 返回索引
摘要：音频分层架构、自适应音乐系统、音效触发契约与音量管理。

---

目录

1. 音频设计原则
2. 音频分层架构
3. 自适应音乐系统
4. 音效（SFX）规范
5. 音频总线与混音
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	播放敌人死亡音效