Manual
Manual
Agents
An agent walks the navmesh to where it is sent: along a path around walls and holes, steering around the other agents, slowing as it arrives. This page covers the Nav Mesh Agent 3D and its twin in 2D, sending agents from code, avoidance, moving an agent's entity yourself, and finding paths on a navmesh from code.
Nav Mesh Agent 3D
A Nav Mesh Agent 3D makes its entity walk the navmesh of its agent type while the game plays. Nothing walks while you edit. An agent needs a baked navmesh under it: it is put on the first navmesh of its type within a couple of meters of where its entity stands.
| Field | What it does |
|---|---|
| Agent Type | Which agent type it is, by name: its width and height, and the navmesh it walks. Humanoid at first. |
| Speed | How fast it walks, in meters a second. 3.5 at first. |
| Angular Speed | How fast it turns to face where it walks, in degrees a second. 120 at first. |
| Acceleration | How fast it gets up to speed and slows down, in meters a second each second. 8 at first. |
| Stopping Distance | How near where it is sent it stops, in meters. 0 at first. |
| Auto Braking | Whether it slows as it comes to where it is sent, rather than arriving at full speed. On at first. |
| Base Offset | How far above the navmesh its entity is put, in meters: from its feet to the entity's middle. |
| Avoidance | How well it steers around other agents and moving obstacles: None, Low, Medium, Good or High. High at first. |
| Priority | How readily it keeps clear of others, from 0 to 99. 50 at first. |
| Update Position | Whether it moves its entity. Off, it only steers; see Move the entity yourself. |
| Update Rotation | Whether it turns its entity to face where it walks. |
| Destination | Where it walks to, while Has Destination is on and Target is none. |
| Has Destination | Whether it walks to Destination. |
| Target | An entity it follows wherever that goes. While one is named, Destination is not walked to. |
| Stopped | Holds it where it stands, though it is sent somewhere. |
| Area Mask | The areas its path may cross, ticked by name. Everything at first. |
| Auto Traverse | Whether it crosses links by itself. On at first. |
The agent puts its entity where it walks, Base Offset above the navmesh, and turns the entity's +Z, the way an imported model faces, toward the way it walks at Angular Speed.
What it writes back
Each frame, the agent writes what it did into its own fields, for any system to read. They are hidden from the Inspector's normal view; turn on Debug to see them.
| Field | What it holds |
|---|---|
Velocity | How it moves, in meters a second. |
RemainingDistance | How far it has left to walk along its path, in meters; 0 with nowhere to go. |
Arrived | Whether it has come within Stopping Distance of where it was sent. |
OnNavMesh | Whether it stands on a navmesh of its type. False where it was put where none is. |
OnLink | Whether it is crossing a link. |
LinkProgress | How far across the link it is, from 0 at its start to 1 at its end. |
LinkStart, LinkEnd | The ends of the link it crosses, in the world. |
Nav Mesh Agent 2D
A Nav Mesh Agent 2D walks the navmesh of a Nav Mesh Surface 2D, moving its entity across X and Y and keeping its Z. Its fields are the Nav Mesh Agent 3D's, with these differences:
- Destination is a point on the XY plane, and what it writes back (
Velocity,LinkStart,LinkEnd) is on that plane too. - It has no Base Offset: its entity is put where it walks.
- Update Rotation, off at first, turns its entity about Z so the entity's up, its +Y, points the way it walks, at Angular Speed, 360 degrees a second at first.
It is sent as the 3D one is, by its fields: a 2D patrol is the one below with Vector2 points and NavMeshAgent2D.
Send an agent from code
An agent goes where its fields say, so sending one is setting them in a system. This patrol walks each agent between two points, turning back each time it arrives:
using System.Numerics;using System.Runtime.CompilerServices;using Abyss.Core;using Abyss.Navigation;
namespace MyGame;
[AbyssComponent]public partial struct Patrol{ public Vector3 A; public Vector3 B; public bool ToB;}
public static partial class Patrolling{ [AbyssSystem] [MethodImpl(MethodImplOptions.AggressiveInlining)] private static void Walk(ref NavMeshAgent3D agent, ref Patrol patrol) { if (agent.Arrived || !agent.HasDestination) { patrol.ToB = !patrol.ToB; agent.Destination = patrol.ToB ? patrol.B : patrol.A; agent.HasDestination = true; } }}
// In a plugin's Build:Patrolling.AddWalk(schedule, world.Component<NavMeshAgent3D>(), world.Component<Patrol>());Each way to send an agent:
- To a point: set
Destinationand turnHasDestinationon. - After an entity: set
Target, asagent.Target = new EntityRef(player);. The agent follows it wherever it goes, finding its path again as it moves. Set it back toEntityRef.Noneto stop following. A target that is gone sends the agent to itsDestinationinstead, if it has one. - Nowhere: turn
HasDestinationoff with noTarget, and it stops where it is. - Hold it: turn
Stoppedon. It stands still until you turn it off, then walks on.
It arrives within StoppingDistance. Pushed farther away after that, it walks back.
Avoidance and priority
Agents on the same navmesh steer around each other as they walk, and around obstacles that move. Avoidance sets how well: None walks through the others, and each step up to High steers better and costs more.
Priority says how hard an agent keeps clear of the others: one numbered higher steps aside more for one numbered lower. Two agents meeting head on in a narrow corridor both slow and squeeze past each other; neither waits for the other.
A navmesh holds up to 512 walking agents at once.
Move the entity yourself
With Update Position off, the agent only steers. Something else moves the entity, such as your own system or a Rigidbody 3D, and the agent follows wherever the entity went. Read its Velocity to know which way to go:
// In a static partial class, added in a plugin's Build with AddSteer, as any system is.[AbyssSystem(Fixed = true)][MethodImpl(MethodImplOptions.AggressiveInlining)]private static void Steer(ref Rigidbody3D body, in NavMeshAgent3D agent){ // Walk where the agent steers, and keep falling as physics says. body.LinearVelocity = agent.Velocity with { Y = body.LinearVelocity.Y };}Turn Update Rotation off as well to turn the entity yourself, for a character that faces where it aims rather than where it walks.
Paths from code
The navmeshes are a service of the world, which any system can ask: context.Services.Get<Navigation3D>() in a system, or world.Navigation3D() elsewhere. It answers while you edit as well as while the game plays, as soon as a surface's navmesh is loaded. Navmeshes in 2D are their own service, Navigation2D, which answers the same questions with Vector2 points: world.Navigation2D().FindPath(guard, player) gives a NavPath2D.
using Abyss.Navigation;
Navigation3D navigation = context.Services.Get<Navigation3D>();
NavPath3D path = navigation.FindPath(guard, player); // two points in the worldif (path.Found){ // path.Corners: where to walk, from the start; path.Partial where the end could not be reached}
bool onFloor = navigation.ClosestPoint(clicked, out Vector3 floor); // the navmesh nearest a clickbool blocked = navigation.Raycast(guard, player, out Vector3 wall); // a straight walk, and where a wall stops itNavPath3D wide = navigation.FindPath(from, to, agentType: 1); // on the navmesh of the second agent type| Method | What it does |
|---|---|
FindPath(from, to, agentType, areaMask) | A path's corners from one point to another, crossing only the areas areaMask ticks. Where the end cannot be reached, the path ends as close as it gets and Partial is true. NavPath3D.None, with no corners, where either point is not near a navmesh. |
ClosestPoint(point, out closest, agentType) | The point of the navmesh closest to point, and whether there is one that close. |
Raycast(from, to, out hit, agentType) | Walks straight from from toward to on the navmesh, and says whether a wall or the navmesh's edge stops it short, and where. |
PathOf(agent, corners) | The corners of the path an agent is walking, from where it is, while the game plays. |
agentType is the agent type's place in Project Settings ▸ Navigation, 0 for the first, and can be left out. Where several surfaces are baked for one agent type, each question goes to the first whose navmesh the start is on. The service is safe to ask from systems that run in parallel.
Seen in the Scene view
A picked agent is drawn as its agent type's size, a cylinder on the floor it stands on, or a circle about it in 2D. While you edit, the path it would take to where it is sent is drawn with it; while the game plays, the path it walks and the corner it heads for. The Navigation window's Show Agents draws every agent, not only those picked.
In the Scripting API
- NavMeshAgent3D: an agent, what it is sent to and what it did, with NavMeshAvoidance3D.
- Navigation3D: paths, closest points and straight walks on the navmeshes.
- NavPath3D: a path's corners.
- NavMeshAgent2D, NavMeshAvoidance2D, Navigation2D and NavPath2D: the same in 2D.
- EntityRef: the entity an agent follows.
