Trait bevy::ecs::query::QueryFilter

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. 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>>) {
    // ...
}

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.

Object Safety§

This trait is not object safe.

Implementations on Foreign Types§

§

impl QueryFilter for ()

§

const IS_ARCHETYPAL: bool = true

§

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

§

impl<F0> QueryFilter for (F0,)
where F0: QueryFilter,

§

const IS_ARCHETYPAL: bool = _

§

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

§

impl<F0, F1> QueryFilter for (F0, F1)
where F0: QueryFilter, F1: QueryFilter,

§

const IS_ARCHETYPAL: bool = _

§

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

§

impl<F0, F1, F2> QueryFilter for (F0, F1, F2)
where F0: QueryFilter, F1: QueryFilter, F2: QueryFilter,

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3> QueryFilter for (F0, F1, F2, F3)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4> QueryFilter for (F0, F1, F2, F3, F4)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5> QueryFilter for (F0, F1, F2, F3, F4, F5)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4, F5) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5, F6> QueryFilter for (F0, F1, F2, F3, F4, F5, F6)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5, F6, F7> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4, F5, F6, F7) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7, F8)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4, F5, F6, F7, F8) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7, F8, F9)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11)

§

const IS_ARCHETYPAL: bool = _

§

unsafe fn filter_fetch( fetch: &mut <(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11) as WorldQuery>::Fetch<'_>, _entity: Entity, _table_row: TableRow, ) -> bool

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12)

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13)

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14> QueryFilter for (F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14)

Implementors§

§

impl QueryFilter for Or<()>

§

const IS_ARCHETYPAL: bool = true

§

impl<F0> QueryFilter for Or<(F0,)>
where F0: QueryFilter,

§

impl<F0, F1> QueryFilter for Or<(F0, F1)>
where F0: QueryFilter, F1: QueryFilter,

§

impl<F0, F1, F2> QueryFilter for Or<(F0, F1, F2)>
where F0: QueryFilter, F1: QueryFilter, F2: QueryFilter,

§

impl<F0, F1, F2, F3> QueryFilter for Or<(F0, F1, F2, F3)>

§

impl<F0, F1, F2, F3, F4> QueryFilter for Or<(F0, F1, F2, F3, F4)>

§

impl<F0, F1, F2, F3, F4, F5> QueryFilter for Or<(F0, F1, F2, F3, F4, F5)>

§

impl<F0, F1, F2, F3, F4, F5, F6> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7, F8)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13)>

§

impl<F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14> QueryFilter for Or<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14)>

§

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

§

const IS_ARCHETYPAL: bool = false

§

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

§

const IS_ARCHETYPAL: bool = false

§

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

§

const IS_ARCHETYPAL: bool = true

§

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

§

const IS_ARCHETYPAL: bool = true