Trait bevy_ecs::query::QueryData

source ·

pub unsafe trait QueryData: WorldQuery {
    type ReadOnly: ReadOnlyQueryData<State = <Self as WorldQuery>::State>;
}

Expand description

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

There are many types that natively implement this trait:

Component references. (&T and &mut T) Fetches a component by reference (immutably or mutably).
QueryData tuples. If every element of a tuple implements QueryData, then the tuple itself also implements the same trait. This enables a single Query to access multiple components. 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.
Entity. Gets the identifier of the queried entity.
EntityLocation. Gets the location metadata of the queried entity.
EntityRef. Read-only access to arbitrary components on the queried entity.
EntityMut. Mutable access to arbitrary components on the queried entity.
&Archetype. Read-only access to the archetype-level metadata 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.
Ref. 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.
Has. Returns a bool indicating whether the entity has the specified component.

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

§Trait derivation

Query design can be easily structured by deriving QueryData for custom types. Despite the added complexity, this approach has several advantages over using QueryData 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 for structs, if each field also implements QueryData.

use bevy_ecs::query::QueryData;

#[derive(QueryData)]
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 one or three 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
`XItem`	—	The type of the query item for `X`
`XReadOnlyItem`	✓	The type of the query item for `XReadOnly`
`XReadOnly`	✓	`ReadOnly` variant of `X`

§Adding mutable references

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

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

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

#[derive(QueryData)]
#[query_data(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(QueryData)]
#[query_data(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 QueryData derive macro does not automatically implement the traits of the struct to the query item types. Something similar can be done by using the #[query_data(derive(...))] attribute. This will apply the listed derivable traits to the query item structs.

#[derive(QueryData)]
#[query_data(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 QueryData as a field of another one. This means that a QueryData can also be used as a subquery, potentially in multiple places.

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

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

§Generic Queries

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

#[derive(QueryData)]
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

Required Associated Types§

source

type ReadOnly: ReadOnlyQueryData<State = <Self as WorldQuery>::State>

The read-only variant of this QueryData, which satisfies the ReadOnlyQueryData trait.

Object Safety§

This trait is not object safe.

Trait bevy_ecs::query::QueryDataCopy item path

§Trait derivation

§Macro expansion

§Adding mutable references

§Adding methods to query items

§Deriving traits for query items

§Query composition

§Generic Queries

§Safety

Required Associated Types§

type ReadOnly: ReadOnlyQueryData<State = <Self as WorldQuery>::State>

Object Safety§

Implementations on Foreign Types§

impl QueryData for ()

type ReadOnly = ()

impl<'__w, T: Component> QueryData for &'__w mut T

type ReadOnly = &'__w T

impl<F0: QueryData> QueryData for (F0,)

type ReadOnly = (<F0 as QueryData>::ReadOnly,)

impl<F0: QueryData, F1: QueryData> QueryData for (F0, F1)

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

impl<F0: QueryData, F1: QueryData, F2: QueryData> QueryData for (F0, F1, F2)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl<T: Component> QueryData for &T

type ReadOnly = &T

impl<T: QueryData> QueryData for Option<T>

type ReadOnly = Option<<T as QueryData>::ReadOnly>

impl<T: ?Sized> QueryData for PhantomData<T>

type ReadOnly = PhantomData<T>

Implementors§

impl QueryData for &Archetype

type ReadOnly = &Archetype

impl QueryData for Entity

type ReadOnly = Entity

impl QueryData for EntityLocation

type ReadOnly = EntityLocation

impl QueryData for AnyOf<()>

type ReadOnly = AnyOf<()>

impl<'__w, T: Component> QueryData for Mut<'__w, T>

type ReadOnly = Ref<'__w, T>

impl<'__w, T: Component> QueryData for Ref<'__w, T>

type ReadOnly = Ref<'__w, T>

impl<'a> QueryData for EntityMut<'a>

type ReadOnly = EntityRef<'a>

impl<'a> QueryData for EntityRef<'a>

type ReadOnly = EntityRef<'a>

impl<'a> QueryData for FilteredEntityMut<'a>

type ReadOnly = FilteredEntityRef<'a>

impl<'a> QueryData for FilteredEntityRef<'a>

type ReadOnly = FilteredEntityRef<'a>

impl<F0: QueryData> QueryData for AnyOf<(F0,)>

type ReadOnly = AnyOf<(<F0 as QueryData>::ReadOnly,)>

impl<F0: QueryData, F1: QueryData> QueryData for AnyOf<(F0, F1)>

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

impl<F0: QueryData, F1: QueryData, F2: QueryData> QueryData for AnyOf<(F0, F1, F2)>

type ReadOnly = AnyOf<(<F0 as QueryData>::ReadOnly, <F1 as QueryData>::ReadOnly, <F2 as QueryData>::ReadOnly)>

impl<F0: QueryData, F1: QueryData, F2: QueryData, F3: QueryData> QueryData for AnyOf<(F0, F1, F2, F3)>

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

impl<F0: QueryData, F1: QueryData, F2: QueryData, F3: QueryData, F4: QueryData> QueryData for AnyOf<(F0, F1, F2, F3, F4)>

type ReadOnly = AnyOf<(<F0 as QueryData>::ReadOnly, <F1 as QueryData>::ReadOnly, <F2 as QueryData>::ReadOnly, <F3 as QueryData>::ReadOnly, <F4 as QueryData>::ReadOnly)>

impl<F0: QueryData, F1: QueryData, F2: QueryData, F3: QueryData, F4: QueryData, F5: QueryData> QueryData for AnyOf<(F0, F1, F2, F3, F4, F5)>

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

impl<F0: QueryData, F1: QueryData, F2: QueryData, F3: QueryData, F4: QueryData, F5: QueryData, F6: QueryData> QueryData for AnyOf<(F0, F1, F2, F3, F4, F5, F6)>

Trait bevy_ecs::query::QueryData

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

impl<'w, T: Component> QueryData for Mut<'w, T>

impl<'w, T: Component> QueryData for Ref<'w, T>