511 lines
15 KiB
Markdown
511 lines
15 KiB
Markdown
# 英雄信息面板功能详细文档
|
||
|
||
<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组件。 |