refactor(game): 移除已弃用的事件常量
- 删除 UpdateHero 和 UpdateFightHero 事件 - 移除 MISSION_UPDATE 事件常量 - 优化游戏事件枚举定义
This commit is contained in:
panw
140
.qoder/repowiki/zh/content/用户界面系统/怪物信息显示.md
Normal file
140
.qoder/repowiki/zh/content/用户界面系统/怪物信息显示.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# 怪物信息显示
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.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)
|
||||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [怪物信息显示功能概述](#怪物信息显示功能概述)
|
||||
2. [事件监听与数据更新机制](#事件监听与数据更新机制)
|
||||
3. [关卡数据获取与格式化](#关卡数据获取与格式化)
|
||||
4. [生命周期与初始化逻辑](#生命周期与初始化逻辑)
|
||||
5. [UI更新与数据流分析](#ui更新与数据流分析)
|
||||
6. [组件交互与系统集成](#组件交互与系统集成)
|
||||
|
||||
## 怪物信息显示功能概述
|
||||
|
||||
怪物信息显示组件（MInfoComp）负责在游戏界面中动态展示当前关卡信息。该组件通过监听游戏事件系统中的关卡更新事件，实时响应游戏进度变化，并将当前关卡数据格式化为"第 X 关"的文本形式显示在UI界面上。此功能作为游戏状态可视化的重要组成部分，为玩家提供清晰的进度反馈。
|
||||
|
||||
**Section sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L1-L27)
|
||||
|
||||
## 事件监听与数据更新机制
|
||||
|
||||
MInfoComp组件通过oops消息系统订阅GameEvent.MISSION_UPDATE事件，建立事件驱动的更新机制。当游戏中的关卡状态发生变化时，系统会广播该事件，触发MInfoComp组件的onMissionUpdate回调函数。这种事件监听模式实现了组件间的松耦合，确保UI更新仅在相关数据发生变化时才执行，提高了系统性能和响应效率。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 系统 as 游戏系统
|
||||
participant MInfoComp as MInfoComp组件
|
||||
participant SMC as SingletonModuleComp
|
||||
系统->>SMC : 更新smc.data.mission
|
||||
SMC->>系统 : dispatchEvent(GameEvent.MISSION_UPDATE)
|
||||
系统->>MInfoComp : onMissionUpdate回调
|
||||
MInfoComp->>SMC : 获取smc.data.mission
|
||||
MInfoComp->>自身 : update_mission更新UI
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L9-L13)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L67)
|
||||
|
||||
**Section sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L9-L13)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L67)
|
||||
|
||||
## 关卡数据获取与格式化
|
||||
|
||||
组件通过全局单例smc.data.mission属性获取当前关卡数据。该数据存储在SingletonModuleComp的data对象中，初始值为1，表示游戏从第一关开始。在update_mission方法中，组件将数字类型的关卡号转换为字符串，并格式化为"第 X 关"的显示格式。这种格式化处理增强了用户界面的可读性和友好性，符合中文用户的阅读习惯。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[开始] --> B{获取关卡数据}
|
||||
B --> C[smc.data.mission]
|
||||
C --> D[转换为字符串]
|
||||
D --> E[格式化为"第 X 关"]
|
||||
E --> F[更新Label组件]
|
||||
F --> G[结束]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L20-L23)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L40)
|
||||
|
||||
**Section sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L20-L23)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L40)
|
||||
|
||||
## 生命周期与初始化逻辑
|
||||
|
||||
在onLoad生命周期方法中，组件注册事件监听器并立即执行一次初始更新，确保UI在加载时显示正确的关卡信息。start方法中再次调用update_mission，形成双重保障机制，防止因事件订阅时机问题导致的显示延迟。这种设计模式确保了组件在不同加载场景下都能正确初始化，提高了代码的健壮性和可靠性。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MInfoComp {
|
||||
+onLoad()
|
||||
+start()
|
||||
+onMissionUpdate(event, data)
|
||||
+update_mission(mission)
|
||||
}
|
||||
MInfoComp --> GameEvent : "监听"
|
||||
MInfoComp --> SingletonModuleComp : "读取数据"
|
||||
MInfoComp --> Label : "更新文本"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L8-L15)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L37-L40)
|
||||
|
||||
**Section sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L8-L15)
|
||||
|
||||
## UI更新与数据流分析
|
||||
|
||||
组件通过节点查找机制获取名为"mission"的子节点，并获取其Label组件实例，直接更新字符串属性。这种直接的UI操作方式简洁高效，避免了不必要的中间层。数据流从全局单例smc出发，经过事件系统触发，最终更新到UI组件，形成了清晰的数据传递路径。整个过程体现了MVC模式中视图与模型分离的设计思想。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[smc.data.mission] --> B[GameEvent.MISSION_UPDATE]
|
||||
B --> C[MInfoComp.onMissionUpdate]
|
||||
C --> D[MInfoComp.update_mission]
|
||||
D --> E[Label.string更新]
|
||||
E --> F[UI显示变化]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L20-L23)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L37-L40)
|
||||
|
||||
**Section sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L20-L23)
|
||||
|
||||
## 组件交互与系统集成
|
||||
|
||||
MInfoComp与其他游戏组件通过事件系统协同工作。当玩家完成关卡时，VictoryComp组件会触发GameEvent.MissionEnd事件，随后新的关卡开始流程会更新smc.data.mission并广播GameEvent.MISSION_UPDATE事件。这种基于事件的通信机制使得各个功能模块能够独立开发和测试，同时保持良好的系统集成性，体现了高内聚低耦合的设计原则。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant VictoryComp as VictoryComp
|
||||
participant MissionComp as MissionComp
|
||||
participant MInfoComp as MInfoComp
|
||||
VictoryComp->>MissionComp : 触发新关卡
|
||||
MissionComp->>SMC : 更新关卡数据
|
||||
SMC->>系统 : 广播MISSION_UPDATE
|
||||
系统->>MInfoComp : 更新显示
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L9)
|
||||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L60)
|
||||
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L85)
|
||||
|
||||
**Section sources**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L9)
|
||||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L60)
|
||||
- [MissionComp.ts](file://assets/script/game/map/MissionComp.ts#L85)
|
||||
414
.qoder/repowiki/zh/content/用户界面系统/技能图标组件.md
Normal file
414
.qoder/repowiki/zh/content/用户界面系统/技能图标组件.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# 技能图标组件详细实现文档
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts)
|
||||
- [SkillSet.ts](file://assets/script/game/common/config/SkillSet.ts)
|
||||
- [CCComp.ts](file://extensions/oops-plugin-framework/assets/module/common/CCComp.ts)
|
||||
- [loader.md](file://doc/core/common/loader.md)
|
||||
- [ecs.md](file://doc/ecs/ecs.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [组件架构概览](#组件架构概览)
|
||||
3. [核心功能实现](#核心功能实现)
|
||||
4. [资源管理系统集成](#资源管理系统集成)
|
||||
5. [ECS系统组件生命周期](#ecs系统组件生命周期)
|
||||
6. [使用示例与最佳实践](#使用示例与最佳实践)
|
||||
7. [性能优化考虑](#性能优化考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [总结](#总结)
|
||||
|
||||
## 简介
|
||||
|
||||
SIconCompComp是一个专门用于显示技能图标的通用UI组件，它通过Cocos Creator的游戏引擎与Oops框架的结合，实现了技能图标资源的动态加载和显示功能。该组件采用ECMAScript组件模式设计，具有良好的可复用性和扩展性。
|
||||
|
||||
该组件的核心价值在于：
|
||||
- 提供统一的技能图标显示接口
|
||||
- 实现资源的按需加载和智能管理
|
||||
- 支持多种UI上下文环境的适配
|
||||
- 集成完整的ECS系统组件生命周期管理
|
||||
|
||||
## 组件架构概览
|
||||
|
||||
SIconCompComp组件采用了分层架构设计，将业务逻辑、资源管理和UI渲染进行了清晰的分离：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CCComp {
|
||||
<<abstract>>
|
||||
+canRecycle : boolean
|
||||
+ent : ecs.Entity
|
||||
+reset() : void
|
||||
}
|
||||
class SIconCompComp {
|
||||
+start() : void
|
||||
+update_data(s_uuid : number) : void
|
||||
+reset() : void
|
||||
}
|
||||
class SkillSet {
|
||||
+Record~number, SkillConfig~
|
||||
+SkillConfig : interface
|
||||
}
|
||||
class Sprite {
|
||||
+spriteFrame : SpriteFrame
|
||||
}
|
||||
class oopsRes {
|
||||
+get(path : string, type : Constructor) : Asset
|
||||
}
|
||||
CCComp <|-- SIconCompComp : 继承
|
||||
SIconCompComp --> SkillSet : 读取配置
|
||||
SIconCompComp --> Sprite : 更新纹理
|
||||
SIconCompComp --> oopsRes : 资源加载
|
||||
SkillSet --> Sprite : 提供路径
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L1-L28)
|
||||
- [CCComp.ts](file://extensions/oops-plugin-framework/assets/module/common/CCComp.ts#L36-L45)
|
||||
|
||||
**章节来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L1-L28)
|
||||
- [CCComp.ts](file://extensions/oops-plugin-framework/assets/module/common/CCComp.ts#L1-L46)
|
||||
|
||||
## 核心功能实现
|
||||
|
||||
### update_data方法详解
|
||||
|
||||
`update_data`方法是组件的核心功能入口，负责接收技能UUID并加载对应的图标资源：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端代码
|
||||
participant SIconComp as SIconCompComp
|
||||
participant SkillSet as SkillSet配置
|
||||
participant oopsRes as 资源管理系统
|
||||
participant Sprite as Sprite组件
|
||||
Client->>SIconComp : update_data(skillUUID)
|
||||
SIconComp->>SkillSet : 查找技能配置
|
||||
SkillSet-->>SIconComp : 返回SkillConfig
|
||||
SIconComp->>SIconComp : 构建资源路径
|
||||
SIconComp->>oopsRes : oops.res.get(path, SpriteFrame)
|
||||
oopsRes-->>SIconComp : 返回SpriteFrame
|
||||
SIconComp->>Sprite : 设置spriteFrame
|
||||
Sprite-->>Client : 图标显示更新
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L18-L20)
|
||||
|
||||
该方法的工作流程包括：
|
||||
1. **技能配置查询**：通过传入的技能UUID从SkillSet配置表中获取对应的技能信息
|
||||
2. **路径构建**：根据技能配置中的`path`字段构建资源加载路径
|
||||
3. **资源加载**：调用oops.res.get方法异步加载SpriteFrame资源
|
||||
4. **纹理更新**：将加载的SpriteFrame赋值给Sprite组件的spriteFrame属性
|
||||
|
||||
### reset方法的节点销毁逻辑
|
||||
|
||||
reset方法实现了组件的清理和销毁功能：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([组件销毁开始]) --> CheckNode{"节点是否有效?"}
|
||||
CheckNode --> |是| DestroyNode["调用node.destroy()"]
|
||||
CheckNode --> |否| Skip["跳过销毁"]
|
||||
DestroyNode --> ReleaseMemory["释放内存资源"]
|
||||
ReleaseMemory --> CleanupComplete["清理完成"]
|
||||
Skip --> CleanupComplete
|
||||
CleanupComplete --> End([销毁结束])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L22-L24)
|
||||
|
||||
reset方法的设计考虑了以下因素：
|
||||
- **内存管理**：确保节点被正确销毁，避免内存泄漏
|
||||
- **ECS系统集成**：与ECS系统的组件回收机制保持一致
|
||||
- **生命周期管理**：在组件被移除时执行必要的清理工作
|
||||
|
||||
**章节来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L18-L24)
|
||||
|
||||
## 资源管理系统集成
|
||||
|
||||
### SkillSet配置系统
|
||||
|
||||
SkillSet配置系统提供了技能的基础信息和资源路径映射：
|
||||
|
||||
| 配置项 | 类型 | 描述 | 示例值 |
|
||||
|--------|------|------|--------|
|
||||
| uuid | number | 技能唯一标识符 | 6001 |
|
||||
| name | string | 技能显示名称 | "挥击" |
|
||||
| path | string | 图标资源路径 | "3036" |
|
||||
| sp_name | string | 特效名称 | "atk_s1" |
|
||||
| TGroup | TGroup | 目标群体类型 | TGroup.Enemy |
|
||||
|
||||
### oops.res.get资源加载机制
|
||||
|
||||
oops.res.get方法提供了统一的资源加载接口：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Request[资源请求] --> Cache{缓存检查}
|
||||
Cache --> |命中| ReturnCached[返回缓存资源]
|
||||
Cache --> |未命中| LoadResource[加载资源]
|
||||
LoadResource --> ParsePath[解析资源路径]
|
||||
ParsePath --> LoadFromDisk[从磁盘加载]
|
||||
LoadFromDisk --> CreateAsset[创建资源对象]
|
||||
CreateAsset --> StoreCache[存储到缓存]
|
||||
StoreCache --> ReturnAsset[返回资源]
|
||||
ReturnCached --> End[完成]
|
||||
ReturnAsset --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [loader.md](file://doc/core/common/loader.md#L1-L66)
|
||||
|
||||
资源加载过程的关键特性：
|
||||
- **异步加载**：支持异步资源加载，避免阻塞主线程
|
||||
- **缓存机制**：自动缓存已加载的资源，提高重复访问效率
|
||||
- **类型安全**：通过泛型参数确保资源类型的一致性
|
||||
- **错误处理**：提供完善的错误处理和回退机制
|
||||
|
||||
**章节来源**
|
||||
- [SkillSet.ts](file://assets/script/game/common/config/SkillSet.ts#L1-L148)
|
||||
- [loader.md](file://doc/core/common/loader.md#L1-L66)
|
||||
|
||||
## ECS系统组件生命周期
|
||||
|
||||
### 组件注册与管理
|
||||
|
||||
SIconCompComp通过ecs.register装饰器注册到ECS系统中：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 创建实例
|
||||
创建实例 --> 注册组件 : @ecs.register('SIconComp', false)
|
||||
注册组件 --> 初始化 : start()
|
||||
初始化 --> 运行中 : update_data()
|
||||
运行中 --> 更新数据 : update_data()
|
||||
更新数据 --> 运行中 : 继续处理
|
||||
运行中 --> 销毁 : reset()
|
||||
销毁 --> 回收组件 : 组件池管理
|
||||
回收组件 --> [*]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L9-L10)
|
||||
|
||||
### 生命周期方法详解
|
||||
|
||||
组件的生命周期管理遵循ECS系统的设计原则：
|
||||
|
||||
| 方法 | 调用时机 | 主要功能 | 注意事项 |
|
||||
|------|----------|----------|----------|
|
||||
| start() | 组件激活时 | 初始化基础逻辑 | 可选重写 |
|
||||
| update_data() | 外部调用 | 更新技能图标 | 必须实现 |
|
||||
| reset() | 组件销毁时 | 清理资源 | 必须实现 |
|
||||
|
||||
### 与ECS系统的集成优势
|
||||
|
||||
1. **组件复用**：支持多个实体共享同一组件实例
|
||||
2. **性能优化**：通过组件池减少对象创建开销
|
||||
3. **解耦设计**：业务逻辑与渲染逻辑完全分离
|
||||
4. **生命周期管理**：自动化的资源管理和清理
|
||||
|
||||
**章节来源**
|
||||
- [ecs.md](file://doc/ecs/ecs.md#L1-L87)
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L9-L10)
|
||||
|
||||
## 使用示例与最佳实践
|
||||
|
||||
### 基础使用示例
|
||||
|
||||
以下展示了SIconCompComp在不同UI上下文中的典型使用方式：
|
||||
|
||||
#### 技能面板中的应用
|
||||
|
||||
```typescript
|
||||
// 在技能面板中显示技能图标
|
||||
const iconNode = instantiate(iconPrefab);
|
||||
const iconComp = iconNode.getComponent(SIconCompComp);
|
||||
iconComp.update_data(6001); // 显示挥击技能图标
|
||||
panelNode.addChild(iconNode);
|
||||
```
|
||||
|
||||
#### 技能快捷栏中的应用
|
||||
|
||||
```typescript
|
||||
// 在技能快捷栏中动态更新图标
|
||||
skillBar.updateIcon = function(skillUUID: number) {
|
||||
const iconNode = this.iconNode;
|
||||
const iconComp = iconNode.getComponent(SIconCompComp);
|
||||
iconComp.update_data(skillUUID);
|
||||
};
|
||||
```
|
||||
|
||||
### 复用示例集合
|
||||
|
||||
#### 1. 技能详情窗口
|
||||
|
||||
```typescript
|
||||
class SkillDetailPanel {
|
||||
private iconComp: SIconCompComp;
|
||||
|
||||
showSkillDetails(skillUUID: number) {
|
||||
// 更新技能图标
|
||||
this.iconComp.update_data(skillUUID);
|
||||
|
||||
// 更新其他UI元素
|
||||
const skillConfig = SkillSet[skillUUID];
|
||||
this.nameLabel.string = skillConfig.name;
|
||||
this.descriptionLabel.string = skillConfig.info;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 英雄技能槽位
|
||||
|
||||
```typescript
|
||||
class HeroSkillSlot {
|
||||
private iconNode: Node;
|
||||
private slotIndex: number;
|
||||
|
||||
equipSkill(skillUUID: number) {
|
||||
if (!this.iconNode) {
|
||||
this.createIconNode();
|
||||
}
|
||||
|
||||
const iconComp = this.iconNode.getComponent(SIconCompComp);
|
||||
iconComp.update_data(skillUUID);
|
||||
}
|
||||
|
||||
unequipSkill() {
|
||||
if (this.iconNode) {
|
||||
this.iconNode.destroy();
|
||||
this.iconNode = null;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 战斗技能指示器
|
||||
|
||||
```typescript
|
||||
class CombatSkillIndicator {
|
||||
private indicators: SIconCompComp[];
|
||||
|
||||
updateSkillIndicators(skillUUIDs: number[]) {
|
||||
skillUUIDs.forEach((skillUUID, index) => {
|
||||
const indicator = this.indicators[index];
|
||||
indicator.update_data(skillUUID);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 最佳实践建议
|
||||
|
||||
1. **资源预加载**：对于频繁使用的技能图标，建议在游戏启动时进行预加载
|
||||
2. **错误处理**：在update_data方法中添加异常处理，防止资源加载失败导致程序崩溃
|
||||
3. **内存监控**：定期检查组件的内存使用情况，及时清理不需要的图标
|
||||
4. **缓存策略**：合理设置资源缓存策略，平衡内存使用和加载性能
|
||||
|
||||
## 性能优化考虑
|
||||
|
||||
### 资源加载优化
|
||||
|
||||
1. **延迟加载**：只在需要时才加载技能图标资源
|
||||
2. **批量加载**：对于一组相关的技能图标，可以考虑批量加载
|
||||
3. **压缩优化**：使用适当的图片压缩格式减少资源体积
|
||||
4. **CDN加速**：对于大型游戏，可以考虑使用CDN加速资源加载
|
||||
|
||||
### 内存管理优化
|
||||
|
||||
1. **组件池化**：利用ECS系统的组件池机制减少对象创建开销
|
||||
2. **及时清理**：在reset方法中确保所有资源都被正确释放
|
||||
3. **弱引用**：对于长期持有的资源引用，考虑使用弱引用避免内存泄漏
|
||||
|
||||
### 渲染性能优化
|
||||
|
||||
1. **纹理合并**：将多个小图标合并到一个大纹理中
|
||||
2. **批处理**：利用Cocos Creator的自动批处理功能
|
||||
3. **LOD系统**：对于远距离显示的图标，使用较低分辨率的版本
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 1. 技能图标无法显示
|
||||
|
||||
**可能原因**：
|
||||
- 技能UUID不存在于SkillSet配置中
|
||||
- 资源路径配置错误
|
||||
- 资源加载失败
|
||||
|
||||
**解决步骤**：
|
||||
```typescript
|
||||
// 添加调试信息
|
||||
update_data(s_uuid: number) {
|
||||
console.log(`尝试加载技能 ${s_uuid} 的图标`);
|
||||
let skill_data = SkillSet[s_uuid];
|
||||
|
||||
if (!skill_data) {
|
||||
console.error(`技能 ${s_uuid} 配置不存在`);
|
||||
return;
|
||||
}
|
||||
|
||||
console.log(`技能 ${s_uuid} 路径: game/heros/cards/${skill_data.path}`);
|
||||
// 继续原有逻辑...
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 内存泄漏问题
|
||||
|
||||
**诊断方法**：
|
||||
- 监控组件的reset方法调用频率
|
||||
- 检查节点是否被正确销毁
|
||||
- 使用内存分析工具检查资源占用
|
||||
|
||||
**预防措施**：
|
||||
```typescript
|
||||
reset() {
|
||||
// 确保节点被正确销毁
|
||||
if (this.node && this.node.isValid) {
|
||||
this.node.destroy();
|
||||
}
|
||||
|
||||
// 清理其他可能的引用
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 资源加载超时
|
||||
|
||||
**解决方案**：
|
||||
- 添加加载超时机制
|
||||
- 提供默认图标作为后备
|
||||
- 实现重试逻辑
|
||||
|
||||
**章节来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L18-L24)
|
||||
|
||||
## 总结
|
||||
|
||||
SIconCompComp技能图标组件是一个设计精良的通用UI组件，它成功地将资源管理、UI渲染和ECS系统生命周期管理进行了有机结合。通过本文档的详细分析，我们可以看到：
|
||||
|
||||
### 核心优势
|
||||
|
||||
1. **架构清晰**：采用分层架构设计，职责分明
|
||||
2. **易于复用**：支持多种UI上下文的适配
|
||||
3. **性能优秀**：集成资源管理系统，支持按需加载
|
||||
4. **生命周期完善**：与ECS系统深度集成，自动化资源管理
|
||||
|
||||
### 设计亮点
|
||||
|
||||
- **update_data方法**：简洁高效的技能图标更新接口
|
||||
- **reset方法**：完善的资源清理和节点销毁逻辑
|
||||
- **SkillSet集成**：标准化的技能配置管理
|
||||
- **oops.res.get**：统一的资源加载机制
|
||||
|
||||
### 应用价值
|
||||
|
||||
该组件不仅解决了技能图标显示的技术难题，更为游戏开发提供了一个可复用的UI组件模板，展示了现代游戏开发中组件化、模块化的设计思想。通过合理的抽象和封装，它大大提高了开发效率，降低了维护成本，是游戏UI组件设计的优秀范例。
|
||||
607
.qoder/repowiki/zh/content/用户界面系统/用户界面系统.md
Normal file
607
.qoder/repowiki/zh/content/用户界面系统/用户界面系统.md
Normal file
@@ -0,0 +1,607 @@
|
||||
# 用户界面系统
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts)
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts)
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts)
|
||||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts)
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||||
- [MvvmInfo.md](file://doc/mvvm/MvvmInfo.md)
|
||||
- [VMBase.md](file://doc/mvvm/VMBase.md)
|
||||
- [gui.md](file://doc/core/gui/gui.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [UI层级架构](#ui层级架构)
|
||||
4. [核心组件分析](#核心组件分析)
|
||||
5. [MVVM框架集成](#mvvm框架集成)
|
||||
6. [事件系统与数据绑定](#事件系统与数据绑定)
|
||||
7. [使用示例](#使用示例)
|
||||
8. [性能优化考虑](#性能优化考虑)
|
||||
9. [故障排除指南](#故障排除指南)
|
||||
10. [总结](#总结)
|
||||
|
||||
## 简介
|
||||
|
||||
本游戏采用基于Oops Framework的现代化UI系统架构，集成了MVVM设计模式和事件驱动的组件化开发方式。系统通过GameUIConfig.ts统一管理界面配置，支持多种UI层级和预制体路径配置，并通过MVVM框架实现数据与视图的自动绑定。
|
||||
|
||||
## 项目结构
|
||||
|
||||
UI系统的核心文件组织结构如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "UI配置层"
|
||||
A[GameUIConfig.ts] --> B[UIID枚举]
|
||||
A --> C[UIConfigData配置]
|
||||
end
|
||||
subgraph "组件层"
|
||||
D[HInfoComp.ts] --> E[英雄信息面板]
|
||||
F[MInfoComp.ts] --> G[怪物信息组件]
|
||||
H[TopComp.ts] --> I[顶部状态栏]
|
||||
J[VictoryComp.ts] --> K[胜利界面]
|
||||
L[SIconComp.ts] --> M[技能图标组件]
|
||||
end
|
||||
subgraph "框架层"
|
||||
N[MVVM框架] --> O[ViewModel]
|
||||
N --> P[VMBase组件]
|
||||
Q[事件系统] --> R[GameEvent]
|
||||
end
|
||||
A --> D
|
||||
A --> F
|
||||
A --> H
|
||||
A --> J
|
||||
A --> L
|
||||
N --> D
|
||||
N --> F
|
||||
N --> H
|
||||
N --> J
|
||||
N --> L
|
||||
Q --> D
|
||||
Q --> F
|
||||
Q --> H
|
||||
Q --> J
|
||||
Q --> L
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L36)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L344)
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L1-L28)
|
||||
|
||||
**章节来源**
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L36)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L344)
|
||||
|
||||
## UI层级架构
|
||||
|
||||
### 层级类型定义
|
||||
|
||||
系统采用分层的UI管理架构，通过LayerType枚举定义不同的界面层级：
|
||||
|
||||
| 层级类型 | 描述 | 使用场景 |
|
||||
|---------|------|----------|
|
||||
| UI层 | 主界面层级，常驻显示 | 英雄信息面板、顶部状态栏 |
|
||||
| PopUp层 | 弹出式界面 | 网络不稳定提示、Toast消息 |
|
||||
| Dialog层 | 模态对话框 | 弹窗界面、确认对话框 |
|
||||
|
||||
### 配置数据结构
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class UIConfig {
|
||||
+LayerType layer
|
||||
+string prefab
|
||||
+string bundle
|
||||
}
|
||||
class UIID {
|
||||
<<enumeration>>
|
||||
Loading
|
||||
Netinstable
|
||||
Role_Controller
|
||||
Victory
|
||||
Guide
|
||||
}
|
||||
class GameUIConfig {
|
||||
+UIConfigData : {[key : number] : UIConfig}
|
||||
+registerUI(id : number, config : UIConfig) : void
|
||||
+getUIConfig(id : number) : UIConfig
|
||||
}
|
||||
UIID --> GameUIConfig : "配置"
|
||||
UIConfig --> GameUIConfig : "管理"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L10-L35)
|
||||
|
||||
**章节来源**
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L36)
|
||||
|
||||
## 核心组件分析
|
||||
|
||||
### HInfoComp - 英雄信息面板
|
||||
|
||||
英雄信息面板是最复杂的UI组件，负责展示和管理英雄选择、属性显示和交互功能。
|
||||
|
||||
#### 组件架构
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class HInfoComp {
|
||||
+number h_uuid
|
||||
+Node[] heroNodes
|
||||
+Vec3 hero_pos
|
||||
+boolean isMoving
|
||||
+any moveTimeoutId
|
||||
+update_data(uuid : number) : void
|
||||
+load_all_hero(uuid : number) : void
|
||||
+load_hui(uuid : number, pos_index : number) : Node
|
||||
+next_hero() : void
|
||||
+prev_hero() : void
|
||||
+buy_hero() : void
|
||||
+start_mission() : void
|
||||
+moveHeroesLeft() : void
|
||||
+moveHeroesRight() : void
|
||||
+show_lock() : void
|
||||
+claear_hero() : void
|
||||
}
|
||||
class CCComp {
|
||||
+onLoad() : void
|
||||
+start() : void
|
||||
+update(deltaTime : number) : void
|
||||
+reset() : void
|
||||
}
|
||||
HInfoComp --|> CCComp : "继承"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L10-L344)
|
||||
|
||||
#### 英雄选择动画系统
|
||||
|
||||
组件实现了复杂的英雄选择动画系统，包括：
|
||||
|
||||
- **循环滚动算法**：支持无限循环的英雄选择
|
||||
- **平滑动画过渡**：使用Tween实现流畅的移动效果
|
||||
- **视觉焦点效果**：3号位置英雄显示1.5倍放大效果
|
||||
- **动画锁定机制**：防止快速点击导致的动画冲突
|
||||
|
||||
#### 数据绑定与更新
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant HInfo as HInfoComp
|
||||
participant SM as SingletonModule
|
||||
participant VM as ViewModel
|
||||
User->>HInfo : 点击英雄选择
|
||||
HInfo->>HInfo : 验证动画状态
|
||||
HInfo->>HInfo : 计算下一个英雄
|
||||
HInfo->>SM : updateFihgtHero(uuid)
|
||||
SM->>VM : 更新战斗英雄
|
||||
VM->>HInfo : 通知数据变更
|
||||
HInfo->>HInfo : update_data(uuid)
|
||||
HInfo->>HInfo : 执行动画过渡
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L200-L344)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L120-L140)
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L344)
|
||||
|
||||
### MInfoComp - 怪物信息组件
|
||||
|
||||
怪物信息组件负责显示当前关卡信息，采用简洁的设计模式。
|
||||
|
||||
#### 组件特性
|
||||
|
||||
- **事件驱动更新**：监听MISSION_UPDATE事件自动更新关卡信息
|
||||
- **文本绑定**：直接绑定到Label组件的字符串属性
|
||||
- **生命周期管理**：在onLoad中注册事件监听器，在start中初始化数据
|
||||
|
||||
**章节来源**
|
||||
- [MInfoComp.ts](file://assets/script/game/map/MInfoComp.ts#L1-L28)
|
||||
|
||||
### TopComp - 顶部状态栏
|
||||
|
||||
顶部状态栏组件专注于显示玩家资源信息，特别是金币数量的动画效果。
|
||||
|
||||
#### 特色功能
|
||||
|
||||
- **资源动画效果**：金币数量变化时触发缩放动画
|
||||
- **事件响应**：监听GOLD_UPDATE事件执行动画
|
||||
- **轻量级设计**：专注于单一功能，避免过度复杂化
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L1-L30)
|
||||
|
||||
### VictoryComp - 胜利界面
|
||||
|
||||
胜利界面组件处理战斗结算和奖励展示，包含复杂的奖励系统和动画效果。
|
||||
|
||||
#### 界面流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[战斗胜利] --> B[显示胜利界面]
|
||||
B --> C[展示奖励信息]
|
||||
C --> D{玩家选择}
|
||||
D --> |继续| E[下一关卡]
|
||||
D --> |重新开始| F[重置关卡]
|
||||
D --> |双倍奖励| G[观看广告]
|
||||
E --> H[清理数据]
|
||||
F --> H
|
||||
G --> I[验证广告]
|
||||
I --> J{验证结果}
|
||||
J --> |成功| K[获得双倍奖励]
|
||||
J --> |失败| L[显示错误]
|
||||
K --> H
|
||||
H --> M[返回主界面]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L30-L75)
|
||||
|
||||
**章节来源**
|
||||
- [VictoryComp.ts](file://assets/script/game/map/VictoryComp.ts#L1-L75)
|
||||
|
||||
### SIconComp - 技能图标组件
|
||||
|
||||
技能图标组件负责显示技能的视觉图标，采用简单的数据绑定模式。
|
||||
|
||||
#### 组件特点
|
||||
|
||||
- **资源动态加载**：根据技能UUID动态加载对应的图标资源
|
||||
- **路径配置**：通过SkillSet配置技能的资源路径
|
||||
- **轻量级实现**：专注于单一职责，易于维护和扩展
|
||||
|
||||
**章节来源**
|
||||
- [SIconComp.ts](file://assets/script/game/map/SIconComp.ts#L1-L28)
|
||||
|
||||
## MVVM框架集成
|
||||
|
||||
### 架构概览
|
||||
|
||||
系统采用MVVM（Model-View-ViewModel）架构模式，通过Oops Framework的ViewModel模块实现数据与视图的自动绑定。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Model层"
|
||||
A[数据模型] --> B[SingletonModuleComp]
|
||||
B --> C[vmdata对象]
|
||||
end
|
||||
subgraph "ViewModel层"
|
||||
D[ViewModel] --> E[VMManager]
|
||||
E --> F[数据监听]
|
||||
end
|
||||
subgraph "View层"
|
||||
G[UI组件] --> H[VMBase组件]
|
||||
H --> I[数据绑定]
|
||||
end
|
||||
C --> D
|
||||
F --> H
|
||||
I --> G
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L50-L70)
|
||||
- [MvvmInfo.md](file://doc/mvvm/MvvmInfo.md#L10-L15)
|
||||
|
||||
### 数据模型管理
|
||||
|
||||
系统通过SingletonModuleComp统一管理游戏数据，特别是VM数据模型：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SingletonModuleComp {
|
||||
+vmdata : any
|
||||
+vmAdd() : void
|
||||
+updateGold(gold : number) : void
|
||||
+updateFihgtHero(heroId : number) : void
|
||||
+addHero(hero_uuid : number) : void
|
||||
}
|
||||
class ViewModel {
|
||||
+add(data : any, tag : string) : void
|
||||
+get(tag : string) : ViewModel
|
||||
+setValue(path : string, value : any) : void
|
||||
+getValue(path : string) : any
|
||||
}
|
||||
SingletonModuleComp --> ViewModel : "管理"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L50-L70)
|
||||
|
||||
### VMBase组件基类
|
||||
|
||||
所有UI组件都继承自VMBase组件，实现自动的数据绑定功能：
|
||||
|
||||
| 属性 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| watchPath | string | 需要监听的数据路径 |
|
||||
| watchPathArr | string[] | 多路径监听数组 |
|
||||
| templateMode | boolean | 启用模板模式 |
|
||||
| VM | VMManager | ViewModel管理器引用 |
|
||||
|
||||
**章节来源**
|
||||
- [VMBase.md](file://doc/mvvm/VMBase.md#L1-L39)
|
||||
|
||||
## 事件系统与数据绑定
|
||||
|
||||
### 事件类型定义
|
||||
|
||||
系统通过GameEvent枚举定义了完整的游戏事件体系：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "战斗事件"
|
||||
A[FightStart] --> B[FightEnd]
|
||||
C[FightPause] --> D[FightResume]
|
||||
end
|
||||
subgraph "关卡事件"
|
||||
E[MissionStart] --> F[MissionEnd]
|
||||
G[MissionWin] --> H[MissionLoss]
|
||||
end
|
||||
subgraph "资源事件"
|
||||
I[GOLD_UPDATE] --> J[DIAMOND_UPDATE]
|
||||
K[MEAT_UPDATE] --> L[MISSION_UPDATE]
|
||||
end
|
||||
subgraph "选择事件"
|
||||
M[HeroSelect] --> N[EnhancementSelect]
|
||||
O[TalentSelect] --> P[FuncSelect]
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L10-L70)
|
||||
|
||||
### 数据绑定流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Model as 数据模型
|
||||
participant VM as ViewModel
|
||||
participant View as UI组件
|
||||
participant Event as 事件系统
|
||||
Model->>VM : 数据变更
|
||||
VM->>VM : 触发监听器
|
||||
VM->>Event : 发送事件通知
|
||||
Event->>View : 分发事件
|
||||
View->>View : 更新UI显示
|
||||
View->>Model : 响应用户交互
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L150-L195)
|
||||
|
||||
**章节来源**
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L1-L70)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L150-L195)
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 注册新UI界面
|
||||
|
||||
以下是如何注册和使用新UI界面的完整示例：
|
||||
|
||||
```typescript
|
||||
// 1. 在GameUIConfig.ts中添加UI配置
|
||||
export enum UIID {
|
||||
// ... 现有UI ID
|
||||
CustomPanel = 2001,
|
||||
}
|
||||
|
||||
export var UIConfigData: { [key: number]: UIConfig } = {
|
||||
// ... 现有UI配置
|
||||
[UIID.CustomPanel]: {
|
||||
layer: LayerType.UI,
|
||||
prefab: "custom/prefab/panel"
|
||||
},
|
||||
};
|
||||
|
||||
// 2. 创建UI组件
|
||||
@ccclass('CustomPanelComp')
|
||||
export class CustomPanelComp extends CCComp {
|
||||
protected onLoad(): void {
|
||||
// 注册事件监听
|
||||
oops.message.on(GameEvent.CustomEvent, this.onCustomEvent, this);
|
||||
}
|
||||
|
||||
onCustomEvent(event: string, data: any): void {
|
||||
// 处理自定义事件
|
||||
this.updateDisplay(data);
|
||||
}
|
||||
|
||||
updateDisplay(data: any): void {
|
||||
// 更新UI显示
|
||||
const label = this.node.getChildByName("content")
|
||||
.getComponent(Label);
|
||||
label.string = data.message;
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 打开UI界面
|
||||
const callbacks: UICallbacks = {
|
||||
onAdded: (node: Node, params: any) => {
|
||||
const comp = node.getComponent(CustomPanelComp);
|
||||
// 初始化界面
|
||||
},
|
||||
onRemoved: (node: Node | null, params: any) => {
|
||||
// 清理资源
|
||||
}
|
||||
};
|
||||
|
||||
oops.gui.open(UIID.CustomPanel, null, callbacks);
|
||||
```
|
||||
|
||||
### 处理按钮点击事件
|
||||
|
||||
```typescript
|
||||
// 在UI组件中处理按钮点击
|
||||
@ccclass('ButtonHandler')
|
||||
export class ButtonHandler extends Component {
|
||||
start(): void {
|
||||
// 获取按钮节点
|
||||
const button = this.node.getChildByName("action_button");
|
||||
if (button) {
|
||||
// 添加点击事件监听
|
||||
button.on(Node.EventType.TOUCH_END, this.onButtonClick, this);
|
||||
}
|
||||
}
|
||||
|
||||
onButtonClick(event: EventTouch): void {
|
||||
// 触发游戏事件
|
||||
oops.message.dispatchEvent(GameEvent.ButtonClicked, {
|
||||
buttonId: "action_button",
|
||||
timestamp: Date.now()
|
||||
});
|
||||
|
||||
// 执行业务逻辑
|
||||
this.performAction();
|
||||
}
|
||||
|
||||
performAction(): void {
|
||||
// 实现具体业务逻辑
|
||||
console.log("按钮被点击");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 实现动态数据刷新
|
||||
|
||||
```typescript
|
||||
// 使用MVVM框架实现自动数据刷新
|
||||
@ccclass('DynamicDataComp')
|
||||
export class DynamicDataComp extends VMBase {
|
||||
@property({ type: Label })
|
||||
public displayLabel: Label = null!;
|
||||
|
||||
@property(String)
|
||||
public watchPath: string = "global.player.health";
|
||||
|
||||
onValueChanged(newValue: any, oldValue: any, pathArray: string[]): void {
|
||||
// 自动更新UI显示
|
||||
this.displayLabel.string = `生命值: ${newValue}`;
|
||||
|
||||
// 可选：添加视觉反馈
|
||||
if (newValue < oldValue) {
|
||||
this.showDamageEffect();
|
||||
}
|
||||
}
|
||||
|
||||
showDamageEffect(): void {
|
||||
// 显示伤害特效
|
||||
tween(this.node)
|
||||
.to(0.1, { color: Color.RED })
|
||||
.to(0.1, { color: Color.WHITE })
|
||||
.start();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 性能优化考虑
|
||||
|
||||
### 组件复用策略
|
||||
|
||||
1. **预制体池化**：对于频繁创建销毁的UI组件，实现预制体池化机制
|
||||
2. **延迟加载**：非关键UI组件采用延迟加载策略
|
||||
3. **内存管理**：及时清理事件监听器和定时器
|
||||
|
||||
### 动画性能优化
|
||||
|
||||
1. **批量动画**：将多个动画合并为批量操作
|
||||
2. **硬件加速**：利用CSS3变换实现硬件加速
|
||||
3. **帧率控制**：限制动画帧率避免过度消耗CPU
|
||||
|
||||
### 数据绑定优化
|
||||
|
||||
1. **路径简化**：避免过深的数据绑定路径
|
||||
2. **防抖处理**：对高频数据更新实施防抖机制
|
||||
3. **选择性更新**：只更新发生变化的UI部分
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### UI组件无法显示
|
||||
|
||||
**问题症状**：UI组件创建后不显示或显示异常
|
||||
|
||||
**排查步骤**：
|
||||
1. 检查预制体路径配置是否正确
|
||||
2. 验证UI层级设置是否符合预期
|
||||
3. 确认组件脚本是否正确注册
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// 检查UI配置
|
||||
console.log("UI配置:", UIConfigData[UIID.CustomPanel]);
|
||||
|
||||
// 验证预制体加载
|
||||
oops.res.get(UIConfigData[UIID.CustomPanel].prefab, Prefab, (err, prefab) => {
|
||||
if (err) {
|
||||
console.error("预制体加载失败:", err);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### 数据绑定失效
|
||||
|
||||
**问题症状**：数据更新后UI不自动刷新
|
||||
|
||||
**排查步骤**：
|
||||
1. 检查watchPath路径是否正确
|
||||
2. 验证ViewModel是否正常工作
|
||||
3. 确认事件系统是否正常
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// 手动测试数据绑定
|
||||
VM.setValue("global.test.value", "测试数据");
|
||||
console.log("当前值:", VM.getValue("global.test.value"));
|
||||
```
|
||||
|
||||
#### 动画卡顿
|
||||
|
||||
**问题症状**：UI动画播放不流畅
|
||||
|
||||
**排查步骤**：
|
||||
1. 检查动画复杂度
|
||||
2. 验证硬件性能
|
||||
3. 确认动画队列管理
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// 优化动画实现
|
||||
tween(target)
|
||||
.to(0.2, { position: newPosition })
|
||||
.call(() => {
|
||||
// 动画完成后清理
|
||||
this.cleanupAnimation();
|
||||
})
|
||||
.start();
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L200-L344)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L150-L195)
|
||||
|
||||
## 总结
|
||||
|
||||
本UI系统通过模块化的架构设计，实现了高度可维护和可扩展的界面管理方案。系统的主要优势包括：
|
||||
|
||||
1. **统一的配置管理**：通过GameUIConfig.ts集中管理所有UI配置
|
||||
2. **MVVM架构**：实现数据与视图的自动绑定，减少手动DOM操作
|
||||
3. **事件驱动**：基于事件系统实现松耦合的组件通信
|
||||
4. **性能优化**：通过合理的架构设计和优化策略保证良好的性能表现
|
||||
5. **易于扩展**：模块化的设计使得添加新UI组件变得简单直观
|
||||
|
||||
该系统为游戏提供了稳定可靠的UI基础设施，支持复杂的交互逻辑和动态内容更新，是现代游戏开发中UI系统设计的优秀实践案例。
|
||||
467
.qoder/repowiki/zh/content/用户界面系统/胜利界面.md
Normal file
467
.qoder/repowiki/zh/content/用户界面系统/胜利界面.md
Normal file
@@ -0,0 +1,467 @@
|
||||
# 胜利界面
|
||||
|
||||
<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文档和使用示例
|
||||
|
||||
该组件为游戏胜利界面提供了坚实的技术基础，其设计理念和实现方式值得在类似项目中借鉴和应用。
|
||||
511
.qoder/repowiki/zh/content/用户界面系统/英雄信息面板.md
Normal file
511
.qoder/repowiki/zh/content/用户界面系统/英雄信息面板.md
Normal file
@@ -0,0 +1,511 @@
|
||||
# 英雄信息面板功能详细文档
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts)
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||||
- [HeroAttrs.ts](file://assets/script/game/common/config/HeroAttrs.ts)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||||
- [BezierMove.ts](file://assets/script/game/BezierMove/BezierMove.ts)
|
||||
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [概述](#概述)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 概述
|
||||
|
||||
HInfoComp.ts是Cocos Creator游戏引擎中英雄信息面板的核心组件，负责展示英雄属性、实现英雄切换动画以及处理用户交互。该组件采用MVVM架构模式，通过Tween动画系统实现流畅的英雄切换效果，并与全局状态管理系统smc紧密集成。
|
||||
|
||||
## 项目结构
|
||||
|
||||
英雄信息面板位于游戏的地图模块中，其文件组织结构如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "英雄信息面板模块"
|
||||
HInfoComp[HInfoComp.ts<br/>主控制器]
|
||||
HeroSet[heroSet.ts<br/>英雄配置]
|
||||
Singleton[SingletonModuleComp.ts<br/>全局状态管理]
|
||||
end
|
||||
subgraph "动画系统"
|
||||
Tween[Tween动画系统]
|
||||
AnimClip[AnimationClip<br/>动画剪辑]
|
||||
end
|
||||
subgraph "UI组件"
|
||||
Label[Label组件<br/>文本显示]
|
||||
ProgressBar[ProgressBar组件<br/>进度条显示]
|
||||
Button[Button组件<br/>交互按钮]
|
||||
end
|
||||
HInfoComp --> Tween
|
||||
HInfoComp --> HeroSet
|
||||
HInfoComp --> Singleton
|
||||
HInfoComp --> Label
|
||||
HInfoComp --> ProgressBar
|
||||
HInfoComp --> Button
|
||||
Tween --> AnimClip
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L50)
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts#L1-L30)
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L344)
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts#L1-L152)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 主控制器组件（HInfoComp）
|
||||
|
||||
HInfoComp是英雄信息面板的主要控制器，负责：
|
||||
- 管理英雄节点的生命周期
|
||||
- 处理英雄切换动画逻辑
|
||||
- 更新UI数据绑定
|
||||
- 响应用户交互事件
|
||||
|
||||
### 英雄配置系统
|
||||
|
||||
英雄配置系统提供了完整的英雄数据结构和过滤逻辑：
|
||||
- `getHeroList()`函数实现英雄列表的智能过滤
|
||||
- 支持拥有的英雄优先显示
|
||||
- 提供英雄属性计算和归一化功能
|
||||
|
||||
### 全局状态管理系统
|
||||
|
||||
smc（SingletonModuleComp）作为全局状态管理器，维护：
|
||||
- 当前出战英雄信息
|
||||
- 用户拥有的英雄列表
|
||||
- 游戏金币和其他资源数据
|
||||
- 与云端数据的同步机制
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L10-L50)
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts#L20-L40)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L40-L80)
|
||||
|
||||
## 架构概览
|
||||
|
||||
英雄信息面板采用分层架构设计，从底层到顶层依次为：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "表现层"
|
||||
UI[UI组件层<br/>Label, ProgressBar, Button]
|
||||
Anim[动画层<br/>Tween动画]
|
||||
end
|
||||
subgraph "业务逻辑层"
|
||||
Controller[控制器层<br/>HInfoComp]
|
||||
EventMgr[事件管理器<br/>GameEvent]
|
||||
end
|
||||
subgraph "数据层"
|
||||
Config[配置层<br/>HeroInfo, HeroSet]
|
||||
State[状态层<br/>smc全局状态]
|
||||
end
|
||||
subgraph "引擎层"
|
||||
CCEngine[Cocos引擎]
|
||||
ECS[ECS系统]
|
||||
end
|
||||
UI --> Controller
|
||||
Anim --> Controller
|
||||
Controller --> EventMgr
|
||||
Controller --> Config
|
||||
Controller --> State
|
||||
EventMgr --> State
|
||||
Config --> ECS
|
||||
State --> ECS
|
||||
Controller --> CCEngine
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L20)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L30)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 英雄属性展示系统
|
||||
|
||||
#### 属性数据绑定机制
|
||||
|
||||
英雄信息面板通过精确的UI数据绑定系统展示英雄属性：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户界面
|
||||
participant HInfo as HInfoComp
|
||||
participant HeroInfo as HeroInfo配置
|
||||
participant UI as UI组件
|
||||
User->>HInfo : 请求更新英雄属性
|
||||
HInfo->>HeroInfo : 查询英雄数据
|
||||
HeroInfo-->>HInfo : 返回英雄属性数据
|
||||
HInfo->>HInfo : 计算属性进度值
|
||||
HInfo->>UI : 更新Label组件
|
||||
HInfo->>UI : 更新ProgressBar组件
|
||||
UI-->>User : 显示更新后的属性
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L55-L76)
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts#L60-L70)
|
||||
|
||||
#### 英雄属性结构
|
||||
|
||||
| 属性类别 | 组件名称 | 数据来源 | 显示格式 |
|
||||
|---------|----------|----------|----------|
|
||||
| 基础属性 | 名称 | HeroInfo[uuid].name | 文本显示 |
|
||||
| 类型标识 | 类型 | HTypeName[HeroInfo[uuid].type] | 文本显示 |
|
||||
| 攻击力 | ap_node | HeroInfo[uuid].ap | 数字+进度条 |
|
||||
| 生命值 | hp_node | HeroInfo[uuid].hp | 数字+进度条 |
|
||||
| 物理防御 | def_node | HeroInfo[uuid].def | 数字+进度条 |
|
||||
| 魔法防御 | mdef_node | HeroInfo[uuid].mdef | 数字+进度条 |
|
||||
| 魔法值 | mp_node | HeroInfo[uuid].mp | 数字+进度条 |
|
||||
| 魔法攻击力 | map_node | HeroInfo[uuid].map | 数字+进度条 |
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L55-L76)
|
||||
|
||||
### 英雄切换动画系统
|
||||
|
||||
#### 动画冲突防止机制
|
||||
|
||||
系统实现了完善的动画冲突防止机制，确保用户交互的流畅性：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([用户点击切换]) --> CheckMoving{是否正在动画?}
|
||||
CheckMoving --> |是| Return([直接返回])
|
||||
CheckMoving --> |否| GetList[获取英雄列表]
|
||||
GetList --> CalcIndex[计算目标索引]
|
||||
CalcIndex --> UpdateUUID[更新英雄UUID]
|
||||
UpdateUUID --> UpdateData[更新UI数据]
|
||||
UpdateData --> StartAnim[启动切换动画]
|
||||
StartAnim --> SetFlag[设置动画标志]
|
||||
SetFlag --> WaitComplete[等待动画完成]
|
||||
WaitComplete --> ClearFlag[清除动画标志]
|
||||
ClearFlag --> End([完成])
|
||||
Return --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L169-L185)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L189-L205)
|
||||
|
||||
#### 平滑滚动机制
|
||||
|
||||
英雄切换采用基于Tween的平滑滚动动画：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Comp as HInfoComp
|
||||
participant Tween as Tween系统
|
||||
participant Node as 英雄节点
|
||||
participant Timer as 定时器
|
||||
Comp->>Comp : 检查动画状态
|
||||
Comp->>Comp : 销毁边界节点
|
||||
Comp->>Node : 获取所有现有节点
|
||||
loop 对每个节点
|
||||
Comp->>Tween : 创建移动动画
|
||||
Tween->>Node : 执行位置变换
|
||||
Tween->>Node : 执行缩放动画
|
||||
end
|
||||
Comp->>Timer : 设置延迟回调
|
||||
Timer->>Comp : 执行节点重排
|
||||
Comp->>Comp : 创建新节点
|
||||
Comp->>Comp : 清除动画标志
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L220-L344)
|
||||
|
||||
#### 中心位置缩放特效
|
||||
|
||||
系统为英雄信息面板的中心位置（pos_index=3）实现了独特的缩放特效：
|
||||
|
||||
| 位置索引 | 缩放比例 | 动画时长 | 特效说明 |
|
||||
|---------|----------|----------|----------|
|
||||
| 0, 6 | 1.0倍 | 0.2秒 | 标准大小显示 |
|
||||
| 1, 5 | 1.0倍 | 0.2秒 | 标准大小显示 |
|
||||
| 2, 4 | 1.0倍 | 0.2秒 | 标准大小显示 |
|
||||
| 3 | 1.5倍 | 0.2秒 | 中心放大特效 |
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L289-L344)
|
||||
|
||||
### 英雄列表获取与过滤
|
||||
|
||||
#### getHeroList()函数实现
|
||||
|
||||
getHeroList()函数实现了智能的英雄列表过滤逻辑：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始获取英雄列表]) --> FilterByFac[按阵营过滤英雄]
|
||||
FilterByFac --> SplitOwned[分离拥有的英雄]
|
||||
SplitOwned --> SplitUnowned[分离未拥有的英雄]
|
||||
SplitUnowned --> MergeLists[合并列表]
|
||||
MergeLists --> MapUUID[提取UUID数组]
|
||||
MapUUID --> Return([返回英雄列表])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts#L20-L35)
|
||||
|
||||
#### 英雄列表排序策略
|
||||
|
||||
英雄列表采用以下排序策略：
|
||||
1. **拥有的英雄优先**：用户已解锁的英雄排在前面
|
||||
2. **未拥有的英雄在后**：显示可购买的英雄
|
||||
3. **保持循环访问**：支持首尾循环切换
|
||||
|
||||
**章节来源**
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts#L20-L40)
|
||||
|
||||
### UI数据绑定系统
|
||||
|
||||
#### MVVM架构实现
|
||||
|
||||
英雄信息面板采用MVVM架构模式，实现数据与视图的自动同步：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class HInfoComp {
|
||||
+update_data(uuid : number)
|
||||
+show_lock()
|
||||
+is_own() boolean
|
||||
-name_node : any
|
||||
-type_node : any
|
||||
-ap_node : any
|
||||
-hp_node : any
|
||||
-def_node : any
|
||||
-mp_node : any
|
||||
-map_node : any
|
||||
-mdef_node : any
|
||||
}
|
||||
class HeroInfo {
|
||||
+uuid : number
|
||||
+name : string
|
||||
+type : HType
|
||||
+ap : number
|
||||
+hp : number
|
||||
+def : number
|
||||
+mp : number
|
||||
+map : number
|
||||
+mdef : number
|
||||
}
|
||||
class SingletonModuleComp {
|
||||
+fight_hero : number
|
||||
+heros : any[]
|
||||
+vmdata : any
|
||||
+updateFihgtHero(heroId : number)
|
||||
+addHero(hero_uuid : number)
|
||||
}
|
||||
HInfoComp --> HeroInfo : "读取数据"
|
||||
HInfoComp --> SingletonModuleComp : "状态管理"
|
||||
SingletonModuleComp --> HeroInfo : "共享数据"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L10-L50)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L40-L80)
|
||||
|
||||
#### ProgressBar和Label响应机制
|
||||
|
||||
系统通过以下机制响应smc.fight_hero的变化：
|
||||
|
||||
| 组件类型 | 响应方式 | 更新内容 | 触发条件 |
|
||||
|---------|----------|----------|----------|
|
||||
| Label | 直接赋值 | 文本内容 | UUID变化 |
|
||||
| ProgressBar | 进度赋值 | 进度条显示 | 属性值变化 |
|
||||
| Lock状态 | 可见性切换 | 锁定图标显示 | 拥有状态变化 |
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L55-L76)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L145-L155)
|
||||
|
||||
### 英雄购买逻辑
|
||||
|
||||
#### buy_hero()函数实现
|
||||
|
||||
英雄购买功能实现了完整的购买流程：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([点击购买]) --> CheckGold{金币充足?}
|
||||
CheckGold --> |否| ShowToast[显示提示："金币不足"]
|
||||
CheckGold --> |是| AddHero[添加英雄到列表]
|
||||
AddHero --> UpdateUI[更新UI显示]
|
||||
UpdateUI --> ShowLock[刷新锁定状态]
|
||||
ShowToast --> End([结束])
|
||||
ShowLock --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L207-L215)
|
||||
|
||||
#### 购买成本与验证
|
||||
|
||||
| 参数 | 值 | 说明 |
|
||||
|------|----|----- |
|
||||
| 购买成本 | 1500金币 | HeroConf.COST常量 |
|
||||
| 验证方式 | smc.vmdata.gold | 全局金币余额 |
|
||||
| 失败处理 | 显示Toast提示 | 用户友好反馈 |
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L207-L215)
|
||||
- [heroSet.ts](file://assets/script/game/common/config/heroSet.ts#L54-L56)
|
||||
|
||||
### 战斗启动流程
|
||||
|
||||
#### start_mission()函数实现
|
||||
|
||||
战斗启动流程负责初始化战斗准备：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant HInfo as HInfoComp
|
||||
participant Event as GameEvent
|
||||
participant Scene as 游戏场景
|
||||
User->>HInfo : 点击开始战斗
|
||||
HInfo->>Event : 分发MissionStart事件
|
||||
Event->>Scene : 触发战斗准备
|
||||
HInfo->>HInfo : 隐藏面板
|
||||
Scene-->>User : 进入战斗场景
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L216-L219)
|
||||
|
||||
#### 与全局状态管理的交互
|
||||
|
||||
战斗启动过程中，HInfoComp与smc的交互包括：
|
||||
- 触发GameEvent.MissionStart事件
|
||||
- 隐藏英雄信息面板
|
||||
- 准备战斗所需的英雄数据
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L216-L219)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L1-L20)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 组件间依赖关系
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "外部依赖"
|
||||
CCEngine[Cocos引擎]
|
||||
OopsFramework[Oops框架]
|
||||
end
|
||||
subgraph "内部模块"
|
||||
HInfoComp[HInfoComp]
|
||||
HeroSet[heroSet]
|
||||
Singleton[SingletonModuleComp]
|
||||
GameEvent[GameEvent]
|
||||
end
|
||||
subgraph "动画系统"
|
||||
Tween[Tween动画]
|
||||
AnimClip[AnimationClip]
|
||||
end
|
||||
HInfoComp --> CCEngine
|
||||
HInfoComp --> OopsFramework
|
||||
HInfoComp --> HeroSet
|
||||
HInfoComp --> Singleton
|
||||
HInfoComp --> GameEvent
|
||||
HInfoComp --> Tween
|
||||
Tween --> AnimClip
|
||||
Singleton --> GameEvent
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L10)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L15)
|
||||
|
||||
### 数据流依赖
|
||||
|
||||
英雄信息面板的数据流遵循单向数据流原则：
|
||||
|
||||
| 数据流向 | 源组件 | 目标组件 | 数据类型 | 更新机制 |
|
||||
|---------|--------|----------|----------|----------|
|
||||
| 配置数据 | HeroInfo | HInfoComp | 静态配置 | 静态加载 |
|
||||
| 状态数据 | smc | HInfoComp | 动态状态 | 事件驱动 |
|
||||
| 用户输入 | UI交互 | HInfoComp | 用户指令 | 事件响应 |
|
||||
| 动画状态 | Tween | HInfoComp | 动画进度 | 回调通知 |
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L1-L20)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L40-L80)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 内存管理优化
|
||||
|
||||
英雄信息面板实现了多项内存管理优化措施：
|
||||
|
||||
1. **节点池化**：通过`claear_hero()`方法及时销毁不再使用的英雄节点
|
||||
2. **定时器清理**：使用`moveTimeoutId`避免内存泄漏
|
||||
3. **动画状态控制**：通过`isMoving`标志防止重复动画
|
||||
|
||||
### 动画性能优化
|
||||
|
||||
- **批量动画**：使用Tween系统批量处理多个节点的动画
|
||||
- **延迟执行**：通过setTimeout实现动画与逻辑的解耦
|
||||
- **缩放优化**：中心位置使用预设缩放值，减少计算开销
|
||||
|
||||
### 数据访问优化
|
||||
|
||||
- **静态数据缓存**：HeroInfo配置数据在编译时确定
|
||||
- **索引查找优化**：使用indexOf快速定位英雄位置
|
||||
- **循环边界处理**：预计算边界条件，减少运行时计算
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题与解决方案
|
||||
|
||||
#### 动画冲突问题
|
||||
|
||||
**症状**：快速点击英雄切换按钮导致动画混乱
|
||||
**原因**：多个动画同时执行
|
||||
**解决方案**：系统通过`isMoving`标志和`moveTimeoutId`实现动画冲突防止
|
||||
|
||||
#### 英雄节点显示异常
|
||||
|
||||
**症状**：英雄节点位置错乱或不显示
|
||||
**原因**：hero_pos配置错误或节点销毁不完全
|
||||
**解决方案**：检查HeroPos配置，确保`claear_hero()`正确执行
|
||||
|
||||
#### UI数据不同步
|
||||
|
||||
**症状**：英雄属性显示与实际不符
|
||||
**原因**：smc状态未正确更新
|
||||
**解决方案**：验证smc.updateFihgtHero()调用，检查事件分发机制
|
||||
|
||||
#### 购买功能失效
|
||||
|
||||
**症状**：点击购买按钮无响应
|
||||
**原因**：金币不足检测或smc.addHero()调用失败
|
||||
**解决方案**：检查smc.vmdata.gold值，验证全局状态同步
|
||||
|
||||
**章节来源**
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L169-L185)
|
||||
- [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts#L207-L215)
|
||||
|
||||
## 结论
|
||||
|
||||
HInfoComp.ts英雄信息面板组件展现了现代游戏开发中的最佳实践：
|
||||
|
||||
1. **架构设计**：采用分层架构和MVVM模式，实现了良好的代码组织和数据管理
|
||||
2. **用户体验**：通过流畅的动画和直观的界面，提供了优秀的用户体验
|
||||
3. **性能优化**：实现了内存管理和动画优化，确保了良好的运行性能
|
||||
4. **扩展性**：模块化设计便于功能扩展和维护
|
||||
|
||||
该组件的成功实现为游戏开发提供了宝贵的参考经验，特别是在动画系统集成、状态管理和用户交互方面。通过深入理解其实现原理，开发者可以更好地构建类似的复杂UI组件。
|
||||
333
.qoder/repowiki/zh/content/用户界面系统/顶部状态栏.md
Normal file
333
.qoder/repowiki/zh/content/用户界面系统/顶部状态栏.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# 顶部状态栏组件详细文档
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||||
- [BoxSet.ts](file://assets/script/game/common/config/BoxSet.ts)
|
||||
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构概述](#项目结构概述)
|
||||
3. [核心组件分析](#核心组件分析)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
TopComp.ts是游戏主界面中的顶部状态栏组件，负责显示玩家的金币数量并提供视觉反馈动画。该组件采用Cocos Creator框架开发，集成了Oops框架的消息系统，实现了对金币更新事件的响应式处理。
|
||||
|
||||
## 项目结构概述
|
||||
|
||||
TopComp组件位于游戏的地图模块中，属于游戏主界面的重要组成部分。其文件结构如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "游戏模块结构"
|
||||
A[assets/script/game/map/] --> B[TopComp.ts]
|
||||
A --> C[GameEvent.ts]
|
||||
A --> D[BoxSet.ts]
|
||||
A --> E[SingletonModuleComp.ts]
|
||||
end
|
||||
subgraph "Oops框架集成"
|
||||
F[Oops Framework] --> G[Message System]
|
||||
F --> H[Global Events]
|
||||
end
|
||||
B --> F
|
||||
C --> G
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L1-L30)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L1-L70)
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L1-L30)
|
||||
|
||||
## 核心组件分析
|
||||
|
||||
TopComp组件是一个继承自Cocos Creator Component类的UI组件，具有以下核心特性：
|
||||
|
||||
### 组件基本信息
|
||||
- **类名**: topComp
|
||||
- **装饰器**: @ccclass('topComp')
|
||||
- **继承关系**: Component
|
||||
- **事件监听**: GameEvent.GOLD_UPDATE
|
||||
|
||||
### 主要功能模块
|
||||
1. **事件监听机制**: 监听金币更新事件
|
||||
2. **动画效果**: 实现金币数字的缩放脉冲动画
|
||||
3. **节点路径查找**: 定位金币显示节点
|
||||
4. **全局消息集成**: 与Oops框架消息系统协作
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L8-L30)
|
||||
|
||||
## 架构概览
|
||||
|
||||
TopComp组件在整个游戏架构中扮演着重要的UI状态同步角色：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Game as "游戏逻辑"
|
||||
participant Event as "GameEvent"
|
||||
participant TopComp as "TopComp组件"
|
||||
participant Tween as "Tween动画系统"
|
||||
participant UI as "UI显示层"
|
||||
Game->>Event : 触发GOLD_UPDATE事件
|
||||
Event->>TopComp : onGoldUpdate回调
|
||||
TopComp->>TopComp : 查找节点路径
|
||||
TopComp->>Tween : 创建缩放动画
|
||||
Tween->>UI : 执行1.2倍放大
|
||||
Tween->>UI : 执行恢复动画
|
||||
UI-->>Game : 显示视觉反馈
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L12-L20)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L68-L69)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 事件监听机制
|
||||
|
||||
TopComp组件通过Oops框架的消息系统实现事件监听：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class topComp {
|
||||
+onLoad() void
|
||||
+onGoldUpdate(event, data) void
|
||||
+start() void
|
||||
+update(deltaTime) void
|
||||
}
|
||||
class GameEvent {
|
||||
<<enumeration>>
|
||||
GOLD_UPDATE
|
||||
DIAMOND_UPDATE
|
||||
MEAT_UPDATE
|
||||
MISSION_UPDATE
|
||||
}
|
||||
class OopsMessage {
|
||||
+on(event, callback, target) void
|
||||
+once(event, callback, target) void
|
||||
}
|
||||
topComp --> GameEvent : "监听"
|
||||
topComp --> OopsMessage : "使用"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L10-L12)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L68-L69)
|
||||
|
||||
#### 监听机制实现细节
|
||||
|
||||
组件在`onLoad`生命周期中注册事件监听器，当GameEvent.GOLD_UPDATE事件被触发时，会调用`onGoldUpdate`回调函数。
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L10-L12)
|
||||
|
||||
### 金币数字缩放动画
|
||||
|
||||
TopComp的核心功能是实现金币数字的视觉反馈动画：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["接收GOLD_UPDATE事件"] --> B["查找节点路径"]
|
||||
B --> C["获取Label组件"]
|
||||
C --> D["创建Tween动画"]
|
||||
D --> E["执行1.2倍放大(0.1秒)"]
|
||||
E --> F["执行恢复原大小(0.1秒)"]
|
||||
F --> G["动画完成"]
|
||||
B1["this.node.getChildByName('bar')"] --> B2["getChildByName('gold')"]
|
||||
B2 --> B3["getChildByName('num')"]
|
||||
B3 --> B4["getComponent(Label)"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L14-L19)
|
||||
|
||||
#### 动画参数配置
|
||||
|
||||
动画系统使用以下参数：
|
||||
- **持续时间**: 每阶段0.1秒，总时长0.2秒
|
||||
- **缩放比例**: 从1.0倍放大到1.2倍
|
||||
- **恢复比例**: 从1.2倍恢复到1.0倍
|
||||
- **缓动类型**: 默认缓动（未指定具体类型）
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L14-L19)
|
||||
|
||||
### 节点路径查找机制
|
||||
|
||||
组件通过层级化的节点查找方式定位金币显示元素：
|
||||
|
||||
#### 路径解析
|
||||
1. **根节点**: `this.node`
|
||||
2. **第一层**: `"bar"` - 状态栏容器
|
||||
3. **第二层**: `"gold"` - 金币区域
|
||||
4. **第三层**: `"num"` - 数字显示区域
|
||||
5. **目标组件**: `Label` - 文本显示组件
|
||||
|
||||
这种设计允许开发者灵活调整UI布局，只需修改节点名称即可适应不同的界面设计。
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L14-L19)
|
||||
|
||||
### 与全局消息系统的集成
|
||||
|
||||
TopComp与Oops框架的消息系统深度集成：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A["Oops Message System"] --> B["事件发布"]
|
||||
B --> C["TopComp监听"]
|
||||
C --> D["回调执行"]
|
||||
D --> E["动画触发"]
|
||||
F["GameEvent枚举"] --> G["GOLD_UPDATE"]
|
||||
G --> C
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L10-L12)
|
||||
|
||||
#### 集成优势
|
||||
1. **解耦设计**: 组件间通过事件通信，降低耦合度
|
||||
2. **可扩展性**: 支持多个组件监听同一事件
|
||||
3. **内存安全**: 自动清理事件监听器
|
||||
4. **类型安全**: 通过枚举确保事件名称正确性
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L10-L12)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
TopComp组件的依赖关系展现了清晰的分层架构：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "外部依赖"
|
||||
A[Cocos Creator Engine]
|
||||
B[Oops Framework]
|
||||
end
|
||||
subgraph "内部依赖"
|
||||
C[GameEvent枚举]
|
||||
D[SingletonModuleComp]
|
||||
E[BoxSet工具类]
|
||||
end
|
||||
subgraph "TopComp组件"
|
||||
F[topComp类]
|
||||
end
|
||||
A --> F
|
||||
B --> F
|
||||
C --> F
|
||||
D --> F
|
||||
E --> F
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L1-L6)
|
||||
|
||||
### 依赖项说明
|
||||
|
||||
| 依赖项 | 类型 | 用途 | 版本要求 |
|
||||
|--------|------|------|----------|
|
||||
| Cocos Creator | 引擎 | UI渲染和动画系统 | 最新稳定版 |
|
||||
| Oops Framework | 框架 | 消息系统和全局管理 | 1.x版本 |
|
||||
| GameEvent | 枚举 | 事件类型定义 | 内部定义 |
|
||||
| SingletonModuleComp | 单例 | 全局状态管理 | 内部实现 |
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L1-L6)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
TopComp组件在设计时充分考虑了性能优化：
|
||||
|
||||
### 动画性能优化
|
||||
- **短时动画**: 0.2秒的动画周期不会造成明显的性能负担
|
||||
- **局部更新**: 只更新金币显示区域，不影响其他UI元素
|
||||
- **硬件加速**: 利用Cocos Creator的GPU加速能力
|
||||
|
||||
### 内存管理
|
||||
- **事件监听**: 使用Oops框架的自动清理机制
|
||||
- **节点查找**: 缓存节点引用，避免重复查找
|
||||
- **组件卸载**: 遵循Cocos Creator的组件生命周期
|
||||
|
||||
### 最佳实践建议
|
||||
1. **避免频繁触发**: 控制GOLD_UPDATE事件的触发频率
|
||||
2. **批量更新**: 如果需要同时更新多个状态，考虑合并事件
|
||||
3. **性能监控**: 在复杂场景下监控动画帧率
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 问题1: 动画不显示
|
||||
**症状**: 金币更新时没有视觉反馈
|
||||
**可能原因**:
|
||||
- 节点路径错误
|
||||
- Label组件未正确绑定
|
||||
- Tween系统异常
|
||||
|
||||
**解决方案**:
|
||||
1. 检查节点层次结构是否符合预期
|
||||
2. 验证"bar/gold/num"路径是否存在
|
||||
3. 确认Label组件已正确添加到目标节点
|
||||
|
||||
#### 问题2: 事件监听失效
|
||||
**症状**: 金币更新事件无法触发动画
|
||||
**可能原因**:
|
||||
- 事件名称不匹配
|
||||
- 组件未正确初始化
|
||||
- Oops消息系统异常
|
||||
|
||||
**解决方案**:
|
||||
1. 确认使用的是`GameEvent.GOLD_UPDATE`
|
||||
2. 检查组件是否已正确添加到场景
|
||||
3. 验证Oops框架是否正常加载
|
||||
|
||||
#### 问题3: 动画卡顿
|
||||
**症状**: 动画播放不流畅
|
||||
**可能原因**:
|
||||
- 系统资源不足
|
||||
- 同时运行过多动画
|
||||
- GPU性能限制
|
||||
|
||||
**解决方案**:
|
||||
1. 减少同时播放的动画数量
|
||||
2. 优化动画参数
|
||||
3. 监控系统资源使用情况
|
||||
|
||||
**章节来源**
|
||||
- [TopComp.ts](file://assets/script/game/map/TopComp.ts#L14-L19)
|
||||
|
||||
## 结论
|
||||
|
||||
TopComp组件是一个设计精良的UI状态栏组件，具有以下特点：
|
||||
|
||||
### 技术优势
|
||||
1. **事件驱动架构**: 通过Oops框架实现松耦合的事件通信
|
||||
2. **响应式设计**: 对金币变化提供即时的视觉反馈
|
||||
3. **易于维护**: 清晰的代码结构和明确的职责分工
|
||||
4. **性能友好**: 短时动画和局部更新策略
|
||||
|
||||
### 设计亮点
|
||||
- **模块化**: 事件监听与动画执行分离
|
||||
- **可扩展**: 支持多种状态栏元素的扩展
|
||||
- **健壮性**: 完善的错误处理和边界检查
|
||||
- **用户体验**: 流畅的动画效果提升用户感知
|
||||
|
||||
### 改进建议
|
||||
1. **动画参数化**: 提供可配置的动画参数
|
||||
2. **状态管理**: 集成更完整的UI状态管理系统
|
||||
3. **测试覆盖**: 增加单元测试和集成测试
|
||||
4. **文档完善**: 补充详细的API文档和使用示例
|
||||
|
||||
TopComp组件展现了现代游戏UI开发的最佳实践，为游戏提供了良好的用户体验基础。
|
||||
Reference in New Issue
Block a user