128 lines
5.8 KiB
Markdown
128 lines
5.8 KiB
Markdown
# CombatNode Architecture
|
||
|
||
最后更新：2026-03-02
|
||
|
||
## 1. 总览
|
||
CombatNode 当前分为三层：
|
||
- `CombatNodeComponent`：入口与关卡数据装配。
|
||
- `CombatScheduler`：战斗状态机与阶段推进，以及关卡内资源结算。
|
||
- `EnemyManager`：敌人系统 Facade（对外接口保持稳定，内部由多个子服务协作）。
|
||
|
||
本文重点记录 `EnemyManager` 与 `CombatScheduler` 的职责边界（尤其资源管理收口后的模型）。
|
||
|
||
## 2. EnemyManager 相关类
|
||
|
||
### 2.1 EnemyManager（Facade）
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyManager.cs`
|
||
|
||
职责：
|
||
- 对 `CombatScheduler` 提供统一接口：`OnInit / BeginPhase / OnUpdate / EndPhase / OnDestroy`。
|
||
- 编排敌人域子服务，不承载具体业务细节。
|
||
- 转发状态：`AliveEnemyCount`、`IsPhaseRunning`、`IsPhaseSpawnCompleted`。
|
||
- 处理敌人实体事件（Show/Hide）后的结果上报：
|
||
- 击杀：上报 `coin/gold` 到 `CombatScheduler.OnEnemyDefeatedRewardResolved(...)`
|
||
- 到家：上报 `baseDamage` 到 `CombatScheduler.OnEnemyReachedBase(...)`
|
||
|
||
不负责：
|
||
- 不直接维护刷怪时间轴。
|
||
- 不直接维护出生点缓存与路径查询。
|
||
- 不直接维护敌人追踪结构。
|
||
- 不直接维护掉落池抽样与背包库存。
|
||
- 不直接维护敌人配置兜底和血量倍率算法。
|
||
|
||
### 2.2 EnemySpawnDirector（刷怪时序）
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemySpawnDirector.cs`
|
||
|
||
职责：
|
||
- 管理 `DRLevelSpawnEntry` 的运行时实例（`SpawnEntryRuntime`）。
|
||
- 按时间推进 `Stream / Burst / Boss` 生成逻辑。
|
||
- 输出“当前应生成多少敌人”，通过回调交给 `EnemyManager.SpawnEnemies` 执行。
|
||
- 维护阶段刷怪状态：`IsPhaseRunning`、`IsPhaseSpawnCompleted`。
|
||
|
||
### 2.3 SpawnerResolver（出生点与路径）
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/SpawnerResolver.cs`
|
||
|
||
职责：
|
||
- 缓存当前地图可用 `Spawner`。
|
||
- 支持 `SpawnOrder` 映射与 fallback 轮询。
|
||
- 对外提供 `TryResolveSpawnPath(...)`，返回世界坐标路径点。
|
||
- 在地图切换时刷新缓存，避免每次刷怪全量扫描。
|
||
|
||
### 2.4 EnemyLifecycleTracker（敌人生命周期追踪）
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyLifecycleTracker.cs`
|
||
|
||
职责：
|
||
- 追踪本局敌人 `entityId -> DREnemy`。
|
||
- 维护 `AliveEnemyCount`。
|
||
- 处理 `ShowSuccess / ShowFailure / HideComplete` 对追踪状态的变更。
|
||
- 提供批量导出 tracked ids，用于 `CleanupTrackedEnemies` 清场。
|
||
|
||
### 2.5 EnemyConfigService（敌人配置与倍率）
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/EnemyManager/EnemyConfigService.cs`
|
||
|
||
职责：
|
||
- 读取 `DREnemy`，处理默认配置兜底。
|
||
- 计算循环周目下的基础血量倍率（按 `displayPhaseIndex / phaseCount` 推导 loop）。
|
||
- 缓存数据表引用并在 `Reset` 时清理。
|
||
|
||
## 3. CombatScheduler 资源收口
|
||
|
||
### 3.1 CombatResourceManager（关卡内资源统一管理）
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatResourceManager.cs`
|
||
|
||
职责：
|
||
- 统一维护关卡内资源状态：
|
||
- `GainedCoin`、`GainedGold`
|
||
- `BackpackInventoryData`（结算背包快照）
|
||
- 处理击杀奖励入账：`AddEnemyDefeatedReward(...)`
|
||
- 处理局外掉落抽样与物品构建：`TryRollOutGameItemDrop(...)`
|
||
- 对结算 UI 提供只读快照：`GetRewardInventorySnapshot()`
|
||
|
||
### 3.2 CombatScheduler 与资源类关系
|
||
文件：`Assets/GameMain/Scripts/CustomComponent/CombatNode/CombatScheduler/CombatScheduler.cs`
|
||
|
||
当前模型：
|
||
- `CombatScheduler` 持有 `_combatResourceManager`。
|
||
- `GainedCoin/GainedGold` 属性透传资源类。
|
||
- `OnEnemyDefeatedRewardResolved(...)` 统一触发：
|
||
- 货币入账
|
||
- 关卡内掉落判定
|
||
- `EnterFinishFlow(...)` 从资源类取 `BackpackInventoryData` 作为结算数据。
|
||
|
||
## 4. 协作流程（简版）
|
||
1. `CombatScheduler.BeginNextPhase()` 调 `EnemyManager.BeginPhase(...)`。
|
||
2. `EnemyManager` 刷新 `SpawnerResolver` 缓存，并通知 `EnemySpawnDirector.BeginPhase(...)`。
|
||
3. 每帧 `EnemyManager.OnUpdate(...)`：
|
||
- `SpawnerResolver.RefreshCache(...)`
|
||
- `EnemySpawnDirector.OnUpdate(..., SpawnEnemies)`
|
||
4. `SpawnEnemies(...)` 执行实际生成：
|
||
- `SpawnerResolver.TryResolveSpawnPath(...)`
|
||
- `EnemyConfigService.GetEnemyConfig(...)`
|
||
- `EnemyConfigService.ResolveScaledEnemyBaseHp(...)`
|
||
- `EnemyLifecycleTracker.TrackEnemy(...)`
|
||
- `GameEntry.Entity.ShowEnemy(...)`
|
||
5. 敌人回收时 `EnemyManager.OnHideEntityComplete(...)`：
|
||
- `EnemyLifecycleTracker.TryHandleHideComplete(...)`
|
||
- 若击杀：上报 `coin/gold` 给 `CombatScheduler.OnEnemyDefeatedRewardResolved(...)`
|
||
- 若到家：上报 `baseDamage` 给 `CombatScheduler.OnEnemyReachedBase(...)`
|
||
6. `CombatScheduler.OnEnemyDefeatedRewardResolved(...)`：
|
||
- `CombatResourceManager.AddEnemyDefeatedReward(...)`
|
||
- `CombatResourceManager.TryRollOutGameItemDrop(...)`
|
||
7. `CombatScheduler.EnterFinishFlow(...)`：
|
||
- 读取 `CombatResourceManager.GetRewardInventorySnapshot()`
|
||
- 打开结算 UI
|
||
|
||
## 5. 关键不变量
|
||
- 存活敌人数以 `EnemyLifecycleTracker.AliveEnemyCount` 为唯一真值来源。
|
||
- 刷怪阶段状态以 `EnemySpawnDirector` 为唯一真值来源。
|
||
- 关卡内资源以 `CombatResourceManager` 为唯一真值来源。
|
||
- `EnemyManager` 只做敌人域编排与结果上报，不再持有奖励库存。
|
||
- 清场必须只作用于本局 tracked 敌人，避免误伤其他实体。
|
||
|
||
## 6. 维护建议
|
||
- 新增刷怪类型：优先改 `EnemySpawnDirector`。
|
||
- 新增路径/出生规则：优先改 `SpawnerResolver`。
|
||
- 新增敌人追踪策略：优先改 `EnemyLifecycleTracker`。
|
||
- 新增敌人配置兜底或倍率策略：优先改 `EnemyConfigService`。
|
||
- 新增货币/掉落/结算背包规则：优先改 `CombatResourceManager`。
|