# 英雄信息面板功能详细文档 **本文档中引用的文件** - [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) ## 目录 1. [概述](#概述) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构概览](#架构概览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考虑](#性能考虑) 8. [故障排除指南](#故障排除指南) 9. [结论](#结论) ## 概述 HInfoComp.ts是Cocos Creator游戏引擎中英雄信息面板的核心组件，负责展示英雄属性、实现英雄切换动画以及处理用户交互。该组件采用MVVM架构模式，通过Tween动画系统实现流畅的英雄切换效果，并与全局状态管理系统smc紧密集成。 ## 项目结构 英雄信息面板位于游戏的地图模块中，其文件组织结构如下： ```mermaid graph TB subgraph "英雄信息面板模块" HInfoComp[HInfoComp.ts
主控制器] HeroSet[heroSet.ts
英雄配置] Singleton[SingletonModuleComp.ts
全局状态管理] end subgraph "动画系统" Tween[Tween动画系统] AnimClip[AnimationClip
动画剪辑] end subgraph "UI组件" Label[Label组件
文本显示] ProgressBar[ProgressBar组件
进度条显示] Button[Button组件
交互按钮] 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组件层
Label, ProgressBar, Button] Anim[动画层
Tween动画] end subgraph "业务逻辑层" Controller[控制器层
HInfoComp] EventMgr[事件管理器
GameEvent] end subgraph "数据层" Config[配置层
HeroInfo, HeroSet] State[状态层
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组件。