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.

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

RayCastRequest Properties

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.

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

ShapeCastRequest Properties

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

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