# 地图图层管理

<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轴排序算法，引入更复杂的光照模型，并完善技能特效的资源管理机制。