Unity NavMesh (AI Navigation)
Give NPCs pathfinding in Unity 6.3 LTS: bake walkable surfaces and move agents around obstacles.
Targets Unity 6.3 LTS (6000.3) with the AI Navigation package 2.0 (2.0.16 at last check).
Version trap (Unity 2022+/6): the old built-in Navigation window (Object/Bake tabs,
"Navigation Static" flag) is gone. The package's Window → AI → Navigation only holds the
Agents and Areas tabs. 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.
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.
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,
NavMeshModifiers, or agent settings change. Agent types (radius, height, step, slope)
are defined in Window → AI → Navigation → Agents.
- 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.
Patterns
1. Chase/seek with a 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. Check reachability before committing
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. Bake at runtime (for procedurally built or streamed levels)
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. Dynamic obstacle that carves the mesh
// 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. Connect separate mesh pieces with a NavMeshLink (jumps, doors, gaps)
// 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).
Pitfalls
- Looking for the Bake tab or the Navigation Static flag — the old Navigation window was
removed in AI Navigation 2.0. Bake from a
NavMeshSurface component; the package's
Window → AI → Navigation only edits agent types and areas.
- 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.
- An NPC with a Rigidbody jitters or drifts off its path — a
NavMeshAgent and a
non-kinematic Rigidbody both move the transform. Tick Is Kinematic while the agent
is in control.
- An agent with a
NavMeshObstacle on the same GameObject spins or slides — it tries to
avoid itself (worse with carving). Keep only one of them enabled at a time, e.g. switch the
agent off and the obstacle on when the NPC stops for good.
- Teleporting an agent — use
agent.Warp(position) (returns false if it fails), not a
plain Transform write.
- 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.
- Reaching for
OffMeshLink — the built-in OffMeshLink component is deprecated in
AI Navigation 2.0 and can no longer be added from the Add Component menu. Use a
NavMeshLink (from the package, Unity.AI.Navigation) instead — it adds Transform-based
endpoints and a runtime activated property. Migrate any existing OffMeshLinks.
CalculatePath returns PathPartial — the destination sits on a different baked
island than the agent (a gap the mesh doesn't cross). Bridge the two with a NavMeshLink
(pattern 5) or extend the geometry so one surface covers both; a partial path only reaches
the near edge.
References
- Primary docs: AI Navigation package manual
(
https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/index.html),
the NavMeshLink page
(https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/NavMeshLink.html)
and its "What's new" note on the OffMeshLink deprecation
(https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/whats-new.html), the
"Navigation window" and "Use NavMesh Agent with other components" pages
(NavigationWindow.html, MixingComponents.html in the same manual), plus
ScriptReference/AI.NavMeshAgent, ScriptReference/AI.NavMesh.
Related skills
game-ai — engine-agnostic decision-making (FSM, behaviour trees, steering) that uses this.
unity-csharp-scripting — the MonoBehaviour structure around the agent.
tower-defense / fps-shooter — genres that compose pathfinding with gameplay.
1---2name: unity-navmesh3description: >4 Add AI navigation in Unity 6.3 LTS: bake a NavMesh with the AI Navigation package (NavMeshSurface),5 move agents with NavMeshAgent.SetDestination, and handle dynamic obstacles. Use when setting6 up pathfinding, making an enemy chase the player, baking navigation, or when the user7 mentions NavMesh, NavMeshAgent, NavMeshSurface, NavMeshObstacle, or Unity pathfinding.8metadata:9 source: https://skillmd.com/skills/junmystery/unity-navmesh10---1112# Unity NavMesh (AI Navigation)1314Give NPCs pathfinding in Unity 6.3 LTS: bake walkable surfaces and move agents around obstacles.15Targets **Unity 6.3 LTS (6000.3)** with the **AI Navigation package 2.0** (2.0.16 at last check).1617> **Version trap (Unity 2022+/6):** the old built-in **Navigation window** (Object/Bake tabs,18> "Navigation Static" flag) is gone. The package's **Window → AI → Navigation** only holds the19> Agents and Areas tabs. Baking is now **component-based** via the **AI Navigation package**20> (`com.unity.ai.navigation`): add a **NavMeshSurface** to your level geometry and click21> **Bake**. The *runtime* `NavMeshAgent`/`NavMesh` API stays in built-in `UnityEngine.AI`.2223## When to use2425- Use when an agent needs to walk/chase/patrol to a target, when baking a navigable surface,26 adding dynamic blockers (`NavMeshObstacle`), or checking whether a destination is reachable.27- Use when the project has the AI Navigation package, a `NavMeshSurface` component, or scripts28 using `UnityEngine.AI.NavMeshAgent`.2930**When *not* to use:** the *decision* logic of when/where to move (FSMs, behaviour trees,31steering) → `game-ai` (this skill is the Unity movement/pathing mechanism). Force-driven or32kinematic movement that isn't pathfinding → `unity-physics`.3334## Core workflow35361. **Install the AI Navigation package** (Package Manager → `com.unity.ai.navigation`).372. **Bake a surface:** select the static level geometry, **Add Component → Navigation → NavMesh38 Surface**, set the agent type/area settings, and click **Bake**. Re-bake whenever geometry,39 `NavMeshModifier`s, or agent settings change. Agent types (radius, height, step, slope)40 are defined in **Window → AI → Navigation → Agents**.413. **Add a `NavMeshAgent`** to each moving NPC; its radius/height/speed must match the baked42 agent type, and it must spawn *on* the baked mesh.434. **Drive it from script** with `SetDestination(targetPos)`; the agent steers and avoids other44 agents automatically. Detect arrival with `remainingDistance`/`pathPending`.455. **Handle dynamic blockers** with `NavMeshObstacle` (carving) so closed doors/crates block46 paths without a full re-bake.476. **Verify** with the AI Navigation overlay (the baked mesh is drawn in the Scene view) and by48 watching agents path around obstacles to the goal; check `NavMeshPath.status` for49 unreachable targets.5051## Patterns5253### 1. Chase/seek with a NavMeshAgent5455```csharp56using UnityEngine;57using UnityEngine.AI;5859[RequireComponent(typeof(NavMeshAgent))]60public class Chaser : MonoBehaviour61{62 [SerializeField] private Transform target;63 private NavMeshAgent _agent;6465 private void Awake() => _agent = GetComponent<NavMeshAgent>();6667 private void Update()68 {69 if (target) _agent.SetDestination(target.position); // re-path toward the target70 }7172 // Arrived? pathPending guards the first frame before a path exists.73 private bool HasArrived() =>74 !_agent.pathPending && _agent.remainingDistance <= _agent.stoppingDistance;75}76```7778### 2. Check reachability before committing7980```csharp81using UnityEngine.AI;8283public bool CanReach(NavMeshAgent agent, Vector3 destination)84{85 var path = new NavMeshPath();86 agent.CalculatePath(destination, path);87 return path.status == NavMeshPathStatus.PathComplete; // vs Partial / Invalid88}89```9091### 3. Bake at runtime (for procedurally built or streamed levels)9293```csharp94using Unity.AI.Navigation; // the package namespace (NavMeshSurface)9596[SerializeField] private NavMeshSurface surface;9798// After spawning level geometry, build the navmesh in code.99public void RebuildNav() => surface.BuildNavMesh();100```101102### 4. Dynamic obstacle that carves the mesh103104```csharp105// Add a NavMeshObstacle (Carve = true) to a door/crate. While present it cuts a hole in the106// navmesh so agents route around it; remove/disable it to reopen the path — no re-bake needed.107```108109### 5. Connect separate mesh pieces with a NavMeshLink (jumps, doors, gaps)110111```csharp112// Two baked surfaces that don't touch (a ledge and the floor below, two platforms across a113// gap) are separate islands — an agent can't path between them. Add Component > Navigation >114// NavMesh Link to bridge them: assign Start/End Transforms, set Width (0 = point-to-point),115// and toggle Bidirectional for one-way vs two-way. NavMeshLink lives in Unity.AI.Navigation.116// It replaces the deprecated built-in OffMeshLink (see pitfalls).117```118119## Pitfalls120121- **Looking for the Bake tab or the Navigation Static flag** — the old Navigation window was122 removed in AI Navigation 2.0. Bake from a `NavMeshSurface` component; the package's123 Window → AI → Navigation only edits agent types and areas.124- **Agent doesn't move / warps to origin** — it isn't on the baked mesh, or no surface was125 baked. Bake the surface and spawn the agent on it (`NavMesh.SamplePosition` to snap).126- **Agent ignores new geometry** — the navmesh is baked; runtime-spawned obstacles need a127 `NavMeshObstacle` (carving) or a `surface.BuildNavMesh()` re-bake.128- **`SetDestination` every frame is wasteful** — for a slow-moving target, re-path on a timer129 (e.g. every 0.2s) instead of each frame.130- **An NPC with a Rigidbody jitters or drifts off its path** — a `NavMeshAgent` and a131 non-kinematic `Rigidbody` both move the transform. Tick **Is Kinematic** while the agent132 is in control.133- **An agent with a `NavMeshObstacle` on the same GameObject spins or slides** — it tries to134 avoid itself (worse with carving). Keep only one of them enabled at a time, e.g. switch the135 agent off and the obstacle on when the NPC stops for good.136- **Teleporting an agent** — use `agent.Warp(position)` (returns false if it fails), not a137 plain Transform write.138- **Agent radius/height mismatch** — if the `NavMeshAgent`'s size differs from the baked agent139 type, it gets stuck in gaps or floats; keep them consistent.140- **Agents jitter against each other** — tune `avoidancePriority` and quality, or use an141 obstacle for truly static blockers rather than relying on agent avoidance.142- **Reaching for `OffMeshLink`** — the built-in `OffMeshLink` component is **deprecated** in143 AI Navigation 2.0 and can no longer be added from the Add Component menu. Use a144 **`NavMeshLink`** (from the package, `Unity.AI.Navigation`) instead — it adds Transform-based145 endpoints and a runtime `activated` property. Migrate any existing `OffMeshLink`s.146- **`CalculatePath` returns `PathPartial`** — the destination sits on a *different* baked147 island than the agent (a gap the mesh doesn't cross). Bridge the two with a `NavMeshLink`148 (pattern 5) or extend the geometry so one surface covers both; a partial path only reaches149 the near edge.150151## References152153- Primary docs: AI Navigation package manual154 (`https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/index.html`),155 the `NavMeshLink` page156 (`https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/NavMeshLink.html`)157 and its "What's new" note on the `OffMeshLink` deprecation158 (`https://docs.unity3d.com/Packages/com.unity.ai.navigation@2.0/manual/whats-new.html`), the159 "Navigation window" and "Use NavMesh Agent with other components" pages160 (`NavigationWindow.html`, `MixingComponents.html` in the same manual), plus161 `ScriptReference/AI.NavMeshAgent`, `ScriptReference/AI.NavMesh`.162163## Related skills164165- `game-ai` — engine-agnostic decision-making (FSM, behaviour trees, steering) that *uses* this.166- `unity-csharp-scripting` — the MonoBehaviour structure around the agent.167- `tower-defense` / `fps-shooter` — genres that compose pathfinding with gameplay.