Lumberyard
User Guide (Version 1.21)

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.

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.


                        Raycast query example in PhysX world.

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

Property Description

m_distance

Maximum distance along the ray to test for intersections.

m_start

World space point where the ray starts.

m_direction

Direction to cast the ray. This vector must be normalised.

m_collisionGroup

Specifies which layers to test against. Use this to test only against specific layers.

m_filterCallback

Custom callback function provided by the game to filter our specific objects.

m_queryType

Include either static, dynamic objects, or both.

RayCastHit Properties

Property Description
m_distance

Distance along the ray at which the hit was found.

m_position

Position in world space of the hit.

m_normal

Normal in world space of the hit surface.

m_body

Body that was hit.

m_shape

Shape on the body that was hit.

m_material

Shape on the body that was hit.

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.


                        Shapecast query example in PhysX.

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

Property Description
m_distance

Maximum distance along m_direction to test.

m_start

Transform in world space where the shape cast begins.

m_direction

Direction to cast. The vector must be normalised.

m_shapeConfiguration

Shape that should be swept along the ray.

m_collisionGroup

Specifies which layers to test against. Use this property to test only against specific layers.

m_filterCallback

Custom callback function provided by the game to filter out specific objects.

m_queryType

Includes static, dynamic, or both.

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.


                        Overlap query example in PhysX.

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

Property Description
m_pose

Transform in world space of the shape.

m_shapeConfiguration

Shape to use for the overlap.

m_collisionGroup

Specifies which layers to test against. Use this to test only against specific layers.

m_filterCallback

Custom callback function provided by the same to filter out specific entities.

m_queryType

Includes static, dynamic, or both.

OverlapHit Properties

Property Description

m_body

Body that was hit.

m_shape

Shape on the body that was hit.

m_material

Material on the shape that was hit.

On this page: