/unity-navmesh

name: unity-navmesh
description: >
  Unity 6.3 LTS pathfinding with the AI Navigation package: NavMeshSurface baking, NavMeshAgent,
  NavMeshLink jumps and runtime rebakes. Use when a Unity enemy should chase or patrol, an agent
  will not move or warps, a path is partial, or the Bake tab is missing. Not for deciding when
  NPCs move (`game-ai`, `ai-behavior-trees-utility-ai`) or force-driven movement
  (`unity-physics`).

Unity NavMesh (AI Navigation)

Give NPCs pathfinding in Unity 6.3 LTS (6000.3) with the AI Navigation package 2.0: bake walkable surfaces, move agents around obstacles, and prove the mesh and paths exist by reading them back.

> **Version trap:** the old built-in Navigation window (Object and Bake tabs, the "Navigation > Static" flag) is gone. Baking is component-based: a `NavMeshSurface` > (`Unity.AI.Navigation`, package `com.unity.ai.navigation`) holds the bake settings and the > baked data. The package's **Window > AI > Navigation** only edits agent types and areas. > The runtime API (`NavMeshAgent`, `NavMesh`, `NavMeshObstacle`) stays in `UnityEngine.AI`.

When to use

• An agent needs to walk, chase or patrol to a target; a level needs a baked surface;

doors or crates should block paths at runtime; you need to know whether a target is reachable.

• The project has `com.unity.ai.navigation`, a `NavMeshSurface`, or scripts using

`UnityEngine.AI`.

**When not to use:** the decision of when and where to move → `game-ai` or `ai-behavior-trees-utility-ai`; force-driven or kinematic movement that is not pathfinding → `unity-physics`. If Unity's official `initialize-ai-navigation` skill is installed and an Editor is connected, it can add and bake the components for you; this skill still owns the agent code and the checks.

Workflow

1. **Gate on the package.** Look for `com.unity.ai.navigation` in `Packages/packages-lock.json`, not only `manifest.json`: a package the Editor has not resolved yet produces the same "type not found" errors as one that was never added. If it is missing, ask before adding it to `manifest.json`. 2. **Take inventory before adding anything.** Grep the scenes for `NavMeshSurface`, `NavMeshAgent`, `NavMeshObstacle`, `NavMeshLink` and the deprecated `OffMeshLink`. Agent types (radius, height, step, slope) and area names live in `ProjectSettings/NavMeshAreas.asset` (`m_Settings`, `areas`). 3. **Bake the surface.** Pick one path:

• Unity CLI with a ready Editor: `unity command navmesh bake_surfaces` (the plain

`navmesh bake` command is the old built-in bake, not `NavMeshSurface`).

• Procedural or streamed levels: call `surface.BuildNavMesh()` after the geometry exists

(pattern 3). Nothing is saved to disk.

• Otherwise ask the user to select the GameObject with the `NavMeshSurface` and press

**Bake**, then confirm from the file (step 6). Re-bake whenever geometry, `NavMeshModifier`s or agent settings change. 4. **Add a `NavMeshAgent`** whose agent type matches the baked one, spawned on the mesh. Drive it with `SetDestination`; detect arrival with `pathPending` and `remainingDistance`. 5. **Block paths at runtime** with `NavMeshObstacle` and `carving = true` instead of a rebake. Bridge separate islands (ledges, gaps) with a `NavMeshLink`. 6. **Verify** with the checks below.

Patterns

1. Chase with a re-path timer

using UnityEngine;
using UnityEngine.AI;

[RequireComponent(typeof(NavMeshAgent))]
public class Chaser : MonoBehaviour
{
    [SerializeField] private Transform target;
    [SerializeField] private float repathInterval = 0.2f;
    private NavMeshAgent _agent;
    private float _nextRepath;

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

    private void Update()
    {
        if (!target || Time.time < _nextRepath) return;
        _nextRepath = Time.time + repathInterval;
        _agent.SetDestination(target.position);
    }

    // pathPending guards the frames before the first path exists.
    public bool HasArrived() =>
        !_agent.pathPending && _agent.remainingDistance <= _agent.stoppingDistance;
}

2. Check reachability before committing

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

3. Bake at runtime and bridge a gap

using Unity.AI.Navigation;
using UnityEngine;

public class LevelNav : MonoBehaviour
{
    [SerializeField] private NavMeshSurface surface;

    // Call after spawning the level geometry.
    public void Rebuild() => surface.BuildNavMesh();

    // One-way drop from a ledge to the floor below.
    public NavMeshLink AddDrop(Vector3 ledge, Vector3 landing)
    {
        var link = gameObject.AddComponent<NavMeshLink>();
        // Points are local to this GameObject; the link ignores its scale.
        Quaternion toLocal = Quaternion.Inverse(transform.rotation);
        link.startPoint = toLocal * (ledge - transform.position);
        link.endPoint = toLocal * (landing - transform.position);
        link.width = 1f;
        link.bidirectional = false;
        return link;
    }
}

Verify

Say which path you used.

• **Unity CLI with a ready Editor:** after the bake, read the mesh and a real path back:

  unity command script eval --code 'var t = UnityEngine.AI.NavMesh.CalculateTriangulation(); return "triangles=" + t.indices.Length / 3;'
  unity command script eval --code 'var p = new UnityEngine.AI.NavMeshPath(); UnityEngine.AI.NavMesh.CalculatePath(GameObject.Find("Enemy").transform.position, GameObject.Find("Player").transform.position, UnityEngine.AI.NavMesh.AllAreas, p); return p.status.ToString();'

Zero triangles means nothing is baked or loaded. In Play mode, also read `agent.isOnNavMesh` and `agent.pathStatus` for each agent. Find current command