Struct legion::Query

pub struct Query<V: IntoView, F: EntityFilter = <<V as IntoView>::View as DefaultFilter>::Filter> { /* fields omitted */ }

Provides efficient means to iterate and filter entities in a world.

See the module-level documentation for more details and examples.

Implementations

impl<V: IntoView, F: EntityFilter> Query<V, F>

pub fn new() -> Self

Consructs a new Query

pub fn filter<T: EntityFilter>(
    self,
    filter: T
) -> Query<V, <F as BitAnd<T>>::Output> where
    F: BitAnd<T>,
    <F as BitAnd<T>>::Output: EntityFilter, 

Adds an additional filter to the query.

pub unsafe fn get_unchecked<'query, 'world, T>(
    &'query mut self,
    world: &'world T,
    entity: Entity
) -> Result<<V::View as View<'world>>::Element, EntityAccessError> where
    T: EntityStore, 

Returns the components for a single entity.

This function will not evaluate the query’s dynamic filters. This means, for example, that calling get on all entities in an archetype will not prevent maybe_changed from returning those entities the next time the query is iterated.

Safety

This function allows mutable access via a shared world reference. The caller is responsible for ensuring that no component accesses may create mutable aliases.

pub fn get_mut<'query, 'world, T>(
    &'query mut self,
    world: &'world mut T,
    entity: Entity
) -> Result<<V::View as View<'world>>::Element, EntityAccessError> where
    T: EntityStore, 

Returns the components for a single entity.

pub fn get<'query, 'world, T>(
    &'query mut self,
    world: &'world T,
    entity: Entity
) -> Result<<V::View as View<'world>>::Element, EntityAccessError> where
    T: EntityStore,
    <V::View as View<'world>>::Fetch: ReadOnlyFetch, 

Returns the components for a single entity.

pub unsafe fn iter_chunks_unchecked<'query, 'world, T: EntityStore>(
    &'query mut self,
    world: &'world T
) -> ChunkIter<'world, 'query, V::View, F>

Returns an iterator which will yield all entity chunks which match the query.

Each chunk contains slices of components for entities which all have the same component layout.

Safety

This function allows mutable access via a shared world reference. The caller is responsible for ensuring that no component accesses may create mutable aliases.

pub fn iter_chunks_mut<'query, 'world, T: EntityStore>(
    &'query mut self,
    world: &'world mut T
) -> ChunkIter<'world, 'query, V::View, F>

Returns an iterator which will yield all entity chunks which match the query.

Each chunk contains slices of components for entities which all have the same component layout.

pub fn iter_chunks<'query, 'world, T: EntityStore>(
    &'query mut self,
    world: &'world T
) -> ChunkIter<'world, 'query, V::View, F> where
    <V::View as View<'world>>::Fetch: ReadOnlyFetch, 

Returns an iterator which will yield all entity chunks which match the query.

Each chunk contains slices of components for entities which all have the same component layout.
Only usable with queries whose views are read-only.

pub unsafe fn iter_unchecked<'query, 'world, T: EntityStore>(
    &'query mut self,
    world: &'world T
) -> Flatten<ChunkIter<'world, 'query, V::View, F>>

Returns an iterator which will yield all components which match the query.

Prefer for_each_unchecked as it offers better performance.

Safety

This function allows mutable access via a shared world reference. The caller is responsible for ensuring that no component accesses may create mutable aliases.

pub fn iter_mut<'query, 'world, T: EntityStore>(
    &'query mut self,
    world: &'world mut T
) -> Flatten<ChunkIter<'world, 'query, V::View, F>>

Returns an iterator which will yield all components which match the query.

Prefer for_each_mut as it yields better performance.

pub fn iter<'query, 'world, T: EntityStore>(
    &'query mut self,
    world: &'world T
) -> Flatten<ChunkIter<'world, 'query, V::View, F>> where
    <V::View as View<'world>>::Fetch: ReadOnlyFetch, 

Returns an iterator which will yield all components which match the query.

Prefer for_each as it yields better performance.
Only usable with queries whose views are read-only.

pub unsafe fn for_each_chunk_unchecked<'query, 'world, T: EntityStore, Body>(
    &'query mut self,
    world: &'world T,
    f: Body
) where
    Body: FnMut(ChunkView<'_, <V::View as View<'world>>::Fetch>), 

Iterates through all entity chunks which match the query.

Each chunk contains slices of components for entities which all have the same component layout.

Safety

This function allows mutable access via a shared world reference. The caller is responsible for ensuring that no component accesses may create mutable aliases.

pub fn for_each_chunk_mut<'query, 'world, T: EntityStore, Body>(
    &'query mut self,
    world: &'world mut T,
    f: Body
) where
    Body: FnMut(ChunkView<'_, <V::View as View<'world>>::Fetch>), 

Iterates through all entity chunks which match the query.

Each chunk contains slices of components for entities which all have the same component layout.

pub fn for_each_chunk<'query, 'world, T: EntityStore, Body>(
    &'query mut self,
    world: &'world T,
    f: Body
) where
    Body: FnMut(ChunkView<'_, <V::View as View<'world>>::Fetch>),
    <V::View as View<'world>>::Fetch: ReadOnlyFetch, 

Iterates through all entity chunks which match the query.

Each chunk contains slices of components for entities which all have the same component layout.
Only usable with queries whose views are read-only.

pub unsafe fn for_each_unchecked<'query, 'world, T: EntityStore, Body>(
    &'query mut self,
    world: &'world T,
    f: Body
) where
    Body: FnMut(<V::View as View<'world>>::Element), 

Iterates through all components which match the query.

Safety

This function allows mutable access via a shared world reference. The caller is responsible for ensuring that no component accesses may create mutable aliases.

pub fn for_each_mut<'query, 'world, T: EntityStore, Body>(
    &'query mut self,
    world: &'world mut T,
    f: Body
) where
    Body: FnMut(<V::View as View<'world>>::Element), 

Iterates through all components which match the query.

pub fn for_each<'query, 'world, T: EntityStore, Body>(
    &'query mut self,
    world: &'world T,
    f: Body
) where
    Body: FnMut(<V::View as View<'world>>::Element),
    <V::View as View<'world>>::Fetch: ReadOnlyFetch, 

Iterates through all components which match the query.

Only usable with queries whose views are read-only.

Trait Implementations

impl<V: IntoView, F: EntityFilter> Default for Query<V, F>

fn default() -> Self

Returns the “default value” for a type.

impl<AV, AF> QuerySet for Query<AV, AF> where
    AV: IntoView + Send + Sync,
    AF: EntityFilter, 

fn filter_archetypes(&mut self, world: &World, bitset: &mut BitSet)

Evaluates the queries and records which archetypes they require access to into a bitset.