850 lines
36 KiB
Markdown
850 lines
36 KiB
Markdown
# 移除寻路库 / 敌人导航框架重构 实现计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 用约 200 行的"直接移动 + 地形夹紧"导航替换 405 行第三方寻路适配层，删除第三方寻路包（21,069 行）及对其源码的 4 处修改，同时收敛 3 处重复的卡死检测并修复 Pace 翻向缺陷。
|
||
|
||
**Architecture:** 可达性由 `EnemyMovement` 的墙/悬崖夹紧天然表达——"走过去、被夹停就是边界"，不重建任何图/段结构。导航接口从 20+ 成员瘦身为 7 成员的 `IEnemyNavigator`，地面/飞行两个实现；巡逻策略与 AI 决策层契约不变。
|
||
|
||
**Tech Stack:** Unity 2022.3、C#、NUnit EditMode（经 MCP `unity_testing_run_tests` 运行）。
|
||
|
||
**设计文档：** `Docs_Dev/superpowers/specs/2026-07-28-enemy-navigation-without-pathfinding-design.md`
|
||
|
||
**通用验证（每个 Task 都要做）：**
|
||
- **编译门**：MCP `unity_execute_menu_item("Assets/Refresh")` → 等约 10 秒 → `unity_get_compilation_errors`，预期 0 错误。
|
||
- **测试门**：MCP `unity_testing_run_tests({mode:"EditMode"})` → `unity_testing_get_job(jobId)`。**当前基线 191 条**，新增测试后基线上升（各 Task 注明）。
|
||
- **提交**：中文 + 类型前缀。每个 Task 独立提交。
|
||
|
||
**关键既有事实（已核实，可直接依赖）：**
|
||
- 硬依赖 `using PathBerserker2d` 的仅 **4 个文件**：`Navigation/EnemyNavAgent.cs`、`Editor/Enemies/Navigation/NavSurfaceBakeShortcut.cs`、`Editor/Scene/SceneObjectPlacerTool.cs`、`Editor/Scene/SceneScaffoldTools.cs`。其余文件仅在注释提及。
|
||
- `NavLinkType` / `INavLinkHandler` 是**项目自有抽象**，不含第三方类型。
|
||
- **Boss 代码完全不引用导航**（无 `.Nav`/`IPathAgent`/`MoveTo`/`Locomotion`），其预制体上的导航组件是冗余件。
|
||
- 敌人预制体除 `ENM_ChaoFeng` 外均已删除；场景敌人实例只有 `TestRoomA` 的 `ENM_CaoZhi`。
|
||
- ⚠ **同名陷阱**：`UI/MainMenu/DataDrivenMainMenuController.cs` 的 `Nav` 是 **UI 导航栈**，**不得改动**。
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
**新建：**
|
||
- `Assets/_Game/Scripts/Enemies/StallDetector.cs` — 推进停滞检测（纯逻辑 struct）
|
||
- `Assets/_Game/Scripts/Enemies/IEnemyNavigator.cs` — 新导航接口 + `NullEnemyNavigator`
|
||
- `Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs` — 地面直接移动导航
|
||
- `Assets/Tests/EditMode/Enemies/StallDetectorTests.cs`
|
||
- `Assets/Tests/EditMode/Enemies/GroundNavigatorLogicTests.cs`
|
||
|
||
**修改：** `EnemyLocomotion.cs`、`RushAbility.cs`、`EnemyBase.cs`、`EnemyLocomotionEditor.cs`、`FlyingDirectNavigator.cs`(→`FlyingNavigator.cs`)、2 个 asmdef、3 个编辑器脚本
|
||
|
||
**删除：** `IPathAgent.cs`、`Navigation/EnemyNavAgent.cs`、`Editor/Enemies/Navigation/NavSurfaceBakeShortcut.cs`、`Assets/PathBerserker2d/`
|
||
|
||
---
|
||
|
||
# 阶段 P0：修 Pace 翻向缺陷 + 收敛卡死检测
|
||
|
||
> 此阶段与寻路库无关，独立成立。完成后寻路库仍在。
|
||
|
||
## Task 1: `StallDetector` 纯逻辑 struct（TDD）
|
||
|
||
**Files:**
|
||
- Test: `Assets/Tests/EditMode/Enemies/StallDetectorTests.cs`
|
||
- Create: `Assets/_Game/Scripts/Enemies/StallDetector.cs`
|
||
|
||
- [ ] **Step 1: 先写失败测试**
|
||
|
||
创建 `Assets/Tests/EditMode/Enemies/StallDetectorTests.cs`：
|
||
```csharp
|
||
using NUnit.Framework;
|
||
using BaseGames.Enemies;
|
||
|
||
namespace BaseGames.Tests.EditMode.Enemies
|
||
{
|
||
/// <summary>
|
||
/// StallDetector：窗口内净位移不足即判停滞。
|
||
/// 该逻辑原本在 3 处各写一遍（巡逻 Pace / 导航层 / 冲锋），此处集中钉住行为。
|
||
/// </summary>
|
||
public class StallDetectorTests
|
||
{
|
||
const float Window = 0.5f, MinProgress = 0.05f;
|
||
|
||
[Test]
|
||
public void BeforeWindowElapses_NeverStalled()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
d.Reset(0f);
|
||
Assert.IsFalse(d.Tick(0f, 0.1f)); // 完全没动，但窗口未到
|
||
Assert.IsFalse(d.Tick(0f, 0.1f));
|
||
}
|
||
|
||
[Test]
|
||
public void NoProgressOverWindow_Stalled()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
d.Reset(0f);
|
||
Assert.IsFalse(d.Tick(0f, 0.4f));
|
||
Assert.IsTrue (d.Tick(0f, 0.2f)); // 累计 0.6s ≥ 窗口，净位移 0
|
||
}
|
||
|
||
[Test]
|
||
public void EnoughProgressOverWindow_NotStalled()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
d.Reset(0f);
|
||
Assert.IsFalse(d.Tick(1f, 0.6f)); // 位移 1m 远超阈值
|
||
}
|
||
|
||
[Test]
|
||
public void ProgressJustBelowThreshold_Stalled()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
d.Reset(0f);
|
||
Assert.IsTrue(d.Tick(0.04f, 0.6f)); // 0.04 < 0.05
|
||
}
|
||
|
||
[Test]
|
||
public void ProgressCountsBothDirections()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
d.Reset(0f);
|
||
Assert.IsFalse(d.Tick(-1f, 0.6f)); // 向左移动同样算推进
|
||
}
|
||
|
||
[Test]
|
||
public void AfterStalled_WindowRestartsFromCurrentPosition()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
d.Reset(0f);
|
||
Assert.IsTrue (d.Tick(0f, 0.6f)); // 第一次判停滞
|
||
Assert.IsFalse(d.Tick(0f, 0.1f)); // 窗口已重开，未到期
|
||
Assert.IsTrue (d.Tick(0f, 0.6f)); // 再次到期且仍无推进
|
||
}
|
||
|
||
[Test]
|
||
public void Reset_ClearsAccumulatedTime()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
d.Reset(0f);
|
||
d.Tick(0f, 0.4f);
|
||
d.Reset(0f); // 重开窗口
|
||
Assert.IsFalse(d.Tick(0f, 0.2f)); // 只累计了 0.2s
|
||
}
|
||
|
||
[Test]
|
||
public void WithoutReset_FirstTickInitializes()
|
||
{
|
||
var d = new StallDetector(Window, MinProgress);
|
||
Assert.IsFalse(d.Tick(5f, 1f)); // 未 Reset 时首帧只做初始化，不误判
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
MCP：`Assets/Refresh` → 等 10 秒 → `unity_get_compilation_errors`。
|
||
预期：**编译失败**，报 `StallDetector` 不存在。
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
创建 `Assets/_Game/Scripts/Enemies/StallDetector.cs`：
|
||
```csharp
|
||
using UnityEngine;
|
||
|
||
namespace BaseGames.Enemies
|
||
{
|
||
/// <summary>
|
||
/// 推进停滞检测：滑动窗口内的**净水平位移**不足阈值即判为停滞。
|
||
/// 用于"命令了移动却推不动"的兜底（撞上未纳入检测层的碰撞体、贴墙微抖等）。
|
||
///
|
||
/// <para>用净位移而非逐帧差值，避免"贴墙推进-被弹回"的微抖每帧重置计数。</para>
|
||
/// <para><b>调用方须以字段持有本结构</b>（struct 的方法会就地修改字段）；
|
||
/// 开始移动 / 更换目标后调用 <see cref="Reset"/> 重开窗口。</para>
|
||
/// </summary>
|
||
public struct StallDetector
|
||
{
|
||
private readonly float _windowSeconds;
|
||
private readonly float _minProgress;
|
||
private float _timer;
|
||
private float _startX;
|
||
private bool _initialized;
|
||
|
||
/// <param name="windowSeconds">判定窗口时长（秒）。</param>
|
||
/// <param name="minProgress">窗口内所需的最小净位移（米）。</param>
|
||
public StallDetector(float windowSeconds, float minProgress)
|
||
{
|
||
_windowSeconds = windowSeconds;
|
||
_minProgress = minProgress;
|
||
_timer = 0f;
|
||
_startX = 0f;
|
||
_initialized = false;
|
||
}
|
||
|
||
/// <summary>以当前位置重开窗口。</summary>
|
||
public void Reset(float currentX)
|
||
{
|
||
_startX = currentX;
|
||
_timer = 0f;
|
||
_initialized = true;
|
||
}
|
||
|
||
/// <summary>
|
||
/// 推进一帧。返回 true 表示本窗口内推进不足（停滞）；返回 true 后窗口自动以当前位置重开。
|
||
/// </summary>
|
||
public bool Tick(float currentX, float deltaTime)
|
||
{
|
||
if (!_initialized) { Reset(currentX); return false; }
|
||
|
||
_timer += deltaTime;
|
||
if (_timer < _windowSeconds) return false;
|
||
|
||
bool stalled = Mathf.Abs(currentX - _startX) < _minProgress;
|
||
_startX = currentX;
|
||
_timer = 0f;
|
||
return stalled;
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 编译门 + 测试**
|
||
|
||
预期 0 错误；EditMode **199 条**全绿（191 + 新增 8）。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/StallDetector.cs Assets/Tests/EditMode/Enemies/StallDetectorTests.cs
|
||
git commit -m "feat(enemy): 新增 StallDetector 推进停滞检测(+8 单测),为收敛三处重复实现做准备"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: 三处改用 `StallDetector` + 修复 Pace 翻向缺陷
|
||
|
||
**Files:**
|
||
- Modify: `Assets/_Game/Scripts/Enemies/Navigation/EnemyLocomotion.cs`
|
||
- Modify: `Assets/_Game/Scripts/Enemies/Abilities/RushAbility.cs`
|
||
- Modify: `Assets/_Game/Scripts/Enemies/Navigation/EnemyNavAgent.cs`
|
||
|
||
- [ ] **Step 1: `EnemyLocomotion` — Pace 改用 StallDetector 并修翻向**
|
||
|
||
字段区把 `_paceWindowStartX` / `_paceWindowFrames` 两个字段替换为：
|
||
```csharp
|
||
// Pace 推进停滞检测（原为 12 帧计数，@60fps ≈ 0.2s，改用统一原语并保持观感）
|
||
private StallDetector _paceStall = new StallDetector(0.2f, 0.05f);
|
||
```
|
||
|
||
把 `TickPatrol()` 的 `case PatrolStrategy.Pace:` 整段替换为：
|
||
```csharp
|
||
case PatrolStrategy.Pace: // 撞墙/悬崖翻向的来回踱步（速度驱动，不依赖 nav）
|
||
var mv = _enemy.Movement;
|
||
// 用与移动层夹紧同一判定(WouldBlockAhead，即时按请求方向+碰撞体前缘)，
|
||
// 保证"夹停在地形边缘"与"掉头"一致，不会夹停却不翻向。
|
||
bool blocked = mv != null && mv.WouldBlockAhead(_paceDir);
|
||
// 兜底卡死检测：命令前进但窗口内净位移过小(撞上未挂检测层的墙/卡角，含贴墙微抖)也视为受阻。
|
||
if (_paceStall.Tick(_enemy.transform.position.x, Time.deltaTime)) blocked = true;
|
||
|
||
// 翻向：首次受阻翻一次(边沿触发，天然消抖)；或"持续受阻但反方向畅通"也翻——
|
||
// 后者修复"顶着堵侧却因边沿触发失效而永远转不回来"的死锁。
|
||
// 两侧都堵(窄台)时只有边沿那一次翻向，之后保持，不来回抖。
|
||
bool oppositeFree = mv != null && !mv.WouldBlockAhead(-_paceDir);
|
||
if (blocked && (!_paceBlockedPrev || oppositeFree))
|
||
{
|
||
_paceDir = -_paceDir;
|
||
_paceStall.Reset(_enemy.transform.position.x); // 翻向后重开窗口
|
||
}
|
||
_paceBlockedPrev = blocked;
|
||
_enemy.MoveInDirection(_paceDir);
|
||
break;
|
||
```
|
||
|
||
- [ ] **Step 2: `RushAbility` — 内联停滞检测改用 StallDetector**
|
||
|
||
删除常量 `StuckWindowSeconds` / `StuckMinProgress`，改为字段：
|
||
```csharp
|
||
// 推进停滞检测（撞上未纳入墙层的碰撞体时兜底结束冲锋）
|
||
private StallDetector _stall = new StallDetector(0.15f, 0.05f);
|
||
```
|
||
`RushRoutine` 中删除 `winX` / `winT` 两个局部变量及其窗口判定块，改为：
|
||
```csharp
|
||
var body = _enemy.Body;
|
||
float elapsed = 0f;
|
||
_stall.Reset(_enemy.transform.position.x);
|
||
|
||
while (true)
|
||
{
|
||
if (body != null && body.HasPassed(lockX, dir)) break;
|
||
if (mv != null && mv.WouldHitWallAhead(dir)) break;
|
||
if (_cfg.maxDashDuration > 0f && elapsed >= _cfg.maxDashDuration) break;
|
||
|
||
_enemy.MoveInDirectionWithSpeed(dir, speed, allowLedgeCross: true);
|
||
yield return null;
|
||
|
||
float dt = Time.deltaTime;
|
||
elapsed += dt;
|
||
// 兜底：撞上未纳入墙层的碰撞体(玩家/边界墙)导致原地不动 → 结束本次冲锋
|
||
if (_stall.Tick(_enemy.transform.position.x, dt)) break;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: `EnemyNavAgent` — 段内推进停滞改用 StallDetector**
|
||
|
||
删除字段 `_stuckWinTimer` / `_stuckWinStartDist` / `_stuckWinInit`，改为：
|
||
```csharp
|
||
private StallDetector _segStall;
|
||
```
|
||
在 `Awake` 末尾初始化：
|
||
```csharp
|
||
_segStall = new StallDetector(_stuckWindowSeconds, _stuckMinProgress);
|
||
```
|
||
把 `TickStuckDetection(bool onSegment)` 整体替换为：
|
||
```csharp
|
||
// 卡死检测：段上移动时，窗口内净水平位移不足 → 判受阻（覆盖"障碍未进图"的物理空推）。
|
||
private void TickStuckDetection(bool onSegment)
|
||
{
|
||
if (!onSegment) { _segStall.Reset(transform.position.x); return; }
|
||
if (_segStall.Tick(transform.position.x, Time.fixedDeltaTime))
|
||
_obstructionSignal = true;
|
||
}
|
||
```
|
||
并把 `ResetStuckWindow()` 的实现改为 `_segStall.Reset(transform.position.x);`。
|
||
|
||
> 注：原实现比较的是"到子目标的距离缩小量"，新实现比较"净水平位移"。两者都用于识别"推不动"，
|
||
> 后者与另外两处统一且不依赖子目标；行为差异仅在"绕行时距离不减但确实在移动"的场景——
|
||
> 那种情况下**新实现更准确**（不会误判为卡死）。
|
||
|
||
- [ ] **Step 4: 编译门 + 测试**
|
||
|
||
预期 0 错误；EditMode **199 条**全绿。
|
||
|
||
- [ ] **Step 5: PlayMode 验证 Pace 修复**
|
||
|
||
进 Play，禁用 `ENM_CaoZhi` 的 `EnemyAiBrain`，用反射把 `_patrolStrategy` 设为 `Pace`，
|
||
把敌人放到平台左缘外侧悬空处（`center x = -22.30, y = 2.01`），`Locomotion.SetMode(Patrol)`。
|
||
预期：敌人**能掉头走回平台**（修复前会永久顶着崖外不动）。验证后 `unity_play_mode({action:"stop"})`。
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/Navigation/EnemyLocomotion.cs \
|
||
Assets/_Game/Scripts/Enemies/Abilities/RushAbility.cs \
|
||
Assets/_Game/Scripts/Enemies/Navigation/EnemyNavAgent.cs
|
||
git commit -m "refactor(enemy): 三处卡死检测收敛为 StallDetector;修复 Pace 持续受阻时无法掉头的死锁"
|
||
```
|
||
|
||
---
|
||
|
||
# 阶段 P1：新增 `IEnemyNavigator` 与 `GroundNavigator`（不动现有接线）
|
||
|
||
## Task 3: 新接口 `IEnemyNavigator` + `NullEnemyNavigator`
|
||
|
||
**Files:**
|
||
- Create: `Assets/_Game/Scripts/Enemies/IEnemyNavigator.cs`
|
||
|
||
- [ ] **Step 1: 创建接口文件**
|
||
|
||
```csharp
|
||
using UnityEngine;
|
||
|
||
namespace BaseGames.Enemies
|
||
{
|
||
/// <summary>
|
||
/// 敌人导航抽象：把"去某个世界点"的请求翻译为具体移动方式（地面沿地形走 / 飞行直取），
|
||
/// 并报告到达与受阻。
|
||
///
|
||
/// <para><b>不含任何路径图概念</b>——可达性由移动层的墙/悬崖夹紧天然决定：
|
||
/// 走得过去就是可达，被夹停的地方就是边界。</para>
|
||
///
|
||
/// 实现：<c>GroundNavigator</c>（地面）、<c>FlyingNavigator</c>（飞行）、
|
||
/// <see cref="NullEnemyNavigator"/>（无导航/测试）。
|
||
/// </summary>
|
||
public interface IEnemyNavigator
|
||
{
|
||
/// <summary>
|
||
/// 请求朝世界坐标移动。目标被记录后由实现逐帧驱动，**重复传入同一目标是幂等的**
|
||
/// （每帧调用或只在目标变化时调用皆可）。传入新目标会清除 <see cref="HasArrived"/> / <see cref="IsBlocked"/>。
|
||
/// </summary>
|
||
void MoveTowards(Vector2 target);
|
||
|
||
/// <summary>停止移动并清除当前目标。</summary>
|
||
void Stop();
|
||
|
||
/// <summary>设置移动速度（巡逻走速 / 追击跑速）。传 0 表示使用移动层配置的默认步速。</summary>
|
||
void SetSpeed(float speed);
|
||
|
||
/// <summary>当前是否正朝目标推进（有目标、未到达、未受阻）。</summary>
|
||
bool IsMoving { get; }
|
||
|
||
/// <summary>是否已到达目标（进入停止距离内）。</summary>
|
||
bool HasArrived { get; }
|
||
|
||
/// <summary>是否被地形挡住而无法继续靠近目标（墙 / 悬崖夹停 / 推进停滞）。</summary>
|
||
bool IsBlocked { get; }
|
||
|
||
/// <summary>取一个可供游走的目标点。取不到时返回 false。</summary>
|
||
bool TryPickWanderPoint(out Vector2 point);
|
||
}
|
||
|
||
/// <summary>无导航单位 / 测试用空实现：不移动，不报告到达或受阻。</summary>
|
||
public sealed class NullEnemyNavigator : IEnemyNavigator
|
||
{
|
||
public void MoveTowards(Vector2 _) { }
|
||
public void Stop() { }
|
||
public void SetSpeed(float _) { }
|
||
public bool IsMoving => false;
|
||
public bool HasArrived => false;
|
||
public bool IsBlocked => false;
|
||
public bool TryPickWanderPoint(out Vector2 point) { point = Vector2.zero; return false; }
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 编译门 + 测试**
|
||
|
||
预期 0 错误；EditMode 199 条全绿（新接口尚无人使用）。
|
||
|
||
- [ ] **Step 3: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/IEnemyNavigator.cs
|
||
git commit -m "feat(enemy): 新增 IEnemyNavigator 瘦身导航接口(7 成员)与 NullEnemyNavigator"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: `GroundNavigator` + 纯逻辑单测（TDD）
|
||
|
||
**Files:**
|
||
- Test: `Assets/Tests/EditMode/Enemies/GroundNavigatorLogicTests.cs`
|
||
- Create: `Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs`
|
||
|
||
- [ ] **Step 1: 先写失败测试**
|
||
|
||
```csharp
|
||
using NUnit.Framework;
|
||
using BaseGames.Enemies.Navigation;
|
||
|
||
namespace BaseGames.Tests.EditMode.Enemies
|
||
{
|
||
/// <summary>GroundNavigator 的方向/到达判定纯函数（无场景依赖）。</summary>
|
||
public class GroundNavigatorLogicTests
|
||
{
|
||
[Test]
|
||
public void Arrived_WhenWithinStopDistance()
|
||
=> Assert.IsTrue(GroundNavigator.Arrived(1.0f, 1.1f, 0.2f));
|
||
|
||
[Test]
|
||
public void Arrived_ExactlyAtStopDistance_True()
|
||
=> Assert.IsTrue(GroundNavigator.Arrived(1.0f, 1.2f, 0.2f));
|
||
|
||
[Test]
|
||
public void NotArrived_WhenOutsideStopDistance()
|
||
=> Assert.IsFalse(GroundNavigator.Arrived(1.0f, 1.5f, 0.2f));
|
||
|
||
[Test]
|
||
public void Arrived_IgnoresDirection()
|
||
{
|
||
Assert.IsTrue(GroundNavigator.Arrived(1.0f, 0.9f, 0.2f)); // 目标在左侧
|
||
Assert.IsFalse(GroundNavigator.Arrived(1.0f, 0.5f, 0.2f));
|
||
}
|
||
|
||
[Test]
|
||
public void WanderX_PositiveSign_LandsWithinForwardRange()
|
||
{
|
||
float x = GroundNavigator.WanderX(10f, 1.5f, 5f, +1f, 0f);
|
||
Assert.AreEqual(11.5f, x, 1e-4f); // t=0 → 最近端
|
||
x = GroundNavigator.WanderX(10f, 1.5f, 5f, +1f, 1f);
|
||
Assert.AreEqual(15f, x, 1e-4f); // t=1 → 最远端
|
||
}
|
||
|
||
[Test]
|
||
public void WanderX_NegativeSign_LandsWithinBackwardRange()
|
||
{
|
||
float x = GroundNavigator.WanderX(10f, 1.5f, 5f, -1f, 0f);
|
||
Assert.AreEqual(8.5f, x, 1e-4f);
|
||
x = GroundNavigator.WanderX(10f, 1.5f, 5f, -1f, 1f);
|
||
Assert.AreEqual(5f, x, 1e-4f);
|
||
}
|
||
|
||
[Test]
|
||
public void WanderX_MidT_Interpolates()
|
||
=> Assert.AreEqual(13.25f, GroundNavigator.WanderX(10f, 1.5f, 5f, +1f, 0.5f), 1e-4f);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**（`GroundNavigator` 不存在）
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
创建 `Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs`：
|
||
```csharp
|
||
using UnityEngine;
|
||
|
||
namespace BaseGames.Enemies.Navigation
|
||
{
|
||
/// <summary>
|
||
/// 地面单位导航：朝目标 X 直接行走，由 <see cref="EnemyMovement"/> 的墙/悬崖夹紧决定可达性。
|
||
///
|
||
/// <para><b>不做任何地形扫描</b>：走得过去就是可达，被夹停的地方就是边界。
|
||
/// 因此不存在"脱离导航图"这类状态——敌人无论被击退/冲锋到哪里，都能正常继续行走。</para>
|
||
///
|
||
/// <para>只驱动水平方向；垂直交给刚体重力。移动经 <see cref="EnemyMoveInput"/> 下发，
|
||
/// 速度为 0 时退化为移动层配置的步速。</para>
|
||
/// </summary>
|
||
[RequireComponent(typeof(EnemyMovement))]
|
||
public sealed class GroundNavigator : MonoBehaviour, IEnemyNavigator
|
||
{
|
||
[Header("到达判定")]
|
||
[Tooltip("身体中心 X 与目标 X 的距离小于此值即视为到达(m)")]
|
||
[SerializeField] [Min(0.01f)] private float _stoppingDistance = 0.2f;
|
||
|
||
[Header("游走取点（Wander 用）")]
|
||
[Tooltip("单次游走的最近距离(m)")]
|
||
[SerializeField] [Min(0f)] private float _wanderMinRange = 1.5f;
|
||
[Tooltip("单次游走的最远距离(m)。走不到会被地形夹停，自然结束本次游走。")]
|
||
[SerializeField] [Min(0f)] private float _wanderMaxRange = 5f;
|
||
|
||
[Header("推进停滞检测")]
|
||
[Tooltip("窗口时长(s)：此时长内净位移不足即判受阻")]
|
||
[SerializeField] [Min(0.05f)] private float _stallWindowSeconds = 0.4f;
|
||
[Tooltip("窗口内所需最小净位移(m)")]
|
||
[SerializeField] [Min(0f)] private float _stallMinProgress = 0.05f;
|
||
|
||
private EnemyBase _enemy;
|
||
private EnemyMovement _movement;
|
||
private StallDetector _stall;
|
||
|
||
private Vector2 _target;
|
||
private bool _hasTarget;
|
||
private float _speed; // 0 = 用移动层配置步速
|
||
private bool _arrived;
|
||
private bool _blocked;
|
||
|
||
public bool IsMoving => _hasTarget && !_arrived && !_blocked;
|
||
public bool HasArrived => _arrived;
|
||
public bool IsBlocked => _blocked;
|
||
|
||
private void Awake()
|
||
{
|
||
_enemy = GetComponent<EnemyBase>();
|
||
_movement = GetComponent<EnemyMovement>();
|
||
_stall = new StallDetector(_stallWindowSeconds, _stallMinProgress);
|
||
if (_enemy == null)
|
||
Debug.LogError($"[GroundNavigator] {name} 找不到 EnemyBase，无法读取身体几何。", this);
|
||
}
|
||
|
||
// ── IEnemyNavigator ────────────────────────────────────────────
|
||
public void MoveTowards(Vector2 target)
|
||
{
|
||
// 幂等：同一目标重复调用不重置状态，避免每帧调用时永远清掉到达/受阻标志
|
||
if (_hasTarget && (target - _target).sqrMagnitude < 1e-6f) return;
|
||
_target = target;
|
||
_hasTarget = true;
|
||
_arrived = false;
|
||
_blocked = false;
|
||
_stall.Reset(BodyX);
|
||
}
|
||
|
||
public void Stop()
|
||
{
|
||
_hasTarget = false;
|
||
_arrived = false;
|
||
_blocked = false;
|
||
_enemy?.StopMovement();
|
||
}
|
||
|
||
public void SetSpeed(float speed) => _speed = Mathf.Max(0f, speed);
|
||
|
||
public bool TryPickWanderPoint(out Vector2 point)
|
||
{
|
||
float sign = Random.value < 0.5f ? -1f : 1f;
|
||
float x = WanderX(BodyX, _wanderMinRange, _wanderMaxRange, sign, Random.value);
|
||
point = new Vector2(x, transform.position.y);
|
||
return true; // 地面单位总能尝试；走不到会被夹停并置 IsBlocked
|
||
}
|
||
|
||
// ── 驱动 ───────────────────────────────────────────────────────
|
||
private float BodyX => _enemy != null ? _enemy.Body.Center.x : transform.position.x;
|
||
|
||
private void FixedUpdate()
|
||
{
|
||
if (!_hasTarget || _arrived || _blocked || _movement == null) return;
|
||
|
||
float bodyX = BodyX;
|
||
if (Arrived(bodyX, _target.x, _stoppingDistance))
|
||
{
|
||
_arrived = true;
|
||
_enemy?.StopMovement();
|
||
return;
|
||
}
|
||
|
||
float dir = Mathf.Sign(_target.x - bodyX);
|
||
|
||
// 地形夹紧即为"不可达边界"：着地时前方是墙或悬崖 → 本次移动到此为止
|
||
if (_movement.IsGrounded && _movement.WouldBlockAhead(dir))
|
||
{
|
||
_blocked = true;
|
||
_enemy?.StopMovement();
|
||
return;
|
||
}
|
||
|
||
_movement.PendingInput.MoveDir = dir;
|
||
_movement.PendingInput.MoveSpeed = _speed; // 0 → MoveHorizontal 用配置步速
|
||
_movement.PendingInput.WantStop = false;
|
||
|
||
// 兜底：命令了移动却推不动（撞上未纳入检测层的碰撞体等）
|
||
if (_stall.Tick(bodyX, Time.fixedDeltaTime))
|
||
{
|
||
_blocked = true;
|
||
_enemy?.StopMovement();
|
||
}
|
||
}
|
||
|
||
// ── 纯函数（便于无场景单测）──────────────────────────────────────
|
||
/// <summary>身体中心 X 是否已进入目标 X 的停止距离内。</summary>
|
||
public static bool Arrived(float currentX, float targetX, float stopDistance)
|
||
=> Mathf.Abs(targetX - currentX) <= stopDistance;
|
||
|
||
/// <summary>
|
||
/// 游走目标 X：自当前位置朝 <paramref name="sign"/> 方向，
|
||
/// 在 [minRange, maxRange] 区间内按插值系数 <paramref name="t"/>(0..1) 取点。
|
||
/// </summary>
|
||
public static float WanderX(float currentX, float minRange, float maxRange, float sign, float t)
|
||
=> currentX + sign * Mathf.Lerp(minRange, Mathf.Max(minRange, maxRange), Mathf.Clamp01(t));
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 编译门 + 测试**
|
||
|
||
预期 0 错误；EditMode **206 条**全绿（199 + 新增 7）。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/Navigation/GroundNavigator.cs \
|
||
Assets/Tests/EditMode/Enemies/GroundNavigatorLogicTests.cs
|
||
git commit -m "feat(enemy): 新增 GroundNavigator 地面直接移动导航(+7 纯函数单测)"
|
||
```
|
||
|
||
---
|
||
|
||
# 阶段 P2：消费者切换（唯一需重点比对行为的阶段）
|
||
|
||
## Task 5: `FlyingDirectNavigator` → `FlyingNavigator`（改接口）
|
||
|
||
**Files:**
|
||
- Rename: `Navigation/FlyingDirectNavigator.cs` → `Navigation/FlyingNavigator.cs`（连同 `.meta`，`git mv` 保 GUID）
|
||
- Modify: 重写为新接口
|
||
|
||
- [ ] **Step 1: 改名（保 GUID）**
|
||
|
||
```bash
|
||
cd Assets/_Game/Scripts/Enemies/Navigation
|
||
git mv FlyingDirectNavigator.cs FlyingNavigator.cs
|
||
git mv FlyingDirectNavigator.cs.meta FlyingNavigator.cs.meta
|
||
```
|
||
|
||
- [ ] **Step 2: 改类名与接口**
|
||
|
||
- 类声明改为 `public sealed class FlyingNavigator : MonoBehaviour, IEnemyNavigator`
|
||
- **删除**：4 个事件（`OnLinkStarted`/`OnLinkCompleted`/`OnNavPathFailed`/`OnGoalReached`）、
|
||
`IsOnLink`/`CurrentLinkType`/`CurrentLinkStart`/`CurrentLinkEnd`、`LastMoveObstructed`、
|
||
`TryGetClosestReachable`、`IsNearEdge`、`CanReach`、`WalkToRandomOnSegment`、`ResolveStandablePoint`、
|
||
以及 `_goalFired` 字段。
|
||
- **改名**：`RequestMoveTo` → `MoveTowards`（新增幂等判断）、`StopNavigation` → `Stop`、
|
||
`IsAtDestination()` → `HasArrived` 属性、`WalkToRandom()` → `TryPickWanderPoint(out Vector2)`。
|
||
- **新增**：`public bool IsBlocked => false;`（飞行直取，无地形阻挡概念）
|
||
- `UpdateChase()` 中原先触发 `OnGoalReached` 的分支，改为置 `_arrived = true`。
|
||
- 状态字段改为：`Vector2 _target; bool _hasTarget; bool _arrived;`，
|
||
`IsMoving => _hasTarget && !_arrived;`
|
||
- 悬停逻辑（`UpdateHover`）与朝向逻辑**保持不变**。
|
||
|
||
- [ ] **Step 3: 编译门 + 测试** → 0 错误、206 条全绿
|
||
|
||
- [ ] **Step 4: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/Navigation/
|
||
git commit -m "refactor(enemy): FlyingDirectNavigator 改名 FlyingNavigator 并切换到 IEnemyNavigator"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 6: `EnemyBase` / `EnemyLocomotion` / 编辑器面板切换到新接口
|
||
|
||
**Files:**
|
||
- Modify: `Enemies/EnemyBase.cs`、`Enemies/Navigation/EnemyLocomotion.cs`、`Editor/Enemies/EnemyLocomotionEditor.cs`
|
||
|
||
- [ ] **Step 1: `EnemyBase` 换类型**
|
||
|
||
- 字段：`protected IPathAgent _nav;` → `protected IEnemyNavigator _nav;`
|
||
- 属性：`public IPathAgent Nav => _nav;` → `public IEnemyNavigator Nav => _nav;`
|
||
- `Awake`：`_nav = GetComponent<IPathAgent>() ?? new NullPathAgent();`
|
||
→ `_nav = GetComponent<IEnemyNavigator>() ?? new NullEnemyNavigator();`
|
||
- 更新类头注释中提到 `IPathAgent` 的措辞。
|
||
- `MoveTo(Vector2)` 内部对 `_nav.RequestMoveTo` 的调用改为 `_nav.MoveTowards`；
|
||
`StopMovement()` 内对 `_nav.StopNavigation()` 的调用改为 `_nav.Stop()`（按实际代码定位）。
|
||
|
||
- [ ] **Step 2: `EnemyLocomotion` — Wander 改用新接口**
|
||
|
||
`TickWander()` 整体替换为：
|
||
```csharp
|
||
/// <summary>
|
||
/// 就近随机游走：朝随机取的目标点走，**到达或被地形夹停**即视为本次游走结束，
|
||
/// 停顿 [_wanderPauseMin, _wanderPauseMax] 秒（期间播 Idle）后再挑下一个点。
|
||
/// 走到平台边缘停下转身是预期表现——可达性由移动层夹紧决定，不做地形扫描。
|
||
/// </summary>
|
||
private void TickWander()
|
||
{
|
||
var nav = _enemy.Nav;
|
||
if (nav == null) return;
|
||
|
||
// 仍在推进：清停顿态，等到达/受阻
|
||
if (nav.IsMoving) { _wanderPausing = false; return; }
|
||
|
||
// 到达、受阻或尚未出发：先停顿计时，再挑下一个点
|
||
if (!_wanderPausing)
|
||
{
|
||
_wanderPausing = true;
|
||
_wanderPauseTimer = Random.Range(_wanderPauseMin, Mathf.Max(_wanderPauseMin, _wanderPauseMax));
|
||
}
|
||
|
||
_wanderPauseTimer -= Time.deltaTime;
|
||
if (_wanderPauseTimer <= 0f)
|
||
{
|
||
_wanderPausing = false;
|
||
if (nav.TryPickWanderPoint(out var point)) nav.MoveTowards(point);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: `EnemyLocomotion` — Waypoints 去掉吸附**
|
||
|
||
- 删除字段 `_wpResolvedGoal` 的"吸附"语义相关：保留 `_wpResolvedGoal` 作为**当前路点坐标**缓存，
|
||
删除 `_wpResolveOk` 字段及其 `DebugResolveOk` 只读属性。
|
||
- `SetWaypointGoal()` 替换为：
|
||
```csharp
|
||
/// <summary>取当前路点坐标并出发。路点若摆在崖外/墙后，敌人会走到边缘被夹停 → IsBlocked → 结算推进下一个。</summary>
|
||
private void SetWaypointGoal()
|
||
{
|
||
_wpResolvedGoal = _waypoints[_wpIndex].position;
|
||
_enemy.Nav?.MoveTowards(_wpResolvedGoal);
|
||
}
|
||
```
|
||
- `case PatrolStrategy.Waypoints:` 中：
|
||
- `bool obstructedSettled = nav != null && nav.LastMoveObstructed && !nav.IsMoving;`
|
||
→ `bool obstructedSettled = nav != null && nav.IsBlocked;`
|
||
- 末尾的 `else if (nav != null && !nav.IsMoving && !nav.LastMoveObstructed) { _enemy.MoveTo(_wpResolvedGoal); }`
|
||
→ 改为 `else if (nav != null && !nav.IsMoving && !nav.IsBlocked && !nav.HasArrived) { nav.MoveTowards(_wpResolvedGoal); }`
|
||
|
||
- [ ] **Step 4: `EnemyLocomotion` — Approach/Pursue 改用新接口**
|
||
|
||
`Pursue(Vector2)` 与 `MoveTo(Vector2)`、`Update()` 中 `LocomotionMode.Approach` 分支里
|
||
对 `_enemy.MoveTo(...)` 的调用保持不变（`EnemyBase.MoveTo` 内部已在 Step 1 改为 `MoveTowards`）。
|
||
|
||
- [ ] **Step 5: `EnemyLocomotionEditor` — 调试面板去掉导航图信息**
|
||
|
||
- 第 127 行替换为：
|
||
```csharp
|
||
sb.AppendLine($"Nav 类型: {nav.GetType().Name} IsMoving: {nav.IsMoving} HasArrived: {nav.HasArrived} IsBlocked: {nav.IsBlocked}");
|
||
```
|
||
- **删除**：第 128–133 行（`EnemyNavAgent`/`RawNavAgent`/`HasValidPosition` 相关块）、
|
||
第 139 行 `_maxSnapDistance` 行及 `ReadMaxSnap` 方法、
|
||
Waypoints 段中 `CanReach` 与"路点逐个吸附检测"整块（第 152–171 行）、
|
||
以及 `Diagnose(...)` 里所有引用已删成员之处（按编译错误逐个修正）。
|
||
- Waypoints 段保留：当前索引/ArriveRadius/当前目标/到目标距离。
|
||
|
||
- [ ] **Step 6: 编译门 + 测试** → 0 错误、206 条全绿
|
||
|
||
- [ ] **Step 7: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/EnemyBase.cs \
|
||
Assets/_Game/Scripts/Enemies/Navigation/EnemyLocomotion.cs \
|
||
Assets/_Game/Scripts/Editor/Enemies/EnemyLocomotionEditor.cs
|
||
git commit -m "refactor(enemy): 消费者切换到 IEnemyNavigator(Wander/Waypoints 去导航图化,调试面板简化)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 7: 场景敌人换装 `GroundNavigator` + PlayMode 全面验收
|
||
|
||
**Files:** 场景 `TestRoomA`（不提交场景改动，除非用户要求）
|
||
|
||
- [ ] **Step 1: 换装组件**
|
||
|
||
MCP `unity_execute_code`：对 `ENM_CaoZhi`
|
||
- `DestroyImmediate` 掉 `EnemyNavAgent`、PB2d `NavAgent`、`TransformBasedMovement` 三个组件
|
||
- `AddComponent<GroundNavigator>()`
|
||
- 打印确认 `EnemyBase.Nav` 类型为 `GroundNavigator`（需重进 Play 让 Awake 重取）
|
||
|
||
- [ ] **Step 2: 三种巡逻验收**
|
||
|
||
进 Play，禁用 AI 大脑，逐一切换 `_patrolStrategy` 并观察 4 秒：
|
||
| 策略 | 预期 |
|
||
|---|---|
|
||
| Wander | 位移 > 0；走到平台边缘停下 → 停顿 → 反向再走；**动画为 Move（不再卡 Idle）** |
|
||
| Pace | 正常来回；顶到崖沿能掉头 |
|
||
| Waypoints | 依次推进路点；路点够不着时受阻结算并推进下一个 |
|
||
|
||
- [ ] **Step 3: 追击与冲锋验收**
|
||
|
||
- 启用 AI 大脑，玩家放到同平台 → 敌人应能追击并进入攻击（ApproachAttack）
|
||
- 玩家跳到够不着的位置 → 敌人走到边缘停下（**不卡死、不原地踏步**）
|
||
- 触发 `e001_chase` 冲锋 → 越过锁定点即停、可冲下悬崖、收尾不悬空
|
||
|
||
- [ ] **Step 4: 退出 Play，确认 Console 无新增报错**
|
||
|
||
- [ ] **Step 5: 记录结果**
|
||
|
||
把验收结论写入 `Docs_Dev/Verification/`（沿用现有验证文档风格）并提交该文档。
|
||
|
||
---
|
||
|
||
# 阶段 P3–P5：清理
|
||
|
||
## Task 8: Boss 预制体移除冗余导航组件
|
||
|
||
- [ ] **Step 1:** 打开 `Assets/_Game/Prefabs/Enemies/ChaoFeng/ENM_ChaoFeng.prefab`，
|
||
移除 `NavAgent`、`TransformBasedMovement`、`EnemyNavAgent`（已核实 Boss 代码不引用导航）。
|
||
- [ ] **Step 2:** 编译门 + 测试；PlayMode 快速确认 Boss 预制体可正常实例化（无 Missing 组件报错）。
|
||
- [ ] **Step 3:** 提交预制体改动。
|
||
|
||
## Task 9: 删除 `EnemyNavAgent`、`IPathAgent` 与编辑器中的寻路库用法
|
||
|
||
- [ ] **Step 1:** 删除 `Assets/_Game/Scripts/Enemies/Navigation/EnemyNavAgent.cs`（+`.meta`）
|
||
与 `Assets/_Game/Scripts/Enemies/IPathAgent.cs`（+`.meta`）。
|
||
> `NavLinkType` / `INavLinkHandler` 若仍被 `EnemyMovement`/`BlinkStrikeAbility` 使用则**保留**——
|
||
> 把 `NavLinkType` 枚举移入 `INavLinkHandler.cs`。
|
||
- [ ] **Step 2:** 删除 `Assets/_Game/Scripts/Editor/Enemies/Navigation/NavSurfaceBakeShortcut.cs`（+`.meta`）。
|
||
- [ ] **Step 3:** `SceneObjectPlacerTool.cs` / `SceneScaffoldTools.cs`：删除 `using PathBerserker2d;`
|
||
与所有放置 `NavAgent`/`TransformBasedMovement`/`NavSurface` 的代码；敌人放置改为 `AddComponent<GroundNavigator>()`；
|
||
删除 `PlaceNavSurface` 菜单项。
|
||
- [ ] **Step 4:** 两个 asmdef 移除对 PathBerserker 的引用：
|
||
`BaseGames.Editor.asmdef`、`BaseGames.Enemies.Navigation.asmdef`。
|
||
- [ ] **Step 5:** 编译门 + 测试 → 0 错误、206 条全绿。
|
||
- [ ] **Step 6:** 提交。
|
||
|
||
## Task 10: 删除第三方寻路包
|
||
|
||
- [ ] **Step 1:** 确认 `grep -rn "PathBerserker2d" Assets/_Game Assets/Tests --include=*.cs` **无输出**。
|
||
- [ ] **Step 2:** 场景中删除导航面物体（`TestRoomA` 的 NavSurface 所在 GameObject）。
|
||
- [ ] **Step 3:** 删除 `Assets/PathBerserker2d/` 整目录（含 `.meta`）。
|
||
- [ ] **Step 4:** 编译门 + 测试 → 0 错误、206 条全绿；PlayMode 冒烟：敌人巡逻/追击/冲锋均正常。
|
||
- [ ] **Step 5:** 提交（提交信息注明删除行数）。
|
||
|
||
---
|
||
|
||
## 自检记录（写计划时）
|
||
|
||
- **Spec 覆盖**：§5 接口→Task 3；§6.1 地面实现→Task 4；§6.2 飞行→Task 5；§6.3 Null→Task 3；
|
||
§7 巡逻/追击→Task 6；§7.1 Pace 修复→Task 2；§8 StallDetector→Task 1+2；
|
||
§9.1 消费者→Task 6；§9.2 删除清单→Task 8/9/10；§12 测试→Task 1/4 单测 + 各 Task 回归 + Task 7 PlayMode；
|
||
§13 阶段→Task 1–10 分组。**无遗漏**。
|
||
- **占位符扫描**：无 TBD；新文件均给出完整代码；修改处给出替换后的完整代码或精确删除清单。
|
||
- **类型一致性**：`IEnemyNavigator` 7 成员（`MoveTowards`/`Stop`/`SetSpeed`/`IsMoving`/`HasArrived`/`IsBlocked`/`TryPickWanderPoint`）
|
||
在 Task 3 定义，Task 4/5/6 用法一致；`StallDetector(windowSeconds, minProgress)` + `Reset(x)` + `Tick(x, dt)`
|
||
在 Task 1 定义，Task 2/4 用法一致；`GroundNavigator.Arrived/WanderX` 静态签名与测试一致。
|
||
- **测试基线**：191 → Task 1 后 199 → Task 4 后 206，其后不再新增。
|