A* Pathfinding Project  4.1.9
The A* Pathfinding Project for Unity 3D
Agent Class Reference

Internal agent for the RVO system. More...

Detailed Description

Internal agent for the RVO system.

Usually you will interface with the IAgent interface instead.

See also
IAgent

Classes

struct  VO
 Velocity Obstacle. More...
 
class  VOBuffer
 Very simple list. More...
 

Public Member Functions

 Agent (Vector2 pos, float elevationCoordinate)
 
void BufferSwitch ()
 Reads public properties and stores them in internal fields. More...
 
void CalculateNeighbours ()
 Populate the neighbours and neighbourDists lists with the closest agents to this agent. More...
 
void ForceSetVelocity (Vector2 velocity)
 Set the current velocity of the agent. More...
 
void PostCalculation ()
 
void PreCalculation ()
 
void SetCollisionNormal (Vector2 normal)
 Set the normal of a wall (or something else) the agent is currently colliding with. More...
 
void SetTarget (Vector2 targetPoint, float desiredSpeed, float maxSpeed)
 Point towards which the agent should move. More...
 

Package Functions

void CalculateVelocity (Pathfinding.RVO.Simulator.WorkerContext context)
 
float InsertAgentNeighbour (Agent agent, float rangeSq)
 Used by the Quadtree. More...
 

Package Attributes

bool locked = false
 
Agent next
 Used internally for a linked list. More...
 
Vector2 position
 
float radius
 
Simulator simulator
 Simulator which handles this agent. More...
 

Properties

float AgentTimeHorizon [get, set]
 Max number of estimated seconds to look into the future for collisions with agents. More...
 
float CalculatedSpeed [get, private set]
 Optimal speed of the agent to avoid collisions. More...
 
Vector2 CalculatedTargetPoint [get, private set]
 Optimal point to move towards to avoid collisions. More...
 
RVOLayer CollidesWith [get, set]
 Layer mask specifying which layers this agent will avoid. More...
 
bool DebugDraw [get, set]
 Draw debug information. More...
 
float ElevationCoordinate [get, set]
 Coordinate which separates characters in the height direction. More...
 
float Height [get, set]
 Height of the agent in world units. More...
 
RVOLayer Layer [get, set]
 Specifies the avoidance layer for this agent. More...
 
bool Locked [get, set]
 Locked agents will be assumed not to move. More...
 
int MaxNeighbours [get, set]
 Max number of agents to take into account. More...
 
int NeighbourCount [get, private set]
 Number of neighbours that the agent took into account during the last simulation step. More...
 
List< ObstacleVertexNeighbourObstacles [get]
 
float ObstacleTimeHorizon [get, set]
 Max number of estimated seconds to look into the future for collisions with obstacles. More...
 
Vector2 Position [get, set]
 Position of the agent. More...
 
System.Action PreCalculationCallback [set, private get]
 Callback which will be called right before avoidance calculations are started. More...
 
float Priority [get, set]
 How strongly other agents will avoid this agent. More...
 
float Radius [get, set]
 Radius of the agent in world units. More...
 
- Properties inherited from IAgent
float AgentTimeHorizon [get, set]
 Max number of estimated seconds to look into the future for collisions with agents. More...
 
float CalculatedSpeed [get]
 Optimal speed of the agent to avoid collisions. More...
 
Vector2 CalculatedTargetPoint [get]
 Optimal point to move towards to avoid collisions. More...
 
RVOLayer CollidesWith [get, set]
 Layer mask specifying which layers this agent will avoid. More...
 
bool DebugDraw [get, set]
 Draw debug information. More...
 
float ElevationCoordinate [get, set]
 Coordinate which separates characters in the height direction. More...
 
float Height [get, set]
 Height of the agent in world units. More...
 
RVOLayer Layer [get, set]
 Specifies the avoidance layer for this agent. More...
 
bool Locked [get, set]
 Locked agents will be assumed not to move. More...
 
int MaxNeighbours [get, set]
 Max number of agents to take into account. More...
 
int NeighbourCount [get]
 Number of neighbours that the agent took into account during the last simulation step. More...
 
List< ObstacleVertexNeighbourObstacles [get]
 List of obstacle segments which were close to the agent during the last simulation step. More...
 
float ObstacleTimeHorizon [get, set]
 Max number of estimated seconds to look into the future for collisions with obstacles. More...
 
Vector2 Position [get, set]
 Position of the agent. More...
 
System.Action PreCalculationCallback [set]
 Callback which will be called right before avoidance calculations are started. More...
 
float Priority [get, set]
 How strongly other agents will avoid this agent. More...
 
float Radius [get, set]
 Radius of the agent in world units. More...
 

Private Member Functions

Vector2 EvaluateGradient (VOBuffer vos, Vector2 p, out float value)
 Evaluate gradient and value of the cost function at velocity p. More...
 
void GenerateNeighbourAgentVOs (VOBuffer vos)
 
void GenerateObstacleVOs (VOBuffer vos)
 
Vector2 GradientDescent (VOBuffer vos, Vector2 sampleAround1, Vector2 sampleAround2)
 
Vector2 To2D (Vector3 p, out float elevation)
 Converts a 3D vector to a 2D vector in the movement plane. More...
 
Vector2 Trace (VOBuffer vos, Vector2 p, out float score)
 Traces the vector field constructed out of the velocity obstacles. More...
 

Static Private Member Functions

static bool BiasDesiredVelocity (VOBuffer vos, ref Vector2 desiredVelocity, ref Vector2 targetPointInVelocitySpace, float maxBiasRadians)
 Bias towards the right side of agents. More...
 
static void DrawVO (Vector2 circleCenter, float radius, Vector2 origin)
 
static Vector3 FromXZ (Vector2 p)
 (x, 0, y) More...
 
static Color Rainbow (float v)
 
static float Sqr (float x)
 Square a number. More...
 
static Vector2 ToXZ (Vector3 p)
 (x, z) More...
 

Private Attributes

float agentTimeHorizon
 
float calculatedSpeed
 
Vector2 calculatedTargetPoint
 
RVOLayer collidesWith
 
Vector2 collisionNormal
 
Vector2 currentVelocity
 
bool debugDraw
 
float desiredSpeed
 
Vector2 desiredTargetPointInVelocitySpace
 Desired target point - position. More...
 
Vector2 desiredVelocity
 
const float DesiredVelocityWeight = 0.1f
 
float elevationCoordinate
 
float height
 
RVOLayer layer
 
bool manuallyControlled
 
int maxNeighbours
 
float maxSpeed
 
List< float > neighbourDists = new List<float>()
 
List< Agentneighbours = new List<Agent>()
 
float nextDesiredSpeed
 
float nextMaxSpeed
 
Vector2 nextTargetPoint
 
List< ObstacleVertexobstacles = new List<ObstacleVertex>()
 
List< ObstacleVertexobstaclesBuffered = new List<ObstacleVertex>()
 
float obstacleTimeHorizon
 
const float WallWeight = 5
 Extra weight that walls will have. More...
 

Constructor & Destructor Documentation

◆ Agent()

Agent ( Vector2  pos,
float  elevationCoordinate 
)

Member Function Documentation

◆ BiasDesiredVelocity()

static bool BiasDesiredVelocity ( VOBuffer  vos,
ref Vector2  desiredVelocity,
ref Vector2  targetPointInVelocitySpace,
float  maxBiasRadians 
)
staticprivate

Bias towards the right side of agents.

Rotate desiredVelocity at most [value] number of radians. 1 radian ≈ 57° This breaks up symmetries.

The desired velocity will only be rotated if it is inside a velocity obstacle (VO). If it is inside one, it will not be rotated further than to the edge of it

The targetPointInVelocitySpace will be rotated by the same amount as the desired velocity

Returns
True if the desired velocity was inside any VO

◆ BufferSwitch()

void BufferSwitch ( )

Reads public properties and stores them in internal fields.

This is required because multithreading is used and if another script updated the fields at the same time as this class used them in another thread weird things could happen.

Will also set CalculatedTargetPoint and CalculatedSpeed to the result which was last calculated.

◆ CalculateNeighbours()

void CalculateNeighbours ( )

Populate the neighbours and neighbourDists lists with the closest agents to this agent.

◆ CalculateVelocity()

void CalculateVelocity ( Pathfinding.RVO.Simulator.WorkerContext  context)
package

◆ DrawVO()

static void DrawVO ( Vector2  circleCenter,
float  radius,
Vector2  origin 
)
staticprivate

◆ EvaluateGradient()

Vector2 EvaluateGradient ( VOBuffer  vos,
Vector2  p,
out float  value 
)
private

Evaluate gradient and value of the cost function at velocity p.

◆ ForceSetVelocity()

void ForceSetVelocity ( Vector2  velocity)

Set the current velocity of the agent.

This will override the local avoidance input completely. It is useful if you have a player controlled character and want other agents to avoid it.

Calling this method will mark the agent as being externally controlled for 1 simulation step. Local avoidance calculations will be skipped for the next simulation step but will be resumed after that unless this method is called again.

Implements IAgent.

◆ FromXZ()

static Vector3 FromXZ ( Vector2  p)
staticprivate

(x, 0, y)

◆ GenerateNeighbourAgentVOs()

void GenerateNeighbourAgentVOs ( VOBuffer  vos)
private

◆ GenerateObstacleVOs()

void GenerateObstacleVOs ( VOBuffer  vos)
private

◆ GradientDescent()

Vector2 GradientDescent ( VOBuffer  vos,
Vector2  sampleAround1,
Vector2  sampleAround2 
)
private

◆ InsertAgentNeighbour()

float InsertAgentNeighbour ( Agent  agent,
float  rangeSq 
)
package

Used by the Quadtree.

See also
CalculateNeighbours

◆ PostCalculation()

void PostCalculation ( )

◆ PreCalculation()

void PreCalculation ( )

◆ Rainbow()

static Color Rainbow ( float  v)
staticprivate

◆ SetCollisionNormal()

void SetCollisionNormal ( Vector2  normal)

Set the normal of a wall (or something else) the agent is currently colliding with.

This is used to make the RVO system aware of things like physics or an agent being clamped to the navmesh. The velocity of this agent that other agents observe will be modified so that there is no component into the wall. The agent will however not start to avoid the wall, for that you will need to add RVO obstacles.

This value will be cleared after the next simulation step, normally it should be set every frame when the collision is still happening.

Implements IAgent.

◆ SetTarget()

void SetTarget ( Vector2  targetPoint,
float  desiredSpeed,
float  maxSpeed 
)

Point towards which the agent should move.

Usually you set this once per frame. The agent will try move as close to the target point as possible. Will take effect at the next simulation step.

Note
The system assumes that the agent will stop when it reaches the target point so if you just want to move the agent in a particular direction, make sure that you set the target point a good distance in front of the character as otherwise the system may not avoid colisions that well. What would happen is that the system (in simplified terms) would think that the agents would stop before the collision and thus it wouldn't slow down or change course. See the image below. In the image the desiredSpeed is the length of the blue arrow and the target point is the point where the black arrows point to. In the upper case the agent does not avoid the red agent (you can assume that the red agent has a very small velocity for simplicity) while in the lower case it does.
If you are following a path a good way to pick the target point is to set it to
targetPoint = directionToNextWaypoint.normalized * remainingPathDistance
Where remainingPathDistance is the distance until the character would reach the end of the path. This works well because at the end of the path the direction to the next waypoint will just be the direction to the last point on the path and remainingPathDistance will be the distance to the last point in the path, so targetPoint will be set to simply the last point in the path. However when remainingPathDistance is large the target point will be so far away that the agent will essentially be told to move in a particular direction, which is precisely what we want.
Parameters
targetPointTarget point in world space (XZ plane or XY plane depending on if the simulation is configured for 2D or 3D). Note that this is a Vector2, not a Vector3 since the system simulates everything internally in 2D. So if your agents move in the XZ plane you will have to supply it as a Vector2 with (x,z) coordinates.
desiredSpeedDesired speed of the agent. In world units per second. The agent will try to move with this speed if possible.
maxSpeedMax speed of the agent. In world units per second. If necessary (for example if another agent is on a collision trajectory towards this agent) the agent can move at this speed. Should be at least as high as desiredSpeed, but it is recommended to use a slightly higher value than desiredSpeed (for example desiredSpeed*1.2).

Implements IAgent.

◆ Sqr()

static float Sqr ( float  x)
staticprivate

Square a number.

◆ To2D()

Vector2 To2D ( Vector3  p,
out float  elevation 
)
private

Converts a 3D vector to a 2D vector in the movement plane.

If movementPlane is XZ it will be projected onto the XZ plane and the elevation coordinate will be the Y coordinate otherwise it will be projected onto the XY plane and elevation will be the Z coordinate.

◆ ToXZ()

static Vector2 ToXZ ( Vector3  p)
staticprivate

(x, z)

◆ Trace()

Vector2 Trace ( VOBuffer  vos,
Vector2  p,
out float  score 
)
private

Traces the vector field constructed out of the velocity obstacles.

Returns the position which gives the minimum score (approximately).

See also
https://en.wikipedia.org/wiki/Gradient_descent

Member Data Documentation

◆ agentTimeHorizon

float agentTimeHorizon
private

◆ calculatedSpeed

float calculatedSpeed
private

◆ calculatedTargetPoint

Vector2 calculatedTargetPoint
private

◆ collidesWith

RVOLayer collidesWith
private

◆ collisionNormal

Vector2 collisionNormal
private

◆ currentVelocity

Vector2 currentVelocity
private

◆ debugDraw

bool debugDraw
private

◆ desiredSpeed

float desiredSpeed
private

◆ desiredTargetPointInVelocitySpace

Vector2 desiredTargetPointInVelocitySpace
private

Desired target point - position.

◆ desiredVelocity

Vector2 desiredVelocity
private

◆ DesiredVelocityWeight

const float DesiredVelocityWeight = 0.1f
private

◆ elevationCoordinate

float elevationCoordinate
private

◆ height

float height
private

◆ layer

RVOLayer layer
private

◆ locked

bool locked = false
package

◆ manuallyControlled

bool manuallyControlled
private

◆ maxNeighbours

int maxNeighbours
private

◆ maxSpeed

float maxSpeed
private

◆ neighbourDists

List<float> neighbourDists = new List<float>()
private

◆ neighbours

List<Agent> neighbours = new List<Agent>()
private

◆ next

Agent next
package

Used internally for a linked list.

◆ nextDesiredSpeed

float nextDesiredSpeed
private

◆ nextMaxSpeed

float nextMaxSpeed
private

◆ nextTargetPoint

Vector2 nextTargetPoint
private

◆ obstacles

List<ObstacleVertex> obstacles = new List<ObstacleVertex>()
private

◆ obstaclesBuffered

List<ObstacleVertex> obstaclesBuffered = new List<ObstacleVertex>()
private

◆ obstacleTimeHorizon

float obstacleTimeHorizon
private

◆ position

Vector2 position
package

◆ radius

float radius
package

◆ simulator

Simulator simulator
package

Simulator which handles this agent.

Used by this script as a reference and to prevent adding this agent to multiple simulations.

◆ WallWeight

const float WallWeight = 5
private

Extra weight that walls will have.

Property Documentation

◆ AgentTimeHorizon

float AgentTimeHorizon
getset

Max number of estimated seconds to look into the future for collisions with agents.

As it turns out, this variable is also very good for controling agent avoidance priorities. Agents with lower values will avoid other agents less and thus you can make 'high priority agents' by giving them a lower value.

◆ CalculatedSpeed

float CalculatedSpeed
getprivate set

Optimal speed of the agent to avoid collisions.

The movement script should move towards CalculatedTargetPoint with this speed.

◆ CalculatedTargetPoint

Vector2 CalculatedTargetPoint
getprivate set

Optimal point to move towards to avoid collisions.

The movement script should move towards this point with a speed of CalculatedSpeed.

Note
This is a Vector2, not a Vector3 as that is what the SetTarget method accepts.
See also
RVOController.CalculateMovementDelta.

◆ CollidesWith

RVOLayer CollidesWith
getset

Layer mask specifying which layers this agent will avoid.

You can set it as CollidesWith = RVOLayer.DefaultAgent | RVOLayer.Layer3 | RVOLayer.Layer6 ...

See also
http://en.wikipedia.org/wiki/Mask_(computing)

◆ DebugDraw

bool DebugDraw
getset

Draw debug information.

Note
Will always draw debug info in the XZ plane even if Pathfinding.RVO.Simulator.movementPlane is set to XY.
Ignored if multithreading on the simulator component has been enabled since Unity's Debug API can only be called from the main thread.

◆ ElevationCoordinate

float ElevationCoordinate
getset

Coordinate which separates characters in the height direction.

Since RVO can be used either in 2D or 3D, it is not as simple as just using the y coordinate of the 3D position. In 3D this will most likely be set to the y coordinate, but in 2D (top down) it should in most cases be set to 0 since all characters are always in the same plane, however it may be set to some other value, for example if the game is 2D isometric.

The position is assumed to be at the base of the character (near the feet).

◆ Height

float Height
getset

Height of the agent in world units.

Agents are modelled as circles/cylinders.

◆ Layer

RVOLayer Layer
getset

Specifies the avoidance layer for this agent.

The CollidesWith mask on other agents will determine if they will avoid this agent.

◆ Locked

bool Locked
getset

Locked agents will be assumed not to move.

◆ MaxNeighbours

int MaxNeighbours
getset

Max number of agents to take into account.

Decreasing this value can lead to better performance, increasing it can lead to better quality of the simulation.

◆ NeighbourCount

int NeighbourCount
getprivate set

Number of neighbours that the agent took into account during the last simulation step.

◆ NeighbourObstacles

List<ObstacleVertex> NeighbourObstacles
get

◆ ObstacleTimeHorizon

float ObstacleTimeHorizon
getset

Max number of estimated seconds to look into the future for collisions with obstacles.

◆ Position

Vector2 Position
getset

Position of the agent.

The agent does not move by itself, a movement script has to be responsible for reading the CalculatedTargetPoint and CalculatedSpeed properties and move towards that point with that speed. This property should ideally be set every frame.

Note that this is a Vector2, not a Vector3 since the RVO simulates everything internally in 2D. So if your agents move in the XZ plane you may have to convert it to a Vector3 like this.

Vector3 position3D = new Vector3(agent.Position.x, agent.ElevationCoordinate, agent.Position.y);

◆ PreCalculationCallback

System.Action PreCalculationCallback
setprivate get

Callback which will be called right before avoidance calculations are started.

Used to update the other properties with the most up to date values

◆ Priority

float Priority
getset

How strongly other agents will avoid this agent.

Usually a value between 0 and 1. Agents with similar priorities will avoid each other with an equal strength. If an agent sees another agent with a higher priority than itself it will avoid that agent more strongly. In the extreme case (e.g this agent has a priority of 0 and the other agent has a priority of 1) it will treat the other agent as being a moving obstacle. Similarly if an agent sees another agent with a lower priority than itself it will avoid that agent less.

In general the avoidance strength for this agent is:

if this.priority > 0 or other.priority > 0:
avoidanceStrength = other.priority / (this.priority + other.priority);
else:
avoidanceStrength = 0.5

◆ Radius

float Radius
getset

Radius of the agent in world units.

Agents are modelled as circles/cylinders.


The documentation for this class was generated from the following file: