Inherits MonoBehaviour.

Classes
struct	PathRequest

Public Types
enum	CollisionQuality { CollisionQuality.VeryLow, CollisionQuality.Low, CollisionQuality.Medium, CollisionQuality.High, CollisionQuality.VeryHigh }

enum	State { State.Inactive, State.Idle, State.Active }

Public Member Functions
delegate void	AgentEventDelegate (Agent agent)

void	Deactivate ()

void	Draw (Color color, Color pathColor, float y=0.1f, bool drawArrow=true, bool drawPath=true)

bool	IsFriendly (Agent agent)

void	SetDesiredVelocity (Vector3 velocity, bool avoidCollisions=true)

int	SetDestination (Vector3 point, float stopDistance=0, bool stopIfGoalOccupied=true)

int	SetDestination (Agent target, float stopDistance=0)

int	SetDestinationImmediate (Vector3 point, float stopDistance=0, bool stopIfGoalOccupied=true)

int	SetDestinationImmediate (Agent target, float stopDistance=0)

bool	SetPosition (Vector3 position)

void	SetVelocity (Vector3 velocity, Vector3 lookDirection)

void	Stop ()

void	StopDesiredVelocity ()

void	StopVelocity ()

override string	ToString ()

Public Attributes
bool	autoRepath

bool	avoidCollisions

bool	collideWithAgents

int	collisionAvoidancePriority

CollisionQuality	collisionQuality

float	collisionRadius

float	dynamicRepathInterval

float	movementSpeed

int	pathfindingQueuePriority

float	repathInterval

float	rotationSpeed

Properties
State	AgentState `[get]`

float	CurrentSpeed `[get]`

bool	HasExternalDesiredVelocity `[get]`

bool	HasExternalVelocity `[get]`

bool	HasInput `[get]`

bool	HoldOrientation `[get, set]`

bool	HoldPosition `[get, set]`

int	Id `[get]`

bool	IsActive `[get, set]`

bool	IsAvoidingCollisions `[get]`

bool	IsIdle `[get]`

Path	Path `[get]`

Team	Team `[get, set]`

Vector3	WorldPosition `[get]`

Vector2	WorldVelocity `[get]`

NavigationZone	Zone `[get]`

Vector2	ZonePosition `[get]`

Vector2	ZoneVelocity `[get]`

Events
AgentEventDelegate	OnPathFailure

AgentEventDelegate	OnReachDestination

Detailed Description

The agent class is a MonobeHaviour which can be attached to GameObjects that represent game Characters.

Agents are entities that can navigate on the NavMesh avoiding collisions with obstacles and other agents.

NavAI automatically handles and updates agents positions. It is only needed to set the agent's desired destination or desired velocity and the algorithm will take care of carefully moving the agent around the environment while avoiding collision with obstacles and other agents.

The most common usage of the Agent class is to call SetDestination to a target destination or SetDesiredVelocity with the user input as a velocity.

Advanced functions are available and supported, but they should only be used in special situations.

It is important to configure the parameters of agents such as movementSpeed, rotationSpeed and collisionRadius. All accessible agent parameters can be changed at runtime, and their change will affect the agent navigation automatically.

Usage of non-public fields and methods are not supported.

Member Enumeration Documentation

◆ CollisionQuality

enum NavAI.Agent.CollisionQuality

strong

Enum used to quantify the collision avoidance quality.

Enumerator
VeryLow	Lowest collision avoidance quality. Collision Avoidance Velocity is calculated once every 20 steps.
Low	Low collision avoidance quality. Collision Avoidance Velocity is calculated once every 15 steps.
Medium	Medium collision avoidance quality. Collision Avoidance Velocity is calculated once every 10 steps.
High	High collision avoidance quality. Collision Avoidance Velocity is calculated once every 5 steps.
VeryHigh	(Recommended) Highest collision avoidance quality. Collision Avoidance Velocity is calculated once every step.

◆ State

enum NavAI.Agent.State

strong

Enum used to define the agent's state.

Enumerator
Inactive	Inactive agents do not calculate or use their velocity during their update.
Idle	Idle agents have no destination, but may still move to get away from collisions.
Active	Active agents have a destination and are trying to reach it.

Member Function Documentation

◆ AgentEventDelegate()

delegate void NavAI.Agent.AgentEventDelegate ( Agent agent )

Delegate used for agent events.

Parameters

agent The agent passed on the events.

◆ Deactivate()

void NavAI.Agent.Deactivate ( )

Orders the agent to stop and become Inactive.

This will deactivate the agent, meaning it whill not move untill it receives another command such as SetDestination or SetVelocity.

◆ Draw()

void NavAI.Agent.Draw	(	Color	color,
		Color	pathColor,
		float	y = `0.1f`,
		bool	drawArrow = `true`,
		bool	drawPath = `true`
	)

Draws the agent.

Parameters

color	Material color for the agent.
pathColor	Material color for the agent's path
y	Offset height coordinate for the drawing.
drawArrow	Toggles drawing the arrow which shows the agent orientation.
drawPath	Toggles drawing the agent's path.

If the drawing is partially or completely invisible, it is possible that it is hidden inderneaath some other object. To fix that, it is possible to set a custom y offset value, which will offset the drawing on the y axis.

This method is not thread safe and should only be called on the main thread.

◆ IsFriendly()

bool NavAI.Agent.IsFriendly ( Agent agent )

True if this agents team is friendly to the other agents team.

Parameters

agent The agent to compare relationship with

Returns: True if the input agent has a friendly relationship with this agent.

Agents using the default team definition are all considered friendly with one another. Agents can only be considered unfriendly if their team is set to a custom team. To define friendly / unfriendly relationships between teams, use the Agent.Team.SetFriendly or Agent.Team.SetUnfriendly methods. By default, teams have feiendly relationship with the default team (Team_0), and unfriendly relationships with any other teams.

◆ SetDesiredVelocity()

void NavAI.Agent.SetDesiredVelocity	(	Vector3	velocity,
		bool	avoidCollisions = `true`
	)

Sets the agent desired velocity for this frame.

Note that the final velocity will be affected by collision avoidance.

This effect will only end when Stop() or Hold() methods are called, or when the desired velocity is overriden by calling SetDesiredVelocity() again.

Parameters

velocity	The desired world velocity in meters per second.
avoidCollisions	Toggles collision avoidance while using the desired velocity to navigate.

If avoidCollisions is set to true (default), then the agent will avoid collisions while trying to move with the desired velocity. This can lead the agent to sometimes move on different directions than the desired velocity. If this behaviour is not wanted, then avoidCollisions can be set to false.

Even if avoidCollisions is set to false, the agent will physically collide with other agents and obstacles. To disable collisions with other agents, set the agent's collideWithOther agents variable to false.

SetDesiredVelocity differs from SetVelocity because the desired velocity considers collisions.

◆ SetDestination() [1/2]

int NavAI.Agent.SetDestination	(	Vector3	point,
		float	stopDistance = `0`,
		bool	stopIfGoalOccupied = `true`
	)

Sets the agent destination to the world point.

Parameters

point	World destination point.
stopDistance	Distance to stop from the destination point in meters.
stopIfGoalOccupied	Enables the agent to stop near the point if the goal point is occupied by another agent.

Returns: Unique ID of the path being calculated.

When the destination is set, the agent will automatically move every frame following the path towards the destination until it reaches stopDistance of the destination point.

SetDestination automatically requests a new path from the pathfinder, and the agent's path to the destination will be calculated as soon as possible. The agent will automatically receive and use the path when it is done calculating.

If the zone uses one or more threads for pathfinding, the path will not be immediately calculated. Instead, it will be put on a queue for background calculation on a separate thread. In this case, the path will not be immediately available, but should be available on the next few frames (usually on the next frame, unless the path is very complicated ot be calculated fast). To check when the path is ready, constantly check if the agent path is ready and if it's id matches the return value of this function.

◆ SetDestination() [2/2]

int NavAI.Agent.SetDestination	(	Agent	target,
		float	stopDistance = `0`
	)

Sets the agent destination to follow the target agent.

Parameters

target	Target Agent to follow
stopDistance	Distance to stop from the target agent in meters.

Returns: Unique ID of the path being calculated.

When the destination is set, the agent will automatically move every frame following the path towards the destination until it reaches stopDistance of the destination point.

SetDestination automatically requests a new path from the pathfinder, and the agent's path to the destination will be calculated as soon as possible. The agent will automatically receive and use the path when it is done calculating.

If the zone uses one or more threads for pathfinding, the path will not be immediately calculated. Instead, it will be put on a queue for background calculation on a separate thread. In this case, the path will not be immediately available, but should be available on the next few frames (usually on the next frame, unless the path is very complicated ot be calculated fast). To check when the path is ready, constantly check if the agent path is ready and if it's id matches the return value of this function.

◆ SetDestinationImmediate() [1/2]

int NavAI.Agent.SetDestinationImmediate	(	Vector3	point,
		float	stopDistance = `0`,
		bool	stopIfGoalOccupied = `true`
	)

Immediately sets the agent destination to the world point.

Parameters

point	World destination point.
stopDistance	Distance to stop from the destination point in meters.
stopIfGoalOccupied	Enables the agent to stop near the point if the goal point is occupied by another agent.

Returns: Unique ID of the path being calculated.

When the destination is set, the agent will automatically move every frame following the path towards the destination until it reaches stopDistance of the destination point.

SetDestinationImmediate immediately calculates the path from the agent's position to the destination on the main thread, and the path will be available right after this method call. This process runs on the main thread and may cause performance problems. Use of this method is not recommended.

◆ SetDestinationImmediate() [2/2]

int NavAI.Agent.SetDestinationImmediate	(	Agent	target,
		float	stopDistance = `0`
	)

Sets the agent destination to follow the target agent.

Parameters

target	Target Agent to follow
stopDistance	Distance to stop from the target agent in meters.

Returns: Unique ID of the path being calculated.

When the destination is set, the agent will automatically move every frame following the path towards the destination until it reaches stopDistance of the destination point.

SetDestinationImmediate immediately calculates the path from the agent's position to the destination on the main thread, and the path will be available right after this method call. This process runs on the main thread and may cause performance problems. Use of this method is not recommended.

◆ SetPosition()

bool NavAI.Agent.SetPosition ( Vector3 position )

Sets the agent's position.

Parameters

position The new world position for the agent.

Returns: True if the agent was sucessfully positioned in a zone.

This is equivalent to Unity's NavMeshAgent.Warp method. The agent will be instantly warped to the nearest collision-free mesh point of the input position. If a zone containg the input position is not found, then the agent will be zoneless and will be deactivated. The agent may switch zone during this process.

The agent's new position may not be exactly the input position. Not only can the height change to accomodate the agent on the mehs surface, but the x and z coordinates can change as well to place the agent out of collisions.

This method is a lot slower than updating the agent's position using veleocities, and setting using this method every frame is innapropriate. Use SetVelocity instead for continuous movement.

◆ SetVelocity()

void NavAI.Agent.SetVelocity	(	Vector3	velocity,
		Vector3	lookDirection
	)

Sets the agent world velocity in meters per second.

Parameters

velocity	The world velocity in meters per second.
lookDirection	The world normalized look direction.

The final velocity will not be affected by the agents desired velocity nor collision avoidance, and the agent will not check any collisions while moving with this velocity.

This effect will only stop when StopVelocity() is called or when the velocity is overriden with SetVelocity().

◆ Stop()

void NavAI.Agent.Stop ( )

Orders the agent to stop and become Idle.

An Idle agent does not have a desired to move, but it may move to avoid collisions with other agents as needed. This method will not stop the agent from being pushed if it has an external velocity set with the SetVelocity function. To stop the agent velocity, use StopVelocity instead.

This method will erase the agent's path.

◆ StopDesiredVelocity()

void NavAI.Agent.StopDesiredVelocity ( )

Stops all external input desired velocities on the agent.

This method is used after SetDesiredVelocity is set to nullify the desired velocity and allow the agent to move naturally.

◆ StopVelocity()

void NavAI.Agent.StopVelocity ( )

Stops all external input velocities on the agent.

This is used after SetVelocity or SetDesiredVelocity is set to nullify the velocity and allow the agent to move naturally.

This method includes a SetPosition call and should not be called too frequently for performance reasons.

◆ ToString()

override string NavAI.Agent.ToString ( )

Gets a nicely formated string with the agent's name, ID and position.

Returns: A string with the agent information.

Member Data Documentation

◆ autoRepath

bool NavAI.Agent.autoRepath

Toggles automatic recalculating the path periodically.

If set to false, the agent's path can become outdated for the agent's current position, causing the agent to be unable to reach it's destination. It is highly recommended to set this variable to true.

◆ avoidCollisions

bool NavAI.Agent.avoidCollisions

Toggles collision avoidance.

An agent with collision avoidance disabled will still physically collide with other agents and obstacles, but it will not change its movement direction to avoid collisions ahead of time.

This variable does not affect pathfinding in any way.

◆ collideWithAgents

bool NavAI.Agent.collideWithAgents

Toggles collisions with other agents.

When turned off, the agent will not physically collide and will not avoid collisions with any other agent.

◆ collisionAvoidancePriority

int NavAI.Agent.collisionAvoidancePriority

Collision avoidance priority used when avoiding collisions with other agents. Higher values mean higher movement priority.

Collision avoidance priority requires the settings file to have Enable Priority set to true.

Collision avoidance rules only apply to agents with friendly team relaionship.

◆ collisionQuality

CollisionQuality NavAI.Agent.collisionQuality

Collision Avoidance Quality. Lower quality will recalculate collision avoiding velocities less often and will make the agent more likely to collide with other agents.

Lowering the collision avoidance quality can sometimes fix lag issues. Unless fixing lag issues, it is recommended to se the collision avoidance quality to maximum at all times.

◆ collisionRadius

float NavAI.Agent.collisionRadius

Agent's collision radius in meters.

The agent's collision radius is used to calculate collisions with other agents, collisions with obstacles, to position to agent on the navmesh and also to find paths for the agent.

This variable should never exceed the Agent Max. Radius setting of the NavigationZone or NavigationWorld the agent is in.

◆ dynamicRepathInterval

float NavAI.Agent.dynamicRepathInterval

Time interval in seconds for the agent to automatically recalculat it's path when the path destination is another agent.

This variable only affects paths whose destination is another agent. If the agent's path destination is a fixed world point, then repathInterval will be used instead.

Lowering this value can fix cases where agents get stuck behind an obstacle for too long. If set to zero, the the agent will automatically request a path update whenever it's previous path request was completed (not recommended).

◆ movementSpeed

float NavAI.Agent.movementSpeed

Agent's movement speed in meters per second.

This value is the agent's maximum allowed movement speed. The agent will try to move at it's maximum speed while it is moving, but during collision avoidance it's current speed may be lower than this value, but never higher.

This variable should never exceed the Agent Max. Movemnent Speed setting of the NavigationZone or the NavigationWorld the agent is in.

◆ pathfindingQueuePriority

int NavAI.Agent.pathfindingQueuePriority

Pathfinding Queue priority. Lower values means the agent will get the path sooner.

This variable can be used in case where there are many agents active on the scene, but the agent being controlled by the player should have a faster response. In this case, the player controlled agent should have this variable set to a lower value than the other agents.

It is not recommended to set this value below 1 or above 99.

◆ repathInterval

float NavAI.Agent.repathInterval

Time interval in seconds for the agent to automatically recalculat it's path when the path destination is a fixed world point.

This variable only affects paths to fixed world points. If the agent's path is following another agent, then dynamicRepathInterval will be used instead.

Lowering this value can fix cases where agents get stuck behind an obstacle for too long. If set to zero, the the agent will automatically request a path update whenever it's previous path request was completed (not recommended).

◆ rotationSpeed

float NavAI.Agent.rotationSpeed

Agent's rotation speed in radians per second.

The agent will always rotate at maximum rotation speed, unless the Max. Angular Acceleration setting limits rotation speed variations.

It is important to note that the agents rotations can also be affected by the Rotation Stability setting.

Property Documentation

◆ AgentState

State NavAI.Agent.AgentState

get

Gets the agent state.

◆ CurrentSpeed

float NavAI.Agent.CurrentSpeed

get

Gets the agent's current speed in meters per second.

The agent's current speed can be lower than the agent's movement speed to avoid collisions.

This is the same value as LocalVelocity.Magnitude.

◆ HasExternalDesiredVelocity

bool NavAI.Agent.HasExternalDesiredVelocity

get

Gets true if the agent is being controlled externally using SetDesiredVelocity.

◆ HasExternalVelocity

bool NavAI.Agent.HasExternalVelocity

get

Gets true if the agent is being controlled externally using SetVelocity.

◆ HasInput

bool NavAI.Agent.HasInput

get

Gets true if the agent is being controlled externally with SetVelocity or SetDesiredVelocity.

◆ HoldOrientation

bool NavAI.Agent.HoldOrientation

getset

Toggles agent rotation. If HoldOrientation is set to true, then the agent will not rotate.

Even when not moving, the agent may still be able to rotate. To completely disable agent rotation, set this propriety to true.

◆ HoldPosition

bool NavAI.Agent.HoldPosition

getset

Toggles agent agent movement. If HoldPosition is set to true, then the agent will not move, unless forced to.

Set this variable to true if the agent should not be pushed away from its position due to collisions with other agents.

An agent that is holding position will only move to solve collisions with other agents that are also unable to move. If the agent is holding position, then other moving agents will never be able to push it due to collisions. This may not be true for agents that are not holding positions, because collision separation will be reciprocal for them, meaning they will move to solve collisions whenever needed.

◆ Id

int NavAI.Agent.Id

get

Gets the agent unique id.

This variable is set during Awake and does not ever change at runtime after that, but it can change from session to session.

◆ IsActive

bool NavAI.Agent.IsActive

getset

Gets true if the agent is active on a NavigationZone.

◆ IsAvoidingCollisions

bool NavAI.Agent.IsAvoidingCollisions

get

Gets true if collision avoidance is enabled for this agent.

This includes additional conditions other than the agent's avoidCollisions variable.

◆ IsIdle

bool NavAI.Agent.IsIdle

get

Gets true if the agent is idle.

◆ Path

Path NavAI.Agent.Path

get

Gets the agent's NavAI.Path.

The path contains a sequence of points used by the agent to navigate around obstacles in order to reach it's destination. All path pointst are in local zone space.

Before using the raw data of the path, check the NavAI.Path reference to understand the path points structure and how to use them properly.

◆ Team

Team NavAI.Agent.Team

getset

Gets or sets the agent's team.

The agent's team is used to define friendly and unfriendly relationships with other agents. Agents that are friendly to one another may be able to cooperate with the overall movement of the other. If two agents do not have a friendly relationship, then some movement priority rules may not apply to them.

◆ WorldPosition

Vector3 NavAI.Agent.WorldPosition

get

Gets the agent's world position (x, y, z).

The agent world position may differ from it's zone position if the zone transform is not the identity transform.

This is the same as agent.Zone.LocalToWorld(agent.ZonePosition).

◆ WorldVelocity

Vector2 NavAI.Agent.WorldVelocity

get

Gets the agent's current world velocity (x, y, z) in meters per second.

The agent world velocity may differ from it's zone velocity if the zone transform is not the idendity transform.

This is the same as agent.Zone.LocalToWorldVector (agent.ZoneVelocity).

◆ Zone

NavigationZone NavAI.Agent.Zone

get

Gets the agent zone.

The agent's zone may be null if it nos not active. Otherwise it will always have a reference.

◆ ZonePosition

Vector2 NavAI.Agent.ZonePosition

get

Gets the agent's zone position (x, z).

The agent world position may differ from it's zone position if the zone transform is not the identity transform.

This is the same as agent.Zone.WorldToLocal(agent.WorldPosition).

◆ ZoneVelocity

Vector2 NavAI.Agent.ZoneVelocity

get

Gets the agent's current zone velocity (x, z) in meters per second.

The agent world velocity may differ from it's zone velocity if the zone transform is not the identity transform.

This is the same as agent.Zone.WorldToLocalVector(agent.WorldVelocity).

Event Documentation

◆ OnPathFailure

AgentEventDelegate NavAI.Agent.OnPathFailure

Event fired when the agent is unable to calculate a path to it's destination.

◆ OnReachDestination

AgentEventDelegate NavAI.Agent.OnReachDestination

Event fired when the agent reaches it's destination.

This event is fired every step the agent is within target distance of it's destination. To stop this event from firing, the Agent.Stop can be used to stop the agent once it reaches it's destination.

Classes

Public Types

Public Member Functions

Public Attributes

Properties

Events

Detailed Description

Member Enumeration Documentation

◆ CollisionQuality

◆ State

Member Function Documentation

◆ AgentEventDelegate()

◆ Deactivate()

◆ Draw()

◆ IsFriendly()

◆ SetDesiredVelocity()

◆ SetDestination() [1/2]

◆ SetDestination() [2/2]

◆ SetDestinationImmediate() [1/2]

◆ SetDestinationImmediate() [2/2]

◆ SetPosition()

◆ SetVelocity()

◆ Stop()

◆ StopDesiredVelocity()

◆ StopVelocity()

◆ ToString()

Member Data Documentation

◆ autoRepath

◆ avoidCollisions

◆ collideWithAgents

◆ collisionAvoidancePriority

◆ collisionQuality

◆ collisionRadius

◆ dynamicRepathInterval

◆ movementSpeed

◆ pathfindingQueuePriority

◆ repathInterval

◆ rotationSpeed

Property Documentation

◆ AgentState

◆ CurrentSpeed

◆ HasExternalDesiredVelocity

◆ HasExternalVelocity

◆ HasInput

◆ HoldOrientation

◆ HoldPosition

◆ Id

◆ IsActive

◆ IsAvoidingCollisions

◆ IsIdle

◆ Path

◆ Team

◆ WorldPosition

◆ WorldVelocity

◆ Zone

◆ ZonePosition

◆ ZoneVelocity

Event Documentation

◆ OnPathFailure

◆ OnReachDestination