# 技术架构

<cite>
**本文档中引用的文件**
- [Main.ts](file://assets/script/Main.ts) - *更新了ECS系统注册*
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)
- [HSkillSystem.ts](file://assets/script/game/hero/HSkillSystem.ts#L1-L272) - *新增ECS系统注册装饰器*
- [HeroAtk.ts](file://assets/script/game/hero/HeroAtk.ts#L1-L248) - *新增ECS系统注册装饰器*
- [HeroAttrsComp.ts](file://assets/script/game/hero/HeroAttrsComp.ts#L1-L380) - *新增ECS组件注册装饰器*
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L1-L780)
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts)
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts)
- [ecs.md](file://doc/ecs/ecs.md)
- [MvvmInfo.md](file://doc/mvvm/MvvmInfo.md)
</cite>

## 更新摘要
**变更内容**
- 在HSkillSystem.ts、HeroAtk.ts和HeroAttrsComp.ts中添加了ECS注册装饰器
- Main.ts的初始化流程更新，反映架构入口点调整
- 移除了过时的SkillConComp组件，更新技能系统架构说明
- 新增了英雄属性更新系统(HeroAttrSystem)和生命周期系统(HeroLifecycleSystem)的文档
- 更新了ECS架构支柱章节，反映最新的系统注册模式

## 目录
1. [引言](#引言)
2. [项目架构概览](#项目架构概览)
3. [ECS架构支柱](#ecs架构支柱)
4. [MVVM架构支柱](#mvvm架构支柱)
5. [单例模式架构支柱](#单例模式架构支柱)
6. [核心组件深度分析](#核心组件深度分析)
7. [架构协作机制](#架构协作机制)
8. [生命周期管理](#生命周期管理)
9. [性能优化策略](#性能优化策略)
10. [总结](#总结)

## 引言

本项目采用了一套高度集成的技术架构，以ECS（实体-组件-系统）、MVVM（模型-视图-视图模型）和单例模式三大支柱为核心，构建了一个高度解耦、可扩展的游戏引擎。这种架构设计不仅提升了代码的可维护性，还为游戏逻辑的复杂性管理提供了强有力的支撑。

## 项目架构概览

项目采用了分层架构设计，每一层都有明确的职责分工：

```mermaid
graph TB
subgraph "表现层"
UI[用户界面]
GUI[图形用户界面]
end
subgraph "业务逻辑层"
ECS[ECS系统]
MVVM[MVVM框架]
SM[单例模块]
end
subgraph "数据层"
DATA[游戏数据]
CONFIG[配置数据]
RESOURCES[资源管理]
end
UI --> ECS
GUI --> MVVM
ECS --> DATA
MVVM --> DATA
SM --> CONFIG
DATA --> RESOURCES
```

**图表来源**
- [Main.ts](file://assets/script/Main.ts#L1-L41)
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207)

**章节来源**
- [Main.ts](file://assets/script/Main.ts#L1-L41)
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207)

## ECS架构支柱

### ECS核心概念

ECS（Entity-Component-System）架构是一种面向组件的设计模式，将游戏对象分解为三个核心元素：

1. **实体（Entity）**：纯粹的标识符，用于组合组件
2. **组件（Component）**：携带数据的简单容器
3. **系统（System）**：处理具有特定组件组合的实体

### 组件系统设计

项目中的组件系统展现了高度的模块化和可复用性：

```mermaid
classDiagram
class ecs_Comp {
+reset() void
+canRecycle boolean
+ent Entity
}
class HeroAttrsComp {
+hero_uuid number
+lv number
+base_ap number
+base_hp number
+hp number
+mp number
+Attrs any
+BUFFS any
+reset() void
}
class HeroViewComp {
+status string
+hero_uuid number
+hp number
+mp number
+Attrs any
+BUFFS any
+update(dt) void
}
class HeroSkillsComp {
+skills SkillSlot[]
+initSkills(skillIds) void
+canCast(index, mp) boolean
+resetCD(index) void
+updateCDs(dt) void
}
ecs_Comp <|-- HeroAttrsComp
ecs_Comp <|-- HeroViewComp
ecs_Comp <|-- HeroSkillsComp
```

**图表来源**
- [HeroAttrsComp.ts](file://assets/script/game/hero/HeroAttrsComp.ts#L7-L380) - *新增ECS组件注册*
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L1-L780)
- [HeroSkills.ts](file://assets/script/game/hero/HeroSkills.ts#L1-L150)

### 系统协作机制

系统通过过滤器机制实现高效的实体管理，并使用ECS注册装饰器进行系统注册：

```mermaid
sequenceDiagram
participant RS as RootSystem
participant HSS as HeroAttrSystem
participant ECS as ECS引擎
participant Entity as 实体
participant Comp as 组件
RS->>ECS : 执行系统
ECS->>HSS : filter()匹配实体
HSS->>Entity : 获取HeroAttrsComp
HSS->>Entity : update()处理逻辑
Entity->>Comp : 更新状态
Comp-->>Entity : 返回结果
Entity-->>HSS : 完成处理
HSS-->>RS : 系统执行完毕
```

**图表来源**
- [HSkillSystem.ts](file://assets/script/game/hero/HSkillSystem.ts#L1-L272) - *新增ECS系统注册装饰器*
- [HeroAtk.ts](file://assets/script/game/hero/HeroAtk.ts#L1-L248) - *新增ECS系统注册装饰器*
- [HeroAttrsComp.ts](file://assets/script/game/hero/HeroAttrsComp.ts#L397-L437) - *新增HeroAttrSystem*

### ECS解耦优势

ECS架构在游戏逻辑中实现了以下解耦效果：

1. **数据与行为分离**：组件只负责数据存储，系统负责逻辑处理
2. **灵活组合**：通过不同组件的组合实现多样化的游戏对象
3. **高效处理**：系统可以批量处理具有相同组件组合的实体
4. **易于扩展**：新增功能只需添加新组件和系统，无需修改现有代码

**章节来源**
- [ecs.md](file://doc/ecs/ecs.md#L1-L357)
- [HSkillSystem.ts](file://assets/script/game/hero/HSkillSystem.ts#L1-L272) - *新增ECS系统注册装饰器*

## MVVM架构支柱

### Oops Plugin Framework概述

Oops Plugin Framework是一个专为Cocos Creator设计的MVVM框架，提供了完整的双向数据绑定解决方案：

```mermaid
graph LR
subgraph "ViewModel层"
VM[ViewModel]
VMData[数据模型]
end
subgraph "View层"
UI[用户界面]
Components[UI组件]
end
subgraph "Binding层"
VMCustom[VMCustom]
VMLabel[VMLabel]
VMState[VMState]
VMProgress[VMProgress]
end
VM --> VMData
VMData --> VMCustom
VMCustom --> UI
VMLabel --> UI
VMState --> UI
VMProgress --> UI
Components --> VMCustom
```

**图表来源**
- [MvvmInfo.md](file://doc/mvvm/MvvmInfo.md#L1-L52)

### 双向绑定机制

MVVM框架通过观察者模式实现了数据的自动同步：

```mermaid
flowchart TD
Start([数据变更]) --> Notify[通知ViewModel]
Notify --> Emit[触发cc.director.emit]
Emit --> Listen[UI组件监听]
Listen --> Update[更新界面显示]
Update --> End([界面刷新完成])
Start2([用户交互]) --> Trigger[触发事件]
Trigger --> Modify[修改数据模型]
Modify --> Notify
```

**图表来源**
- [MvvmInfo.md](file://doc/mvvm/MvvmInfo.md#L30-L51)

### ViewModel数据管理

项目中的数据模型通过SingletonModuleComp进行统一管理：

| 数据类型 | 管理方式 | 生命周期 | 用途 |
|---------|---------|---------|------|
| 游戏状态数据 | VM.add() | 全局 | UI绑定、状态同步 |
| 用户配置数据 | 直接访问 | 持久化 | 设置保存、偏好记录 |
| 实时战斗数据 | 动态更新 | 帧级 | 战斗界面、技能显示 |
| 网络同步数据 | 异步处理 | 会话级 | 云端保存、数据同步 |

**章节来源**
- [MvvmInfo.md](file://doc/mvvm/MvvmInfo.md#L1-L52)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)

## 单例模式架构支柱

### 全局模块管理

SingletonModuleComp作为全局状态管理的核心，实现了以下功能：

```mermaid
classDiagram
class SingletonModuleComp {
+initialize Initialize
+map GameMap
+openid string
+mission any
+guides any
+data any
+fight_hero number
+heros any
+monsters any
+vmdata any
+vmAdd() void
+reset() void
+updateCloudData() boolean
+overrideLocalDataWithRemote() void
+addHero() boolean
+updateFihgtHero() boolean
+updateGold() boolean
}
class smc {
<<singleton>>
}
SingletonModuleComp --> smc : 实例
```

**图表来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)

### 单例模式优势

1. **全局访问**：任何地方都可以通过smc访问全局状态
2. **状态一致性**：确保整个应用的状态统一
3. **内存效率**：避免重复创建相同功能的对象
4. **生命周期管理**：集中管理应用的初始化和销毁

### 数据同步机制

项目实现了云端与本地数据的双向同步：

```mermaid
sequenceDiagram
participant Client as 客户端
participant SMC as SingletonModuleComp
participant Cloud as 微信云API
participant Local as 本地存储
Client->>SMC : updateCloudData()
SMC->>Cloud : save(gameData)
Cloud-->>SMC : 保存结果
SMC-->>Client : 返回状态
Client->>SMC : getCloudData()
SMC->>Cloud : get()
Cloud-->>SMC : 云端数据
SMC->>SMC : overrideLocalDataWithRemote()
SMC-->>Client : 数据同步完成
```

**图表来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L80-L150)

**章节来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)

## 核心组件深度分析

### 主入口组件分析

Main.ts作为应用的主入口，负责整体初始化流程：

```mermaid
flowchart TD
Start([应用启动]) --> Run[run方法]
Run --> InitECS[初始化ECS系统]
InitECS --> InitGUI[初始化GUI]
InitGUI --> InitSMC[初始化SingletonModuleComp]
InitSMC --> Complete([初始化完成])
InitECS --> CreateEntity[创建Initialize实体]
CreateEntity --> AddToSMC[添加到SMC]
InitGUI --> LoadConfig[加载UI配置]
LoadConfig --> SetupGUI[设置GUI框架]
```

**图表来源**
- [Main.ts](file://assets/script/Main.ts#L15-L41) - *更新了ECS系统注册*

### 初始化流程详解

Initialize.ts实现了复杂的游戏初始化流程：

```mermaid
flowchart TD
Init[Initialize实体创建] --> Queue[AsyncQueue队列]
Queue --> Custom[加载自定义资源]
Custom --> Lang[加载语言包]
Lang --> Common[加载公共资源]
Common --> Progress[加载进度界面]
Progress --> Start[开始游戏]
Custom --> Font[加载字体资源]
Font --> Unified[统一数据加载]
Unified --> Cloud{检测微信客户端}
Cloud --> |是| CloudLoad[云端数据加载]
Cloud --> |否| LocalLoad[本地数据加载]
CloudLoad --> Login[微信登录]
Login --> Sync[数据同步]
LocalLoad --> Debug[调试数据]
```

**图表来源**
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L20-L207)

### 游戏状态管理

HeroViewComp展示了复杂的游戏状态管理：

| 状态类型 | 管理方式 | 更新频率 | 用途 |
|---------|---------|---------|------|
| 基础属性 | 直接计算 | 帧级 | 生命值、魔法值、防御力 |
| Buff效果 | 数组管理 | 帧级 | 增益效果、持续时间 |
| 负面状态 | 对象管理 | 帧级 | 减益效果、眩晕、冰冻 |
| 战斗状态 | 状态机 | 事件触发 | 移动、攻击、死亡 |
| 技能效果 | 特殊处理 | 事件触发 | 技能释放、特效显示 |

**章节来源**
- [Main.ts](file://assets/script/Main.ts#L1-L41)
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L1-L780)

## 架构协作机制

### 三大支柱的协同工作

三个架构支柱在项目中形成了紧密的协作关系：

```mermaid
graph TB
subgraph "ECS系统"
ECS_Entities[实体管理]
ECS_Components[组件系统]
ECS_Systems[系统处理]
end
subgraph "MVVM框架"
VM_Manager[ViewModel管理]
UI_Binding[UI绑定]
Event_Handler[事件处理]
end
subgraph "单例模式"
Global_State[全局状态]
Data_Sync[数据同步]
Config_Manage[配置管理]
end
ECS_Entities --> VM_Manager
ECS_Components --> UI_Binding
ECS_Systems --> Event_Handler
VM_Manager --> Global_State
UI_Binding --> Data_Sync
Event_Handler --> Config_Manage
Global_State --> ECS_Entities
Data_Sync --> ECS_Components
Config_Manage --> ECS_Systems
```

### 生命周期管理

项目实现了完整的组件生命周期管理：

```mermaid
stateDiagram-v2
[*] --> Created : 实体创建
Created --> Initialized : 初始化
Initialized --> Active : 激活状态
Active --> Updating : 帧更新
Updating --> Active : 继续运行
Active --> Paused : 暂停状态
Paused --> Active : 恢复运行
Active --> Destroyed : 销毁
Destroyed --> [*]
Initialized --> Error : 初始化失败
Error --> [*] : 清理资源
```

**章节来源**
- [Main.ts](file://assets/script/Main.ts#L15-L41)
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L20-L50)

## 性能优化策略

### ECS性能优化

1. **组件缓存池**：重用组件对象，减少垃圾回收压力
2. **系统批处理**：同一系统的实体批量处理，提高CPU缓存命中率
3. **过滤器优化**：精确的实体筛选，避免不必要的遍历
4. **延迟销毁**：延迟实体销毁，减少频繁的内存分配

### MVVM性能优化

1. **脏检查优化**：智能的变更检测，避免不必要的UI更新
2. **事件节流**：高频事件的防抖处理
3. **组件懒加载**：按需加载UI组件，减少内存占用
4. **绑定优化**：选择性的数据绑定，避免过度监听

### 单例模式优化

1. **延迟初始化**：按需创建单例对象
2. **弱引用管理**：避免循环引用导致的内存泄漏
3. **状态压缩**：定期清理无效状态数据
4. **异步处理**：耗时操作的异步化处理

## 总结

本项目的技术架构通过ECS、MVVM和单例模式三大支柱，构建了一个高度解耦、可扩展的游戏引擎。这种架构设计带来了以下显著优势：

1. **代码可维护性**：清晰的职责分离，便于团队协作和长期维护
2. **系统可扩展性**：模块化设计支持快速功能迭代和扩展
3. **性能优化空间**：多层次的优化策略确保良好的运行性能
4. **开发效率提升**：标准化的开发模式降低学习成本
5. **质量保证**：完善的测试和调试机制确保代码质量

通过这种架构设计，项目不仅能够应对当前的功能需求，还为未来的功能扩展和技术升级奠定了坚实的基础。三大支柱的协同工作使得整个系统既灵活又稳定，为游戏开发提供了强有力的技术支撑。