refactor(game): 移除已弃用的事件常量
- 删除 UpdateHero 和 UpdateFightHero 事件 - 移除 MISSION_UPDATE 事件常量 - 优化游戏事件枚举定义
This commit is contained in:
panw
521
.qoder/repowiki/zh/content/辅助系统/新手引导系统.md
Normal file
521
.qoder/repowiki/zh/content/辅助系统/新手引导系统.md
Normal file
@@ -0,0 +1,521 @@
|
||||
# 新手引导系统
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts)
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts)
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||||
- [guide_step.prefab](file://assets/resources/gui/element/guide_step.prefab)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [系统架构](#系统架构)
|
||||
3. [核心数据结构](#核心数据结构)
|
||||
4. [引导配置管理](#引导配置管理)
|
||||
5. [引导流程控制](#引导流程控制)
|
||||
6. [UI高亮与交互](#ui高亮与交互)
|
||||
7. [事件监听与进度管理](#事件监听与进度管理)
|
||||
8. [与Oops GUI系统集成](#与oops-gui系统集成)
|
||||
9. [实际应用示例](#实际应用示例)
|
||||
10. [跳过逻辑与资源清理](#跳过逻辑与资源清理)
|
||||
11. [总结](#总结)
|
||||
|
||||
## 简介
|
||||
|
||||
新手引导系统是游戏中的重要组成部分，用于指导新玩家了解游戏的基本操作和核心玩法。本系统基于Oops框架构建，采用组件化设计，支持多种引导类型，具备完善的进度管理和事件驱动机制。
|
||||
|
||||
系统的主要特点包括：
|
||||
- 支持点击、拖拽、提示、等待等多种引导类型
|
||||
- 基于事件驱动的触发机制
|
||||
- 完善的进度跟踪和状态管理
|
||||
- 与Oops GUI系统的深度集成
|
||||
- 可扩展的配置化引导方案
|
||||
|
||||
## 系统架构
|
||||
|
||||
新手引导系统采用分层架构设计，包含配置层、控制层和UI层三个主要部分：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "配置层"
|
||||
GC[GuideConfig<br/>引导配置]
|
||||
GEC[EndEventToKey<br/>事件映射]
|
||||
GT[GuideTypes<br/>引导类型]
|
||||
end
|
||||
subgraph "控制层"
|
||||
GCC[GuideConComp<br/>引导控制器]
|
||||
SM[SingletonModule<br/>单例模块]
|
||||
GE[GameEvent<br/>游戏事件]
|
||||
end
|
||||
subgraph "UI层"
|
||||
GSC[GuideSetpComp<br/>引导步骤UI]
|
||||
GUI[Oops GUI<br/>界面管理]
|
||||
GS[Guide Step<br/>引导步骤]
|
||||
end
|
||||
subgraph "资源层"
|
||||
PREFAB[guide_step.prefab<br/>引导UI预制体]
|
||||
CONFIG[GameUIConfig<br/>UI配置]
|
||||
end
|
||||
GC --> GCC
|
||||
GEC --> GCC
|
||||
GT --> GCC
|
||||
GCC --> GSC
|
||||
SM --> GCC
|
||||
GE --> GCC
|
||||
GSC --> GUI
|
||||
GUI --> GS
|
||||
PREFAB --> GSC
|
||||
CONFIG --> GUI
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L1-L283)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L220)
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L1-L268)
|
||||
|
||||
## 核心数据结构
|
||||
|
||||
### 引导步骤类型枚举
|
||||
|
||||
系统定义了四种基本的引导步骤类型：
|
||||
|
||||
| 类型 | 枚举值 | 描述 | 适用场景 |
|
||||
|------|--------|------|----------|
|
||||
| 点击操作 | `CLICK` | 用户需要点击目标节点 | 按钮激活、功能解锁 |
|
||||
| 拖拽操作 | `DRAG` | 用户需要拖拽目标节点 | 物品移动、场景探索 |
|
||||
| 显示提示 | `TIP` | 显示文字提示信息 | 游戏说明、规则介绍 |
|
||||
| 等待操作 | `WAIT` | 等待特定时间或条件 | 动画播放、效果展示 |
|
||||
|
||||
### 引导步骤配置接口
|
||||
|
||||
每个引导步骤都遵循统一的配置接口规范：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IGuideStep {
|
||||
+string id
|
||||
+GuideStepType type
|
||||
+number key
|
||||
+string targetPath
|
||||
+string tipParent
|
||||
+string tipText
|
||||
+Vec2 tipOffset
|
||||
+Vec2 handOffset
|
||||
+string nextStep
|
||||
+boolean skippable
|
||||
+function condition
|
||||
+UIID uiId
|
||||
+number waitTime
|
||||
+string end_event
|
||||
+boolean noInput
|
||||
}
|
||||
class GuideStepType {
|
||||
<<enumeration>>
|
||||
CLICK
|
||||
DRAG
|
||||
TIP
|
||||
WAIT
|
||||
}
|
||||
class UIID {
|
||||
<<enumeration>>
|
||||
Guide = 1001
|
||||
}
|
||||
IGuideStep --> GuideStepType
|
||||
IGuideStep --> UIID
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L25-L50)
|
||||
|
||||
**章节来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L1-L283)
|
||||
|
||||
## 引导配置管理
|
||||
|
||||
### 引导配置数据结构
|
||||
|
||||
引导系统采用数字ID与字符串ID双重索引的方式管理引导配置：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
GuideConfig {
|
||||
number key PK
|
||||
string id UK
|
||||
GuideStepType type
|
||||
number target_key
|
||||
string target_path
|
||||
string tip_text
|
||||
vec2 hand_offset
|
||||
string next_step
|
||||
number wait_time
|
||||
string end_event
|
||||
boolean skippable
|
||||
}
|
||||
EndEventToKey {
|
||||
string end_event PK
|
||||
array guide_keys
|
||||
}
|
||||
SingletonModule {
|
||||
array guides
|
||||
number current_guide
|
||||
}
|
||||
GuideConfig ||--o{ EndEventToKey : "maps to"
|
||||
SingletonModule ||--o{ GuideConfig : "tracks progress"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L52-L120)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L35-L40)
|
||||
|
||||
### 引导配置示例
|
||||
|
||||
系统提供了完整的三步引导示例，展示了不同类型引导的实际应用场景：
|
||||
|
||||
| 步骤ID | 类型 | 目标路径 | 提示文本 | 手指偏移 |
|
||||
|--------|------|----------|----------|----------|
|
||||
| welcome | WAIT | root/gui/LayerUI/role_controller/mission_home/start/name | "伟大的勇者,欢迎来到 『像素模拟战』" | {42, -45} |
|
||||
| start_battle | CLICK | root/gui/LayerUI/role_controller/mission_home/start/name | "请带领您的英雄抵御兽人的入侵吧！" | {42, -45} |
|
||||
| hero_page | CLICK | root/gui/LayerUI/role_controller/mission_home/btns/heros | "在酒馆招募更多英雄增强队伍" | {42, -45} |
|
||||
|
||||
**章节来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L52-L120)
|
||||
|
||||
## 引导流程控制
|
||||
|
||||
### 引导控制器架构
|
||||
|
||||
引导控制器负责整个引导流程的协调和管理：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Player as 玩家
|
||||
participant GCC as GuideConComp
|
||||
participant SM as SingletonModule
|
||||
participant GSC as GuideSetpComp
|
||||
participant GUI as Oops GUI
|
||||
Player->>GCC : 触发引导事件
|
||||
GCC->>GCC : 验证引导权限
|
||||
GCC->>GSC : 创建引导步骤UI
|
||||
GSC->>GUI : 打开引导界面
|
||||
GUI-->>GSC : UI加载完成
|
||||
GSC->>GSC : 显示引导内容
|
||||
Player->>GSC : 完成引导操作
|
||||
GSC->>GCC : 步骤完成回调
|
||||
GCC->>GCC : 检查下一步骤
|
||||
GCC->>GSC : 启动下一引导
|
||||
Note over GCC,GSC : 循环直到引导完成
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L40-L80)
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L80-L120)
|
||||
|
||||
### 引导启动机制
|
||||
|
||||
引导系统采用事件驱动的启动方式，支持多种触发条件：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([引导启动请求]) --> CheckPermission{检查权限}
|
||||
CheckPermission --> |权限不足| ReturnError[返回错误]
|
||||
CheckPermission --> |权限充足| GetGuide[获取引导配置]
|
||||
GetGuide --> ValidateConfig{验证配置}
|
||||
ValidateConfig --> |配置无效| ReturnError
|
||||
ValidateConfig --> |配置有效| ClosePrevious[关闭之前引导]
|
||||
ClosePrevious --> OpenUI[打开引导UI]
|
||||
OpenUI --> ShowStep[显示引导步骤]
|
||||
ShowStep --> WaitInput[等待用户输入]
|
||||
WaitInput --> CompleteStep[完成步骤]
|
||||
CompleteStep --> CheckNext{是否有下一步}
|
||||
CheckNext --> |有| StartNext[启动下一引导]
|
||||
CheckNext --> |无| CompleteGuide[完成引导]
|
||||
StartNext --> ShowStep
|
||||
CompleteGuide --> End([引导结束])
|
||||
ReturnError --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L50-L90)
|
||||
|
||||
**章节来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L220)
|
||||
|
||||
## UI高亮与交互
|
||||
|
||||
### 引导步骤UI组件
|
||||
|
||||
引导步骤UI组件负责显示引导内容和处理用户交互：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class GuideSetpComp {
|
||||
+Label tipLabel
|
||||
+Node tipNode
|
||||
+Node handNode
|
||||
+Button skipButton
|
||||
-IGuideStep currentStep
|
||||
-number currentStepIndex
|
||||
-number totalSteps
|
||||
-Node _targetNode
|
||||
-Node _tipParent
|
||||
-boolean _showTip
|
||||
-boolean _showHand
|
||||
-any _callback
|
||||
-boolean _noInput
|
||||
-boolean _hasTouchListener
|
||||
+onAdded(args) void
|
||||
+handleStepInfo(data) void
|
||||
+findTargetNode(path) Node
|
||||
+showStep(step, index, total) void
|
||||
+onTouchStart(event) void
|
||||
+addTouchListener() void
|
||||
+removeTouchListener() void
|
||||
+onSkipButtonClick() void
|
||||
+cleanup() void
|
||||
}
|
||||
class GuideStepType {
|
||||
<<enumeration>>
|
||||
CLICK
|
||||
DRAG
|
||||
TIP
|
||||
WAIT
|
||||
}
|
||||
GuideSetpComp --> GuideStepType
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L10-L50)
|
||||
|
||||
### 目标节点查找机制
|
||||
|
||||
系统提供了灵活的目标节点查找机制，支持相对路径和绝对路径两种方式：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始查找目标节点]) --> SplitPath[分割路径字符串]
|
||||
SplitPath --> GetScene[获取场景根节点]
|
||||
GetScene --> LoopPath{遍历路径段}
|
||||
LoopPath --> |路径段存在| GetChild[获取子节点]
|
||||
LoopPath --> |路径段不存在| NotFound[节点未找到]
|
||||
GetChild --> CheckChild{检查子节点}
|
||||
CheckChild --> |找到| NextSegment[下一段]
|
||||
CheckChild --> |未找到| NotFound
|
||||
NextSegment --> MoreSegments{还有更多段?}
|
||||
MoreSegments --> |是| LoopPath
|
||||
MoreSegments --> |否| Found[节点找到]
|
||||
NotFound --> LogError[记录错误日志]
|
||||
Found --> ReturnNode[返回节点对象]
|
||||
LogError --> ReturnNull[返回null]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L180-L220)
|
||||
|
||||
**章节来源**
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L1-L268)
|
||||
|
||||
## 事件监听与进度管理
|
||||
|
||||
### 事件监听机制
|
||||
|
||||
引导系统实现了完善的事件监听机制，支持多种交互方式：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant GSC as GuideSetpComp
|
||||
participant Node as UI节点
|
||||
participant Touch as 触摸系统
|
||||
participant Callback as 回调函数
|
||||
GSC->>Node : 添加触摸监听器
|
||||
Node->>Touch : 注册事件监听
|
||||
Touch-->>Node : 触摸事件发生
|
||||
Node->>GSC : 触摸事件回调
|
||||
GSC->>GSC : 验证引导类型
|
||||
GSC->>Callback : 调用完成回调
|
||||
Callback->>GSC : 清理资源
|
||||
GSC->>Node : 移除监听器
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L50-L90)
|
||||
|
||||
### 进度管理系统
|
||||
|
||||
系统采用数组形式管理引导进度，每个引导步骤对应数组的一个元素：
|
||||
|
||||
| 状态 | 数值 | 描述 | 影响 |
|
||||
|------|------|------|------|
|
||||
| 未开始 | 0 | 引导尚未执行 | 可以正常启动 |
|
||||
| 进行中 | 0 | 引导正在执行 | 阻止重复启动 |
|
||||
| 已完成 | 1 | 引导已经完成 | 不再显示该引导 |
|
||||
| 已跳过 | 2 | 用户主动跳过 | 标记状态但不影响其他引导 |
|
||||
|
||||
**章节来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L130-L170)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L80-L90)
|
||||
|
||||
## 与Oops GUI系统集成
|
||||
|
||||
### GUI集成架构
|
||||
|
||||
新手引导系统与Oops GUI系统深度集成，利用其强大的界面管理能力：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Oops GUI系统"
|
||||
GM[GUI Manager]
|
||||
LM[Layer Manager]
|
||||
PM[Prefab Manager]
|
||||
end
|
||||
subgraph "引导系统"
|
||||
GCC[GuideConComp]
|
||||
GSC[GuideSetpComp]
|
||||
UI[UI Config]
|
||||
end
|
||||
subgraph "资源管理"
|
||||
PREFAB[guide_step.prefab]
|
||||
ASSETS[引导资源]
|
||||
end
|
||||
GCC --> GM
|
||||
GSC --> LM
|
||||
UI --> PM
|
||||
PREFAB --> PM
|
||||
ASSETS --> PM
|
||||
GM --> UI
|
||||
LM --> GSC
|
||||
PM --> PREFAB
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L20-L35)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L170-L200)
|
||||
|
||||
### UI配置管理
|
||||
|
||||
系统通过统一的UI配置管理引导界面的加载和显示：
|
||||
|
||||
| 配置项 | 值 | 说明 |
|
||||
|--------|-----|------|
|
||||
| UIID.Guide | 1001 | 引导界面的唯一标识 |
|
||||
| LayerType | UI | 界面层级类型 |
|
||||
| Prefab路径 | gui/element/guide_step | 引导UI预制体路径 |
|
||||
| Bundle | resources | 资源包名称 |
|
||||
|
||||
**章节来源**
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L36)
|
||||
|
||||
## 实际应用示例
|
||||
|
||||
### 新增三步引导流程
|
||||
|
||||
以下是如何新增一个完整的三步引导流程的完整示例：
|
||||
|
||||
#### 1. 配置引导数据
|
||||
|
||||
```typescript
|
||||
// 在Guide.ts中添加新的引导配置
|
||||
export const GuideConfig: { [key: number]: IGuideStep } = {
|
||||
// ... 现有引导配置 ...
|
||||
|
||||
11: {
|
||||
id: "new_feature_tutorial",
|
||||
type: GuideStepType.CLICK,
|
||||
key: 11,
|
||||
targetPath: "root/gui/LayerUI/new_feature_panel/button",
|
||||
tipText: "点击这里体验新功能！",
|
||||
handOffset: { x: 42, y: -45 },
|
||||
nextStep: "feature_explanation",
|
||||
skippable: true
|
||||
},
|
||||
|
||||
12: {
|
||||
id: "feature_explanation",
|
||||
type: GuideStepType.TIP,
|
||||
key: 12,
|
||||
targetPath: "root/gui/LayerUI/new_feature_panel/explanation",
|
||||
tipText: "这是全新的功能特性，让游戏更加有趣！",
|
||||
tipOffset: { x: 0, y: 100 },
|
||||
waitTime: 3000,
|
||||
nextStep: "feature_usage"
|
||||
},
|
||||
|
||||
13: {
|
||||
id: "feature_usage",
|
||||
type: GuideStepType.CLICK,
|
||||
key: 13,
|
||||
targetPath: "root/gui/LayerUI/new_feature_panel/usage_button",
|
||||
tipText: "现在尝试使用这个功能吧！",
|
||||
handOffset: { x: 42, y: -45 },
|
||||
skippable: true
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
#### 2. 触发引导启动
|
||||
|
||||
```typescript
|
||||
// 在适当的游戏事件中触发引导
|
||||
oops.message.dispatchEvent(GameEvent.GuideStart, 11);
|
||||
```
|
||||
|
||||
#### 3. 处理用户交互
|
||||
|
||||
系统会自动处理用户的点击、拖拽等交互行为，并根据配置自动推进到下一步骤。
|
||||
|
||||
#### 4. 完成回调处理
|
||||
|
||||
当引导完成后，系统会自动更新进度状态并清理相关资源。
|
||||
|
||||
**章节来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L52-L120)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L50-L90)
|
||||
|
||||
## 跳过逻辑与资源清理
|
||||
|
||||
### 跳过按钮实现
|
||||
|
||||
引导系统提供了完善的跳过功能，允许用户主动终止引导流程：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([用户点击跳过]) --> HideTips[隐藏提示内容]
|
||||
HideTips --> DestroyHands[销毁手势动画]
|
||||
DestroyHands --> RemoveListeners[移除事件监听器]
|
||||
RemoveListeners --> CallCallback[调用完成回调]
|
||||
CallCallback --> CleanupResources[清理资源]
|
||||
CleanupResources --> CloseUI[关闭引导界面]
|
||||
CloseUI --> End([跳过完成])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L240-L260)
|
||||
|
||||
### 资源清理机制
|
||||
|
||||
系统实现了多层次的资源清理机制，确保内存使用效率：
|
||||
|
||||
| 清理阶段 | 清理内容 | 触发时机 |
|
||||
|----------|----------|----------|
|
||||
| 步骤完成 | 移除触摸监听器 | 每个步骤结束后 |
|
||||
| 引导取消 | 销毁UI组件 | 用户跳过时 |
|
||||
| 组件销毁 | 清理所有资源 | 组件生命周期结束 |
|
||||
| 内存回收 | 释放引用 | 系统垃圾回收 |
|
||||
|
||||
**章节来源**
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L240-L268)
|
||||
|
||||
## 总结
|
||||
|
||||
新手引导系统是一个功能完善、架构清晰的游戏辅助系统。它具有以下核心优势：
|
||||
|
||||
1. **模块化设计**：采用分层架构，职责明确，易于维护和扩展
|
||||
2. **事件驱动**：基于事件的触发机制，灵活性强，适应各种游戏场景
|
||||
3. **配置化管理**：支持通过配置文件管理引导流程，减少代码耦合
|
||||
4. **资源优化**：完善的资源清理机制，确保良好的性能表现
|
||||
5. **用户体验**：直观的UI设计和流畅的交互体验
|
||||
|
||||
开发者可以通过本系统快速实现各种类型的引导功能，为新用户提供良好的游戏体验。系统的可扩展性也确保了随着游戏发展，可以轻松添加新的引导内容和功能。
|
||||
533
.qoder/repowiki/zh/content/辅助系统/日志输出系统.md
Normal file
533
.qoder/repowiki/zh/content/辅助系统/日志输出系统.md
Normal file
@@ -0,0 +1,533 @@
|
||||
# 日志输出系统
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [log.md](file://doc/core/common/log.md)
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts)
|
||||
- [Hero.ts](file://assets/script/game/hero/Hero.ts)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts)
|
||||
- [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts)
|
||||
- [GameConfig.ts](file://extensions/oops-plugin-framework/assets/module/config/GameConfig.ts)
|
||||
- [GUI.ts](file://extensions/oops-plugin-framework/assets/core/gui/GUI.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [日志系统架构](#日志系统架构)
|
||||
3. [日志输出方法详解](#日志输出方法详解)
|
||||
4. [日志格式与结构](#日志格式与结构)
|
||||
5. [性能分析工具](#性能分析工具)
|
||||
6. [日志表格化输出](#日志表格化输出)
|
||||
7. [实际开发示例](#实际开发示例)
|
||||
8. [日志级别与模块分类](#日志级别与模块分类)
|
||||
9. [生产环境日志控制](#生产环境日志控制)
|
||||
10. [最佳实践指南](#最佳实践指南)
|
||||
|
||||
## 简介
|
||||
|
||||
Oops Framework 提供了一套完整而强大的日志管理系统，专门针对复杂的游戏业务逻辑进行优化。该系统不仅提供了多种颜色标识的日志输出方式，还集成了性能分析、表格化展示等高级功能，为开发者提供了全方位的调试支持。
|
||||
|
||||
日志系统的核心设计理念是通过颜色编码和模块分类来区分不同类型的日志信息，使开发者能够快速定位问题所在。同时，系统支持灵活的日志级别控制，可以在生产环境中安全地关闭不必要的日志输出，确保应用性能不受影响。
|
||||
|
||||
## 日志系统架构
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Logger {
|
||||
-tags : number
|
||||
+setTags(tag : LogType) : void
|
||||
+trace(msg : any, color : string) : void
|
||||
+logNet(msg : any, describe? : string) : void
|
||||
+logModel(msg : any, describe? : string) : void
|
||||
+logBusiness(msg : any, describe? : string) : void
|
||||
+logView(msg : any, describe? : string) : void
|
||||
+logConfig(msg : any, describe? : string) : void
|
||||
+start(describe : string) : void
|
||||
+end(describe : string) : void
|
||||
+table(msg : any, describe? : string) : void
|
||||
-isOpen(tag : LogType) : boolean
|
||||
-print(tag : LogType, msg : any, color : string, describe? : string) : void
|
||||
-stack(index : number) : string
|
||||
-getDateString() : string
|
||||
}
|
||||
class LogType {
|
||||
<<enumeration>>
|
||||
Net : 1
|
||||
Model : 2
|
||||
Business : 4
|
||||
View : 8
|
||||
Config : 16
|
||||
Trace : 32
|
||||
}
|
||||
Logger --> LogType : uses
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L1-L281)
|
||||
|
||||
**章节来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L1-L50)
|
||||
|
||||
## 日志输出方法详解
|
||||
|
||||
### 基础日志输出
|
||||
|
||||
系统提供了六种不同类型的日志输出方法，每种方法对应不同的业务模块和颜色标识：
|
||||
|
||||
| 方法名 | 颜色标识 | 用途描述 | 适用场景 |
|
||||
|--------|----------|----------|----------|
|
||||
| `trace()` | 黑色 | 默认标准日志 | 通用调试信息 |
|
||||
| `logConfig()` | 灰色 | 配置相关日志 | 游戏配置、参数设置 |
|
||||
| `logNet()` | 橙色 | 网络通信日志 | 网络请求、数据传输 |
|
||||
| `logModel()` | 紫色 | 数据模型日志 | 数据结构、状态变更 |
|
||||
| `logBusiness()` | 蓝色 | 业务逻辑日志 | 游戏流程、规则执行 |
|
||||
| `logView()` | 绿色 | 视图界面日志 | UI交互、渲染操作 |
|
||||
|
||||
### 性能分析方法
|
||||
|
||||
#### start() 和 end() 方法
|
||||
|
||||
这两个方法用于性能耗时分析，通过浏览器的 `console.time()` 和 `console.timeEnd()` 实现精确的时间测量：
|
||||
|
||||
```typescript
|
||||
// 性能分析使用示例
|
||||
oops.log.start("数据加载耗时");
|
||||
// 执行耗时操作
|
||||
const result = await loadData();
|
||||
oops.log.end("数据加载耗时");
|
||||
```
|
||||
|
||||
#### 工作原理
|
||||
|
||||
- `start()` 方法启动计时器，记录开始时间
|
||||
- `end()` 方法停止计时器，计算并输出执行时间
|
||||
- 支持自定义描述信息，便于识别不同的性能测量点
|
||||
|
||||
**章节来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L45-L85)
|
||||
|
||||
## 日志格式与结构
|
||||
|
||||
### 标准日志格式
|
||||
|
||||
所有日志输出都遵循统一的格式规范：
|
||||
|
||||
```
|
||||
[时间戳][日志类型][文件路径->方法名]:日志内容
|
||||
```
|
||||
|
||||
### 格式组成部分详解
|
||||
|
||||
| 组件 | 格式 | 示例 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 时间戳 | `[HH:mm:ss:SSS]` | `[11:31:07:293]` | 精确到毫秒的时间标记 |
|
||||
| 日志类型 | `[类型名称]` | `[网络日志]` | 通过颜色区分的模块标识 |
|
||||
| 文件路径 | `[文件名.ts]` 或 `[文件名.ts->方法名]` | `[Hero.ts->load]` | 调用位置的精确追踪 |
|
||||
| 日志内容 | `具体内容` | `'英雄加载完成'` | 实际的日志消息内容 |
|
||||
|
||||
### 文件路径解析机制
|
||||
|
||||
系统自动解析调用栈，提取文件名和方法名：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[调用堆栈] --> B[解析错误对象]
|
||||
B --> C[分割堆栈行]
|
||||
C --> D[提取文件信息]
|
||||
D --> E{文件类型判断}
|
||||
E --> |单文件| F[返回文件名]
|
||||
E --> |方法调用| G[返回文件名->方法名]
|
||||
F --> H[格式化输出]
|
||||
G --> H
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L150-L200)
|
||||
|
||||
**章节来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L150-L281)
|
||||
|
||||
## 性能分析工具
|
||||
|
||||
### 时间测量功能
|
||||
|
||||
系统内置了精确的性能分析工具，支持：
|
||||
|
||||
#### 基本用法
|
||||
```typescript
|
||||
// 开始性能测量
|
||||
oops.log.start("复杂算法执行");
|
||||
|
||||
// 执行需要测量的代码
|
||||
for (let i = 0; i < 1000000; i++) {
|
||||
// 复杂计算
|
||||
Math.sqrt(i);
|
||||
}
|
||||
|
||||
// 结束测量并输出结果
|
||||
oops.log.end("复杂算法执行");
|
||||
```
|
||||
|
||||
#### 多重测量
|
||||
```typescript
|
||||
// 测量多个独立的操作
|
||||
oops.log.start("数据预处理");
|
||||
processData();
|
||||
oops.log.end("数据预处理");
|
||||
|
||||
oops.log.start("算法计算");
|
||||
calculateResults();
|
||||
oops.log.end("算法计算");
|
||||
```
|
||||
|
||||
### 性能监控最佳实践
|
||||
|
||||
1. **合理命名测量点**：使用描述性的名称便于识别
|
||||
2. **避免过度测量**：仅测量关键路径和瓶颈点
|
||||
3. **及时清理**：在生产环境中移除性能测量代码
|
||||
|
||||
**章节来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L65-L85)
|
||||
|
||||
## 日志表格化输出
|
||||
|
||||
### table() 方法功能
|
||||
|
||||
`table()` 方法专门用于对象数据的表格化展示，特别适用于调试复杂的数据结构：
|
||||
|
||||
#### 基本用法
|
||||
```typescript
|
||||
// 对象数据表格化输出
|
||||
const playerData = {
|
||||
uid: 1001,
|
||||
name: "勇者",
|
||||
level: 25,
|
||||
hp: 850,
|
||||
mp: 300,
|
||||
attributes: {
|
||||
strength: 120,
|
||||
agility: 95,
|
||||
intelligence: 110
|
||||
}
|
||||
};
|
||||
|
||||
oops.log.table(playerData, "玩家属性详情");
|
||||
```
|
||||
|
||||
#### 输出效果
|
||||
表格化输出会将对象的键值对以表格形式展示，便于快速查看和比较：
|
||||
|
||||
| 键名 | 值 |
|
||||
|------|-----|
|
||||
| uid | 1001 |
|
||||
| name | "勇者" |
|
||||
| level | 25 |
|
||||
| hp | 850 |
|
||||
| mp | 300 |
|
||||
| attributes | {...} |
|
||||
|
||||
### 使用场景
|
||||
|
||||
1. **数据结构调试**：查看复杂对象的内部结构
|
||||
2. **配置参数检查**：验证配置数据的正确性
|
||||
3. **状态监控**：跟踪游戏状态的变化
|
||||
4. **性能分析**：对比不同条件下的数据差异
|
||||
|
||||
**章节来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L87-L97)
|
||||
|
||||
## 实际开发示例
|
||||
|
||||
### Hero.ts 中的业务日志
|
||||
|
||||
在英雄系统中，可以使用不同类型的日志来跟踪各种操作：
|
||||
|
||||
```typescript
|
||||
// 英雄加载过程中的日志记录
|
||||
load(pos: Vec3, scale: number, uuid: number = 1001, fight_pos: number = 1) {
|
||||
oops.log.logBusiness("开始加载英雄", { uuid, pos, scale });
|
||||
|
||||
// 加载前的预检查
|
||||
oops.log.logModel("检查英雄槽位可用性");
|
||||
|
||||
// 资源加载
|
||||
oops.log.logNet("从服务器获取英雄资源");
|
||||
|
||||
// 初始化英雄属性
|
||||
oops.log.logBusiness("初始化英雄基础属性");
|
||||
|
||||
// 添加到战斗系统
|
||||
oops.log.logModel("将英雄添加到战斗系统");
|
||||
|
||||
oops.log.logBusiness("英雄加载完成", { uuid, position: pos });
|
||||
}
|
||||
```
|
||||
|
||||
### GameMap.ts 中的地图日志
|
||||
|
||||
地图系统的日志记录示例：
|
||||
|
||||
```typescript
|
||||
load() {
|
||||
oops.log.logView("开始加载地图资源");
|
||||
|
||||
// 资源加载过程
|
||||
oops.log.logNet("加载地图预制体资源");
|
||||
|
||||
// 地图初始化
|
||||
oops.log.logModel("初始化地图数据结构");
|
||||
|
||||
// UI显示
|
||||
oops.log.logView("创建地图显示节点");
|
||||
|
||||
oops.log.logBusiness("地图加载完成");
|
||||
}
|
||||
```
|
||||
|
||||
### Root.ts 中的系统级日志
|
||||
|
||||
全局系统事件的日志记录：
|
||||
|
||||
```typescript
|
||||
// 游戏显示事件
|
||||
game.on(Game.EVENT_SHOW, () => {
|
||||
oops.log.logView("【系统】游戏前台显示");
|
||||
oops.log.logBusiness("恢复游戏运行状态");
|
||||
});
|
||||
|
||||
// 游戏隐藏事件
|
||||
game.on(Game.EVENT_HIDE, () => {
|
||||
oops.log.logView("【系统】游戏切到后台");
|
||||
oops.log.logBusiness("暂停游戏运行状态");
|
||||
});
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [Hero.ts](file://assets/script/game/hero/Hero.ts#L40-L80)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L20-L35)
|
||||
- [Root.ts](file://extensions/oops-plugin-framework/assets/core/Root.ts#L105-L140)
|
||||
|
||||
## 日志级别与模块分类
|
||||
|
||||
### 日志类型枚举
|
||||
|
||||
系统定义了完整的日志类型体系：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[LogType 枚举] --> B[Net<br/>网络层日志]
|
||||
A --> C[Model<br/>数据层日志]
|
||||
A --> D[Business<br/>业务层日志]
|
||||
A --> E[View<br/>视图层日志]
|
||||
A --> F[Config<br/>配置日志]
|
||||
A --> G[Trace<br/>标准日志]
|
||||
B --> B1[网络请求]
|
||||
B --> B2[数据传输]
|
||||
B --> B3[API调用]
|
||||
C --> C1[数据结构]
|
||||
C --> C2[状态变更]
|
||||
C --> C3[缓存操作]
|
||||
D --> D1[游戏流程]
|
||||
D --> D2[规则执行]
|
||||
D --> D3[事件处理]
|
||||
E --> E1[UI交互]
|
||||
E --> E2[渲染操作]
|
||||
E --> E3[动画播放]
|
||||
F --> F1[配置文件]
|
||||
F --> F2[参数设置]
|
||||
F --> F3[初始化数据]
|
||||
G --> G1[通用调试]
|
||||
G --> G2[错误提示]
|
||||
G --> G3[警告信息]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L3-L15)
|
||||
|
||||
### 日志级别控制
|
||||
|
||||
#### setTags() 方法
|
||||
|
||||
通过 `setTags()` 方法可以控制哪些类型的日志会被输出：
|
||||
|
||||
```typescript
|
||||
// 显示所有日志类型
|
||||
oops.log.setTags(
|
||||
LogType.Net | LogType.Model | LogType.Business |
|
||||
LogType.View | LogType.Config | LogType.Trace
|
||||
);
|
||||
|
||||
// 只显示业务和视图日志
|
||||
oops.log.setTags(LogType.Business | LogType.View);
|
||||
|
||||
// 关闭所有日志输出
|
||||
oops.log.setTags(0);
|
||||
```
|
||||
|
||||
#### 默认行为
|
||||
|
||||
系统默认不显示任何日志，需要显式设置日志级别才能看到输出。
|
||||
|
||||
**章节来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L25-L45)
|
||||
|
||||
## 生产环境日志控制
|
||||
|
||||
### 性能优化策略
|
||||
|
||||
在生产环境中，合理的日志控制对于应用性能至关重要：
|
||||
|
||||
#### 1. 条件编译控制
|
||||
|
||||
```typescript
|
||||
// 开发环境启用详细日志
|
||||
#if DEBUG
|
||||
oops.log.setTags(
|
||||
LogType.Net | LogType.Model | LogType.Business |
|
||||
LogType.View | LogType.Config | LogType.Trace
|
||||
);
|
||||
#else
|
||||
// 生产环境关闭所有日志
|
||||
oops.log.setTags(0);
|
||||
#endif
|
||||
```
|
||||
|
||||
#### 2. 动态日志级别调整
|
||||
|
||||
```typescript
|
||||
// 运行时动态调整日志级别
|
||||
class LogManager {
|
||||
static enableDebugLogs(enabled: boolean) {
|
||||
if (enabled) {
|
||||
oops.log.setTags(
|
||||
LogType.Net | LogType.Model | LogType.Business |
|
||||
LogType.View | LogType.Config | LogType.Trace
|
||||
);
|
||||
} else {
|
||||
oops.log.setTags(0);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 模块化日志控制
|
||||
|
||||
```typescript
|
||||
// 针对不同模块设置不同的日志级别
|
||||
class ModuleLogManager {
|
||||
static configureNetworkLogs(enabled: boolean) {
|
||||
const currentTags = oops.log.getTags();
|
||||
const newTags = enabled
|
||||
? currentTags | LogType.Net
|
||||
: currentTags & ~LogType.Net;
|
||||
oops.log.setTags(newTags);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 性能影响评估
|
||||
|
||||
| 日志级别 | 内存占用 | CPU开销 | I/O影响 | 推荐场景 |
|
||||
|----------|----------|---------|---------|----------|
|
||||
| 全部开启 | 高 | 高 | 高 | 开发调试 |
|
||||
| 业务+视图 | 中 | 中 | 中 | 正常测试 |
|
||||
| 仅错误日志 | 低 | 低 | 低 | 生产环境 |
|
||||
|
||||
### 最佳实践建议
|
||||
|
||||
1. **开发阶段**：启用全部日志以便全面调试
|
||||
2. **测试阶段**：启用关键模块日志，减少噪音
|
||||
3. **生产环境**：仅保留错误和关键业务日志
|
||||
4. **定期审查**：定期检查日志输出，移除不必要的日志代码
|
||||
|
||||
**章节来源**
|
||||
- [Logger.ts](file://extensions/oops-plugin-framework/assets/core/common/log/Logger.ts#L25-L45)
|
||||
|
||||
## 最佳实践指南
|
||||
|
||||
### 日志编写原则
|
||||
|
||||
#### 1. 明确目的
|
||||
每次写日志都应该有明确的目的：
|
||||
- 调试特定问题
|
||||
- 监控系统状态
|
||||
- 记录重要事件
|
||||
- 性能分析
|
||||
|
||||
#### 2. 选择合适的日志类型
|
||||
根据日志内容选择最适合的类型：
|
||||
- 网络操作使用 `logNet()`
|
||||
- 数据变更使用 `logModel()`
|
||||
- 用户交互使用 `logView()`
|
||||
- 配置信息使用 `logConfig()`
|
||||
|
||||
#### 3. 提供上下文信息
|
||||
```typescript
|
||||
// 好的做法：提供足够的上下文
|
||||
oops.log.logBusiness("玩家升级", {
|
||||
playerId: player.id,
|
||||
oldLevel: player.level,
|
||||
newLevel: player.level + 1
|
||||
});
|
||||
|
||||
// 避免的做法：缺乏上下文
|
||||
oops.log.logBusiness("玩家升级");
|
||||
```
|
||||
|
||||
### 日志内容组织
|
||||
|
||||
#### 结构化日志
|
||||
```typescript
|
||||
// 使用对象传递复杂信息
|
||||
const logData = {
|
||||
action: "skill_cast",
|
||||
caster: { id: caster.id, name: caster.name },
|
||||
target: { id: target.id, health: target.health },
|
||||
skill: { id: skill.id, name: skill.name },
|
||||
damage: calculatedDamage,
|
||||
timestamp: Date.now()
|
||||
};
|
||||
|
||||
oops.log.logBusiness("技能释放", logData);
|
||||
```
|
||||
|
||||
#### 条件日志记录
|
||||
```typescript
|
||||
// 根据条件决定是否记录详细日志
|
||||
if (DEBUG_MODE) {
|
||||
oops.log.logModel("详细数据状态", gameState);
|
||||
} else {
|
||||
oops.log.logBusiness("游戏状态更新");
|
||||
}
|
||||
```
|
||||
|
||||
### 日志维护策略
|
||||
|
||||
#### 1. 定期清理
|
||||
- 移除不再需要的调试日志
|
||||
- 优化重复的日志输出
|
||||
- 更新过时的日志格式
|
||||
|
||||
#### 2. 日志质量检查
|
||||
- 确保日志信息的准确性
|
||||
- 避免敏感信息泄露
|
||||
- 保持日志格式的一致性
|
||||
|
||||
#### 3. 性能监控
|
||||
- 监控日志输出对性能的影响
|
||||
- 识别高频率的日志输出点
|
||||
- 优化频繁调用的日志方法
|
||||
|
||||
### 团队协作规范
|
||||
|
||||
#### 日志命名约定
|
||||
- 使用描述性的日志描述
|
||||
- 保持术语的一致性
|
||||
- 遵循团队的编码规范
|
||||
|
||||
#### 日志审核流程
|
||||
- 新功能开发时同步添加必要的日志
|
||||
- 代码审查时检查日志的适当性
|
||||
- 定期回顾和优化现有日志
|
||||
|
||||
通过遵循这些最佳实践，可以构建一个高效、可维护的日志系统，既满足开发调试需求，又保证生产环境的性能表现。
|
||||
473
.qoder/repowiki/zh/content/辅助系统/辅助系统.md
Normal file
473
.qoder/repowiki/zh/content/辅助系统/辅助系统.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# 辅助系统
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts)
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts)
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||||
- [log.md](file://doc/core/common/log.md)
|
||||
- [audio.md](file://doc/core/common/audio.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
辅助系统是Cocos游戏框架中的重要组成部分，主要负责新手引导、日志输出管理和音效控制三大核心功能。该系统采用模块化设计，通过事件驱动的方式实现各功能模块间的解耦，提供了灵活且可扩展的辅助功能支持。
|
||||
|
||||
系统的核心特点包括：
|
||||
- **新手引导系统**：提供可视化的操作指导，支持多种交互类型的引导步骤
|
||||
- **日志管理系统**：封装了丰富的日志输出功能，支持不同级别的日志分类
|
||||
- **音效控制系统**：管理背景音乐和音效的播放、暂停、音量控制等功能
|
||||
|
||||
## 项目结构
|
||||
|
||||
辅助系统的文件组织结构清晰，按功能模块进行分类：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "配置层"
|
||||
A[Guide.ts<br/>引导配置]
|
||||
B[GameUIConfig.ts<br/>UI配置]
|
||||
C[GameEvent.ts<br/>事件定义]
|
||||
end
|
||||
subgraph "组件层"
|
||||
D[GuideConComp.ts<br/>引导控制器]
|
||||
E[GuideSetpComp.ts<br/>引导步骤组件]
|
||||
F[SingletonModuleComp.ts<br/>单例模块]
|
||||
end
|
||||
subgraph "工具层"
|
||||
G[log.md<br/>日志规范]
|
||||
H[audio.md<br/>音效规范]
|
||||
end
|
||||
A --> D
|
||||
A --> E
|
||||
B --> D
|
||||
C --> D
|
||||
D --> F
|
||||
E --> F
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L1-L50)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L30)
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L20)
|
||||
|
||||
**章节来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L1-L283)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L220)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 引导系统核心组件
|
||||
|
||||
引导系统包含三个核心组件，每个组件承担不同的职责：
|
||||
|
||||
1. **GuideConfig**：引导配置管理器，负责引导步骤的定义和查找
|
||||
2. **GuideConComp**：引导控制器，负责引导流程的控制和状态管理
|
||||
3. **GuideSetpComp**：引导步骤组件，负责具体的UI显示和用户交互
|
||||
|
||||
### 日志系统核心组件
|
||||
|
||||
日志系统基于Oops Framework的日志管理模块，提供以下功能：
|
||||
- 标准日志输出
|
||||
- 分类日志（配置、网络、数据、业务、视图）
|
||||
- 性能监控（执行时间统计）
|
||||
- 表格格式化输出
|
||||
|
||||
### 音效系统核心组件
|
||||
|
||||
音效系统提供完整的音频管理功能：
|
||||
- 背景音乐播放控制
|
||||
- 音效播放管理
|
||||
- 音量调节和开关控制
|
||||
- 音频资源的异步加载
|
||||
|
||||
**章节来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L1-L100)
|
||||
- [log.md](file://doc/core/common/log.md#L1-L30)
|
||||
- [audio.md](file://doc/core/common/audio.md#L1-L85)
|
||||
|
||||
## 架构概览
|
||||
|
||||
辅助系统采用分层架构设计，确保各功能模块的独立性和可维护性：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "表现层"
|
||||
A[UI界面]
|
||||
B[引导步骤UI]
|
||||
C[日志输出界面]
|
||||
end
|
||||
subgraph "控制层"
|
||||
D[GuideConComp<br/>引导控制器]
|
||||
E[SingletonModuleComp<br/>单例模块]
|
||||
F[事件管理器]
|
||||
end
|
||||
subgraph "服务层"
|
||||
G[引导服务]
|
||||
H[日志服务]
|
||||
I[音效服务]
|
||||
end
|
||||
subgraph "数据层"
|
||||
J[引导配置数据]
|
||||
K[日志配置数据]
|
||||
L[音效配置数据]
|
||||
end
|
||||
A --> D
|
||||
B --> D
|
||||
C --> H
|
||||
D --> G
|
||||
E --> G
|
||||
F --> G
|
||||
G --> J
|
||||
H --> K
|
||||
I --> L
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L15-L35)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L25-L50)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 引导系统详细分析
|
||||
|
||||
#### 引导配置结构
|
||||
|
||||
引导系统的核心是`IGuideStep`接口定义，它描述了引导步骤的所有属性：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IGuideStep {
|
||||
+string id
|
||||
+GuideStepType type
|
||||
+number key
|
||||
+string targetPath
|
||||
+string tipParent
|
||||
+string tipText
|
||||
+Vector2 tipOffset
|
||||
+Vector2 handOffset
|
||||
+string nextStep
|
||||
+boolean skippable
|
||||
+function condition
|
||||
+UIID uiId
|
||||
+number waitTime
|
||||
+string end_event
|
||||
+boolean noInput
|
||||
}
|
||||
class GuideStepType {
|
||||
<<enumeration>>
|
||||
CLICK
|
||||
DRAG
|
||||
TIP
|
||||
WAIT
|
||||
}
|
||||
class GuideConfig {
|
||||
+IGuideStep[] steps
|
||||
+findGuideById(id) IGuideStep
|
||||
+findGuideByNumberId(id) IGuideStep
|
||||
+findGuideIndexById(id) number
|
||||
}
|
||||
IGuideStep --> GuideStepType
|
||||
GuideConfig --> IGuideStep
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L25-L55)
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L84-L110)
|
||||
|
||||
#### 引导流程执行逻辑
|
||||
|
||||
引导控制器负责管理整个引导流程的执行：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Player as 玩家
|
||||
participant Controller as GuideConComp
|
||||
participant StepComp as GuideSetpComp
|
||||
participant SM as SingletonModuleComp
|
||||
participant UI as UI系统
|
||||
Player->>Controller : 触发引导事件
|
||||
Controller->>Controller : 初始化引导进度
|
||||
Controller->>StepComp : 创建引导步骤UI
|
||||
StepComp->>UI : 显示引导界面
|
||||
UI->>Player : 展示引导提示
|
||||
Player->>StepComp : 完成引导操作
|
||||
StepComp->>Controller : 步骤完成回调
|
||||
Controller->>Controller : 检查下一步骤
|
||||
alt 有下一步骤
|
||||
Controller->>StepComp : 显示下个步骤
|
||||
else 无下一步骤
|
||||
Controller->>SM : 标记引导完成
|
||||
Controller->>UI : 关闭引导界面
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L50-L80)
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L80-L120)
|
||||
|
||||
#### UI高亮机制
|
||||
|
||||
引导步骤组件实现了精确的目标节点定位和高亮显示：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[解析目标路径] --> B{路径有效?}
|
||||
B --> |是| C[查找目标节点]
|
||||
B --> |否| D[使用默认节点]
|
||||
C --> E{找到节点?}
|
||||
E --> |是| F[设置高亮样式]
|
||||
E --> |否| G[记录错误日志]
|
||||
D --> F
|
||||
F --> H[计算手指位置]
|
||||
H --> I[显示引导指示器]
|
||||
G --> J[降级处理]
|
||||
J --> I
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L200-L250)
|
||||
|
||||
**章节来源**
|
||||
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L25-L85)
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L50-L150)
|
||||
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L150-L200)
|
||||
|
||||
### 日志系统详细分析
|
||||
|
||||
#### 日志输出规范
|
||||
|
||||
日志系统提供了六种不同级别的日志输出：
|
||||
|
||||
| 日志级别 | 方法名 | 颜色标识 | 使用场景 |
|
||||
|---------|--------|----------|----------|
|
||||
| 标准日志 | `oops.log.trace()` | 默认 | 通用调试信息 |
|
||||
| 配置日志 | `oops.log.logConfig()` | 灰色 | 配置相关输出 |
|
||||
| 网络日志 | `oops.log.logNet()` | 橙色 | 网络请求跟踪 |
|
||||
| 数据日志 | `oops.log.logModel()` | 紫色 | 数据模型操作 |
|
||||
| 业务日志 | `oops.log.logBusiness()` | 蓝色 | 业务逻辑执行 |
|
||||
| 视图日志 | `oops.log.logView()` | 绿色 | UI界面交互 |
|
||||
|
||||
#### 性能监控功能
|
||||
|
||||
日志系统还提供了性能监控能力：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[开始计时] --> B[执行代码段]
|
||||
B --> C[结束计时]
|
||||
C --> D[计算执行时间]
|
||||
D --> E[输出性能日志]
|
||||
F[表格数据] --> G[格式化输出]
|
||||
G --> H[结构化日志]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [log.md](file://doc/core/common/log.md#L10-L25)
|
||||
|
||||
**章节来源**
|
||||
- [log.md](file://doc/core/common/log.md#L1-L30)
|
||||
|
||||
### 音效系统详细分析
|
||||
|
||||
#### 音效资源管理
|
||||
|
||||
音效系统采用异步加载策略，确保游戏性能：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 初始化
|
||||
初始化 --> 加载中 : 请求播放
|
||||
加载中 --> 播放就绪 : 资源加载完成
|
||||
加载中 --> 加载失败 : 资源加载失败
|
||||
播放就绪 --> 播放中 : 开始播放
|
||||
播放中 --> 暂停 : 用户暂停
|
||||
暂停 --> 播放中 : 用户继续
|
||||
播放中 --> 停止 : 用户停止
|
||||
停止 --> [*]
|
||||
加载失败 --> [*]
|
||||
```
|
||||
|
||||
#### 音量控制策略
|
||||
|
||||
音效系统提供了精细的音量控制：
|
||||
|
||||
| 功能 | 方法 | 参数范围 | 说明 |
|
||||
|------|------|----------|------|
|
||||
| 背景音乐音量 | `oops.audio.musicVolume` | 0.0 - 1.0 | 全局背景音乐音量 |
|
||||
| 音效音量 | `oops.audio.volumeEffect` | 0.0 - 1.0 | 全局音效音量 |
|
||||
| 音乐开关 | `oops.audio.switchMusic` | true/false | 控制背景音乐播放 |
|
||||
| 音效开关 | `oops.audio.switchEffect` | true/false | 控制音效播放 |
|
||||
|
||||
**章节来源**
|
||||
- [audio.md](file://doc/core/common/audio.md#L1-L85)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
辅助系统的依赖关系体现了良好的模块化设计：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "外部依赖"
|
||||
A[Oops Framework]
|
||||
B[Cocos Creator]
|
||||
end
|
||||
subgraph "核心模块"
|
||||
C[Guide.ts]
|
||||
D[GuideConComp.ts]
|
||||
E[GuideSetpComp.ts]
|
||||
F[SingletonModuleComp.ts]
|
||||
end
|
||||
subgraph "配置模块"
|
||||
G[GameUIConfig.ts]
|
||||
H[GameEvent.ts]
|
||||
end
|
||||
subgraph "工具模块"
|
||||
I[log.md]
|
||||
J[audio.md]
|
||||
end
|
||||
A --> C
|
||||
A --> D
|
||||
A --> E
|
||||
B --> D
|
||||
B --> E
|
||||
C --> D
|
||||
C --> E
|
||||
G --> D
|
||||
H --> D
|
||||
F --> D
|
||||
F --> E
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L10)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L15)
|
||||
|
||||
**章节来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L20)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L25)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
辅助系统在设计时充分考虑了性能优化：
|
||||
|
||||
### 引导系统性能优化
|
||||
|
||||
1. **延迟加载**：引导UI仅在需要时创建和销毁
|
||||
2. **内存管理**：及时清理不再使用的引导资源
|
||||
3. **事件监听**：智能添加和移除触摸监听器
|
||||
4. **节点查找**：缓存常用节点引用，避免重复查找
|
||||
|
||||
### 日志系统性能优化
|
||||
|
||||
1. **条件输出**：根据日志级别决定是否输出
|
||||
2. **批量处理**：支持批量日志输出以减少I/O操作
|
||||
3. **格式化优化**：使用高效的字符串拼接方法
|
||||
|
||||
### 音效系统性能优化
|
||||
|
||||
1. **预加载策略**：关键音效提前加载
|
||||
2. **资源池管理**：复用音频资源减少内存占用
|
||||
3. **异步加载**：避免阻塞主线程
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见引导问题
|
||||
|
||||
#### 引导无法启动
|
||||
**症状**：触发引导事件但没有显示任何提示
|
||||
**原因分析**：
|
||||
- 目标节点路径错误
|
||||
- 引导配置数据缺失
|
||||
- 引导进度状态异常
|
||||
|
||||
**解决方案**：
|
||||
1. 检查`targetPath`是否正确
|
||||
2. 验证`GuideConfig`配置
|
||||
3. 重置引导进度：`smc.guides = []`
|
||||
|
||||
#### 引导步骤不连续
|
||||
**症状**：引导过程中跳过了某些步骤
|
||||
**原因分析**：
|
||||
- `nextStep`配置错误
|
||||
- 引导完成状态未正确更新
|
||||
- 事件触发时机不当
|
||||
|
||||
**解决方案**：
|
||||
1. 检查引导步骤的`nextStep`链接
|
||||
2. 确认`smc.finishGuide()`调用
|
||||
3. 验证事件触发顺序
|
||||
|
||||
### 日志系统问题
|
||||
|
||||
#### 日志输出格式异常
|
||||
**症状**：日志时间戳或类别显示错误
|
||||
**解决方案**：
|
||||
检查日志配置和格式化函数
|
||||
|
||||
#### 性能监控失效
|
||||
**症状**：执行时间统计不准确
|
||||
**解决方案**：
|
||||
确认`oops.log.start()`和`oops.log.end()`配对使用
|
||||
|
||||
### 音效系统问题
|
||||
|
||||
#### 音效无法播放
|
||||
**症状**：音效请求后没有声音输出
|
||||
**解决方案**：
|
||||
1. 检查音效文件路径
|
||||
2. 验证音量设置
|
||||
3. 确认音频开关状态
|
||||
|
||||
#### 背景音乐重复播放
|
||||
**症状**：同一首音乐多次播放
|
||||
**解决方案**：
|
||||
1. 检查音乐播放完成回调
|
||||
2. 确认音乐切换逻辑
|
||||
3. 清理旧的音乐实例
|
||||
|
||||
**章节来源**
|
||||
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L180-L220)
|
||||
- [log.md](file://doc/core/common/log.md#L15-L30)
|
||||
- [audio.md](file://doc/core/common/audio.md#L40-L85)
|
||||
|
||||
## 结论
|
||||
|
||||
辅助系统作为游戏开发中的重要基础设施，提供了完整的新手引导、日志管理和音效控制功能。通过模块化的设计和事件驱动的架构，系统实现了高度的可扩展性和可维护性。
|
||||
|
||||
### 主要优势
|
||||
|
||||
1. **模块化设计**：各功能模块职责明确，便于维护和扩展
|
||||
2. **事件驱动**：通过事件系统实现松耦合的组件通信
|
||||
3. **配置灵活**：支持动态配置引导步骤和日志级别
|
||||
4. **性能优化**：采用多种优化策略确保系统流畅运行
|
||||
|
||||
### 最佳实践建议
|
||||
|
||||
1. **引导设计**：合理规划引导步骤，避免过度引导影响用户体验
|
||||
2. **日志管理**：根据环境设置合适的日志级别，生产环境避免过多调试信息
|
||||
3. **音效控制**：注意音效的音量平衡，避免影响游戏体验
|
||||
4. **资源管理**：及时释放不再使用的资源，防止内存泄漏
|
||||
|
||||
### 扩展方向
|
||||
|
||||
1. **多语言支持**：扩展引导文本的国际化功能
|
||||
2. **自定义事件**：支持开发者自定义引导触发事件
|
||||
3. **数据分析**：集成引导完成率等数据分析功能
|
||||
4. **云端配置**：支持引导配置的云端动态更新
|
||||
|
||||
通过持续的优化和功能扩展，辅助系统将继续为游戏开发提供强有力的支持，帮助开发者构建更好的用户体验。
|
||||
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