refactor(game): 移除已弃用的事件常量
- 删除 UpdateHero 和 UpdateFightHero 事件 - 移除 MISSION_UPDATE 事件常量 - 优化游戏事件枚举定义
This commit is contained in:
panw
301
.qoder/repowiki/zh/content/辅助系统/音效管理系统.md
Normal file
301
.qoder/repowiki/zh/content/辅助系统/音效管理系统.md
Normal file
@@ -0,0 +1,301 @@
|
||||
# 音效管理系统
|
||||
|
||||
<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)
|
||||
Reference in New Issue
Block a user