refactor(game): 移除已弃用的事件常量
- 删除 UpdateHero 和 UpdateFightHero 事件 - 移除 MISSION_UPDATE 事件常量 - 优化游戏事件枚举定义
This commit is contained in:
panw
465
.qoder/repowiki/zh/content/技术架构/单例模式管理.md
Normal file
465
.qoder/repowiki/zh/content/技术架构/单例模式管理.md
Normal file
@@ -0,0 +1,465 @@
|
||||
# 单例模式管理
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||||
- [Main.ts](file://assets/script/Main.ts)
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts)
|
||||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [概述](#概述)
|
||||
2. [系统架构](#系统架构)
|
||||
3. [SingletonModuleComp核心设计](#singletonmodulecompcore设计)
|
||||
4. [初始化流程分析](#初始化流程分析)
|
||||
5. [MVVM数据绑定机制](#mvvm数据绑定机制)
|
||||
6. [云同步与数据管理](#云同步与数据管理)
|
||||
7. [单例模式实现](#单例模式实现)
|
||||
8. [数据操作方法](#数据操作方法)
|
||||
9. [性能优化与最佳实践](#性能优化与最佳实践)
|
||||
10. [总结](#总结)
|
||||
|
||||
## 概述
|
||||
|
||||
SingletonModuleComp是游戏核心数据容器，采用单例模式设计，作为整个游戏应用的全局状态管理中心。它负责集中管理initialize、map、vmdata、heros等关键对象和状态，通过MVVM数据绑定机制实现视图与数据的同步，支持微信云同步功能，确保游戏数据的一致性和可靠性。
|
||||
|
||||
## 系统架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "游戏启动流程"
|
||||
Main[Main.ts] --> Run[run方法]
|
||||
Run --> InitSMC[初始化SMC]
|
||||
InitSMC --> VMAdd[vmAdd绑定]
|
||||
end
|
||||
subgraph "SingletonModuleComp核心"
|
||||
SMC[SingletonModuleComp] --> VMData[vmdata数据层]
|
||||
SMC --> Initialize[initialize模块]
|
||||
SMC --> Map[GameMap]
|
||||
SMC --> Cloud[WxCloudApi]
|
||||
end
|
||||
subgraph "数据流"
|
||||
VMData --> MVVM[MVVM绑定]
|
||||
Cloud --> Sync[云同步]
|
||||
Sync --> Local[本地数据]
|
||||
end
|
||||
subgraph "外部依赖"
|
||||
ECS[ECS框架] --> SMC
|
||||
Oops[Oops框架] --> SMC
|
||||
WX[微信API] --> Cloud
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Main.ts](file://assets/script/Main.ts#L25-L30)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L20-L195)
|
||||
|
||||
**章节来源**
|
||||
- [Main.ts](file://assets/script/Main.ts#L1-L41)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L195)
|
||||
|
||||
## SingletonModuleComp核心设计
|
||||
|
||||
### 类结构与职责
|
||||
|
||||
SingletonModuleComp继承自ecs.Comp，作为ECS框架中的核心组件，承担以下主要职责：
|
||||
|
||||
- **全局状态管理**：维护游戏的核心状态数据
|
||||
- **数据持久化**：处理本地存储和云端同步
|
||||
- **业务逻辑协调**：管理英雄、金币、任务等业务数据
|
||||
- **事件通信**：通过GameEvent分发状态变更事件
|
||||
|
||||
### 核心数据结构
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SingletonModuleComp {
|
||||
+Initialize initialize
|
||||
+GameMap map
|
||||
+string openid
|
||||
+object mission
|
||||
+array guides
|
||||
+number current_guide
|
||||
+object data
|
||||
+number fight_hero
|
||||
+array heros
|
||||
+array monsters
|
||||
+object vmdata
|
||||
+vmAdd() void
|
||||
+reset() void
|
||||
+updateGold(gold) boolean
|
||||
+addHero(hero_uuid) boolean
|
||||
+updateFihgtHero(heroId) boolean
|
||||
+finishGuide(index) void
|
||||
+updateCloudData() boolean
|
||||
+getCloudData() void
|
||||
+overrideLocalDataWithRemote(CloudData) void
|
||||
}
|
||||
class VMData {
|
||||
+boolean game_over
|
||||
+boolean game_pause
|
||||
+object mission_data
|
||||
+number gold
|
||||
}
|
||||
class MissionData {
|
||||
+number mon_num
|
||||
+number hero_num
|
||||
+number wave_time_num
|
||||
+boolean in_fight
|
||||
+number fight_time
|
||||
+number level
|
||||
+number max_mission
|
||||
+number coin
|
||||
}
|
||||
SingletonModuleComp --> VMData : "包含"
|
||||
VMData --> MissionData : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L20-L87)
|
||||
|
||||
### 数据层次结构
|
||||
|
||||
| 数据类型 | 字段名 | 描述 | 用途 |
|
||||
|---------|--------|------|------|
|
||||
| 基础状态 | `mission` | 游戏任务状态 | 控制游戏流程状态 |
|
||||
| 引导系统 | `guides` | 引导步骤记录 | 管理新手引导进度 |
|
||||
| 游戏数据 | `data` | 基础游戏属性 | 存储分数、钻石、肉等 |
|
||||
| 英雄管理 | `heros` | 英雄列表 | 管理解锁的英雄 |
|
||||
| 战斗配置 | `fight_hero` | 当前战斗英雄 | 指定出战英雄 |
|
||||
| 地图数据 | `monsters` | 怪物配置 | 关卡怪物数据 |
|
||||
|
||||
**章节来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L25-L87)
|
||||
|
||||
## 初始化流程分析
|
||||
|
||||
### Main.ts中的启动流程
|
||||
|
||||
游戏启动时，Main类的run方法负责初始化SingletonModuleComp实例：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Main as Main.ts
|
||||
participant ECS as ECS框架
|
||||
participant SMC as SingletonModuleComp
|
||||
participant VM as ViewModel
|
||||
Main->>ECS : 获取Initialize实体
|
||||
Main->>SMC : 设置initialize属性
|
||||
Main->>SMC : 调用vmAdd()
|
||||
SMC->>VM : 注册vmdata到VMManager
|
||||
VM-->>SMC : 绑定完成
|
||||
SMC-->>Main : 初始化完成
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Main.ts](file://assets/script/Main.ts#L25-L30)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L89-L91)
|
||||
|
||||
### Initialize.ts的初始化过程
|
||||
|
||||
Initialize类负责统一的游戏数据加载流程，根据运行环境选择不同的数据源：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始初始化]) --> CheckEnv{检查运行环境}
|
||||
CheckEnv --> |微信客户端| LoadCloud[加载云端数据]
|
||||
CheckEnv --> |非微信客户端| LoadLocal[加载本地调试数据]
|
||||
LoadCloud --> InitWX[初始化微信云环境]
|
||||
InitWX --> WXLogin[微信登录]
|
||||
WXLogin --> GetCloudData[获取云端数据]
|
||||
GetCloudData --> OverrideLocal[覆盖本地数据]
|
||||
LoadLocal --> LoadDebug[加载本地调试数据]
|
||||
OverrideLocal --> Complete([初始化完成])
|
||||
LoadDebug --> Complete
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L85-L120)
|
||||
|
||||
**章节来源**
|
||||
- [Main.ts](file://assets/script/Main.ts#L25-L30)
|
||||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L85-L120)
|
||||
|
||||
## MVVM数据绑定机制
|
||||
|
||||
### ViewModel集成
|
||||
|
||||
SingletonModuleComp通过VM.add方法将vmdata注册到ViewModel管理系统：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "MVVM架构"
|
||||
VMData[vmdata对象] --> VMManager[VMManager]
|
||||
VMManager --> VMBase[VMBase组件]
|
||||
VMBase --> UI[UI组件]
|
||||
end
|
||||
subgraph "绑定类型"
|
||||
VMCustom[VMCustom] --> Label[cc.Label]
|
||||
VMProgress[VMProgress] --> ProgressBar[cc.ProgressBar]
|
||||
VMState[VMState] --> NodeState[节点状态]
|
||||
end
|
||||
VMBase --> VMCustom
|
||||
VMBase --> VMProgress
|
||||
VMBase --> VMState
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L89-L91)
|
||||
|
||||
### 数据绑定示例
|
||||
|
||||
| 绑定类型 | 监听路径 | 绑定组件 | 更新时机 |
|
||||
|---------|----------|----------|----------|
|
||||
| 金币显示 | `vmdata.gold` | VMLabel | 每次金币变更 |
|
||||
| 任务进度 | `vmdata.mission_data.coin` | VMProgress | 金币变化时 |
|
||||
| 游戏状态 | `vmdata.game_over` | VMState | 状态切换时 |
|
||||
| 英雄数量 | `vmdata.mission_data.hero_num` | VMLabel | 英雄加入时 |
|
||||
|
||||
### 事件驱动更新
|
||||
|
||||
系统通过GameEvent实现数据变更的通知机制：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户操作
|
||||
participant SMC as SingletonModuleComp
|
||||
participant VM as ViewModel
|
||||
participant UI as UI组件
|
||||
User->>SMC : updateGold(100)
|
||||
SMC->>SMC : 修改vmdata.gold
|
||||
SMC->>VM : dispatchEvent(GOLD_UPDATE)
|
||||
VM->>UI : 更新绑定组件
|
||||
UI-->>User : 显示新数值
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L175-L185)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L65-L66)
|
||||
|
||||
**章节来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L89-L91)
|
||||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L65-L66)
|
||||
|
||||
## 云同步与数据管理
|
||||
|
||||
### 微信云API集成
|
||||
|
||||
系统集成了WxCloudApi用于云端数据同步：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class WxCloudApi {
|
||||
+init(env) void
|
||||
+login() Promise
|
||||
+save(gameData) Promise
|
||||
+get() Promise
|
||||
}
|
||||
class CloudData {
|
||||
+string openid
|
||||
+GameDate data
|
||||
}
|
||||
class GameDate {
|
||||
+number gold
|
||||
+any heros
|
||||
+number fight_hero
|
||||
}
|
||||
WxCloudApi --> CloudData : "处理"
|
||||
CloudData --> GameDate : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts#L1-L94)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L11-L18)
|
||||
|
||||
### 数据同步流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant SMC as SingletonModuleComp
|
||||
participant WX as WxCloudApi
|
||||
participant Cloud as 微信云数据库
|
||||
SMC->>WX : updateCloudData()
|
||||
WX->>Cloud : save(gameData)
|
||||
Cloud-->>WX : 保存结果
|
||||
WX-->>SMC : 返回状态
|
||||
alt 同步成功
|
||||
SMC->>SMC : 继续业务逻辑
|
||||
else 同步失败
|
||||
SMC->>SMC : 回滚操作
|
||||
SMC->>SMC : 显示错误提示
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L93-L118)
|
||||
|
||||
### 数据覆盖策略
|
||||
|
||||
系统实现了智能的数据覆盖机制：
|
||||
|
||||
| 数据类型 | 覆盖条件 | 回滚策略 |
|
||||
|---------|----------|----------|
|
||||
| openid | 存在时覆盖 | 无 |
|
||||
| gold | 存在时覆盖 | 撤销变更 |
|
||||
| heros | 存在时覆盖 | 删除新增英雄 |
|
||||
| fight_hero | 存在时覆盖 | 恢复原配置 |
|
||||
|
||||
**章节来源**
|
||||
- [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts#L1-L94)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L93-L118)
|
||||
|
||||
## 单例模式实现
|
||||
|
||||
### ECS框架集成
|
||||
|
||||
SingletonModuleComp通过ECS.register装饰器注册为单例组件：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "ECS生命周期"
|
||||
Register[ecs.register] --> Create[创建实例]
|
||||
Create --> Get[ecs.getSingleton]
|
||||
Get --> Use[全局使用]
|
||||
end
|
||||
subgraph "单例保证"
|
||||
Instance[SingletonInstance] --> GlobalVar[smc全局变量]
|
||||
GlobalVar --> Consistency[状态一致性]
|
||||
end
|
||||
Register --> Instance
|
||||
Create --> Instance
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L19-L20)
|
||||
|
||||
### 全局访问机制
|
||||
|
||||
通过全局变量smc提供便捷的单例访问：
|
||||
|
||||
```typescript
|
||||
// 全局访问方式
|
||||
import { smc } from 'SingletonModuleComp';
|
||||
|
||||
// 使用示例
|
||||
smc.updateGold(100);
|
||||
smc.addHero(5003);
|
||||
```
|
||||
|
||||
### 状态一致性保障
|
||||
|
||||
单例模式确保：
|
||||
- **全局唯一性**：整个应用中只有一个实例
|
||||
- **状态同步**：所有组件访问相同的数据状态
|
||||
- **内存效率**：避免重复创建和销毁
|
||||
- **线程安全**：在单线程环境下天然安全
|
||||
|
||||
**章节来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L19-L20)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L195)
|
||||
|
||||
## 数据操作方法
|
||||
|
||||
### 安全的数据修改
|
||||
|
||||
系统提供了多层安全保障的数据操作方法：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Operation[数据操作请求] --> Validate{验证操作}
|
||||
Validate --> |有效| LocalUpdate[本地更新]
|
||||
Validate --> |无效| Reject[拒绝操作]
|
||||
LocalUpdate --> CheckWX{微信环境?}
|
||||
CheckWX --> |是| CloudSync[云端同步]
|
||||
CheckWX --> |否| DispatchEvent[分发事件]
|
||||
CloudSync --> SyncResult{同步结果}
|
||||
SyncResult --> |成功| DispatchEvent
|
||||
SyncResult --> |失败| Rollback[回滚操作]
|
||||
Rollback --> ErrorMsg[错误提示]
|
||||
DispatchEvent --> Complete[操作完成]
|
||||
Reject --> ErrorMsg
|
||||
ErrorMsg --> Complete
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L120-L194)
|
||||
|
||||
### 核心数据操作方法
|
||||
|
||||
| 方法名 | 参数 | 功能 | 安全特性 |
|
||||
|-------|------|------|----------|
|
||||
| `updateGold` | `gold: number` | 增减金币 | 自动同步失败回滚 |
|
||||
| `addHero` | `hero_uuid: number` | 添加英雄 | 检查重复，同步失败删除 |
|
||||
| `updateFihgtHero` | `heroId: number` | 设置战斗英雄 | 微信环境自动同步 |
|
||||
| `finishGuide` | `index: number` | 完成引导步骤 | 计划中云端存储 |
|
||||
|
||||
### 错误处理机制
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "错误类型"
|
||||
Network[网络错误]
|
||||
Sync[同步错误]
|
||||
Data[数据错误]
|
||||
Security[安全错误]
|
||||
end
|
||||
subgraph "处理策略"
|
||||
Retry[重试机制]
|
||||
Rollback[数据回滚]
|
||||
Notify[用户通知]
|
||||
Log[错误日志]
|
||||
end
|
||||
Network --> Retry
|
||||
Sync --> Rollback
|
||||
Data --> Notify
|
||||
Security --> Log
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L120-L194)
|
||||
|
||||
## 性能优化与最佳实践
|
||||
|
||||
### 内存管理
|
||||
|
||||
- **延迟初始化**：仅在需要时创建子组件
|
||||
- **及时清理**：通过reset方法清理不必要的数据
|
||||
- **弱引用**：避免循环引用导致的内存泄漏
|
||||
|
||||
### 数据同步优化
|
||||
|
||||
- **批量操作**：合并多个数据变更减少同步次数
|
||||
- **增量更新**：只传输变更的数据而非全量数据
|
||||
- **缓存策略**：本地缓存常用数据减少网络请求
|
||||
|
||||
### MVVM性能优化
|
||||
|
||||
- **路径监听**：精确监听必要的数据路径
|
||||
- **事件节流**：限制频繁的数据变更事件
|
||||
- **组件复用**：合理使用UI组件的复用机制
|
||||
|
||||
### 最佳实践建议
|
||||
|
||||
1. **数据验证**：在修改数据前进行有效性检查
|
||||
2. **错误恢复**：实现完善的错误恢复机制
|
||||
3. **日志记录**：记录关键操作的日志便于调试
|
||||
4. **版本兼容**：考虑数据结构的向前兼容性
|
||||
|
||||
## 总结
|
||||
|
||||
SingletonModuleComp作为游戏的核心数据容器，通过单例模式确保了全局状态的一致性，结合MVVM数据绑定机制实现了视图与数据的高效同步。其设计充分考虑了移动端游戏的特点，支持微信云同步功能，提供了安全可靠的数据操作方法。
|
||||
|
||||
### 核心优势
|
||||
|
||||
- **全局统一**：单例模式保证状态一致性
|
||||
- **数据绑定**：MVVM机制简化UI开发
|
||||
- **云端同步**：支持跨设备数据共享
|
||||
- **安全可靠**：多重验证和回滚机制
|
||||
- **易于扩展**：模块化设计便于功能扩展
|
||||
|
||||
### 应用价值
|
||||
|
||||
该设计模式为游戏开发提供了标准化的状态管理解决方案，特别适用于需要云端同步和复杂数据交互的移动端游戏项目。通过合理的架构设计和性能优化，确保了游戏在各种环境下的稳定运行。
|
||||
Reference in New Issue
Block a user