Menu
Lumberyard
User Guide (Version 1.14)

Raycast and Shape Cast Queries (Preview)

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 find out 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).

AZ Framework Physics API and the PhysX Gem

To create raycast and shape queries, you can use the generic physics API that the AZ framework provides. The following diagram shows the relationship between the AZ framework physics API and the PhysX gem that implements it.


        AZ framework and the PhysX gem

Creating Raycast and Shape Cast Queries

When creating raycast and shape cast queries, follow these guidelines:

  • To create a raycast query in C++, create a Physics::RayCastRequest object, assign values to its properties, and then pass it to the Physics::World::RayCast function.

    The query returns a Physics::RayCastResult object that contains an array of Physics::RayCastHit objects that have detailed information about each hit.

  • To create a shape cast query in C++, create a Physics::ShapeCastRequest object, assign values to its properties, and then pass it to the Physics::World::ShapeCast function.

    The query returns a Physics::ShapeCastResult object that contains an array of Physics::ShapeCastHit objects that have detailed information about each hit.

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

RayCastRequest Properties

Property Description
m_time The distance along the m_dir direction.
m_start The world space point where the ray starts.
m_dir The world space direction (normalized).
m_maxHits The maximum number of hits to be collected.
m_collisionFilter The collision filter for the raycast.

RayCastHit Properties

Property Description
m_hitTime

The distance along the cast at which the selection occurred.

m_position The position of the selection in world space.
m_normal The normal of the surface chosen.
m_entityId The ID of the AZ::Entity selected, or AZ::InvalidEntityId if the selected object is not an AZ::Entity.
m_hitBody World body that was selected.
m_hitShapeIdHierarchy The shape ID hierarchy of the selected body at the specified location.

ShapeCastRequest Properties

Property Description
m_start The world space start position. The value assumes rotation plus translation without scaling.
m_end The world space end position. Considers translation only if \ref m_nonLinear is true.
m_shapeConfiguration Contains shape configuration information.
m_maxHits The maximum number of hits to be collected.
m_collisionFilter The collision filter for the raycast.
m_nonLinear When true, performs translational and rotational nonlinear sweep.

ShapeCastHit Properties

Property Description
m_hitTime The normalized distance along the cast at which the selection occurred.
m_position The position of the selection in world space.
m_normal The normal of the surface chosen.
m_entityId The ID of the AZ::Entity selected, or AZ::InvalidEntityId if the selected object is not an AZ::Entity.
m_hitBody The world body that was selected.
m_shapeIdHierarchySelf The shape ID hierarchy of the casted body at the specified location.
m_shapeIdHierarchyHit The shape ID hierarchy of the selected body at the specified location.

RayCast and ShapeCast Interfaces

To perform raycasting and shape casting, use the following Physics::World interfaces.

Physics::World Interfaces

Interface Function Parameters Return value(s) Scriptable
World::RayCast const RayCastRequest& request, RayCastResult& result void No
World::ShapeCast const ShapeCastRequest& request, ShapeCastResult& result void No

The following code example creates a RayCastRequest object and uses it to perform a raycast in the defaultWorld physics world.

Physics::RayCastRequest request; request.m_origin = AZ::Vector3(-100.0f, 0.0f, 0.0f); request.m_dir = AZ::Vector3(1.0f, 0.0f, 0.0f); request.m_time = 200.0f; Physics::RayCastResult result; Physics::Ptr<Physics::World> defaultWorld = nullptr; EBUS_EVENT_RESULT(defaultWorld, Physics::SystemRequestBus, GetDefaultWorld); defaultWorld->RayCast(request, result); successResult &= (result.m_hits.size() != 0 && result.m_hits[0].m_entityId == sphereEntity->GetId());