4.4 KiB

Raw Blame History

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. 运行时主流程（简版）

MapEntity.OnInit 初始化 4 个服务：
- MapTopologyService
- CombatSelectInputService
- TowerPlacementService
- TowerSelectionPresenter
MapEntity.OnShow 刷新地图拓扑，配置 UI action。
每帧 OnUpdate：
- 采集输入（InputService）
- 更新选中对象（SelectionPresenter）
- 打开/刷新 UI
UI Build/Upgrade/Destroy action 回调：
- 通过 PlacementService 改变塔状态
- 通过 SelectionPresenter 同步选中和范围显示
OnHide：
- 关闭 UI
- 清理塔实体
- 清理拓扑/选择/映射运行时状态

4. 核心不变量（必须保持）

MapEntity 只编排，不承载业务细节实现。
TowerPlacementService 是塔映射状态的唯一写入口。
MapTopologyService 是 Path/Foundation 数据的唯一来源。
“当前可见攻击范围”同一时刻最多一个塔。
清场顺序固定：先隐藏塔，再清空映射与选择，再清理拓扑缓存。

5. 扩展开发规范

5.1 新增地图规则（地形、禁建、动态阻挡）

优先改 MapTopologyService，不要直接改 MapEntity。

5.2 新增建造规则（费用、限制、回滚策略）

优先改 TowerPlacementService，不要在 MapEntity 写分支。

5.3 新增点击交互或 UI 定位策略

优先改 CombatSelectInputService。

5.4 新增选中表现（特效、描边、信息面板联动）

优先改 TowerSelectionPresenter。

6. 代码变更检查清单（PR 自检）

是否把新业务放进了对应服务，而不是 MapEntity？
是否破坏了“服务唯一写入口”不变量？
Build/Upgrade 失败是否有完整回滚和金币返还？
清理路径是否覆盖了 OnHide 与重进地图场景？
dotnet build GeometryTD.sln 是否通过？

4.4 KiB Raw Blame History Unescape Escape