148 lines
4.4 KiB
Markdown
148 lines
4.4 KiB
Markdown
# MapEntity 设计规范（开发约束）
|
||
|
||
最后更新：2026-03-02
|
||
|
||
## 1. 目标与边界
|
||
|
||
`MapEntity` 现在是战斗地图域的编排层（orchestrator），目标是：
|
||
- 对外暴露地图能力（格子查询、路径查询、建造操作入口）。
|
||
- 在 Unity 生命周期中初始化/清理各子服务。
|
||
- 承担输入与 UI 用例的连接，不承载具体业务算法细节。
|
||
|
||
`MapEntity` 不应再直接实现以下细节：
|
||
- Tile 扫描与路径缓存算法。
|
||
- 防御塔映射字典的增删改查细节。
|
||
- 选中状态与攻击范围显示细节。
|
||
- 鼠标拾取与 `CombatSelectFormUserData` 组装细节。
|
||
|
||
---
|
||
|
||
## 2. 模块划分（当前标准）
|
||
|
||
### 2.1 MapEntity（编排层）
|
||
|
||
文件：`Assets/GameMain/Scripts/Entity/EntityLogic/MapEntity.cs`
|
||
|
||
职责：
|
||
- 生命周期编排：`OnInit / OnShow / OnUpdate / OnHide`
|
||
- 子服务初始化与清理
|
||
- UI 用例绑定（`CombatSelectFormUseCase`）
|
||
- 将输入结果分发到选择器/建造器
|
||
|
||
### 2.2 MapTopologyService（地图拓扑层）
|
||
|
||
当前文件：`Assets/GameMain/Scripts/Scene/Map/TowerPlacementService.cs`（同文件内）
|
||
|
||
职责：
|
||
- 扫描 Tilemap，构建 `PathCells` / `FoundationCells`
|
||
- 缓存 `Spawner -> 默认路径`
|
||
- 提供路径查询：
|
||
- `TryGetNearestPathCell`
|
||
- `TryGetDefaultPathCells`
|
||
- `TryFindPathCells`
|
||
- `TryFindPathWorldPoints`
|
||
|
||
约束：
|
||
- 只处理“地图拓扑与路径”，不处理经济、建塔、UI。
|
||
|
||
### 2.3 CombatSelectInputService（输入解析层）
|
||
|
||
文件：`Assets/GameMain/Scripts/Entity/EntityLogic/CombatSelectInputService.cs`
|
||
|
||
职责：
|
||
- 鼠标屏幕坐标 -> 世界坐标
|
||
- 判定点击对象类型（`None/Foundation/Tower`）
|
||
- 组装 `CombatSelectFormUserData`
|
||
|
||
约束：
|
||
- 只读上下文，不改变游戏状态。
|
||
- Foundation/Tower 点击时，UI 定位由 Cell 中心决定（稳定定位）。
|
||
|
||
### 2.4 TowerPlacementService（塔部署层）
|
||
|
||
当前文件：`Assets/GameMain/Scripts/Scene/Map/TowerPlacementService.cs`
|
||
|
||
职责：
|
||
- 建造 / 升级 / 销毁（含升级失败回滚）
|
||
- 维护塔映射状态：
|
||
- `foundationCell -> towerEntityId`
|
||
- `towerEntityId -> foundationCell`
|
||
- `towerEntityId -> towerStats`
|
||
- 提供整局清理接口
|
||
|
||
约束：
|
||
- 仅处理塔生命周期与映射，不处理选中态和 UI。
|
||
|
||
### 2.5 TowerSelectionPresenter（选择展示层）
|
||
|
||
文件：`Assets/GameMain/Scripts/Scene/Map/TowerSelectionPresenter.cs`
|
||
|
||
职责：
|
||
- 维护当前选中对象
|
||
- 根据选中状态切换攻击范围显示（通过 `DefenseTowerEntity.SetAttackRangeVisible`）
|
||
|
||
约束：
|
||
- 不做建造/升级/销毁。
|
||
|
||
---
|
||
|
||
## 3. 运行时主流程（简版）
|
||
|
||
1. `MapEntity.OnInit` 初始化 4 个服务：
|
||
- `MapTopologyService`
|
||
- `CombatSelectInputService`
|
||
- `TowerPlacementService`
|
||
- `TowerSelectionPresenter`
|
||
2. `MapEntity.OnShow` 刷新地图拓扑，配置 UI action。
|
||
3. 每帧 `OnUpdate`：
|
||
- 采集输入（InputService）
|
||
- 更新选中对象（SelectionPresenter）
|
||
- 打开/刷新 UI
|
||
4. UI Build/Upgrade/Destroy action 回调：
|
||
- 通过 PlacementService 改变塔状态
|
||
- 通过 SelectionPresenter 同步选中和范围显示
|
||
5. `OnHide`：
|
||
- 关闭 UI
|
||
- 清理塔实体
|
||
- 清理拓扑/选择/映射运行时状态
|
||
|
||
---
|
||
|
||
## 4. 核心不变量（必须保持）
|
||
|
||
1. `MapEntity` 只编排，不承载业务细节实现。
|
||
2. `TowerPlacementService` 是塔映射状态的唯一写入口。
|
||
3. `MapTopologyService` 是 Path/Foundation 数据的唯一来源。
|
||
4. “当前可见攻击范围”同一时刻最多一个塔。
|
||
5. 清场顺序固定：先隐藏塔，再清空映射与选择，再清理拓扑缓存。
|
||
|
||
---
|
||
|
||
## 5. 扩展开发规范
|
||
|
||
### 5.1 新增地图规则（地形、禁建、动态阻挡）
|
||
|
||
优先改 `MapTopologyService`，不要直接改 `MapEntity`。
|
||
|
||
### 5.2 新增建造规则（费用、限制、回滚策略）
|
||
|
||
优先改 `TowerPlacementService`，不要在 `MapEntity` 写分支。
|
||
|
||
### 5.3 新增点击交互或 UI 定位策略
|
||
|
||
优先改 `CombatSelectInputService`。
|
||
|
||
### 5.4 新增选中表现（特效、描边、信息面板联动）
|
||
|
||
优先改 `TowerSelectionPresenter`。
|
||
|
||
---
|
||
|
||
## 6. 代码变更检查清单（PR 自检）
|
||
|
||
1. 是否把新业务放进了对应服务，而不是 `MapEntity`？
|
||
2. 是否破坏了“服务唯一写入口”不变量？
|
||
3. Build/Upgrade 失败是否有完整回滚和金币返还？
|
||
4. 清理路径是否覆盖了 `OnHide` 与重进地图场景？
|
||
5. `dotnet build GeometryTD.sln` 是否通过？
|