# 音效管理系统

<cite>
**本文档引用文件**  
- [audio.md](file://doc/core/common/audio.md)
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts)
- [AudioMusic.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioMusic.ts)
- [AudioEffect.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioEffect.ts)
- [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts)
- [GameComponent.ts](file://extensions/oops-plugin-framework/assets/module/common/GameComponent.ts)
</cite>

## 目录
1. [简介](#简介)
2. [核心功能](#核心功能)
3. [背景音乐管理](#背景音乐管理)
4. [音效管理](#音效管理)
5. [播放状态控制](#播放状态控制)
6. [用户设置持久化](#用户设置持久化)
7. [关键节点集成示例](#关键节点集成示例)
8. [性能优化建议](#性能优化建议)
9. [系统架构](#系统架构)
10. [依赖关系](#依赖关系)

## 简介
Oops Framework 音效管理模块为游戏提供完整的音频解决方案，涵盖背景音乐与音效两大核心功能。该系统在游戏启动时自动初始化，支持异步资源加载、音量控制、播放状态管理及用户偏好设置的本地持久化。通过简洁的接口设计，开发者可轻松在游戏各关键节点集成音效，提升用户体验。

**Section sources**
- [audio.md](file://doc/core/common/audio.md#L1-L10)
- [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts#L85-L93)

## 核心功能
音效管理系统提供以下核心功能：
- 背景音乐与音效的异步加载与播放
- 独立的音量控制（musicVolume 与 volumeEffect）
- 开关状态管理（switchMusic 与 switchEffect）
- 播放进度控制（progressMusic）
- 全局播放状态控制（pauseAll/resumeAll/stopAll）
- 用户音频设置的本地持久化（save/load）

```mermaid
flowchart TD
A[音效管理系统] --> B[背景音乐管理]
A --> C[音效管理]
A --> D[状态控制]
A --> E[数据持久化]
B --> F[异步加载]
B --> G[音量控制]
B --> H[进度控制]
C --> I[异步加载]
C --> J[音量控制]
D --> K[暂停/恢复/停止]
E --> L[保存/加载]
```

**Diagram sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L10-L201)

## 背景音乐管理

### 播放与加载机制
通过 `playMusic` 或 `playerMusicLoop` 方法播放背景音乐，系统会异步加载音频资源。播放前会自动释放先前的音乐资源，确保内存高效利用。

```mermaid
sequenceDiagram
participant 游戏逻辑
participant AudioManager
participant AudioMusic
participant 资源系统
游戏逻辑->>AudioManager : playMusic("audios/nocturne")
AudioManager->>AudioManager : 检查switchMusic开关
AudioManager->>AudioMusic : load(url)
AudioMusic->>资源系统 : oops.res.load(url, AudioClip)
资源系统-->>AudioMusic : 返回AudioClip
AudioMusic->>AudioMusic : 停止当前播放，设置新音频
AudioMusic->>AudioMusic : 开始播放
```

**Diagram sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L37-L55)
- [AudioMusic.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioMusic.ts#L40-L60)

### 音量与开关控制
提供 `volumeMusic` 属性设置背景音乐音量（范围0-1），`switchMusic` 属性控制开关状态。关闭时会自动停止播放。

**Section sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L65-L85)

### 进度控制
通过 `progressMusic` 属性获取或设置音乐播放进度（0-1）。设置时会自动调整 `currentTime` 实现跳转。

**Section sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L57-L63)

## 音效管理

### 播放机制
通过 `playEffect` 方法播放音效，系统异步加载音频资源后使用 `playOneShot` 播放。每个音效资源会被缓存，避免重复加载。

```mermaid
sequenceDiagram
participant 游戏逻辑
participant AudioManager
participant AudioEffect
participant 资源系统
游戏逻辑->>AudioManager : playEffect("audios/Gravel")
AudioManager->>AudioManager : 检查switchEffect开关
AudioManager->>AudioEffect : load(url)
AudioEffect->>资源系统 : oops.res.load(url, AudioClip)
资源系统-->>AudioEffect : 返回AudioClip
AudioEffect->>AudioEffect : 缓存AudioClip
AudioEffect->>AudioEffect : playOneShot(data, volume)
```

**Diagram sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L101-L108)
- [AudioEffect.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioEffect.ts#L20-L35)

### 音量与开关控制
提供 `volumeEffect` 属性设置音效音量（范围0-1），`switchEffect` 属性控制开关状态。关闭时会停止所有音效播放。

**Section sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L110-L128)

## 播放状态控制
系统提供全局播放状态控制方法：
- `pauseAll()`：暂停所有音乐与音效
- `resumeAll()`：恢复所有暂停的音乐与音效
- `stopAll()`：停止所有音乐与音效播放

这些方法在游戏切入后台时自动调用，确保良好的用户体验。

```mermaid
stateDiagram-v2
[*] --> 播放中
播放中 --> 暂停 : pauseAll()
暂停 --> 播放中 : resumeAll()
播放中 --> 停止 : stopAll()
暂停 --> 停止 : stopAll()
停止 --> 播放中 : playMusic/playEffect
```

**Diagram sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L130-L150)
- [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts#L109-L119)

## 用户设置持久化
系统使用本地存储保存和加载用户音频设置，包括音量和开关状态。

### 保存设置
`save()` 方法将当前音量和开关状态序列化为JSON字符串并存储到本地。

### 加载设置
`load()` 方法在初始化时自动调用，从本地加载设置并应用到音频系统。如果数据损坏，则使用默认值。

```mermaid
flowchart TD
A[初始化] --> B[调用load()]
B --> C{本地数据存在?}
C --> |是| D[解析JSON数据]
C --> |否| E[使用默认值]
D --> F{解析成功?}
F --> |是| G[应用音量和开关设置]
F --> |否| H[使用默认值]
G --> I[初始化AudioMusic和AudioEffect组件]
H --> I
I --> J[系统就绪]
```

**Diagram sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L152-L198)

## 关键节点集成示例

### 游戏启动
在游戏启动时，系统自动初始化音频管理器并加载用户设置：

```typescript
// Root.ts 中的初始化代码
oops.audio = this.persistRootNode.addComponent(AudioManager);
oops.audio.load(); // 加载用户音频设置
```

**Section sources**
- [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts#L92-L93)

### 战斗开始
在战斗相关组件中，可通过封装的方法播放音效：

```typescript
// GameComponent.ts 中的封装方法
playEffect(url: string) {
    this.resPaths.set(url, oops.res.defaultBundleName);
    oops.audio.playEffect(url);
}
```

**Section sources**
- [GameComponent.ts](file://extensions/oops-plugin-framework/assets/module/common/GameComponent.ts#L180-L196)

### 技能释放
在技能控制组件中，可根据技能类型播放相应音效：

```typescript
// 示例：技能释放时播放音效
this.HeroView.playSkillEffect(skill_id);
// 内部实现可能调用 oops.audio.playEffect(...)
```

**Section sources**
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L720-L746)

## 性能优化建议

### 避免频繁创建
- 音效资源会被缓存，避免重复加载
- 使用 `playOneShot` 而非创建多个 AudioSource 组件
- 在对象销毁时调用 `release()` 释放资源

### 音量层级管理
- 合理设置 `volumeMusic` 和 `volumeEffect` 的默认值
- 提供用户界面让玩家自定义音量
- 背景音乐音量通常低于音效音量，保持平衡

### 资源管理
- 使用资源路径规范，便于管理和加载
- 在适当时机预加载常用音效
- 定期清理不常用的音效缓存

**Section sources**
- [AudioEffect.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioEffect.ts#L37-L44)
- [AudioMusic.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioMusic.ts#L80-L89)

## 系统架构
音效管理系统采用组件化设计，核心类关系如下：

```mermaid
classDiagram
class AudioManager {
+local_data : any
+music : AudioMusic
+effect : AudioEffect
+playMusic(url : string)
+playEffect(url : string)
+pauseAll()
+resumeAll()
+stopAll()
+save()
+load()
}
class AudioMusic {
+onComplete : Function | null
+progress : number
+volume : number
+load(url : string)
+play()
+pause()
+stop()
}
class AudioEffect {
+effects : Map~string, AudioClip~
+load(url : string)
+playOneShot()
+release()
}
AudioManager --> AudioMusic : "包含"
AudioManager --> AudioEffect : "包含"
AudioMusic --|> AudioSource : "继承"
AudioEffect --|> AudioSource : "继承"
```

**Diagram sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L10-L201)
- [AudioMusic.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioMusic.ts#L10-L90)
- [AudioEffect.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioEffect.ts#L10-L45)

## 依赖关系
音效管理系统依赖于框架的其他核心模块：

```mermaid
graph TB
AudioManager --> oops.res : "资源加载"
AudioManager --> oops.storage : "本地存储"
AudioManager --> oops.log : "错误日志"
Root --> AudioManager : "初始化"
GameComponent --> AudioManager : "使用接口"
subgraph "核心依赖"
oops.res
oops.storage
oops.log
end
subgraph "使用方"
Root
GameComponent
其他游戏组件
end
```

**Diagram sources**
- [AudioManager.ts](file://extensions/oops-plugin-framework/assets/core/common/audio/AudioManager.ts#L1-L201)
- [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts#L85-L143)