Struct QueryPipeline 

pub struct QueryPipeline<'a> {
    pub dispatcher: &'a dyn QueryDispatcher,
    pub bvh: &'a Bvh,
    pub bodies: &'a RigidBodySet,
    pub colliders: &'a ColliderSet,
    pub filter: QueryFilter<'a>,
}

A query system for performing spatial queries on your physics world (raycasts, shape casts, intersections).

Think of this as a “search engine” for your physics world. Use it to answer questions like:

• “What does this ray hit?”
• “What colliders are near this point?”
• “If I move this shape, what will it collide with?”

Get a QueryPipeline from your BroadPhaseBvh using as_query_pipeline().

Example

let query_pipeline = broad_phase.as_query_pipeline(
    narrow_phase.query_dispatcher(),
    &bodies,
    &colliders,
    QueryFilter::default()
);

// Cast a ray downward
let ray = Ray::new(Vector::new(0.0, 10.0, 0.0), Vector::new(0.0, -1.0, 0.0));
if let Some((handle, toi)) = query_pipeline.cast_ray(&ray, Real::MAX, false) {
    println!("Hit collider {:?} at distance {}", handle, toi);
}

Fields

dispatcher: &'a dyn QueryDispatcher

The query dispatcher for running geometric queries on leaf geometries.

bvh: &'a Bvh

A bvh containing collider indices at its leaves.

bodies: &'a RigidBodySet

Rigid-bodies potentially involved in the scene queries.

colliders: &'a ColliderSet

Colliders potentially involved in the scene queries.

filter: QueryFilter<'a>

The query filters for controlling what colliders should be ignored by the queries.

Implementations

impl<'a> QueryPipeline<'a>

pub fn with_filter(self, filter: QueryFilter<'a>) -> Self

Replaces Self::filter with different filtering rules.

pub fn cast_ray( &self, ray: &Ray, max_toi: f32, solid: bool, ) -> Option<(ColliderHandle, f32)>

Casts a ray through the world and returns the first collider it hits.

This is one of the most common operations - use it for line-of-sight checks, projectile trajectories, mouse picking, laser beams, etc.

Returns Some((handle, distance)) if the ray hits something, where:

• handle is which collider was hit
• distance is how far along the ray the hit occurred (time-of-impact)

Parameters

• ray - The ray to cast (origin + direction). Create with Ray::new(origin, direction)
• max_toi - Maximum distance to check. Use Real::MAX for unlimited range
• solid - If true, detects hits even if the ray starts inside a shape. If false, the ray “passes through” from the inside until it exits

Example

// Raycast downward from (0, 10, 0)
let ray = Ray::new(Vector::new(0.0, 10.0, 0.0), Vector::new(0.0, -1.0, 0.0));
if let Some((handle, toi)) = query_pipeline.cast_ray(&ray, Real::MAX, true) {
    let hit_point = ray.origin + ray.dir * toi;
    println!("Hit at {:?}, distance = {}", hit_point, toi);
}

pub fn cast_ray_and_get_normal( &self, ray: &Ray, max_toi: f32, solid: bool, ) -> Option<(ColliderHandle, RayIntersection)>

Casts a ray and returns detailed information about the hit (including surface normal).

Like cast_ray(), but returns more information useful for things like:

• Decals (need surface normal to orient the texture)
• Bullet holes (need to know what part of the mesh was hit)
• Ricochets (need normal to calculate bounce direction)

Returns Some((handle, intersection)) where intersection contains:

• toi: Distance to impact
• normal: Surface normal at the hit point
• feature: Which geometric feature was hit (vertex, edge, face)

Example

if let Some((handle, hit)) = query_pipeline.cast_ray_and_get_normal(&ray, 100.0, true) {
    println!("Hit at distance {}, surface normal: {:?}", hit.time_of_impact, hit.normal);
}

pub fn intersect_ray( &'a self, ray: Ray, max_toi: f32, solid: bool, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider, RayIntersection)> + 'a

Returns ALL colliders that a ray passes through (not just the first).

Unlike cast_ray() which stops at the first hit, this returns every collider along the ray’s path. Useful for:

• Penetrating weapons that go through multiple objects
• Checking what’s in a line (e.g., visibility through glass)
• Counting how many objects are between two points

Returns an iterator of (handle, collider, intersection) tuples.

Example

for (handle, collider, hit) in query_pipeline.intersect_ray(ray, 100.0, true) {
    println!("Ray passed through {:?} at distance {}", handle, hit.time_of_impact);
}

pub fn project_point( &self, point: Vector, max_dist: f32, solid: bool, ) -> Option<(ColliderHandle, PointProjection)>

Finds the closest point on any collider to the given point.

Returns the collider and information about where on its surface the closest point is. Useful for:

• Finding nearest cover/obstacle
• Snap-to-surface mechanics
• Distance queries

Parameters

• solid - If true, a point inside a shape projects to itself. If false, it projects to the nearest point on the shape’s boundary

Example

let point = Vector::new(5.0, 0.0, 0.0);
if let Some((handle, projection)) = query_pipeline.project_point(point, std::f32::MAX, true) {
    println!("Closest collider: {:?}", handle);
    println!("Closest point: {:?}", projection.point);
    println!("Distance: {}", (point - projection.point).length());
}

pub fn intersect_point( &'a self, point: Vector, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider)> + 'a

Returns ALL colliders that contain the given point.

A point is “inside” a collider if it’s within its volume. Useful for:

• Detecting what area/trigger zones a point is in
• Checking if a position is inside geometry
• Finding all overlapping volumes at a location

Example

let point = Vector::new(0.0, 0.0, 0.0);
for (handle, collider) in query_pipeline.intersect_point(point) {
    println!("Point is inside {:?}", handle);
}

pub fn project_point_and_get_feature( &self, point: Vector, max_dist: f32, ) -> Option<(ColliderHandle, PointProjection, FeatureId)>

Find the projection of a point on the closest collider.

The results include the ID of the feature hit by the point.

Parameters

• point - The point to project.

pub fn intersect_aabb_conservative( &'a self, aabb: Aabb, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider)> + 'a

Finds all handles of all the colliders with an Aabb intersecting the given Aabb.

Note that the collider AABB taken into account is the one currently stored in the query pipeline’s BVH. It doesn’t recompute the latest collider AABB.

pub fn cast_shape( &self, shape_pos: &Pose, shape_vel: Vector, shape: &dyn Shape, options: ShapeCastOptions, ) -> Option<(ColliderHandle, ShapeCastHit)>

Sweeps a shape through the world to find what it would collide with.

Like raycasting, but instead of a thin ray, you’re moving an entire shape (sphere, box, etc.) through space. This is also called “shape casting” or “sweep testing”. Useful for:

• Predicting where a moving object will hit something
• Checking if a movement is valid before executing it
• Thick raycasts (e.g., character controller collision prediction)
• Area-of-effect scanning along a path

Returns the first collision: (collider_handle, hit_details) where hit contains time-of-impact, witness points, and surface normal.

In the returned ShapeCastHit, witness1 and normal1 refer to the hit collider and are expressed in world space. witness2 and normal2 refer to the cast shape and are expressed in its local space (relative to shape_pos).

Parameters

• shape_pos - Starting position/orientation of the shape
• shape_vel - Direction and speed to move the shape (velocity vector)
• shape - The shape to sweep (ball, cuboid, capsule, etc.)
• options - Maximum distance, collision filtering, etc.

Example

// Sweep a sphere downward
let shape = Ball::new(0.5);
let start_pos = Pose::translation(0.0, 10.0, 0.0);
let velocity = Vector::new(0.0, -1.0, 0.0);
let options = ShapeCastOptions::default();

if let Some((handle, hit)) = query_pipeline.cast_shape(&start_pos, velocity, &shape, options) {
    println!("Shape would hit {:?} at time {}", handle, hit.time_of_impact);
}

pub fn cast_shape_nonlinear( &self, shape_motion: &NonlinearRigidMotion, shape: &dyn Shape, start_time: f32, end_time: f32, stop_at_penetration: bool, ) -> Option<(ColliderHandle, ShapeCastHit)>

Casts a shape with an arbitrary continuous motion and retrieve the first collider it hits.

In the returned ShapeCastHit, witness1 and normal1 refer to the hit collider and are expressed in world space. witness2 and normal2 refer to the cast shape and are expressed in its local space (they follow the shape along shape_motion).

Parameters

• shape_motion - The motion of the shape.
• shape - The shape to cast.
• start_time - The starting time of the interval where the motion takes place.
• end_time - The end time of the interval where the motion takes place.
• stop_at_penetration - If the casted shape starts in a penetration state with any collider, two results are possible. If stop_at_penetration is true then, the result will have a toi equal to start_time. If stop_at_penetration is false then the nonlinear shape-casting will see if further motion with respect to the penetration normal would result in tunnelling. If it does not (i.e. we have a separating velocity along that normal) then the nonlinear shape-casting will attempt to find another impact, at a time > start_time that could result in tunnelling.

pub fn intersect_shape( &'a self, shape_pos: Pose, shape: &'a dyn Shape, ) -> impl Iterator<Item = (ColliderHandle, &'a Collider)> + 'a

Retrieve all the colliders intersecting the given shape.

Parameters

• shapePos - The pose of the shape to test.
• shape - The shape to test.

Trait Implementations

impl<'a> Clone for QueryPipeline<'a>

fn clone(&self) -> QueryPipeline<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CompositeShape for QueryPipeline<'_>

fn map_part_at( &self, shape_id: u32, f: &mut dyn FnMut(Option<&Pose>, &dyn Shape, Option<&dyn NormalConstraints>), )

Applies a function to one sub-shape of this composite shape.

fn bvh(&self) -> &Bvh

Gets the acceleration structure of the composite shape.

impl<'a> Copy for QueryPipeline<'a>

impl TypedCompositeShape for QueryPipeline<'_>

type PartNormalConstraints = ()

type PartShape = dyn Shape

fn map_typed_part_at<T>( &self, shape_id: u32, f: impl FnMut(Option<&Pose>, &Self::PartShape, Option<&Self::PartNormalConstraints>) -> T, ) -> Option<T>

fn map_untyped_part_at<T>( &self, shape_id: u32, f: impl FnMut(Option<&Pose>, &dyn Shape, Option<&dyn NormalConstraints>) -> T, ) -> Option<T>