unity-navmesh

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity NavMesh (AI Navigation)

Unity NavMesh（AI导航）

Give NPCs pathfinding in Unity 6: bake walkable surfaces and move agents around obstacles. Targets Unity 6 (6000.0 LTS) with the AI Navigation package 2.x.

Version trap (Unity 2022+/6): the old built-in Navigation window (Object/Bake tabs) is gone. Baking is now component-based via the AI Navigation package (
com.unity.ai.navigation
): add a NavMeshSurface to your level geometry and click Bake. The runtime
NavMeshAgent
/
NavMesh
API stays in built-in
UnityEngine.AI
.

在Unity 6中为NPC添加寻路功能：烘焙可行走表面并让智能体绕过障碍物移动。针对 Unity 6（6000.0 LTS） 及 AI Navigation package 2.x 版本。

版本陷阱（Unity 2022+/6）： 旧版内置的 Navigation窗口（Object/Bake标签页）已被移除。现在烘焙通过 AI Navigation包（
com.unity.ai.navigation
）以组件化方式实现：为关卡几何体添加 NavMeshSurface 组件，点击 Bake 即可。运行时的
NavMeshAgent
/
NavMesh
API仍保留在内置的
UnityEngine.AI
命名空间中。

When to use

适用场景

Use when an agent needs to walk/chase/patrol to a target, when baking a navigable surface, adding dynamic blockers (
```
NavMeshObstacle
```
), or checking whether a destination is reachable.
Use when the project has the AI Navigation package, a
```
NavMeshSurface
```
component, or scripts using
```
UnityEngine.AI.NavMeshAgent
```
.

When not to use: the decision logic of when/where to move (FSMs, behaviour trees, steering) →

game-ai

(this skill is the Unity movement/pathing mechanism). Force-driven or kinematic movement that isn't pathfinding →

unity-physics

当智能体需要行走/追逐/巡逻到目标点、烘焙可导航表面、添加动态阻挡物（
```
NavMeshObstacle
```
），或检查目标点是否可达时使用。
当项目已安装AI Navigation包、包含
```
NavMeshSurface
```
组件，或脚本中使用
```
UnityEngine.AI.NavMeshAgent
```
时使用。

不适用场景： 何时/何地移动的决策逻辑（有限状态机、行为树、转向控制）→ 请使用

game-ai

（本技能仅为Unity中的移动/寻路机制）。非寻路的力驱动或运动学移动→ 请使用

unity-physics

。

Core workflow

核心工作流程

Install the AI Navigation package (Package Manager →
```
com.unity.ai.navigation
```
).
Bake a surface: select the static level geometry, Add Component → Navigation → NavMesh Surface, set the agent type/area settings, and click Bake. Re-bake whenever geometry,
```
NavMeshModifier
```
s, or agent settings change.
Add a
NavMeshAgent
to each moving NPC; its radius/height/speed must match the baked agent type, and it must spawn on the baked mesh.
Drive it from script with
```
SetDestination(targetPos)
```
; the agent steers and avoids other agents automatically. Detect arrival with
```
remainingDistance
```
/
```
pathPending
```
.
Handle dynamic blockers with
```
NavMeshObstacle
```
(carving) so closed doors/crates block paths without a full re-bake.
Verify with the AI Navigation overlay (the baked mesh is drawn in the Scene view) and by watching agents path around obstacles to the goal; check
```
NavMeshPath.status
```
for unreachable targets.

安装AI Navigation包（Package Manager中搜索
```
com.unity.ai.navigation
```
）。
烘焙导航表面： 选择静态关卡几何体，点击添加组件→导航→NavMeshSurface，设置智能体类型/区域参数，然后点击Bake。每当几何体、
```
NavMeshModifier
```
或智能体参数变化时，需重新烘焙。
为每个移动NPC添加
NavMeshAgent
组件：其半径/高度/速度必须与烘焙时设置的智能体类型匹配，且必须生成在已烘焙的导航网格上。
通过脚本驱动移动：使用
```
SetDestination(targetPos)
```
方法；智能体会自动转向并避开其他智能体。可通过
```
remainingDistance
```
/
```
pathPending
```
检测是否到达目标。
使用
NavMeshObstacle
处理动态阻挡物（开启Carve功能），这样关闭的门/箱子无需重新烘焙即可阻挡路径。
验证效果：通过AI Navigation叠加层（场景视图中会绘制已烘焙的网格）观察智能体绕过障碍物前往目标的路径；可通过
```
NavMeshPath.status
```
检查目标点是否不可达。

Patterns

实现模式

1. Chase/seek with a NavMeshAgent

1. 使用NavMeshAgent实现追逐/追踪

csharp

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;
}

csharp

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);   // 重新规划路径朝向目标
    }

    // 是否到达？pathPending用于防范路径生成前的第一帧异常。
    private bool HasArrived() =>
        !_agent.pathPending && _agent.remainingDistance <= _agent.stoppingDistance;
}

2. Check reachability before committing

2. 执行移动前检查可达性

csharp

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
}

csharp

using UnityEngine.AI;

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

3. Bake at runtime (for procedurally built or streamed levels)

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

csharp

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();

csharp

using Unity.AI.Navigation;   // 包的命名空间（NavMeshSurface）

[SerializeField] private NavMeshSurface surface;

// 生成关卡几何体后，通过代码重建导航网格。
public void RebuildNav() => surface.BuildNavMesh();

4. Dynamic obstacle that carves the mesh

4. 可切割网格的动态障碍物

csharp

// 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.

csharp

// 为门/箱子添加NavMeshObstacle组件（开启Carve = true）。当组件存在时，会在导航网格上切割出孔洞，让智能体绕路；移除/禁用组件即可重新开放路径——无需重新烘焙。

Pitfalls

常见陷阱

Looking for the Navigation window — it no longer exists in Unity 6. Use the AI Navigation package's
```
NavMeshSurface
```
component + Bake.
Agent doesn't move / warps to origin — it isn't on the baked mesh, or no surface was baked. Bake the surface and spawn the agent on it (
```
NavMesh.SamplePosition
```
to snap).
Agent ignores new geometry — the navmesh is baked; runtime-spawned obstacles need a
```
NavMeshObstacle
```
(carving) or a
```
surface.BuildNavMesh()
```
re-bake.
SetDestination
every frame is wasteful — for a slow-moving target, re-path on a timer (e.g. every 0.2s) instead of each frame.
Agent radius/height mismatch — if the
```
NavMeshAgent
```
's size differs from the baked agent type, it gets stuck in gaps or floats; keep them consistent.
Agents jitter against each other — tune
```
avoidancePriority
```
and quality, or use an obstacle for truly static blockers rather than relying on agent avoidance.

寻找Navigation窗口——Unity 6中已不再存在该窗口。请使用AI Navigation包的
```
NavMeshSurface
```
组件+Bake功能。
智能体不移动/瞬移到原点——智能体不在已烘焙的网格上，或未烘焙任何导航表面。请烘焙表面并将智能体生成在网格上（可使用
```
NavMesh.SamplePosition
```
对齐）。
智能体无视新增几何体——导航网格是烘焙生成的；运行时生成的障碍物需要添加
```
NavMeshObstacle
```
（开启切割）或调用
```
surface.BuildNavMesh()
```
重新烘焙。
每帧调用
SetDestination
过于浪费——对于移动缓慢的目标，可设置定时器（例如每0.2秒）重新规划路径，而非每帧执行。
智能体半径/高度不匹配——如果
```
NavMeshAgent
```
的尺寸与烘焙时的智能体类型不一致，会导致智能体卡在缝隙中或浮空；请保持两者参数一致。
智能体相互碰撞抖动——调整
```
avoidancePriority
```
和避让质量，或为真正静态的阻挡物添加障碍物组件，而非依赖智能体自身的避让机制。

References

参考资料

Primary docs: AI Navigation package manual (

https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/index.html

) and

ScriptReference/AI.NavMeshAgent

ScriptReference/AI.NavMesh

官方文档：AI Navigation包手册（

https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/index.html

）以及

ScriptReference/AI.NavMeshAgent

、

ScriptReference/AI.NavMesh

。

unity-navmesh

Original

Translation

Unity NavMesh (AI Navigation)

Unity NavMesh（AI导航）

When to use

适用场景

Core workflow

核心工作流程

Patterns

实现模式

1. Chase/seek with a NavMeshAgent

1. 使用NavMeshAgent实现追逐/追踪

2. Check reachability before committing

2. 执行移动前检查可达性

3. Bake at runtime (for procedurally built or streamed levels)

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

4. Dynamic obstacle that carves the mesh

4. 可切割网格的动态障碍物

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能