Provides local steering behaviors for a group of agents. More...

#include <DetourCrowd.h>

Public Member Functions
	dtCrowd ()

	~dtCrowd ()

bool	init (const int maxAgents, const float maxAgentRadius, dtNavMesh *nav)
	Initializes the crowd. More...

void	setObstacleAvoidanceParams (const int idx, const dtObstacleAvoidanceParams *params)
	Sets the shared avoidance configuration for the specified index. More...

const dtObstacleAvoidanceParams *	getObstacleAvoidanceParams (const int idx) const
	Gets the shared avoidance configuration for the specified index. More...

const dtCrowdAgent *	getAgent (const int idx)
	Gets the specified agent from the pool. More...

dtCrowdAgent *	getEditableAgent (const int idx)
	Gets the specified agent from the pool. More...

int	getAgentCount () const
	The maximum number of agents that can be managed by the object. More...

int	addAgent (const float pos, const dtCrowdAgentParams params)
	Adds a new agent to the crowd. More...

void	updateAgentParameters (const int idx, const dtCrowdAgentParams *params)
	Updates the specified agent's configuration. More...

void	removeAgent (const int idx)
	Removes the agent from the crowd. More...

bool	requestMoveTarget (const int idx, dtPolyRef ref, const float *pos)
	Submits a new move request for the specified agent. More...

bool	requestMoveVelocity (const int idx, const float *vel)
	Submits a new move request for the specified agent. More...

bool	resetMoveTarget (const int idx)
	Resets any request for the specified agent. More...

int	getActiveAgents (dtCrowdAgent **agents, const int maxAgents)
	Gets the active agents int the agent pool. More...

void	update (const float dt, dtCrowdAgentDebugInfo *debug)
	Updates the steering and positions of all agents. More...

const dtQueryFilter *	getFilter (const int i) const
	Gets the filter used by the crowd. More...

dtQueryFilter *	getEditableFilter (const int i)
	Gets the filter used by the crowd. More...

const float *	getQueryHalfExtents () const
	Gets the search halfExtents [(x, y, z)] used by the crowd for query operations. More...

const float *	getQueryExtents () const
	Same as getQueryHalfExtents. More...

int	getVelocitySampleCount () const
	Gets the velocity sample count. More...

const dtProximityGrid *	getGrid () const
	Gets the crowd's proximity grid. More...

const dtPathQueue *	getPathQueue () const
	Gets the crowd's path request queue. More...

const dtNavMeshQuery *	getNavMeshQuery () const
	Gets the query object used by the crowd. More...

Description

Provides local steering behaviors for a group of agents.

This is the core class of the Crowd module. See the Crowd documentation for a summary of the crowd features.

A common method for setting up the crowd is as follows:

Allocate the crowd using dtAllocCrowd.
Initialize the crowd using init().
Set the avoidance configurations using setObstacleAvoidanceParams().
Add agents using addAgent() and make an initial movement request using requestMoveTarget().

A common process for managing the crowd is as follows:

Call update() to allow the crowd to manage its agents.
Retrieve agent information using getActiveAgents().
Make movement requests using requestMoveTarget() when movement goal changes.
Repeat every frame.

Some agent configuration settings can be updated using updateAgentParameters(). But the crowd owns the agent position. So it is not possible to update an active agent's position. If agent position must be fed back into the crowd, the agent must be removed and re-added.

Notes:

Path related information is available for newly added agents only after an update() has been performed.
Agent objects are kept in a pool and re-used. So it is important when using agent objects to check the value of dtCrowdAgent::active to determine if the agent is actually in use or not.
This class is meant to provide 'local' movement. There is a limit of 256 polygons in the path corridor.
So it is not meant to provide automatic pathfinding services over long distances.

See also: dtAllocCrowd(), dtFreeCrowd(), init(), dtCrowdAgent

Constructor & Destructor Documentation

◆ dtCrowd()

dtCrowd::dtCrowd ( )

◆ ~dtCrowd()

dtCrowd::~dtCrowd ( )

Member Function Documentation

◆ addAgent()

int dtCrowd::addAgent	(	const float *	pos,
		const dtCrowdAgentParams *	params
	)

Adds a new agent to the crowd.

Parameters

[in]	pos	The requested position of the agent. [(x, y, z)]
[in]	params	The configuration of the agent.

Returns: The index of the agent in the agent pool. Or -1 if the agent could not be added.

The agent's position will be constrained to the surface of the navigation mesh.

◆ getActiveAgents()

int dtCrowd::getActiveAgents	(	dtCrowdAgent **	agents,
		const int	maxAgents
	)

Gets the active agents int the agent pool.

Parameters

[out]	agents	An array of agent pointers. [(dtCrowdAgent ) maxAgents]
[in]	maxAgents	The size of the crowd agent array.

Returns: The number of agents returned in agents.

◆ getAgent()

const dtCrowdAgent * dtCrowd::getAgent ( const int idx )

Gets the specified agent from the pool.

Parameters

[in] idx The agent index. [Limits: 0 <= value < getAgentCount()]

Returns: The requested agent.

Agents in the pool may not be in use. Check dtCrowdAgent.active before using the returned object.

◆ getAgentCount()

int dtCrowd::getAgentCount ( ) const

The maximum number of agents that can be managed by the object.

Returns: The maximum number of agents.

◆ getEditableAgent()

dtCrowdAgent * dtCrowd::getEditableAgent ( const int idx )

Gets the specified agent from the pool.

Agents in the pool may not be in use.

Parameters

[in] idx The agent index. [Limits: 0 <= value < getAgentCount()]

Returns: The requested agent.

Check dtCrowdAgent.active before using the returned object.

◆ getEditableFilter()

dtQueryFilter* dtCrowd::getEditableFilter ( const int i )

inline

Gets the filter used by the crowd.

Returns: The filter used by the crowd.

◆ getFilter()

const dtQueryFilter* dtCrowd::getFilter ( const int i ) const

inline

Gets the filter used by the crowd.

Returns: The filter used by the crowd.

◆ getGrid()

const dtProximityGrid* dtCrowd::getGrid ( ) const

inline

Gets the crowd's proximity grid.

Returns: The crowd's proximity grid.

◆ getNavMeshQuery()

const dtNavMeshQuery* dtCrowd::getNavMeshQuery ( ) const

inline

Gets the query object used by the crowd.

◆ getObstacleAvoidanceParams()

const dtObstacleAvoidanceParams * dtCrowd::getObstacleAvoidanceParams ( const int idx ) const

Gets the shared avoidance configuration for the specified index.

Parameters

[in] idx The index of the configuration to retreive. [Limits: 0 <= value < DT_CROWD_MAX_OBSTAVOIDANCE_PARAMS]

Returns: The requested configuration.

◆ getPathQueue()

const dtPathQueue* dtCrowd::getPathQueue ( ) const

inline

Gets the crowd's path request queue.

Returns: The crowd's path request queue.

◆ getQueryExtents()

const float* dtCrowd::getQueryExtents ( ) const

inline

Same as getQueryHalfExtents.

Left to maintain backwards compatibility.

Returns: The search halfExtents used by the crowd. [(x, y, z)]

◆ getQueryHalfExtents()

const float* dtCrowd::getQueryHalfExtents ( ) const

inline

Gets the search halfExtents [(x, y, z)] used by the crowd for query operations.

Returns: The search halfExtents used by the crowd. [(x, y, z)]

◆ getVelocitySampleCount()

int dtCrowd::getVelocitySampleCount ( ) const

inline

Gets the velocity sample count.

Returns: The velocity sample count.

◆ init()

bool dtCrowd::init	(	const int	maxAgents,
		const float	maxAgentRadius,
		dtNavMesh *	nav
	)

Initializes the crowd.

Parameters

[in]	maxAgents	The maximum number of agents the crowd can manage. [Limit: >= 1]
[in]	maxAgentRadius	The maximum radius of any agent that will be added to the crowd. [Limit: > 0]
[in]	nav	The navigation mesh to use for planning.

Returns: True if the initialization succeeded.

May be called more than once to purge and re-initialize the crowd.

◆ removeAgent()

void dtCrowd::removeAgent ( const int idx )

Removes the agent from the crowd.

Parameters

[in] idx The agent index. [Limits: 0 <= value < getAgentCount()]

The agent is deactivated and will no longer be processed. Its dtCrowdAgent object is not removed from the pool. It is marked as inactive so that it is available for reuse.

◆ requestMoveTarget()

bool dtCrowd::requestMoveTarget	(	const int	idx,
		dtPolyRef	ref,
		const float *	pos
	)

Submits a new move request for the specified agent.

Parameters

[in]	idx	The agent index. [Limits: 0 <= value < getAgentCount()]
[in]	ref	The position's polygon reference.
[in]	pos	The position within the polygon. [(x, y, z)]

Returns: True if the request was successfully submitted.

This method is used when a new target is set.

The position will be constrained to the surface of the navigation mesh.

The request will be processed during the next update().

◆ requestMoveVelocity()

bool dtCrowd::requestMoveVelocity	(	const int	idx,
		const float *	vel
	)

Submits a new move request for the specified agent.

Parameters

[in]	idx	The agent index. [Limits: 0 <= value < getAgentCount()]
[in]	vel	The movement velocity. [(x, y, z)]

Returns: True if the request was successfully submitted.

◆ resetMoveTarget()

bool dtCrowd::resetMoveTarget ( const int idx )

Resets any request for the specified agent.

Parameters

[in] idx The agent index. [Limits: 0 <= value < getAgentCount()]

Returns: True if the request was successfully reseted.

◆ setObstacleAvoidanceParams()

void dtCrowd::setObstacleAvoidanceParams	(	const int	idx,
		const dtObstacleAvoidanceParams *	params
	)

Sets the shared avoidance configuration for the specified index.

Parameters

[in]	idx	The index. [Limits: 0 <= value < DT_CROWD_MAX_OBSTAVOIDANCE_PARAMS]
[in]	params	The new configuration.

◆ update()

void dtCrowd::update	(	const float	dt,
		dtCrowdAgentDebugInfo *	debug
	)

Updates the steering and positions of all agents.

Parameters

[in]	dt	The time, in seconds, to update the simulation. [Limit: > 0]
[out]	debug	A debug object to load with debug information. [Opt]

◆ updateAgentParameters()

void dtCrowd::updateAgentParameters	(	const int	idx,
		const dtCrowdAgentParams *	params
	)

Updates the specified agent's configuration.

Parameters

[in]	idx	The agent index. [Limits: 0 <= value < getAgentCount()]
[in]	params	The new agent configuration.

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

Public Member Functions

Description

Constructor & Destructor Documentation

◆ dtCrowd()

◆ ~dtCrowd()

Member Function Documentation

◆ addAgent()

◆ getActiveAgents()

◆ getAgent()

◆ getAgentCount()

◆ getEditableAgent()

◆ getEditableFilter()

◆ getFilter()

◆ getGrid()

◆ getNavMeshQuery()

◆ getObstacleAvoidanceParams()

◆ getPathQueue()

◆ getQueryExtents()

◆ getQueryHalfExtents()

◆ getVelocitySampleCount()

◆ init()

◆ removeAgent()

◆ requestMoveTarget()

◆ requestMoveVelocity()

◆ resetMoveTarget()

◆ setObstacleAvoidanceParams()

◆ update()

◆ updateAgentParameters()