refactor(game): 移除已弃用的事件常量
- 删除 UpdateHero 和 UpdateFightHero 事件 - 移除 MISSION_UPDATE 事件常量 - 优化游戏事件枚举定义
This commit is contained in:
panw
272
.qoder/repowiki/zh/content/地图系统/地图视图/地图图层管理/地图图层管理.md
Normal file
272
.qoder/repowiki/zh/content/地图系统/地图视图/地图图层管理/地图图层管理.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# 地图图层管理
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts)
|
||||
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts)
|
||||
- [SkillLayer.ts](file://assets/script/game/map/view/map/layer/SkillLayer.ts)
|
||||
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts)
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts)
|
||||
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts)
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
本文档系统阐述了Cocos游戏项目中地图图层管理系统的实现机制。重点分析MapLayer作为背景图层的基础实现，EntityLayer如何承载动态实体并实现Z轴层级控制，SkillLayer在技能特效渲染中的作用，以及light.ts实现光照效果的潜在扩展方式。同时详细解析各图层继承Component的结构设计，展示图层间协作模式与节点组织策略，并提供新增自定义图层、优化图层渲染顺序与内存管理的最佳实践。
|
||||
|
||||
## 项目结构
|
||||
地图图层管理系统位于`assets/script/game/map/`目录下，采用MVC架构模式组织代码。系统分为模型层（model）、视图层（view）和控制器层，其中图层相关实现集中在view目录下的map/layer子目录中。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "地图系统"
|
||||
Model[模型层\nMapModelComp]
|
||||
View[视图层\nMapViewComp/MapViewScene]
|
||||
Layers[图层组件\nMapLayer/EntityLayer/SkillLayer]
|
||||
end
|
||||
Model --> View
|
||||
View --> Layers
|
||||
Layers --> CC[CC引擎组件\nSprite/Node/Camera]
|
||||
```
|
||||
|
||||
**图层来源**
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L10)
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L1-L10)
|
||||
|
||||
**章节来源**
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L80)
|
||||
- [MapModelComp.ts](file://assets/script/game/map/model/MapModelComp.ts#L1-L50)
|
||||
|
||||
## 核心组件
|
||||
地图图层管理系统由四个核心图层组件构成：MapLayer负责背景渲染，EntityLayer管理动态实体，SkillLayer处理技能特效，light.ts提供光照效果扩展。这些组件均继承自CC引擎的Component类，通过节点树结构组织，形成分层渲染体系。
|
||||
|
||||
**章节来源**
|
||||
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts#L1-L47)
|
||||
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L39)
|
||||
|
||||
## 架构概述
|
||||
地图图层系统采用分层架构设计，通过MapViewScene统一管理各图层组件的生命周期和交互逻辑。系统实现了数据与视图的分离，通过ECS架构模式管理游戏实体状态。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Component {
|
||||
<<abstract>>
|
||||
}
|
||||
class MapLayer {
|
||||
-bgImg : Sprite
|
||||
+init() : void
|
||||
+clear() : void
|
||||
+bgImage : Sprite
|
||||
+width : number
|
||||
+height : number
|
||||
}
|
||||
class EntityLayer {
|
||||
-timer : Timer
|
||||
+update(dt : number)
|
||||
+clear() : void
|
||||
}
|
||||
class SkillLayer {
|
||||
-timer : Timer
|
||||
-light : Prefab
|
||||
+doSkill() : void
|
||||
+clear() : void
|
||||
}
|
||||
class light {
|
||||
+start() : void
|
||||
+onLoad() : void
|
||||
+update(deltaTime : number) : void
|
||||
}
|
||||
class MapViewScene {
|
||||
-camera : Camera
|
||||
-mapLayer : MapLayer
|
||||
-entityLayer : EntityLayer
|
||||
-SkillLayer : SkillLayer
|
||||
+init() : void
|
||||
+reset() : void
|
||||
}
|
||||
Component <|-- MapLayer
|
||||
Component <|-- EntityLayer
|
||||
Component <|-- SkillLayer
|
||||
Component <|-- light
|
||||
MapViewScene --> MapLayer
|
||||
MapViewScene --> EntityLayer
|
||||
MapViewScene --> SkillLayer
|
||||
```
|
||||
|
||||
**图层来源**
|
||||
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts#L1-L47)
|
||||
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L39)
|
||||
- [SkillLayer.ts](file://assets/script/game/map/view/map/layer/SkillLayer.ts#L1-L48)
|
||||
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts#L1-L20)
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L77)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### MapLayer分析
|
||||
MapLayer组件作为地图的背景图层，负责初始化纹理、适配尺寸和管理精灵帧。通过Sprite组件实现背景图像的渲染，利用UITransform组件控制图层尺寸。
|
||||
|
||||
#### 类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MapLayer {
|
||||
-bgImg : Sprite
|
||||
+init() : void
|
||||
+clear() : void
|
||||
+bgImage : Sprite
|
||||
+width : number
|
||||
+height : number
|
||||
}
|
||||
class Sprite {
|
||||
-spriteFrame : SpriteFrame
|
||||
-texture : Texture2D
|
||||
}
|
||||
class UITransform {
|
||||
-width : number
|
||||
-height : number
|
||||
}
|
||||
MapLayer --> Sprite : "包含"
|
||||
MapLayer --> UITransform : "使用"
|
||||
```
|
||||
|
||||
**图层来源**
|
||||
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts#L15-L47)
|
||||
|
||||
**章节来源**
|
||||
- [MapLayer.ts](file://assets/script/game/map/view/map/layer/MapLayer.ts#L1-L47)
|
||||
|
||||
### EntityLayer分析
|
||||
EntityLayer组件承载英雄与怪物等动态实体，通过子节点排序实现Z轴层级控制。采用定时器优化渲染更新频率，避免每帧都进行排序操作以提升性能。
|
||||
|
||||
#### 序列图
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant EntityLayer as EntityLayer
|
||||
participant Timer as Timer
|
||||
participant Node as Node.children
|
||||
participant Sort as zIndexSort
|
||||
EntityLayer->>Timer : update(dt)
|
||||
Timer-->>EntityLayer : 是否达到0.2秒间隔?
|
||||
alt 达到间隔
|
||||
EntityLayer->>Node : children.sort()
|
||||
Node->>Sort : 执行Z轴排序
|
||||
Sort-->>Node : 返回排序结果
|
||||
Node-->>EntityLayer : 完成排序
|
||||
end
|
||||
EntityLayer->>EntityLayer : 继续下一帧更新
|
||||
```
|
||||
|
||||
**图层来源**
|
||||
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L39)
|
||||
- [Timer.ts](file://assets/script/game/common/config/BoxSet.ts#L1-L10)
|
||||
|
||||
**章节来源**
|
||||
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L39)
|
||||
|
||||
### SkillLayer分析
|
||||
SkillLayer组件专门处理技能特效的渲染，通过预制体(Prefab)管理技能相关的视觉效果。组件设计支持事件驱动的技能触发机制，为技能系统的扩展提供了基础。
|
||||
|
||||
#### 流程图
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([组件加载]) --> B{是否监听到\n"do_use_skill"事件?}
|
||||
B --> |是| C[执行doSkill方法]
|
||||
B --> |否| D[等待下一帧]
|
||||
C --> E[实例化技能特效预制体]
|
||||
E --> F[添加到场景节点树]
|
||||
F --> G[播放技能动画]
|
||||
G --> H[技能效果完成]
|
||||
H --> I[清理特效节点]
|
||||
I --> D
|
||||
D --> J{组件是否销毁?}
|
||||
J --> |是| K([组件卸载])
|
||||
J --> |否| B
|
||||
```
|
||||
|
||||
**图层来源**
|
||||
- [SkillLayer.ts](file://assets/script/game/map/view/map/layer/SkillLayer.ts#L1-L48)
|
||||
- [Prefab](file://assets/script/game/common/config/BoxSet.ts#L1-L10)
|
||||
|
||||
**章节来源**
|
||||
- [SkillLayer.ts](file://assets/script/game/map/view/map/layer/SkillLayer.ts#L1-L48)
|
||||
|
||||
### 光照系统分析
|
||||
light.ts文件定义了基础的光照组件，为地图系统提供了光照效果的扩展能力。虽然当前实现较为简单，但已具备完整的组件生命周期管理。
|
||||
|
||||
#### 状态图
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 初始化
|
||||
初始化 --> 加载中 : onLoad()
|
||||
加载中 --> 运行中 : start()
|
||||
运行中 --> 加载中 : 重新加载
|
||||
运行中 --> 更新中 : update()
|
||||
更新中 --> 运行中 : 完成更新
|
||||
运行中 --> 销毁 : 组件移除
|
||||
销毁 --> [*]
|
||||
```
|
||||
|
||||
**图层来源**
|
||||
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts#L1-L20)
|
||||
|
||||
**章节来源**
|
||||
- [light.ts](file://assets/script/game/map/view/map/layer/light.ts#L1-L20)
|
||||
|
||||
## 依赖分析
|
||||
地图图层系统依赖于Oops插件框架提供的核心功能，包括资源管理、消息系统和ECS架构。各图层组件通过MapViewScene进行协调管理，形成清晰的依赖关系。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[MapLayer] --> B[CC引擎]
|
||||
C[EntityLayer] --> B
|
||||
D[SkillLayer] --> B
|
||||
E[light] --> B
|
||||
F[MapViewScene] --> A
|
||||
F --> C
|
||||
F --> D
|
||||
F --> E
|
||||
G[Oops框架] --> F
|
||||
G --> C
|
||||
G --> D
|
||||
B --> H[Sprite]
|
||||
B --> I[Node]
|
||||
B --> J[Camera]
|
||||
```
|
||||
|
||||
**图层来源**
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L77)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L1-L36)
|
||||
|
||||
**章节来源**
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L77)
|
||||
- [GameMap.ts](file://assets/script/game/map/GameMap.ts#L1-L36)
|
||||
|
||||
## 性能考虑
|
||||
地图图层系统在设计时充分考虑了性能优化。EntityLayer和SkillLayer均采用定时器控制更新频率，避免不必要的每帧计算。MapLayer通过直接操作UITransform组件实现高效的尺寸适配。
|
||||
|
||||
系统建议的性能优化策略包括：
|
||||
1. 对于静态背景，使用MapLayer一次性初始化
|
||||
2. 动态实体的Z轴排序采用0.2秒间隔更新，平衡视觉效果与性能
|
||||
3. 技能特效使用对象池模式管理预制体实例，减少GC压力
|
||||
4. 光照效果可根据需要动态启用或禁用
|
||||
|
||||
## 故障排除指南
|
||||
当遇到地图图层相关问题时，可参考以下排查步骤：
|
||||
|
||||
**章节来源**
|
||||
- [MapViewComp.ts](file://assets/script/game/map/view/MapViewComp.ts#L1-L45)
|
||||
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L77)
|
||||
|
||||
## 结论
|
||||
地图图层管理系统通过分层设计实现了关注点分离，各图层职责明确，便于维护和扩展。系统充分利用了CC引擎的节点组件体系，结合Oops框架的ECS架构，构建了一个高效、可扩展的地图渲染解决方案。未来可进一步优化Z轴排序算法，引入更复杂的光照模型，并完善技能特效的资源管理机制。
|
||||
Reference in New Issue
Block a user