Revision control
++ // Copyright (C) 2026 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++ /*!
++ \example queries
++ \ingroup quick3dphysics-examples
++ \title Qt Quick 3D Physics - Queries Example
++ \examplecategory {3D}
++ \brief Demonstrates the scene query methods of PhysicsWorld.
++ \image queries-example.webp {Screenshot of the queries example}
++
++ Qt Quick 3D Physics provides a set of synchronous spatial query methods directly on
++ the \l PhysicsWorld node. These let you evaluate physical intersections, cast rays,
++ test volumetric paths, and find overlapping collision bodies on demand, without
++ waiting for a contact callback.
++
++ The example demonstrates all eight query methods in an interactive scene, split into
++ probes that push bodies around and scanners that only report whether the space ahead
++ is clear. Move with \c WASD, drag with the mouse to look, press \c {1} to \c {8} to
++ pick a query, and press \c Space to run it.
++
++ \section1 Overview of Query Types
++
++ Spatial queries are divided into three shape geometries and three operational modes:
++
++ \table
++ \header
++ \li Query Geometry
++ \li Test Mode (\c bool)
++ \li Single Hit Mode (\c locationHit)
++ \li Multi Hit Mode (\c {list<locationHit>})
++ \row
++ \li \b Raycast (Infinitesimal Line)
++ \li \c testRaycastQuery()
++ \li \c singleRaycastQuery()
++ \li \c multiRaycastQuery()
++ \row
++ \li \b Sweep (Volume Extrusion)
++ \li \c testSweepQuery()
++ \li \c singleSweepQuery()
++ \li \c multiSweepQuery()
++ \row
++ \li \b Overlap (Stationary Volume)
++ \li \c testOverlapQuery()
++ \li N/A
++ \li \c multiOverlapQuery()
++ \endtable
++
++ \section2 Key Query Parameters
++
++ All query methods share two filtering parameters:
++
++ \list
++ \li \c includeStatic (\c bool): Includes \l StaticRigidBody nodes in the query.
++ \li \c includeDynamic (\c bool): Includes \l DynamicRigidBody nodes in the query.
++ \endlist
++
++ \note At least one of \c includeStatic or \c includeDynamic must be \c true. If both
++ are \c false, the query returns \c false or an empty list immediately.
++
++ \section1 Understanding queryHit and locationHit
++
++ Overlap queries return \l queryHit, which carries the \c body and \c shape that were
++ hit. Raycast and sweep queries return \l locationHit, which adds the geometric fields:
++
++ \table
++ \header
++ \li Property
++ \li Type
++ \li Description
++ \row
++ \li \c body
++ \li \c PhysicsNode
++ \li The physics body hit by the query.
++ \row
++ \li \c position
++ \li \c vector3d
++ \li World-space coordinates of the exact collision impact point.
++ \row
++ \li \c normal
++ \li \c vector3d
++ \li Surface normal vector at the impact point (facing outward).
++ \row
++ \li \c distance
++ \li \c real
++ \li Distance along the query ray or sweep from the origin to the hit position.
++ \row
++ \li \c shape
++ \li \c CollisionShape
++ \li The specific collision shape that was hit.
++ \endtable
++
++ A query that hits nothing returns a hit whose \c body is \c null. Because every body
++ in the scene has an associated node, \c {hit.body === null} is the reliable test for a
++ miss; the \c distance of a missed hit is \c 0 and carries no meaning.
++
++ \section1 Setup in PhysicsWorld
++
++ To run queries you need a running \l PhysicsWorld. Volume-based queries, meaning sweeps
++ and overlaps, additionally need a \l CollisionShape to use as the query volume.
++
++ \snippet queries/main.qml physics-world-setup
++
++ A sweep or overlap query runs the shape at its current scene transform, so the shape's
++ position and rotation define where the query happens. The query shapes here have no
++ parent node, so the example assigns their \c position directly before each query.
++
++ The query shape must be a \l BoxShape, \l SphereShape, \l CapsuleShape or
++ \l ConvexMeshShape. See \l {Qt Quick 3D Physics Scene Queries} for the behavior that
++ all scene queries share, including how they treat trigger bodies and triangle meshes.
++
++ \section1 Raycast Queries
++
++ Raycast queries project an infinitely thin ray from an origin along a direction vector,
++ up to a maximum distance.
++
++ All three raycast modes in the example start from the same place. The player's own
++ collider is an ordinary hit candidate, so a ray starting at the player's center would
++ hit the player's own capsule at distance \c 0 before reaching anything else. To avoid
++ that, the example pushes the origin out in front of the player before casting:
++
++ \snippet queries/main.qml probe-origin
++
++ \section2 Single Raycast
++
++ \c singleRaycastQuery evaluates the line segment and returns the \e closest body hit.
++ The example uses it for a precise, instant probe: it casts along the player's facing
++ direction, draws a thin tracer out to whatever it hit (or to the full range on a miss),
++ and pushes the body it found.
++
++ \snippet queries/main.qml mode-single-raycast
++
++ Note that the impulse is only applied to a \l DynamicRigidBody. The query also returns
++ the static arena and the player's own character controller, neither of which can take
++ an impulse.
++
++ \section2 Multi Raycast
++
++ \c multiRaycastQuery pierces through geometry and returns \e all bodies along the ray
++ path, not just the nearest. The example uses it to push an entire column of bodies at
++ once, so the tracer always spans the full range.
++
++ \snippet queries/main.qml mode-multi-raycast
++
++ \note Results from multi-hit queries are \b unsorted. If you need depth order, sort the
++ returned list by \c hit.distance yourself.
++
++ \section2 Test Raycast
++
++ \c testRaycastQuery is a boolean line-of-sight check. It returns as soon as \e any
++ obstacle intersects the ray and never builds hit structures, which makes it the
++ cheapest of the three. The example runs it every frame as a scanner and colors the
++ tracer according to whether the path is clear.
++
++ \snippet queries/main.qml mode-test-raycast
++
++ \section1 Sweep Queries
++
++ Sweep queries cast a 3D volume (\l CollisionShape) along a direction vector, which is
++ what you want for thick projectiles, wide probes, or checking whether a character fits
++ through a gap.
++
++ \section2 Single Sweep
++
++ \c singleSweepQuery moves a shape along a vector and reports the first body it touches.
++ The example sweeps a \l SphereShape, so unlike the raycast it connects with anything
++ within the sphere's radius of the path rather than only what is exactly on the line.
++
++ \snippet queries/main.qml mode-single-sweep
++
++ \section2 Multi Sweep
++
++ \c multiSweepQuery sweeps a shape, here a \l BoxShape, and collects every body along
++ the path. The example renders the swept corridor as a translucent box so the volume
++ being tested is visible.
++
++ \snippet queries/main.qml mode-multi-sweep
++
++ \section2 Test Sweep
++
++ \c testSweepQuery reports whether a volumetric corridor is free of obstructions. The
++ example runs it every frame as a clearance scanner, casting the sphere ahead of the
++ player and coloring a ghost volume at the far end by the result.
++
++ \snippet queries/main.qml mode-test-sweep
++
++ \section1 Overlap Queries
++
++ Overlap queries evaluate a stationary region of space using a \l CollisionShape,
++ without extruding it along a path.
++
++ \section2 Multi Overlap
++
++ \c multiOverlapQuery returns all bodies currently inside or intersecting the query
++ volume. The example places a sphere some distance ahead of the player and pushes
++ everything inside it outward, using each body's position relative to the sphere's
++ center to compute a direction.
++
++ \snippet queries/main.qml mode-multi-overlap
++
++ \section2 Test Overlap
++
++ \c testOverlapQuery reports whether any body occupies the given volume. It returns as
++ soon as it finds one and builds no hit data, which makes it the cheapest of the overlap
++ queries. The example uses it as an occupancy check on the space ahead of the player,
++ the kind of test you would run before spawning something there.
++
++ \snippet queries/main.qml mode-test-overlap
++
++ \sa PhysicsWorld, {Qt Quick 3D Physics Scene Queries}
++ */