avian3d/spatial_query/
query_filter.rs

1use bevy::{ecs::entity::hash_set::EntityHashSet, prelude::*};
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#[cfg_attr(feature = "2d", doc = "use avian2d::prelude::*;")]
11#[cfg_attr(feature = "3d", doc = "use avian3d::prelude::*;")]
12/// use bevy::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, Debug, PartialEq, Reflect)]
32#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
33#[cfg_attr(feature = "serialize", reflect(Serialize, Deserialize))]
34#[reflect(Debug, PartialEq)]
35pub struct SpatialQueryFilter {
36    /// Specifies which [collision layers](CollisionLayers) will be included in the [spatial query](crate::spatial_query).
37    pub mask: LayerMask,
38    /// Entities that will not be included in [spatial queries](crate::spatial_query).
39    pub excluded_entities: EntityHashSet,
40}
41
42impl Default for SpatialQueryFilter {
43    fn default() -> Self {
44        Self::DEFAULT
45    }
46}
47
48impl SpatialQueryFilter {
49    /// The default [`SpatialQueryFilter`] configuration that includes all collision layers
50    /// and has no excluded entities.
51    pub const DEFAULT: Self = Self {
52        mask: LayerMask::ALL,
53        excluded_entities: EntityHashSet::new(),
54    };
55
56    /// Creates a new [`SpatialQueryFilter`] with the given [`LayerMask`] determining
57    /// which [collision layers] will be included in the [spatial query].
58    ///
59    /// [collision layers]: CollisionLayers
60    /// [spatial query]: crate::spatial_query
61    pub fn from_mask(mask: impl Into<LayerMask>) -> Self {
62        Self {
63            mask: mask.into(),
64            ..default()
65        }
66    }
67
68    /// Creates a new [`SpatialQueryFilter`] with the given entities excluded from the [spatial query].
69    ///
70    /// [spatial query]: crate::spatial_query
71    pub fn from_excluded_entities(entities: impl IntoIterator<Item = Entity>) -> Self {
72        Self {
73            excluded_entities: EntityHashSet::from_iter(entities),
74            ..default()
75        }
76    }
77
78    /// Sets the [`LayerMask`] of the filter configuration. Only colliders with the corresponding
79    /// [collision layer memberships] will be included in the [spatial query].
80    ///
81    /// [collision layer memberships]: CollisionLayers
82    /// [spatial query]: crate::spatial_query
83    pub fn with_mask(mut self, masks: impl Into<LayerMask>) -> Self {
84        self.mask = masks.into();
85        self
86    }
87
88    /// Excludes the given entities from the [spatial query](crate::spatial_query).
89    pub fn with_excluded_entities(mut self, entities: impl IntoIterator<Item = Entity>) -> Self {
90        self.excluded_entities = EntityHashSet::from_iter(entities);
91        self
92    }
93
94    /// Tests if an entity should be included in [spatial queries] based on the filter configuration.
95    ///
96    /// [spatial queries]: crate::spatial_query
97    pub fn test(&self, entity: Entity, layers: CollisionLayers) -> bool {
98        !self.excluded_entities.contains(&entity)
99            && CollisionLayers::new(LayerMask::ALL, self.mask)
100                .interacts_with(CollisionLayers::new(layers.memberships, LayerMask::ALL))
101    }
102}
avian3d/spatial_query/query_filter.rs

avian3d/spatial_query/
query_filter.rs
