PhysX Scene Queries

You can use physics raycast and shape cast queries to determine whether a specific line segment intersects physics geometry. For example, you might want to determine what object is in front of another object, or test a line of sight. For a shape cast, the line segment is in the form of a desired shape (for example, a sphere). All scene queries are performed on a Physics::World object. For more information, see PhysX World Programming Notes.

You can use scene queries to find nearby objects using the following methods.

Topics

• Raycast
• Shapecast
• Overlap

Note
Scene queries can have a performance cost.

Raycast

Raycast queries are the most common scene query. A raycast query takes a point and direction, with a distance, and returns the closest collider that intersected the ray.

Example
The raycast query intersects the pentagon only.

To perform a raycast query, use the WorldRequestBus.

Example RayCast Closest

Physics::RayCastRequest request;
Physics::RayCastHit result;
WorldRequestBus::BroadcastResult(result, &WorldRequests::RayCast, request);

You can also retrieve objects that intersect with the ray by using the multiple version.

Example RayCast Multiple

Physics::RayCastRequest request;
vector<Physics::RayCastHit> results;
WorldRequestBus::BroadcastResult(result, &WorldRequests::RayCastMultiple, request);

Note
You can specify the maximum number of hits that can be collected from a RayCastMultiple query. You can specify the RayCast Buffer Size property in the PhysX Configuration window. For more information, see World Configuration.

The following tables describe the properties for the RayCastRequest and RayCastHit objects.

RayCastRequest Properties

RayCastHit Properties

Shapecast

A shapecast query is similar to a raycast query except that a shapecast query takes a shape as well as a point and direction. The shape is swept along the ray to form a volume. Anything that intersects with this volume is returned from the query.

Example
The shapecast query is in the shape of a sphere and intersects with the rectangle and pentagon entities.

To perform a shapecast query, use the WorldRequestBus.

Example ShapeCast Closest

Physics::ShapeCastRequest request;
Physics::RayCastHit result;
WorldRequestBus::BroadcastResult(result, &WorldRequests::ShapeCast, request);

Similar to raycasting, there is a multiple version for retrieving all objects that intersect with the volume.

Example ShapeCast Multiple

Physics::ShapeCastRequest request;
vector<Physics::RayCastHit> results;
WorldRequestBus::BroadcastResult(results, &WorldRequests::ShapeCastMultiple, request);

Note
You can specify the maximum number of hits that can be collected from a ShapeCastMultiple query. You can specify the Shapecast Buffer Size value in the PhysX Configuration window. For more information, see World Configuration.

ShapeCastRequest Properties

Overlap

Overlap queries are simpler, as they don’t take a direction or distance. Overlap queries simply return all objects that intersect a shape at specified location in the world. There is only one multiple version using this method.

Example
The overlap query is a sphere shape that intersects with both entities.

Example Overlap Closest

Physics::OverlapRequest request;
vector<Physics::OverlapHit> results;
WorldRequestBus::BroadcastResult(results, &WorldRequests::Overlap, request);

Note
You can specify the maximum number of hits that can be collected from a Overlap query. You can specify the Overlap Query Buffer Size value in the PhysX Configuration window. For more information, see World Configuration.

OverlapRequest Properties

OverlapHit Properties