Legacy Documentation: Version 4.5
Previous
Navigation Layers and Costs
Next
Navmesh Obstacle

NavMesh Agent

Switch to Scripting

A NavMesh Agent component can be added to a character to allow it to navigate from place to place automatically over a Navigation Mesh. The agent begins its task by using information stored in the mesh to calculate an optimal path. With the path calculated, the agent is then responsible for moving the object automatically along the path.

Properties

Property: Function:
Radius Radius around the agent within which obstacles should not pass.
Speed Maximum movement speed (in world units per second).
Acceleration Maximum acceleration (in world units per second squared).
Angular Speed Maximum speed of rotation (degrees per second).
Stopping distance Minimum distance from the target within which the agent can stop.
Auto Traverse OffMesh Link Should off-mesh links be crossed automatically without intervention from a script?
Auto Repath Should a new path be calculated if the current one becomes obstructed or invalid?
Auto Braking Should the agent automatically slow down as it approaches the target point?
Height The height clearance the agent needs to pass below an obstacle overhead.
Base offset Height difference between the anchor point of the GameObject and the centre point of the agent’s cylinder.
Obstacle Avoidance Type An approximate quality level for obstacle avoidance.
Avoidance Priority Agents of lower priority will be ignored by this agent when performing avoidance. The value should be in the range 0..99 where lower numbers indicate higher priority.
NavMesh Walkable Specifies the Navmesh layers that the agent can traverse.

Details

The agent is defined by an upright cylinder whose size is specified by the Radius and Height properties. The cylinder moves with the object but always remains upright even if the object itself rotates. Its purpose is to define the region within which obstacles should not intrude as the object moves around. The agent will aim to keep a distance of Radius or greater between its centre and surrounding obstacles and cannot pass under a ceiling lower than the Height property. When the GameObject’s anchor point does not coincide with the base of the cylinder, you can use the Base Offset property to take up the height difference.

The path calculated by the agent is a sequence of waypoints connected by straight lines that denote the shortest path. However, rather than follow this path perfectly, the agent will use more realistic motion that incorporates acceleration and gradual turning (specified by the Speed, Acceleration and Angular Speed properties).

Since the agent has gradual acceleration and a limit on its turn rate, it typically won’t be able to stop precisely on the target point. Without further intervention, it will overshoot the target and then turn to try to reach it again from the other side. This results in endless “orbiting” around the target point and the agent will thus never truly reach its destination. This well-known problem is handled in Unity using the Stopping Distance and Auto Braking properties. When the agent gets within the Stopping Distance of the target, it is assumed to have reached its destination and can stop moving. When Auto Braking is switched on, the agent will slow down automatically as it gets close to the target, thus enabling it to turn in a tighter circle and get closer to the target point. The ideal choice of stopping distance depends on the speed, acceleration and angular speed of the agent; landing very close to the target from speed can involve gradual slowing and course adjustment from the agent, resulting in unnatural movement.

As it moves around, an agent will avoid fixed obstacles in the scene as well as other agents. The Obstacle Avoidance Type gives a hint to the navigation system about how accurate the avoidance should be. Low quality may sometimes allow obstacles to come within the agent’s cylinder but the processing overhead will be lower than with high quality. The Avoidance Priority determines how the agent will behave when it encounters another agent - the agent with the larger priority number will avoid while the other will just follow its normal path.

For further information about the use of NavMesh Agents, see the page about Enabling a Character To Navigate.

Previous
Navigation Layers and Costs
Next
Navmesh Obstacle