Struct bevy_xpbd_3d::plugins::spatial_query::SpatialQuery

pub struct SpatialQuery<'w, 's> {
    pub query_pipeline: ResMut<'w, SpatialQueryPipeline>,
    /* private fields */
}

A system parameter for performing spatial queries.

Methods

• Raycasting: cast_ray, ray_hits, ray_hits_callback
• Shapecasting: cast_shape, shape_hits, shape_hits_callback
• Point projection: project_point
• Intersection tests
  • Point intersections: point_intersections, point_intersections_callback
  • AABB intersections: aabb_intersections_with_aabb, aabb_intersections_with_aabb_callback
  • Shape intersections: shape_intersections shape_intersections_callback

For simple raycasts and shapecasts, consider using the RayCaster and ShapeCaster components that provide a more ECS-based approach and perform casts on every frame.

Raycasting example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_hits(spatial_query: SpatialQuery) {
    // Cast ray and print first hit
    if let Some(first_hit) = spatial_query.cast_ray(
        Vec3::ZERO,                    // Origin
        Direction3d::X,                // Direction
        100.0,                         // Maximum time of impact (travel distance)
        true,                          // Does the ray treat colliders as "solid"
        SpatialQueryFilter::default(), // Query filter
    ) {
        println!("First hit: {:?}", first_hit);
    }

    // Cast ray and get up to 20 hits
    let hits = spatial_query.ray_hits(
        Vec3::ZERO,                    // Origin
        Direction3d::X,                // Direction
        100.0,                         // Maximum time of impact (travel distance)
        20,                            // Maximum number of hits
        true,                          // Does the ray treat colliders as "solid"
        SpatialQueryFilter::default(), // Query filter
    );

    // Print hits
    for hit in hits.iter() {
        println!("Hit: {:?}", hit);
    }
}

Fields

query_pipeline: ResMut<'w, SpatialQueryPipeline>

The SpatialQueryPipeline.

Implementations

impl<'w, 's> SpatialQuery<'w, 's>

pub fn update_pipeline(&mut self)

Updates the colliders in the pipeline. This is done automatically once per physics frame in PhysicsStepSet::SpatialQuery, but if you modify colliders or their positions before that, you can call this to make sure the data is up to date when performing spatial queries using SpatialQuery.

pub fn cast_ray( &self, origin: Vector, direction: Direction3d, max_time_of_impact: Scalar, solid: bool, query_filter: SpatialQueryFilter ) -> Option<RayHitData>

Casts a ray and computes the closest hit with a collider. If there are no hits, None is returned.

Arguments

• origin: Where the ray is cast from.
• direction: What direction the ray is cast in.
• max_time_of_impact: The maximum distance that the ray can travel.
• solid: If true and the ray origin is inside of a collider, the hit point will be the ray origin itself. Otherwise, the collider will be treated as hollow, and the hit point will be at the collider’s boundary.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_hits(spatial_query: SpatialQuery) {
    // Cast ray and print first hit
    if let Some(first_hit) = spatial_query.cast_ray(
        Vec3::ZERO,                    // Origin
        Direction3d::X,                // Direction
        100.0,                         // Maximum time of impact (travel distance)
        true,                          // Does the ray treat colliders as "solid"
        SpatialQueryFilter::default(), // Query filter
    ) {
        println!("First hit: {:?}", first_hit);
    }
}

pub fn cast_ray_predicate( &self, origin: Vector, direction: Direction3d, max_time_of_impact: Scalar, solid: bool, query_filter: SpatialQueryFilter, predicate: &dyn Fn(Entity) -> bool ) -> Option<RayHitData>

Casts a ray and computes the closest hit with a collider. If there are no hits, None is returned.

Arguments

• origin: Where the ray is cast from.
• direction: What direction the ray is cast in.
• max_time_of_impact: The maximum distance that the ray can travel.
• solid: If true and the ray origin is inside of a collider, the hit point will be the ray origin itself. Otherwise, the collider will be treated as hollow, and the hit point will be at the collider’s boundary.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.
• predicate: A function with which the colliders are filtered. Given the Entity it should return false, if the entity should be ignored.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

#[derive(Component)]
struct Invisible;

fn print_hits(spatial_query: SpatialQuery, query: Query<&Invisible>) {
    // Cast ray and print first hit
    if let Some(first_hit) = spatial_query.cast_ray_predicate(
        Vec3::ZERO,                    // Origin
        Direction3d::X,                // Direction
        100.0,                         // Maximum time of impact (travel distance)
        true,                          // Does the ray treat colliders as "solid"
        SpatialQueryFilter::default(), // Query filter
        &|entity| {                    // Predicate
            // Skip entities with the `Invisible` component.
            !query.contains(entity)
        }
    ) {
        println!("First hit: {:?}", first_hit);
    }
}

pub fn ray_hits( &self, origin: Vector, direction: Direction3d, max_time_of_impact: Scalar, max_hits: u32, solid: bool, query_filter: SpatialQueryFilter ) -> Vec<RayHitData>

Casts a ray and computes all hits until max_hits is reached.

Note that the order of the results is not guaranteed, and if there are more hits than max_hits, some hits will be missed.

Arguments

• origin: Where the ray is cast from.
• direction: What direction the ray is cast in.
• max_time_of_impact: The maximum distance that the ray can travel.
• max_hits: The maximum number of hits. Additional hits will be missed.
• solid: If true and the ray origin is inside of a collider, the hit point will be the ray origin itself. Otherwise, the collider will be treated as hollow, and the hit point will be at the collider’s boundary.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_hits(spatial_query: SpatialQuery) {
    // Cast ray and get hits
    let hits = spatial_query.ray_hits(
        Vec3::ZERO,                    // Origin
        Direction3d::X,                // Direction
        100.0,                         // Maximum time of impact (travel distance)
        20,                            // Maximum number of hits
        true,                          // Does the ray treat colliders as "solid"
        SpatialQueryFilter::default(), // Query filter
    );

    // Print hits
    for hit in hits.iter() {
        println!("Hit: {:?}", hit);
    }
}

pub fn ray_hits_callback( &self, origin: Vector, direction: Direction3d, max_time_of_impact: Scalar, solid: bool, query_filter: SpatialQueryFilter, callback: impl FnMut(RayHitData) -> bool )

Casts a ray and computes all hits, calling the given callback for each hit. The raycast stops when callback returns false or all hits have been found.

Note that the order of the results is not guaranteed.

Arguments

• origin: Where the ray is cast from.
• direction: What direction the ray is cast in.
• max_time_of_impact: The maximum distance that the ray can travel.
• solid: If true and the ray origin is inside of a collider, the hit point will be the ray origin itself. Otherwise, the collider will be treated as hollow, and the hit point will be at the collider’s boundary.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.
• callback: A callback function called for each hit.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_hits(spatial_query: SpatialQuery) {
    let mut hits = vec![];

    // Cast ray and get all hits
    spatial_query.ray_hits_callback(
        Vec3::ZERO,                    // Origin
        Direction3d::X,                // Direction
        100.0,                         // Maximum time of impact (travel distance)
        true,                          // Does the ray treat colliders as "solid"
        SpatialQueryFilter::default(), // Query filter
        |hit| {                        // Callback function
            hits.push(hit);
            true
        },
    );

    // Print hits
    for hit in hits.iter() {
        println!("Hit: {:?}", hit);
    }
}

pub fn cast_shape( &self, shape: &Collider, origin: Vector, shape_rotation: Quaternion, direction: Direction3d, max_time_of_impact: Scalar, ignore_origin_penetration: bool, query_filter: SpatialQueryFilter ) -> Option<ShapeHitData>

Casts a shape with a given rotation and computes the closest hit with a collider. If there are no hits, None is returned.

For a more ECS-based approach, consider using the ShapeCaster component instead.

Arguments

• shape: The shape being cast represented as a Collider.
• origin: Where the shape is cast from.
• shape_rotation: The rotation of the shape being cast.
• direction: What direction the shape is cast in.
• max_time_of_impact: The maximum distance that the shape can travel.
• ignore_origin_penetration: If true and the shape is already penetrating a collider at the shape origin, the hit will be ignored and only the next hit will be computed. Otherwise, the initial hit will be returned.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_hits(spatial_query: SpatialQuery) {
    // Cast ray and print first hit
    if let Some(first_hit) = spatial_query.cast_shape(
        &Collider::sphere(0.5),          // Shape
        Vec3::ZERO,                      // Origin
        Quat::default(),                 // Shape rotation
        Direction3d::X,                  // Direction
        100.0,                           // Maximum time of impact (travel distance)
        true,                            // Should initial penetration at the origin be ignored
        SpatialQueryFilter::default(),   // Query filter
    ) {
        println!("First hit: {:?}", first_hit);
    }
}

pub fn shape_hits( &self, shape: &Collider, origin: Vector, shape_rotation: Quaternion, direction: Direction3d, max_time_of_impact: Scalar, max_hits: u32, ignore_origin_penetration: bool, query_filter: SpatialQueryFilter ) -> Vec<ShapeHitData>

Casts a shape with a given rotation and computes computes all hits in the order of the time of impact until max_hits is reached.

Arguments

• shape: The shape being cast represented as a Collider.
• origin: Where the shape is cast from.
• shape_rotation: The rotation of the shape being cast.
• direction: What direction the shape is cast in.
• max_time_of_impact: The maximum distance that the shape can travel.
• max_hits: The maximum number of hits. Additional hits will be missed.
• ignore_origin_penetration: If true and the shape is already penetrating a collider at the shape origin, the hit will be ignored and only the next hit will be computed. Otherwise, the initial hit will be returned.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.
• callback: A callback function called for each hit.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_hits(spatial_query: SpatialQuery) {
    // Cast shape and get all hits
    let hits = spatial_query.shape_hits(
        &Collider::sphere(0.5),          // Shape
        Vec3::ZERO,                      // Origin
        Quat::default(),                 // Shape rotation
        Direction3d::X,                  // Direction
        100.0,                           // Maximum time of impact (travel distance)
        20,                              // Max hits
        true,                            // Should initial penetration at the origin be ignored
        SpatialQueryFilter::default(),   // Query filter
    );

    // Print hits
    for hit in hits.iter() {
        println!("Hit: {:?}", hit);
    }
}

pub fn shape_hits_callback( &self, shape: &Collider, origin: Vector, shape_rotation: Quaternion, direction: Direction3d, max_time_of_impact: Scalar, ignore_origin_penetration: bool, query_filter: SpatialQueryFilter, callback: impl FnMut(ShapeHitData) -> bool )

Casts a shape with a given rotation and computes computes all hits in the order of the time of impact, calling the given callback for each hit. The shapecast stops when callback returns false or all hits have been found.

Arguments

• shape: The shape being cast represented as a Collider.
• origin: Where the shape is cast from.
• shape_rotation: The rotation of the shape being cast.
• direction: What direction the shape is cast in.
• max_time_of_impact: The maximum distance that the shape can travel.
• ignore_origin_penetration: If true and the shape is already penetrating a collider at the shape origin, the hit will be ignored and only the next hit will be computed. Otherwise, the initial hit will be returned.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.
• callback: A callback function called for each hit.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_hits(spatial_query: SpatialQuery) {
    let mut hits = vec![];

    // Cast shape and get all hits
    spatial_query.shape_hits_callback(
        &Collider::sphere(0.5),          // Shape
        Vec3::ZERO,                      // Origin
        Quat::default(),                 // Shape rotation
        Direction3d::X,                  // Direction
        100.0,                           // Maximum time of impact (travel distance)
        true,                            // Should initial penetration at the origin be ignored
        SpatialQueryFilter::default(),   // Query filter
        |hit| {                          // Callback function
            hits.push(hit);
            true
        },
    );

    // Print hits
    for hit in hits.iter() {
        println!("Hit: {:?}", hit);
    }
}

pub fn project_point( &self, point: Vector, solid: bool, query_filter: SpatialQueryFilter ) -> Option<PointProjection>

Finds the projection of a given point on the closest collider. If one isn’t found, None is returned.

Arguments

• point: The point that should be projected.
• solid: If true and the point is inside of a collider, the projection will be at the point. Otherwise, the collider will be treated as hollow, and the projection will be at the collider’s boundary.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_point_projection(spatial_query: SpatialQuery) {
    // Project a point and print the result
    if let Some(projection) = spatial_query.project_point(
        Vec3::ZERO,                    // Point
        true,                          // Are colliders treated as "solid"
        SpatialQueryFilter::default(), // Query filter
    ) {
        println!("Projection: {:?}", projection);
    }
}

pub fn point_intersections( &self, point: Vector, query_filter: SpatialQueryFilter ) -> Vec<Entity>

An intersection test that finds all entities with a collider that contains the given point.

Arguments

• point: The point that intersections are tested against.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_point_intersections(spatial_query: SpatialQuery) {
    let intersections =
        spatial_query.point_intersections(Vec3::ZERO, SpatialQueryFilter::default());

    for entity in intersections.iter() {
        println!("Entity: {:?}", entity);
    }
}

pub fn point_intersections_callback( &self, point: Vector, query_filter: SpatialQueryFilter, callback: impl FnMut(Entity) -> bool )

An intersection test that finds all entities with a collider that contains the given point, calling the given callback for each intersection. The search stops when callback returns false or all intersections have been found.

Arguments

• point: The point that intersections are tested against.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.
• callback: A callback function called for each intersection.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_point_intersections(spatial_query: SpatialQuery) {
    let mut intersections = vec![];
     
    spatial_query.point_intersections_callback(
        Vec3::ZERO,                     // Point
        SpatialQueryFilter::default(),  // Query filter
        |entity| {                      // Callback function
            intersections.push(entity);
            true
        },
    );

    for entity in intersections.iter() {
        println!("Entity: {:?}", entity);
    }
}

pub fn aabb_intersections_with_aabb(&self, aabb: ColliderAabb) -> Vec<Entity>

An intersection test that finds all entities with a ColliderAabb that is intersecting the given aabb.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_aabb_intersections(spatial_query: SpatialQuery) {
    let aabb = Collider::sphere(0.5).aabb(Vec3::ZERO, Quat::default());
    let intersections = spatial_query.aabb_intersections_with_aabb(aabb);

    for entity in intersections.iter() {
        println!("Entity: {:?}", entity);
    }
}

pub fn aabb_intersections_with_aabb_callback( &self, aabb: ColliderAabb, callback: impl FnMut(Entity) -> bool )

An intersection test that finds all entities with a ColliderAabb that is intersecting the given aabb, calling callback for each intersection. The search stops when callback returns false or all intersections have been found.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_aabb_intersections(spatial_query: SpatialQuery) {
    let mut intersections = vec![];

    spatial_query.aabb_intersections_with_aabb_callback(
        Collider::sphere(0.5).compute_aabb(Vec3::ZERO, Quat::default()),
        |entity| {
            intersections.push(entity);
            true
        }
    );

    for entity in intersections.iter() {
        println!("Entity: {:?}", entity);
    }
}

pub fn shape_intersections( &self, shape: &Collider, shape_position: Vector, shape_rotation: Quaternion, query_filter: SpatialQueryFilter ) -> Vec<Entity>

An intersection test that finds all entities with a Collider that is intersecting the given shape with a given position and rotation.

Arguments

• shape: The shape that intersections are tested against represented as a Collider.
• shape_position: The position of the shape.
• shape_rotation: The rotation of the shape.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_shape_intersections(spatial_query: SpatialQuery) {
    let intersections = spatial_query.shape_intersections(
        &Collider::sphere(0.5),          // Shape
        Vec3::ZERO,                      // Shape position
        Quat::default(),                 // Shape rotation
        SpatialQueryFilter::default(),   // Query filter
    );

    for entity in intersections.iter() {
        println!("Entity: {:?}", entity);
    }
}

pub fn shape_intersections_callback( &self, shape: &Collider, shape_position: Vector, shape_rotation: Quaternion, query_filter: SpatialQueryFilter, callback: impl FnMut(Entity) -> bool )

An intersection test that finds all entities with a Collider that is intersecting the given shape with a given position and rotation, calling callback for each intersection. The search stops when callback returns false or all intersections have been found.

Arguments

• shape: The shape that intersections are tested against represented as a Collider.
• shape_position: The position of the shape.
• shape_rotation: The rotation of the shape.
• query_filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.
• callback: A callback function called for each intersection.

Example

use bevy::prelude::*;
use bevy_xpbd_3d::prelude::*;

fn print_shape_intersections(spatial_query: SpatialQuery) {
    let mut intersections = vec![];

    spatial_query.shape_intersections_callback(
        &Collider::sphere(0.5),          // Shape
        Vec3::ZERO,                      // Shape position
        Quat::default(),                 // Shape rotation
        SpatialQueryFilter::default(),   // Query filter
        |entity| {                       // Callback function
            intersections.push(entity);
            true
        },
    );

    for entity in intersections.iter() {
        println!("Entity: {:?}", entity);
    }
}

Trait Implementations

impl SystemParam for SpatialQuery<'_, '_>

type State = FetchState

Used to store data which persists across invocations of a system.

type Item<'w, 's> = SpatialQuery<'w, 's>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

Registers any [World] access used by this [SystemParam] and creates a new instance of this param’s State.

fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta )

For the specified [Archetype], registers the components accessed by this [SystemParam] (if applicable).

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this [SystemParam]’s state. This is used to apply Commands during apply_deferred.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for SpatialQuery<'w, 's>

where Query<'w, 's, (Entity, &'static Position, &'static Rotation, &'static Collider, Option<&'static CollisionLayers>)>: ReadOnlySystemParam, Query<'w, 's, Entity, Added<Collider>>: ReadOnlySystemParam, ResMut<'w, SpatialQueryPipeline>: ReadOnlySystemParam,