Trait WorldQuery

pub unsafe trait WorldQuery {
    type Fetch<'a>: Clone;
    type State: Send + Sync + Sized;

    const IS_DENSE: bool;

    // Required methods
    fn shrink_fetch<'wlong: 'wshort, 'wshort>(
        fetch: Self::Fetch<'wlong>,
    ) -> Self::Fetch<'wshort>;
    unsafe fn init_fetch<'w>(
        world: UnsafeWorldCell<'w>,
        state: &Self::State,
        last_run: Tick,
        this_run: Tick,
    ) -> 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,
    );
    fn update_component_access(
        state: &Self::State,
        access: &mut FilteredAccess<ComponentId>,
    );
    fn init_state(world: &mut World) -> Self::State;
    fn get_state(components: &Components) -> Option<Self::State>;
    fn matches_component_set(
        state: &Self::State,
        set_contains_id: &impl Fn(ComponentId) -> bool,
    ) -> bool;

    // Provided method
    fn set_access(
        _state: &mut Self::State,
        _access: &FilteredAccess<ComponentId>,
    ) { ... }
}

Types that can be used as parameters in a Query. Types that implement this should also implement either QueryData or QueryFilter

Safety

Implementor must ensure that update_component_access, matches_component_set, QueryData::fetch, QueryFilter::filter_fetch and init_fetch obey the following:

• For each component mutably accessed by QueryData::fetch, update_component_access should add write access unless read or write access has already been added, in which case it should panic.
• For each component readonly accessed by QueryData::fetch or QueryFilter::filter_fetch, update_component_access should add read access unless write access has already been added, in which case it should panic.
• If fetch mutably accesses the same component twice, update_component_access should panic.
• update_component_access may not add a Without filter for a component unless matches_component_set always returns false when the component set contains that component.
• update_component_access may not add a With filter for a component unless matches_component_set always returns false when the component set doesn’t contain that component.
• In cases where the query represents a disjunction (such as an Or filter) where each element is a valid WorldQuery, the following rules must be obeyed:
  • matches_component_set must be a disjunction of the element’s implementations
  • update_component_access must replace the filters with a disjunction of filters
  • Each filter in that disjunction must be a conjunction of the corresponding element’s filter with the previous access
• For each resource readonly accessed by init_fetch, update_component_access should add read access.
• Mutable resource access is not allowed.

When implementing update_component_access, note that add_read and add_write both also add a With filter, whereas extend_access does not change the filters.

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 QueryData::fetch can be called for iterators. If this returns false, WorldQuery::set_archetype must be used before QueryData::fetch can be called for iterators.

Required Associated Types

type Fetch<'a>: Clone

Per archetype/table state retrieved by this WorldQuery to compute Self::Item for each entity.

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 Methods

fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

This function manually implements subtyping for the query fetches.

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, state: &Self::State, last_run: Tick, this_run: Tick, ) -> Self::Fetch<'w>

Creates a new instance of Self::Fetch, by combining data from the World with the cached Self::State. Readonly accesses resources registered in WorldQuery::update_component_access.

Safety

• state must have been initialized (via WorldQuery::init_state) using the same world passed in to this function.
• world must have the right to access any access registered in update_component_access.
• There must not be simultaneous resource access conflicting with readonly resource access registered in WorldQuery::update_component_access.

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

Adjusts internal state to account for the next Archetype. This will always be called on archetypes that match this WorldQuery.

Safety

• archetype and tables must be from the same World that WorldQuery::init_state was called on.
• table must correspond to archetype.
• state must be the State that fetch was initialized with.

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

Adjusts internal state to account for the next Table. This will always be called on tables that match this WorldQuery.

Safety

• table must be from the same World that WorldQuery::init_state was called on.
• state must be the State that fetch was initialized with.

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

Adds any component accesses used by this WorldQuery to access.

Used to check which queries are disjoint and can run in parallel

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

Creates and initializes a State for this WorldQuery type.

fn get_state(components: &Components) -> Option<Self::State>

Attempts to initialize a State for this WorldQuery type using read-only access to Components.

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

Returns true if this query matches a set of components. Otherwise, returns false.

Used to check which Archetypes can be skipped by the query (if none of the Components match). This is how archetypal query filters like With work.

Provided Methods

fn set_access(_state: &mut Self::State, _access: &FilteredAccess<ComponentId>)

Sets available accesses for implementors with dynamic access such as FilteredEntityRef or FilteredEntityMut.

Called when constructing a QueryLens or calling QueryState::from_builder

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 WorldQuery for ()

SAFETY: fetch accesses are the conjunction of the subqueries’ accesses This is sound because update_component_access adds accesses according to the implementations of all the subqueries. update_component_access adds all With and Without filters from the subqueries. This is sound because matches_component_set always returns false if any the subqueries’ implementations return false.

const IS_DENSE: bool = true

type Fetch<'w> = ()

type State = ()

fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, state: &Self::State, last_run: Tick, this_run: Tick, ) -> 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, )

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

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

fn get_state(components: &Components) -> Option<Self::State>

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

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

SAFETY: fetch accesses a single component mutably. This is sound because update_component_access and update_archetype_component_access add write access for that component and panic when appropriate. update_component_access adds a With filter for a component. This is sound because matches_component_set returns whether the set contains that component.

const IS_DENSE: bool

type Fetch<'w> = WriteFetch<'w, T>

type State = ComponentId

fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, component_id: &ComponentId, last_run: Tick, this_run: Tick, ) -> WriteFetch<'w, T>

unsafe fn set_archetype<'w>( fetch: &mut WriteFetch<'w, T>, component_id: &ComponentId, _archetype: &'w Archetype, table: &'w Table, )

unsafe fn set_table<'w>( fetch: &mut WriteFetch<'w, T>, component_id: &ComponentId, table: &'w Table, )

fn update_component_access( component_id: &ComponentId, access: &mut FilteredAccess<ComponentId>, )

fn init_state(world: &mut World) -> ComponentId

fn get_state(components: &Components) -> Option<Self::State>

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

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

This trait is implemented for tuples up to 16 items long. SAFETY: fetch accesses are the conjunction of the subqueries’ accesses This is sound because update_component_access adds accesses according to the implementations of all the subqueries. update_component_access adds all With and Without filters from the subqueries. This is sound because matches_component_set always returns false if any the subqueries’ implementations return false.

const IS_DENSE: bool

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

type State = (<F as WorldQuery>::State,)

fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, state: &Self::State, last_run: Tick, this_run: Tick, ) -> 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, )

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

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

fn get_state(components: &Components) -> Option<Self::State>

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

impl<T: Component> WorldQuery for &T

SAFETY: fetch accesses a single component in a readonly way. This is sound because update_component_access and update_archetype_component_access add read access for that component and panic when appropriate. update_component_access adds a With filter for a component. This is sound because matches_component_set returns whether the set contains that component.

const IS_DENSE: bool

type Fetch<'w> = ReadFetch<'w, T>

type State = ComponentId

fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, component_id: &ComponentId, _last_run: Tick, _this_run: Tick, ) -> ReadFetch<'w, T>

unsafe fn set_archetype<'w>( fetch: &mut ReadFetch<'w, T>, component_id: &ComponentId, _archetype: &'w Archetype, table: &'w Table, )

unsafe fn set_table<'w>( fetch: &mut ReadFetch<'w, T>, component_id: &ComponentId, table: &'w Table, )

fn update_component_access( component_id: &ComponentId, access: &mut FilteredAccess<ComponentId>, )

fn init_state(world: &mut World) -> ComponentId

fn get_state(components: &Components) -> Option<Self::State>

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

impl<T: WorldQuery> WorldQuery for Option<T>

SAFETY: fetch might access any components that T accesses. This is sound because update_component_access and update_archetype_component_access add the same accesses as T. Filters are unchanged.

const IS_DENSE: bool = T::IS_DENSE

type Fetch<'w> = OptionFetch<'w, T>

type State = <T as WorldQuery>::State

fn shrink_fetch<'wlong: 'wshort, 'wshort>( fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

unsafe fn init_fetch<'w>( world: UnsafeWorldCell<'w>, state: &T::State, last_run: Tick, this_run: Tick, ) -> OptionFetch<'w, T>

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

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

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

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

fn get_state(components: &Components) -> Option<Self::State>

fn matches_component_set( _state: &T::State, _set_contains_id: &impl Fn(ComponentId) -> bool, ) -> bool

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

SAFETY: update_component_access and update_archetype_component_access do nothing. This is sound because fetch does not access components.

const IS_DENSE: bool = true

type Fetch<'a> = ()

type State = ()

fn shrink_fetch<'wlong: 'wshort, 'wshort>( _fetch: Self::Fetch<'wlong>, ) -> Self::Fetch<'wshort>

unsafe fn init_fetch<'w>( _world: UnsafeWorldCell<'w>, _state: &Self::State, _last_run: Tick, _this_run: Tick, ) -> 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, )

fn update_component_access( _state: &Self::State, _access: &mut FilteredAccess<ComponentId>, )

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

fn get_state(_components: &Components) -> Option<Self::State>

fn matches_component_set( _state: &Self::State, _set_contains_id: &impl Fn(ComponentId) -> bool, ) -> bool

Implementors

impl WorldQuery for &Archetype

SAFETY: update_component_access and update_archetype_component_access do nothing. This is sound because fetch does not access components.

const IS_DENSE: bool = true

type Fetch<'w> = (&'w Entities, &'w Archetypes)

type State = ()

impl WorldQuery for Entity

SAFETY: update_component_access and update_archetype_component_access do nothing. This is sound because fetch does not access components.

const IS_DENSE: bool = true

type Fetch<'w> = ()

type State = ()

impl WorldQuery for EntityLocation

SAFETY: update_component_access and update_archetype_component_access do nothing. This is sound because fetch does not access components.

const IS_DENSE: bool = true

type Fetch<'w> = &'w Entities

type State = ()

impl WorldQuery for NameOrEntity

const IS_DENSE: bool = true

type Fetch<'__w> = NameOrEntityFetch<'__w>

type State = NameOrEntityState

impl WorldQuery for AnyOf<()>

SAFETY: fetch accesses are a subset of the subqueries’ accesses This is sound because update_component_access and update_archetype_component_access adds accesses according to the implementations of all the subqueries. update_component_access replaces the filters with a disjunction where every element is a conjunction of the previous filters and the filters of one of the subqueries. This is sound because matches_component_set returns a disjunction of the results of the subqueries’ implementations.

const IS_DENSE: bool = true

type Fetch<'w> = ()

type State = ()

impl WorldQuery for Or<()>

SAFETY: QueryFilter::filter_fetch accesses are a subset of the subqueries’ accesses This is sound because update_component_access adds accesses according to the implementations of all the subqueries. update_component_access replace the filters with a disjunction where every element is a conjunction of the previous filters and the filters of one of the subqueries. This is sound because matches_component_set returns a disjunction of the results of the subqueries’ implementations.

const IS_DENSE: bool = true

type Fetch<'w> = ()

type State = ()

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

When Mut<T> is used in a query, it will be converted to Ref<T> when transformed into its read-only form, providing access to change detection methods.

By contrast &mut T will result in a Mut<T> item in mutable form to record mutations, but result in a bare &T in read-only form.

SAFETY: fetch accesses a single component mutably. This is sound because update_component_access and update_archetype_component_access add write access for that component and panic when appropriate. update_component_access adds a With filter for a component. This is sound because matches_component_set returns whether the set contains that component.

const IS_DENSE: bool = <&mut T as WorldQuery>::IS_DENSE

type Fetch<'w> = WriteFetch<'w, T>

type State = ComponentId

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

SAFETY: fetch accesses a single component in a readonly way. This is sound because update_component_access and update_archetype_component_access add read access for that component and panic when appropriate. update_component_access adds a With filter for a component. This is sound because matches_component_set returns whether the set contains that component.

const IS_DENSE: bool

type Fetch<'w> = RefFetch<'w, T>

type State = ComponentId

impl<'a> WorldQuery for EntityMut<'a>

SAFETY: The accesses of Self::ReadOnly are a subset of the accesses of Self

const IS_DENSE: bool = true

type Fetch<'w> = UnsafeWorldCell<'w>

type State = ()

impl<'a> WorldQuery for EntityRef<'a>

SAFETY: fetch accesses all components in a readonly way. This is sound because update_component_access and update_archetype_component_access set read access for all components and panic when appropriate. Filters are unchanged.

const IS_DENSE: bool = true

type Fetch<'w> = UnsafeWorldCell<'w>

type State = ()

impl<'a> WorldQuery for FilteredEntityMut<'a>

SAFETY: The accesses of Self::ReadOnly are a subset of the accesses of Self

const IS_DENSE: bool = false

type Fetch<'w> = (UnsafeWorldCell<'w>, Access<ComponentId>)

type State = FilteredAccess<ComponentId>

impl<'a> WorldQuery for FilteredEntityRef<'a>

SAFETY: The accesses of Self::ReadOnly are a subset of the accesses of Self

const IS_DENSE: bool = false

type Fetch<'w> = (UnsafeWorldCell<'w>, Access<ComponentId>)

type State = FilteredAccess<ComponentId>

impl<'a, B> WorldQuery for EntityMutExcept<'a, B>

where B: Bundle,

SAFETY: EntityMutExcept guards access to all components in the bundle B and populates Access values so that queries that conflict with this access are rejected.

const IS_DENSE: bool = true

type Fetch<'w> = UnsafeWorldCell<'w>

type State = SmallVec<[ComponentId; 4]>

impl<'a, B> WorldQuery for EntityRefExcept<'a, B>

where B: Bundle,

SAFETY: EntityRefExcept guards access to all components in the bundle B and populates Access values so that queries that conflict with this access are rejected.

const IS_DENSE: bool = true

type Fetch<'w> = UnsafeWorldCell<'w>

type State = SmallVec<[ComponentId; 4]>

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

This trait is implemented for tuples up to 16 items long. SAFETY: QueryFilter::filter_fetch accesses are a subset of the subqueries’ accesses This is sound because update_component_access adds accesses according to the implementations of all the subqueries. update_component_access replace the filters with a disjunction where every element is a conjunction of the previous filters and the filters of one of the subqueries. This is sound because matches_component_set returns a disjunction of the results of the subqueries’ implementations.

const IS_DENSE: bool

type Fetch<'w> = (OrFetch<'w, F>,)

type State = (<F as WorldQuery>::State,)

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

This trait is implemented for tuples up to 16 items long. SAFETY: fetch accesses are a subset of the subqueries’ accesses This is sound because update_component_access and update_archetype_component_access adds accesses according to the implementations of all the subqueries. update_component_access replaces the filters with a disjunction where every element is a conjunction of the previous filters and the filters of one of the subqueries. This is sound because matches_component_set returns a disjunction of the results of the subqueries’ implementations.

const IS_DENSE: bool

type Fetch<'w> = ((<F as WorldQuery>::Fetch<'w>, bool),)

type State = (<F as WorldQuery>::State,)

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

SAFETY: QueryFilter::filter_fetch accesses a single component in a readonly way. This is sound because update_component_access adds read access for that component and panics when appropriate. update_component_access adds a With filter for a component. This is sound because matches_component_set returns whether the set contains that component.

const IS_DENSE: bool

type Fetch<'w> = AddedFetch<'w, T>

type State = ComponentId

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

SAFETY: fetch accesses a single component in a readonly way. This is sound because update_component_access add read access for that component and panics when appropriate. update_component_access adds a With filter for a component. This is sound because matches_component_set returns whether the set contains that component.

const IS_DENSE: bool

type Fetch<'w> = ChangedFetch<'w, T>

type State = ComponentId

impl<T: Component> WorldQuery for Has<T>

SAFETY: update_component_access and update_archetype_component_access do nothing. This is sound because fetch does not access components.

const IS_DENSE: bool

type Fetch<'w> = bool

type State = ComponentId

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

SAFETY: update_component_access does not add any accesses. This is sound because QueryFilter::filter_fetch does not access any components. update_component_access adds a With filter for T. This is sound because matches_component_set returns whether the set contains the component.

const IS_DENSE: bool

type Fetch<'w> = ()

type State = ComponentId

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

SAFETY: update_component_access does not add any accesses. This is sound because QueryFilter::filter_fetch does not access any components. update_component_access adds a Without filter for T. This is sound because matches_component_set returns whether the set does not contain the component.

const IS_DENSE: bool

type Fetch<'w> = ()

type State = ComponentId