Add DefaultQueryFilters

crates/bevy_ecs/src/query/access.rs

@@ -508,6 +508,16 @@ impl<T: SparseSetIndex> FilteredAccess<T> {
             .iter()
             .flat_map(|f| f.without.ones().map(T::get_sparse_set_index))
     }
+
+    /// Returns true if the index is used by this `FilteredAccess` in any way
+    pub fn contains(&self, index: T) -> bool {
+        self.access().has_read(index.clone())
+            || self.access().has_archetypal(index.clone())
+            || self.filter_sets.iter().any(|f| {
+                f.with.contains(index.sparse_set_index())
+                    || f.without.contains(index.sparse_set_index())
+            })
+    }
 }
 
 #[derive(Clone, Eq, PartialEq)]

crates/bevy_ecs/src/query/default_filters.rs

@@ -0,0 +1,191 @@
+use crate as bevy_ecs;
+use crate::{component::ComponentId, query::FilteredAccess};
+use bevy_ecs_macros::Resource;
+use bevy_utils::HashMap;
+
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+#[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))]
+enum FilterKind {
+    With,
+    Without,
+}
+
+/// A list of default query filters, these can be used to globally exclude entities from queries.
+/// Default filters are applied to any queries that does not explicitly mention that component.
+///
+/// If for example we register a `Hidden` component using the `without_untyped` method, entities
+/// with this component will only be visible to a [`Query`](crate::prelude::Query) containing
+/// something like [`With<Hidden>`](crate::prelude::With) or [`Has<Hidden>`](crate::prelude::Has).
+/// See below for a more detailed example.
+///
+/// These filters are only applied to queries whose cache is generated after updating this resource,
+/// As a result, this resource should generally only be modified before the app starts (typically
+/// during plugin construction)
+///
+/// See `World::default_with_filter` and `World::default_without_filter` for easier access
+///
+/// ### Example
+///
+/// ```rust
+/// # use bevy_ecs::{prelude::*, query::DefaultQueryFilters};
+/// # #[derive(Component)]
+/// # struct Enabled;
+/// # #[derive(Component)]
+/// # struct TopSecret;
+/// #
+/// let mut world = World::new();
+/// let mut filters = DefaultQueryFilters::default();
+/// filters.with_untyped(world.init_component::<Enabled>());
+/// filters.without_untyped(world.init_component::<TopSecret>());
+/// world.insert_resource(filters);
+///
+/// // This entity is missing Enabled, so most queries won't see it
+/// let entity_a = world.spawn_empty().id();
+///
+/// // This entity has Enabled, and isn't TopSecret, so most queries see it
+/// let entity_b = world.spawn(Enabled).id();
+///
+/// // This entity is Enabled and TopSecret, so most queries won't see it
+/// let entity_c = world.spawn((Enabled, TopSecret)).id();
+///
+/// // This entity is TopSecret but not enabled, so only very specific queries will see it
+/// let entity_d = world.spawn(TopSecret).id();
+///
+/// // This query does not mention either of the markers, so it only gets entity_b
+/// let mut query = world.query::<Entity>();
+/// assert_eq!(1, query.iter(&world).count());
+/// assert_eq!(entity_b, query.get_single(&world).unwrap());
+///
+/// // This query only wants entities that aren't Enabled, but can't see TopSecret entities,
+/// // thus it only sees entity_a
+/// let mut query = world.query_filtered::<Entity, Without<Enabled>>();
+/// assert_eq!(1, query.iter(&world).count());
+/// assert_eq!(entity_a, query.get_single(&world).unwrap());
+///
+/// // This query only wants TopSecret entities, but still can't see entities that aren't Enabled,
+/// // thus it only sees entity_c
+/// let mut query = world.query_filtered::<Entity, With<TopSecret>>();
+/// assert_eq!(1, query.iter(&world).count());
+/// assert_eq!(entity_c, query.get_single(&world).unwrap());
+///
+/// // This query mentions both, so it gets results as if the filters don't exist
+/// let mut query = world.query::<(Entity, Has<Enabled>, Has<TopSecret>)>();
+/// assert_eq!(4, query.iter(&world).count());
+/// ```
+#[derive(Resource, Default, Debug)]
+#[cfg_attr(feature = "bevy_reflect", derive(bevy_reflect::Reflect))]
+pub struct DefaultQueryFilters(HashMap<ComponentId, FilterKind>);
+
+impl DefaultQueryFilters {
+    /// Add a With filter to the default query filters.
+    /// Removes any Without filter for this component if present.
+    pub fn with_untyped(&mut self, component_id: ComponentId) {
+        self.0.insert(component_id, FilterKind::With);
+    }
+
+    /// Add a Without filter to the default query filters.
+    /// Removes any With filter for this component if present.
+    pub fn without_untyped(&mut self, component_id: ComponentId) {
+        self.0.insert(component_id, FilterKind::Without);
+    }
+
+    /// Remove a filter for the specified [`ComponentId`]
+    pub fn remove(&mut self, component_id: ComponentId) {
+        self.0.remove(&component_id);
+    }
+
+    pub(super) fn apply(&self, component_access: &mut FilteredAccess<ComponentId>) {
+        for (&component_id, kind) in self.0.iter() {
+            if !component_access.contains(component_id) {
+                match kind {
+                    FilterKind::With => component_access.and_with(component_id),
+                    FilterKind::Without => component_access.and_without(component_id),
+                }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_set_filters() {
+        let mut filters = DefaultQueryFilters::default();
+        filters.with_untyped(ComponentId::new(1));
+        filters.with_untyped(ComponentId::new(3));
+        filters.without_untyped(ComponentId::new(3));
+
+        assert_eq!(2, filters.0.len());
+        assert_eq!(Some(&FilterKind::With), filters.0.get(&ComponentId::new(1)));
+        assert_eq!(
+            Some(&FilterKind::Without),
+            filters.0.get(&ComponentId::new(3))
+        );
+    }
+
+    #[test]
+    fn test_apply_filters() {
+        let mut filters = DefaultQueryFilters::default();
+        filters.with_untyped(ComponentId::new(1));
+        filters.without_untyped(ComponentId::new(3));
+
+        // A component access with an unrelated component
+        let mut component_access = FilteredAccess::<ComponentId>::default();
+        component_access.access_mut().add_read(ComponentId::new(2));
+
+        let mut applied_access = component_access.clone();
+        filters.apply(&mut applied_access);
+        assert_eq!(
+            vec![ComponentId::new(1)],
+            applied_access.with_filters().collect::<Vec<_>>()
+        );
+        assert_eq!(
+            vec![ComponentId::new(3)],
+            applied_access.without_filters().collect::<Vec<_>>()
+        );
+
+        // We add a with filter, now we expect to see both filters
+        component_access.and_with(ComponentId::new(4));
+
+        let mut applied_access = component_access.clone();
+        filters.apply(&mut applied_access);
+        assert_eq!(
+            vec![ComponentId::new(1), ComponentId::new(4)],
+            applied_access.with_filters().collect::<Vec<_>>()
+        );
+        assert_eq!(
+            vec![ComponentId::new(3)],
+            applied_access.without_filters().collect::<Vec<_>>()
+        );
+
+        // We add a rule targeting a default component, that filter should no longer be added
+        component_access.and_with(ComponentId::new(3));
+
+        let mut applied_access = component_access.clone();
+        filters.apply(&mut applied_access);
+        assert_eq!(
+            vec![
+                ComponentId::new(1),
+                ComponentId::new(3),
+                ComponentId::new(4)
+            ],
+            applied_access.with_filters().collect::<Vec<_>>()
+        );
+        assert!(applied_access.without_filters().next().is_none());
+
+        // Archetypal access should also filter rules
+        component_access
+            .access_mut()
+            .add_archetypal(ComponentId::new(1));
+
+        let mut applied_access = component_access.clone();
+        filters.apply(&mut applied_access);
+        assert_eq!(
+            vec![ComponentId::new(3), ComponentId::new(4)],
+            applied_access.with_filters().collect::<Vec<_>>()
+        );
+        assert!(applied_access.without_filters().next().is_none());
+    }
+}

crates/bevy_ecs/src/query/mod.rs

@@ -2,6 +2,7 @@
 
 mod access;
 mod builder;
+mod default_filters;
 mod error;
 mod fetch;
 mod filter;
@@ -13,6 +14,7 @@ mod world_query;
 pub use access::*;
 pub use bevy_ecs_macros::{QueryData, QueryFilter};
 pub use builder::*;
+pub use default_filters::DefaultQueryFilters;
 pub use error::*;
 pub use fetch::*;
 pub use filter::*;

crates/bevy_ecs/src/query/state.rs

@@ -5,7 +5,8 @@ use crate::{
     entity::Entity,
     prelude::FromWorld,
     query::{
-        Access, DebugCheckedUnwrap, FilteredAccess, QueryCombinationIter, QueryIter, QueryParIter,
+        default_filters::DefaultQueryFilters, Access, DebugCheckedUnwrap, FilteredAccess,
+        QueryCombinationIter, QueryIter, QueryParIter,
     },
     storage::{SparseSetIndex, TableId},
     world::{unsafe_world_cell::UnsafeWorldCell, World, WorldId},
@@ -194,6 +195,10 @@ impl<D: QueryData, F: QueryFilter> QueryState<D, F> {
         // properly considered in a global "cross-query" context (both within systems and across systems).
         component_access.extend(&filter_component_access);
 
+        if let Some(default_filters) = world.get_resource::<DefaultQueryFilters>() {
+            default_filters.apply(&mut component_access);
+        }
+
         Self {
             world_id: world.id(),
             archetype_generation: ArchetypeGeneration::initial(),
@@ -218,13 +223,19 @@ impl<D: QueryData, F: QueryFilter> QueryState<D, F> {
         let filter_state = F::init_state(builder.world_mut());
         D::set_access(&mut fetch_state, builder.access());
 
+        let mut component_access = builder.access().clone();
+
+        if let Some(default_filters) = builder.world().get_resource::<DefaultQueryFilters>() {
+            default_filters.apply(&mut component_access);
+        }
+
         let mut state = Self {
             world_id: builder.world().id(),
             archetype_generation: ArchetypeGeneration::initial(),
             matched_storage_ids: Vec::new(),
             fetch_state,
             filter_state,
-            component_access: builder.access().clone(),
+            component_access,
             matched_tables: Default::default(),
             matched_archetypes: Default::default(),
             #[cfg(feature = "trace")]
@@ -1657,8 +1668,9 @@ impl<D: QueryData, F: QueryFilter> From<QueryBuilder<'_, D, F>> for QueryState<D
 #[cfg(test)]
 mod tests {
     use crate as bevy_ecs;
-    use crate::world::FilteredEntityRef;
-    use crate::{component::Component, prelude::*, query::QueryEntityError};
+    use crate::{
+        component::Component, prelude::*, query::QueryEntityError, world::FilteredEntityRef,
+    };
 
     #[test]
     fn get_many_unchecked_manual_uniqueness() {
@@ -2030,4 +2042,27 @@ mod tests {
         let query_2 = QueryState::<&B, Without<C>>::new(&mut world);
         let _: QueryState<Entity, Changed<C>> = query_1.join_filtered(&world, &query_2);
     }
+
+    #[test]
+    fn query_respects_default_filters() {
+        let mut world = World::new();
+        world.spawn((A(0), B(0)));
+        world.spawn((B(0), C(0)));
+        world.spawn(C(0));
+
+        world.default_with_filter::<B>();
+        world.default_without_filter::<C>();
+
+        // With<B>, Without<C> only matches the first entity
+        let mut query = QueryState::<()>::new(&mut world);
+        assert_eq!(1, query.iter(&world).count());
+
+        // With<B>, With<C> only matches the second entity
+        let mut query = QueryState::<(), With<C>>::new(&mut world);
+        assert_eq!(1, query.iter(&world).count());
+
+        // Without<B> only matches the last entity
+        let mut query = QueryState::<Has<C>, Without<B>>::new(&mut world);
+        assert_eq!(1, query.iter(&world).count());
+    }
 }

crates/bevy_ecs/src/world/mod.rs

@@ -8,6 +8,7 @@ mod spawn_batch;
 pub mod unsafe_world_cell;
 
 pub use crate::change_detection::{Mut, Ref, CHECK_TICK_THRESHOLD};
+use crate::query::DefaultQueryFilters;
 pub use crate::world::command_queue::CommandQueue;
 pub use deferred_world::DeferredWorld;
 pub use entity_ref::{
@@ -1074,6 +1075,32 @@ impl World {
         QueryState::new(self)
     }
 
+    /// Add a [`With<T>`](crate::prelude::With) filter to [`DefaultQueryFilters`].
+    /// Inserts the [`DefaultQueryFilters`] resource if it does not exist
+    pub fn default_with_filter<T: Component>(&mut self) {
+        let id = self.init_component::<T>();
+        if let Some(mut filters) = self.get_resource_mut::<DefaultQueryFilters>() {
+            filters.with_untyped(id);
+        } else {
+            let mut filters = DefaultQueryFilters::default();
+            filters.with_untyped(id);
+            self.insert_resource(filters);
+        }
+    }
+
+    /// Add a [`Without<T>`](crate::prelude::Without) filter to [`DefaultQueryFilters`].
+    /// Inserts the [`DefaultQueryFilters`] resource if it does not exist
+    pub fn default_without_filter<T: Component>(&mut self) {
+        let id = self.init_component::<T>();
+        if let Some(mut filters) = self.get_resource_mut::<DefaultQueryFilters>() {
+            filters.without_untyped(id);
+        } else {
+            let mut filters = DefaultQueryFilters::default();
+            filters.without_untyped(id);
+            self.insert_resource(filters);
+        }
+    }
+
     /// Returns an iterator of entities that had components of type `T` removed
     /// since the last call to [`World::clear_trackers`].
     pub fn removed<T: Component>(&self) -> impl Iterator<Item = Entity> + '_ {