pixelheros/.qoder/repowiki/zh/content/技术架构/技术架构.md

技术架构

**本文档中引用的文件** - [Main.ts](file://assets/script/Main.ts) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts) - [EcsPositionSystem.ts](file://assets/script/game/common/ecs/position/EcsPositionSystem.ts) - [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts) - [BattleMoveComp.ts](file://assets/script/game/common/ecs/position/BattleMoveComp.ts) - [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts) - [HeroModelComp.ts](file://assets/script/game/hero/HeroModelComp.ts) - [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)

目录

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

引言

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

项目架构概览

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

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
• Initialize.ts

章节来源

• Main.ts
• Initialize.ts

ECS架构支柱

ECS核心概念

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

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

组件系统设计

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

classDiagram
class ecs_Comp {
+reset() void
+canRecycle boolean
+ent Entity
}
class BattleMoveComp {
+direction number
+targetX number
+moving boolean
+reset() void
}
class HeroViewComp {
+status string
+hero_uuid number
+hp number
+mp number
+Attrs any
+BUFFS any
+update(dt) void
}
class HeroModelComp {
+reset() void
}
ecs_Comp <|-- BattleMoveComp
ecs_Comp <|-- HeroViewComp
ecs_Comp <|-- HeroModelComp

图表来源

• BattleMoveComp.ts
• HeroViewComp.ts
• HeroModelComp.ts

系统协作机制

系统通过过滤器机制实现高效的实体管理：

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

图表来源

• BattleMoveSystem.ts
• EcsPositionSystem.ts

ECS解耦优势

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

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

章节来源

• ecs.md
• BattleMoveSystem.ts

MVVM架构支柱

Oops Plugin Framework概述

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

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

双向绑定机制

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

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

ViewModel数据管理

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

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

章节来源

• MvvmInfo.md
• SingletonModuleComp.ts

单例模式架构支柱

全局模块管理

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

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

单例模式优势

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

数据同步机制

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

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

章节来源

• SingletonModuleComp.ts

核心组件深度分析

主入口组件分析

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

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

初始化流程详解

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

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

游戏状态管理

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

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

章节来源

• Main.ts
• Initialize.ts
• HeroViewComp.ts

架构协作机制

三大支柱的协同工作

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

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

生命周期管理

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

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

章节来源

• Main.ts
• Initialize.ts

性能优化策略

ECS性能优化

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

MVVM性能优化

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

单例模式优化

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

总结

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

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

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