# 实体图层管理

<cite>
**本文档引用文件**   
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts)
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts)
- [BattleMoveComp.ts](file://assets/script/game/common/ecs/position/BattleMoveComp.ts)
- [Hero.ts](file://assets/script/game/hero/Hero.ts)
- [Mon.ts](file://assets/script/game/hero/Mon.ts)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts)
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts)
- [timer.md](file://doc/core/common/timer.md)
</cite>

## 目录
1. [引言](#引言)
2. [实体图层结构](#实体图层结构)
3. [Z轴层级管理机制](#z轴层级管理机制)
4. [定时器更新策略](#定时器更新策略)
5. [ECS系统数据同步](#ecs系统数据同步)
6. [性能优化方案](#性能优化方案)
7. [结论](#结论)

## 引言
本文档深入解析EntityLayer作为动态实体容器的实现机制，重点阐述其如何承载英雄、怪物及其他可移动单位的可视化节点。文档将详细说明其通过addChild与zIndex控制子节点渲染顺序的Z轴层级管理机制，分析其内置的定时器更新策略，以及与ECS系统中BattleMoveComp的数据同步设计模式。同时，提供处理大量实体时的性能优化方案。

## 实体图层结构

EntityLayer作为游戏场景中的物体层，负责管理所有动态实体的可视化节点。该图层通过Cocos Creator的节点系统实现，作为场景中的一个特殊容器节点，专门用于承载英雄、怪物等可移动单位。

```mermaid
graph TB
subgraph "场景层级结构"
MapViewScene[地图场景]
EntityLayer[实体图层]
SkillLayer[技能图层]
MapLayer[地图图层]
end
MapViewScene --> EntityLayer
MapViewScene --> SkillLayer
MapViewScene --> MapLayer
EntityLayer --> HeroNode[英雄节点]
EntityLayer --> MonsterNode[怪物节点]
```

**Diagram sources**
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L38)
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L20)

**Section sources**
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L38)
- [MapViewScene.ts](file://assets/script/game/map/view/MapViewScene.ts#L1-L20)

## Z轴层级管理机制

EntityLayer通过精确的Z轴层级管理机制确保战斗单位在地形与特效间的正确叠加。该机制不直接依赖节点的z坐标，而是通过控制节点在父节点中的兄弟索引（sibling index）来实现渲染顺序的控制。

核心实现位于BattleMoveSystem中，通过updateRenderOrder方法动态调整所有单位的渲染层级：

```mermaid
flowchart TD
Start([开始更新渲染层级]) --> FindUnits["查找所有HeroViewComp实体"]
FindUnits --> FilterByFac["按阵营分组"]
FilterByFac --> SortByX["按x坐标排序<br/>x坐标越小越靠后"]
SortByX --> SetSiblingIndex["设置兄弟索引<br/>index越大层级越高"]
SetSiblingIndex --> End([完成渲染层级更新])
```

**Diagram sources**
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L233-L262)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L1-L50)

**Section sources**
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L233-L262)
- [HeroViewComp.ts](file://assets/script/game/hero/HeroViewComp.ts#L1-L50)

## 定时器更新策略

EntityLayer采用智能的定时器更新策略，通过固定帧间隔批量刷新实体位置以降低渲染开销。该策略避免了每帧都进行深度排序可能带来的性能问题。

```mermaid
classDiagram
class EntityLayer {
-timer : Timer
+update(dt : number)
+clear()
}
class Timer {
+interval : number
+update(dt : number) : boolean
}
EntityLayer --> Timer : "使用"
```

EntityLayer中定义了一个间隔为0.2秒的Timer实例，理论上应该周期性地执行节点排序。然而，当前实现中相关代码被注释，表明开发者意识到每帧排序的性能开销问题，为未来优化预留了接口。

**Diagram sources**
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L38)
- [timer.md](file://doc/core/common/timer.md#L79-L91)

**Section sources**
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L38)
- [timer.md](file://doc/core/common/timer.md#L79-L91)

## ECS系统数据同步

系统采用实体-组件-系统（ECS）架构实现视图与逻辑的完全解耦。BattleMoveComp作为数据组件承载移动状态，而EntityLayer作为视图容器负责可视化呈现。

```mermaid
sequenceDiagram
participant BattleMoveSystem as BattleMoveSystem
participant BattleMoveComp as BattleMoveComp
participant HeroViewComp as HeroViewComp
participant EntityLayer as EntityLayer
BattleMoveSystem->>BattleMoveComp : 读取移动状态
BattleMoveSystem->>HeroViewComp : 获取节点引用
BattleMoveSystem->>HeroViewComp : 更新位置
BattleMoveSystem->>BattleMoveSystem : updateRenderOrder()
BattleMoveSystem->>HeroViewComp : setSiblingIndex()
HeroViewComp->>EntityLayer : 节点层级更新
```

当英雄或怪物实体被加载时，通过addChild方法将其节点添加到EntityLayer中，实现视图与逻辑的绑定：

**Section sources**
- [Hero.ts](file://assets/script/game/hero/Hero.ts#L45-L55)
- [Mon.ts](file://assets/script/game/hero/Mon.ts#L48-L58)
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L1-L34)

## 性能优化方案

### 对象池复用
系统通过ECS框架内置的对象池机制实现组件和实体的高效复用。当实体被销毁时，其组件会被放入缓存池中，下次创建时优先从池中获取，避免频繁的内存分配与垃圾回收。

```mermaid
erDiagram
ENTITY["实体"] {
string name PK
boolean active
}
COMPONENT["组件"] {
string type PK
boolean pooled
}
ENTITY_POOL["实体池"] {
int capacity
int count
}
COMPONENT_POOL["组件池"] {
int capacity
int count
}
ENTITY ||--o{ COMPONENT : "包含"
ENTITY_POOL }o--|| ENTITY : "存储"
COMPONENT_POOL }o--|| COMPONENT : "存储"
```

### 可见性裁剪
虽然当前代码未显式实现可见性裁剪，但在BattleMoveSystem中通过阵营分组过滤和距离检测，间接实现了部分裁剪功能。系统只对同阵营的单位进行渲染层级计算，减少了不必要的处理。

### 批量更新策略
通过0.2秒的定时器间隔，系统可以批量处理多个实体的位置更新和层级排序，而不是每帧都执行，有效降低了CPU开销。

**Section sources**
- [ecs.md](file://ecs.md#L29-L87)
- [EntityLayer.ts](file://assets/script/game/map/view/map/layer/EntityLayer.ts#L1-L38)
- [BattleMoveSystem.ts](file://assets/script/game/common/ecs/position/BattleMoveSystem.ts#L1-L34)

## 结论
EntityLayer作为动态实体容器，通过精心设计的Z轴层级管理机制和定时器更新策略，有效平衡了视觉效果与性能开销。其与ECS系统的深度集成实现了视图与逻辑的完美解耦，为游戏的可维护性和扩展性奠定了坚实基础。未来的优化方向包括启用定时排序、实现完整的可见性裁剪以及进一步优化对象池策略。