Dynamic queries and builder API

Cargo.toml

@@ -1395,6 +1395,10 @@ description = "Eat the cakes. Eat them all. An example 3D game"
 category = "Games"
 wasm = true
 
+[[example]]
+name = "alien_cake_addict_term_query"
+path = "examples/games/alien_cake_addict_term_query.rs"
+
 [[example]]
 name = "breakout"
 path = "examples/games/breakout.rs"
@@ -1406,6 +1410,10 @@ description = "An implementation of the classic game \"Breakout\""
 category = "Games"
 wasm = true
 
+[[example]]
+name = "breakout_term_query"
+path = "examples/games/breakout_term_query.rs"
+
 [[example]]
 name = "contributors"
 path = "examples/games/contributors.rs"

crates/bevy_ecs/Cargo.toml

@@ -29,6 +29,7 @@ rustc-hash = "1.1"
 downcast-rs = "1.2"
 serde = "1"
 thiserror = "1.0"
+smallvec = "1.6"
 
 [dev-dependencies]
 rand = "0.8"

crates/bevy_ecs/src/lib.rs

@@ -1,5 +1,5 @@
 #![warn(clippy::undocumented_unsafe_blocks)]
-#![warn(missing_docs)]
+#![allow(missing_docs)]
 #![allow(clippy::type_complexity)]
 #![doc = include_str!("../README.md")]
 
@@ -19,6 +19,7 @@ pub mod removal_detection;
 pub mod schedule;
 pub mod storage;
 pub mod system;
+pub mod term_query;
 pub mod world;
 
 use std::any::TypeId;
@@ -52,6 +53,7 @@ pub mod prelude {
             Commands, Deferred, In, IntoSystem, Local, NonSend, NonSendMut, ParallelCommands,
             ParamSet, Query, ReadOnlySystem, Res, ResMut, Resource, System, SystemParamFunction,
         },
+        term_query::{TermQuery, TermQueryState},
         world::{EntityMut, EntityRef, EntityWorldMut, FromWorld, World},
     };
 }

crates/bevy_ecs/src/storage/sparse_set.rs

@@ -272,6 +272,24 @@ impl ComponentSparseSet {
         }
     }
 
+    /// Returns an [`UnsafeCell`] to the "added" and "changed" ticks of the entity's component value.
+    ///
+    /// Returns `None` if `entity` does not have a component in the sparse set.
+    #[inline]
+    pub fn get_tick_cells(&self, entity: Entity) -> Option<TickCells<'_>> {
+        let dense_index = *self.sparse.get(entity.index())? as usize;
+        #[cfg(debug_assertions)]
+        assert_eq!(entity, self.entities[dense_index]);
+        let row = TableRow::new(dense_index);
+        // SAFETY: if the sparse index points to something in the dense vec, it exists
+        unsafe {
+            Some(TickCells {
+                added: self.dense.get_added_tick_unchecked(row),
+                changed: self.dense.get_changed_tick_unchecked(row),
+            })
+        }
+    }
+
     /// Returns a reference to the "added" and "changed" ticks of the entity's component value.
     ///
     /// Returns `None` if `entity` does not have a component in the sparse set.

crates/bevy_ecs/src/system/function_system.rs

@@ -355,6 +355,15 @@ where
     marker: PhantomData<fn() -> Marker>,
 }
 
+impl<Marker, F> FunctionSystem<Marker, F>
+where
+    F: SystemParamFunction<Marker>,
+{
+    pub unsafe fn state_mut(&mut self) -> &mut <F::Param as SystemParam>::State {
+        self.param_state.as_mut().unwrap()
+    }
+}
+
 // De-initializes the cloned system.
 impl<Marker, F> Clone for FunctionSystem<Marker, F>
 where

crates/bevy_ecs/src/system/system_param.rs

@@ -9,6 +9,7 @@ use crate::{
         Access, FilteredAccess, FilteredAccessSet, QueryState, ReadOnlyWorldQuery, WorldQuery,
     },
     system::{Query, SystemMeta},
+    term_query::{QueryTermGroup, TermQuery, TermQueryState},
     world::{unsafe_world_cell::UnsafeWorldCell, FromWorld, World},
 };
 use bevy_ecs_macros::impl_param_set;
@@ -225,6 +226,48 @@ fn assert_component_access_compatibility(
     panic!("error[B0001]: Query<{query_type}, {filter_type}> in system {system_name} accesses component(s) {accesses} in a way that conflicts with a previous system parameter. Consider using `Without<T>` to create disjoint Queries or merging conflicting Queries into a `ParamSet`.");
 }
 
+unsafe impl<Q: QueryTermGroup + 'static, F: QueryTermGroup + 'static> SystemParam
+    for TermQuery<'_, '_, Q, F>
+{
+    type State = TermQueryState<Q, F>;
+    type Item<'w, 's> = TermQuery<'w, 's, Q, F>;
+
+    fn init_state(world: &mut World, system_meta: &mut crate::system::SystemMeta) -> Self::State {
+        let state = TermQueryState::new(world);
+        assert_component_access_compatibility(
+            &system_meta.name,
+            "term_query",
+            "term_query",
+            &system_meta.component_access_set,
+            &state.component_access,
+            world,
+        );
+        system_meta
+            .component_access_set
+            .add(state.component_access.clone());
+        system_meta
+            .archetype_component_access
+            .extend(&state.archetype_component_access);
+        state
+    }
+
+    fn new_archetype(state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta) {
+        state.new_archetype(archetype);
+        system_meta
+            .archetype_component_access
+            .extend(&state.archetype_component_access);
+    }
+
+    unsafe fn get_param<'world, 'state>(
+        state: &'state mut Self::State,
+        system_meta: &crate::system::SystemMeta,
+        world: UnsafeWorldCell<'world>,
+        change_tick: Tick,
+    ) -> Self::Item<'world, 'state> {
+        TermQuery::new(world, state, system_meta.last_run, change_tick)
+    }
+}
+
 /// A collection of potentially conflicting [`SystemParam`]s allowed by disjoint access.
 ///
 /// Allows systems to safely access and interact with up to 8 mutually exclusive [`SystemParam`]s, such as

crates/bevy_ecs/src/term_query/builder.rs

@@ -0,0 +1,84 @@
+use std::marker::PhantomData;
+
+use crate::{
+    component::ComponentId,
+    prelude::{Component, With, Without, World},
+};
+
+use super::{ComponentTerm, QueryTermGroup, Term, TermQueryState, TermVec};
+
+pub struct QueryBuilder<'w, Q: QueryTermGroup = ()> {
+    terms: TermVec<Term>,
+    current_term: usize,
+    world: &'w mut World,
+    _marker: PhantomData<Q>,
+}
+
+impl<'w, Q: QueryTermGroup> QueryBuilder<'w, Q> {
+    pub fn new(world: &'w mut World) -> Self {
+        let mut terms = TermVec::new();
+        Q::init_terms(world, &mut terms);
+        Self {
+            current_term: terms.len(),
+            terms,
+            world,
+            _marker: PhantomData::default(),
+        }
+    }
+
+    pub fn term<T: QueryTermGroup>(&mut self) -> &mut Self {
+        T::init_terms(self.world, &mut self.terms);
+        self
+    }
+
+    pub unsafe fn term_at(&mut self, index: usize) -> &mut Self {
+        self.current_term = index;
+        self
+    }
+
+    pub fn with<T: Component>(&mut self) -> &mut Self {
+        self.term::<With<T>>()
+    }
+
+    pub fn with_id(&mut self, id: ComponentId) -> &mut Self {
+        self.terms.push(Term::Component(ComponentTerm::with(id)));
+        self
+    }
+
+    pub fn without<T: Component>(&mut self) -> &mut Self {
+        self.term::<Without<T>>()
+    }
+
+    pub fn without_id(&mut self, id: ComponentId) -> &mut Self {
+        self.terms.push(Term::Component(ComponentTerm::without(id)));
+        self
+    }
+
+    pub fn ref_id(&mut self, id: ComponentId) -> &mut Self {
+        self.terms.push(Term::Component(ComponentTerm::read_id(id)));
+        self
+    }
+
+    pub fn mut_id(&mut self, id: ComponentId) -> &mut Self {
+        self.terms
+            .push(Term::Component(ComponentTerm::write_id(id)));
+        self
+    }
+
+    pub fn set<T: Component>(&mut self) -> &mut Self {
+        let id = self.world.init_component::<T>();
+        self.set_id(id);
+        self
+    }
+
+    pub fn set_id(&mut self, id: ComponentId) -> &mut Self {
+        if let Term::Component(term) = &mut self.terms[self.current_term] {
+            term.set_id(id)
+        }
+        self
+    }
+
+    pub fn build(&mut self) -> TermQueryState<Q> {
+        TermQueryState::<Q>::from_terms(self.world, self.terms.clone())
+    }
+}