unity-navmesh

Unity NavMesh（AI Navigation）

在 Unity 6.3 LTS 中为 NPC 添加寻路功能：烘焙可行走表面，并让 Agent 绕开障碍物移动。 面向 Unity 6.3 LTS (6000.3) 和 AI Navigation package 2.x。

**版本陷阱（Unity 2022+/6）：**旧版内置的 Navigation window（Object/Bake 选项卡） 已移除。现在通过 AI Navigation package (com.unity.ai.navigation) 使用基于组件的方式烘焙：为关卡几何体添加 NavMeshSurface，然后点击 Bake。运行时 NavMeshAgent/NavMesh API 仍内置于 UnityEngine.AI 中。

适用场景

• 当 Agent 需要走向、追逐或巡逻至目标，烘焙可导航表面、添加动态阻挡物（NavMeshObstacle），或检查目标位置是否可到达时使用。
• 项目使用 AI Navigation package、包含 NavMeshSurface 组件，或脚本使用 UnityEngine.AI.NavMeshAgent 时使用。

**不适用场景：**决定何时、何处移动的逻辑（FSM、行为树、转向）→ game-ai（此技能用于 Unity 移动/寻路机制）。不涉及寻路的受力驱动或运动学移动 → unity-physics。

核心工作流

1. 安装 AI Navigation package（Package Manager → com.unity.ai.navigation）。
2. **烘焙表面：**选择静态关卡几何体，Add Component → Navigation → NavMesh Surface，设置 Agent 类型/区域设置，然后点击 Bake。几何体、NavMeshModifier 或 Agent 设置发生变化时，都要重新烘焙。
3. 为每个移动中的 NPC 添加 NavMeshAgent；其半径/高度/速度必须与烘焙所用的 Agent 类型一致，并且必须生成在已烘焙的网格上。
4. 使用脚本通过 SetDestination(targetPos) 控制它；Agent 会自动转向并避开其他 Agent。通过 remainingDistance/pathPending 检测是否到达。
5. 使用 NavMeshObstacle（carving）处理动态阻挡物，这样关闭的门/箱子就能阻挡路径，而无需完整重新烘焙。
6. **验证：**使用 AI Navigation overlay（已烘焙的网格会显示在 Scene 视图中），并观察 Agent 是否绕过障碍物到达目标；对于无法到达的目标，检查 NavMeshPath.status。

模式

1. 使用 NavMeshAgent 追逐/前往目标

using UnityEngine;
using UnityEngine.AI;

[RequireComponent(typeof(NavMeshAgent))]
public class Chaser : MonoBehaviour
{
    [SerializeField] private Transform target;
    private NavMeshAgent _agent;

    private void Awake() => _agent = GetComponent<NavMeshAgent>();

    private void Update()
    {
        if (target) _agent.SetDestination(target.position);   // re-path toward the target
    }

    // Arrived? pathPending guards the first frame before a path exists.
    private bool HasArrived() =>
        !_agent.pathPending && _agent.remainingDistance <= _agent.stoppingDistance;
}

2. 在确定目标位置前检查是否可到达

using UnityEngine.AI;

public bool CanReach(NavMeshAgent agent, Vector3 destination)
{
    var path = new NavMeshPath();
    agent.CalculatePath(destination, path);
    return path.status == NavMeshPathStatus.PathComplete;   // vs Partial / Invalid
}

3. 在运行时烘焙（适用于程序生成或流式加载的关卡）

using Unity.AI.Navigation;   // the package namespace (NavMeshSurface)

[SerializeField] private NavMeshSurface surface;

// After spawning level geometry, build the navmesh in code.
public void RebuildNav() => surface.BuildNavMesh();

4. 会雕刻网格的动态障碍物

// Add a NavMeshObstacle (Carve = true) to a door/crate. While present it cuts a hole in the
// navmesh so agents route around it; remove/disable it to reopen the path — no re-bake needed.

5. 使用 NavMeshLink 连接独立网格块（跳跃、门、间隙）

// Two baked surfaces that don't touch (a ledge and the floor below, two platforms across a
// gap) are separate islands — an agent can't path between them. Add Component > Navigation >
// NavMesh Link to bridge them: assign Start/End Transforms, set Width (0 = point-to-point),
// and toggle Bidirectional for one-way vs two-way. NavMeshLink lives in Unity.AI.Navigation.
// It replaces the deprecated built-in OffMeshLink (see pitfalls).

常见问题

• 寻找 Navigation 窗口 — Unity 6 中已不再提供该窗口。请使用 AI Navigation 包中的 NavMeshSurface 组件并进行烘焙。
• Agent 不移动／传送到原点 — 它不在已烘焙的网格上，或者没有烘焙任何表面。请烘焙表面，并在其上生成 Agent（使用 NavMesh.SamplePosition 进行贴合）。
• Agent 忽略新几何体 — 导航网格已烘焙；运行时生成的障碍物需要添加 NavMeshObstacle（挖洞），或者重新烘焙：surface.BuildNavMesh()。
• 每帧调用 SetDestination 很浪费 — 对于移动缓慢的目标，请使用计时器定期重新规划路径（例如每 0.2s 一次），而不是每帧调用。
• Agent 半径／高度不匹配 — 如果 NavMeshAgent 的尺寸与已烘焙的 Agent 类型不一致，它会卡在缝隙中或悬空；请保持两者一致。
• Agent 之间发生抖动 — 调整 avoidancePriority 和质量设置，或者对真正静态的阻挡物使用障碍物，而不要依赖 Agent 避障。
• 尝试使用 OffMeshLink — AI Navigation 2.0 中内置的 OffMeshLink 组件已弃用，无法再从 Add Component 菜单添加。请改用 AI Navigation 包（Unity.AI.Navigation）中的 NavMeshLink — 它提供基于 Transform 的端点和运行时 activated 属性。请迁移现有的 OffMeshLink。
• CalculatePath 返回 PathPartial — 目标位于与 Agent 不同的已烘焙岛上（网格无法跨越间隙）。使用 NavMeshLink（模式 5）连接两者，或者扩展几何体，让同一个表面覆盖两者；部分路径只能到达靠近的一侧边缘。

参考资料

• 主要文档：AI Navigation 包手册 （https://docs.unity3d.com/Packages/[email protected]/manual/index.html）、 NavMeshLink 页面 （https://docs.unity3d.com/Packages/[email protected]/manual/NavMeshLink.html） 及其关于 OffMeshLink 弃用的“What's new”说明 （https://docs.unity3d.com/Packages/[email protected]/manual/whats-new.html），以及 ScriptReference/AI.NavMeshAgent、ScriptReference/AI.NavMesh。

相关技能

• game-ai — 与引擎无关的决策机制（FSM、行为树、转向），供此处使用。
• unity-csharp-scripting — Agent 周围的 MonoBehaviour 结构。
• tower-defense / fps-shooter — 将寻路与玩法结合的游戏类型。