pan/heros

Files

panw 4235e3b776 refactor(game): 移除已弃用的事件常量

- 删除 UpdateHero 和 UpdateFightHero 事件
- 移除 MISSION_UPDATE 事件常量
- 优化游戏事件枚举定义

2025-10-28 16:15:47 +08:00

15 KiB

Raw Blame History

英雄信息面板功能详细文档

**本文档中引用的文件** - [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)

概述

HInfoComp.ts是Cocos Creator游戏引擎中英雄信息面板的核心组件，负责展示英雄属性、实现英雄切换动画以及处理用户交互。该组件采用MVVM架构模式，通过Tween动画系统实现流畅的英雄切换效果，并与全局状态管理系统smc紧密集成。

项目结构

英雄信息面板位于游戏的地图模块中，其文件组织结构如下：

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）

HInfoComp是英雄信息面板的主要控制器，负责：

管理英雄节点的生命周期
处理英雄切换动画逻辑
更新UI数据绑定
响应用户交互事件

英雄配置系统

英雄配置系统提供了完整的英雄数据结构和过滤逻辑：

getHeroList()函数实现英雄列表的智能过滤
支持拥有的英雄优先显示
提供英雄属性计算和归一化功能

全局状态管理系统

smc（SingletonModuleComp）作为全局状态管理器，维护：

当前出战英雄信息
用户拥有的英雄列表
游戏金币和其他资源数据
与云端数据的同步机制

章节来源

架构概览

英雄信息面板采用分层架构设计，从底层到顶层依次为：

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

图表来源

详细组件分析

英雄属性展示系统

属性数据绑定机制

英雄信息面板通过精确的UI数据绑定系统展示英雄属性：

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 : 显示更新后的属性

图表来源

英雄属性结构

属性类别	组件名称	数据来源	显示格式
基础属性	名称	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

英雄切换动画系统

动画冲突防止机制

系统实现了完善的动画冲突防止机制，确保用户交互的流畅性：

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

图表来源

平滑滚动机制

英雄切换采用基于Tween的平滑滚动动画：

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

中心位置缩放特效

系统为英雄信息面板的中心位置（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

英雄列表获取与过滤

getHeroList()函数实现

getHeroList()函数实现了智能的英雄列表过滤逻辑：

flowchart TD
Start([开始获取英雄列表]) --> FilterByFac[按阵营过滤英雄]
FilterByFac --> SplitOwned[分离拥有的英雄]
SplitOwned --> SplitUnowned[分离未拥有的英雄]
SplitUnowned --> MergeLists[合并列表]
MergeLists --> MapUUID[提取UUID数组]
MapUUID --> Return([返回英雄列表])

图表来源

heroSet.ts

英雄列表排序策略

英雄列表采用以下排序策略：

拥有的英雄优先：用户已解锁的英雄排在前面
未拥有的英雄在后：显示可购买的英雄
保持循环访问：支持首尾循环切换

章节来源

heroSet.ts

UI数据绑定系统

MVVM架构实现

英雄信息面板采用MVVM架构模式，实现数据与视图的自动同步：

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 : "共享数据"

图表来源

ProgressBar和Label响应机制

系统通过以下机制响应smc.fight_hero的变化：

组件类型	响应方式	更新内容	触发条件
Label	直接赋值	文本内容	UUID变化
ProgressBar	进度赋值	进度条显示	属性值变化
Lock状态	可见性切换	锁定图标显示	拥有状态变化

章节来源

英雄购买逻辑

buy_hero()函数实现

英雄购买功能实现了完整的购买流程：

flowchart TD
Start([点击购买]) --> CheckGold{金币充足?}
CheckGold --> |否| ShowToast[显示提示："金币不足"]
CheckGold --> |是| AddHero[添加英雄到列表]
AddHero --> UpdateUI[更新UI显示]
UpdateUI --> ShowLock[刷新锁定状态]
ShowToast --> End([结束])
ShowLock --> End

图表来源

HInfoComp.ts

购买成本与验证

参数	值	说明
购买成本	1500金币	HeroConf.COST常量
验证方式	smc.vmdata.gold	全局金币余额
失败处理	显示Toast提示	用户友好反馈

章节来源

战斗启动流程

start_mission()函数实现

战斗启动流程负责初始化战斗准备：

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

与全局状态管理的交互

战斗启动过程中，HInfoComp与smc的交互包括：

触发GameEvent.MissionStart事件
隐藏英雄信息面板
准备战斗所需的英雄数据

章节来源

依赖关系分析

组件间依赖关系

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

图表来源

数据流依赖

英雄信息面板的数据流遵循单向数据流原则：

数据流向	源组件	目标组件	数据类型	更新机制
配置数据	HeroInfo	HInfoComp	静态配置	静态加载
状态数据	smc	HInfoComp	动态状态	事件驱动
用户输入	UI交互	HInfoComp	用户指令	事件响应
动画状态	Tween	HInfoComp	动画进度	回调通知

章节来源

性能考虑

内存管理优化

英雄信息面板实现了多项内存管理优化措施：

节点池化：通过claear_hero()方法及时销毁不再使用的英雄节点
定时器清理：使用moveTimeoutId避免内存泄漏
动画状态控制：通过isMoving标志防止重复动画

动画性能优化

批量动画：使用Tween系统批量处理多个节点的动画
延迟执行：通过setTimeout实现动画与逻辑的解耦
缩放优化：中心位置使用预设缩放值，减少计算开销

数据访问优化

静态数据缓存：HeroInfo配置数据在编译时确定
索引查找优化：使用indexOf快速定位英雄位置
循环边界处理：预计算边界条件，减少运行时计算

故障排除指南

常见问题与解决方案

动画冲突问题

症状：快速点击英雄切换按钮导致动画混乱原因：多个动画同时执行 解决方案：系统通过isMoving标志和moveTimeoutId实现动画冲突防止

英雄节点显示异常

症状：英雄节点位置错乱或不显示原因：hero_pos配置错误或节点销毁不完全 解决方案：检查HeroPos配置，确保claear_hero()正确执行

UI数据不同步

症状：英雄属性显示与实际不符原因：smc状态未正确更新 解决方案：验证smc.updateFihgtHero()调用，检查事件分发机制

购买功能失效

症状：点击购买按钮无响应原因：金币不足检测或smc.addHero()调用失败 解决方案：检查smc.vmdata.gold值，验证全局状态同步

章节来源

结论

HInfoComp.ts英雄信息面板组件展现了现代游戏开发中的最佳实践：

架构设计：采用分层架构和MVVM模式，实现了良好的代码组织和数据管理
用户体验：通过流畅的动画和直观的界面，提供了优秀的用户体验
性能优化：实现了内存管理和动画优化，确保了良好的运行性能
扩展性：模块化设计便于功能扩展和维护

该组件的成功实现为游戏开发提供了宝贵的参考经验，特别是在动画系统集成、状态管理和用户交互方面。通过深入理解其实现原理，开发者可以更好地构建类似的复杂UI组件。

15 KiB Raw Blame History Unescape Escape

英雄信息面板功能详细文档

目录

概述

项目结构

核心组件

主控制器组件（HInfoComp）

英雄配置系统

全局状态管理系统

架构概览

详细组件分析

英雄属性展示系统

属性数据绑定机制

英雄属性结构

英雄切换动画系统

动画冲突防止机制

平滑滚动机制

中心位置缩放特效

英雄列表获取与过滤

getHeroList()函数实现

英雄列表排序策略

UI数据绑定系统

MVVM架构实现

ProgressBar和Label响应机制

英雄购买逻辑

buy_hero()函数实现

购买成本与验证

战斗启动流程

start_mission()函数实现

与全局状态管理的交互

依赖关系分析

组件间依赖关系

数据流依赖

性能考虑

内存管理优化

动画性能优化

数据访问优化

故障排除指南

常见问题与解决方案

动画冲突问题

英雄节点显示异常

UI数据不同步

购买功能失效

结论

15 KiB

Raw Blame History