Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/unity/unity-navmesh

unity-navmesh

Verified

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, NavMeshModifiers 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 names with unity command --query navmesh.

  • No CLI: a baked surface stores a reference in the scene file. Grep the .unity for the surface's m_NavMeshData: line; {fileID: 0} means it was never baked or was cleared, and a guid: means baked data exists (check that asset file is present). Then write a PlayMode test that loads the scene, calls NavMesh.CalculatePath between two known points and asserts PathComplete; run it as described in unity-csharp-scripting.

  • Behavior you cannot assert: ask the user to press Play and report whether each agent reaches the target and roughly how long it takes.

Gotchas

  • Looking for the Bake tab or Navigation Static. Removed with AI Navigation 2.0. Bake from a NavMeshSurface.
  • Agent does not move or warps to the origin. It is not on the baked mesh, or no surface is baked or enabled (only enabled surfaces on active GameObjects load their data). Snap the spawn with NavMesh.SamplePosition and move it with agent.Warp, not the Transform.
  • PathPartial. The target is on another island. Add a NavMeshLink or extend the geometry so one surface covers both; a partial path only reaches the near edge.
  • Agents ignore new geometry. The mesh is baked data. Runtime props need a carving NavMeshObstacle or a BuildNavMesh().
  • An NPC with a Rigidbody jitters or drifts. The agent and a non-kinematic Rigidbody both move the Transform. Make the body kinematic while the agent is in control.
  • An agent with a NavMeshObstacle on the same GameObject spins or slides. It avoids itself. Enable only one at a time, for example switch the agent off and the obstacle on when the NPC stops for good.
  • Agent size does not match the baked agent type. It gets stuck in gaps or floats. Keep the agent's type, radius and height consistent with the surface's agent type.
  • OffMeshLink in old scenes. Deprecated in AI Navigation 2.0 and gone from the Add Component menu. Replace it with NavMeshLink, which adds Transform endpoints and an activated flag.
  • SetDestination every frame for many agents. Wasted path queries; re-path on a timer (pattern 1) or when the target moved more than a threshold.
  • Agents jitter against each other. Tune avoidancePriority and the obstacle avoidance quality, or use an obstacle for blockers that never move.

References

Related skills

  • game-ai: engine-neutral decisions (FSM, steering, perception) that use this movement.
  • unity-csharp-scripting: the MonoBehaviour around the agent, test assemblies and the .meta checker.
  • tower-defense, fps-shooter: genres that combine pathfinding with gameplay.

Version notes

Last verified: 2026-11-11.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall