dtCrowd Class Reference

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.
void	setObstacleAvoidanceParams (const int idx, const dtObstacleAvoidanceParams *params)
	Sets the shared avoidance configuration for the specified index.
const dtObstacleAvoidanceParams *	getObstacleAvoidanceParams (const int idx) const
	Gets the shared avoidance configuration for the specified index.
const dtCrowdAgent *	getAgent (const int idx)
	Gets the specified agent from the pool.
dtCrowdAgent *	getEditableAgent (const int idx)
	Gets the specified agent from the pool.
int	getAgentCount () const
	The maximum number of agents that can be managed by the object.
int	addAgent (const float *pos, const dtCrowdAgentParams *params)
	Adds a new agent to the crowd.
void	updateAgentParameters (const int idx, const dtCrowdAgentParams *params)
	Updates the specified agent's configuration.
void	removeAgent (const int idx)
	Removes the agent from the crowd.
bool	requestMoveTarget (const int idx, dtPolyRef ref, const float *pos)
	Submits a new move request for the specified agent.
bool	requestMoveVelocity (const int idx, const float *vel)
	Submits a new move request for the specified agent.
bool	resetMoveTarget (const int idx)
	Resets any request for the specified agent.
int	getActiveAgents (dtCrowdAgent **agents, const int maxAgents)
	Gets the active agents int the agent pool.
void	update (const float dt, dtCrowdAgentDebugInfo *debug)
	Updates the steering and positions of all agents.
const dtQueryFilter *	getFilter (const int i) const
	Gets the filter used by the crowd.
dtQueryFilter *	getEditableFilter (const int i)
	Gets the filter used by the crowd.
const float *	getQueryHalfExtents () const
	Gets the search halfExtents [(x, y, z)] used by the crowd for query operations.
const float *	getQueryExtents () const
	Same as getQueryHalfExtents.
int	getVelocitySampleCount () const
	Gets the velocity sample count.
const dtProximityGrid *	getGrid () const
	Gets the crowd's proximity grid.
const dtPathQueue *	getPathQueue () const
	Gets the crowd's path request queue.
const dtNavMeshQuery *	getNavMeshQuery () const
	Gets the query object used by the crowd.

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:

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

A common process for managing the crowd is as follows:

1. Call update() to allow the crowd to manage its agents.
2. Retrieve agent information using getActiveAgents().
3. Make movement requests using requestMoveTarget() when movement goal changes.
4. 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:

• DetourCrowd.h
• DetourCrowd.cpp