Struct apecs::Query

source · [−]

pub struct Query<T>(_, _)
where
    T: IsQuery + ?Sized;

Expand description

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:

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

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

System data queries

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

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

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

#[derive(CanFetch)]
struct MySystemData {
    tracker: Write<u64>,
    // we can use Mut and Ref which are aliases for &'static mut and &'static
    q_f32_and_string: Query<(Mut<f32>, Ref<String>)>,
}
let mut world = World::default();
world
    .with_system("query_example", |mut data: MySystemData| {
        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()
    })
    .unwrap();
world.tick();

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);

let mut world = World::default();
world
    .with_system("create", |mut entities: Write<Entities>| {
        for i in 0..100 {
            entities.create().insert_bundle((
                Position(0.0),
                Velocity(0.0),
                Acceleration(i as f32),
            ));
        }
        end()
    })
    .unwrap()
    .with_system(
        "accelerate",
        |q_accelerate: Query<(&mut Velocity, &Acceleration)>| {
            for (v, a) in q_accelerate.query().iter_mut() {
                v.0 += a.0;
            }
            ok()
        },
    )
    .unwrap()
    .with_system("move", |q_move: Query<(&mut Position, &Velocity)>| {
        for (p, v) in q_move.query().iter_mut() {
            p.0 += v.0;
        }
        ok()
    })
    .unwrap();