Trait bevy_ecs::query::QueryFilter
source · pub trait QueryFilter: WorldQuery {
const IS_ARCHETYPAL: bool;
// Required method
unsafe fn filter_fetch(
fetch: &mut Self::Fetch<'_>,
entity: Entity,
table_row: TableRow
) -> bool;
}Expand description
Types that filter the results of a Query.
There are many types that natively implement this trait:
- Component filters.
WithandWithoutfilters can be applied to check if the queried entity does or does not contain a particular component. - Change detection filters.
AddedandChangedfilters can be applied to detect component changes to an entity. QueryFiltertuples. If every element of a tuple implementsQueryFilter, then the tuple itself also implements the same trait. This enables a singleQueryto filter over multiple conditions. Due to the current lack of variadic generics in Rust, the trait has been implemented for tuples from 0 to 15 elements, but nesting of tuples allows infiniteQueryFilters.- Filter disjunction operator.
By default, tuples compose query filters in such a way that all conditions must be satisfied to generate a query item for a given entity.
Wrapping a tuple inside an
Oroperator will relax the requirement to just one condition.
Implementing the trait manually can allow for a fundamentally new type of behavior.
Query design can be easily structured by deriving QueryFilter for custom types.
Despite the added complexity, this approach has several advantages over using QueryFilter tuples.
The most relevant improvements are:
- Reusability across multiple systems.
- Filters can be composed together to create a more complex filter.
This trait can only be derived for structs if each field also implements QueryFilter.
#[derive(QueryFilter)]
struct MyFilter<T: Component, P: Component> {
// Field names are not relevant, since they are never manually accessed.
with_a: With<ComponentA>,
or_filter: Or<(With<ComponentC>, Added<ComponentB>)>,
generic_tuple: (With<T>, Without<P>),
}
fn my_system(query: Query<Entity, MyFilter<ComponentD, ComponentE>>) {
// ...
}Required Associated Constants§
sourceconst IS_ARCHETYPAL: bool
const IS_ARCHETYPAL: bool
Returns true if (and only if) this Filter relies strictly on archetypes to limit which components are accessed by the Query.
This enables optimizations for crate::query::QueryIter that rely on knowing exactly how
many elements are being iterated (such as Iterator::collect()).
Required Methods§
sourceunsafe fn filter_fetch(
fetch: &mut Self::Fetch<'_>,
entity: Entity,
table_row: TableRow
) -> bool
unsafe fn filter_fetch( fetch: &mut Self::Fetch<'_>, entity: Entity, table_row: TableRow ) -> bool
Returns true if the provided Entity and TableRow should be included in the query results.
If false, the entity will be skipped.
Note that this is called after already restricting the matched Tables and Archetypes to the
ones that are compatible with the Filter’s access.
§Safety
Must always be called after WorldQuery::set_table or WorldQuery::set_archetype. entity and
table_row must be in the range of the current table and archetype.
Object Safety§
This trait is not object safe.