bevy_xpbd_3d/plugins/spatial_query/
query_filter.rs

1use bevy::{prelude::*, utils::HashSet};
2
3use crate::prelude::*;
4
5/// Rules that determine which colliders are taken into account in [spatial queries](crate::spatial_query).
6///
7/// ## Example
8///
9/// ```
10/// use bevy::prelude::*;
11#[cfg_attr(feature = "2d", doc = "use bevy_xpbd_2d::prelude::*;")]
12#[cfg_attr(feature = "3d", doc = "use bevy_xpbd_3d::prelude::*;")]
13///
14/// fn setup(mut commands: Commands) {
15#[cfg_attr(
16    feature = "2d",
17    doc = "    let object = commands.spawn(Collider::circle(0.5)).id();"
18)]
19#[cfg_attr(
20    feature = "3d",
21    doc = "    let object = commands.spawn(Collider::sphere(0.5)).id();"
22)]
23///
24///     // A query filter that has three collision layers and excludes the `object` entity
25///     let query_filter = SpatialQueryFilter::from_mask(0b1011).with_excluded_entities([object]);
26///
27///     // Spawn a ray caster with the query filter
28///     commands.spawn(RayCaster::default().with_query_filter(query_filter));
29/// }
30/// ```
31#[derive(Clone)]
32#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
33pub struct SpatialQueryFilter {
34    /// Specifies which [collision layers](CollisionLayers) will be included in the [spatial query](crate::spatial_query).
35    pub mask: LayerMask,
36    /// Entities that will not be included in [spatial queries](crate::spatial_query).
37    pub excluded_entities: HashSet<Entity>,
38}
39
40impl Default for SpatialQueryFilter {
41    fn default() -> Self {
42        Self {
43            mask: LayerMask::ALL,
44            excluded_entities: default(),
45        }
46    }
47}
48
49impl SpatialQueryFilter {
50    /// Creates a new [`SpatialQueryFilter`] with the given [`LayerMask`] determining
51    /// which [collision layers](CollisionLayers) will be included in the [spatial query](crate::spatial_query).
52    pub fn from_mask(mask: impl Into<LayerMask>) -> Self {
53        Self {
54            mask: mask.into(),
55            ..default()
56        }
57    }
58
59    /// Creates a new [`SpatialQueryFilter`] with the given entities excluded from the [spatial query](crate::spatial_query).
60    pub fn from_excluded_entities(entities: impl IntoIterator<Item = Entity>) -> Self {
61        Self {
62            excluded_entities: HashSet::from_iter(entities),
63            ..default()
64        }
65    }
66
67    /// Sets the [`LayerMask`] of the filter configuration. Only colliders with the corresponding
68    /// [collision layer memberships](CollisionLayers) will be included in the [spatial query](crate::spatial_query).
69    pub fn with_mask(mut self, masks: impl Into<LayerMask>) -> Self {
70        self.mask = masks.into();
71        self
72    }
73
74    /// Excludes the given entities from the [spatial query](crate::spatial_query).
75    pub fn with_excluded_entities(mut self, entities: impl IntoIterator<Item = Entity>) -> Self {
76        self.excluded_entities = HashSet::from_iter(entities);
77        self
78    }
79
80    /// Tests if an entity should be included in [spatial queries](crate::spatial_query) based on the
81    /// filter configuration.
82    pub fn test(&self, entity: Entity, layers: CollisionLayers) -> bool {
83        !self.excluded_entities.contains(&entity)
84            && CollisionLayers::new(LayerMask::ALL, self.mask)
85                .interacts_with(CollisionLayers::new(layers.memberships, LayerMask::ALL))
86    }
87}
bevy_xpbd_3d/plugins/spatial_query/query_filter.rs

bevy_xpbd_3d/plugins/spatial_query/
query_filter.rs
