Trait valence::ecs::query::WorldQuery

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

    const IS_DENSE: bool;

    // Required methods
    fn shrink<'wlong, 'wshort>(item: Self::Item<'wlong>) -> Self::Item<'wshort>
       where 'wlong: '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,
    );
    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 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>,
    ) { ... }
}

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, matches_component_set, and fetch obey the following:

For each component mutably accessed by 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 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

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

type Item<'a>

The item returned by this WorldQuery For QueryData this will be the item returned by the query. For QueryFilter this will be either (), or a bool indicating whether the entity should be included or a tuple of such things.

type Fetch<'a>: Clone

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

type State: Send + Sync

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.

Required Methods§

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

This function manually implements subtyping for the query items.

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 this fetch.

§Safety

state must have been initialized (via WorldQuery::init_state) using the same world passed in to this function.

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.

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

Fetch Self::Item for either the given entity in the current Table, or for the given entity in the current Archetype. This must always be called after WorldQuery::set_table with a table_row in the range of the current Table or after WorldQuery::set_archetype with a entity in the current archetype.

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

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)

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

Object Safety§

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.

SAFETY: we call set_archetype for each member that implements Fetch

§

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

SAFETY: we call set_table for each member that implements Fetch

§

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

SAFETY: we call fetch for each member that implements Fetch.