465 lines
14 KiB
Markdown
465 lines
14 KiB
Markdown
# 单例模式管理
|
||
|
||
<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开发
|
||
- **云端同步**：支持跨设备数据共享
|
||
- **安全可靠**：多重验证和回滚机制
|
||
- **易于扩展**：模块化设计便于功能扩展
|
||
|
||
### 应用价值
|
||
|
||
该设计模式为游戏开发提供了标准化的状态管理解决方案，特别适用于需要云端同步和复杂数据交互的移动端游戏项目。通过合理的架构设计和性能优化，确保了游戏在各种环境下的稳定运行。 |