Trait QueryFilter

pub unsafe trait QueryFilter: WorldQuery {
    const IS_ARCHETYPAL: bool;

    // Required method
    unsafe fn filter_fetch(
        fetch: &mut Self::Fetch<'_>,
        entity: Entity,
        table_row: TableRow,
    ) -> bool;
}

Types that filter the results of a Query.

There are many types that natively implement this trait:

• Component filters. With and Without filters can be applied to check if the queried entity does or does not contain a particular component.
• Change detection filters. Added and Changed filters can be applied to detect component changes to an entity.
• QueryFilter tuples. If every element of a tuple implements QueryFilter, then the tuple itself also implements the same trait. This enables a single Query to 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 infinite QueryFilters.
• 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 Or operator 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>>) {
    // ...
}

Safety

The WorldQuery implementation must not take any mutable access. This is the same safety requirement as ReadOnlyQueryData.

Required Associated Constants

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

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl QueryFilter for ()

const IS_ARCHETYPAL: bool = true

unsafe fn filter_fetch( fetch: &mut Self::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

impl<F: QueryFilter> QueryFilter for (F₁, F₂, …, Fₙ)

This trait is implemented for tuples up to 16 items long.

const IS_ARCHETYPAL: bool = _

unsafe fn filter_fetch( fetch: &mut Self::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

Implementors

impl QueryFilter for Or<()>

const IS_ARCHETYPAL: bool = true

impl<F: QueryFilter> QueryFilter for Or<(F₁, F₂, …, Fₙ)>

This trait is implemented for tuples up to 16 items long.

const IS_ARCHETYPAL: bool = _

impl<T: Component> QueryFilter for Added<T>

const IS_ARCHETYPAL: bool = false

impl<T: Component> QueryFilter for Changed<T>

const IS_ARCHETYPAL: bool = false

impl<T: Component> QueryFilter for With<T>

const IS_ARCHETYPAL: bool = true

impl<T: Component> QueryFilter for Without<T>

const IS_ARCHETYPAL: bool = true