20 KiB
20 KiB
初始化系统
**本文档中引用的文件** - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts) - [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts) - [WxCloudApi.ts](file://assets/script/game/wx_clound_client_api/WxCloudApi.ts) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts) - [USAGE.md](file://assets/script/game/wx_clound_client_api/USAGE.md) - [index.js](file://build-templates/wechatgame/cloud_functions/cocos_cloud/index.js) - [config.json](file://assets/resources/config.json)目录
简介
游戏初始化系统是一个基于ECS架构的复杂初始化流程，负责在游戏启动时完成资源加载、数据初始化、界面显示和环境配置等关键任务。该系统采用异步队列机制确保各个初始化步骤按顺序执行，同时支持云端数据加载和本地调试两种模式。
初始化系统的核心目标是：
- 提供流畅的游戏启动体验
- 支持云端数据同步和本地调试
- 实现模块化的初始化流程
- 确保错误处理和性能优化
项目结构
初始化系统的主要文件组织结构如下：
graph TB
subgraph "初始化模块"
A[Initialize.ts<br/>主初始化类]
B[LoadingViewComp.ts<br/>加载界面组件]
end
subgraph "云服务模块"
C[WxCloudApi.ts<br/>微信云API封装]
D[USAGE.md<br/>使用指南]
end
subgraph "共享模块"
E[SingletonModuleComp.ts<br/>单例模块组件]
end
subgraph "配置文件"
F[config.json<br/>配置信息]
G[index.js<br/>云函数实现]
end
A --> B
A --> C
A --> E
C --> G
E --> C
图表来源
章节来源
核心组件
初始化系统由以下核心组件构成：
Initialize 主初始化类
负责协调整个初始化流程，包含四个主要阶段：
- loadCustom: 加载自定义资源和字体
- loadLanguage: 加载多语言包
- loadCommon: 加载公共资源
- onComplete: 完成初始化并显示加载界面
LoadingViewComp 加载界面组件
提供可视化的加载进度反馈，支持多语言提示和进度监控。
WxCloudApi 微信云API
封装微信云开发接口，提供登录、数据存储和获取功能。
SingletonModuleComp 单例模块
管理全局游戏数据和状态，处理云端数据同步。
章节来源
架构概览
初始化系统采用基于ECS架构的设计模式，通过异步队列实现串行任务执行：
sequenceDiagram
participant Game as 游戏引擎
participant Init as Initialize
participant Queue as AsyncQueue
participant View as LoadingViewComp
participant Cloud as WxCloudApi
participant SMC as SingletonModuleComp
Game->>Init : 创建Initialize实例
Init->>Queue : 创建异步队列
Init->>Queue : 添加loadCustom任务
Init->>Queue : 添加loadLanguage任务
Init->>Queue : 添加loadCommon任务
Init->>Queue : 添加onComplete任务
Init->>Queue : 执行queue.play()
Queue->>Init : 执行loadCustom
Init->>Init : 加载字体资源
Init->>Init : 调用loadGameDataUnified
alt 微信客户端
Init->>Cloud : initWxCloudEnv()
Init->>Cloud : WxCloudApi.login()
Cloud-->>Init : 返回云端数据
Init->>SMC : 更新本地数据
else 非微信客户端
Init->>Init : 使用本地调试数据
end
Queue->>Init : 执行loadLanguage
Init->>Init : 设置默认语言
Init->>Init : 加载语言包
Queue->>Init : 执行loadCommon
Init->>Init : 加载公共资源
Queue->>View : 执行onComplete
View->>View : 显示加载界面
View->>View : 开始游戏资源加载
Note over Game,SMC : 初始化流程完成
图表来源
详细组件分析
Initialize 类详细分析
Initialize类是初始化系统的核心控制器，采用ECS实体模式设计：
classDiagram
class Initialize {
+LoadingViewComp LoadingView
+init() void
-loadCustom(queue : AsyncQueue) void
-loadLanguage(queue : AsyncQueue) void
-loadCommon(queue : AsyncQueue) void
-onComplete(queue : AsyncQueue) void
-loadGameDataUnified() Promise~void~
-loadFromCloud() Promise~void~
-loadFromLocalDebug() Promise~void~
-initWxCloudEnv() void
-isWxClient() boolean
}
class AsyncQueue {
+push(task : Function) void
+play() void
+complete : Function
}
class LoadingViewComp {
+data : Object
+reset() void
+start() void
-loadRes() Promise~void~
-loadCustom() void
-loadGameRes() void
-onProgressCallback() void
-onCompleteCallback() void
}
Initialize --> AsyncQueue : 使用
Initialize --> LoadingViewComp : 创建
LoadingViewComp --> SingletonModuleComp : 通信
图表来源
初始化流程详解
初始化过程分为四个关键阶段：
-
loadCustom阶段：加载自定义资源和字体
- 加载多语言对应的字体资源
- 调用统一数据加载流程
- 错误处理：即使失败也继续执行
-
loadLanguage阶段：处理多语言支持
- 检查并设置默认语言（zh）
- 从本地存储读取语言偏好
- 加载对应的语言包资源
-
loadCommon阶段：加载公共资源
- 加载common目录下的所有资源
- 包括游戏必需的基础资源
-
onComplete阶段：完成初始化
- 注册UI回调函数
- 打开加载界面
- 准备进入游戏内容加载
章节来源
加载界面组件分析
LoadingViewComp负责提供可视化的加载体验：
flowchart TD
A[开始加载] --> B[设置提示文本]
B --> C[加载自定义资源]
C --> D[加载游戏资源]
D --> E{加载完成?}
E --> |否| F[更新进度]
F --> G[计算百分比]
G --> H[更新UI显示]
H --> E
E --> |是| I[移除组件]
I --> J[加载地图]
J --> K[打开角色控制界面]
图表来源
加载进度监控机制
加载界面通过以下机制实现实时进度反馈：
- 进度回调：监听资源加载进度事件
- 百分比计算：实时计算并格式化进度百分比
- 多语言支持：根据当前语言显示相应提示
- 资源释放：加载完成后及时释放临时资源
章节来源
云端数据加载机制
初始化系统支持两种数据加载模式：
flowchart TD
A[开始数据加载] --> B{检测运行环境}
B --> |微信客户端| C[使用云端数据]
B --> |非微信客户端| D[使用本地调试数据]
C --> E[初始化微信云环境]
E --> F[调用WxCloudApi.login]
F --> G{登录成功?}
G --> |是| H[获取云端数据]
G --> |否| I[使用本地数据]
H --> J[更新本地数据]
J --> K[覆盖游戏配置]
D --> L[加载本地调试数据]
L --> M[使用默认配置]
I --> N[记录警告日志]
M --> O[继续初始化]
N --> O
K --> O
图表来源
微信云环境初始化
微信云环境的初始化过程包括：
- 环境配置：设置云环境ID
- API初始化：调用微信云SDK初始化
- 错误处理：捕获并记录初始化异常
用户登录流程
用户登录通过WxCloudApi.login()实现：
- 函数调用：调用微信云函数
cocos_cloud - 命令参数：发送
cmd: "login"指令 - 数据验证：检查返回结果的状态码
- 数据覆盖：成功时直接覆盖本地游戏数据
章节来源
单例模块组件
SingletonModuleComp作为全局状态管理器：
classDiagram
class SingletonModuleComp {
+initialize : Initialize
+map : GameMap
+openid : string
+mission : Object
+guides : Array
+current_guide : number
+data : Object
+fight_hero : number
+heros : Array
+monsters : Array
+vmdata : Object
+vmAdd() void
+reset() void
+updateCloudData() Promise~boolean~
+getCloudData() void
+overrideLocalDataWithRemote() void
+getGameDate() Object
+addHero() boolean
+updateFihgtHero() boolean
+updateGold() boolean
+error() void
}
class WxCloudApi {
+init(env : string) void
+login() Promise
+save(gameData : any) Promise
+get() Promise
}
SingletonModuleComp --> WxCloudApi : 使用
SingletonModuleComp --> Initialize : 被引用
图表来源
章节来源
依赖关系分析
初始化系统的依赖关系图展示了各组件间的交互：
graph TB
subgraph "外部依赖"
A[Cocos引擎]
B[Oops框架]
C[微信云开发]
end
subgraph "核心模块"
D[Initialize]
E[LoadingViewComp]
F[WxCloudApi]
G[SingletonModuleComp]
end
subgraph "配置资源"
H[config.json]
I[语言包]
J[游戏资源]
end
A --> D
B --> D
B --> E
B --> G
C --> F
D --> E
D --> F
D --> G
F --> G
H --> D
I --> D
J --> D
图表来源
组件耦合度分析
- Initialize与LoadingViewComp：松耦合，通过UI回调机制通信
- Initialize与WxCloudApi：中等耦合，直接调用API方法
- SingletonModuleComp与其他组件：高耦合，作为全局状态中心
- 各组件与Oops框架：强耦合，依赖框架提供的功能
章节来源
性能考虑
异步队列调度优化
初始化系统采用异步队列机制确保任务按序执行，避免阻塞主线程：
- 串行执行：每个任务完成后才执行下一个
- 错误隔离：单个任务失败不影响整体流程
- 资源管理：及时释放不需要的资源
资源预加载策略
- 字体预加载：优先加载多语言字体
- 公共资源缓存：提前加载常用资源
- 渐进式加载：分阶段加载不同类型的资源
内存管理
- 及时释放：加载完成后立即释放临时资源
- 引用清理：避免循环引用导致内存泄漏
- 组件卸载：完成初始化后移除不必要的组件
故障排除指南
常见问题及解决方案
1. 云环境ID未配置
症状：微信客户端初始化失败，控制台显示云环境初始化错误
原因：WxCloudApi.init()中的cloudEnvId未正确设置
解决方案：
// 修改Initialize.ts中的initWxCloudEnv方法
private initWxCloudEnv() {
try {
// 替换为您的实际云环境ID
const cloudEnvId = "您的云环境ID"; // 必须配置
WxCloudApi.init(cloudEnvId);
console.log("[Initialize]: 微信云环境初始化完成");
} catch (error) {
console.error("[Initialize]: 微信云环境初始化失败:", error);
// 提供降级方案
this.useFallbackMode();
}
}
2. 语言包加载失败
症状：游戏界面显示英文或乱码
原因：语言包资源加载失败或语言文件损坏
解决方案：
private loadLanguage(queue: AsyncQueue) {
queue.push((next: NextFunction, params: any, args: any) => {
try {
let lan = oops.storage.get("language");
if (!lan || lan === "") {
lan = "zh"; // 默认语言
oops.storage.set("language", lan);
}
// 添加语言包加载超时处理
const timeout = setTimeout(() => {
console.warn("[Initialize]: 语言包加载超时，使用默认语言");
oops.language.setLanguage("zh", next);
}, 5000);
oops.language.setLanguage(lan, () => {
clearTimeout(timeout);
next();
});
} catch (error) {
console.error("[Initialize]: 语言包加载失败:", error);
// 使用默认语言
oops.language.setLanguage("zh", next);
}
});
}
3. 云端数据同步失败
症状：游戏数据无法从云端获取，使用默认数据
原因：网络问题或云端服务异常
解决方案：
private async loadFromCloud() {
try {
this.initWxCloudEnv();
// 添加重试机制
let retryCount = 0;
const maxRetries = 3;
while (retryCount < maxRetries) {
try {
const loginResult = await WxCloudApi.login();
if (loginResult.result.code === 200) {
console.log("[Initialize]: 云端登录成功");
this.overrideLocalDataWithRemote(loginResult.result.data);
return;
} else {
console.warn(`[Initialize]: 云端登录失败，尝试次数 ${retryCount + 1}`);
retryCount++;
await this.delay(1000 * retryCount); // 指数退避
}
} catch (error) {
console.error("[Initialize]: 云端数据加载异常:", error);
retryCount++;
await this.delay(1000 * retryCount);
}
}
// 最终使用本地数据
console.warn("[Initialize]: 云端数据加载多次失败，使用本地数据");
this.useLocalDataFallback();
} catch (error) {
console.error("[Initialize]: 云端数据加载最终失败:", error);
this.useLocalDataFallback();
}
}
4. 加载界面显示异常
症状：加载进度不更新或界面显示错误
原因：LoadingViewComp组件初始化失败或数据绑定问题
解决方案：
private onComplete(queue: AsyncQueue) {
queue.complete = () => {
try {
var uic: UICallbacks = {
onAdded: (node: Node, params: any) => {
try {
var comp = node.getComponent(LoadingViewComp) as ecs.Comp;
if (comp) {
this.add(comp);
console.log("[Initialize]: 加载界面组件添加成功");
} else {
console.error("[Initialize]: 加载界面组件获取失败");
this.useAlternativeLoading();
}
} catch (error) {
console.error("[Initialize]: 加载界面组件处理异常:", error);
this.useAlternativeLoading();
}
}
};
// 界面管理 - 打开游戏内容资源加载进度提示界面
oops.gui.open(UIID.Loading, null, uic);
} catch (error) {
console.error("[Initialize]: 加载界面打开失败:", error);
this.useAlternativeLoading();
}
};
}
性能优化建议
1. 资源预加载优化
// 在初始化早期阶段预加载关键资源
private preloadCriticalResources(queue: AsyncQueue) {
queue.push((next: NextFunction, params: any, args: any) => {
// 预加载关键字体和UI资源
const criticalResources = [
"language/font/zh",
"common/ui/loading",
"common/audio/bgm"
];
let loaded = 0;
const total = criticalResources.length;
criticalResources.forEach(resource => {
oops.res.load(resource, () => {
loaded++;
if (loaded === total) {
next();
}
});
});
});
}
2. 并行加载优化
// 对于独立的资源组，可以考虑并行加载
private loadResourcesParallel(queue: AsyncQueue) {
queue.push((next: NextFunction, params: any, args: any) => {
// 并行加载多个资源组
const groups = [
{ name: "fonts", path: "language/font" },
{ name: "ui", path: "common/ui" },
{ name: "audio", path: "common/audio" }
];
let completed = 0;
const total = groups.length;
groups.forEach(group => {
oops.res.loadDir(group.path, () => {
console.log(`[${group.name}] 资源加载完成`);
completed++;
if (completed === total) {
next();
}
});
});
});
}
3. 内存使用监控
// 添加内存使用监控
private monitorMemoryUsage() {
setInterval(() => {
if (typeof performance !== 'undefined' && performance.memory) {
const memory = performance.memory;
console.log(`内存使用情况:
已用: ${(memory.usedJSHeapSize / 1024 / 1024).toFixed(2)}MB
总计: ${(memory.totalJSHeapSize / 1024 / 1024).toFixed(2)}MB
限制: ${(memory.jsHeapSizeLimit / 1024 / 1024).toFixed(2)}MB`);
// 如果内存使用过高，触发垃圾回收
if (memory.usedJSHeapSize > memory.jsHeapSizeLimit * 0.8) {
console.warn("内存使用过高，触发垃圾回收");
if (typeof global !== 'undefined') {
global.gc && global.gc();
}
}
}
}, 5000);
}
结论
游戏初始化系统是一个设计精良的模块化架构，通过ECS模式实现了高度解耦和可扩展性。系统的主要优势包括：
技术优势
- 模块化设计：每个初始化阶段职责明确，便于维护和扩展
- 异步处理：采用异步队列确保流畅的用户体验
- 环境适配：支持云端和本地两种运行环境
- 错误恢复：完善的错误处理和降级机制
架构特点
- ECS集成：充分利用ECS架构的优势
- 组件化：清晰的组件边界和职责划分
- 事件驱动：基于事件的松耦合通信
- 状态管理：集中式的全局状态管理
性能特性
- 渐进式加载：分阶段加载减少首屏时间
- 资源优化：智能的资源管理和释放
- 内存控制：有效的内存使用和垃圾回收
- 并发处理：合理的并行加载策略
扩展性
系统设计充分考虑了未来的扩展需求，可以通过以下方式轻松扩展：
- 新增初始化阶段：通过AsyncQueue.push()添加新任务
- 自定义加载逻辑：继承或组合现有组件
- 多环境支持：通过条件判断支持更多运行环境
- 插件化架构：支持第三方插件集成
初始化系统为游戏开发提供了坚实的基础架构，确保了游戏能够稳定、高效地启动，并为后续的功能扩展奠定了良好的基础。