467 lines
13 KiB
Markdown
467 lines
13 KiB
Markdown
# 胜利界面
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts)
|
||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts)
|
||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts)
|
||
- [gui.md](file://doc/core/gui/gui.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概览](#架构概览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
|
||
VictoryComp.ts是游戏胜利界面的核心组件，负责展示战斗胜利后的奖励界面，包括经验值、金币和钻石奖励的展示。该组件采用基于ECS（Entity-Component-System）架构设计，实现了视图层与业务逻辑的分离，提供了完整的胜利后交互功能，包括继续游戏、重新开始、观看广告双倍奖励等操作。
|
||
|
||
## 项目结构
|
||
|
||
胜利界面组件位于游戏的地图模块中，与其他战斗相关组件协同工作：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "游戏模块结构"
|
||
A[地图模块] --> B[VictoryComp.ts]
|
||
A --> C[MissionComp.ts]
|
||
A --> D[MissionMonComp.ts]
|
||
A --> E[MissionHeroComp.ts]
|
||
end
|
||
subgraph "配置文件"
|
||
F[GameUIConfig.ts] --> G[UIID.Victory]
|
||
H[GameEvent.ts] --> I[MissionEnd]
|
||
H --> J[MissionStart]
|
||
end
|
||
subgraph "框架支持"
|
||
K[Oops Framework] --> L[ECS系统]
|
||
K --> M[GUI管理]
|
||
K --> N[消息系统]
|
||
end
|
||
B --> F
|
||
B --> H
|
||
B --> K
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L75)
|
||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L35)
|
||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L1-L70)
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L75)
|
||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L35)
|
||
|
||
## 核心组件
|
||
|
||
### 主要数据结构
|
||
|
||
胜利界面维护以下核心数据结构：
|
||
|
||
| 属性名称 | 类型 | 默认值 | 描述 |
|
||
|---------|------|--------|------|
|
||
| reward_lv | number | 1 | 奖励等级 |
|
||
| reward_num | number | 2 | 奖励数量 |
|
||
| rewards | any[] | [] | 奖励物品列表 |
|
||
| game_data | object | {exp:0,gold:0,diamond:0} | 游戏数据奖励 |
|
||
|
||
### 组件注册与生命周期
|
||
|
||
组件通过ECS系统注册，具有完整的生命周期管理：
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> 初始化
|
||
初始化 --> onAdded : 接收参数
|
||
onAdded --> 显示界面 : 设置游戏数据
|
||
显示界面 --> 等待交互 : 按钮延迟显示
|
||
等待交互 --> 继续游戏 : victory_end()
|
||
等待交互 --> 重新开始 : restart()
|
||
等待交互 --> 广告双倍 : watch_ad()
|
||
继续游戏 --> 清理资源 : clear_data()
|
||
重新开始 --> 清理资源 : clear_data()
|
||
广告双倍 --> 清理资源 : clear_data()
|
||
清理资源 --> 销毁界面 : removeByNode()
|
||
销毁界面 --> [*]
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L18-L75)
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L18-L75)
|
||
|
||
## 架构概览
|
||
|
||
胜利界面采用模块化架构设计，与游戏的ECS系统深度集成：
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class VictoryComp {
|
||
+number reward_lv
|
||
+number reward_num
|
||
+any[] rewards
|
||
+object game_data
|
||
+onAdded(args : any) void
|
||
+victory_end() void
|
||
+restart() void
|
||
+watch_ad() boolean
|
||
+double_reward() void
|
||
+clear_data() void
|
||
+reset() void
|
||
}
|
||
class CCComp {
|
||
<<abstract>>
|
||
+onLoad() void
|
||
+onDestroy() void
|
||
}
|
||
class ecs {
|
||
+register(name : string, persistent : boolean) decorator
|
||
}
|
||
class oops {
|
||
+message MessageManager
|
||
+gui GUIManager
|
||
}
|
||
class GameEvent {
|
||
+MissionEnd string
|
||
+MissionStart string
|
||
}
|
||
VictoryComp --|> CCComp
|
||
VictoryComp ..> ecs : 注册到ECS
|
||
VictoryComp ..> oops : 使用GUI和消息系统
|
||
VictoryComp ..> GameEvent : 触发游戏事件
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L10-L75)
|
||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L10-L70)
|
||
|
||
## 详细组件分析
|
||
|
||
### onAdded方法：界面初始化
|
||
|
||
onAdded方法是胜利界面的主要初始化入口，负责接收游戏数据并设置界面状态：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Mission as MissionComp
|
||
participant GUI as GUI系统
|
||
participant Victory as VictoryComp
|
||
participant SM as SingletonModuleComp
|
||
participant Game as 游戏事件系统
|
||
Mission->>GUI : open(UIID.Victory, args)
|
||
GUI->>Victory : 实例化组件
|
||
Victory->>Victory : onAdded(args)
|
||
Victory->>Victory : 检查并设置game_data
|
||
Victory->>Victory : 显示胜利标题
|
||
Victory->>Victory : 隐藏继续按钮
|
||
Victory->>Victory : scheduleOnce延迟显示按钮
|
||
Victory->>SM : 初始化界面状态
|
||
Victory-->>GUI : 初始化完成
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L28-L40)
|
||
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L65-L108)
|
||
|
||
#### 参数处理逻辑
|
||
|
||
onAdded方法接收包含游戏数据的参数对象，主要处理以下内容：
|
||
|
||
1. **游戏数据验证**：检查args.game_data是否存在并有效
|
||
2. **数据赋值**：将传入的游戏数据赋值给组件的game_data属性
|
||
3. **界面元素激活**：显示胜利标题文本
|
||
4. **按钮状态管理**：隐藏继续按钮，设置延迟显示
|
||
|
||
#### 定时器应用
|
||
|
||
组件使用scheduleOnce实现按钮的延迟显示，这是优化用户体验的重要设计：
|
||
|
||
- **延迟时间**：0.2秒
|
||
- **目的**：避免界面元素同时出现造成的视觉冲击
|
||
- **实现方式**：通过Cocos Creator的定时器系统
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L28-L40)
|
||
|
||
### 交互功能分析
|
||
|
||
#### 继续游戏功能（victory_end）
|
||
|
||
继续游戏功能负责结束当前关卡并返回主界面：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[victory_end调用] --> B[clear_data清理数据]
|
||
B --> C[dispatchEvent MissionEnd]
|
||
C --> D[removeByNode销毁界面]
|
||
D --> E[释放内存资源]
|
||
E --> F[返回主界面]
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L42-L46)
|
||
|
||
#### 重新开始功能（restart）
|
||
|
||
重新开始功能允许玩家重新挑战当前关卡：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[restart调用] --> B[clear_data清理数据]
|
||
B --> C[dispatchEvent MissionStart]
|
||
C --> D[removeByNode销毁界面]
|
||
D --> E[重新初始化关卡]
|
||
E --> F[开始新游戏]
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L54-L58)
|
||
|
||
#### 广告双倍奖励机制
|
||
|
||
虽然当前实现较为简单，但预留了完整的双倍奖励机制：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[watch_ad调用] --> B{return true}
|
||
B --> C[触发double_reward]
|
||
C --> D[处理奖励翻倍逻辑]
|
||
D --> E[更新游戏数据]
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L50-L52)
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L42-L60)
|
||
|
||
### 资源管理策略
|
||
|
||
#### clear_data方法
|
||
|
||
clear_data方法目前为空实现，但作为资源清理的占位符，为未来的扩展预留空间：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[clear_data调用] --> B[当前为空实现]
|
||
B --> C[预留扩展点]
|
||
C --> D[未来可添加资源清理逻辑]
|
||
```
|
||
|
||
#### reset方法与界面销毁
|
||
|
||
reset方法实现了组件的完整销毁流程：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant ECS as ECS系统
|
||
participant Victory as VictoryComp
|
||
participant Node as Cocos节点
|
||
participant Memory as 内存管理
|
||
ECS->>Victory : 调用reset()
|
||
Victory->>Node : node.destroy()
|
||
Node->>Memory : 释放节点内存
|
||
Memory-->>Victory : 内存释放完成
|
||
Victory-->>ECS : 销毁完成
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L70-L74)
|
||
|
||
#### oops.gui.removeByNode的应用
|
||
|
||
组件使用oops.gui.removeByNode进行界面销毁，这是框架推荐的标准做法：
|
||
|
||
- **优势**：确保资源正确释放
|
||
- **安全性**：只有通过GUI系统打开的节点才能被正确移除
|
||
- **一致性**：与整个框架的资源管理模式保持一致
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L42-L74)
|
||
|
||
### ECS系统集成
|
||
|
||
#### 组件注册机制
|
||
|
||
VictoryComp通过@ecs.register装饰器注册到ECS系统：
|
||
|
||
```typescript
|
||
@ecs.register('Victory', false)
|
||
export class VictoryComp extends CCComp
|
||
```
|
||
|
||
注册参数说明：
|
||
- **第一个参数**：组件名称'Victory'
|
||
- **第二个参数**：持久化标志false（表示非持久化组件）
|
||
|
||
#### 在游戏状态流转中的作用
|
||
|
||
胜利界面在游戏状态流转中扮演关键角色：
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> 战斗中
|
||
战斗中 --> 战斗胜利 : 敌人全部死亡
|
||
战斗胜利 --> 胜利界面 : open(UIID.Victory)
|
||
胜利界面 --> 继续游戏 : 用户选择
|
||
胜利界面 --> 重新开始 : 用户选择
|
||
继续游戏 --> 主界面 : MissionEnd事件
|
||
重新开始 --> 新关卡 : MissionStart事件
|
||
主界面 --> [*]
|
||
新关卡 --> [*]
|
||
```
|
||
|
||
**图表来源**
|
||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L30-L35)
|
||
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L65-L108)
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L13-L14)
|
||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L30-L35)
|
||
|
||
## 依赖关系分析
|
||
|
||
### 外部依赖
|
||
|
||
胜利界面组件依赖以下外部模块：
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[VictoryComp] --> B[Cocos Creator引擎]
|
||
A --> C[Oops Framework]
|
||
A --> D[ECS系统]
|
||
A --> E[SingletonModuleComp]
|
||
A --> F[GameEvent枚举]
|
||
B --> G[_decorator, instantiate, Label, Prefab, Node]
|
||
C --> H[GUI管理, 消息系统]
|
||
D --> I[组件注册, 生命周期管理]
|
||
E --> J[全局游戏状态]
|
||
F --> K[游戏事件定义]
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L10)
|
||
|
||
### 内部依赖
|
||
|
||
组件内部的相互依赖关系：
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[VictoryComp] --> B[游戏数据处理]
|
||
A --> C[界面交互逻辑]
|
||
A --> D[资源管理]
|
||
A --> E[ECS系统集成]
|
||
B --> F[game_data对象]
|
||
C --> G[按钮事件处理]
|
||
D --> H[clear_data & reset]
|
||
E --> I[组件注册 & 生命周期]
|
||
```
|
||
|
||
**图表来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L18-L75)
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L10)
|
||
|
||
## 性能考虑
|
||
|
||
### 内存管理
|
||
|
||
胜利界面采用了多层次的内存管理策略：
|
||
|
||
1. **组件级销毁**：通过reset方法确保组件完全销毁
|
||
2. **节点级清理**：使用destroy方法释放Cocos节点
|
||
3. **引用清理**：避免循环引用导致的内存泄漏
|
||
|
||
### 渲染优化
|
||
|
||
- **延迟显示**：使用scheduleOnce避免界面元素同时渲染
|
||
- **条件激活**：根据游戏状态动态控制界面元素的显示
|
||
- **资源预加载**：通过GUI系统管理界面资源的生命周期
|
||
|
||
### 事件处理优化
|
||
|
||
- **事件解耦**：通过消息系统实现松耦合的事件通信
|
||
- **批量处理**：在合适的时机批量处理界面更新
|
||
- **防重复**：确保相同事件不会被重复处理
|
||
|
||
## 故障排除指南
|
||
|
||
### 常见问题及解决方案
|
||
|
||
#### 界面无法正常显示
|
||
|
||
**可能原因**：
|
||
- 参数传递错误
|
||
- 游戏数据格式不正确
|
||
- GUI系统配置问题
|
||
|
||
**解决方案**：
|
||
1. 检查args.game_data的结构和内容
|
||
2. 验证UIID.Victory的配置
|
||
3. 确认ECS系统注册正常
|
||
|
||
#### 按钮点击无响应
|
||
|
||
**可能原因**：
|
||
- 事件绑定失败
|
||
- 组件生命周期问题
|
||
- GUI系统状态异常
|
||
|
||
**解决方案**：
|
||
1. 检查onAdded方法的执行情况
|
||
2. 验证组件的生命周期管理
|
||
3. 确认GUI系统的正常运行
|
||
|
||
#### 内存泄漏问题
|
||
|
||
**可能原因**：
|
||
- 资源未正确释放
|
||
- 循环引用存在
|
||
- 事件监听器未清理
|
||
|
||
**解决方案**：
|
||
1. 确保调用clear_data和reset方法
|
||
2. 检查组件间的引用关系
|
||
3. 验证事件监听器的正确清理
|
||
|
||
**章节来源**
|
||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L42-L74)
|
||
|
||
## 结论
|
||
|
||
VictoryComp.ts作为游戏胜利界面的核心组件，展现了现代游戏开发中优秀的架构设计原则：
|
||
|
||
### 设计亮点
|
||
|
||
1. **模块化架构**：通过ECS系统实现组件化开发
|
||
2. **生命周期管理**：完善的资源管理和销毁机制
|
||
3. **事件驱动**：基于消息系统的松耦合设计
|
||
4. **扩展性**：预留的接口和占位符便于功能扩展
|
||
|
||
### 技术特点
|
||
|
||
1. **类型安全**：充分利用TypeScript的类型系统
|
||
2. **性能优化**：合理的内存管理和渲染优化
|
||
3. **用户体验**：精心设计的界面交互流程
|
||
4. **框架集成**：与Oops Framework的深度集成
|
||
|
||
### 改进建议
|
||
|
||
1. **增强功能**：完善双倍奖励机制的具体实现
|
||
2. **错误处理**：添加更健壮的错误处理逻辑
|
||
3. **测试覆盖**：建立完整的单元测试和集成测试
|
||
4. **文档完善**：补充详细的API文档和使用示例
|
||
|
||
该组件为游戏胜利界面提供了坚实的技术基础，其设计理念和实现方式值得在类似项目中借鉴和应用。 |