# PathBerserker2d 技术评估与使用手册

> **版本**: PathBerserker2d (Unity Asset Store)  
> **Unity 要求**: 2020.3+  
> **依赖**: `com.unity.modules.physics2d`  
> **许可**: Unity Asset Store EULA  
> **包路径**: `Assets/PathBerserker2d/`  
> **官方文档**: https://oribow.github.io/PathBerserker2dDemo/Documentation/

---

## 目录

1. [概述与设计哲学](#1-概述与设计哲学)
2. [架构总览](#2-架构总览)
3. [核心组件](#3-核心组件)
4. [NavAgent 详解](#4-navagent-详解)
5. [NavSurface 详解](#5-navsurface-详解)
6. [NavLink 与 NavLinkCluster](#6-navlink-与-navlinkcluster)
7. [辅助组件](#7-辅助组件)
8. [全局系统 — PBWorld 与 Settings](#8-全局系统--pbworld-与-settings)
9. [路径与寻路请求](#9-路径与寻路请求)
10. [预置行为脚本](#10-预置行为脚本)
11. [TransformBasedMovement 移动系统](#11-transformbasedmovement-移动系统)
12. [Demo 场景与使用模式](#12-demo-场景与使用模式)
13. [Corgi 引擎集成](#13-corgi-引擎集成)
14. [全局设置参考](#14-全局设置参考)
15. [与 BaseGames 架构集成方案](#15-与-basegames-架构集成方案)
16. [性能分析与优化建议](#16-性能分析与优化建议)
17. [优缺点总结](#17-优缺点总结)
18. [总结与建议](#18-总结与建议)

---

## 1. 概述与设计哲学

### 1.1 什么是 PathBerserker2d

PathBerserker2d 是一款专为 **2D 游戏** 设计的导航/寻路插件。与 Unity 内置的 NavMesh（面向 3D）不同，它基于 **线段（Segment）** 而非面片构建导航图，天然适合 2D 横版游戏的地形表示。

核心理念：

> **从 2D Collider 自动烘焙导航线段，通过多线程 A\* 异步寻路，以事件驱动的方式委托移动实现。**

### 1.2 核心设计原则

| 原则 | 说明 |
|------|------|
| **线段导航** | 导航数据为沿 Collider2D 表面的线段，适合平台跳跃和横版场景 |
| **自动烘焙** | 从子对象的 Collider2D 自动提取导航线段，无需手动标记 |
| **异步多线程** | 寻路计算在后台线程完成（默认4线程），不阻塞主线程 |
| **事件驱动** | NavAgent 通过事件通知移动组件，移动实现完全解耦 |
| **动态世界** | 支持运行时烘焙、移动平台、动态链接启停 |
| **链接系统** | 跳跃、下落、攀爬、电梯、传送等复杂行为通过 NavLink 建模 |

### 1.3 适用场景

- 2D 横版平台跳跃（Metroidvania / Platformer）
- 2D 俯视角 RPG（360° 模式）
- 需要 AI 自动寻路的 2D 游戏
- 含电梯、梯子、传送门、移动平台等复杂地形的关卡

---

## 2. 架构总览

### 2.1 系统架构图

```
NavSurface (烘焙 Collider2D → 线段数据)
    ↓ OnEnable 时添加
PBWorld.NavGraph (全局导航图，B2DynamicTree 空间索引)
    ↑ NavLink / NavLinkCluster 添加连接
    ↑ NavAreaMarker 标记区域 NavTag
    ↑ NavSegmentSubstractor 裁剪线段

NavAgent.PathTo() → PBWorld.PathTo(PathRequest)
    ↓ 入队
PathfinderThread (多线程 A*) → PathRequest.Fulfill(Path)
    ↓ 主线程轮询
NavAgent.HandlePathRequest() → 开始 FollowPath
    ↓ 事件驱动
TransformBasedMovement / 自定义移动 (实际移动)
    ↓ 完成后回调
NavAgent.CompleteSegmentTraversal() / CompleteLinkTraversal()
```

### 2.2 关键设计模式

| 模式 | 说明 |
|------|------|
| **异步多线程寻路** | PathRequest 入队 → PathfinderThread 后台 A\* → 主线程轮询结果 |
| **事件驱动移动** | NavAgent 触发事件，外部组件响应事件实现移动逻辑 |
| **动态世界** | NavSurface 可运行时烘焙/加载/卸载，链接可动态添加/移除/切换可穿越性 |
| **移动平台支持** | 所有坐标相对 NavSurface 本地坐标存储，Transform 变化时自动跟随 |
| **自动重新寻路** | `autoRepathIntervall` 控制周期性重算路径，应对世界变化 |
| **WebGL 兼容** | 检测平台后使用协程替代线程，确保单线程环境可用 |

### 2.3 目录结构

```
Assets/PathBerserker2d/
├── Scripts/PathBerserker2d/          # 核心源码
│   ├── NavAgent/                     # NavAgent.cs, TransformBasedMovement.cs
│   │   └── NavAgentUsers/            # 预置行为脚本 (8个)
│   ├── NavSurface/                   # NavSurface.cs, 碰撞体过滤, 线段创建
│   │   ├── NavSegments/              # 线段数据结构
│   │   └── Creation/                 # 烘焙管线
│   ├── NavObjects/                   # NavLink, NavLinkCluster, NavAreaMarker 等
│   ├── NavGraph/                     # 导航图, 图节点, 空间索引
│   ├── Pathfinder/                   # A* 寻路, 路径请求, 多线程
│   ├── PBWorld.cs                    # 全局单例管理器
│   ├── PathBerserker2dSettings.cs    # 全局设置
│   └── IVelocityProvider.cs          # 速度接口
├── Demo/                             # 演示场景与脚本
│   ├── Scenes/                       # 15+ 场景
│   └── Scripts/                      # 演示脚本
├── Corgi/                            # Corgi Engine 集成层
├── Resources/                        # 全局设置资源文件
└── Documentation/                    # 官方文档 (zip)
```

---

## 3. 核心组件

### 3.1 组件总览

| 组件 | 菜单路径 | 职责 |
|------|---------|------|
| **NavSurface** | `PathBerserker2d/Nav Surface` | 从 Collider2D 烘焙导航线段 |
| **NavAgent** | `PathBerserker2d/Nav Agent` | 寻路请求与路径跟随 |
| **NavLink** | `PathBerserker2d/Nav Link` | 两点间导航链接（跳跃/下落/攀爬等） |
| **NavLinkCluster** | `PathBerserker2d/Nav Link Cluster` | 多点互联链接集群（电梯/梯子） |
| **NavAreaMarker** | `PathBerserker2d/Nav Area Marker` | 区域 NavTag 标记 |
| **NavSegmentSubstractor** | — | 在烘焙时裁剪指定区域的线段 |
| **DynamicObstacle** | — | 标记 GameObject 在烘焙时被忽略 |
| **TransformBasedMovement** | — | 基于 Transform 的默认移动实现 |

### 3.2 组件依赖关系

```
NavAgent ←需要→ TransformBasedMovement (或自定义移动组件)
NavAgent ←依赖→ PBWorld (全局单例，自动创建)
NavSurface ←依赖→ 子对象的 Collider2D
NavLink / NavLinkCluster ←映射→ NavSurface 上的线段
NavAreaMarker ←需要→ RectTransform
NavSegmentSubstractor ←需要→ RectTransform
```

---

## 4. NavAgent 详解

### 4.1 状态机

```
NavAgent 状态:
┌─────────┐
│  Idle    │ ←── 初始 / Stop() / ForceStop() / 到达目标
└────┬─────┘
     │ PathTo()
     ▼
┌─────────────────────────────┐
│      FollowPath             │
│  ┌─────────────────────┐    │
│  │  OnSegment           │ ←─ 在线段上移动
│  ├─────────────────────┤    │
│  │  WaitForLinkOnSegment│ ←─ 等待链接可用
│  ├─────────────────────┤    │
│  │  OnLink              │ ←─ 正在穿越链接
│  └─────────────────────┘    │
└─────────────────────────────┘
```

### 4.2 公共方法

| 方法 | 返回值 | 说明 |
|------|--------|------|
| `PathTo(Vector2 goal)` | `bool` | 寻路到目标位置 |
| `PathTo(params Vector2[] goals)` | `bool` | 寻路到多个目标中最近的 |
| `UpdatePath()` | `void` | 触发重新寻路（不改变目标） |
| `SetRandomDestination()` | `bool` | 设置随机目标 |
| `Stop()` | `void` | 优雅停止（完成当前链接后停止） |
| `ForceStop()` | `void` | 立即强制停止 |
| `CompleteSegmentTraversal()` | `void` | 通知已完成线段移动（由移动组件调用） |
| `CompleteLinkTraversal()` | `void` | 通知已完成链接穿越（由移动组件调用） |
| `WarpToNearestSegment()` | `void` | 传送到最近线段 |
| `CanTraverseLink(int linkType)` | `bool` | 检查是否可穿越指定类型链接 |
| `CanReach(Vector2 goal)` | `bool` | 同步检查目标是否可达 |
| `CreatePathRequest()` | `PathRequest` | 创建自定义寻路请求 |

### 4.3 公共属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `CurrentStatus` | `NavAgentStatus` | 当前状态枚举 |
| `IsIdle` | `bool` | 是否空闲 |
| `IsFollowingAPath` | `bool` | 是否正在跟随路径 |
| `IsOnLink` | `bool` | 是否正在链接上 |
| `IsMovingOnSegment` | `bool` | 是否在线段上移动 |
| `HasValidPosition` | `bool` | 当前位置是否有效（在线段上） |
| `Height` | `float` | 代理高度 |
| `MaxSlopeAngle` | `float` | 最大坡度角 |
| `CurrentSegmentNormal` | `Vector2` | 当前线段法线 |
| `PathGoal` | `Vector2` | 当前路径目标 |
| `Position` | `Vector2` | 代理位置 |
| `CurrentNavTagVector` | `int` | 当前位置的 NavTag |
| `TimeOnLink` | `float` | 在当前链接上经过的时间 |

### 4.4 事件

| 事件 | 参数 | 触发时机 |
|------|------|---------|
| `OnStartLinkTraversal` | `NavAgent, PathSegment` | 开始穿越链接 |
| `OnLinkTraversal` | `NavAgent, PathSegment, float t` | 链接穿越每帧回调（t: 0→1） |
| `OnStartSegmentTraversal` | `NavAgent, PathSegment` | 开始线段移动 |
| `OnSegmentTraversal` | `NavAgent, PathSegment, float t` | 线段移动每帧回调 |
| `OnFailedToFindPath` | — | 寻路失败 |
| `OnStop` | — | 停止移动 |
| `OnReachedGoal` | — | 到达目标 |
| `OnStartFollowingNewPath` | — | 开始跟随新路径 |

### 4.5 Inspector 配置

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `height` | 1 | 代理高度（影响净空检查） |
| `maxSlopeAngle` | 60 | 最大可行走坡度角 |
| `autoRepathIntervall` | 1 | 自动重新寻路间隔（秒） |
| `maximumDistanceToPathStart` | ∞ | 到路径起点的最大距离 |
| `linkTraversalCostMultipliers[]` | — | 各链接类型代价乘数 |
| `navTagTraversalCostMultipliers[]` | — | 各 NavTag 代价乘数 |
| `allowCloseEnoughPath` | `false` | 允许"近似到达"路径 |
| `enableDebugMessages` | `false` | 启用调试日志 |

---

## 5. NavSurface 详解

### 5.1 核心概念

NavSurface 是导航数据的来源。它扫描子对象上的 **Collider2D**，沿碰撞体表面生成导航线段，并在烘焙完成后将数据添加到全局 NavGraph。

关键特性：
- **自动烘焙**：编辑器中或运行时均可烘焙
- **移动平台**：烘焙数据以本地坐标存储，NavSurface Transform 移动时路径跟随
- **动态加载**：`OnEnable` 添加到 NavGraph，`OnDisable` 移除

### 5.2 公共属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `WorldBounds` | `Rect` | 世界空间包围盒 |
| `MaxClearance` | `float` | 最大净空检查高度 |
| `MinClearance` | `float` | 最小净空（低于此值的线段被移除） |
| `CellSize` | `float` | 净空检查精度 |
| `ColliderMask` | `LayerMask` | 碰撞体过滤层 |
| `TotalLineLength` | `float` | 所有线段总长度 |
| `MaxSlopeAngle` | `float` | 最大坡度角 |
| `LocalToWorldMatrix` | `Matrix4x4` | 本地到世界矩阵 |

### 5.3 公共方法

| 方法 | 说明 |
|------|------|
| `IEnumerator Bake()` | 运行时烘焙（协程） |
| `Vector2 LocalToWorld(Vector2 pos)` | 本地坐标转世界坐标 |
| `Vector2 WorldToLocal(Vector2 pos)` | 世界坐标转本地坐标 |

### 5.4 事件

| 事件 | 说明 |
|------|------|
| `OnBakingCompleted` | 烘焙完成 |
| `OnReadyToPathfind` | 已添加到 NavGraph，可以开始寻路 |
| `OnRemovedFromPathfinding` | 已从 NavGraph 移除 |

### 5.5 Inspector 烘焙配置

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `maxClearance` | 1.8 | 障碍检查最大高度 |
| `minClearance` | 0.1 | 净空低于此值的线段被移除 |
| `cellSize` | 0.1 | 障碍检查精度（越小越精确但越慢） |
| `includedColliders` | ~0 | 参与烘焙的层 |
| `onlyStaticColliders` | false | 仅包含静态碰撞体 |
| `maxSlopeAngle` | 180 | 移除超过此角度的线段 |
| `smallestDistanceYouCareAbout` | 0.1 | RDP 线简化容差 |
| `minSegmentLength` | 0.1 | 最小线段长度 |

### 5.6 使用示例

```
场景层级结构:
NavSurface (GameObject)
├── Ground (BoxCollider2D)
├── Platform_1 (BoxCollider2D)
├── Platform_2 (PolygonCollider2D)
└── Wall (BoxCollider2D)
```

> **注意**: NavSurface 只扫描 **子对象** 上的 Collider2D，自身上的碰撞体不会被烘焙。

---

## 6. NavLink 与 NavLinkCluster

### 6.1 NavLink — 单个导航链接

NavLink 连接两个点，代表跳跃、下落、攀爬等需要特殊处理的路径段。

#### 可视化类型

| 类型 | 说明 |
|------|------|
| `Linear` | 直线 |
| `QuadradticBezier` | 二次贝塞尔曲线 |
| `Projectile` | 抛物线 |
| `Teleport` | 传送（瞬移） |
| `None` | 无可视化 |
| `TransformBasedMovement` | 使用 TransformBasedMovement 的默认处理 |

#### 公共属性

| 属性 | 类型 | 说明 |
|------|------|------|
| `GoalWorldPosition` | `Vector2` | 目标世界位置（可读写） |
| `StartWorldPosition` | `Vector2` | 起点世界位置（可读写） |
| `IsBidirectional` | `bool` | 是否双向 |
| `IsAddedToWorld` | `bool` | 是否已添加到 NavGraph |

#### 公共方法

| 方法 | 说明 |
|------|------|
| `UpdateMapping()` | 位置改变后更新链接映射 |
| `SetStartToGoalLinkTraversable(bool)` | 设置正向可穿越性 |
| `SetGoalToStartLinkTraversable(bool)` | 设置反向可穿越性 |

#### 共有基类属性 (BaseNavLink)

| 属性 | 说明 |
|------|------|
| `LinkType` | 链接类型索引（corner=0, jump=1, fall=2, teleport=3, climb=4, elevator=5） |
| `Clearance` | 允许通过的最大代理高度 |
| `AvgWaitTime` | 平均等待时间（影响寻路代价） |
| `CostOverride` | 代价覆盖（≤0 使用距离计算） |
| `NavTag` | NavTag 标记 |
| `MaxTraversableDistance` | 最大可穿越距离 |
| `autoMap` | 自动映射到 NavGraph |

### 6.2 NavLinkCluster — 链接集群

NavLinkCluster 适用于多点互联场景，如 **电梯**（多层站点）、**梯子**（多个停靠点）。

内部为每对点自动生成一个链接。

#### LinkPoint 结构

```csharp
struct LinkPoint {
    Vector2 point;
    PointTraversalType traversalType;  // Exit | Entry | Both
}
```

#### 公共方法

| 方法 | 说明 |
|------|------|
| `UpdateMapping()` | 更新所有链接映射 |
| `SetLinksTraversable(Func<Vector2, Vector2, bool>)` | 根据起终点函数设置各链接可穿越性 |

#### 使用场景

```csharp
// 电梯到达某层时，只允许穿越与该层相关的链接
navLinkCluster.SetLinksTraversable((start, goal) =>
    Mathf.Abs(start.y - currentFloor.position.y) < 0.1f ||
    Mathf.Abs(goal.y - currentFloor.position.y) < 0.1f);

// 离开时禁用所有链接
navLinkCluster.SetLinksTraversable((start, goal) => false);
```

---

## 7. 辅助组件

### 7.1 NavAreaMarker — 区域标记

**要求**: `RectTransform`

将矩形区域内的所有导航线段标记为指定 NavTag。常用于标记水域、危险区域、门区域等。

| 属性/方法 | 说明 |
|-----------|------|
| `NavTag` | NavTag 索引 |
| `MarkerColor` | 标记颜色 |
| `updateAfterTimeOfNoMovement` | 停止移动后更新延迟 |
| `updateAfterTime` | 最大更新间隔 |
| `UpdateMappings()` | 手动更新映射 |

**门控模式**: 通过启用/禁用 NavAreaMarker 来控制门的通行：
```csharp
// 开门 → 禁用标记 → 代理可通过
navAreaMarker.enabled = false;
// 关门 → 启用标记 → 区域被标记为不可通行 NavTag
navAreaMarker.enabled = true;
```

### 7.2 NavSegmentSubstractor — 线段裁剪器

**要求**: `RectTransform`

在烘焙时从指定矩形区域移除线段。支持角度过滤：

| 字段 | 说明 |
|------|------|
| `fromAngle` | 最小角度过滤 |
| `toAngle` | 最大角度过滤 |

### 7.3 DynamicObstacle — 动态障碍物

空标记组件。附加到 GameObject 上，使其在 NavSurface 烘焙时被忽略。

### 7.4 IVelocityProvider — 速度接口

```csharp
interface IVelocityProvider {
    Vector2 WorldVelocity { get; }
}
```

用于 `Follower` 组件的目标预测功能。在跟随目标上实现此接口即可。

---

## 8. 全局系统 — PBWorld 与 Settings

### 8.1 PBWorld — 全局单例

自动实例化，`DontDestroyOnLoad`。管理全局 NavGraph 和寻路调度。

#### 静态 API

```csharp
// === 点映射 ===
// 映射世界点到最近导航位置
static bool TryMapPoint(Vector2 position, out NavSegmentPositionPointer pointer)
// 自定义搜索半径
static bool TryMapPoint(Vector2 position, float searchRadius, out NavSegmentPositionPointer pointer)
// 确保映射位置对代理可通行
static bool TryMapPoint(Vector2 position, float searchRadius, NavAgent agent, out NavSegmentPositionPointer pointer)

// === 随机 ===
static Vector2 GetRandomPointOnGraph()  // 返回图上随机点

// === 寻路 ===
static void PathTo(PathRequest pathRequest)  // 入队异步寻路请求

// === 空间查询 ===
static List<NavSubsegmentPointer> BoxCast(Rect rect, float rotation, float fromAngle, float toAngle)

// === 图变化监听 ===
static INavGraphChangeSource NavGraphChangeSource  // 订阅 OnGraphChange 事件
```

#### NavGraphChange 事件枚举

| 值 | 说明 |
|----|------|
| `NavSurfaceAdded` | NavSurface 添加 |
| `NavSurfaceRemoved` | NavSurface 移除 |
| `NavLinkAdded` | NavLink 添加 |
| `NavLinkRemoved` | NavLink 移除 |
| `SegmentModifierAdded` | 线段修改器添加 |
| `SegmentModifierRemoved` | 线段修改器移除 |
| `NavLinkMoved` | NavLink 位置变更 |

### 8.2 NavSegmentPositionPointer

导航位置指针结构体，用于表示一个在导航图上的有效位置：

| 属性 | 类型 | 说明 |
|------|------|------|
| `Position` | `Vector2` | 世界位置 |
| `Normal` | `Vector2` | 法线 |
| `IsValid()` | `bool` | 是否有效 |
| `IsInvalid()` | `bool` | 是否无效 |

---

## 9. 路径与寻路请求

### 9.1 PathRequest — 寻路请求

| 枚举 | 值 |
|------|-----|
| **RequestState** | `Draft`, `Pending`, `Finished`, `Failed` |
| **RequestFailReason** | `CouldntMapStart`, `CouldntMapGoal`, `MappedStartChanged`, `AllMappedGoalsChanged`, `NoPathFromStartToGoal`, `WorldWasDestroyed`, `ToFarFromStart` |

| 属性 | 类型 | 说明 |
|------|------|------|
| `Status` | `RequestState` | 请求状态 |
| `FailReason` | `RequestFailReason` | 失败原因 |
| `Path` | `Path` | 计算出的路径 |
| `start` | `NavSegmentPositionPointer` | 起点 |
| `goals` | `IList<NavSegmentPositionPointer>` | 目标列表 |
| `client` | `NavAgent` | 请求代理 |

### 9.2 Path — 路径

| 属性/方法 | 说明 |
|-----------|------|
| `Current` | 当前路径片段 (`PathSegment`) |
| `NextSegment` | 下一个片段 |
| `HasNext` | 是否有下一个 |
| `Goal` | 目标位置 |
| `Start` | 起点位置 |
| `totalCosts` | 总代价 |
| `MoveNext()` | 前进到下一片段 |
| `AllPathPoints()` | 获取所有路径点列表 |
| `RemainingPathPoints()` | 获取剩余路径点列表 |

### 9.3 PathSegment — 路径片段

| 属性/方法 | 说明 |
|-----------|------|
| `Next` | 下一个片段 |
| `LinkStart` | 链接起点（世界坐标，随 NavSurface 移动） |
| `LinkEnd` | 链接终点 |
| `Normal` | 线段法线 |
| `Tangent` | 线段切线 |
| `Point` | 线段上的参考点 |
| `link` | 关联的链接实例 |
| `owner` | 所属 NavSurface |
| `GetTagVector(float t)` | 获取位置的 NavTag |
| `DistanceAlongSegment(Vector2 pos)` | 投影距离 |

---

## 10. 预置行为脚本

PathBerserker2d 提供 8 个即用的 NavAgent 行为脚本：

| 组件 | 说明 | 典型用途 |
|------|------|---------|
| **MouseWalker** | 鼠标点击处寻路 | 调试、点击移动原型 |
| **PatrolWalker** | 按顺序巡逻路线，循环 | 巡逻敌人 |
| **RandomWalker** | 持续随机行走 | NPC 闲逛 |
| **MultiGoalWalker** | 寻路到多个目标中最近的一个 | 收集物搜索 |
| **Follower** | 跟随目标 Transform，支持目标预测 | 追踪型敌人 |
| **KeepGrounded** | 通过 Raycast 检测移动平台并 parent | 移动平台上的代理 |
| **AdjustRotation** | 旋转代理匹配线段法线方向 | 沿曲面行走的方向适配 |
| **FootStepSounds** | 根据 NavTag 播放不同脚步声 | 环境音效 |

### 使用方式

直接将这些脚本添加到带有 NavAgent 的 GameObject 上即可。它们自动获取同 GameObject 上的 NavAgent 引用。

---

## 11. TransformBasedMovement 移动系统

### 11.1 概述

`TransformBasedMovement` 是 PathBerserker2d 提供的默认移动实现。它订阅 NavAgent 的事件，在回调中直接修改 Transform 位置，并在完成后调用 `CompleteSegmentTraversal()` / `CompleteLinkTraversal()` 通知 NavAgent。

### 11.2 FeatureFlags

```csharp
[Flags] enum FeatureFlags {
    SegmentMovement = 1,    // 线段移动
    JumpLinks       = 2,    // 跳跃链接
    CornerLinks     = 4,    // 拐角链接
    FallLinks       = 8,    // 下落链接
    TeleportLinks   = 16,   // 传送链接
    ClimbLinks      = 32,   // 攀爬链接
    ElevatorLinks   = 64,   // 电梯链接
    OtherLinks      = 128,  // 其他链接
}
```

### 11.3 配置属性

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `movementSpeed` | 5 | 线段移动速度 (unit/s) |
| `cornerSpeed` | 100 | 拐角链接速度 (degrees/s) |
| `jumpSpeed` | 5 | 跳跃速度 (unit/s) |
| `fallSpeed` | 5 | 下落速度 (unit/s) |
| `climbSpeed` | 5 | 攀爬速度 (unit/s) |
| `enableAgentRotation` | true | 是否旋转代理朝向移动方向 |
| `enabledFeatures` | 全部启用 | 控制由本组件处理的功能 |

### 11.4 自定义移动组件

如果 `TransformBasedMovement` 不满足需求（例如需要物理驱动移动），可以创建自定义移动组件：

```csharp
public class CustomMovement : MonoBehaviour
{
    NavAgent navAgent;
    
    void Awake() => navAgent = GetComponent<NavAgent>();
    
    void OnEnable()
    {
        navAgent.OnStartSegmentTraversal += HandleSegmentStart;
        navAgent.OnSegmentTraversal += HandleSegmentMove;
        navAgent.OnStartLinkTraversal += HandleLinkStart;
        navAgent.OnLinkTraversal += HandleLinkMove;
    }
    
    void HandleSegmentMove(NavAgent agent, PathSegment seg, float t)
    {
        // 自定义线段移动逻辑
        // ...
        // 完成后:
        agent.CompleteSegmentTraversal();
    }
    
    void HandleLinkMove(NavAgent agent, PathSegment seg, float t)
    {
        // 自定义链接穿越逻辑
        // ...
        // 完成后:
        agent.CompleteLinkTraversal();
    }
}
```

---

## 12. Demo 场景与使用模式

### 12.1 Demo 场景一览

| 场景 | 展示内容 |
|------|---------|
| `breakable_wall` | 可破坏墙壁 + 寻路 |
| `door` | NavAreaMarker 门控 |
| `elevator` | NavLinkCluster 电梯系统 |
| `follow_target` | Follower 跟随行为 |
| `ladder` | 攀爬链接 |
| `moving_platform` | 移动平台导航 |
| `multi_surface` | 多 NavSurface 场景 |
| `procedural_endless_jumper` | 运行时烘焙 |
| `runtime_bake` | 运行时动态烘焙 |
| `simple_patrol` | 基础巡逻 |
| `teleport` | 传送链接 |
| `threesixtydegree` | 360° 全向导航 |
| `trafficlight` | 交通灯 + 等待逻辑 |
| `tricky_jump` | 复杂跳跃场景 |

### 12.2 常用使用模式

#### 模式 1：最简单的寻路

```csharp
// GoalWalker 模式：检查距离 + IsIdle → PathTo
void Update()
{
    if (Vector2.Distance(goal.position, navAgent.transform.position) > 0.5f
        && (navAgent.IsIdle || goal.hasChanged))
    {
        goal.hasChanged = false;
        navAgent.PathTo(goal.position);
    }
}
```

#### 模式 2：电梯 — 动态链接切换

```csharp
// 电梯到达某层 → 启用相关链接
navLinkCluster.SetLinksTraversable((start, goal) =>
    Mathf.Abs(start.y - levels[nextLevel].position.y) < 0.1f ||
    Mathf.Abs(goal.y - levels[nextLevel].position.y) < 0.1f);

// 电梯离开 → 禁用所有链接
navLinkCluster.SetLinksTraversable((start, goal) => false);
```

#### 模式 3：门 — NavAreaMarker 控制

```csharp
// 开门：禁用 NavAreaMarker → 区域不再有阻挡标记
navAreaMarker.enabled = false;

// 关门：启用 NavAreaMarker → 门区域被标记为不可通行 NavTag
navAreaMarker.enabled = true;
```

#### 模式 4：移动平台

```csharp
// MovingPlatform 是 NavSurface 的子对象
// 只需移动 NavSurface 的 Transform，导航数据自动跟随
transform.Translate(velocity * Time.deltaTime);
```

#### 模式 5：运行时烘焙

```csharp
// 在运行时触发烘焙
StartCoroutine(navSurface.Bake());

// 监听烘焙完成
navSurface.OnBakingCompleted += () => Debug.Log("Bake done!");
navSurface.OnReadyToPathfind += () => Debug.Log("Ready for pathfinding!");
```

---

## 13. Corgi 引擎集成

PathBerserker2d 附带 **CorgiBasedMovement** 组件，替代 `TransformBasedMovement` 以对接 Corgi Engine 的角色控制系统。

### 13.1 核心映射

| 导航行为 | Corgi 映射 |
|---------|-----------|
| 线段移动 | `CharacterHorizontalMovement.SetHorizontalMove()` |
| 跳跃链接 | `CharacterJump.JumpStart()` |
| 攀爬链接 | `CharacterLadder`（反射调用） |
| 传送链接 | 直接设置 Position |
| 拐角链接 | 直接 `CompleteLinkTraversal()` |
| 卡住检测 | `fallbackTeleportDelay` 秒后传送 |

### 13.2 Corgi AI Actions

| 脚本 | 说明 |
|------|------|
| `AIActionPBMoveTowardsTarget` | 移向目标 |
| `AIActionPBMoveTowardsClosestTarget` | 移向最近目标 |
| `AIActionPBMoveTowardsRandomPathableTarget` | 移向可达随机目标 |
| `AIActionPBPatrol` | 巡逻 |
| `AIDecisionPBHasReachedGoal` | 判断是否到达 |
| `AIDecisionPBPathfindingFailed` | 判断寻路失败 |

> **注意**: 本项目使用自研架构而非 Corgi Engine，此集成仅作参考。

---

## 14. 全局设置参考

**位置**: `Edit > Project Settings > PathBerserker2d`  
**资源文件**: `Assets/PathBerserker2d/Resources/PathBerserker2dSettings`

### 14.1 设置项

| 属性 | 类型 | 当前值 | 说明 |
|------|------|--------|------|
| `PointMappingDistance` | float | 0.2 | 点映射最大距离（性能关键，应尽量小） |
| `PathfinderThreadCount` | int | 4 | 寻路线程数（WebGL 强制 = 1） |
| `InitiateUpdateInterval` | float | 0.1s | NavGraph 更新间隔 |
| `DrawGraphWhilePlaying` | bool | — | 运行时绘制导航图 |
| `NavSurfaceLineWidth` | float | — | 线宽 |
| `UsePolygonCollider2dPathsForBaking` | bool | — | 多边形碰撞体烘焙方式 |

### 14.2 内置链接类型

| 索引 | 名称 | 说明 |
|------|------|------|
| 0 | `corner` | 拐角（自动生成） |
| 1 | `jump` | 跳跃 |
| 2 | `fall` | 下落 |
| 3 | `teleport` | 传送 |
| 4 | `climb` | 攀爬 |
| 5 | `elevator` | 电梯 |

### 14.3 内置 NavTag

| 名称 | 用途 |
|------|------|
| `default` | 默认 |
| `water` | 水域 |
| `lava` | 岩浆 |
| `grass` | 草地 |
| `concrete` | 混凝土 |
| `dirt` | 泥土 |

---

## 15. 与 BaseGames 架构集成方案

### 15.1 防腐层原则

根据 BaseGames 架构总纲（`00_Architecture_Overview.md`）第 3 条设计理念：

> **防腐层隔离**: 业务代码永远不直接调用 PathBerserker2d 等第三方 API。所有第三方交互通过 `Adapters/` 层代理。

因此 PathBerserker2d 的所有功能必须通过 **适配器层** 暴露给业务系统。

### 15.2 适配器设计

```
Layer 3 — Adapters/
└── NavAgentAdapter.cs          # PathBerserker2d NavAgent 的防腐包装

业务层调用链:
EnemyAI (Layer 5) → NavAgentAdapter (Layer 3) → NavAgent (第三方)
```

#### NavAgentAdapter 接口建议

```csharp
namespace BaseGames.Adapters
{
    /// <summary>
    /// PathBerserker2d NavAgent 的防腐层适配器。
    /// 业务代码通过此接口进行寻路，不直接引用 PathBerserker2d API。
    /// </summary>
    public interface INavigation
    {
        bool PathTo(Vector2 goal);
        bool PathTo(params Vector2[] goals);
        void Stop();
        void ForceStop();
        bool IsIdle { get; }
        bool IsFollowingPath { get; }
        bool CanReach(Vector2 goal);
        Vector2 CurrentPosition { get; }
        
        event Action OnReachedGoal;
        event Action OnPathFailed;
        event Action OnStopped;
    }
}
```

### 15.3 与其他系统的集成点

| BaseGames 系统 | 集成方式 |
|----------------|---------|
| **敌人 AI (20_Enemy_AI)** | 行为树通过 `INavigation` 接口调用寻路 |
| **环境系统 (11_Environment)** | MovingPlatform 使用 NavSurface 子对象模式 |
| **环境系统 (11_Environment)** | BreakableWall 销毁后触发 NavSurface 重新烘焙 |
| **环境系统 (11_Environment)** | TeleportGate 对应 NavLink（teleport 类型） |
| **物理动画 (08_Physics)** | 自定义移动组件桥接 `IPhysicsBody` 与 NavAgent 事件 |
| **标签系统 (02_GameTag)** | NavTag 可映射为 GameTagSO 用于环境效果触发 |

### 15.4 自定义移动组件集成

由于 BaseGames 使用自研物理系统 (`IPhysicsBody` / `RaycastBody2D`)，不应使用默认的 `TransformBasedMovement`。需要创建桥接移动组件：

```csharp
namespace BaseGames.Adapters
{
    public class PhysicsBasedNavMovement : MonoBehaviour
    {
        // 订阅 NavAgent 事件
        // 将移动指令转发给 IPhysicsBody
        // 通过 IPhysicsBody 驱动实际移动
        // 移动完成后调用 CompleteSegmentTraversal() / CompleteLinkTraversal()
    }
}
```

---

## 16. 性能分析与优化建议

### 16.1 性能特性

| 方面 | 评估 |
|------|------|
| **寻路** | 多线程 A\*，不阻塞主线程。线程数可配置（默认 4） |
| **烘焙** | 协程方式，可分帧执行。复杂场景烘焙较重 |
| **内存** | 线段数据以本地坐标存储，紧凑 |
| **空间索引** | B2DynamicTree（Box2D 动态树），查询高效 |
| **WebGL** | 自动降级为单线程协程模式 |

### 16.2 优化建议

| 建议 | 说明 |
|------|------|
| **减小 `PointMappingDistance`** | 当前 0.2，越小映射查询越快 |
| **调整 `autoRepathIntervall`** | 不要过于频繁，1-2 秒通常足够 |
| **合理设置 `cellSize`** | 烘焙精度越高越慢，0.1 适合大多数情况 |
| **分区管理 NavSurface** | 按房间/区域拆分 NavSurface，按需启用/禁用 |
| **限制同时寻路数** | 大量代理时排队处理，避免请求洪峰 |
| **善用 `onlyStaticColliders`** | 排除动态碰撞体可加速烘焙 |

---

## 17. 优缺点总结

### 17.1 优势

| 优势 | 说明 |
|------|------|
| **原生 2D 支持** | 基于线段而非面片，天然适合 2D 横版游戏 |
| **完整源码** | 所有代码可见，便于调试和定制 |
| **链接系统丰富** | 内置 6 种链接类型，覆盖跳跃/下落/攀爬/电梯/传送/拐角 |
| **动态世界** | 运行时烘焙、移动平台、动态链接切换 |
| **多线程寻路** | 不阻塞主线程，支持多代理并发 |
| **事件驱动架构** | 移动实现完全解耦，易于替换为自定义移动系统 |
| **预置行为丰富** | 8 个即用行为脚本覆盖常见场景 |
| **移动平台支持** | 本地坐标体系自动跟随 NavSurface Transform 变化 |

### 17.2 不足

| 不足 | 说明 |
|------|------|
| **文档较简陋** | 官方文档以 Demo 为主，缺少系统性 API 文档 |
| **无官方维护迹象** | Asset Store 版本更新不频繁 |
| **烘焙仅支持 Collider2D** | 不支持 Tilemap 直接烘焙（需转换为 Collider） |
| **链接需手动放置** | 跳跃/攀爬等链接需要手动在编辑器中放置 |
| **360° 模式限制** | 虽支持 360° 但主要为横版优化 |
| **缺少动态避障** | 无 RVO / ORCA 等动态避障实现 |
| **NavTag 数量有限** | 内置 6 个 NavTag，扩展需修改设置 |

### 17.3 技术评分

| 维度 | 评分 (1-10) | 说明 |
|------|-------------|------|
| 2D 适配度 | **9** | 专为 2D 设计，线段导航非常贴合横版场景 |
| API 设计 | **8** | 事件驱动架构清晰，易于扩展 |
| 文档质量 | **5** | Demo 丰富但系统文档不足 |
| 性能 | **8** | 多线程寻路 + B2DynamicTree 空间索引 |
| 易用性 | **7** | 基础使用简单，高级功能学习曲线稍陡 |
| 可维护性 | **7** | 完整源码可见，但注释较少 |
| 扩展性 | **8** | 事件驱动 + 接口隔离，易接入自定义系统 |
| **综合** | **7.4** | 适合 2D Metroidvania 项目的可靠寻路方案 |

---

## 18. 总结与建议

### 18.1 总体评价

PathBerserker2d 是目前 Unity 生态中少有的 **专为 2D 横版设计** 的寻路方案。其基于线段的导航模型天然适配平台跳跃类游戏，多线程异步寻路保证了性能，事件驱动架构提供了良好的扩展性。

对于 BaseGames 这样的 2D Metroidvania 项目，它提供了：
- **完整的 2D 导航能力**：地面行走、跳跃、下落、攀爬、电梯、传送
- **移动平台支持**：天然适配关卡中的动态地形
- **与自定义物理系统的解耦**：通过事件驱动架构可桥接 `IPhysicsBody`

### 18.2 集成建议

1. **严格通过适配器层访问** — 遵循 BaseGames 防腐层原则，创建 `NavAgentAdapter` / `INavigation` 接口
2. **替换 TransformBasedMovement** — 创建 `PhysicsBasedNavMovement` 桥接 `IPhysicsBody`
3. **按房间分区 NavSurface** — 配合关卡加载系统，按需启用/禁用导航区域
4. **NavTag 映射 GameTagSO** — 统一标签体系，复用效果系统触发逻辑
5. **行为树集成** — 通过 `INavigation` 接口在行为树节点中调用寻路

### 18.3 注意事项

- 可破坏墙壁销毁后需触发 NavSurface 重新烘焙
- 电梯/升降台需使用 NavLinkCluster 配合动态可穿越性控制
- 大量 AI 代理场景需排队管理寻路请求避免性能瓶颈
- WebGL 构建时自动降级为单线程，需额外测试性能