# 单例模式管理

<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开发
- **云端同步**：支持跨设备数据共享
- **安全可靠**：多重验证和回滚机制
- **易于扩展**：模块化设计便于功能扩展

### 应用价值

该设计模式为游戏开发提供了标准化的状态管理解决方案，特别适用于需要云端同步和复杂数据交互的移动端游戏项目。通过合理的架构设计和性能优化，确保了游戏在各种环境下的稳定运行。