pub struct Query<S> where
S: QuerySpec, { /* private fields */ }
Expand description
Query to get an iterator over all entities with a certain combination of components.
Queries are specified through their type argument, by composing the type of their result. The following type specifications are possible:
&C
- shared, immutable reference to components of typeC
&mut C
- exclusive, mutable reference(P, Q, R)
- combine multiple queriesOption<Q>
- optional component(s)With<Q, C>
to filterQ
for presence ofC
Without<Q, C>
to filterQ
for absence ofC
Matches<Q> to indicate which entities match
Q`
Note that Entities are components themselves, so they can be optionally obtained in a query,
like Query<Entity, &C, &mut D>
.
Queries are provided as stand-alone structs to allow for prepared queries that can be re-used, as an optimzation. Hence, queries need to borrow the World before their results can be iterated (see Query::borrow).
Examples
let mut world = World::new();
let entity1 = world.alloc();
world.insert(entity1, (42_i32, 23_u32, 1.0_f32));
let entity2 = world.alloc();
world.insert(entity2, (0_i32, true));
let mut query = Query::<(&mut i32, Option<(&u32, &mut f32)>)>::new();
for (i, opt) in query.borrow(&world).iter() {
if let Some((u, f)) = opt {
*i += *u as i32;
*f += 1.0
} else {
*i -= 1;
}
}
assert_eq!(*world.get::<i32>(entity1).unwrap(), 65);
assert_eq!(*world.get::<f32>(entity1).unwrap(), 2.0);
assert_eq!(*world.get::<i32>(entity2).unwrap(), -1);
Use of a prepared query that is stored and reused for optimization:
#[derive(Default)]
struct System {
query: Query<(&'static i32, &'static mut bool)>
}
impl System {
pub fn update(&mut self, world: &World) {
for (i, b) in self.query.borrow(world).iter() {
*b = *i >= 0;
}
}
}
fn main() {
let mut world = World::new();
let entity = world.alloc();
world.insert(entity, (23_i32, false));
let mut system = System::default();
for _ in 0..42 {
system.update(&world);
}
}
Implementations
Create a query.
Examples
let mut immutable_query = Query::<(&i32,)>::new();
let mut mutable_query = Query::<(&i32, &mut bool)>::new();
let mut query_with_entity = Query::<(&Entity, &i32, &mut bool)>::new();