Trait bevy::ecs::query::WorldQuery

pub unsafe trait WorldQuery {
    type Item<'a>;
    type Fetch<'a>;
    type ReadOnly: ReadOnlyWorldQuery<State = Self::State>;
    type State: Send + Sync + Sized;

    const IS_DENSE: bool;
    const IS_ARCHETYPAL: bool;

    // Required methods
    fn shrink<'wlong, 'wshort>(item: Self::Item<'wlong>) -> Self::Item<'wshort>
       where 'wlong: 'wshort;
    unsafe fn init_fetch<'w>(
        world: &'w World,
        state: &Self::State,
        last_change_tick: u32,
        change_tick: u32
    ) -> Self::Fetch<'w>;
    unsafe fn clone_fetch<'w>(fetch: &Self::Fetch<'w>) -> Self::Fetch<'w>;
    unsafe fn set_archetype<'w>(
        fetch: &mut Self::Fetch<'w>,
        state: &Self::State,
        archetype: &'w Archetype,
        table: &'w Table
    );
    unsafe fn set_table<'w>(
        fetch: &mut Self::Fetch<'w>,
        state: &Self::State,
        table: &'w Table
    );
    unsafe fn fetch<'w>(
        fetch: &mut Self::Fetch<'w>,
        entity: Entity,
        table_row: TableRow
    ) -> Self::Item<'w>;
    fn update_component_access(
        state: &Self::State,
        access: &mut FilteredAccess<ComponentId>
    );
    fn update_archetype_component_access(
        state: &Self::State,
        archetype: &Archetype,
        access: &mut Access<ArchetypeComponentId>
    );
    fn init_state(world: &mut World) -> Self::State;
    fn matches_component_set(
        state: &Self::State,
        set_contains_id: &impl Fn(ComponentId) -> bool
    ) -> bool;

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

Expand description

Types that can be fetched from a World using a Query.

There are many types that natively implement this trait:

Component references. Fetches a component by reference (immutably or mutably).
WorldQuery tuples. If every element of a tuple implements WorldQuery, then the tuple itself also implements the same trait. This enables a single Query to access multiple components and 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 WorldQuerys.
Component filters. With and Without filters can be applied to check if the queried entity contains or not a particular component.
Change detection filters. Added and Changed filters can be applied to detect component changes to an entity.
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.
Entity. Gets the identifier of the queried entity.
Option. By default, a world query only tests entities that have the matching component types. Wrapping it into an Option will increase the query search space, and it will return None if an entity doesn’t satisfy the WorldQuery.
AnyOf. Equivalent to wrapping each world query inside it into an Option.
ChangeTrackers. Similar to change detection filters but it is used as a query fetch parameter. It exposes methods to check for changes to the wrapped component.

Implementing the trait manually can allow for a fundamentally new type of behaviour.

Trait derivation

Query design can be easily structured by deriving WorldQuery for custom types. Despite the added complexity, this approach has several advantages over using WorldQuery tuples. The most relevant improvements are:

Reusability across multiple systems.
There is no need to destructure a tuple since all fields are named.
Subqueries can be composed together to create a more complex query.
Methods can be implemented for the query items.
There is no hardcoded limit on the number of elements.

This trait can only be derived if each field either

also implements WorldQuery, or
is marked with #[world_query(ignore)]. Fields decorated with this attribute must implement Default and will be initialized to the default value as defined by the trait.

The derive macro only supports regular structs (structs with named fields).

use bevy_ecs::query::WorldQuery;

#[derive(WorldQuery)]
struct MyQuery {
    entity: Entity,
    // It is required that all reference lifetimes are explicitly annotated, just like in any
    // struct. Each lifetime should be 'static.
    component_a: &'static ComponentA,
    component_b: &'static ComponentB,
}

fn my_system(query: Query<MyQuery>) {
    for q in &query {
        q.component_a;
    }
}

Macro expansion

Expanding the macro will declare three or six additional structs, depending on whether or not the struct is marked as mutable. For a struct named X, the additional structs will be:

Struct name	`mutable` only	Description
`XState`	—	Used as the `State` type for `X` and `XReadOnly`
`XItem`	—	The type of the query item for `X`
`XFetch`	—	Used as the `Fetch` type for `X`
`XReadOnlyItem`	✓	The type of the query item for `XReadOnly`
`XReadOnlyFetch`	✓	Used as the `Fetch` type for `XReadOnly`
`XReadOnly`	✓	`ReadOnly` variant of `X`

Adding mutable references

Simply adding mutable references to a derived WorldQuery will result in a compilation error:

#[derive(WorldQuery)]
struct CustomQuery {
    component_a: &'static mut ComponentA,
}

To grant mutable access to components, the struct must be marked with the #[world_query(mutable)] attribute. This will also create three more structs that will be used for accessing the query immutably (see table above).

#[derive(WorldQuery)]
#[world_query(mutable)]
struct CustomQuery {
    component_a: &'static mut ComponentA,
}

Adding methods to query items

It is possible to add methods to query items in order to write reusable logic about related components. This will often make systems more readable because low level logic is moved out from them. It is done by adding impl blocks with methods for the -Item or -ReadOnlyItem generated structs.

#[derive(Component)]
struct Health(f32);

#[derive(Component)]
struct Buff(f32);

#[derive(WorldQuery)]
#[world_query(mutable)]
struct HealthQuery {
    health: &'static mut Health,
    buff: Option<&'static mut Buff>,
}

// `HealthQueryItem` is only available when accessing the query with mutable methods.
impl<'w> HealthQueryItem<'w> {
    fn damage(&mut self, value: f32) {
        self.health.0 -= value;
    }

    fn total(&self) -> f32 {
        self.health.0 + self.buff.as_deref().map_or(0.0, |Buff(buff)| *buff)
    }
}

// `HealthQueryReadOnlyItem` is only available when accessing the query with immutable methods.
impl<'w> HealthQueryReadOnlyItem<'w> {
    fn total(&self) -> f32 {
        self.health.0 + self.buff.map_or(0.0, |Buff(buff)| *buff)
    }
}

fn my_system(mut health_query: Query<HealthQuery>) {
    // The item returned by the iterator is of type `HealthQueryReadOnlyItem`.
    for health in health_query.iter() {
        println!("Total: {}", health.total());
    }
    // The item returned by the iterator is of type `HealthQueryItem`.
    for mut health in &mut health_query {
        health.damage(1.0);
        println!("Total (mut): {}", health.total());
    }
}

Deriving traits for query items

The WorldQuery derive macro does not automatically implement the traits of the struct to the query item types. Something similar can be done by using the #[world_query(derive(...))] attribute. This will apply the listed derivable traits to the query item structs.

#[derive(WorldQuery)]
#[world_query(mutable, derive(Debug))]
struct CustomQuery {
    component_a: &'static ComponentA,
}

// This function statically checks that `T` implements `Debug`.
fn assert_debug<T: std::fmt::Debug>() {}

assert_debug::<CustomQueryItem>();
assert_debug::<CustomQueryReadOnlyItem>();

Query composition

It is possible to use any WorldQuery as a field of another one. This means that a WorldQuery can also be used as a subquery, potentially in multiple places.

#[derive(WorldQuery)]
struct SubQuery {
    component_a: &'static ComponentA,
    component_b: &'static ComponentB,
}

#[derive(WorldQuery)]
struct MyQuery {
    subquery: SubQuery,
    component_c: &'static ComponentC,
}

Filters

Since the query filter type parameter is WorldQuery, it is also possible to use this macro to create filters.

#[derive(WorldQuery)]
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>>) {
    // ...
}

Generic Queries

When writing generic code, it is often necessary to use PhantomData to constrain type parameters. Since WorldQuery is implemented for all PhantomData<T> types, this pattern can be used with this macro.

#[derive(WorldQuery)]
pub struct GenericQuery<T> {
    id: Entity,
    marker: PhantomData<T>,
}

Safety

Component access of Self::ReadOnly must be a subset of Self and Self::ReadOnly must match exactly the same archetypes/tables as Self

Implementor must ensure that update_component_access and update_archetype_component_access exactly reflects the results of the following methods:

Required Associated Types§

type Item<'a>

The item returned by this WorldQuery

type Fetch<'a>

Per archetype/table state used by this WorldQuery to fetch Self::Item

type ReadOnly: ReadOnlyWorldQuery<State = Self::State>

The read-only variant of this WorldQuery, which satisfies the ReadOnlyWorldQuery trait.

type State: Send + Sync + Sized

State used to construct a Self::Fetch. This will be cached inside QueryState, so it is best to move as much data / computation here as possible to reduce the cost of constructing Self::Fetch.

Required Associated Constants§

const IS_DENSE: bool

Returns true if (and only if) every table of every archetype matched by this fetch contains all of the matched components. This is used to select a more efficient “table iterator” for “dense” queries. If this returns true, WorldQuery::set_table must be used before WorldQuery::fetch can be called for iterators. If this returns false, WorldQuery::set_archetype must be used before WorldQuery::fetch can be called for iterators.

const IS_ARCHETYPAL: bool

Returns true if (and only if) this Fetch 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()).

fn update_archetype_component_access( state: &Self::State, archetype: &Archetype, access: &mut Access<ArchetypeComponentId> )

fn init_state(world: &mut World) -> Self::State

fn matches_component_set( state: &Self::State, set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool

Provided Methods§

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

impl<'w, T> WorldQuery for &'w mut Twhere T: Component,

SAFETY: access of &T is a subset of &mut T

impl<T> WorldQuery for PhantomData<T>where T: ?Sized,

SAFETY: PhantomData never accesses any world data.

impl WorldQuery for Entity

SAFETY: no component or archetype access

impl<Q> WorldQuery for NopWorldQuery<Q>where Q: WorldQuery,

Trait bevy::ecs::query::WorldQuery

Required Associated Types§

type Item<'a>

type Fetch<'a>

type ReadOnly: ReadOnlyWorldQuery<State = Self::State>

type State: Send + Sync + Sized

Required Associated Constants§

const IS_DENSE: bool

const IS_ARCHETYPAL: bool

Required Methods§

fn shrink<'wlong, 'wshort>(item: Self::Item<'wlong>) -> Self::Item<'wshort>where 'wlong: 'wshort,

unsafe fn init_fetch<'w>( world: &'w World, state: &Self::State, last_change_tick: u32, change_tick: u32 ) -> Self::Fetch<'w>

unsafe fn clone_fetch<'w>(fetch: &Self::Fetch<'w>) -> Self::Fetch<'w>

unsafe fn set_archetype<'w>( fetch: &mut Self::Fetch<'w>, state: &Self::State, archetype: &'w Archetype, table: &'w Table )

unsafe fn set_table<'w>( fetch: &mut Self::Fetch<'w>, state: &Self::State, table: &'w Table )

unsafe fn fetch<'w>( fetch: &mut Self::Fetch<'w>, entity: Entity, table_row: TableRow ) -> Self::Item<'w>

fn update_component_access( state: &Self::State, access: &mut FilteredAccess<ComponentId> )

fn update_archetype_component_access( state: &Self::State, archetype: &Archetype, access: &mut Access<ArchetypeComponentId> )

fn init_state(world: &mut World) -> Self::State

fn matches_component_set( state: &Self::State, set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool

Provided Methods§

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

Implementations on Foreign Types§

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

type Fetch = (<F0 as WorldQuery>::Fetch<'w>, <F1 as WorldQuery>::Fetch<'w>)

type Item = (<F0 as WorldQuery>::Item<'w>, <F1 as WorldQuery>::Item<'w>)

type ReadOnly = (<F0 as WorldQuery>::ReadOnly, <F1 as WorldQuery>::ReadOnly)

type State = (<F0 as WorldQuery>::State, <F1 as WorldQuery>::State)

fn shrink<'wlong, 'wshort>( item: <(F0, F1) as WorldQuery>::Item<'wlong> ) -> <(F0, F1) as WorldQuery>::Item<'wshort>where 'wlong: 'wshort,

unsafe fn init_fetch<'w>( _world: &'w World, state: &<(F0, F1) as WorldQuery>::State, _last_change_tick: u32, _change_tick: u32 ) -> <(F0, F1) as WorldQuery>::Fetch<'w>

unsafe fn clone_fetch<'w>( fetch: &<(F0, F1) as WorldQuery>::Fetch<'w> ) -> <(F0, F1) as WorldQuery>::Fetch<'w>

const IS_DENSE: bool = true && F0::IS_DENSE && F1::IS_DENSE

const IS_ARCHETYPAL: bool = true && F0::IS_ARCHETYPAL && F1::IS_ARCHETYPAL

unsafe fn set_archetype<'w>( _fetch: &mut <(F0, F1) as WorldQuery>::Fetch<'w>, _state: &<(F0, F1) as WorldQuery>::State, _archetype: &'w Archetype, _table: &'w Table )

unsafe fn set_table<'w>( _fetch: &mut <(F0, F1) as WorldQuery>::Fetch<'w>, _state: &<(F0, F1) as WorldQuery>::State, _table: &'w Table )

unsafe fn fetch<'w>( _fetch: &mut <(F0, F1) as WorldQuery>::Fetch<'w>, _entity: Entity, _table_row: TableRow ) -> <(F0, F1) as WorldQuery>::Item<'w>

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

fn update_component_access( state: &<(F0, F1) as WorldQuery>::State, _access: &mut FilteredAccess<ComponentId> )

fn update_archetype_component_access( state: &<(F0, F1) as WorldQuery>::State, _archetype: &Archetype, _access: &mut Access<ArchetypeComponentId> )

fn init_state(_world: &mut World) -> <(F0, F1) as WorldQuery>::State

fn matches_component_set( state: &<(F0, F1) as WorldQuery>::State, _set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool

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

type Fetch = (<F0 as WorldQuery>::Fetch<'w>, <F1 as WorldQuery>::Fetch<'w>, <F2 as WorldQuery>::Fetch<'w>, <F3 as WorldQuery>::Fetch<'w>)

type Item = (<F0 as WorldQuery>::Item<'w>, <F1 as WorldQuery>::Item<'w>, <F2 as WorldQuery>::Item<'w>, <F3 as WorldQuery>::Item<'w>)

type ReadOnly = (<F0 as WorldQuery>::ReadOnly, <F1 as WorldQuery>::ReadOnly, <F2 as WorldQuery>::ReadOnly, <F3 as WorldQuery>::ReadOnly)

type State = (<F0 as WorldQuery>::State, <F1 as WorldQuery>::State, <F2 as WorldQuery>::State, <F3 as WorldQuery>::State)

fn shrink<'wlong, 'wshort>( item: <(F0, F1, F2, F3) as WorldQuery>::Item<'wlong> ) -> <(F0, F1, F2, F3) as WorldQuery>::Item<'wshort>where 'wlong: 'wshort,

unsafe fn init_fetch<'w>( _world: &'w World, state: &<(F0, F1, F2, F3) as WorldQuery>::State, _last_change_tick: u32, _change_tick: u32 ) -> <(F0, F1, F2, F3) as WorldQuery>::Fetch<'w>

unsafe fn clone_fetch<'w>( fetch: &<(F0, F1, F2, F3) as WorldQuery>::Fetch<'w> ) -> <(F0, F1, F2, F3) as WorldQuery>::Fetch<'w>

const IS_DENSE: bool = true && F0::IS_DENSE && F1::IS_DENSE && F2::IS_DENSE && F3::IS_DENSE

const IS_ARCHETYPAL: bool = true && F0::IS_ARCHETYPAL && F1::IS_ARCHETYPAL && F2::IS_ARCHETYPAL && F3::IS_ARCHETYPAL

unsafe fn set_archetype<'w>( _fetch: &mut <(F0, F1, F2, F3) as WorldQuery>::Fetch<'w>, _state: &<(F0, F1, F2, F3) as WorldQuery>::State, _archetype: &'w Archetype, _table: &'w Table )

unsafe fn set_table<'w>( _fetch: &mut <(F0, F1, F2, F3) as WorldQuery>::Fetch<'w>, _state: &<(F0, F1, F2, F3) as WorldQuery>::State, _table: &'w Table )

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

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

fn update_component_access( state: &<(F0, F1, F2, F3) as WorldQuery>::State, _access: &mut FilteredAccess<ComponentId> )

fn update_archetype_component_access( state: &<(F0, F1, F2, F3) as WorldQuery>::State, _archetype: &Archetype, _access: &mut Access<ArchetypeComponentId> )

fn init_state(_world: &mut World) -> <(F0, F1, F2, F3) as WorldQuery>::State

fn matches_component_set( state: &<(F0, F1, F2, F3) as WorldQuery>::State, _set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool

impl<F0, F1, F2, F3, F4, F5, F6> WorldQuery for (F0, F1, F2, F3, F4, F5, F6)where F0: WorldQuery, F1: WorldQuery, F2: WorldQuery, F3: WorldQuery, F4: WorldQuery, F5: WorldQuery, F6: WorldQuery,

type Fetch = (<F0 as WorldQuery>::Fetch<'w>, <F1 as WorldQuery>::Fetch<'w>, <F2 as WorldQuery>::Fetch<'w>, <F3 as WorldQuery>::Fetch<'w>, <F4 as WorldQuery>::Fetch<'w>, <F5 as WorldQuery>::Fetch<'w>, <F6 as WorldQuery>::Fetch<'w>)

type Item = (<F0 as WorldQuery>::Item<'w>, <F1 as WorldQuery>::Item<'w>, <F2 as WorldQuery>::Item<'w>, <F3 as WorldQuery>::Item<'w>, <F4 as WorldQuery>::Item<'w>, <F5 as WorldQuery>::Item<'w>, <F6 as WorldQuery>::Item<'w>)

type ReadOnly = (<F0 as WorldQuery>::ReadOnly, <F1 as WorldQuery>::ReadOnly, <F2 as WorldQuery>::ReadOnly, <F3 as WorldQuery>::ReadOnly, <F4 as WorldQuery>::ReadOnly, <F5 as WorldQuery>::ReadOnly, <F6 as WorldQuery>::ReadOnly)

type State = (<F0 as WorldQuery>::State, <F1 as WorldQuery>::State, <F2 as WorldQuery>::State, <F3 as WorldQuery>::State, <F4 as WorldQuery>::State, <F5 as WorldQuery>::State, <F6 as WorldQuery>::State)

fn shrink<'wlong, 'wshort>( item: <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Item<'wlong> ) -> <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Item<'wshort>where 'wlong: 'wshort,

unsafe fn init_fetch<'w>( _world: &'w World, state: &<(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::State, _last_change_tick: u32, _change_tick: u32 ) -> <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Fetch<'w>

unsafe fn clone_fetch<'w>( fetch: &<(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Fetch<'w> ) -> <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Fetch<'w>

const IS_DENSE: bool = true && F0::IS_DENSE && F1::IS_DENSE && F2::IS_DENSE && F3::IS_DENSE && F4::IS_DENSE && F5::IS_DENSE && F6::IS_DENSE

const IS_ARCHETYPAL: bool = true && F0::IS_ARCHETYPAL && F1::IS_ARCHETYPAL && F2::IS_ARCHETYPAL && F3::IS_ARCHETYPAL && F4::IS_ARCHETYPAL && F5::IS_ARCHETYPAL && F6::IS_ARCHETYPAL

unsafe fn set_archetype<'w>( _fetch: &mut <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Fetch<'w>, _state: &<(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::State, _archetype: &'w Archetype, _table: &'w Table )

unsafe fn set_table<'w>( _fetch: &mut <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::Fetch<'w>, _state: &<(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::State, _table: &'w Table )

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

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

fn update_component_access( state: &<(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::State, _access: &mut FilteredAccess<ComponentId> )

fn update_archetype_component_access( state: &<(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::State, _archetype: &Archetype, _access: &mut Access<ArchetypeComponentId> )

fn init_state( _world: &mut World ) -> <(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::State

fn matches_component_set( state: &<(F0, F1, F2, F3, F4, F5, F6) as WorldQuery>::State, _set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool

fn shrink<'wlong, 'wshort>( item: <(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11) as WorldQuery>::Item<'wlong> ) -> <(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11) as WorldQuery>::Item<'wshort>where 'wlong: 'wshort,

unsafe fn init_fetch<'w>( _world: &'w World, state: &<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11) as WorldQuery>::State, _last_change_tick: u32, _change_tick: u32 ) -> <(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11) as WorldQuery>::Fetch<'w>

unsafe fn clone_fetch<'w>( fetch: &<(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11) as WorldQuery>::Fetch<'w> ) -> <(F0, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11) as WorldQuery>::Fetch<'w>