SimulatorBurst 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	Agent
struct	AgentData
struct	AgentOutputData
struct	HorizonAgentData
struct	TemporaryAgentData

Public Member Functions
	SimulatorBurst (bool doubleBuffering, MovementPlane movementPlane)
	Create a new simulator. More...
IAgent	AddAgent (Vector2 position, float elevationCoordinate)
	Add an agent at the specified position. More...
IAgent	AddAgent (IAgent agent)
ObstacleVertex	AddObstacle (ObstacleVertex v)
ObstacleVertex	AddObstacle (Vector3[] vertices, float height, bool cycle=true)
ObstacleVertex	AddObstacle (Vector3[] vertices, float height, Matrix4x4 matrix, RVOLayer layer=RVOLayer.DefaultObstacle, bool cycle=true)
ObstacleVertex	AddObstacle (Vector3 a, Vector3 b, float height)
void	ClearAgents ()
	Removes all agents from the simulation. More...
IReadOnlyList< IAgent >	GetAgents ()
	Get a list of all agents. More...
List< ObstacleVertex >	GetObstacles ()
	Get a list of all obstacles. More...
void	OnDestroy ()
	Frees all used memory. More...
void	RemoveAgent (IAgent agent)
	Removes a specified agent from this simulation. More...
void	RemoveObstacle (ObstacleVertex v)
void	Update ()
	Should be called once per frame. More...
void	UpdateObstacle (ObstacleVertex obstacle, Vector3[] vertices, Matrix4x4 matrix)
void	UpdateObstacles ()
	Rebuilds the obstacle tree at next simulation frame. More...

Public Attributes
Rect	AgentBounds => quadtree.bounds
int	AgentCount => numAgents
	Number of agents in the simulation. More...
float	DeltaTime => deltaTime
MovementPlane	MovementPlane => movementPlane
readonly MovementPlane	movementPlane = MovementPlane.XZ
	Determines if the XY (2D) or XZ (3D) plane is used for movement. More...
bool	Multithreading => true
AgentData	nextSimulationData
	Internal simulation data. More...
List< ObstacleVertex >	obstacles
	Obstacles in this simulation. More...
AgentOutputData	outputData
	Internal simulation data. More...
RVOQuadtreeBurst	quadtree
	Quadtree for this simulation. More...
float	symmetryBreakingBias = 0.1f
	Bias agents to pass each other on the right side. More...

Properties
bool	AnyAgentHasDebug [get, private set]
float	DesiredDeltaTime [get, set]
	Time in seconds between each simulation step. More...
bool	DoubleBuffering [get, set]
	Use double buffering. More...
bool	HardCollisions [get, set]
	Use hard collisions. More...
float	SymmetryBreakingBias [get, set]
Properties inherited from ISimulator
float	DesiredDeltaTime [get, set]
bool	DoubleBuffering [get, set]
bool	HardCollisions [get, set]
MovementPlane	MovementPlane [get]
bool	Multithreading [get]
float	SymmetryBreakingBias [get, set]

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

Private Attributes
Action []	agentPreCalculationCallbacks = new Action[0]
Agent []	agents = new Agent[0]
	Agents in this simulation. More...
AgentData	currentSimulationData
float	deltaTime
float	desiredDeltaTime = 0.05f
	Inverse desired simulation fps. More...
HorizonAgentData	horizonAgentData
JobHandle	inProgressJob
AgentOutputData	inProgressOutputData
bool	jobInProgress
float	lastStep = -99999
int	numAgents = 0
	Number of agents in this simulation. More...
TemporaryAgentData	temporaryAgentData

Constructor & Destructor Documentation

SimulatorBurst()

SimulatorBurst	(	bool	doubleBuffering,
		MovementPlane	movementPlane
	)

Create a new simulator.

Parameters

workers	Use 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.
doubleBuffering	Use 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.
movementPlane	The 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/2]

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

position	See IAgent.Position
elevationCoordinate	See IAgent.ElevationCoordinate

Implements ISimulator.

AddAgent() [2/2]

IAgent AddAgent

(

IAgent

agent

)

Implements ISimulator.

AddObstacle() [1/4]

ObstacleVertex AddObstacle

(

ObstacleVertex

v

)

Implements ISimulator.

AddObstacle() [2/4]

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

Implements ISimulator.

AddObstacle() [3/4]

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

Implements ISimulator.

AddObstacle() [4/4]

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

Implements ISimulator.

AllocateAgentSpace()

void AllocateAgentSpace ( )

private

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.

CleanAndUpdateObstaclesIfNecessary()

void CleanAndUpdateObstaclesIfNecessary ( )

private

CleanObstacles()

void CleanObstacles ( )

private

ClearAgents()

void ClearAgents

(

)

Removes all agents from the simulation.

Implements ISimulator.

GetAgents()

IReadOnlyList<IAgent> 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!

Implements ISimulator.

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

(

)

Frees all used memory.

Warning

You must call this when you are done with the simulator, otherwise some resources 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

Implements ISimulator.

RemoveObstacle()

void RemoveObstacle

(

ObstacleVertex

v

)

Implements ISimulator.

ScheduleCleanObstacles()

void ScheduleCleanObstacles ( )

private

Update()

void Update

(

)

Should be called once per frame.

Implements ISimulator.

UpdateObstacle()

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

Implements ISimulator.

UpdateObstacles()

void UpdateObstacles

(

)

Rebuilds the obstacle tree at next simulation frame.

Add and remove obstacle functions call this automatically.

Member Data Documentation

AgentBounds

Rect AgentBounds => quadtree.bounds

AgentCount

int AgentCount => numAgents

Number of agents in the simulation.

agentPreCalculationCallbacks

Action [] agentPreCalculationCallbacks = new Action[0]

private

agents

Agent [] agents = new Agent[0]

private

Agents in this simulation.

currentSimulationData

AgentData currentSimulationData

private

deltaTime

float deltaTime

private

DeltaTime

float DeltaTime => deltaTime

desiredDeltaTime

float desiredDeltaTime = 0.05f

private

Inverse desired simulation fps.

See also

DesiredDeltaTime

horizonAgentData

HorizonAgentData horizonAgentData

private

inProgressJob

JobHandle inProgressJob

private

inProgressOutputData

AgentOutputData inProgressOutputData

private

jobInProgress

bool jobInProgress

private

lastStep

float lastStep = -99999

private

MovementPlane

MovementPlane MovementPlane => movementPlane

movementPlane

readonly MovementPlane movementPlane = MovementPlane.XZ

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

Multithreading

bool Multithreading => true

nextSimulationData

AgentData nextSimulationData

Internal simulation data.

Can be used if you need very high performance access to the agent data. Normally you would use the SimulatorBurst.Agent class instead (implements the IAgent interface).

numAgents

int numAgents = 0

private

Number of agents in this simulation.

obstacles

List<ObstacleVertex> obstacles

Obstacles in this simulation.

outputData

AgentOutputData outputData

Internal simulation data.

Can be used if you need very high performance access to the agent data. Normally you would use the SimulatorBurst.Agent class instead (implements the IAgent interface).

quadtree

RVOQuadtreeBurst quadtree

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.

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.

temporaryAgentData

TemporaryAgentData temporaryAgentData

private

Property Documentation

AnyAgentHasDebug

bool AnyAgentHasDebug

getprivate set

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.

DoubleBuffering

bool DoubleBuffering

getset

Use double buffering.

HardCollisions

bool HardCollisions

getset

Use hard collisions.

SymmetryBreakingBias

float SymmetryBreakingBias

getset

---

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

• /Users/arong/Unity/a-pathfinding-project/Assets/AstarPathfindingProject/Core/RVO/RVOCoreSimulatorBurst.cs