A* Pathfinding Project  4.3.5
The A* Pathfinding Project for Unity 3D
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | Package Attributes | Properties | Private Member Functions | Private Attributes | List of all members
RVOController Class Reference

RVO Character Controller. More...

Detailed Description

RVO Character Controller.

Similar to Unity's CharacterController. It handles movement calculations and takes other agents into account. It does not handle movement itself, but allows the calling script to get the calculated velocity and use that to move the object using a method it sees fit (for example using a CharacterController, using transform.Translate or using a rigidbody).

public void Update () {
// Just some point far away
var targetPoint = transform.position + transform.forward * 100;
// Set the desired point to move towards using a desired speed of 10 and a max speed of 12
controller.SetTarget(targetPoint, 10, 12);
// Calculate how much to move during this frame
// This information is based on movement commands from earlier frames
// as local avoidance is calculated globally at regular intervals by the RVOSimulator component
var delta = controller.CalculateMovementDelta(transform.position, Time.deltaTime);
transform.position = transform.position + delta;
}

For documentation of many of the variables of this class: refer to the Pathfinding.RVO.IAgent interface.

Note
Requires a single RVOSimulator component in the scene
See also
Pathfinding.RVO.IAgent
RVOSimulator
Local Avoidance

A* Pro Feature:
This is an A* Pathfinding Project Pro feature only. This function/class/variable might not exist in the Free version of the A* Pathfinding Project or the functionality might be limited
The Pro version can be bought here

Public Member Functions

Vector3 CalculateMovementDelta (float deltaTime)
 Direction and distance to move in a single frame to avoid obstacles. More...
 
Vector3 CalculateMovementDelta (Vector3 position, float deltaTime)
 Direction and distance to move in a single frame to avoid obstacles. More...
 
void ForceSetVelocity (Vector3 velocity)
 
void Move (Vector3 vel)
 Set the desired velocity for the agent. More...
 
void SetCollisionNormal (Vector3 normal)
 Set the normal of a wall (or something else) the agent is currently colliding with. More...
 
void SetTarget (Vector3 pos, float speed, float maxSpeed)
 Set the target point for the agent to move towards. More...
 
void Teleport (Vector3 pos)
 Teleport the agent to a new position. More...
 
Vector2 To2D (Vector3 p)
 Converts a 3D vector to a 2D vector in the movement plane. More...
 
Vector2 To2D (Vector3 p, out float elevation)
 Converts a 3D vector to a 2D vector in the movement plane. More...
 
Vector3 To3D (Vector2 p, float elevationCoordinate)
 Converts a 2D vector in the movement plane as well as an elevation to a 3D coordinate. More...
 

Public Attributes

float agentTimeHorizon = 2
 How far into the future to look for collisions with other agents (in seconds) More...
 
RVOLayer collidesWith = (RVOLayer)(-1)
 Layer mask specifying which layers this agent will avoid. More...
 
bool debug
 Enables drawing debug information in the scene view. More...
 
float flowFollowingStrength = 0.0f
 Determines how strongly this agent just follows the flow instead of making other agents avoid it. More...
 
RVOLayer layer = RVOLayer.DefaultAgent
 Specifies the avoidance layer for this agent. More...
 
bool locked
 A locked unit cannot move. More...
 
bool lockWhenNotMoving = false
 Automatically set locked to true when desired velocity is approximately zero. More...
 
int maxNeighbours = 10
 Max number of other agents to take into account. More...
 
float obstacleTimeHorizon = 2
 How far into the future to look for collisions with obstacles (in seconds) More...
 
float priority = 0.5f
 How strongly other agents will avoid this agent. More...
 
float priorityMultiplier = 1.0f
 Priority multiplier. More...
 
float wallAvoidFalloff = 1
 How much the wallAvoidForce decreases with distance. More...
 
float wallAvoidForce = 1
 An extra force to avoid walls. More...
 

Protected Member Functions

override int OnUpgradeSerializedData (int version, bool unityThread)
 Handle serialization backwards compatibility. More...
 
void UpdateAgentProperties ()
 
- Protected Member Functions inherited from VersionedMonoBehaviour
virtual void Awake ()
 
virtual void Reset ()
 Handle serialization backwards compatibility. More...
 

Protected Attributes

Transform tr
 Cached tranform component. More...
 

Package Attributes

float radiusBackingField = 0.5f
 

Properties

IAstarAI ai [get, set]
 Cached reference to a movement script (if one is used) More...
 
float center [get, set]
 Center of the agent relative to the pivot point of this game object. More...
 
bool enableRotation [get, set]
 
float height [get, set]
 Height of the agent in world units. More...
 
LayerMask mask [get, set]
 
float maxSpeed [get, set]
 
MovementPlane movementPlane [get]
 Determines if the XY (2D) or XZ (3D) plane is used for movement. More...
 
Vector3 position [get]
 Current position of the agent. More...
 
float radius [get, set]
 Radius of the agent in world units. More...
 
float rotationSpeed [get, set]
 
IAgent rvoAgent [get, private set]
 Reference to the internal agent. More...
 
ISimulator simulator [get, private set]
 Reference to the rvo simulator. More...
 
Vector3 velocity [get, set]
 Current calculated velocity of the agent. More...
 
- Properties inherited from VersionedMonoBehaviour
int Util.IEntityIndex. EntityIndex [get, set]
 Internal entity index used by #BurstBatchHelper. More...
 
- Properties inherited from IEntityIndex
int EntityIndex [get, set]
 

Private Member Functions

void OnDisable ()
 
void OnDrawGizmos ()
 
void OnEnable ()
 

Private Attributes

IAstarAI aiBackingField
 
float centerBackingField = 1
 
float heightBackingField = 2
 

Member Function Documentation

◆ CalculateMovementDelta() [1/2]

Vector3 CalculateMovementDelta ( float  deltaTime)

Direction and distance to move in a single frame to avoid obstacles.

Parameters
deltaTimeHow far to move [seconds]. Usually set to Time.deltaTime.

The position of the agent is taken from the attached movement script's position (see Pathfinding.IAstarAI.position) or if none is attached then transform.position.

◆ CalculateMovementDelta() [2/2]

Vector3 CalculateMovementDelta ( Vector3  position,
float  deltaTime 
)

Direction and distance to move in a single frame to avoid obstacles.

Parameters
positionPosition of the agent.
deltaTimeHow far to move [seconds]. Usually set to Time.deltaTime.
public void Update () {
// Just some point far away
var targetPoint = transform.position + transform.forward * 100;
// Set the desired point to move towards using a desired speed of 10 and a max speed of 12
controller.SetTarget(targetPoint, 10, 12);
// Calculate how much to move during this frame
// This information is based on movement commands from earlier frames
// as local avoidance is calculated globally at regular intervals by the RVOSimulator component
var delta = controller.CalculateMovementDelta(transform.position, Time.deltaTime);
transform.position = transform.position + delta;
}

◆ ForceSetVelocity()

void ForceSetVelocity ( Vector3  velocity)

Deprecated:
Set the velocity property instead

◆ Move()

void Move ( Vector3  vel)

Set the desired velocity for the agent.

Note that this is a velocity (units/second), not a movement delta (units/frame).

This is assumed to stay the same until something else is requested (as opposed to being reset every frame).

Note
In most cases the SetTarget method is better to use. What this will actually do is call SetTarget with (position + velocity). See the note in the documentation for IAgent.SetTarget about the potential issues that this can cause (in particular that it might be hard to get the agent to stop at a precise point).
See also
SetTarget

◆ OnDisable()

void OnDisable ( )
private

◆ OnDrawGizmos()

void OnDrawGizmos ( )
private

◆ OnEnable()

void OnEnable ( )
private

◆ OnUpgradeSerializedData()

override int OnUpgradeSerializedData ( int  version,
bool  unityThread 
)
protectedvirtual

Handle serialization backwards compatibility.

Reimplemented from VersionedMonoBehaviour.

◆ SetCollisionNormal()

void SetCollisionNormal ( Vector3  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.

◆ SetTarget()

void SetTarget ( Vector3  pos,
float  speed,
float  maxSpeed 
)

Set the target point for the agent to move towards.

Similar to the Move method but this is more flexible. It is also better to use near the end of the path as when using the Move method the agent does not know where to stop, so it may overshoot the target. When using this method the agent will not overshoot the target. The agent will assume that it will stop when it reaches the target so make sure that you don't place the point too close to the agent if you actually just want to move in a particular direction.

The target point is assumed to stay the same until something else is requested (as opposed to being reset every frame).

Parameters
posPoint in world space to move towards.
speedDesired speed in world units per second.
maxSpeedMaximum speed in world units per second. The agent will use this speed if it is necessary to avoid collisions with other agents. Should be at least as high as speed, but it is recommended to use a slightly higher value than speed (for example speed*1.2).
See also
Also take a look at the documentation for #IAgent.SetTarget which has a few more details.
Move

◆ Teleport()

void Teleport ( Vector3  pos)

Teleport the agent to a new position.

Deprecated:
Use transform.position instead, the RVOController can now handle that without any issues.

◆ To2D() [1/2]

Vector2 To2D ( Vector3  p)

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

If movementPlane is XZ it will be projected onto the XZ plane otherwise it will be projected onto the XY plane.

◆ To2D() [2/2]

Vector2 To2D ( Vector3  p,
out float  elevation 
)

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.

◆ To3D()

Vector3 To3D ( Vector2  p,
float  elevationCoordinate 
)

Converts a 2D vector in the movement plane as well as an elevation to a 3D coordinate.

See also
To2D
movementPlane

◆ UpdateAgentProperties()

void UpdateAgentProperties ( )
protected

Member Data Documentation

◆ agentTimeHorizon

float agentTimeHorizon = 2

How far into the future to look for collisions with other agents (in seconds)

◆ aiBackingField

IAstarAI aiBackingField
private

◆ centerBackingField

float centerBackingField = 1
private

◆ collidesWith

RVOLayer collidesWith = (RVOLayer)(-1)

Layer mask specifying which layers this agent will avoid.

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

This can be very useful in games which have multiple teams of some sort. For example you usually want the agents in one team to avoid each other, but you do not want them to avoid the enemies.

This field only affects which other agents that this agent will avoid, it does not affect how other agents react to this agent.

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

◆ debug

bool debug

Enables drawing debug information in the scene view.

◆ flowFollowingStrength

float flowFollowingStrength = 0.0f

Determines how strongly this agent just follows the flow instead of making other agents avoid it.

The default value is 0, if it is greater than zero (up to the maximum value of 1) other agents will not avoid this character as much. However it works in a different way to #Priority.

A group of agents with FlowFollowingStrength set to a high value that all try to reach the same point will end up just settling to stationary positions around that point, none will push the others away to any significant extent. This is tricky to achieve with priorities as priorities are all relative, so setting all agents to a low priority is the same thing as not changing priorities at all.

Should be a value in the range [0, 1].

Todo:
Add video

◆ heightBackingField

float heightBackingField = 2
private

◆ layer

RVOLayer layer = RVOLayer.DefaultAgent

Specifies the avoidance layer for this agent.

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

◆ locked

bool locked

A locked unit cannot move.

Other units will still avoid it but avoidance quality is not the best.

◆ lockWhenNotMoving

bool lockWhenNotMoving = false

Automatically set locked to true when desired velocity is approximately zero.

This prevents other units from pushing them away when they are supposed to e.g block a choke point.

When this is true every call to SetTarget or Move will set the locked field to true if the desired velocity was non-zero or false if it was zero.

◆ maxNeighbours

int maxNeighbours = 10

Max number of other agents to take into account.

A smaller value can reduce CPU load, a higher value can lead to better local avoidance quality.

◆ obstacleTimeHorizon

float obstacleTimeHorizon = 2

How far into the future to look for collisions with obstacles (in seconds)

◆ priority

float priority = 0.5f

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

◆ priorityMultiplier

float priorityMultiplier = 1.0f

Priority multiplier.

This functions identically to the priority, however it is not exposed in the Unity inspector. It is primarily used by the Pathfinding.RVO.RVODestinationCrowdedBehavior.

◆ radiusBackingField

float radiusBackingField = 0.5f
package

◆ tr

Transform tr
protected

Cached tranform component.

◆ wallAvoidFalloff

float wallAvoidFalloff = 1

How much the wallAvoidForce decreases with distance.

The strenght of avoidance is:

str = 1/dist*wallAvoidFalloff
See also
wallAvoidForce
Deprecated:
This feature is currently disabled as it didn't work that well and was tricky to support after some changes to the RVO system. It may be enabled again in a future version.

◆ wallAvoidForce

float wallAvoidForce = 1

An extra force to avoid walls.

This can be good way to reduce "wall hugging" behaviour.

Deprecated:
This feature is currently disabled as it didn't work that well and was tricky to support after some changes to the RVO system. It may be enabled again in a future version.

Property Documentation

◆ ai

IAstarAI ai
getsetprotected

Cached reference to a movement script (if one is used)

◆ center

float center
getset

Center of the agent relative to the pivot point of this game object.

Note
If a movement script (AIPath/RichAI/AILerp, anything implementing the IAstarAI interface) is attached to the same GameObject, this value will be driven by that script.

◆ enableRotation

bool enableRotation
getset
Deprecated:

◆ height

float height
getset

Height of the agent in world units.

Note
If a movement script (AIPath/RichAI/AILerp, anything implementing the IAstarAI interface) is attached to the same GameObject, this value will be driven by that script.

◆ mask

LayerMask mask
getset
Deprecated:

◆ maxSpeed

float maxSpeed
getset
Deprecated:

◆ movementPlane

MovementPlane movementPlane
get

Determines if the XY (2D) or XZ (3D) plane is used for movement.

◆ position

Vector3 position
get

Current position of the agent.

Note that this is only updated every local avoidance simulation step, not every frame.

◆ radius

float radius
getset

Radius of the agent in world units.

Note
If a movement script (AIPath/RichAI/AILerp, anything implementing the IAstarAI interface) is attached to the same GameObject, this value will be driven by that script.

◆ rotationSpeed

float rotationSpeed
getset
Deprecated:

◆ rvoAgent

IAgent rvoAgent
getprivate set

Reference to the internal agent.

◆ simulator

ISimulator simulator
getprivate set

Reference to the rvo simulator.

◆ velocity

Vector3 velocity
getset

Current calculated velocity of the agent.

This is not necessarily the velocity the agent is actually moving with (that is up to the movement script to decide) but it is the velocity that the RVO system has calculated is best for avoiding obstacles and reaching the target.

See also
CalculateMovementDelta

You can also set the 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.

Setting the velocity using this property 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 property is set again.

Note that if you set the velocity the value that can be read from this property will not change until the next simulation step.

See also
IAgent.ForceSetVelocity
ManualRVOAgent.cs
The documentation for this class was generated from the following file: