🚶 Lesson 6.2: Moving Agents — Destinations & Patrol Routes

SetDestination: One Line to Move

To move an agent, you give it a world position and it does the rest — finds the path, steers around obstacles, and walks there:

using UnityEngine;
using UnityEngine.AI;

[RequireComponent(typeof(NavMeshAgent))]
public class GoToTarget : MonoBehaviour
{
    [SerializeField] Transform target;
    NavMeshAgent agent;

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

    void Start()
    {
        if (target != null)
            agent.SetDestination(target.position);   // that's the whole thing
    }
}

That single call kicks off asynchronous pathfinding. Unity computes a corner list across the NavMesh from the agent to the destination, then the agent follows it, updating its own Transform position and rotation every frame. You never touch transform.position yourself — if you do, you'll fight the agent and get jitter.

Knowing When You've Arrived

The trickiest part of agent movement isn't starting — it's knowing when the agent has finished. The naive check "is my distance to the target small?" fails, because the agent walks the NavMesh path, which is usually longer than the straight line. Unity gives you the right tools:

• pathPending — true while Unity is still computing the path. You must wait for this to be false before trusting the distance.
• remainingDistance — the distance left along the path. This is the number to compare against stoppingDistance.
• hasPath and velocity — a fully arrived agent has no path and (near) zero velocity.

The idiomatic "have I arrived?" check combines them:

bool ReachedDestination()
{
    // 1. path still being calculated? not arrived yet
    if (agent.pathPending) return false;

    // 2. still farther than our stopping distance? still walking
    if (agent.remainingDistance > agent.stoppingDistance) return false;

    // 3. either no path left, or we've slowed to a stop
    return !agent.hasPath || agent.velocity.sqrMagnitude < 0.01f;
}

All three checks matter. Skip pathPending and you'll get a false "arrived" on the very first frame (when remainingDistance is still 0 because no path exists yet). The velocity check handles the case where the agent has a path but is idling at the destination.

A Waypoint Patrol

A patrol is the classic enemy behaviour: walk to waypoint 0, then 1, then 2, then loop back to 0 forever. With SetDestination and an arrival check, it's short:

using UnityEngine;
using UnityEngine.AI;

[RequireComponent(typeof(NavMeshAgent))]
public class Patrol : MonoBehaviour
{
    [SerializeField] Transform[] waypoints;
    [SerializeField] float waitAtPoint = 1.5f;

    NavMeshAgent agent;
    int index = 0;
    float waitTimer = 0f;

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

    void Start()
    {
        if (waypoints.Length > 0)
            agent.SetDestination(waypoints[index].position);
    }

    void Update()
    {
        if (waypoints.Length == 0) return;

        if (ReachedDestination())
        {
            // pause a beat at the waypoint, then advance to the next
            waitTimer += Time.deltaTime;
            if (waitTimer >= waitAtPoint)
            {
                waitTimer = 0f;
                index = (index + 1) % waypoints.Length;   // loop
                agent.SetDestination(waypoints[index].position);
            }
        }
    }

    bool ReachedDestination()
    {
        if (agent.pathPending) return false;
        if (agent.remainingDistance > agent.stoppingDistance) return false;
        return !agent.hasPath || agent.velocity.sqrMagnitude < 0.01f;
    }
}

The modulo (% waypoints.Length) is what makes it loop: after the last waypoint, index wraps back to 0. Drop empty GameObjects around your level, drag them into the waypoints array in order, and the agent walks the circuit. Here's a top-down view of what that circuit looks like:

Reading the Route

The Update loop above hides a small state machine: the agent is either travelling to a waypoint or waiting at one, and arrival is what flips it. Seeing that logic as a flow makes the wrap-around click:

Figure 2: The waypoint-advance logic. Arrival triggers a wait; the wait expiring advances the index (wrapping with modulo) and sets the next destination.

A few properties are worth knowing for debugging and for the states you'll build next lesson:

• agent.destination — the current target position (read it back to confirm what you set).
• agent.isStopped — set true to freeze the agent in place without losing its path; set false to resume. Great for "pause while attacking."
• agent.pathStatus — Complete, Partial (couldn't fully reach — target is off the mesh or blocked), or Invalid. Check for Partial when a destination might be unreachable.

💡 Warp, don't teleport. If you ever need to move an agent instantly (respawn, cutscene), use agent.Warp(position), not transform.position = position. Warp re-seats the agent on the NavMesh correctly; a raw Transform assignment can leave it confused about where it is on the mesh.

Obstacles: Carving vs. Re-baking

Your baked NavMesh is a snapshot. So what happens when something blocks the path after the bake — a door slams shut, a crate gets pushed into the corridor, a car parks across the road? You have two tools, and picking the right one matters.

• NavMeshObstacle (with Carving) — add a NavMeshObstacle component to the moving thing. With Carve ticked, it cuts a hole in the NavMesh at runtime wherever it sits, and agents path around it live. This is the right choice for things that move: doors, crates, other characters, destructible cover.
• Re-baking — regenerate the whole surface. Expensive and causes a hitch, so it's for author-time or rare, deliberate level changes (a wall collapses once in a scripted event), not per-frame movement.

The rule of thumb:

There's one important subtlety. An obstacle with carving off still pushes agents away via avoidance, but it does not alter the path — agents will keep trying to walk their original route and just bump against it. Turn carving on when you need agents to actually re-route around the blockage. Carving is more expensive (it edits the mesh), so use it only where re-routing is required.

Hands-on Challenge

Summary

🚀 What's Next?

Right now the agent only ever patrols — it can't react to anything. In Lesson 6.3: An Enemy State Machine you'll wrap this patrol in a code-driven FSM with Patrol, Chase, and Attack states, so the enemy switches behaviour based on where the player is, and feeds the Animator from Module 1 as it does.