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.

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.

FieldWhat it does
Agent TypeWhich agent type it is, by name: its width and height, and the navmesh it walks. Humanoid at first.
SpeedHow fast it walks, in meters a second. 3.5 at first.
Angular SpeedHow fast it turns to face where it walks, in degrees a second. 120 at first.
AccelerationHow fast it gets up to speed and slows down, in meters a second each second. 8 at first.
Stopping DistanceHow near where it is sent it stops, in meters. 0 at first.
Auto BrakingWhether it slows as it comes to where it is sent, rather than arriving at full speed. On at first.
Base OffsetHow far above the navmesh its entity is put, in meters: from its feet to the entity's middle.
AvoidanceHow well it steers around other agents and moving obstacles: None, Low, Medium, Good or High. High at first.
PriorityHow readily it keeps clear of others, from 0 to 99. 50 at first.
Update PositionWhether it moves its entity. Off, it only steers; see Move the entity yourself.
Update RotationWhether it turns its entity to face where it walks.
DestinationWhere it walks to, while Has Destination is on and Target is none.
Has DestinationWhether it walks to Destination.
TargetAn entity it follows wherever that goes. While one is named, Destination is not walked to.
StoppedHolds it where it stands, though it is sent somewhere.
Area MaskThe areas its path may cross, ticked by name. Everything at first.
Auto TraverseWhether 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.

FieldWhat it holds
VelocityHow it moves, in meters a second.
RemainingDistanceHow far it has left to walk along its path, in meters; 0 with nowhere to go.
ArrivedWhether it has come within Stopping Distance of where it was sent.
OnNavMeshWhether it stands on a navmesh of its type. False where it was put where none is.
OnLinkWhether it is crossing a link.
LinkProgressHow far across the link it is, from 0 at its start to 1 at its end.
LinkStart, LinkEndThe ends of the link it crosses, in the world.

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 Destination and turn HasDestination on.
  • After an entity: set Target, as agent.Target = new EntityRef(player);. The agent follows it wherever it goes, finding its path again as it moves. Set it back to EntityRef.None to stop following. A target that is gone sends the agent to its Destination instead, if it has one.
  • Nowhere: turn HasDestination off with no Target, and it stops where it is.
  • Hold it: turn Stopped on. 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
MethodWhat 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