Struct Query 

pub struct Query<T>(/* private fields */)
where
    T: IsQuery + ?Sized;

Queries are used to iterate over matching bundles of components.

Querys are written as a tuple of component column types, where each position in the tuple denotes a column value in each item of the resulting query iterator. Each item column type will be wrapped in Entry in the resulting query iterator.

For example: Query<(&mut f32, &String)> will result in an iterator of items with the type (&mut Entry<f32>, &Entry<String>).

Creating queries

Some functions query immidiately and return QueryGuard:

• Components::query
• Entity::visit

With these functions you pass component column types as a type parameter:

let mut query = world
    .get_components_mut()
    .query::<(&f32, &String)>();
for (f32, string) in query.iter_mut() {
    //...
}

System data queries

Query implements Edges, which allows you to use queries as fields inside system data structs:

#[derive(Edges)]
struct MySystemData {
    counter: ViewMut<u32>,
    // we use &'static to avoid introducing a lifetime
    q_f32_and_string: Query<(&'static f32, &'static String)>,
}

Which means queries may be visited from outside the world, or used as the input to a system:

use apecs::*;

#[derive(Edges)]
struct MySystemData {
    tracker: ViewMut<u64>,
    // We can use Mut and Ref which are aliases for &'static mut and &'static.
    q_f32_and_string: Query<(Mut<f32>, Ref<String>)>,
}

fn my_system(mut data: MySystemData) -> Result<(), GraphError> {
    for (f32, string) in data.q_f32_and_string.query().iter_mut() {
        if f32.was_modified_since(*data.tracker) {
            **f32 += 1.0;
            println!("set entity {} = {}", f32.id(), **f32);
        }
    }
    *data.tracker = apecs::current_iteration();
    ok()
}

let mut world = World::default();
world.add_subgraph(graph!(my_system));
world.tick().unwrap();

Iterating queries

Below we use mutable and immutable reference types in our query to include either a mutable or immutable reference to those components:

use apecs::*;

struct Position(pub f32);
struct Velocity(pub f32);
struct Acceleration(pub f32);

fn create(mut entities: ViewMut<Entities>) -> Result<(), GraphError> {
    for i in 0..100 {
        entities.create().insert_bundle((
            Position(0.0),
            Velocity(0.0),
            Acceleration(i as f32),
        ));
    }
     
    /// This system ends after one tick
    end()
}

fn accelerate(q_accelerate: Query<(&mut Velocity, &Acceleration)>) -> Result<(), GraphError> {
    for (v, a) in q_accelerate.query().iter_mut() {
        v.0 += a.0;
    }
    ok()
}

fn position(q_move: Query<(&mut Position, &Velocity)>) -> Result<(), GraphError> {
    for (p, v) in q_move.query().iter_mut() {
        p.0 += v.0;
    }
    ok()
}

let mut world = World::default();
world.add_subgraph(graph!(create, accelerate, position));
world.tick().unwrap();

Implementations

impl<Q> Query<Q>

where Q: IsQuery + ?Sized,

pub fn query(&self) -> QueryGuard<'_, Q>

Prepare the query, locking the columns needed to iterate over matching components.

Trait Implementations

impl<T> Edges for Query<T>

where T: IsQuery + Send + Sync + ?Sized,

fn reads() -> Vec<TypeKey>

Keys of all read types used in fields in the implementor.

fn writes() -> Vec<TypeKey>

Keys of all write types used in fields in the implementor.

fn moves() -> Vec<TypeKey>

Keys of all move types used in fields in the implementor.

fn construct(loan_mngr: &mut TypeMap) -> Result<Self, GraphError>

Attempt to construct the implementor from the given TypeMap.