refactor(game): 移除已弃用的事件常量
- 删除 UpdateHero 和 UpdateFightHero 事件 - 移除 MISSION_UPDATE 事件常量 - 优化游戏事件枚举定义
This commit is contained in:
panw
503
.qoder/repowiki/zh/content/地图系统/地图模型.md
Normal file
503
.qoder/repowiki/zh/content/地图系统/地图模型.md
Normal file
@@ -0,0 +1,503 @@
|
||||
# 地图模型
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts)
|
||||
- [map.json](file://assets/resources/config/map/map.json)
|
||||
- [map_delivery.json](file://assets/resources/config/map/map_delivery.json)
|
||||
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts)
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
|
||||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [数据结构分析](#数据结构分析)
|
||||
7. [ECS初始化流程](#ecs初始化流程)
|
||||
8. [地图跳转逻辑](#地图跳转逻辑)
|
||||
9. [数据驱动设计](#数据驱动设计)
|
||||
10. [最佳实践](#最佳实践)
|
||||
11. [总结](#总结)
|
||||
|
||||
## 简介
|
||||
|
||||
MapModelComp组件是Cocos游戏项目中地图系统的核心数据层组件，采用ECS（Entity-Component-System）架构模式设计。该组件负责管理地图资源路径、关卡配置及地图跳转逻辑，为整个地图系统提供数据支撑和状态管理功能。
|
||||
|
||||
地图系统基于两个关键的JSON配置文件：
|
||||
- `map.json`：存储地图基本信息（ID、名称、可跳转关卡）
|
||||
- `map_delivery.json`：存储地图连接点、目标地图和出生点信息
|
||||
|
||||
## 项目结构
|
||||
|
||||
地图系统的文件组织遵循清晰的分层架构：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "地图系统架构"
|
||||
A[MapModelComp.ts<br/>数据模型组件] --> B[GameMap.ts<br/>游戏地图实体]
|
||||
B --> C[MapViewComp.ts<br/>视图组件]
|
||||
C --> D[MapViewScene.ts<br/>场景逻辑]
|
||||
E[map.json<br/>地图配置] --> A
|
||||
F[map_delivery.json<br/>连接点配置] --> A
|
||||
G[SingletonModuleComp.ts<br/>单例模块] --> B
|
||||
H[LoadingViewComp.ts<br/>加载界面] --> B
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L1-L43)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L1-L36)
|
||||
|
||||
**章节来源**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L1-L43)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L1-L36)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### MapModelComp - 地图模型组件
|
||||
|
||||
MapModelComp是地图系统的核心数据组件，继承自ECS框架的ecs.Comp基类，负责维护地图的基本状态和资源配置。
|
||||
|
||||
#### 主要属性
|
||||
|
||||
| 属性名 | 类型 | 默认值 | 描述 |
|
||||
|--------|------|--------|------|
|
||||
| id | number | 1 | 初始地图编号，标识当前激活的地图 |
|
||||
| resPrefab | string | "game/map/map_rpg" | 地图显示预制体资源路径 |
|
||||
|
||||
#### 设计特点
|
||||
|
||||
1. **数据驱动**：所有地图配置通过外部JSON文件管理
|
||||
2. **资源管理**：集中管理地图相关的资源路径
|
||||
3. **状态控制**：维护当前地图的状态信息
|
||||
4. **扩展性**：预留了资源获取方法的注释，支持动态资源加载
|
||||
|
||||
**章节来源**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L9-L43)
|
||||
|
||||
### GameMap - 游戏地图实体
|
||||
|
||||
GameMap继承自ecs.Entity，是地图系统的主实体，负责地图的整体生命周期管理和资源加载。
|
||||
|
||||
#### 核心功能
|
||||
|
||||
1. **组件初始化**：自动添加MapModelComp组件
|
||||
2. **资源加载**：异步加载地图显示资源
|
||||
3. **场景管理**：协调地图视图和场景逻辑
|
||||
|
||||
**章节来源**
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L14-L36)
|
||||
|
||||
## 架构概览
|
||||
|
||||
地图系统采用经典的ECS架构模式，实现了数据与行为的分离：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MapModelComp {
|
||||
+number id
|
||||
+string resPrefab
|
||||
+reset() void
|
||||
}
|
||||
class GameMap {
|
||||
+MapModelComp MapModel
|
||||
+MapViewComp MapView
|
||||
+init() void
|
||||
+load() void
|
||||
}
|
||||
class MapViewComp {
|
||||
+MapViewScene scene
|
||||
+Timer game_timer
|
||||
+onLoad() void
|
||||
+start() void
|
||||
+load_data() void
|
||||
+update(dt) void
|
||||
}
|
||||
class MapViewScene {
|
||||
+Camera camera
|
||||
+Node layer
|
||||
+MapLayer mapLayer
|
||||
+EntityLayer entityLayer
|
||||
+SkillLayer SkillLayer
|
||||
+Vec2 ratio
|
||||
+init() void
|
||||
+update(dt) void
|
||||
}
|
||||
class SingletonModuleComp {
|
||||
+GameMap map
|
||||
+number fight_hero
|
||||
+any heros
|
||||
+updateFihgtHero(id) void
|
||||
+addHero(uuid) void
|
||||
}
|
||||
GameMap --> MapModelComp : "包含"
|
||||
GameMap --> MapViewComp : "包含"
|
||||
MapViewComp --> MapViewScene : "使用"
|
||||
SingletonModuleComp --> GameMap : "管理"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L9-L43)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L14-L36)
|
||||
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts#L14-L45)
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L17-L77)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### MapModelComp组件深度分析
|
||||
|
||||
#### 组件注册与继承
|
||||
|
||||
MapModelComp通过`@ecs.register('MapModel')`装饰器注册到ECS系统中，继承自ecs.Comp基类，具备以下特性：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant ECS as "ECS系统"
|
||||
participant Comp as "MapModelComp"
|
||||
participant Entity as "GameMap实体"
|
||||
ECS->>Comp : 注册组件
|
||||
Entity->>Comp : 创建实例
|
||||
Comp->>Comp : 初始化默认属性
|
||||
Entity->>Comp : 添加到实体
|
||||
Comp->>ECS : 准备就绪
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L8-L9)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L20-L22)
|
||||
|
||||
#### 资源管理策略
|
||||
|
||||
组件提供了灵活的资源管理机制：
|
||||
|
||||
1. **预制体资源**：`resPrefab`属性指向地图显示预制体
|
||||
2. **注释方法**：预留了多种资源获取方法（迷你地图、瓦片、数据资源）
|
||||
3. **默认配置**：提供合理的默认值，确保系统正常运行
|
||||
|
||||
#### 生命周期管理
|
||||
|
||||
reset()方法为空实现，为未来的扩展预留空间。
|
||||
|
||||
**章节来源**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L9-L43)
|
||||
|
||||
### GameMap实体分析
|
||||
|
||||
#### 实体生命周期
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[GameMap创建] --> B[init方法调用]
|
||||
B --> C[添加MapModelComp组件]
|
||||
C --> D[load方法调用]
|
||||
D --> E[异步加载资源]
|
||||
E --> F[实例化预制体]
|
||||
F --> G[添加MapView组件]
|
||||
G --> H[地图加载完成]
|
||||
E --> I[错误处理]
|
||||
I --> J[控制台输出错误]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L20-L36)
|
||||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L36-L42)
|
||||
|
||||
#### 资源加载机制
|
||||
|
||||
load()方法实现了异步资源加载，包括：
|
||||
1. **资源验证**：检查加载结果
|
||||
2. **实例化**：创建地图实例
|
||||
3. **层级设置**：设置父节点关系
|
||||
4. **组件添加**：添加地图视图组件
|
||||
|
||||
**章节来源**
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L24-L36)
|
||||
|
||||
### 地图视图系统
|
||||
|
||||
#### 组件层次结构
|
||||
|
||||
MapViewComp和MapViewScene构成了完整的地图视图系统：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[MapViewComp] --> B[MapViewScene]
|
||||
B --> C[Camera]
|
||||
B --> D[MapLayer]
|
||||
B --> E[EntityLayer]
|
||||
B --> F[SkillLayer]
|
||||
D --> G[背景图片]
|
||||
E --> H[游戏实体]
|
||||
F --> I[技能效果]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts#L14-L45)
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L17-L77)
|
||||
|
||||
**章节来源**
|
||||
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts#L14-L45)
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L17-L77)
|
||||
|
||||
## 数据结构分析
|
||||
|
||||
### map.json - 地图基本信息配置
|
||||
|
||||
map.json文件定义了地图的基本信息和关联关系：
|
||||
|
||||
#### 配置结构
|
||||
|
||||
| 字段 | 类型 | 描述 | 示例值 |
|
||||
|------|------|------|--------|
|
||||
| id | number | 地图唯一标识符 | 1, 2, 3... |
|
||||
| name | string | 地图资源名称 | "img_map3", "img_map15" |
|
||||
| delivery | string | 可跳转的连接点列表 | "1,2", "3,4" |
|
||||
|
||||
#### 数据示例分析
|
||||
|
||||
根据现有配置：
|
||||
- 地图1(ID:1)关联连接点1和2
|
||||
- 地图2(ID:2)关联连接点3和4
|
||||
|
||||
这种设计允许：
|
||||
1. **多路径跳转**：一个地图可以有多个出口
|
||||
2. **动态配置**：通过修改JSON文件即可调整地图关系
|
||||
3. **解耦设计**：地图逻辑与配置分离
|
||||
|
||||
**章节来源**
|
||||
- [map.json](file://assets/resources/config/map/map.json#L1-L12)
|
||||
|
||||
### map_delivery.json - 地图连接点配置
|
||||
|
||||
map_delivery.json定义了具体的跳转连接点信息：
|
||||
|
||||
#### 完整配置结构
|
||||
|
||||
| 字段 | 类型 | 描述 | 示例值 |
|
||||
|------|------|------|--------|
|
||||
| id | number | 连接点唯一标识 | 1, 2, 3... |
|
||||
| mapId | number | 当前地图ID | 1, 2 |
|
||||
| pos | string | 连接点坐标 | "19,267" |
|
||||
| toMapId | number | 目标地图ID | 2, 5, 3, 1 |
|
||||
| start | string | 出生点坐标 | "66,237" |
|
||||
|
||||
#### 数据流分析
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[用户点击连接点] --> B[读取map_delivery.json]
|
||||
B --> C[获取目标地图ID]
|
||||
C --> D[获取出生点坐标]
|
||||
D --> E[切换到目标地图]
|
||||
E --> F[设置玩家位置]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [map_delivery.json](file://assets/resources/config/map/map_delivery.json#L1-L30)
|
||||
|
||||
**章节来源**
|
||||
- [map_delivery.json](file://assets/resources/config/map/map_delivery.json#L1-L30)
|
||||
|
||||
## ECS初始化流程
|
||||
|
||||
### 系统启动序列
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as "应用程序"
|
||||
participant SM as "SingletonModule"
|
||||
participant LM as "LoadingView"
|
||||
participant GM as "GameMap"
|
||||
participant MM as "MapModel"
|
||||
App->>SM : 初始化单例模块
|
||||
SM->>GM : 创建GameMap实体
|
||||
GM->>MM : 添加MapModel组件
|
||||
MM->>MM : 初始化默认状态
|
||||
SM->>LM : 开始加载界面
|
||||
LM->>GM : 调用load()方法
|
||||
GM->>GM : 异步加载资源
|
||||
GM->>SM : 设置smc.map引用
|
||||
SM->>App : 启动游戏主界面
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L36-L42)
|
||||
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L25-L26)
|
||||
|
||||
### 组件注册机制
|
||||
|
||||
ECS框架通过装饰器模式实现组件注册：
|
||||
|
||||
1. **MapModelComp注册**：`@ecs.register('MapModel')`
|
||||
2. **GameMap注册**：`@ecs.register('GameMap')`
|
||||
3. **MapViewComp注册**：`@ecs.register('MapView', false)`
|
||||
|
||||
这种设计确保了：
|
||||
- **自动发现**：ECS系统自动识别和管理组件
|
||||
- **类型安全**：编译时类型检查
|
||||
- **性能优化**：避免运行时反射开销
|
||||
|
||||
**章节来源**
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L8-L9)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L14-L15)
|
||||
- [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts#L36-L42)
|
||||
|
||||
## 地图跳转逻辑
|
||||
|
||||
### 跳转流程设计
|
||||
|
||||
地图跳转是一个复杂的多阶段过程：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[检测到跳转请求] --> B[验证连接点有效性]
|
||||
B --> C{连接点存在?}
|
||||
C --> |否| D[显示错误信息]
|
||||
C --> |是| E[读取连接点配置]
|
||||
E --> F[获取目标地图ID]
|
||||
F --> G[获取出生点坐标]
|
||||
G --> H[清理当前地图资源]
|
||||
H --> I[加载目标地图]
|
||||
I --> J[设置玩家位置]
|
||||
J --> K[更新地图状态]
|
||||
K --> L[触发相关事件]
|
||||
```
|
||||
|
||||
### 多路径跳转实现
|
||||
|
||||
通过map.json中的delivery字段实现多路径跳转：
|
||||
|
||||
1. **配置解析**：将"1,2"字符串解析为数组
|
||||
2. **连接点匹配**：根据用户选择确定具体跳转路径
|
||||
3. **动态路由**：支持运行时修改跳转关系
|
||||
|
||||
### 地图解锁条件
|
||||
|
||||
虽然当前实现中没有显式的解锁条件，但可以通过以下方式扩展：
|
||||
|
||||
1. **成就系统**：完成特定任务后解锁新地图
|
||||
2. **等级要求**：达到一定等级才能访问高级地图
|
||||
3. **前置条件**：需要完成特定关卡才能解锁
|
||||
|
||||
**章节来源**
|
||||
- [map.json](file://assets/resources/config/map/map.json#L2-L11)
|
||||
- [map_delivery.json](file://assets/resources/config/map/map_delivery.json#L1-L30)
|
||||
|
||||
## 数据驱动设计
|
||||
|
||||
### 配置文件的作用
|
||||
|
||||
数据驱动设计的核心优势：
|
||||
|
||||
1. **灵活性**：无需修改代码即可调整地图配置
|
||||
2. **可维护性**：配置与逻辑分离，便于维护
|
||||
3. **可扩展性**：支持动态添加新地图和连接点
|
||||
4. **版本控制**：配置文件易于版本管理和协作
|
||||
|
||||
### 动态配置加载
|
||||
|
||||
系统支持运行时加载配置：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[JSON配置文件] --> B[oops.res.load]
|
||||
B --> C[解析JSON数据]
|
||||
C --> D[构建地图配置对象]
|
||||
D --> E[应用到地图系统]
|
||||
```
|
||||
|
||||
### 配置验证机制
|
||||
|
||||
为了确保配置的正确性，系统应该包含：
|
||||
|
||||
1. **格式验证**：检查JSON语法正确性
|
||||
2. **完整性检查**：验证必需字段的存在
|
||||
3. **一致性验证**：确保地图ID和连接点ID的一致性
|
||||
4. **边界检查**：验证坐标值的有效范围
|
||||
|
||||
**章节来源**
|
||||
- [map.json](file://assets/resources/config/map/map.json#L1-L12)
|
||||
- [map_delivery.json](file://assets/resources/config/map/map_delivery.json#L1-L30)
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 地图配置最佳实践
|
||||
|
||||
#### 新地图添加流程
|
||||
|
||||
1. **创建地图资源**：准备地图图像和相关资源
|
||||
2. **更新map.json**：添加新的地图条目
|
||||
3. **配置连接点**：在map_delivery.json中添加对应的连接点
|
||||
4. **测试验证**：确保跳转逻辑正确
|
||||
|
||||
#### 配置示例
|
||||
|
||||
```json
|
||||
{
|
||||
"3": {
|
||||
"id": 3,
|
||||
"name": "img_map_new",
|
||||
"delivery": "5,6"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"5": {
|
||||
"id": 5,
|
||||
"mapId": 3,
|
||||
"pos": "30,40",
|
||||
"toMapId": 1,
|
||||
"start": "15,25"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 性能优化建议
|
||||
|
||||
1. **资源预加载**：提前加载常用地图资源
|
||||
2. **延迟加载**：对于不常用的地图采用按需加载
|
||||
3. **内存管理**：及时释放不再使用的地图资源
|
||||
4. **缓存策略**：缓存频繁访问的地图配置
|
||||
|
||||
### 错误处理策略
|
||||
|
||||
1. **配置缺失**：提供默认配置或友好的错误提示
|
||||
2. **资源加载失败**：实现资源降级方案
|
||||
3. **跳转失败**：提供重试机制或备用路径
|
||||
4. **数据损坏**：实现配置文件的备份和恢复
|
||||
|
||||
## 总结
|
||||
|
||||
MapModelComp组件作为地图系统的核心数据层，成功地实现了以下目标：
|
||||
|
||||
### 技术亮点
|
||||
|
||||
1. **ECS架构**：采用现代的游戏开发模式，实现了良好的解耦
|
||||
2. **数据驱动**：通过JSON配置文件实现了灵活的地图管理
|
||||
3. **资源管理**：提供了完整的资源生命周期管理
|
||||
4. **扩展性**：预留了丰富的扩展点和优化空间
|
||||
|
||||
### 设计优势
|
||||
|
||||
1. **模块化**：各组件职责明确，便于维护和扩展
|
||||
2. **可配置性**：通过配置文件即可调整地图逻辑
|
||||
3. **性能优化**：支持异步加载和资源管理
|
||||
4. **错误处理**：内置了基本的错误处理机制
|
||||
|
||||
### 应用价值
|
||||
|
||||
该设计为游戏开发提供了：
|
||||
- **快速迭代**：通过配置即可实现地图逻辑变更
|
||||
- **团队协作**：策划人员可以直接编辑配置文件
|
||||
- **跨平台支持**：基于Cocos引擎，支持多平台部署
|
||||
- **未来扩展**：为后续的功能扩展奠定了良好基础
|
||||
|
||||
通过深入理解MapModelComp的设计理念和实现细节，开发者可以更好地利用这一组件，构建更加复杂和有趣的游戏世界。
|
||||
Reference in New Issue
Block a user