10 KiB
音效管理系统
**本文档引用文件** - [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)目录
简介
Oops Framework 音效管理模块为游戏提供完整的音频解决方案，涵盖背景音乐与音效两大核心功能。该系统在游戏启动时自动初始化，支持异步资源加载、音量控制、播放状态管理及用户偏好设置的本地持久化。通过简洁的接口设计，开发者可轻松在游戏各关键节点集成音效，提升用户体验。
Section sources
核心功能
音效管理系统提供以下核心功能：
- 背景音乐与音效的异步加载与播放
- 独立的音量控制（musicVolume 与 volumeEffect）
- 开关状态管理（switchMusic 与 switchEffect）
- 播放进度控制（progressMusic）
- 全局播放状态控制（pauseAll/resumeAll/stopAll）
- 用户音频设置的本地持久化（save/load）
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
背景音乐管理
播放与加载机制
通过 playMusic 或 playerMusicLoop 方法播放背景音乐，系统会异步加载音频资源。播放前会自动释放先前的音乐资源，确保内存高效利用。
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
音量与开关控制
提供 volumeMusic 属性设置背景音乐音量（范围0-1），switchMusic 属性控制开关状态。关闭时会自动停止播放。
Section sources
进度控制
通过 progressMusic 属性获取或设置音乐播放进度（0-1）。设置时会自动调整 currentTime 实现跳转。
Section sources
音效管理
播放机制
通过 playEffect 方法播放音效，系统异步加载音频资源后使用 playOneShot 播放。每个音效资源会被缓存，避免重复加载。
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
音量与开关控制
提供 volumeEffect 属性设置音效音量（范围0-1），switchEffect 属性控制开关状态。关闭时会停止所有音效播放。
Section sources
播放状态控制
系统提供全局播放状态控制方法：
pauseAll()：暂停所有音乐与音效resumeAll()：恢复所有暂停的音乐与音效stopAll()：停止所有音乐与音效播放
这些方法在游戏切入后台时自动调用，确保良好的用户体验。
stateDiagram-v2
[*] --> 播放中
播放中 --> 暂停 : pauseAll()
暂停 --> 播放中 : resumeAll()
播放中 --> 停止 : stopAll()
暂停 --> 停止 : stopAll()
停止 --> 播放中 : playMusic/playEffect
Diagram sources
用户设置持久化
系统使用本地存储保存和加载用户音频设置，包括音量和开关状态。
保存设置
save() 方法将当前音量和开关状态序列化为JSON字符串并存储到本地。
加载设置
load() 方法在初始化时自动调用，从本地加载设置并应用到音频系统。如果数据损坏，则使用默认值。
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
关键节点集成示例
游戏启动
在游戏启动时，系统自动初始化音频管理器并加载用户设置：
// Root.ts 中的初始化代码
oops.audio = this.persistRootNode.addComponent(AudioManager);
oops.audio.load(); // 加载用户音频设置
Section sources
战斗开始
在战斗相关组件中，可通过封装的方法播放音效：
// GameComponent.ts 中的封装方法
playEffect(url: string) {
this.resPaths.set(url, oops.res.defaultBundleName);
oops.audio.playEffect(url);
}
Section sources
技能释放
在技能控制组件中，可根据技能类型播放相应音效：
// 示例：技能释放时播放音效
this.HeroView.playSkillEffect(skill_id);
// 内部实现可能调用 oops.audio.playEffect(...)
Section sources
性能优化建议
避免频繁创建
- 音效资源会被缓存，避免重复加载
- 使用
playOneShot而非创建多个 AudioSource 组件 - 在对象销毁时调用
release()释放资源
音量层级管理
- 合理设置
volumeMusic和volumeEffect的默认值 - 提供用户界面让玩家自定义音量
- 背景音乐音量通常低于音效音量，保持平衡
资源管理
- 使用资源路径规范，便于管理和加载
- 在适当时机预加载常用音效
- 定期清理不常用的音效缓存
Section sources
系统架构
音效管理系统采用组件化设计，核心类关系如下：
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
依赖关系
音效管理系统依赖于框架的其他核心模块：
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