Table of Contents

Scene queries allow you to specify a geometric object and perform a query if that object intersects or overlaps any physics object in the scene. Most queries also return detailed information about the intersection. All queries are performed through the global Physics interface, accessible through gPhysics().

Here is a short example of a basic query, to give you a better idea:

// Ray starting at origin, traveling towards negative Z

Vector3 origin(0, 0, 0);

Vector3 direction(0, 0, -1);

Ray ray(origin, direction);

PhysicsQueryHit hitInfo;

// Cast a ray into the scene and return information about first object hit

They all share a common interface, where as the first parameter they accept a shape with its starting position and orientation, travel direction, and finally an optional maximum range. They return an array of PhysicsQueryHit objects.

PhysicsQueryHit object contains information about each individual hit, and it contains:

Collider component that was hit

Position and normal of the contact point

Distance of the contact point from the query origin

Index of the triangle that was hit (if hit collider is a MeshCollider)

Barycentric coordinates of the triangle that was hit (if hit collider is a MeshCollider)

Closest hit casts

Closest hit casts are nearly identical to all hit casts, with the main difference is that they return a boolean value if a hit occurred or not, and output a single PhysicsQueryHit object. Hit information returned always concerns the closest found hit.

Checking for closest hit is cheaper than checking for them all, and is usually adequate for most applications. Relevant methods are:

They also share a common interface where as the first parameter they accept a shape with its starting position and orientation, travel direction, reference to a PhysicsQueryHit object to receive the results, and finally an optional maximum range. They return a boolean value that returns true if anything was hit.

// Axis aligned box centered at origin with extents 0.5 in all directions

Any overlap methods

This is a set of overlap methods that returns only a boolean value if the overlap occurred or not, without a list of colliders that are overlapping. This is cheaper than querying for all overlaps. The relevant methods are: