420 lines
13 KiB
Markdown
420 lines
13 KiB
Markdown
# 核心系统
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts)
|
||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts)
|
||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
|
||
- [BoxSet.ts](file://assets/script/game/common/config/BoxSet.ts)
|
||
- [Main.ts](file://assets/script/Main.ts)
|
||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts)
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||
- [event.md](file://doc/core/common/event.md)
|
||
- [loader.md](file://doc/core/common/loader.md)
|
||
- [storage.md](file://doc/core/common/storage.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目架构概览](#项目架构概览)
|
||
3. [初始化系统](#初始化系统)
|
||
4. [事件系统](#事件系统)
|
||
5. [资源加载系统](#资源加载系统)
|
||
6. [本地存储系统](#本地存储系统)
|
||
7. [碰撞分组配置](#碰撞分组配置)
|
||
8. [系统集成与工作流程](#系统集成与工作流程)
|
||
9. [最佳实践与优化建议](#最佳实践与优化建议)
|
||
10. [总结](#总结)
|
||
|
||
## 简介
|
||
|
||
本游戏采用基于Oops Framework的模块化架构，核心运行系统包含初始化流程、事件系统、资源加载与本地存储四大核心模块。系统通过异步队列管理初始化顺序，使用事件总线实现模块间解耦，采用分层资源管理模式，并提供安全可靠的本地存储机制。
|
||
|
||
## 项目架构概览
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "游戏入口"
|
||
Main[Main.ts]
|
||
Root[Root基类]
|
||
end
|
||
subgraph "初始化系统"
|
||
Init[Initialize.ts]
|
||
Loading[LoadingViewComp.ts]
|
||
end
|
||
subgraph "核心模块"
|
||
SMC[SingletonModuleComp]
|
||
Event[GameEvent.ts]
|
||
Box[BoxSet.ts]
|
||
end
|
||
subgraph "资源管理"
|
||
ResMgr[资源加载器]
|
||
Storage[本地存储]
|
||
Loader[异步队列]
|
||
end
|
||
subgraph "游戏内容"
|
||
Map[GameMap]
|
||
Scene[场景管理]
|
||
end
|
||
Main --> Init
|
||
Init --> Loading
|
||
Init --> SMC
|
||
Loading --> Map
|
||
SMC --> Event
|
||
SMC --> Storage
|
||
Init --> ResMgr
|
||
ResMgr --> Loader
|
||
```
|
||
|
||
**图表来源**
|
||
- [Main.ts](file://assets/script/Main.ts#L1-L41)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207)
|
||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L1-L91)
|
||
|
||
## 初始化系统
|
||
|
||
### Initialize.ts - 游戏启动核心
|
||
|
||
Initialize.ts作为游戏初始化的核心模块，负责管理整个启动流程，采用异步队列模式确保资源按序加载。
|
||
|
||
#### 初始化流程架构
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Main as Main.ts
|
||
participant Init as Initialize
|
||
participant Queue as AsyncQueue
|
||
participant Loading as LoadingViewComp
|
||
participant SMC as SingletonModuleComp
|
||
Main->>Init : 创建Initialize实体
|
||
Init->>Queue : 创建异步队列
|
||
Init->>Queue : 添加loadCustom任务
|
||
Init->>Queue : 添加loadLanguage任务
|
||
Init->>Queue : 添加loadCommon任务
|
||
Init->>Queue : 添加onComplete回调
|
||
Queue->>Queue : 执行队列任务
|
||
Queue->>Loading : 打开加载界面
|
||
Loading->>SMC : 初始化游戏数据
|
||
Loading->>SMC : 加载地图资源
|
||
SMC->>SMC : 完成初始化
|
||
```
|
||
|
||
**图表来源**
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L25-L40)
|
||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L75-L91)
|
||
|
||
#### 核心初始化步骤
|
||
|
||
1. **自定义内容加载**：支持动态加载多语言字体和游戏配置
|
||
2. **语言包加载**：自动检测并设置默认语言
|
||
3. **公共资源加载**：加载游戏必需的基础资源
|
||
4. **加载界面显示**：展示资源加载进度
|
||
|
||
#### 微信客户端适配
|
||
|
||
系统具备智能客户端识别能力，能够根据运行环境选择不同的数据加载策略：
|
||
|
||
- **微信客户端**：连接云端数据库，实现数据实时同步
|
||
- **本地调试**：使用本地预设数据，便于开发调试
|
||
|
||
**章节来源**
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L42-L207)
|
||
|
||
### LoadingViewComp.ts - 启动画面交互
|
||
|
||
LoadingViewComp负责管理游戏启动过程中的视觉反馈和用户体验。
|
||
|
||
#### 加载状态管理
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> 初始化
|
||
初始化 --> 加载自定义资源 : loadCustom()
|
||
加载自定义资源 --> 加载游戏资源 : loadGameRes()
|
||
加载游戏资源 --> 加载完成 : onCompleteCallback()
|
||
加载完成 --> 销毁组件 : remove(LoadingViewComp)
|
||
销毁组件 --> [*]
|
||
加载自定义资源 : 显示"加载JSON数据"
|
||
加载游戏资源 : 显示"加载游戏内容"
|
||
```
|
||
|
||
**图表来源**
|
||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L50-L91)
|
||
|
||
#### 进度监控机制
|
||
|
||
系统提供实时的资源加载进度监控，包括：
|
||
- 当前完成数量
|
||
- 总资源数量
|
||
- 进度百分比计算
|
||
- 多语言提示文本更新
|
||
|
||
**章节来源**
|
||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L1-L91)
|
||
|
||
## 事件系统
|
||
|
||
### GameEvent.ts - 事件枚举定义
|
||
|
||
GameEvent.ts定义了游戏中的所有自定义事件类型，采用枚举方式组织，确保事件名称的一致性和可维护性。
|
||
|
||
#### 事件分类体系
|
||
|
||
| 事件类别 | 事件名称 | 描述 |
|
||
|---------|---------|------|
|
||
| 游戏连接 | GameServerConnected | 游戏服务器连接成功 |
|
||
| 登录认证 | LoginSuccess | 登录成功事件 |
|
||
| 地图移动 | MAP_MOVE_END_LEFT/RIGHT | 地图移动结束事件 |
|
||
| 引导系统 | GuideStart/End/Complete | 引导流程控制事件 |
|
||
| 英雄系统 | UpdateHero/UpdateFightHero | 英雄数据更新事件 |
|
||
| 技能系统 | CastSkill/CastHeroSkill | 技能释放事件 |
|
||
| 战斗系统 | FightStart/Pause/Resume/End | 战斗状态控制事件 |
|
||
| 资源更新 | GOLD_UPDATE/DIAMOND_UPDATE/MEAT_UPDATE | 资源变化事件 |
|
||
|
||
#### 事件总线使用模式
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[事件发布者] --> B[oops.message.on/once]
|
||
B --> C[事件监听器]
|
||
C --> D[业务逻辑处理]
|
||
D --> E[事件响应完成]
|
||
F[事件取消] --> G[oops.message.off]
|
||
G --> H[移除监听器]
|
||
```
|
||
|
||
**图表来源**
|
||
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts#L1-L70)
|
||
- [event.md](file://doc/core/common/event.md#L1-L44)
|
||
|
||
### 事件系统最佳实践
|
||
|
||
1. **持续监听**：适用于长期关注的事件
|
||
2. **一次性监听**：适用于仅需响应一次的事件
|
||
3. **内存管理**：及时取消不再需要的事件监听
|
||
|
||
**章节来源**
|
||
- [event.md](file://doc/core/common/event.md#L1-L44)
|
||
|
||
## 资源加载系统
|
||
|
||
### loader.md - 资源管理最佳实践
|
||
|
||
系统提供了完整的资源管理解决方案，涵盖从加载到释放的全生命周期管理。
|
||
|
||
#### 资源加载模式
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "资源类型"
|
||
A[单个资源]
|
||
B[资源文件夹]
|
||
C[远程资源]
|
||
D[Bundle资源]
|
||
end
|
||
subgraph "加载方式"
|
||
E[同步加载]
|
||
F[异步加载]
|
||
G[进度回调]
|
||
H[完成回调]
|
||
end
|
||
A --> E
|
||
B --> F
|
||
C --> G
|
||
D --> H
|
||
```
|
||
|
||
**图表来源**
|
||
- [loader.md](file://doc/core/common/loader.md#L1-L91)
|
||
|
||
#### 核心API功能
|
||
|
||
1. **远程资源加载**：支持网络图片和音频资源
|
||
2. **Bundle管理**：支持多资源包的版本控制
|
||
3. **进度监控**：提供实时加载进度反馈
|
||
4. **资源释放**：自动清理无用资源，优化内存使用
|
||
|
||
#### 异步加载队列
|
||
|
||
系统采用AsyncQueue实现资源加载的有序执行，确保关键资源优先加载，提升用户体验。
|
||
|
||
**章节来源**
|
||
- [loader.md](file://doc/core/common/loader.md#L1-L91)
|
||
|
||
## 本地存储系统
|
||
|
||
### storage.md - 数据持久化机制
|
||
|
||
本地存储系统提供安全可靠的数据持久化解决方案，支持数据加密和多用户隔离。
|
||
|
||
#### 存储架构设计
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "存储层次"
|
||
A[应用层API]
|
||
B[加密层]
|
||
C[平台层]
|
||
end
|
||
subgraph "存储介质"
|
||
D[Web Storage]
|
||
E[IndexedDB]
|
||
F[File System]
|
||
end
|
||
A --> B
|
||
B --> C
|
||
C --> D
|
||
C --> E
|
||
C --> F
|
||
```
|
||
|
||
**图表来源**
|
||
- [storage.md](file://doc/core/common/storage.md#L1-L39)
|
||
|
||
#### 核心功能特性
|
||
|
||
1. **数据加密**：发布模式自动启用数据加密
|
||
2. **用户隔离**：支持多用户账号数据分离
|
||
3. **跨平台兼容**：统一的API接口适配不同平台
|
||
4. **类型安全**：支持多种数据类型的序列化存储
|
||
|
||
#### 数据操作示例
|
||
|
||
| 操作类型 | API方法 | 功能描述 |
|
||
|---------|---------|----------|
|
||
| 初始化 | `oops.storage.init(key, vi)` | 设置加密密钥 |
|
||
| 用户设置 | `oops.storage.setUser(uid)` | 设置用户标识 |
|
||
| 数据存储 | `oops.storage.set(key, value)` | 保存数据 |
|
||
| 数据读取 | `oops.storage.get(key)` | 获取数据 |
|
||
| 数据删除 | `oops.storage.remove(key)` | 删除数据 |
|
||
| 清空存储 | `oops.storage.clear()` | 清空所有数据 |
|
||
|
||
**章节来源**
|
||
- [storage.md](file://doc/core/common/storage.md#L1-L39)
|
||
|
||
## 碰撞分组配置
|
||
|
||
### BoxSet.ts - 物理碰撞系统
|
||
|
||
BoxSet.ts定义了游戏中的物理碰撞分组，为2D物理引擎提供精确的碰撞检测规则。
|
||
|
||
#### 碰撞分组体系
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "角色分组"
|
||
A[HERO - 英雄]
|
||
B[MONSTER - 怪物]
|
||
C[BOSS - BOSS]
|
||
D[PLAYER - 玩家]
|
||
end
|
||
subgraph "技能分组"
|
||
E[HERO_SKILL - 英雄技能]
|
||
F[MONSTER_SKILL - 怪物技能]
|
||
G[SKILL_TAG - 技能标记]
|
||
end
|
||
subgraph "范围分组"
|
||
H[ATK_RANGE - 攻击范围]
|
||
I[DEFAULT - 默认分组]
|
||
end
|
||
A --> E
|
||
B --> F
|
||
C --> F
|
||
D --> E
|
||
```
|
||
|
||
**图表来源**
|
||
- [BoxSet.ts](file://assets/script/game/common/config/BoxSet.ts#L1-L109)
|
||
|
||
#### 配置参数详解
|
||
|
||
| 参数类别 | 参数名称 | 数值 | 用途 |
|
||
|---------|---------|------|------|
|
||
| 分组掩码 | DEFAULT | 1 | 默认碰撞分组 |
|
||
| 分组掩码 | MONSTER | 2 | 怪物专用分组 |
|
||
| 分组掩码 | HERO | 4 | 英雄专用分组 |
|
||
| 分组掩码 | MONSTER_SKILL | 8 | 怪物技能分组 |
|
||
| 分组掩码 | HERO_SKILL | 16 | 英雄技能分组 |
|
||
| 分组掩码 | PLAYER | 32 | 玩家区域分组 |
|
||
| 分组掩码 | BOSS | 64 | BOSS专用分组 |
|
||
| 地图边界 | LETF_END | -420 | 左边界坐标 |
|
||
| 地图边界 | RIGHT_END | 420 | 右边界坐标 |
|
||
| 地图边界 | HERO_START | -360 | 英雄起始位置 |
|
||
| 地图边界 | MONSTER_START | 360 | 怪物起始位置 |
|
||
| 攻击范围 | ATK_RANGE_X | 150 | 攻击距离X轴 |
|
||
| 移动范围 | MOVE_RANGE_X | 20 | 移动范围X轴 |
|
||
|
||
**章节来源**
|
||
- [BoxSet.ts](file://assets/script/game/common/config/BoxSet.ts#L1-L109)
|
||
|
||
## 系统集成与工作流程
|
||
|
||
### 整体工作流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[Main.ts启动] --> B[Root初始化]
|
||
B --> C[SMC单例创建]
|
||
C --> D[Initialize初始化]
|
||
D --> E[AsyncQueue执行]
|
||
E --> F[资源加载]
|
||
F --> G[LoadingView显示]
|
||
G --> H[数据初始化]
|
||
H --> I[地图加载]
|
||
I --> J[游戏界面打开]
|
||
K[事件系统] --> L[GameEvent监听]
|
||
L --> M[业务逻辑处理]
|
||
N[存储系统] --> O[本地数据读取]
|
||
O --> P[云端数据同步]
|
||
Q[资源系统] --> R[异步加载队列]
|
||
R --> S[进度监控]
|
||
S --> T[资源释放]
|
||
```
|
||
|
||
**图表来源**
|
||
- [Main.ts](file://assets/script/Main.ts#L1-L41)
|
||
- [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207)
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L194)
|
||
|
||
### 数据流管理
|
||
|
||
系统采用单例模式管理全局状态，通过事件驱动实现模块间的松耦合通信。
|
||
|
||
**章节来源**
|
||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L194)
|
||
|
||
## 最佳实践与优化建议
|
||
|
||
### 初始化优化策略
|
||
|
||
1. **并行加载**：利用异步队列实现资源的并行加载
|
||
2. **错误处理**：对加载失败的资源进行优雅降级
|
||
3. **进度反馈**：提供详细的加载进度和状态提示
|
||
4. **内存管理**：及时释放不需要的资源
|
||
|
||
### 事件系统优化
|
||
|
||
1. **命名规范**：使用语义化的事件名称
|
||
2. **监听管理**：及时移除不需要的事件监听器
|
||
3. **参数传递**：合理设计事件参数结构
|
||
4. **性能考虑**：避免在高频事件中执行复杂操作
|
||
|
||
### 资源管理最佳实践
|
||
|
||
1. **预加载策略**：提前加载常用资源
|
||
2. **按需加载**：根据游戏进度动态加载资源
|
||
3. **缓存管理**：合理利用资源缓存机制
|
||
4. **内存监控**：定期检查和释放内存占用
|
||
|
||
### 存储系统安全
|
||
|
||
1. **数据加密**：在生产环境中启用数据加密
|
||
2. **用户隔离**：确保不同用户的存储数据相互独立
|
||
3. **备份策略**：建立数据备份和恢复机制
|
||
4. **权限控制**：限制对敏感数据的访问权限
|
||
|
||
## 总结
|
||
|
||
本游戏的核心运行系统通过模块化设计实现了高度的可维护性和扩展性。初始化系统确保游戏启动的稳定性和效率，事件系统提供了灵活的模块间通信机制，资源管理系统支持复杂的资源加载和管理需求，本地存储系统保障了数据的安全性和持久性。
|
||
|
||
系统采用的异步队列模式、事件驱动架构和单例管理模式，为游戏开发提供了坚实的基础框架。通过合理的配置和优化，这套系统能够支持大型游戏项目的开发需求，同时保持良好的性能表现和用户体验。 |