527 lines
23 KiB
Markdown
527 lines
23 KiB
Markdown
# 角色身体碰撞体唯一权威源（IEnemyBody）实现计划
|
||
|
||
> **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:** 把散落在 `EnemyMovement` 里 4 处重复的"身体碰撞体解析"与各处身体尺寸取用，收敛为 `EnemyBase` 持有、经 `IEnemyBody` 接口暴露的唯一权威源。
|
||
|
||
**Architecture:** 新增纯 C# 类 `EnemyBody`（实现 `IEnemyBody`，懒解析碰撞体、实时读 bounds、方向判定抽为 static 纯函数便于单测）；`EnemyBase` 持有它并按 `_bodyCollider → 根 Collider2D` 顺序解析，缺失时显式报错；`EnemyMovement` 的 5 处探测与 `EdgeSafeMargin` 全部改走该接口，删除自己的 `_groundCheckCollider` 字段与 `GroundColliderOrSelf()`。
|
||
|
||
**Tech Stack:** Unity 2022.3、C#、NUnit EditMode 测试（Unity Test Runner，经 MCP `unity_testing_run_tests` 运行）。
|
||
|
||
**设计文档：** `Docs_Dev/superpowers/specs/2026-07-27-enemy-body-authority-design.md`
|
||
|
||
**通用验证方式（每个 Task 都要做）：**
|
||
- **编译门**：改 C# 后先 MCP `unity_execute_menu_item("Assets/Refresh")`，等约 8 秒，再 `unity_get_compilation_errors`，预期 0 错误。
|
||
- **测试门**：MCP `unity_testing_run_tests({mode:"EditMode"})` → `unity_testing_get_job(jobId)`，**基线 177 条全绿**（本计划新增测试后基线上升，见各 Task）。
|
||
- **提交**：中文 + 类型前缀（`feat(enemy):` / `refactor(enemy):` / `test(enemy):`）。
|
||
- **重要**：本计划触及所有敌人共用的移动探测路径，**每个 Task 结束都必须跑全量 EditMode**，不能只跑新增测试。
|
||
|
||
**关键既有事实（已核实，实现时可直接依赖）：**
|
||
- `EnemyBase` 已有 `protected virtual void OnValidate()`（`EnemyBase.cs:758`，`#if UNITY_EDITOR` 内），
|
||
开头是 `if (SuppressValidationWarnings) return;` —— **不要新增第二个 `OnValidate`**。
|
||
- `EnemyBase.Awake` 在 `EnemyBase.cs:531-552` 一带做组件收集与 `Debug.Assert` 校验。
|
||
- `EnemyMovement._groundCheckCollider`（`EnemyMovement.cs:46`）在 `ENM_CaoZhi`（场景）与
|
||
`ENM_ChaoFeng`（预制体）上**实测均为 null** → 删除它不改变现有行为。
|
||
- `EnemyMovement` 目前**不持有** `EnemyBase` 引用，需要新增懒获取。
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
**新建：**
|
||
- `Assets/_Game/Scripts/Enemies/EnemyBody.cs` — `IEnemyBody` 接口 + `EnemyBody` 实现（唯一职责：身体几何查询）。
|
||
- `Assets/Tests/EditMode/Enemies/EnemyBodyTests.cs` — 方向纯函数单测。
|
||
|
||
**修改：**
|
||
- `Assets/_Game/Scripts/Enemies/EnemyBase.cs` — `_bodyCollider` 字段、`Body` 属性、`Awake` 校验、扩展既有 `OnValidate`。
|
||
- `Assets/_Game/Scripts/Enemies/EnemyMovement.cs` — 5 处探测改走 `Body`、`EdgeSafeMargin` 改组合、删字段与私有方法。
|
||
|
||
---
|
||
|
||
## Task 1: `IEnemyBody` 接口与 `EnemyBody` 实现（含纯函数单测，TDD）
|
||
|
||
**Files:**
|
||
- Test: `Assets/Tests/EditMode/Enemies/EnemyBodyTests.cs`
|
||
- Create: `Assets/_Game/Scripts/Enemies/EnemyBody.cs`
|
||
|
||
- [ ] **Step 1: 先写失败测试**
|
||
|
||
创建 `Assets/Tests/EditMode/Enemies/EnemyBodyTests.cs`：
|
||
```csharp
|
||
using NUnit.Framework;
|
||
using BaseGames.Enemies;
|
||
|
||
namespace BaseGames.Tests.EditMode.Enemies
|
||
{
|
||
/// <summary>
|
||
/// EnemyBody 方向相关纯函数测试（无场景依赖）。
|
||
/// 这三个函数的左右符号最易写反，故对两个方向与边界相等情形都做断言。
|
||
/// </summary>
|
||
public class EnemyBodyTests
|
||
{
|
||
// 身体占据 [2, 4]，中心 3，半宽 1
|
||
const float MinX = 2f, MaxX = 4f;
|
||
|
||
[Test]
|
||
public void FrontEdge_Right_IsMaxX()
|
||
=> Assert.AreEqual(MaxX, EnemyBody.FrontEdge(MinX, MaxX, 1f));
|
||
|
||
[Test]
|
||
public void FrontEdge_Left_IsMinX()
|
||
=> Assert.AreEqual(MinX, EnemyBody.FrontEdge(MinX, MaxX, -1f));
|
||
|
||
[Test]
|
||
public void FrontEdge_ZeroDir_TreatedAsRight()
|
||
=> Assert.AreEqual(MaxX, EnemyBody.FrontEdge(MinX, MaxX, 0f));
|
||
|
||
[Test]
|
||
public void RearEdge_Right_IsMinX()
|
||
=> Assert.AreEqual(MinX, EnemyBody.RearEdge(MinX, MaxX, 1f));
|
||
|
||
[Test]
|
||
public void RearEdge_Left_IsMaxX()
|
||
=> Assert.AreEqual(MaxX, EnemyBody.RearEdge(MinX, MaxX, -1f));
|
||
|
||
[Test]
|
||
public void RearEdge_ZeroDir_TreatedAsRight()
|
||
=> Assert.AreEqual(MinX, EnemyBody.RearEdge(MinX, MaxX, 0f));
|
||
|
||
// ── BodyPassed：向右 ─────────────────────────────────────────────
|
||
[Test]
|
||
public void BodyPassed_Right_NotReached_False()
|
||
=> Assert.IsFalse(EnemyBody.BodyPassed(MinX, MaxX, 5f, 1f)); // 目标在身体右侧外
|
||
|
||
[Test]
|
||
public void BodyPassed_Right_OverlappingTarget_False()
|
||
=> Assert.IsFalse(EnemyBody.BodyPassed(MinX, MaxX, 3f, 1f)); // 目标仍在身体内，未整体越过
|
||
|
||
[Test]
|
||
public void BodyPassed_Right_ExactlyAtRearEdge_True()
|
||
=> Assert.IsTrue(EnemyBody.BodyPassed(MinX, MaxX, 2f, 1f)); // 后缘恰好等于目标 = 已越过
|
||
|
||
[Test]
|
||
public void BodyPassed_Right_FullyPassed_True()
|
||
=> Assert.IsTrue(EnemyBody.BodyPassed(MinX, MaxX, 1f, 1f));
|
||
|
||
// ── BodyPassed：向左 ─────────────────────────────────────────────
|
||
[Test]
|
||
public void BodyPassed_Left_NotReached_False()
|
||
=> Assert.IsFalse(EnemyBody.BodyPassed(MinX, MaxX, 1f, -1f)); // 目标在身体左侧外
|
||
|
||
[Test]
|
||
public void BodyPassed_Left_OverlappingTarget_False()
|
||
=> Assert.IsFalse(EnemyBody.BodyPassed(MinX, MaxX, 3f, -1f));
|
||
|
||
[Test]
|
||
public void BodyPassed_Left_ExactlyAtRearEdge_True()
|
||
=> Assert.IsTrue(EnemyBody.BodyPassed(MinX, MaxX, 4f, -1f)); // 后缘(max)恰好等于目标
|
||
|
||
[Test]
|
||
public void BodyPassed_Left_FullyPassed_True()
|
||
=> Assert.IsTrue(EnemyBody.BodyPassed(MinX, MaxX, 5f, -1f));
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
MCP：`unity_execute_menu_item("Assets/Refresh")` → 等 8 秒 → `unity_get_compilation_errors`。
|
||
预期：**编译失败**，报 `EnemyBody` 不存在（`CS0103`/`CS0246`）。
|
||
|
||
- [ ] **Step 3: 实现 `EnemyBody.cs`**
|
||
|
||
创建 `Assets/_Game/Scripts/Enemies/EnemyBody.cs`：
|
||
```csharp
|
||
using UnityEngine;
|
||
|
||
namespace BaseGames.Enemies
|
||
{
|
||
/// <summary>
|
||
/// 角色身体碰撞体的唯一权威查询口。
|
||
/// 几何实时取自碰撞体 bounds（随位置/动画变化，不缓存数值），仅缓存碰撞体引用。
|
||
/// 唯一数据源见 <see cref="EnemyBase.Body"/>——其它组件不得自行解析身体碰撞体。
|
||
/// </summary>
|
||
public interface IEnemyBody
|
||
{
|
||
Collider2D Collider { get; }
|
||
/// <summary>世界空间包围盒；实时查询。</summary>
|
||
Bounds Bounds { get; }
|
||
float Width { get; }
|
||
float Height { get; }
|
||
float HalfWidth { get; }
|
||
float HalfHeight { get; }
|
||
Vector2 Center { get; }
|
||
/// <summary>脚底中点 (center.x, min.y)。</summary>
|
||
Vector2 FootPoint { get; }
|
||
|
||
/// <summary>朝 <paramref name="dir"/> 的前缘 X（dir≥0 取 max.x，否则 min.x）。</summary>
|
||
float FrontEdgeX(float dir);
|
||
/// <summary>朝 <paramref name="dir"/> 的后缘 X（前缘的相反侧）。</summary>
|
||
float RearEdgeX(float dir);
|
||
/// <summary>
|
||
/// 身体是否已**整体**越过世界 X 坐标：
|
||
/// dir≥0 时后缘(min.x) ≥ worldX；dir<0 时后缘(max.x) ≤ worldX。
|
||
/// </summary>
|
||
bool HasPassed(float worldX, float dir);
|
||
}
|
||
|
||
/// <summary>
|
||
/// <see cref="IEnemyBody"/> 的实现（纯 C# 类，非 MonoBehaviour）。
|
||
/// 懒解析碰撞体 → 编辑器模式（Gizmo / OnValidate，Awake 未执行）同样可用。
|
||
/// </summary>
|
||
public sealed class EnemyBody : IEnemyBody
|
||
{
|
||
private readonly GameObject _owner;
|
||
private readonly Collider2D _explicitCollider;
|
||
private Collider2D _resolved;
|
||
|
||
/// <param name="owner">宿主 GameObject（未显式指定碰撞体时从其上取 Collider2D）。</param>
|
||
/// <param name="explicitCollider">显式指定的身体碰撞体；可为 null。</param>
|
||
public EnemyBody(GameObject owner, Collider2D explicitCollider)
|
||
{
|
||
_owner = owner;
|
||
_explicitCollider = explicitCollider;
|
||
}
|
||
|
||
public Collider2D Collider
|
||
{
|
||
get
|
||
{
|
||
if (_explicitCollider != null) return _explicitCollider;
|
||
if (_resolved == null && _owner != null) _resolved = _owner.GetComponent<Collider2D>();
|
||
return _resolved;
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// 碰撞体缺失时返回以宿主位置为中心的零尺寸包围盒。
|
||
/// 该错误已由 <see cref="EnemyBase"/> 在 Awake/OnValidate 显式报出，此处不重复每帧刷屏。
|
||
/// </summary>
|
||
public Bounds Bounds
|
||
{
|
||
get
|
||
{
|
||
var col = Collider;
|
||
if (col != null) return col.bounds;
|
||
return new Bounds(_owner != null ? _owner.transform.position : Vector3.zero, Vector3.zero);
|
||
}
|
||
}
|
||
|
||
public float Width => Bounds.size.x;
|
||
public float Height => Bounds.size.y;
|
||
public float HalfWidth => Bounds.extents.x;
|
||
public float HalfHeight => Bounds.extents.y;
|
||
public Vector2 Center => Bounds.center;
|
||
public Vector2 FootPoint { get { var b = Bounds; return new Vector2(b.center.x, b.min.y); } }
|
||
|
||
public float FrontEdgeX(float dir) { var b = Bounds; return FrontEdge(b.min.x, b.max.x, dir); }
|
||
public float RearEdgeX (float dir) { var b = Bounds; return RearEdge (b.min.x, b.max.x, dir); }
|
||
public bool HasPassed(float worldX, float dir)
|
||
{
|
||
var b = Bounds;
|
||
return BodyPassed(b.min.x, b.max.x, worldX, dir);
|
||
}
|
||
|
||
// ── 方向纯函数（static，便于无场景依赖单测；符号最易写反，集中于此）──────
|
||
public static float FrontEdge(float minX, float maxX, float dir) => dir >= 0f ? maxX : minX;
|
||
public static float RearEdge (float minX, float maxX, float dir) => dir >= 0f ? minX : maxX;
|
||
public static bool BodyPassed(float minX, float maxX, float worldX, float dir)
|
||
=> dir >= 0f ? minX >= worldX : maxX <= worldX;
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 编译门 + 运行测试确认通过**
|
||
|
||
MCP：`Assets/Refresh` → 等 8 秒 → `unity_get_compilation_errors`（预期 0 错误）
|
||
→ `unity_testing_run_tests({mode:"EditMode"})` → `unity_testing_get_job(jobId)`。
|
||
预期：**191 条全绿**（原 177 + 新增 14）。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/EnemyBody.cs Assets/Tests/EditMode/Enemies/EnemyBodyTests.cs
|
||
git commit -m "feat(enemy): 新增 IEnemyBody 身体几何权威接口与 EnemyBody 实现(+14 纯函数单测)"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 2: `EnemyBase` 持有权威源
|
||
|
||
**Files:**
|
||
- Modify: `Assets/_Game/Scripts/Enemies/EnemyBase.cs`
|
||
|
||
- [ ] **Step 1: 加序列化字段与 `Body` 属性**
|
||
|
||
在 `EnemyBase.cs` 的"子组件（Prefab Inspector 绑定）"Header 区块内、`_hurtBox` 字段之后（约 `EnemyBase.cs:44`）追加：
|
||
```csharp
|
||
|
||
[Header("身体碰撞体（唯一权威源）")]
|
||
[Tooltip("用于身体几何(宽高/边缘/探测起点)的碰撞体。留空 = 使用本物体上的 Collider2D。" +
|
||
"移动探测、导航内缩、冲刺终点等全部以此为准，不要在各处自行取碰撞体。")]
|
||
[SerializeField] private Collider2D _bodyCollider;
|
||
```
|
||
|
||
在 `_colliders` 字段声明附近（约 `EnemyBase.cs:70`）追加缓存字段：
|
||
```csharp
|
||
// 身体几何权威（懒创建；OnValidate 改引用后置空重建）
|
||
private EnemyBody _body;
|
||
```
|
||
|
||
在公开属性区（`Abilities` / `AttackSelector` 属性附近）追加：
|
||
```csharp
|
||
/// <summary>身体碰撞体几何的唯一权威查询口。移动/导航/能力一律经此获取身体尺寸。</summary>
|
||
public IEnemyBody Body => _body ??= new EnemyBody(gameObject, _bodyCollider);
|
||
```
|
||
|
||
- [ ] **Step 2: `Awake` 加运行期校验**
|
||
|
||
在 `EnemyBase.Awake` 中 `_colliders = GetComponentsInChildren<Collider2D>(true);`（约 `EnemyBase.cs:544`）之后追加：
|
||
```csharp
|
||
// 身体几何权威校验：解析不到碰撞体 → 显式报错（根因暴露，不静默兜底）
|
||
if (Body.Collider == null)
|
||
Debug.LogError($"[EnemyBase] {name} 找不到身体碰撞体：请在 Inspector 指定 _bodyCollider，" +
|
||
"或确保本物体上挂有 Collider2D。移动探测/导航内缩将不可用。", this);
|
||
```
|
||
|
||
- [ ] **Step 3: 扩展既有 `OnValidate`（不要新增第二个）**
|
||
|
||
`EnemyBase.cs:758` 已有 `protected virtual void OnValidate()`，把它改为：
|
||
```csharp
|
||
protected virtual void OnValidate()
|
||
{
|
||
_body = null; // 身体碰撞体引用可能在 Inspector 被改，缓存无条件失效（与警告抑制无关）
|
||
if (SuppressValidationWarnings) return;
|
||
if (_statsSO == null)
|
||
Debug.LogWarning($"[EnemyBase] {gameObject.name} 缺少 EnemyStatsSO 配置（运行时会 NullRef）。", this);
|
||
if (_stats == null)
|
||
Debug.LogWarning($"[EnemyBase] {gameObject.name} 未绑定 EnemyStats 组件引用。", this);
|
||
if (_animancer == null)
|
||
Debug.LogWarning($"[EnemyBase] {gameObject.name} 未绑定 AnimancerComponent 引用。", this);
|
||
if (_bodyCollider == null && GetComponent<Collider2D>() == null)
|
||
Debug.LogWarning($"[EnemyBase] {gameObject.name} 找不到身体碰撞体（未指定 _bodyCollider 且本物体无 Collider2D）。", this);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 编译门 + 全量测试**
|
||
|
||
MCP：`Assets/Refresh` → 等 8 秒 → `unity_get_compilation_errors`（预期 0 错误）
|
||
→ `unity_testing_run_tests({mode:"EditMode"})`。预期：**191 条全绿**。
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/EnemyBase.cs
|
||
git commit -m "feat(enemy): EnemyBase 持有身体几何权威(_bodyCollider + Body),Awake/OnValidate 双重校验"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 3: `EnemyMovement` 全部改走权威接口
|
||
|
||
**Files:**
|
||
- Modify: `Assets/_Game/Scripts/Enemies/EnemyMovement.cs`
|
||
|
||
> 本 Task 是行为等价重构：改完后巡逻/夹停/掉头行为必须与改前完全一致。
|
||
|
||
- [ ] **Step 1: 加 `EnemyBase` 懒获取与 `Body` 便捷属性**
|
||
|
||
在 `EnemyMovement` 类的私有字段区追加（放在 `_groundCheckCollider` 附近即可）：
|
||
```csharp
|
||
// 身体几何权威（EnemyBase.Body）。懒获取以支持编辑器模式(Awake 未执行)下的 Gizmo/探测预览。
|
||
private EnemyBase _enemy;
|
||
private IEnemyBody Body
|
||
{
|
||
get
|
||
{
|
||
if (_enemy == null) _enemy = GetComponent<EnemyBase>();
|
||
return _enemy != null ? _enemy.Body : null;
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 三个射线起点改用 `Body`**
|
||
|
||
把 `EnemyMovement.cs` 中这三个方法整体替换（原实现各自解析碰撞体，约在 185–229 行）：
|
||
```csharp
|
||
private Vector2 GetGroundRayOrigin(int index)
|
||
{
|
||
var body = Body;
|
||
if (body == null || body.Collider == null) return (Vector2)transform.position;
|
||
|
||
Bounds b = body.Bounds;
|
||
float x = _groundCheckCount <= 1
|
||
? b.center.x
|
||
: Mathf.Lerp(b.min.x, b.max.x, (float)index / (_groundCheckCount - 1));
|
||
return new Vector2(x, b.min.y);
|
||
}
|
||
|
||
private bool IsGroundedCheck()
|
||
{
|
||
for (int i = 0; i < _groundCheckCount; i++)
|
||
{
|
||
if (Physics2D.Raycast(GetGroundRayOrigin(i), Vector2.down, _groundCheckDist, _groundMask))
|
||
return true;
|
||
}
|
||
return false;
|
||
}
|
||
|
||
// 墙体射线起点：身体朝向侧边缘、中心高度
|
||
private Vector2 GetWallRayOrigin()
|
||
{
|
||
var body = Body;
|
||
if (body == null || body.Collider == null) return (Vector2)transform.position;
|
||
return new Vector2(body.FrontEdgeX(_facingDir), body.Bounds.center.y);
|
||
}
|
||
|
||
// 悬崖射线起点：身体前下角再向前偏移 _ledgeCheckFwdOffset
|
||
private Vector2 GetLedgeRayOrigin()
|
||
{
|
||
var body = Body;
|
||
if (body == null || body.Collider == null) return (Vector2)transform.position;
|
||
float sign = _facingDir >= 0 ? 1f : -1f;
|
||
return new Vector2(body.FrontEdgeX(_facingDir) + sign * _ledgeCheckFwdOffset, body.Bounds.min.y);
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 删除 `GroundColliderOrSelf()` 与 `_groundCheckCollider` 字段**
|
||
|
||
删除私有方法（原 `EnemyMovement.cs:231-232`）：
|
||
```csharp
|
||
private Collider2D GroundColliderOrSelf()
|
||
=> _groundCheckCollider != null ? _groundCheckCollider : GetComponent<Collider2D>();
|
||
```
|
||
删除序列化字段及其 `[Tooltip]`（原 `EnemyMovement.cs:45-46`）：
|
||
```csharp
|
||
[Tooltip("用于确定射线起点宽度和底边的 Collider2D；留空则 Awake 时自动查找")]
|
||
[SerializeField] private Collider2D _groundCheckCollider;
|
||
```
|
||
|
||
- [ ] **Step 4: 墙/悬崖判定与 `EdgeSafeMargin` 改用 `Body`**
|
||
|
||
替换这三个成员（原 `EnemyMovement.cs:243-278`）：
|
||
```csharp
|
||
/// <summary>朝 <paramref name="dir"/> 前缘水平方向是否有墙。</summary>
|
||
public bool WouldHitWallAhead(float dir)
|
||
{
|
||
var body = Body;
|
||
if (body == null || body.Collider == null || _wallCheckDist <= 0f) return false;
|
||
float sign = Mathf.Sign(dir);
|
||
return Physics2D.Raycast(new Vector2(body.FrontEdgeX(dir), body.Bounds.center.y),
|
||
new Vector2(sign, 0f), _wallCheckDist, _wallMask);
|
||
}
|
||
|
||
/// <summary>朝 <paramref name="dir"/> 前缘外是否为悬崖（脚边地面缺失，会让碰撞体越出地形边缘）。</summary>
|
||
public bool WouldFallAhead(float dir)
|
||
{
|
||
var body = Body;
|
||
if (body == null || body.Collider == null || _ledgeCheckDownDist <= 0f) return false;
|
||
float sign = Mathf.Sign(dir);
|
||
return !Physics2D.Raycast(
|
||
new Vector2(body.FrontEdgeX(dir) + sign * _ledgeCheckFwdOffset, body.Bounds.min.y),
|
||
Vector2.down, _ledgeCheckDownDist, _groundMask);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 身体中心到"能站住的平台边缘最近点"的水平安全余量 = 身体半宽 + 悬崖探测前向偏移。
|
||
/// 半宽取自唯一权威 <see cref="EnemyBase.Body"/>；探测偏移是本移动层自己的射线调参。
|
||
/// WouldFallAhead 在"身体前缘 + _ledgeCheckFwdOffset"处探地，故身体中心必须离平台边缘至少此距离，
|
||
/// 否则前缘探出崖沿被夹停。供 nav 段内随机游走/目标点吸附把点从段两端内缩此值。
|
||
/// </summary>
|
||
public float EdgeSafeMargin
|
||
{
|
||
get
|
||
{
|
||
var body = Body;
|
||
float halfWidth = body != null ? body.HalfWidth : 0f;
|
||
return halfWidth + Mathf.Max(0f, _ledgeCheckFwdOffset);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 确认没有遗漏的旧引用**
|
||
|
||
Grep 确认 `_groundCheckCollider` 与 `GroundColliderOrSelf` 在整个项目已无引用：
|
||
```bash
|
||
grep -rn "_groundCheckCollider\|GroundColliderOrSelf" Assets/_Game/Scripts
|
||
```
|
||
预期：**无输出**。若编辑器脚本（如 `EnemyLocomotionEditor`）引用了它们，一并改为 `Body`。
|
||
|
||
- [ ] **Step 6: 编译门 + 全量测试**
|
||
|
||
MCP：`Assets/Refresh` → 等 8 秒 → `unity_get_compilation_errors`（预期 0 错误）
|
||
→ `unity_testing_run_tests({mode:"EditMode"})`。预期：**191 条全绿**。
|
||
|
||
- [ ] **Step 7: 提交**
|
||
|
||
```bash
|
||
git add Assets/_Game/Scripts/Enemies/EnemyMovement.cs
|
||
git commit -m "refactor(enemy): 移动层探测与 EdgeSafeMargin 改走 Body 权威,删除重复的碰撞体解析"
|
||
```
|
||
|
||
---
|
||
|
||
## Task 4: PlayMode 行为等价性冒烟验证
|
||
|
||
**Files:** 无（场景内验证）
|
||
|
||
> 因两个现存敌人的 `_groundCheckCollider` 实测均为 null，本次重构后行为应**完全一致**。
|
||
> 本 Task 用于确认没有引入回归。
|
||
|
||
- [ ] **Step 1: 确认编辑器无新报错**
|
||
|
||
MCP `unity_console_log({type:"error", count:30})`：确认没有新增的
|
||
`[EnemyBase] ... 找不到身体碰撞体` 报错（`ENM_CaoZhi` 有根 BoxCollider2D，不该触发）。
|
||
|
||
- [ ] **Step 2: 进 Play 验证巡逻与夹停**
|
||
|
||
MCP `unity_play_mode({action:"play"})`，等约 5 秒后用 `unity_execute_code` 读取状态：
|
||
```csharp
|
||
var e = GameObject.Find("ENM_CaoZhi");
|
||
var mv = e.GetComponent<BaseGames.Enemies.EnemyMovement>();
|
||
var eb = e.GetComponent<BaseGames.Enemies.EnemyBase>();
|
||
return "grounded=" + mv.IsGrounded
|
||
+ "; halfWidth=" + eb.Body.HalfWidth.ToString("F3")
|
||
+ "; edgeSafeMargin=" + mv.EdgeSafeMargin.ToString("F3")
|
||
+ "; bodyCollider=" + (eb.Body.Collider != null ? eb.Body.Collider.GetType().Name : "NULL")
|
||
+ "; bounds=" + eb.Body.Bounds.ToString();
|
||
```
|
||
预期：`bodyCollider=BoxCollider2D`（非 NULL）、`halfWidth>0`、`edgeSafeMargin = halfWidth + 0.1`、
|
||
`grounded=True`（敌人站在平台上）。
|
||
|
||
- [ ] **Step 3: 验证敌人仍会被崖边夹停、不会掉下平台**
|
||
|
||
保持 Play，观察 `ENM_CaoZhi` 巡逻若干秒后再读一次：
|
||
```csharp
|
||
var e = GameObject.Find("ENM_CaoZhi");
|
||
var mv = e.GetComponent<BaseGames.Enemies.EnemyMovement>();
|
||
return "pos=" + e.transform.position.ToString("F2")
|
||
+ "; grounded=" + mv.IsGrounded
|
||
+ "; wallAhead=" + mv.IsWallAhead
|
||
+ "; ledgeAhead=" + mv.IsLedgeAhead;
|
||
```
|
||
预期：`grounded=True`（未掉出平台）；敌人位置在平台范围内。
|
||
|
||
- [ ] **Step 4: 退出 Play**
|
||
|
||
MCP `unity_play_mode({action:"stop"})`。确认 Console 无新增异常。
|
||
|
||
- [ ] **Step 5: 记录结果**
|
||
|
||
若全部通过，在提交信息或 `Docs_Dev/Verification/` 记一行验证结论。无代码改动则无需提交。
|
||
|
||
---
|
||
|
||
## 自检记录（写计划时）
|
||
|
||
- **Spec 覆盖**：spec §3.1 权威源→Task 2；§3.2 接口 + §3.3 实现→Task 1；§3.4 消费端改造表（`EnemyMovement`
|
||
5 处 + `EdgeSafeMargin` + 删字段/方法）→Task 3；§3.5 分层原则→Task 3 Step 4 的 `EdgeSafeMargin` 注释体现；
|
||
§4 边界与错误处理→Task 2 Step 2/3（Awake LogError + OnValidate 警告 + 抑制机制）、Task 1 Step 3（碰撞体缺失退化值）；
|
||
§5 测试→Task 1（单测）、Task 3 Step 6（回归）、Task 4（PlayMode）；§6 迁移安全→Task 4 验证。
|
||
**`EnemyNavAgent` 按 spec §3.4 明确不改**，故无对应 Task。
|
||
- **占位符扫描**：无 TBD/TODO；每个改动步骤都给了完整代码。
|
||
- **类型一致性**：`IEnemyBody` 成员（`Collider`/`Bounds`/`HalfWidth`/`FrontEdgeX`/`RearEdgeX`/`HasPassed`）
|
||
与 static 纯函数（`FrontEdge`/`RearEdge`/`BodyPassed`）在 Task 1 定义，Task 2（`Body.Collider`）、
|
||
Task 3（`Body.Bounds`/`Body.FrontEdgeX`/`Body.HalfWidth`）与测试中的用法一致。
|
||
- **测试基线**：当前 177 → Task 1 后 191（新增 14 条）；Task 2/3 不新增测试，仍应为 191。
|