222 lines
6.3 KiB
Markdown
222 lines
6.3 KiB
Markdown
# CombatNode 架构摘要
|
||
|
||
最后更新：2026-02-28
|
||
|
||
## 1. 目标与边界
|
||
|
||
CombatNode 子系统的目标是把“战斗节点”拆成三个稳定层：
|
||
|
||
- `CombatNodeComponent`：节点入口与配置缓存（门面层）
|
||
- `CombatScheduler`：单局战斗状态机（编排层）
|
||
- `EnemyManager`：刷怪与敌人生命周期（执行层）
|
||
|
||
边界约束：
|
||
|
||
- 只负责战斗节点，不负责菜单流程切换，不负责 UI 细节。
|
||
- 只依赖数据表和 Entity 系统，不直接持有场景流程 FSM。
|
||
- 地图寻路由 `MapEntity` 提供能力，敌人移动由 `EnemyEntity` 自治。
|
||
|
||
---
|
||
|
||
## 2. 模块职责划分
|
||
|
||
## 2.1 CombatNodeComponent（门面层）
|
||
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatNodeComponent.cs`
|
||
|
||
职责：
|
||
|
||
- 读取并缓存 `DRLevel / DRLevelPhase / DRLevelSpawnEntry`。
|
||
- 按主题筛选关卡，维护 `Level -> Phase -> SpawnEntry` 映射。
|
||
- 提供 `OnInit / StartCombat / OnUpdate / OnShutdown` 外部接口。
|
||
- 触发节点事件：
|
||
- `NodeEnterEventArgs`
|
||
- `NodeCompleteEventArgs`
|
||
|
||
不做的事：
|
||
|
||
- 不做阶段推进。
|
||
- 不做刷怪时序。
|
||
- 不做实体显示/隐藏细节。
|
||
|
||
## 2.2 CombatScheduler（编排层）
|
||
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler.cs`
|
||
|
||
职责：
|
||
|
||
- 管理战斗状态机：`Idle -> WaitingForMap -> RunningPhase -> Completed/Failed`。
|
||
- 加载地图实体，接收地图 show/hide 成功失败事件。
|
||
- 按 phase 结束条件推进到下一阶段。
|
||
- 在开始新战斗或销毁时做统一清场（地图 + 本局敌人）。
|
||
|
||
不做的事：
|
||
|
||
- 不直接计算每条刷怪规则的触发细节（交给 `EnemyManager`）。
|
||
|
||
## 2.3 EnemyManager（执行层）
|
||
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager.cs`
|
||
|
||
职责：
|
||
|
||
- 将 `DRLevelSpawnEntry` 转为运行时任务（stream/burst/boss）。
|
||
- 按时间推进刷怪任务并生成 `EnemyData`。
|
||
- 维护本局敌人数量 `AliveEnemyCount`。
|
||
- 维护“本局生成敌人 ID 集合”，用于准确计数与清场。
|
||
|
||
关键点：
|
||
|
||
- 生命周期归属按 `entityId` 跟踪，不再按实体组名粗粒度统计。
|
||
- 清场可覆盖“已加载 + 加载中”的本局敌人。
|
||
|
||
---
|
||
|
||
## 3. 关键实体职责
|
||
|
||
## 3.1 MapEntity
|
||
|
||
文件：`Assets/GameMain/Scripts/Entity/EntityLogic/MapEntity.cs`
|
||
|
||
职责：
|
||
|
||
- 读取 Tilemap，识别 Path/Foundation 格子。
|
||
- 为每个 `Spawner` 缓存默认可达路径。
|
||
- 提供：
|
||
- `TryGetDefaultPathCells`
|
||
- `TryFindPathCells`
|
||
- `TryFindPathWorldPoints`
|
||
|
||
## 3.2 EnemyEntity
|
||
|
||
文件：`Assets/GameMain/Scripts/Entity/EntityLogic/EnemyEntity.cs`
|
||
|
||
职责：
|
||
|
||
- 按路径点移动。
|
||
- 到达终点后调用 `HideEntity` 自行退出。
|
||
|
||
---
|
||
|
||
## 4. 运行时时序（简版）
|
||
|
||
1. 菜单触发战斗：`TestMenuFormController -> GameEntry.CombatNode.StartCombat()`
|
||
2. `CombatNodeComponent.StartCombat()` 选关并把关卡配置交给 `CombatScheduler.Start()`
|
||
3. `CombatScheduler.Start()` 先清理上局残留，再 `ShowMap(...)`，状态进入 `WaitingForMap`
|
||
4. 地图加载成功事件到达，`_currentMap` 就绪
|
||
5. `BeginNextPhase()` 进入 `RunningPhase`，`EnemyManager.BeginPhase(...)`
|
||
6. 每帧 `OnUpdate`：
|
||
- `CombatScheduler` 更新时间与结束条件
|
||
- `EnemyManager` 推进刷怪任务并创建敌人
|
||
7. 当前 phase 满足结束条件，`CompleteCurrentPhase()`，然后进入下一 phase
|
||
8. 全 phase 完成后隐藏地图，`GameEntry.CombatNode.EndCombat()`，抛 `NodeComplete`
|
||
|
||
---
|
||
|
||
## 5. 数据契约与 ID 规则
|
||
|
||
数据来源：
|
||
|
||
- `DRLevel`
|
||
- `DRLevelPhase`
|
||
- `DRLevelSpawnEntry`
|
||
|
||
当前约定（依赖 ID 编码）：
|
||
|
||
- `levelId = phaseId / 1000`
|
||
- `phaseId = spawnEntryId / 1000`
|
||
|
||
影响：
|
||
|
||
- 新增配置时必须遵守该编码，否则 phase 和 entry 无法被正确归属。
|
||
|
||
建议：
|
||
|
||
- 若后续改数据结构，优先改成显式外键字段，减少 ID 推导耦合。
|
||
|
||
---
|
||
|
||
## 6. 结束条件模型
|
||
|
||
枚举：`PhaseEndType`
|
||
|
||
- `TimeElapsed`：按 `EndParam`（可解析 float）或 `DurationSeconds`
|
||
- `EnemiesCleared`：`IsPhaseSpawnCompleted && AliveEnemyCount <= 0`
|
||
- `BossDead`：当前与 `EnemiesCleared` 同判定
|
||
- `None`：有 duration 走 duration，否则退化为清怪判定
|
||
|
||
实现点：`CombatScheduler.ShouldEndCurrentPhase()`
|
||
|
||
---
|
||
|
||
## 7. 生命周期与清场策略（当前实现）
|
||
|
||
## 7.1 地图生命周期
|
||
|
||
- 通过 `ShowMap` 异步加载。
|
||
- 通过 `ShowEntitySuccess/Failure` 绑定运行态地图引用。
|
||
- 完成关卡时隐藏地图。
|
||
- 新战斗开始和调度器销毁前都会尝试清理地图实体。
|
||
|
||
## 7.2 敌人生命周期
|
||
|
||
- 创建时登记 `entityId` 到 `_trackedEnemyEntityIds`。
|
||
- `ShowEntitySuccess` 仅对 tracked id 计数。
|
||
- `HideEntityComplete` 仅对 tracked id 减计数并移除跟踪。
|
||
- 清场时按 tracked id 隐藏（覆盖加载中和已加载实体）。
|
||
|
||
## 7.3 设计目标
|
||
|
||
- 防止跨局残留实体污染新局状态。
|
||
- 防止其他系统 `Enemy` 组实体干扰战斗计数。
|
||
|
||
---
|
||
|
||
## 8. 扩展指南（按需求）
|
||
|
||
## 8.1 新增阶段结束条件
|
||
|
||
- 改 `PhaseEndType` 枚举。
|
||
- 在 `ShouldEndCurrentPhase()` 增加分支。
|
||
|
||
## 8.2 新增刷怪条目类型
|
||
|
||
- 改 `EntryType` 枚举。
|
||
- 在 `EnemyManager.BuildSpawnRuntime()` 与 `UpdateSpawnRuntimes()` 增加处理。
|
||
|
||
## 8.3 改选关策略
|
||
|
||
- 当前是随机选关：`TrySelectRandomLevel()`。
|
||
- 可改为按难度、解锁进度、权重池。
|
||
|
||
## 8.4 动态阻挡/重算路径
|
||
|
||
- 当前 `SpawnEnemies` 调 `TryFindPathWorldPoints(spawner, null, ...)`。
|
||
- 若支持塔阻挡，传入 `blockedCells` 并处理“无路可走”策略。
|
||
|
||
## 8.5 结算与奖励
|
||
|
||
- 推荐挂在 `CombatScheduler` 完成分支（所有 phase 完成处），不要塞进 `EnemyManager`。
|
||
|
||
---
|
||
|
||
## 9. 维护时的硬性不变量
|
||
|
||
- `CombatNodeComponent` 只做缓存和入口，不写战斗细节。
|
||
- `CombatScheduler` 是唯一 phase 状态机，不在别处推进 phase。
|
||
- `AliveEnemyCount` 必须由 tracked id 驱动，不回退到组名统计。
|
||
- 新战斗开始前必须清场。
|
||
- `ResetRuntime()` 必须清空地图相关运行态引用和 id。
|
||
|
||
---
|
||
|
||
## 10. 快速阅读路径（新人 10 分钟）
|
||
|
||
1. `CombatNodeComponent.StartCombat()`
|
||
2. `CombatScheduler.Start() / OnUpdate() / BeginNextPhase()`
|
||
3. `EnemyManager.BeginPhase() / OnUpdate() / SpawnEnemies()`
|
||
4. `MapEntity.TryFindPathWorldPoints()`
|
||
5. `EnemyEntity.DespawnOnReachHouse()`
|
||
|
||
这 5 个点读完，基本能覆盖 90% 战斗节点行为。
|