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