Struct acute_ecs::prelude::Query

pub struct Query<V, F> where
    F: EntityFilter,
    V: for<'a> View<'a>,  {
    pub filter: F,
    // some fields omitted
}

Queries for entities within a World.

Examples

Queries can be constructed from any View type, including tuples of Views.

// A query which matches any entity with a `Position` component
let mut query = Read::<Position>::query();

// A query which matches any entity with both a `Position` and a `Velocity` component
let mut query = <(Read<Position>, Read<Velocity>)>::query();

The view determines what data is accessed, and whether it is accessed mutably or not.

// A query which writes `Position`, reads `Velocity` and reads `Model`
// Tags are read-only, and is distinguished from entity data reads with `Tagged<T>`.
let mut query = <(Write<Position>, Read<Velocity>, Tagged<Model>)>::query();

By default, a query will filter its results to include only entities with the data types accessed by the view. However, additional filters can be specified if needed:

#[derive(Copy, Clone, Debug, PartialEq)]
struct Static;

// A query which also requires that entities have the `Static` tag
let mut query = <(Read<Position>, Tagged<Model>)>::query().filter(tag::<Static>());

Filters can be combined with bitwise operators:

#[derive(Copy, Clone, Debug, PartialEq)]
struct Static;

// This query matches entities with positions and a model
// But it also requires that the entity is not static, or has moved (even if static)
let mut query = <(Read<Position>, Tagged<Model>)>::query()
    .filter(!tag::<Static>() | changed::<Position>());

Filters can be iterated through to pull data out of a World:

// A query which writes `Position`, reads `Velocity` and reads `Model`
// Tags are read-only, and is distinguished from entity data reads with `Tagged<T>`.
let mut query = <(Write<Position>, Read<Velocity>, Tagged<Model>)>::query();

for (mut pos, vel, model) in query.iter_mut(&mut world) {
    // `.iter` yields tuples of references to a single entity's data:
    // pos: &mut Position
    // vel: &Velocity
    // model: &Model
}

The lower level iter_chunks_mut function allows access to each underlying chunk of entity data. This allows you to run code for each tag value, or to retrieve a contiguous data slice.

let mut query = <(Write<Position>, Read<Velocity>, Tagged<Model>)>::query();

for chunk in query.iter_chunks_mut(&mut world) {
    let model = chunk.tag::<Model>();
    let positions = chunk.components_mut::<Position>();
    let velocities = chunk.components::<Velocity>();
}

The ChunkView yielded from iter_chunks_mut allows access to all shared data in the chunk (queried for or not), but entity data slices can only be accessed if they were requested in the query's view. Attempting to access other data types, or attempting to write to components that were only requested via a Read will panic.

Fields

filter: F

Implementations

impl<V, F> Query<V, F> where
    F: EntityFilter,
    V: for<'a> View<'a>, 

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

Adds an additional filter to the query.

pub unsafe fn iter_chunks_unchecked<T>(
    &'a self,
    world: &'data T
) -> ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter> where
    T: EntityStore, 

Gets an iterator which iterates through all chunks that match the query. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn iter_chunks<T>(
    &'a self,
    world: &'data T
) -> ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter> where
    T: EntityStore,
    V: ReadOnly, 

Gets an iterator which iterates through all chunks that match the query.

pub fn iter_chunks_mut<T>(
    &'a self,
    world: &'data mut T
) -> ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter> where
    T: EntityStore, 

Gets an iterator which iterates through all chunks that match the query.

pub unsafe fn iter_entities_unchecked<T>(
    &'a self,
    world: &'data T
) -> ChunkEntityIter<'data, V, ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter>> where
    T: EntityStore, 

Gets an iterator which iterates through all entity data that matches the query, and also yields the the Entity IDs. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn iter_entities<T>(
    &'a self,
    world: &'data T
) -> ChunkEntityIter<'data, V, ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter>> where
    T: EntityStore,
    V: ReadOnly, 

Gets an iterator which iterates through all entity data that matches the query, and also yields the the Entity IDs.

pub fn iter_entities_mut<T>(
    &'a self,
    world: &'data mut T
) -> ChunkEntityIter<'data, V, ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter>> where
    T: EntityStore, 

Gets an iterator which iterates through all entity data that matches the query, and also yields the the Entity IDs.

pub unsafe fn iter_unchecked<T>(
    &'a self,
    world: &'data T
) -> ChunkDataIter<'data, V, ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter>> where
    T: EntityStore, 

Gets an iterator which iterates through all entity data that matches the query. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn iter<T>(
    &'a self,
    world: &'data T
) -> ChunkDataIter<'data, V, ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter>> where
    T: EntityStore,
    V: ReadOnly, 

Gets an iterator which iterates through all entity data that matches the query.

pub fn iter_mut<T>(
    &'a self,
    world: &'data mut T
) -> ChunkDataIter<'data, V, ChunkViewIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter>> where
    T: EntityStore, 

Gets an iterator which iterates through all entity data that matches the query.

pub unsafe fn for_each_entities_unchecked<'data, T, W>(
    &'a self,
    world: &'data W,
    f: T
) where
    T: Fn((Entity, <<V as View<'data>>::Iter as Iterator>::Item)),
    W: EntityStore, 

Iterates through all entity data that matches the query. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn for_each_entities<'data, T, W>(&'a self, world: &'data W, f: T) where
    T: Fn((Entity, <<V as View<'data>>::Iter as Iterator>::Item)),
    V: ReadOnly,
    W: EntityStore, 

Iterates through all entity data that matches the query.

pub fn for_each_entities_mut<'data, T, W>(&'a self, world: &'data mut W, f: T) where
    T: Fn((Entity, <<V as View<'data>>::Iter as Iterator>::Item)),
    W: EntityStore, 

Iterates through all entity data that matches the query.

pub unsafe fn for_each_unchecked<'data, T, W>(&'a self, world: &'data W, f: T) where
    T: Fn(<<V as View<'data>>::Iter as Iterator>::Item),
    W: EntityStore, 

Iterates through all entity data that matches the query. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn for_each<'data, T, W>(&'a self, world: &'data W, f: T) where
    T: Fn(<<V as View<'data>>::Iter as Iterator>::Item),
    V: ReadOnly,
    W: EntityStore, 

Iterates through all entity data that matches the query.

pub fn for_each_mut<'data, T, W>(&'a self, world: &'data mut W, f: T) where
    T: Fn(<<V as View<'data>>::Iter as Iterator>::Item),
    W: EntityStore, 

Iterates through all entity data that matches the query.

pub fn components<T, W>(&self, world: &'a W) -> RefMapSet<'a, Vec<&'a T>> where
    T: Component,
    W: EntityStore, 

Returns a RefMapSet of all components of a given type. This simplifies getting a slice of references to all components of type T that match the filter. This can be useful for passing to other libraries or FFI.

pub fn components_mut<T, W>(
    &self,
    world: &'a mut W
) -> RefMapMutSet<'a, Vec<&'a mut T>> where
    T: Component,
    W: EntityStore, 

Returns a RefMapMutSet of all components of a given type. This simplifies getting a slice of mutable refs to all components of type T that match the filter.

pub unsafe fn par_iter_chunks_unchecked<'data, W>(
    &'a self,
    world: &'data W
) -> ChunkViewParIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter> where
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'data>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'data>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'data>>>::Iter: FissileIterator, 

Gets an iterator which iterates through all chunks that match the query in parallel. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn par_iter_chunks<'data, W>(
    &'a self,
    world: &'data W
) -> ChunkViewParIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter> where
    V: ReadOnly,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'data>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'data>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'data>>>::Iter: FissileIterator, 

Gets an iterator which iterates through all chunks that match the query in parallel.

pub fn par_iter_chunks_mut<'data, W>(
    &'a self,
    world: &'data mut W
) -> ChunkViewParIter<'data, 'a, V, <F as EntityFilter>::ArchetypeFilter, <F as EntityFilter>::ChunksetFilter, <F as EntityFilter>::ChunkFilter> where
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'data>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'data>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'data>>>::Iter: FissileIterator, 

Gets an iterator which iterates through all chunks that match the query in parallel.

pub unsafe fn par_entities_for_each_unchecked<'a, T, W>(
    &'a self,
    world: &'a W,
    f: T
) where
    T: Fn((Entity, <<V as View<'a>>::Iter as Iterator>::Item)) + Send + Sync,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all entity data that matches the query in parallel. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn par_entities_for_each<'a, T, W>(&'a self, world: &'a W, f: T) where
    T: Fn((Entity, <<V as View<'a>>::Iter as Iterator>::Item)) + Send + Sync,
    V: ReadOnly,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all entity data that matches the query in parallel.

pub fn par_entities_for_each_mut<'a, T, W>(&'a self, world: &'a mut W, f: T) where
    T: Fn((Entity, <<V as View<'a>>::Iter as Iterator>::Item)) + Send + Sync,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all entity data that matches the query in parallel.

pub unsafe fn par_for_each_unchecked<'a, T, W>(&'a self, world: &'a W, f: T) where
    T: Fn(<<V as View<'a>>::Iter as Iterator>::Item) + Send + Sync,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all entity data that matches the query in parallel. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn par_for_each<'a, T, W>(&'a self, world: &'a W, f: T) where
    T: Fn(<<V as View<'a>>::Iter as Iterator>::Item) + Send + Sync,
    V: ReadOnly,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all entity data that matches the query in parallel.

pub fn par_for_each_mut<'a, T, W>(&'a self, world: &'a mut W, f: T) where
    T: Fn(<<V as View<'a>>::Iter as Iterator>::Item) + Send + Sync,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all entity data that matches the query in parallel.

pub unsafe fn par_for_each_chunk_unchecked<'a, T, W>(
    &'a self,
    world: &'a W,
    f: T
) where
    T: Fn(Chunk<'a, V>) + Send + Sync,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all chunks that match the query in parallel. Does not perform static borrow checking.

Safety

The normal borrowing restrictions apply for the duration of the iteration:

• Components borrowed with Read access must not be borrowed mutably elsewhere.
• Components borrowed with Write access must not be borrowed elsewhere at all.

Panics

This function may panic if other code is concurrently accessing the same components.

pub fn par_for_each_chunk<'a, T, W>(&'a self, world: &'a W, f: T) where
    T: Fn(Chunk<'a, V>) + Send + Sync,
    V: ReadOnly,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all chunks that match the query in parallel.

pub fn par_for_each_chunk_mut<'a, T, W>(&'a self, world: &'a mut W, f: T) where
    T: Fn(Chunk<'a, V>) + Send + Sync,
    W: EntityStore,
    <<F as EntityFilter>::ArchetypeFilter as Filter<ArchetypeFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunksetFilter as Filter<ChunksetFilterData<'a>>>::Iter: FissileIterator,
    <<F as EntityFilter>::ChunkFilter as Filter<ChunkFilterData<'a>>>::Iter: FissileIterator, 

Iterates through all chunks that match the query in parallel.

Trait Implementations

impl<V, F> Clone for Query<V, F> where
    F: EntityFilter + Clone,
    V: for<'a> View<'a>, 

fn clone(&self) -> Query<V, F>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<AV, AF> QuerySet for Query<AV, AF> where
    AF: EntityFilter + Send + Sync,
    AV: for<'v> View<'v>, 

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

Returns the archetypes accessed by this collection of queries. This allows for caching effiency and granularity for system dispatching.