Unity AI Navigation

Retrieval Sources

Local coverage is lopsided and it is worth being precise about the shape of that imbalance. The AI Navigation package Manual page (Manual/com.unity.ai.navigation.html, package com.unity.ai.navigation version 2.0.14 for Unity Editor 6000.3) is a single 194-line landing-page stub: it contains only the package description ("high-level components that allow you to use navmeshes to incorporate navigation and pathfinding in your game... build and use navmeshes at runtime and at edit time, create dynamic obstacles, and use links..."), version/compatibility metadata, and a keyword index (carving, navmesh agent, navmesh link, navmeshlink, navmesh modifier, navmeshmodifier, navmesh modifier volume, navmeshmodifiervolume, navmesh obstacle, navmesh surface, navmeshsurface, offmesh link, pathfinding). A directory search of Manual/ for *navmesh* returns zero additional files — there are no local component reference pages for NavMeshSurface, NavMeshModifier, NavMeshModifierVolume, or NavMeshLink (the actual AI Navigation package components you drag onto GameObjects in the Editor). Any guidance on those four components in this skill is pretrained knowledge, flagged as such, not sourced from local docs.

In sharp contrast, the built-in UnityEngine.AI ScriptReference namespace is exhaustively documented locally: 252 files matching AI.*.html under ScriptReference/, covering every public class, struct, enum, method, and property of the legacy/low-level navigation API that the package's high-level components are built on top of. This is the namespace to lean on. The table below cites every class/member group actually found on disk (verified 2026-08-19 against /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/ScriptReference/), organized by subsystem.

38 substantive rows (39 counting the module overview) covering all 252 on-disk AI.* pages plus the 2 GameObjectUtility legacy helpers and the module-overview page — every path above was opened and its content verified on disk during this pass (2026-08-19), not inferred from filenames alone.

Key Guidelines

NavMesh Baking

Unity has two separate baking paths and conflating them causes real confusion. The classic Navigation window (Window > AI > Navigation) bakes a single navmesh for the whole open scene at edit time, driven by one NavMeshBuildSettings per agent type and the Navigation Static flag on each GameObject (set via the Inspector's Static dropdown or the Navigation window's Object tab) — only flagged geometry contributes. The AI Navigation package's NavMeshSurface component (pretrained knowledge — no local Manual page exists to cite) instead bakes per-GameObject, either at edit time via its Inspector "Bake" button or at runtime via NavMeshSurface.BuildNavMesh(), and supports multiple independent surfaces in one scene (e.g. a ground surface for walking agents and a separate surface at a different agent radius/height for flying or small agents). Under the hood both paths ultimately go through the same AI.NavMeshBuilder/AI.NavMeshBuildSettings/AI.NavMeshBuildSource machinery documented in ScriptReference. For fully scripted control — no NavMeshSurface component at all — call NavMeshBuilder.CollectSources to gather geometry into a List<NavMeshBuildSource>, then NavMeshBuilder.BuildNavMeshData to bake it into a NavMeshData asset, then NavMesh.AddNavMeshData to register it into the live navigation world.

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.AI;

public class RuntimeBake : MonoBehaviour
{
    NavMeshData navMeshData;
    NavMeshDataInstance instance;

    void Start()
    {
        var settings = NavMesh.CreateSettings();
        settings.agentRadius = 0.5f;
        settings.agentHeight = 2.0f;
        settings.agentSlope = 45f;
        settings.agentClimb = 0.4f;

        var sources = new List<NavMeshBuildSource>();
        var bounds = new Bounds(Vector3.zero, new Vector3(100f, 20f, 100f));
        NavMeshBuilder.CollectSources(
            bounds, ~0, NavMeshCollectGeometry.RenderMeshes,
            0, new List<NavMeshBuildMarkup>(), sources);

        navMeshData = NavMeshBuilder.BuildNavMeshData(
            settings, sources, bounds, Vector3.zero, Quaternion.identity);

        instance = NavMesh.AddNavMeshData(navMeshData);
    }

    // Call after procedural geometry changes (destructible walls, spawned terrain)
    public void Rebake()
    {
        var sources = new List<NavMeshBuildSource>();
        var bounds = navMeshData.sourceBounds;
        NavMeshBuilder.CollectSources(
            bounds, ~0, NavMeshCollectGeometry.RenderMeshes,
            0, new List<NavMeshBuildMarkup>(), sources);
        NavMeshBuilder.UpdateNavMeshData(navMeshData, NavMesh.GetSettingsByID(0), sources, bounds);
    }

    void OnDestroy() => instance.Remove();
}

NavMeshBuildSettings also carries voxelization/tiling precision knobs (voxelSize, tileSize, overrideVoxelSize/overrideTileSize) and auto-link generation distances (ledgeDropHeight, maxJumpAcrossDistance) — leave these at their defaults unless a bake is either too coarse (agents clip corners, thin gaps aren't traversable) or too slow (large open scenes with tiny voxel size).

NavMeshAgent Movement & Tuning

NavMeshAgent autonomously drives its GameObject's Transform every frame once given a destination via SetDestination(Vector3). SetDestination returns true if the request was accepted and is asynchronous — the path is not necessarily ready the same frame; check pathPending (true while the path is still being computed) and pathStatus (PathComplete/PathPartial/PathInvalid) before assuming the agent is en route. Because the agent moves the Transform directly, a non-kinematic Rigidbody on the same GameObject fights it every frame (physics and navigation both trying to own position) — omit the Rigidbody or set isKinematic = true. radius, height, speed, acceleration, angularSpeed, and stoppingDistance should match the character's actual capsule and desired feel; baseOffset lifts the visual model relative to the navmesh plane without changing the collision capsule. For cases where you don't want the agent to own the Transform (root-motion animation, a custom CharacterController), set updatePosition/updateRotation to false and read nextPosition/desiredVelocity each frame to drive the object yourself while the agent still does pathfinding and steering math.

using UnityEngine;
using UnityEngine.AI;

public class ClickToMove : MonoBehaviour
{
    NavMeshAgent agent;

    void Start() => agent = GetComponent<NavMeshAgent>();

    void Update()
    {
        if (Input.GetMouseButtonDown(0))
        {
            Ray ray = Camera.main.ScreenPointToRay(Input.mousePosition);
            if (Physics.Raycast(ray, out RaycastHit hit))
            {
                agent.SetDestination(hit.point);
            }
        }

        // Poll movement state instead of assuming the agent arrived
        if (!agent.pathPending && agent.remainingDistance <= agent.stoppingDistance
            && (!agent.hasPath || agent.velocity.sqrMagnitude == 0f))
        {
            // Arrived / idle
        }
    }
}

Use CalculatePath (either NavMeshAgent.CalculatePath or the static NavMesh.CalculatePath) to synchronously pre-check reachability or plan ahead without moving the agent — it's synchronous and can hurt frame rate on long paths, so budget it to a few calls per frame if evaluating many candidate destinations (e.g. patrol point scoring). Warp(Vector3) teleports the agent (and resets its path) without playing movement; use it for spawn placement or cutscene repositioning instead of setting transform.position directly, which desyncs the agent's internal navmesh location.

NavMeshObstacle & Carving

NavMeshObstacle marks a GameObject as a blocker other agents should route around. Its shape is either Box or Capsule, sized via center/size/radius/height. The critical property is carving (bool): when true, the obstacle cuts an actual hole in the navmesh so agents path around it in advance rather than only reacting at close range via local avoidance; when false, the obstacle only affects NavMeshAgent local avoidance steering (cheap, but agents can bunch up against it or clip through pure-obstacle-avoidance limits). Carving recalculation is not free, so Unity gives two throttling knobs: carveOnlyStationary (default-equivalent "carve when stationary" behavior — the hole is only cut in when the obstacle isn't moving, avoiding a re-carve every frame for something in constant motion) and, when carving-while-moving is wanted anyway, carvingMoveThreshold/carvingTimeToStationary control how far/how long the obstacle must be still before it's considered "stationary" and gets re-carved.

using UnityEngine;
using UnityEngine.AI;

[RequireComponent(typeof(NavMeshObstacle))]
public class Door : MonoBehaviour
{
    NavMeshObstacle obstacle;

    void Awake()
    {
        obstacle = GetComponent<NavMeshObstacle>();
        obstacle.shape = NavMeshObstacleShape.Box;
        obstacle.carving = true;
        obstacle.carveOnlyStationary = true; // cheap: only re-cuts the hole once the door stops
    }

    public void Open()
    {
        // Animate/move the door; while moving, no re-carve happens (carveOnlyStationary=true),
        // so agents keep routing around the door's last-stationary footprint until it settles.
    }
}

For obstacles that move constantly (a swarm of physics-driven crates, another agent's collider used as an obstacle proxy), consider disabling carving entirely and relying purely on NavMeshAgent local avoidance (obstacleAvoidanceType) instead — carving every frame for many fast-moving obstacles is a common performance cliff (see Advanced Notes).

Off-Mesh Links

Off-mesh links connect two points that aren't continuously walkable between (a gap to jump, a ledge to drop from, a ladder) so pathfinding can route across the disconnection. There are three ways to create one, all converging on the same runtime OffMeshLinkData: (1) the Inspector-facing OffMeshLink component with manually assigned startTransform/endTransform, optionally biDirectional and a costOverride; (2) auto-generated links created during baking when geometry has a drop within NavMeshBuildSettings.ledgeDropHeight or a gap within maxJumpAcrossDistance (these surface as OffMeshLinkType.LinkTypeDropDown / LinkTypeJumpAcross vs. the component's LinkTypeManual); (3) fully scripted via NavMesh.AddLink(NavMeshLinkData), which returns a NavMeshLinkInstance handle used later to Remove() the link — useful for procedurally generated connections with no Inspector object backing them. NavMeshLinkData costModifier: a positive value overrides the default cost-by-distance for traversing the link (e.g. make a long jump artificially "cheap" to encourage agents to prefer it, or expensive to discourage it as a last resort).

Whether an agent crosses a link automatically or the game code drives it is controlled by NavMeshAgent.autoTraverseOffMeshLink. When true (default), the agent animates straight across the link itself. When false, the agent stops at the link start and your code must read currentOffMeshLinkData to know the link, animate/reposition however you like (jump arc, ladder climb animation), and call CompleteOffMeshLink() when done — ActivateCurrentOffMeshLink(bool) can also gate whether the agent is allowed to enter a pending link at all.

using UnityEngine;
using UnityEngine.AI;

public class ManualLinkTraversal : MonoBehaviour
{
    NavMeshAgent agent;

    void Start()
    {
        agent = GetComponent<NavMeshAgent>();
        agent.autoTraverseOffMeshLink = false;
    }

    void Update()
    {
        if (agent.isOnOffMeshLink)
        {
            OffMeshLinkData data = agent.currentOffMeshLinkData;
            // Custom jump/climb animation driving transform.position from data.startPos to data.endPos
            if (JumpAnimationFinished())
                agent.CompleteOffMeshLink();
        }
    }

    bool JumpAnimationFinished() => true; // placeholder
}

// Fully scripted link, no OffMeshLink component
var link = new NavMeshLinkData
{
    startPosition = ledgeTop,
    endPosition = ledgeBottom,
    width = 1.0f,
    costModifier = -1f,   // negative = use default distance-based cost
    bidirectional = false,
    area = 0,
    agentTypeID = 0
};
NavMeshLinkInstance handle = NavMesh.AddLink(link);
// later: handle.Remove();

Runtime NavMesh Building (NavMeshSurface — pretrained knowledge, package Manual is thin)

The AI Navigation package's NavMeshSurface component is the recommended way to bake at runtime or maintain multiple independent surfaces, but — as noted in Retrieval Sources — there is no local Manual or ScriptReference page for it; everything in this subsection is pretrained knowledge and should be verified against Unity's online package docs before shipping. NavMeshSurface wraps the low-level NavMeshBuilder/NavMeshBuildSettings/NavMeshBuildSource API: add one per agent type (e.g. one surface with a small-radius NavMeshAgent profile for a cat NPC, a separate surface with a larger radius for a human NPC), set its collect-geometry mode (Render Meshes vs. Physics Colliders) and included layers, and call .BuildNavMesh() from code whenever the underlying geometry changes (procedural level generation, destructible terrain, spawned obstacles that should be baked in rather than carved by NavMeshObstacle). The companion NavMeshModifier component overrides the navigation area for a subtree (equivalent to setting NavMeshBuildSource.area/NavMeshBuildMarkup.overrideArea in the scripted API), and NavMeshModifierVolume applies an area override to everything inside a box volume regardless of what geometry is there (useful for a "danger zone" that should cost more to cross without modeling separate collision geometry). NavMeshLink is the package's Inspector-friendly counterpart to OffMeshLink/NavMeshLinkData, supporting the same start/end/width/bidirectional/cost fields.

// Pretrained knowledge — verify against Unity's online AI Navigation package docs
using UnityEngine;
using Unity.AI.Navigation;

public class ProceduralLevelBake : MonoBehaviour
{
    [SerializeField] NavMeshSurface surface;

    public void OnLevelGenerated()
    {
        surface.BuildNavMesh(); // full rebuild; consider async variants for large levels
    }
}

Area Costs & Layers

Navigation areas (Default, Not Walkable, Jump, plus up to 29 custom user-defined areas configured in the Navigation window's Areas tab) let you bias pathfinding toward or away from terrain types instead of hard-blocking them, by weighting the relative cost of crossing each area. Costs can be set at three scopes, checked in order of specificity by the pathfinder: a per-query NavMeshQueryFilter.SetAreaCost, a per-agent NavMeshAgent.SetAreaCost (only affects that one agent and any new agents created afterward inherit the global default, not this override), or the global NavMesh.SetAreaCost (replaces the default cost used by all agents and by any agent created after the call — cost must be > 1.0). Use NavMesh.GetAreaFromName("water") to resolve an area's index by its Inspector-configured name rather than hardcoding indices, which shift if areas are reordered.

using UnityEngine;
using UnityEngine.AI;

public class ToggleWaterCost : MonoBehaviour
{
    void Update()
    {
        if (Input.anyKeyDown)
        {
            // Make the water area 10x more costly to traverse for all agents.
            NavMesh.SetAreaCost(NavMesh.GetAreaFromName("water"), 10.0f);
        }
    }
}

// Per-agent override: this one agent avoids lava-tagged area entirely via areaMask,
// while treating "road" as cheaper than its walkable default.
agent.areaMask &= ~(1 << NavMesh.GetAreaFromName("lava"));
agent.SetAreaCost(NavMesh.GetAreaFromName("road"), 0.5f);

For query-scoped filtering without touching any agent's persistent state, build a NavMeshQueryFilter and pass it to the filtered overloads of NavMesh.CalculatePath/SamplePosition/Raycast/FindClosestEdge — this is the right tool for "what if this hypothetical agent type pathed here" checks (e.g. AI planning/utility scoring across multiple candidate agent profiles) without mutating any live agent.

Path Queries

NavMeshPath is a reusable container populated by CalculatePath — reuse one instance per caller instead of allocating a new one per query to avoid GC churn in hot loops (e.g. per-frame reachability checks for several AI agents). NavMeshPath.corners is the polyline of waypoints; status reports PathComplete (fully reaches target), PathPartial (best-effort path toward an unreachable target — common when the target is off the navmesh or in a disconnected/blocked area), or PathInvalid (no path at all). NavMesh.SamplePosition(sourcePosition, out NavMeshHit hit, maxDistance, areaMask) is the standard way to validate/snap an arbitrary world point (a raycast hit, a spawn point, a click position) onto the navmesh before using it as a destination — note hit.normal is documented as never computed (always (0,0,0)), only hit.position, hit.distance, hit.mask, hit.hit are meaningful. NavMesh.Raycast traces a straight line across the mesh and reports the first point where the mesh becomes untraversable (area mask mismatch or mesh edge) — useful for line-of-sight-along-ground checks distinct from a 3D physics raycast. NavMesh.CalculateTriangulation() dumps the entire baked mesh as a flat NavMeshTriangulation (vertices/indices/areas/layers) — heavy, intended for debug visualization or external tooling, not per-frame use.

using UnityEngine;
using UnityEngine.AI;

public class ReachabilityCheck : MonoBehaviour
{
    NavMeshPath scratchPath = new NavMeshPath(); // reused, not reallocated per call

    public bool CanReach(Vector3 from, Vector3 to)
    {
        if (!NavMesh.SamplePosition(to, out NavMeshHit hit, 2.0f, NavMesh.AllAreas))
            return false; // target isn't near any navmesh

        NavMesh.CalculatePath(from, hit.position, NavMesh.AllAreas, scratchPath);
        return scratchPath.status == NavMeshPathStatus.PathComplete;
    }
}

Common Mistakes

Quick Reference

Advanced Notes

Multi-agent crowd movement. NavMeshAgent local avoidance (steering agents around each other, not around baked-in obstacles) is governed by obstacleAvoidanceType (NoObstacleAvoidance, LowQualityObstacleAvoidance, MedQualityObstacleAvoidance, GoodQualityObstacleAvoidance, HighQualityObstacleAvoidance) — this is a per-agent tradeoff between steering realism and CPU cost, and it does not scale linearly: a scene with a few dozen HighQualityObstacleAvoidance agents can cost noticeably more than the same count at LowQualityObstacleAvoidance or NoObstacleAvoidance, because avoidance quality controls how many neighboring agents/obstacles are considered and how far ahead collisions are predicted. avoidancePriority (0–99, default 50) lets higher-priority agents (e.g. the player, key NPCs) push through crowds of lower-priority agents that yield instead of mutually contesting space — assign priority bands rather than leaving everything at 50, or dense crowds visibly jostle without resolving. NavMesh.avoidancePredictionTime (global static, default 2.0s, documented tuning range 0.5–5.0s) is the single biggest lever for crowd behavior at scale: shorter prediction windows make avoidance cheaper and more reactive/twitchy, longer windows make it smoother but pricier since more of each agent's future path must be checked against neighbors each tick. For genuinely large crowds (hundreds of agents), mixing avoidance quality by relevance — full quality only for agents near the camera/player, NoObstacleAvoidance or LowQualityObstacleAvoidance for background/offscreen agents — is a practical way to keep total avoidance cost bounded; this is a pattern to implement yourself (e.g. LOD-style distance checks each agent's script performs on itself) since the API has no built-in distance-based LOD for avoidance quality. NavMesh.pathfindingIterationsPerFrame bounds how many navmesh-polygon nodes the asynchronous pathfinder expands per frame — raising it makes individual async path requests resolve faster (fewer frames until pathPending goes false) at the cost of a frame-time spike when many agents request paths simultaneously (e.g. a wave-spawn of enemies all calling SetDestination the same frame); lowering it spreads that cost across more frames but delays path availability. Because it only affects the async path (the one behind SetDestination), it does not throttle the synchronous CalculatePath/NavMesh.CalculatePath calls, which always resolve within the calling frame regardless of this setting — that's precisely why those synchronous calls need their own manual per-frame throttling (see Common Mistakes) rather than relying on this knob.

Dynamic obstacle performance. Carving (NavMeshObstacle.carving = true) is the most expensive per-obstacle cost in the navigation system because it triggers a real navmesh polygon regeneration in the obstacle's vicinity, not just a steering adjustment — this is why carveOnlyStationary defaults to the recommended behavior of only re-cutting the hole once an obstacle stops moving, rather than re-carving every frame for something in constant motion. When an obstacle must carve while moving (a slow-moving elevator platform, a rolling boulder that should block path planning ahead of time, not just steer around reactively), carvingMoveThreshold (how far it must move to be considered "moving" again after settling) and carvingTimeToStationary (how long it must stay still before being re-carved as stationary) should be tuned together: a low threshold plus long stationary-time produces frequent flapping between carved/uncarved states (worst case for cost), while a high threshold plus short stationary-time produces stale carve holes that lag noticeably behind the obstacle's actual position. For scenes with many simultaneously-moving obstacles (a physics-driven debris field, a crowd of NPCs each also acting as obstacles for others), the practical ceiling is usually reached well before the agent-count ceiling — profile with the Unity Profiler's AI/Navigation markers specifically, since generic CPU profiling can misattribute carving cost to "physics" or "scripts" depending on what triggers the recarve. A common escape hatch when carving cost dominates: turn carving off for that category of obstacle entirely and let NavMeshAgent local avoidance (obstacleAvoidanceType) handle it reactively instead — this trades "agents plan routes around the obstacle in advance" for "agents steer around it at close range," which is often an acceptable and much cheaper tradeoff for obstacles that are numerous, small, or short-lived (dropped items, thrown projectiles, temporary hazards) rather than large fixed-duration blockers (a closed door, a parked vehicle) where advance route planning actually matters to believability.