PhysX Scene Queries

You can use physics raycast queries to determine whether a specific line segment intersects physics geometry. Similarly a shapecast query (also known as a sweep) tests whether a shape extruded along a line segment intersects with physics geometry. Example uses for these queries might include determining whether an object is in front of another object, or testing a line of sight. Overlap queries are a third type of scene query, which determine whether a stationary shape intersects with other physics geometry. All these scene queries are performed on an AzPhysics::SceneInterface object and they all test against the entire scene. Note that as well as queries against entire scenes, it is also possible to perform a raycast against a single PhysX Simulated Body .

Each type of scene query can be performed using an AzPhysics::SceneQueryRequest object (there are specializations of the request object for each of the three scene query types). As well as performing a single query, it is possible to collect a batch of queries into a single call using an AzPhysics::SceneQueryRequests object, which is a container for many queries. It is also possible to call the request either synchronously or asynchronously.

virtual SceneQueryHits QueryScene(SceneHandle sceneHandle, const SceneQueryRequest* request) = 0;
virtual SceneQueryHitsList QuerySceneBatch(SceneHandle sceneHandle, const SceneQueryRequests& requests) = 0;
[[nodiscard]] virtual bool QuerySceneAsync(SceneHandle sceneHandle, SceneQuery::AsyncRequestId requestId,
    const SceneQueryRequest* request, SceneQuery::AsyncCallback callback) = 0;
[[nodiscard]] virtual bool QuerySceneAsyncBatch(SceneHandle sceneHandle, SceneQuery::AsyncRequestId requestId,
    const SceneQueryRequests& requests, SceneQuery::AsyncBatchCallback callback) = 0;

The results of scene queries are described using containers of AzPhysics::SceneQueryHit objects.

Note:
Scene queries can have a performance cost.

Raycast

Raycast queries are the most common scene query, based on firing a ray from a start position a specified distance along a ray direction.

Example The raycast query intersects the pentagon only.

Raycast query example in PhysX world.

A raycast query is specified using an AzPhysics::RayCastRequest.

RayCastRequest Properties

PropertyDescription
m_distanceMaximum distance along the ray to test for intersections.
m_startWorld space point where the ray starts.
m_directionDirection to cast the ray. This vector must be normalized.
m_hitFlagsFlags used to request particular hit fields to be returned, or indicate which hit fields are valid in a return value.
m_filterCallbackCustom callback function provided by the game to filter out specific objects.
m_reportMultipleHitsWhether to return all hits along the query (up to m_maxResults) or only return the first hit.
m_maxResultsThe maximum number of hits to return (limited by the Global Configuration ).
m_collisionGroupSpecifies which layers to test against. Use this to test only against specific layers.
m_queryTypeInclude either static objects, dynamic objects, or both.

To perform a raycast query, use the AzPhysics::SceneInterface.

Example (C++)

auto* sceneInterface = AZ::Interface<AzPhysics::SceneInterface>::Get();

AzPhysics::RayCastRequest request;
request.m_start = AZ::Vector3(-100.0f, 0.0f, 0.0f);
request.m_direction = AZ::Vector3(1.0f, 0.0f, 0.0f);
request.m_distance = 200.0f;

AzPhysics::SceneQueryHits result = sceneInterface->QueryScene(AzPhysics::DefaultPhysicsSceneName, &request);
auto numHits = result.size();

Example (Lua)

physicsSystem = GetPhysicsSystem()
sceneHandle = physicsSystem:GetSceneHandle(DefaultPhysicsSceneName)
scene = physicsSystem:GetScene(sceneHandle)
request = RayCastRequest()
request.Start = Vector3(5.0, 0.0, 5.0)
request.Direction = Vector3(0.0, 0.0, -1.0)
request.Distance = 10.0
request.ReportMultipleHits = true
hits = scene:QueryScene(request)
numHits = hits.HitArray:Size()

Script Canvas

The following nodes are available in Script Canvas:

  • Raycast (Local Space) Returns the first entity hit by a ray cast in local space from the source entity in the specified direction.
  • Raycast (World Space) Returns the first entity hit by a ray cast in world space from the start position in the specified direction.
  • Raycast Multiple (Local Space) Returns all entities hit by a ray cast in local space from the source entity in the specified direction.

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.

A raycast query is specified using an AzPhysics::ShapeCastRequest.

ShapeCastRequest Properties

PropertyDescription
m_distanceMaximum distance along m_direction to test.
m_startTransform in world space where the shape cast begins.
m_directionDirection to cast. The vector must be normalised.
m_hitFlagsFlags used to request particular hit fields to be returned, or indicate which hit fields are valid in a return value.
m_shapeConfigurationShape that should be swept along the ray.
m_filterCallbackCustom callback function provided by the game to filter out specific objects.
m_reportMultipleHitsWhether to return all hits along the query (up to m_maxResults) or only return the first hit.
m_maxResultsThe maximum number of hits to return (limited by the Global Configuration ).
m_collisionGroupSpecifies which layers to test against. Use this property to test only against specific layers.
m_queryTypeIncludes either static objects, dynamic objects, or both.

Box, capsule and sphere geometries are supported, and there are helper functions to create queries with those shapes in AzPhysics::ShapeCastRequestHelpers. Convex mesh geometries are also supported in C++, but not currently exposed to scripting.

To perform a shapecast query, use the AzPhysics::SceneInterface.

Example (C++)

auto* sceneInterface = AZ::Interface<AzPhysics::SceneInterface>::Get();

AzPhysics::ShapeCastRequest request = AzPhysics::ShapeCastRequestHelpers::CreateSphereCastRequest(1.0f,
    AZ::Transform::CreateTranslation(AZ::Vector3(-20.0f, 0.0f, 0.0f)),
    AZ::Vector3(1.0f, 0.0f, 0.0f),
    20.0f,
    AzPhysics::SceneQuery::QueryType::StaticAndDynamic,
    AzPhysics::CollisionGroup::All,
    nullptr);

AzPhysics::SceneQueryHits hits = sceneInterface->QueryScene(AzPhysics::DefaultPhysicsSceneName, &request);

Example (Lua)

physicsSystem = GetPhysicsSystem()
sceneHandle = physicsSystem:GetSceneHandle(DefaultPhysicsSceneName)
scene = physicsSystem:GetScene(sceneHandle)

boxDimensions = Vector3(1.0, 1.0, 1.0)
startPose = Transform.CreateTranslation(Vector3(0.0, 0.0, 5.0))
direction = Vector3(0.0, 0.0, -1.0)
distance = 10.0
queryType = 0
collisionGroup = CollisionGroup("All")
request = CreateBoxCastRequest(boxDimensions, startPose, direction, distance, queryType, collisionGroup)

hits = scene:QueryScene(request)

Script Canvas

The following nodes are available in Script Canvas:

  • Box Cast Returns the first entity hit by a shapecast query with box geometry.
  • Capsule Cast Returns the first entity hit by a shapecast query with capsule geometry.
  • Sphere Cast Returns the first entity hit by a shapecast query with sphere geometry.

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.

An overlap query is specified using an AzPhysics::OverlapRequest.

OverlapRequest Properties

PropertyDescription
m_poseTransform in world space of the shape.
m_shapeConfigurationShape to use for the overlap.
m_filterCallbackCustom callback function provided by the same to filter out specific entities.
m_unboundedOverlapHitCallbackAllows overlap queries to return unlimited results, processed via a callback.
m_maxResultsThe maximum number of hits to return (limited by the Global Configuration , and assuming m_unboundedOverlapHitCallback is not used ).
m_collisionGroupSpecifies which layers to test against. Use this property to test only against specific layers.
m_queryTypeIncludes either static objects, dynamic objects, or both.

Box, capsule and sphere geometries are supported, and there are helper functions to create queries with those shapes in AzPhysics::OverlapRequestHelpers. Convex mesh geometries are also supported in C++, but not currently exposed to scripting.

To perform an overlap query, use the AzPhysics::SceneInterface.

Example (C++)

auto* sceneInterface = AZ::Interface<AzPhysics::SceneInterface>::Get();

AzPhysics::OverlapRequest request = AzPhysics::OverlapRequestHelpers::CreateBoxOverlapRequest(AZ::Vector3(3.0f),
    AZ::Transform::CreateTranslation(AZ::Vector3(13.0f, 0.0f, 0.0f)));

AzPhysics::SceneQueryHits results = sceneInterface->QueryScene(AzPhysics::DefaultPhysicsSceneName, &request);

Example (Lua)

physicsSystem = GetPhysicsSystem()
sceneHandle = physicsSystem:GetSceneHandle(DefaultPhysicsSceneName)
scene = physicsSystem:GetScene(sceneHandle)

boxDimensions = Vector3(1.0, 1.0, 1.0)
pose = Transform.CreateTranslation(Vector3(0.0, 0.0, 5.0))
request = CreateBoxOverlapRequest(boxDimensions, pose)

hits = scene:QueryScene(request)

Script Canvas

The following nodes are available in Script Canvas:

  • Overlap Box Returns an array of Entity Ids which overlap with a box geometry.
  • Overlap Capsule Returns an array of Entity Ids which overlap with a capsule geometry.
  • Overlap Sphere Returns an array of Entity Ids which overlap with a sphere geometry.

SceneQueryHit

The results of scene queries are described using AzPhysics::SceneQueryHit objects. A single query may return multiple results, contained in an AzPhysics::SceneQueryHits object. The results of batch queries are described using an AzPhysics::SceneQueryHitsList object, which is a container of AzPhysics::SceneQueryHits objects.

SceneQueryHit Properties

PropertyDescription
m_resultFlagsFlags which indicate which of the below properties are valid.
m_distanceThe distance from the origin of the query to the hit (only valid for raycast and shapecast queries).
m_bodyHandleHandle to the AzPhysics::SimulatedBody which was hit.
m_entityIdThe Entity Id of the body which was hit.
m_shapeThe shape on the body which was hit.
m_materialThe material on the shape (or face) which was hit.
m_positionThe position of the hit in world space (only valid for raycast and shapecast queries).
m_normalThe normal in world space of the hit surface. (only valid for raycast and shapecast queries).

Copyright © 2022 Open 3D Engine Contributors

Documentation Distributed under CC BY 4.0.
For our trademark, privacy and antitrust policies, code of conduct, and terms of use, please click the applicable link below or see https://www.lfprojects.org.


The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Policy page.