pan/heros

Files

panw 4235e3b776 refactor(game): 移除已弃用的事件常量

- 删除 UpdateHero 和 UpdateFightHero 事件
- 移除 MISSION_UPDATE 事件常量
- 优化游戏事件枚举定义

2025-10-28 16:15:47 +08:00

14 KiB

Raw Blame History

单例模式管理

**本文档中引用的文件** - [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)

概述

SingletonModuleComp是游戏核心数据容器，采用单例模式设计，作为整个游戏应用的全局状态管理中心。它负责集中管理initialize、map、vmdata、heros等关键对象和状态，通过MVVM数据绑定机制实现视图与数据的同步，支持微信云同步功能，确保游戏数据的一致性和可靠性。

系统架构

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

图表来源

章节来源

SingletonModuleComp核心设计

类结构与职责

SingletonModuleComp继承自ecs.Comp，作为ECS框架中的核心组件，承担以下主要职责：

全局状态管理：维护游戏的核心状态数据
数据持久化：处理本地存储和云端同步
业务逻辑协调：管理英雄、金币、任务等业务数据
事件通信：通过GameEvent分发状态变更事件

核心数据结构

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

数据层次结构

数据类型	字段名	描述	用途
基础状态	`mission`	游戏任务状态	控制游戏流程状态
引导系统	`guides`	引导步骤记录	管理新手引导进度
游戏数据	`data`	基础游戏属性	存储分数、钻石、肉等
英雄管理	`heros`	英雄列表	管理解锁的英雄
战斗配置	`fight_hero`	当前战斗英雄	指定出战英雄
地图数据	`monsters`	怪物配置	关卡怪物数据

章节来源

SingletonModuleComp.ts

初始化流程分析

Main.ts中的启动流程

游戏启动时，Main类的run方法负责初始化SingletonModuleComp实例：

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 : 初始化完成

图表来源

Initialize.ts的初始化过程

Initialize类负责统一的游戏数据加载流程，根据运行环境选择不同的数据源：

flowchart TD
Start([开始初始化]) --> CheckEnv{检查运行环境}
CheckEnv --> |微信客户端| LoadCloud[加载云端数据]
CheckEnv --> |非微信客户端| LoadLocal[加载本地调试数据]
LoadCloud --> InitWX[初始化微信云环境]
InitWX --> WXLogin[微信登录]
WXLogin --> GetCloudData[获取云端数据]
GetCloudData --> OverrideLocal[覆盖本地数据]
LoadLocal --> LoadDebug[加载本地调试数据]
OverrideLocal --> Complete([初始化完成])
LoadDebug --> Complete

图表来源

Initialize.ts

章节来源

MVVM数据绑定机制

ViewModel集成

SingletonModuleComp通过VM.add方法将vmdata注册到ViewModel管理系统：

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

数据绑定示例

绑定类型	监听路径	绑定组件	更新时机
金币显示	`vmdata.gold`	VMLabel	每次金币变更
任务进度	`vmdata.mission_data.coin`	VMProgress	金币变化时
游戏状态	`vmdata.game_over`	VMState	状态切换时
英雄数量	`vmdata.mission_data.hero_num`	VMLabel	英雄加入时

事件驱动更新

系统通过GameEvent实现数据变更的通知机制：

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 : 显示新数值

图表来源

章节来源

云同步与数据管理

微信云API集成

系统集成了WxCloudApi用于云端数据同步：

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 : "包含"

图表来源

数据同步流程

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

数据覆盖策略

系统实现了智能的数据覆盖机制：

数据类型	覆盖条件	回滚策略
openid	存在时覆盖	无
gold	存在时覆盖	撤销变更
heros	存在时覆盖	删除新增英雄
fight_hero	存在时覆盖	恢复原配置

章节来源

单例模式实现

ECS框架集成

SingletonModuleComp通过ECS.register装饰器注册为单例组件：

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

全局访问机制

通过全局变量smc提供便捷的单例访问：

// 全局访问方式
import { smc } from 'SingletonModuleComp';

// 使用示例
smc.updateGold(100);
smc.addHero(5003);

状态一致性保障

单例模式确保：

全局唯一性：整个应用中只有一个实例
状态同步：所有组件访问相同的数据状态
内存效率：避免重复创建和销毁
线程安全：在单线程环境下天然安全

章节来源

数据操作方法

安全的数据修改

系统提供了多层安全保障的数据操作方法：

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

核心数据操作方法

方法名	参数	功能	安全特性
`updateGold`	`gold: number`	增减金币	自动同步失败回滚
`addHero`	`hero_uuid: number`	添加英雄	检查重复，同步失败删除
`updateFihgtHero`	`heroId: number`	设置战斗英雄	微信环境自动同步
`finishGuide`	`index: number`	完成引导步骤	计划中云端存储

错误处理机制

graph LR
subgraph "错误类型"
Network[网络错误]
Sync[同步错误]
Data[数据错误]
Security[安全错误]
end
subgraph "处理策略"
Retry[重试机制]
Rollback[数据回滚]
Notify[用户通知]
Log[错误日志]
end
Network --> Retry
Sync --> Rollback
Data --> Notify
Security --> Log

章节来源

SingletonModuleComp.ts

性能优化与最佳实践

内存管理

延迟初始化：仅在需要时创建子组件
及时清理：通过reset方法清理不必要的数据
弱引用：避免循环引用导致的内存泄漏

数据同步优化

批量操作：合并多个数据变更减少同步次数
增量更新：只传输变更的数据而非全量数据
缓存策略：本地缓存常用数据减少网络请求

MVVM性能优化

路径监听：精确监听必要的数据路径
事件节流：限制频繁的数据变更事件
组件复用：合理使用UI组件的复用机制

最佳实践建议

数据验证：在修改数据前进行有效性检查
错误恢复：实现完善的错误恢复机制
日志记录：记录关键操作的日志便于调试
版本兼容：考虑数据结构的向前兼容性

总结

SingletonModuleComp作为游戏的核心数据容器，通过单例模式确保了全局状态的一致性，结合MVVM数据绑定机制实现了视图与数据的高效同步。其设计充分考虑了移动端游戏的特点，支持微信云同步功能，提供了安全可靠的数据操作方法。

核心优势

全局统一：单例模式保证状态一致性
数据绑定：MVVM机制简化UI开发
云端同步：支持跨设备数据共享
安全可靠：多重验证和回滚机制
易于扩展：模块化设计便于功能扩展

应用价值

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

14 KiB Raw Blame History Unescape Escape

单例模式管理

目录

概述

系统架构

SingletonModuleComp核心设计

类结构与职责

核心数据结构

数据层次结构

初始化流程分析

Main.ts中的启动流程

Initialize.ts的初始化过程

MVVM数据绑定机制

ViewModel集成

数据绑定示例

事件驱动更新

云同步与数据管理

微信云API集成

数据同步流程

数据覆盖策略

单例模式实现

ECS框架集成

全局访问机制

状态一致性保障

数据操作方法

安全的数据修改

核心数据操作方法

错误处理机制

性能优化与最佳实践

内存管理

数据同步优化

MVVM性能优化

最佳实践建议

总结

核心优势

应用价值

14 KiB

Raw Blame History