Trait bevy_ecs::query::WorldQuery

source ·

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

    const IS_DENSE: bool;

    // Required methods
    fn shrink<'wlong: 'wshort, 'wshort>(
        item: Self::Item<'wlong>
    ) -> Self::Item<'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§

source

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.

source

type Fetch<'a>: Clone

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

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

source

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

This function manually implements subtyping for the query items.

source

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.

source

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.

source

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.

source

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.

source

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

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)

Provided Methods§

source

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.

Trait bevy_ecs::query::WorldQueryCopy item path

§Safety

Required Associated Types§

type Item<'a>

type Fetch<'a>: Clone

type State: Send + Sync + Sized

Required Associated Constants§

const IS_DENSE: bool

Required Methods§

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

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

§Safety

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

§Safety

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

§Safety

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

§Safety

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

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

Object Safety§

Implementations on Foreign Types§

impl WorldQuery for ()

type Fetch<'w> = ()

type Item<'w> = ()

type State = ()

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

unsafe fn init_fetch<'w>( _world: UnsafeWorldCell<'w>, state: &Self::State, _last_run: Tick, _this_run: Tick ) -> Self::Fetch<'w>

const IS_DENSE: bool = true

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

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

type Item<'w> = Mut<'w, T>

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

type State = ComponentId

fn shrink<'wlong: 'wshort, 'wshort>(item: Mut<'wlong, T>) -> Mut<'wshort, T>

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

const IS_DENSE: bool = _

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 )

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

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

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

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

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

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

unsafe fn init_fetch<'w>( _world: UnsafeWorldCell<'w>, state: &Self::State, _last_run: Tick, _this_run: Tick ) -> Self::Fetch<'w>

const IS_DENSE: bool = _

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

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

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

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

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

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

unsafe fn init_fetch<'w>( _world: UnsafeWorldCell<'w>, state: &Self::State, _last_run: Tick, _this_run: Tick ) -> Self::Fetch<'w>

const IS_DENSE: bool = _

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

Trait bevy_ecs::query::WorldQuery

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