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}
+ */