Trait WorldQuery

Source

pub unsafe trait WorldQuery {
    type Fetch<'w>: 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, 's>(
        world: UnsafeWorldCell<'w>,
        state: &'s Self::State,
        last_run: Tick,
        this_run: Tick,
    ) -> Self::Fetch<'w>;
    unsafe fn set_archetype<'w, 's>(
        fetch: &mut Self::Fetch<'w>,
        state: &'s Self::State,
        archetype: &'w Archetype,
        table: &'w Table,
    );
    unsafe fn set_table<'w, 's>(
        fetch: &mut Self::Fetch<'w>,
        state: &'s Self::State,
        table: &'w Table,
    );
    fn update_component_access(state: &Self::State, access: &mut FilteredAccess);
    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 methods
    fn init_nested_access(
        _state: &Self::State,
        _system_name: Option<&str>,
        _component_access_set: &mut FilteredAccessSet,
        _world: UnsafeWorldCell<'_>,
    ) { ... }
    fn update_archetypes(_state: &mut Self::State, _world: UnsafeWorldCell<'_>) { ... }
}

Expand description

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, QueryData::provide_extra_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 or QueryData::provide_extra_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 or QueryData::provide_extra_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.
Any access added during QueryData::provide_extra_access must be a subset of available_access, and must not conflict with any access in access.

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§

Source

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§

Source

type Fetch<'w>: Clone

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

Source

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§

Source

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

This function manually implements subtyping for the query fetches.

Source

unsafe fn init_fetch<'w, 's>( world: UnsafeWorldCell<'w>, state: &'s 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 WorldQuery::update_component_access or WorldQuery::init_nested_access.
WorldQuery::update_component_access must not request conflicting access. If Self is ReadOnlyQueryData or QueryFilter, the access is read-only and can never conflict. Otherwise, WorldQuery::update_component_access must be called to ensure it does not panic.
WorldQuery::init_nested_access must not request conflicting access. If Self is ReadOnlyQueryData or QueryFilter, the access is read-only and can never conflict. If Self is SingleEntityQueryData, there is no external access and it cannot conflict. Otherwise, WorldQuery::init_nested_access must be called to ensure it does not panic.

Source

unsafe fn set_archetype<'w, 's>( fetch: &mut Self::Fetch<'w>, state: &'s 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.

Source

unsafe fn set_table<'w, 's>( fetch: &mut Self::Fetch<'w>, state: &'s 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.

Source

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

Adds any component accesses to the current entity used by this WorldQuery to access.

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

Source

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

Creates and initializes a State for this WorldQuery type.

Source

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

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

Source

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§

Source

fn init_nested_access( _state: &Self::State, _system_name: Option<&str>, _component_access_set: &mut FilteredAccessSet, _world: UnsafeWorldCell<'_>, )

Adds any component accesses to other entities used by this WorldQuery.

This method must panic if the access would conflict with any existing access in the FilteredAccessSet.

This is used for queries to request access to entities other than the current one, such as to read resources or to follow relations.

Source

fn update_archetypes(_state: &mut Self::State, _world: UnsafeWorldCell<'_>)

Called when the query state is updating its archetype cache. This can be used by nested queries to update their internal archetype caches.

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.

Trait WorldQuery Copy item path

§Safety

Required Associated Constants§

const IS_DENSE: bool

Required Associated Types§

type Fetch<'w>: Clone

type State: Send + Sync + Sized

Required Methods§

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

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

§Safety

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

§Safety

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

§Safety

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

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 Methods§

fn init_nested_access( _state: &Self::State, _system_name: Option<&str>, _component_access_set: &mut FilteredAccessSet, _world: UnsafeWorldCell<'_>, )

fn update_archetypes(_state: &mut Self::State, _world: UnsafeWorldCell<'_>)

Dyn Compatibility§

Implementations on Foreign Types§

impl WorldQuery for ()

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

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

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

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

fn init_nested_access( state: &Self::State, _system_name: Option<&str>, _component_access_set: &mut FilteredAccessSet, _world: UnsafeWorldCell<'_>, )

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

fn update_archetypes(state: &mut Self::State, _world: UnsafeWorldCell<'_>)

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

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, 's>( 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, )

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<F0: WorldQuery, F1: WorldQuery> WorldQuery for (F0, F1)

const IS_DENSE: bool

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

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

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

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

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

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

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

fn init_nested_access( state: &Self::State, _system_name: Option<&str>, _component_access_set: &mut FilteredAccessSet, _world: UnsafeWorldCell<'_>, )

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

fn update_archetypes(state: &mut Self::State, _world: UnsafeWorldCell<'_>)

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

const IS_DENSE: bool

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

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

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

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

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

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

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

fn init_nested_access( state: &Self::State, _system_name: Option<&str>, _component_access_set: &mut FilteredAccessSet, _world: UnsafeWorldCell<'_>, )

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

fn update_archetypes(state: &mut Self::State, _world: UnsafeWorldCell<'_>)

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

const IS_DENSE: bool

Trait WorldQuery

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