# 核心系统

<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)
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts) - *新增怪物类型配置与属性倍率*
- [MissionMonComp.ts](file://assets/script/game/hero/Mon.ts) - *更新怪物生成逻辑*
- [EBusComp.ts](file://assets/script/game/hero/EBusComp.ts) - *新增事件总线组件，基于ECS框架重构*
</cite>

## 更新摘要
**变更内容**
- 新增怪物类型系统，支持普通/精英/Boss三种类型
- 添加怪物属性倍率配置，不同类型的怪物具有差异化属性
- 更新关卡生成逻辑，支持程序化生成不同类型的怪物组合
- 新增基于ECS框架的事件总线组件(EBusComp)，重构角色视图数据逻辑
- 增强资源引用追踪，添加新修改文件的来源标注

## 目录
1. [简介](#简介)
2. [项目架构概览](#项目架构概览)
3. [初始化系统](#初始化系统)
4. [事件系统](#事件系统)
5. [资源加载系统](#资源加载系统)
6. [本地存储系统](#本地存储系统)
7. [碰撞分组配置](#碰撞分组配置)
8. [怪物生成系统](#怪物生成系统)
9. [系统集成与工作流程](#系统集成与工作流程)
10. [最佳实践与优化建议](#最佳实践与优化建议)
11. [总结](#总结)

## 简介

本游戏采用基于Oops Framework的模块化架构，核心运行系统包含初始化流程、事件系统、资源加载与本地存储四大核心模块。系统通过异步队列管理初始化顺序，使用事件总线实现模块间解耦，采用分层资源管理模式，并提供安全可靠的本地存储机制。新增的怪物生成系统支持多种怪物类型和差异化属性配置。基于ECS框架重构了角色视图的数据逻辑，引入了EBusComp事件总线组件，提升了系统的可维护性和扩展性。

## 项目架构概览

```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]
Monster[怪物生成系统]
Scene[场景管理]
end
subgraph "ECS框架"
EBus[EBusComp]
Hero[Hero组件系统]
end
Main --> Init
Init --> Loading
Init --> SMC
Loading --> Map
SMC --> Event
SMC --> Storage
Init --> ResMgr
ResMgr --> Loader
Map --> Monster
Hero --> EBus
```

**图表来源**
- [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)
- [EBusComp.ts](file://assets/script/game/hero/EBusComp.ts#L6-L89)

## 初始化系统

### 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)

### EBusComp - 基于ECS的事件总线组件

#### EBusComp架构设计

EBusComp是基于ECS框架重构的事件总线组件，为角色视图和数据逻辑提供高效的通信机制。

```mermaid
classDiagram
class EBusComp {
-_eventTarget : EventTarget
+emit(event : string, data? : any) : void
+on(event : string, listener : Function, object? : any) : void
+off(event? : string, callback? : Function, target? : any) : void
+once(event : string, callback : Function, target? : any) : void
+targetOff(target : any) : void
+reset() : void
}
class EventTarget {
+emit(event : string, data? : any) : void
+on(event : string, callback : Function, target? : any) : void
+off(event : string, callback : Function, target? : any) : void
+once(event : string, callback : Function, target? : any) : void
+targetOff(target : any) : void
}
EBusComp --> EventTarget : 使用
```

**图表来源**
- [EBusComp.ts](file://assets/script/game/hero/EBusComp.ts#L6-L89)

#### 核心功能特性

1. **发布订阅模式**：提供标准的事件发布(emit)和订阅(on/once)接口
2. **灵活的取消订阅**：支持多种取消订阅方式
   - 无参调用：清理本节点所有监听
   - 仅提供事件名：清理该事件名下所有回调
   - 完整参数：精确移除指定回调
3. **内存管理**：在reset方法中自动清理所有事件监听，防止内存泄漏
4. **ECS集成**：通过@ecs.register装饰器注册为ECS组件，实现框架级集成

#### 使用示例

```typescript
// 发布事件
this.entity.get(EBusComp).emit(GameEvent.HeroLvUp, { level: 5 });

// 订阅事件
this.entity.get(EBusComp).on(GameEvent.HeroLvUp, this.onHeroLevelUp, this);

// 订阅一次性事件
this.entity.get(EBusComp).once(GameEvent.MissionComplete, this.onMissionComplete, this);

// 取消订阅
this.entity.get(EBusComp).off(GameEvent.HeroLvUp, this.onHeroLevelUp, this);
```

**章节来源**
- [EBusComp.ts](file://assets/script/game/hero/EBusComp.ts#L6-L89)

### 事件系统最佳实践

1. **持续监听**：适用于长期关注的事件
2. **一次性监听**：适用于仅需响应一次的事件
3. **内存管理**：及时取消不再需要的事件监听
4. **ECS组件化**：利用EBusComp实现组件间的松耦合通信

**章节来源**
- [event.md](file://doc/core/common/event.md#L1-L44)
- [EBusComp.ts](file://assets/script/game/hero/EBusComp.ts#L6-L89)

## 资源加载系统

### 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)

## 怪物生成系统

### RogueConfig.ts - 怪物类型与属性配置

RogueConfig.ts重构了怪物生成逻辑，支持多种怪物类型和差异化属性配置。

#### 怪物类型枚举

```typescript
export enum MonType {  
    NORMAL = 0,  // 普通怪物
    ELITE = 1,   // 精英怪物  
    BOSS = 2     // BOSS怪物
}
```

**章节来源**
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts#L21-L23)

#### 怪物属性倍率配置

不同类型的怪物具有不同的属性倍率，通过MonAttrSet配置：

```mermaid
graph LR
subgraph "属性倍率"
A[普通怪物] --> |HP_MAX:1.1| B[生命值+10%]
A --> |AP:1.05| C[攻击力+5%]
D[精英怪物] --> |HP_MAX:2| E[生命值+100%]
D --> |AP:1.1| F[攻击力+10%]
G[BOSS怪物] --> |HP_MAX:5| H[生命值+400%]
G --> |AP:2| I[攻击力+100%]
end
```

**图表来源**
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts#L69-L73)

#### 属性计算函数

```typescript
export const getMonAttr=(lv:number,uuid:number,MonType:MonType)=>{
    let mon=HeroInfo[uuid]
    let hp=mon.hp*lv*MonAttrSet[MonType].HP_MAX
    let mp=mon.mp*lv*MonAttrSet[MonType].MP
    let ap=mon.ap*lv*MonAttrSet[MonType].AP
    let map=mon.map*lv*MonAttrSet[MonType].MAP
    let def=mon.def*lv*MonAttrSet[MonType].DEF
    let mdef=mon.mdef*lv*MonAttrSet[MonType].MDEF
    return {hp:hp,mp:mp,ap:ap,map:map,def:def,mdef:mdef}
}
```

**章节来源**
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts#L79-L88)

### MissionMonComp.ts - 关卡怪物生成

MissionMonComp负责根据关卡配置生成相应的怪物。

#### 关卡配置生成逻辑

```mermaid
flowchart TD
A[开始生成怪物] --> B{是否为Boss关卡?}
B --> |是| C[添加Boss怪物]
B --> |否| D{是否为精英关卡?}
D --> |是| E[添加精英怪物]
D --> |否| F[添加普通怪物]
C --> G[减少普通怪物数量]
E --> H[减少普通怪物数量]
F --> I[按基础数量生成]
G --> J[生成额外怪物?]
H --> J
I --> J
J --> K[返回怪物配置数组]
```

**图表来源**
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts#L95-L173)

#### 怪物生成流程

1. **关卡类型判断**：根据关卡编号判断是否为Boss或精英关卡
2. **特殊怪物添加**：Boss关卡添加Boss怪物，精英关卡添加精英怪物
3. **普通怪物生成**：根据剩余数量生成普通怪物
4. **额外怪物**：有一定概率生成额外怪物

**章节来源**
- [MissionMonComp.ts](file://assets/script/game/map/MissionMonComp.ts#L15-L199)

#### 代码示例：获取关卡怪物配置

```typescript
// 根据波次生成怪物配置
export function getStageMonConfigs(stage: number): IMonsConfig[] {
    const monsterConfigs: IMonsConfig[] = [];
    
    // 判断是否为Boss波次
    const isBossStage = BossStage.includes(stage);
    
    // 如果是Boss波次，增加一个Boss怪物
    if (isBossStage) {
        const bossUUID = BossMons[Math.floor(Math.random() * BossMons.length)] || 5201;
        monsterConfigs.push({
            uuid: bossUUID,
            buff: [],
            level: stage,
            monType: MonType.BOSS
        });
    }
    
    return monsterConfigs;
}
```

**章节来源**
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts#L95-L173)

## 系统集成与工作流程

### 整体工作流程

```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[资源释放]
U[怪物系统] --> V[RogueConfig配置]
V --> W[MissionMonComp生成]
W --> X[属性计算]
Y[ECS框架] --> Z[EBusComp事件总线]
Z --> AA[组件间通信]
```

**图表来源**
- [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)
- [RogueConfig.ts](file://assets/script/game/map/RogueConfig.ts#L0-L178)
- [EBusComp.ts](file://assets/script/game/hero/EBusComp.ts#L6-L89)

### 数据流管理

系统采用单例模式管理全局状态，通过事件驱动实现模块间的松耦合通信。

**章节来源**
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L1-L194)

## 最佳实践与优化建议

### 初始化优化策略

1. **并行加载**：利用异步队列实现资源的并行加载
2. **错误处理**：对加载失败的资源进行优雅降级
3. **进度反馈**：提供详细的加载进度和状态提示
4. **内存管理**：及时释放不需要的资源

### 事件系统优化

1. **命名规范**：使用语义化的事件名称
2. **监听管理**：及时移除不需要的事件监听器
3. **参数传递**：合理设计事件参数结构
4. **性能考虑**：避免在高频事件中执行复杂操作
5. **ECS集成**：充分利用EBusComp组件实现高效的组件间通信

### 资源管理最佳实践

1. **预加载策略**：提前加载常用资源
2. **按需加载**：根据游戏进度动态加载资源
3. **缓存管理**：合理利用资源缓存机制
4. **内存监控**：定期检查和释放内存占用

### 存储系统安全

1. **数据加密**：在生产环境中启用数据加密
2. **用户隔离**：确保不同用户的存储数据相互独立
3. **备份策略**：建立数据备份和恢复机制
4. **权限控制**：限制对敏感数据的访问权限

### 怪物系统优化

1. **类型区分**：合理配置普通、精英、Boss怪物的比例
2. **属性平衡**：通过MonAttrSet调整不同类型怪物的属性倍率
3. **关卡设计**：结合关卡编号动态调整怪物配置
4. **性能优化**：批量生成怪物，减少频繁的资源加载

## 总结

本游戏的核心运行系统通过模块化设计实现了高度的可维护性和扩展性。初始化系统确保游戏启动的稳定性和效率，事件系统提供了灵活的模块间通信机制，资源管理系统支持复杂的资源加载和管理需求，本地存储系统保障了数据的安全性和持久性。

新增的怪物生成系统通过RogueConfig.ts和MissionMonComp.ts实现了程序化的怪物生成逻辑，支持普通、精英、BOSS三种怪物类型，并通过属性倍率配置实现了差异化的设计。系统采用的异步队列模式、事件驱动架构和单例管理模式，为游戏开发提供了坚实的基础框架。

特别值得注意的是，基于ECS框架重构了角色视图的数据逻辑，引入了EBusComp事件总线组件。这一改进不仅提升了系统的可维护性和扩展性，还实现了组件间的松耦合通信。EBusComp组件提供了标准的发布订阅接口，支持灵活的事件管理和内存清理机制，为游戏的长期发展奠定了良好的基础。

通过合理的配置和优化，这套系统能够支持大型游戏项目的开发需求，同时保持良好的性能表现和用户体验。