User Guide (Version 1.17)

Returning Entities with Overlapping Bounding Boxes

The function GetEntitiesInBox uses the internal entity hash grid to return the number of entities whose bounding boxes overlap a specified box volume. The function supports filtering by Simulation type and optional sorting of the output list by entity mass in ascending order.


virtual int GetEntitiesInBox(Vec3 ptmin,Vec3 ptmax, IPhysicalEntity **&pList, int objtypes, int szListPrealloc=0) = 0;

Example call

IPhysicalEntity** entityList = 0; int entityCount = gEnv->pPhysicalWorld->GetEntitiesInBox(m_volume.min, m_volume.max, entityList, ent_static | ent_terrain | ent_sleeping_rigid | ent_rigid);


Parameter Description
ptmin Minimum point in the space that defines the desired box volume.
ptmax Maximum point in the space that defines the desired box volume.
pList Pointer to a list of objects that the function poplulates.
objtypes Types of objects that need to be considered in the query.
szListPrealloc If specified, the maximum number of objects contained in the pList array.

The possible object types are described in the physinterface.h header file in the entity_query_flags enumerators. A few are listed in the following table:

Entity type flag Description
ent_static Static entities
ent_terrain Terrain
ent_sleeping_rigid Sleeping rigid bodies
ent_rigid Rigid bodies

After the function completes, you can easily iterate through the entity list to perform desired operations, as in the following code outline:

for (int i = 0; i < entityCount; \++i) { IPhysicalEntity\* entity = entityList[i]; [...] if (entity->GetType() == PE_RIGID) { [...] } [...] }

If ent_alloctate_list is specified, the function allocates memory for the list (the memory can later be freed by a call to pWorld->GetPhysUtils()->DeletePointer). Otherwise, an internal pointer will be returned.


Because the physics system uses this pointer in almost all operations that require forming an entity list, no such calls should be made when the list is in use. If such calls are required and memory allocation is undesired, copy the list to a local pre-allocated array before iterating over it.