Qt Quick 3D Physics Scene Queries

Scene queries allow applications to test spatial relationships and detect collisions programmatically within a PhysicsWorld. They enable mechanics such as line-of-sight checks, spatial probing, volume clearance testing, and interactive picking without relying on standard physical contact callbacks.

Types of Scene Queries

Qt Quick 3D Physics provides three main query modes, each optimized for different spatial operations:

Each query mode is split into three performance variants depending on the detail level required:

• Test Queries (testRaycastQuery, testSweepQuery, testOverlapQuery): Boolean checks that terminate immediately upon finding the first intersection. They return no detailed hit data, making them the fastest option for occlusion or clearance validation.
• Single Queries (singleRaycastQuery, singleSweepQuery): Return detailed information (locationHit, queryHit) for the closest intersecting body.
• Multi Queries (multiRaycastQuery, multiSweepQuery, multiOverlapQuery): Return a list of hit objects for all intersecting bodies along the query path or volume.

Query Mechanics and Key Nuances

When using scene queries, several system behaviors should be taken into consideration.

Bodies Excluded from Queries

Trigger bodies, such as TriggerBody, are not physical colliders and never appear in scene query results. Use an overlap query if you need the equivalent of a trigger volume that you can poll on demand.

Filter Groups Do Not Apply

The filterGroup and filterIgnoreGroups properties control which bodies collide with each other during simulation. They have no effect on scene queries: a query evaluates every collider matching its includeStatic and includeDynamic arguments, regardless of the filter groups involved. If a query needs to ignore specific bodies, filter the results after the query returns.

Query Shape Transforms

For Sweep and Overlap queries, the provided CollisionShape defines not only the geometry and scale, but also the starting position and orientation for the query. The shape's scene transform (including parent node transformations) is baked directly into the query execution.

Asynchronous Frame Timing and Latency

The physics simulation steps concurrently alongside QML scene graph rendering. Scene queries executed while a physics step is in flight reflect object positions, poses, and bounding structures from the last completed physics frame.

Consequently, queries triggered inside QML event handlers (such as onClicked or a Timer) operate on the state of the last completed step. That is the same state the scene's visual representation reflects, so a query result agrees with what is currently rendered; it does not account for motion occurring during the step being computed.

Triangle Mesh Multi-Hit Behavior

Multi-hit queries against complex triangle meshes or heightfield shapes yield a single intersection result per mesh object (the closest entry point). Individual triangles of a single mesh are not reported as separate hits.

Furthermore, rays or volume sweeps that originate from inside a mesh or exit through back-facing surface triangles will not report hits for that mesh.

Result Ordering in Multi-Queries

Hit objects returned by multi-queries (multiRaycastQuery, multiSweepQuery, multiOverlapQuery) are populated based on spatial tree traversal order. The results in the returned list are not guaranteed to be ordered by distance. If a distance-sorted list is required, applications should sort the resulting list explicitly.

Minimum Translation Distance (MTD) in Initial Overlaps

By default, sweep queries handle initial overlaps with existing colliders using Minimum Translation Distance (MTD). If a query shape already overlaps a body at its starting position, the hit result reports a negative distance (representing the penetration depth), along with the separation position and normal.

Character Controller Query Hits

When scene queries hit a CharacterController, the returned hit structure (queryHit, or locationHit) will contain a valid body, but its shape property will be null. This occurs because the underlying character proxy shape does not maintain individual shape metadata. Applications should check if shape is null before accessing shape-specific properties.

Filtering and Optimization Best Practices

To achieve optimal performance when using scene queries:

• Use Test Queries First: Use testRaycastQuery or testSweepQuery when you only need a true / false answer (e.g., AI visibility checks). They bypass allocation and computation of hit geometry.
• Filter Body Types: Constrain query searches using the includeStatic and includeDynamic parameters. If a raycast only needs to hit dynamic objects, setting includeStatic to false reduces traversal overhead.
• Limit Distance: Keep maxDistance as short as practical to minimize the number of candidate bounds evaluated by the spatial acceleration structures.

Example

The Qt Quick 3D Physics - Queries Example shows how to get physical bodies from the scene.