A* Pathfinding Project  4.2.4
The A* Pathfinding Project for Unity 3D
Simulator Class Reference

Local Avoidance Simulator. More...

Detailed Description

Local Avoidance Simulator.

This class handles local avoidance simulation for a number of agents using Reciprocal Velocity Obstacles (RVO) and Optimal Reciprocal Collision Avoidance (ORCA).

This class will handle calculation of velocities from desired velocities supplied by a script. It is, however, not responsible for moving any objects in a Unity Scene. For that there are other scripts (see below).

Obstacles can be added and removed from the simulation, agents can also be added and removed at any time.

See also
RVOSimulator
RVOAgent
Pathfinding.RVO.IAgent

The implementation uses a sampling based algorithm with gradient descent to find the avoidance velocities.

You will most likely mostly use the wrapper class RVOSimulator.

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

Classes

class  Worker
 Worker thread for RVO simulation. More...
 
class  WorkerContext
 

Public Member Functions

 Simulator (int workers, bool doubleBuffering, MovementPlane movementPlane)
 Create a new simulator. More...
 
IAgent AddAgent (IAgent agent)
 Add a previously removed agent to the simulation. More...
 
IAgent AddAgent (Vector3 position)
 Add an agent at the specified position. More...
 
IAgent AddAgent (Vector2 position, float elevationCoordinate)
 Add an agent at the specified position. More...
 
ObstacleVertex AddObstacle (ObstacleVertex v)
 Adds a previously removed obstacle. More...
 
ObstacleVertex AddObstacle (Vector3[] vertices, float height, bool cycle=true)
 Adds an obstacle described by the vertices. More...
 
ObstacleVertex AddObstacle (Vector3[] vertices, float height, Matrix4x4 matrix, RVOLayer layer=RVOLayer.DefaultObstacle, bool cycle=true)
 Adds an obstacle described by the vertices. More...
 
ObstacleVertex AddObstacle (Vector3 a, Vector3 b, float height)
 Adds a line obstacle with a specified height. More...
 
void ClearAgents ()
 Removes all agents from the simulation. More...
 
List< AgentGetAgents ()
 Get a list of all agents. More...
 
List< ObstacleVertexGetObstacles ()
 Get a list of all obstacles. More...
 
void OnDestroy ()
 Terminates all worker threads. More...
 
void RemoveAgent (IAgent agent)
 Removes a specified agent from this simulation. More...
 
void RemoveObstacle (ObstacleVertex v)
 Removes the obstacle identified by the vertex. More...
 
void Update ()
 Should be called once per frame. More...
 
void UpdateObstacle (ObstacleVertex obstacle, Vector3[] vertices, Matrix4x4 matrix)
 Updates the vertices of an obstacle. More...
 
void UpdateObstacles ()
 Rebuilds the obstacle tree at next simulation frame. More...
 

Public Attributes

readonly MovementPlane movementPlane = MovementPlane.XZ
 Determines if the XY (2D) or XZ (3D) plane is used for movement. More...
 
List< ObstacleVertexobstacles
 Obstacles in this simulation. More...
 
float symmetryBreakingBias = 0.1f
 Bias agents to pass each other on the right side. More...
 

Properties

float DeltaTime [get]
 
float DesiredDeltaTime [get, set]
 Time in seconds between each simulation step. More...
 
bool Multithreading [get]
 Is using multithreading. More...
 
RVOQuadtree Quadtree [get, private set]
 Quadtree for this simulation. More...
 

Private Member Functions

void BlockUntilSimulationStepIsDone ()
 Blocks until separate threads have finished with the current simulation step. More...
 
void BuildQuadtree ()
 
void CleanAndUpdateObstaclesIfNecessary ()
 
void CleanObstacles ()
 
void PreCalculation ()
 
void ScheduleCleanObstacles ()
 

Private Attributes

List< Agentagents
 Agents in this simulation. More...
 
WorkerContext coroutineWorkerContext = new WorkerContext()
 
float deltaTime
 
float desiredDeltaTime = 0.05f
 Inverse desired simulation fps. More...
 
bool doCleanObstacles = false
 
readonly bool doubleBuffering = true
 Use Double Buffering. More...
 
bool doUpdateObstacles = false
 
float lastStep = -99999
 
readonly Worker [] workers
 Worker threads. More...
 

Constructor & Destructor Documentation

◆ Simulator()

Simulator ( int  workers,
bool  doubleBuffering,
MovementPlane  movementPlane 
)

Create a new simulator.

Parameters
workersUse the specified number of worker threads.
When the number zero is specified, no multithreading will be used. A good number is the number of cores on the machine.
doubleBufferingUse Double Buffering for calculations. Testing done with 5000 agents and 0.1 desired delta time showed that with double buffering enabled the game ran at 50 fps for most frames, dropping to 10 fps during calculation frames. But without double buffering it ran at around 10 fps all the time.
This will let threads calculate while the game progresses instead of waiting for the calculations to finish.
movementPlaneThe plane that the movement happens in. XZ for 3D games, XY for 2D games.
Note
Will only have effect if using multithreading
See also
Multithreading

Member Function Documentation

◆ AddAgent() [1/3]

IAgent AddAgent ( IAgent  agent)

Add a previously removed agent to the simulation.

An agent can only be in one simulation at a time, any attempt to add an agent to two simulations or multiple times to the same simulation will result in an exception being thrown.

See also
RemoveAgent

◆ AddAgent() [2/3]

IAgent AddAgent ( Vector3  position)

Add an agent at the specified position.

You can use the returned interface to read several parameters such as position and velocity and set for example radius and desired velocity.

Deprecated:
Use AddAgent(Vector2,float) instead

◆ AddAgent() [3/3]

IAgent AddAgent ( Vector2  position,
float  elevationCoordinate 
)

Add an agent at the specified position.

You can use the returned interface to read and write parameters and set for example radius and desired point to move to.

See also
RemoveAgent
Parameters
positionSee IAgent.Position
elevationCoordinateSee IAgent.ElevationCoordinate

◆ AddObstacle() [1/4]

ObstacleVertex AddObstacle ( ObstacleVertex  v)

Adds a previously removed obstacle.

This does not check if the obstacle is already added to the simulation, so please do not add an obstacle multiple times.

It is assumed that this is a valid obstacle.

◆ AddObstacle() [2/4]

ObstacleVertex AddObstacle ( Vector3 []  vertices,
float  height,
bool  cycle = true 
)

Adds an obstacle described by the vertices.

See also
RemoveObstacle

◆ AddObstacle() [3/4]

ObstacleVertex AddObstacle ( Vector3 []  vertices,
float  height,
Matrix4x4  matrix,
RVOLayer  layer = RVOLayer.DefaultObstacle,
bool  cycle = true 
)

Adds an obstacle described by the vertices.

See also
RemoveObstacle

◆ AddObstacle() [4/4]

ObstacleVertex AddObstacle ( Vector3  a,
Vector3  b,
float  height 
)

Adds a line obstacle with a specified height.

See also
RemoveObstacle

◆ BlockUntilSimulationStepIsDone()

void BlockUntilSimulationStepIsDone ( )
private

Blocks until separate threads have finished with the current simulation step.

When double buffering is done, the simulation is performed in between frames.

◆ BuildQuadtree()

void BuildQuadtree ( )
private

◆ CleanAndUpdateObstaclesIfNecessary()

void CleanAndUpdateObstaclesIfNecessary ( )
private

◆ CleanObstacles()

void CleanObstacles ( )
private

◆ ClearAgents()

void ClearAgents ( )

Removes all agents from the simulation.

◆ GetAgents()

List<Agent> GetAgents ( )

Get a list of all agents.

This is an internal list. I'm not going to be restrictive so you may access it since it is better for performance but please do not modify it since that can cause errors in the simulation.

Warning
Do not modify this list!

◆ GetObstacles()

List<ObstacleVertex> GetObstacles ( )

Get a list of all obstacles.

This is a list of obstacle vertices. Each vertex is part of a doubly linked list loop forming an obstacle polygon.

Warning
Do not modify this list!
See also
AddObstacle
RemoveObstacle

◆ OnDestroy()

void OnDestroy ( )

Terminates all worker threads.

Warning
You must call this when you are done with the simulator, otherwise some threads can linger and lead to memory leaks.

◆ PreCalculation()

void PreCalculation ( )
private

◆ RemoveAgent()

void RemoveAgent ( IAgent  agent)

Removes a specified agent from this simulation.

The agent can be added again later by using AddAgent.

See also
AddAgent(IAgent)
ClearAgents

◆ RemoveObstacle()

void RemoveObstacle ( ObstacleVertex  v)

Removes the obstacle identified by the vertex.

This must be the same vertex as the one returned by the AddObstacle call.

See also
AddObstacle

◆ ScheduleCleanObstacles()

void ScheduleCleanObstacles ( )
private

◆ Update()

void Update ( )

Should be called once per frame.

◆ UpdateObstacle()

void UpdateObstacle ( ObstacleVertex  obstacle,
Vector3 []  vertices,
Matrix4x4  matrix 
)

Updates the vertices of an obstacle.

Parameters
obstacleObstacle to update
verticesNew vertices for the obstacle, must have at least the number of vertices in the original obstacle
matrixMatrix to multiply vertices with before updating obstacle

The number of vertices in an obstacle cannot be changed, existing vertices can only be moved.

◆ UpdateObstacles()

void UpdateObstacles ( )

Rebuilds the obstacle tree at next simulation frame.

Add and remove obstacle functions call this automatically.

Member Data Documentation

◆ agents

List<Agent> agents
private

Agents in this simulation.

◆ coroutineWorkerContext

WorkerContext coroutineWorkerContext = new WorkerContext()
private

◆ deltaTime

float deltaTime
private

◆ desiredDeltaTime

float desiredDeltaTime = 0.05f
private

Inverse desired simulation fps.

See also
DesiredDeltaTime

◆ doCleanObstacles

bool doCleanObstacles = false
private

◆ doubleBuffering

readonly bool doubleBuffering = true
private

Use Double Buffering.

See also
DoubleBuffering

◆ doUpdateObstacles

bool doUpdateObstacles = false
private

◆ lastStep

float lastStep = -99999
private

◆ movementPlane

readonly MovementPlane movementPlane = MovementPlane.XZ

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

◆ obstacles

List<ObstacleVertex> obstacles

Obstacles in this simulation.

◆ symmetryBreakingBias

float symmetryBreakingBias = 0.1f

Bias agents to pass each other on the right side.

If the desired velocity of an agent puts it on a collision course with another agent or an obstacle its desired velocity will be rotated this number of radians (1 radian is approximately 57°) to the right. This helps to break up symmetries and makes it possible to resolve some situations much faster.

When many agents have the same goal this can however have the side effect that the group clustered around the target point may as a whole start to spin around the target point.

Recommended values are in the range of 0 to 0.2.

If this value is negative, the agents will be biased towards passing each other on the left side instead.

◆ workers

readonly Worker [] workers
private

Worker threads.

Property Documentation

◆ DeltaTime

float DeltaTime
get

◆ DesiredDeltaTime

float DesiredDeltaTime
getset

Time in seconds between each simulation step.

This is the desired delta time, the simulation will never run at a higher fps than the rate at which the Update function is called.

◆ Multithreading

bool Multithreading
get

Is using multithreading.

◆ Quadtree

RVOQuadtree Quadtree
getprivate set

Quadtree for this simulation.

Used internally by the simulation to perform fast neighbour lookups for each agent. Please only read from this tree, do not rebuild it since that can interfere with the simulation. It is rebuilt when necessary.


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