pub struct Query<'world, 'state, Q, F = ()> where
Q: WorldQuery,
F: WorldQuery,
<F as WorldQuery>::Fetch: FilterFetch, { /* private fields */ }
Expand description
Provides scoped access to components in a World
.
Queries enable iteration over entities and their components as well as filtering them on certain conditions. A query matches its parameters against the world to produce a series of results. Each query result is a tuple of components (the same components defined in the query) that belong to the same entity.
Computational cost of queries is reduced by the fact that they have an internal archetype cache to avoid re-computing archetype matches on each query access.
Query functionality is based on the WorldQuery
trait. Both tuples of components
(up to 16 elements) and query filters implement this trait.
Query
accepts two type parameters:
- Component access: the components that an entity must have at the same time to yield a query result.
- Query filters (optional): a predicate that ignores query results that don’t match its conditions.
Usage as system parameter
A query is defined by declaring it as a system parameter. This section shows the various
use cases of Query
as a system parameter.
Immutable component access
The following example defines a query that gives an iterator over (&ComponentA, &ComponentB)
tuples, where ComponentA
and ComponentB
belong to the same entity. Accessing components
immutably helps system parallelization.
query: Query<(&ComponentA, &ComponentB)>
Mutable component access
The following example is similar to the previous one, with the exception of ComponentA
being accessed mutably here. Note that both mutable and immutable accesses are allowed
in the same query.
// `ComponentA` is accessed mutably, while `ComponentB` is accessed immutably.
mut query: Query<(&mut ComponentA, &ComponentB)>
Two systems cannot be executed in parallel if both access a certain component and at least one of the accesses is mutable, unless the schedule can verify that no entity could be found in both queries, as otherwise Rusts mutability Rules would be broken.
Similarly, a system cannot contain two queries that would break Rust’s mutability Rules.
If you need such Queries, you can use Filters to make the Queries disjoint or use a
QuerySet
.
Entity ID access
Inserting Entity
at any position in the type parameter tuple
will give access to the entity ID.
query: Query<(Entity, &ComponentA, &ComponentB)>
Query filtering
The second, optional type parameter of query, is used for filters can be added to filter out the query results that don’t satisfy the given condition.
// `ComponentC` data won't be accessed, but only entities that contain it will be queried.
query: Query<(&ComponentA, &ComponentB), With<ComponentC>>
If you need to apply more filters in a single query, group them into a tuple:
// Similar to the previous query, but with the addition of a `Changed` filter.
query: Query<(&ComponentA, &ComponentB), (With<ComponentC>, Changed<ComponentA>)>
The following list contains all the available query filters:
Optional component access
A component can be made optional in a query by wrapping it into an Option
. In the
following example, the query will iterate over components of both entities that contain
ComponentA
and ComponentB
, and entities that contain ComponentA
but not ComponentB
.
query: Query<(&ComponentA, Option<&ComponentB>)>
If an entity does not contain a component, its corresponding query result value will be
None
. Optional components increase the number of entities a query has to match against,
therefore they can hurt iteration performance, especially in the worst case scenario where
the query solely consists of only optional components, since all entities will be iterated
over.
Single component access
If just a single component needs to be accessed, using a tuple as the first type parameter
of Query
can be omitted.
// This is correct, but can be avoided.
query: Query<(&MyComponent,)>
// This is the preferred method.
query: Query<&MyComponent>
Usage of query results
Inside the body of the system function, the Query
is available as a function parameter.
This section shows various methods to access query results.
Iteration over every query result
The iter
and iter_mut
methods are used to iterate
over every query result. Refer to the
Iterator
API docs
for advanced iterator usage.
fn immutable_query_system(query: Query<(&ComponentA, &ComponentB)>) {
for (a, b) in query.iter() {
// Here, `a` and `b` are normal references to components, relatively of
// `&ComponentA` and `&ComponentB` types.
}
}
fn mutable_query_system(mut query: Query<(&mut ComponentA, &ComponentB)>) {
for (mut a, b) in query.iter_mut() {
// Similar to the above system, but this time `ComponentA` can be accessed mutably.
// Note the usage of `mut` in the tuple and the call to `iter_mut` instead of `iter`.
}
}
Getting the query result for a particular entity
If you have an Entity
ID, you can use the get
or
get_mut
methods to access the query result for that particular entity.
Getting a single query result
While it’s possible to get a single result from a query by using iter.next()
, a more
idiomatic approach would use the single
or single_mut
methods instead. Keep in mind though that they will return a QuerySingleError
if the
number of query results differ from being exactly one. If that’s the case, use iter.next()
(or iter_mut.next()
) to only get the first query result.
Implementations
impl<'w, 's, Q, F> Query<'w, 's, Q, F> where
Q: WorldQuery,
F: WorldQuery,
<F as WorldQuery>::Fetch: FilterFetch,
impl<'w, 's, Q, F> Query<'w, 's, Q, F> where
Q: WorldQuery,
F: WorldQuery,
<F as WorldQuery>::Fetch: FilterFetch,
pub fn iter(
&'s self
) -> QueryIter<'w, 's, Q, <Q as WorldQuery>::ReadOnlyFetch, F>ⓘNotable traits for QueryIter<'w, 's, Q, QF, F>impl<'w, 's, Q, QF, F> Iterator for QueryIter<'w, 's, Q, QF, F> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
pub fn iter(
&'s self
) -> QueryIter<'w, 's, Q, <Q as WorldQuery>::ReadOnlyFetch, F>ⓘNotable traits for QueryIter<'w, 's, Q, QF, F>impl<'w, 's, Q, QF, F> Iterator for QueryIter<'w, 's, Q, QF, F> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
Returns an Iterator
over the query results.
This can only return immutable data (mutable data will be cast to an immutable form).
See Self::iter_mut
for queries that contain at least one mutable component.
Example
Here, the report_names_system
iterates over the Player
component of every entity
that contains it:
fn report_names_system(query: Query<&Player>) {
for player in query.iter() {
println!("Say hello to {}!", player.name);
}
}
pub fn iter_mut(&mut self) -> QueryIter<'_, '_, Q, <Q as WorldQuery>::Fetch, F>ⓘNotable traits for QueryIter<'w, 's, Q, QF, F>impl<'w, 's, Q, QF, F> Iterator for QueryIter<'w, 's, Q, QF, F> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
pub fn iter_mut(&mut self) -> QueryIter<'_, '_, Q, <Q as WorldQuery>::Fetch, F>ⓘNotable traits for QueryIter<'w, 's, Q, QF, F>impl<'w, 's, Q, QF, F> Iterator for QueryIter<'w, 's, Q, QF, F> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
Returns an Iterator
over the query results.
Example
Here, the gravity_system
iterates over the Velocity
component of every entity in
the world that contains it in order to update it:
fn gravity_system(mut query: Query<&mut Velocity>) {
const DELTA: f32 = 1.0 / 60.0;
for mut velocity in query.iter_mut() {
velocity.y -= 9.8 * DELTA;
}
}
pub fn iter_combinations<const K: usize>(
&self
) -> QueryCombinationIter<'_, '_, Q, <Q as WorldQuery>::ReadOnlyFetch, F, K>ⓘNotable traits for QueryCombinationIter<'w, 's, Q, QF, F, K>impl<'w, 's, Q, QF, F, const K: usize> Iterator for QueryCombinationIter<'w, 's, Q, QF, F, K> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
pub fn iter_combinations<const K: usize>(
&self
) -> QueryCombinationIter<'_, '_, Q, <Q as WorldQuery>::ReadOnlyFetch, F, K>ⓘNotable traits for QueryCombinationIter<'w, 's, Q, QF, F, K>impl<'w, 's, Q, QF, F, const K: usize> Iterator for QueryCombinationIter<'w, 's, Q, QF, F, K> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
Returns an Iterator
over all possible combinations of K
query results without repetition.
This can only return immutable data
For permutations of size K of query returning N results, you will get:
- if K == N: one permutation of all query results
- if K < N: all possible K-sized combinations of query results, without repetition
- if K > N: empty set (no K-sized combinations exist)
pub fn iter_combinations_mut<const K: usize>(
&mut self
) -> QueryCombinationIter<'_, '_, Q, <Q as WorldQuery>::Fetch, F, K>ⓘNotable traits for QueryCombinationIter<'w, 's, Q, QF, F, K>impl<'w, 's, Q, QF, F, const K: usize> Iterator for QueryCombinationIter<'w, 's, Q, QF, F, K> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
pub fn iter_combinations_mut<const K: usize>(
&mut self
) -> QueryCombinationIter<'_, '_, Q, <Q as WorldQuery>::Fetch, F, K>ⓘNotable traits for QueryCombinationIter<'w, 's, Q, QF, F, K>impl<'w, 's, Q, QF, F, const K: usize> Iterator for QueryCombinationIter<'w, 's, Q, QF, F, K> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
Iterates over all possible combinations of K
query results without repetition.
The returned value is not an Iterator
, because that would lead to aliasing of mutable references.
In order to iterate it, use fetch_next
method with while let Some(..)
loop pattern.
#[derive(Component)]
// iterate using `fetch_next` in while loop
let mut combinations = query.iter_combinations_mut();
while let Some([mut a, mut b]) = combinations.fetch_next() {
// mutably access components data
}
There is no for_each
method, because it cannot be safely implemented
due to a compiler bug.
For immutable access see Query::iter_combinations
.
pub unsafe fn iter_unsafe(
&'s self
) -> QueryIter<'w, 's, Q, <Q as WorldQuery>::Fetch, F>ⓘNotable traits for QueryIter<'w, 's, Q, QF, F>impl<'w, 's, Q, QF, F> Iterator for QueryIter<'w, 's, Q, QF, F> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
pub unsafe fn iter_unsafe(
&'s self
) -> QueryIter<'w, 's, Q, <Q as WorldQuery>::Fetch, F>ⓘNotable traits for QueryIter<'w, 's, Q, QF, F>impl<'w, 's, Q, QF, F> Iterator for QueryIter<'w, 's, Q, QF, F> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State>,
<F as WorldQuery>::Fetch: FilterFetch, type Item = <QF as Fetch<'w, 's>>::Item;
pub unsafe fn iter_combinations_unsafe<const K: usize>(
&self
) -> QueryCombinationIter<'_, '_, Q, <Q as WorldQuery>::Fetch, F, K>ⓘNotable traits for QueryCombinationIter<'w, 's, Q, QF, F, K>impl<'w, 's, Q, QF, F, const K: usize> Iterator for QueryCombinationIter<'w, 's, Q, QF, F, K> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
pub unsafe fn iter_combinations_unsafe<const K: usize>(
&self
) -> QueryCombinationIter<'_, '_, Q, <Q as WorldQuery>::Fetch, F, K>ⓘNotable traits for QueryCombinationIter<'w, 's, Q, QF, F, K>impl<'w, 's, Q, QF, F, const K: usize> Iterator for QueryCombinationIter<'w, 's, Q, QF, F, K> where
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
Q: WorldQuery,
F: WorldQuery,
QF: Fetch<'w, 's, State = <Q as WorldQuery>::State> + Clone + ReadOnlyFetch,
<F as WorldQuery>::Fetch: Clone,
<F as WorldQuery>::Fetch: FilterFetch,
<F as WorldQuery>::Fetch: ReadOnlyFetch, type Item = [<QF as Fetch<'w, 's>>::Item; K];
Iterates over all possible combinations of K
query results without repetition.
See Query::iter_combinations
.
Safety
This allows aliased mutability. You must make sure this call does not result in multiple mutable references to the same component
pub fn for_each<FN>(&'s self, f: FN) where
FN: FnMut(<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item),
pub fn for_each<FN>(&'s self, f: FN) where
FN: FnMut(<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item),
Runs f
on each query result. This is faster than the equivalent iter() method, but cannot
be chained like a normal Iterator
.
This can only pass in immutable data, see Self::for_each_mut
for mutable access.
Example
Here, the report_names_system
iterates over the Player
component of every entity
that contains it:
fn report_names_system(query: Query<&Player>) {
query.for_each(|player| {
println!("Say hello to {}!", player.name);
});
}
pub fn for_each_mut<'a, FN>(&'a mut self, f: FN) where
FN: FnMut(<<Q as WorldQuery>::Fetch as Fetch<'a, 'a>>::Item),
pub fn for_each_mut<'a, FN>(&'a mut self, f: FN) where
FN: FnMut(<<Q as WorldQuery>::Fetch as Fetch<'a, 'a>>::Item),
Runs f
on each query result. This is faster than the equivalent iter() method, but cannot
be chained like a normal Iterator
.
Example
Here, the gravity_system
iterates over the Velocity
component of every entity in
the world that contains it in order to update it:
fn gravity_system(mut query: Query<&mut Velocity>) {
const DELTA: f32 = 1.0 / 60.0;
query.for_each_mut(|mut velocity| {
velocity.y -= 9.8 * DELTA;
});
}
pub fn par_for_each<FN>(
&'s self,
task_pool: &TaskPool,
batch_size: usize,
f: FN
) where
FN: Fn(<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item) + Send + Sync + Clone,
pub fn par_for_each<FN>(
&'s self,
task_pool: &TaskPool,
batch_size: usize,
f: FN
) where
FN: Fn(<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item) + Send + Sync + Clone,
Runs f
on each query result in parallel using the given task pool.
This can only be called for immutable data, see Self::par_for_each_mut
for
mutable access.
pub fn par_for_each_mut<'a, FN>(
&'a mut self,
task_pool: &TaskPool,
batch_size: usize,
f: FN
) where
FN: Fn(<<Q as WorldQuery>::Fetch as Fetch<'a, 'a>>::Item) + Send + Sync + Clone,
pub fn par_for_each_mut<'a, FN>(
&'a mut self,
task_pool: &TaskPool,
batch_size: usize,
f: FN
) where
FN: Fn(<<Q as WorldQuery>::Fetch as Fetch<'a, 'a>>::Item) + Send + Sync + Clone,
Runs f
on each query result in parallel using the given task pool.
pub fn get(
&'s self,
entity: Entity
) -> Result<<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item, QueryEntityError>
pub fn get(
&'s self,
entity: Entity
) -> Result<<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item, QueryEntityError>
Returns the query result for the given Entity
.
In case of a nonexisting entity or mismatched component, a QueryEntityError
is
returned instead.
This can only return immutable data (mutable data will be cast to an immutable form).
See get_mut
for queries that contain at least one mutable component.
Example
Here, get
is used to retrieve the exact query result of the entity specified by the
SelectedCharacter
resource.
fn print_selected_character_name_system(
query: Query<&Character>,
selection: Res<SelectedCharacter>
)
{
if let Ok(selected_character) = query.get(selection.entity) {
println!("{}", selected_character.name);
}
}
pub fn get_mut(
&mut self,
entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_, '_>>::Item, QueryEntityError>
pub fn get_mut(
&mut self,
entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_, '_>>::Item, QueryEntityError>
Returns the query result for the given Entity
.
In case of a nonexisting entity or mismatched component, a QueryEntityError
is
returned instead.
Example
Here, get_mut
is used to retrieve the exact query result of the entity specified by the
PoisonedCharacter
resource.
fn poison_system(mut query: Query<&mut Health>, poisoned: Res<PoisonedCharacter>) {
if let Ok(mut health) = query.get_mut(poisoned.character_id) {
health.0 -= 1;
}
}
pub unsafe fn get_unchecked(
&'s self,
entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'w, 's>>::Item, QueryEntityError>
pub unsafe fn get_unchecked(
&'s self,
entity: Entity
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'w, 's>>::Item, QueryEntityError>
Returns the query result for the given Entity
.
In case of a nonexisting entity or mismatched component, a QueryEntityError
is
returned instead.
Safety
This function makes it possible to violate Rust’s aliasing guarantees. You must make sure this call does not result in multiple mutable references to the same component
pub fn get_component<T>(
&self,
entity: Entity
) -> Result<&T, QueryComponentError> where
T: Component,
pub fn get_component<T>(
&self,
entity: Entity
) -> Result<&T, QueryComponentError> where
T: Component,
Returns a reference to the Entity
’s Component
of the given type.
In case of a nonexisting entity or mismatched component, a QueryEntityError
is
returned instead.
Example
Here, get_component
is used to retrieve the Character
component of the entity
specified by the SelectedCharacter
resource.
fn print_selected_character_name_system(
query: Query<&Character>,
selection: Res<SelectedCharacter>
)
{
if let Ok(selected_character) = query.get_component::<Character>(selection.entity) {
println!("{}", selected_character.name);
}
}
pub fn get_component_mut<T>(
&mut self,
entity: Entity
) -> Result<Mut<'_, T>, QueryComponentError> where
T: Component,
pub fn get_component_mut<T>(
&mut self,
entity: Entity
) -> Result<Mut<'_, T>, QueryComponentError> where
T: Component,
Returns a mutable reference to the Entity
’s Component
of the given type.
In case of a nonexisting entity or mismatched component, a QueryEntityError
is
returned instead.
Example
Here, get_component_mut
is used to retrieve the Health
component of the entity
specified by the PoisonedCharacter
resource.
fn poison_system(mut query: Query<&mut Health>, poisoned: Res<PoisonedCharacter>) {
if let Ok(mut health) = query.get_component_mut::<Health>(poisoned.character_id) {
health.0 -= 1;
}
}
pub unsafe fn get_component_unchecked_mut<T>(
&self,
entity: Entity
) -> Result<Mut<'_, T>, QueryComponentError> where
T: Component,
pub unsafe fn get_component_unchecked_mut<T>(
&self,
entity: Entity
) -> Result<Mut<'_, T>, QueryComponentError> where
T: Component,
Returns a mutable reference to the Entity
’s Component
of the given type.
In case of a nonexisting entity or mismatched component, a QueryEntityError
is
returned instead.
Safety
This function makes it possible to violate Rust’s aliasing guarantees. You must make sure this call does not result in multiple mutable references to the same component
pub fn single(
&'s self
) -> <<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item
pub fn single(
&'s self
) -> <<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item
Returns a single immutable query result when there is exactly one entity matching the query.
This can only return immutable data. Use single_mut
for
queries that contain at least one mutable component.
Example
fn player_system(query: Query<&Position, With<Player>>) {
let player_position = query.single();
// do something with player_position
}
Panics
Panics if the number of query results is not exactly one. Use
get_single
to return a Result
instead of panicking.
pub fn get_single(
&'s self
) -> Result<<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item, QuerySingleError>
pub fn get_single(
&'s self
) -> Result<<<Q as WorldQuery>::ReadOnlyFetch as Fetch<'w, 's>>::Item, QuerySingleError>
Returns a single immutable query result when there is exactly one entity matching the query.
This can only return immutable data. Use get_single_mut
for queries that contain at least one mutable component.
If the number of query results is not exactly one, a QuerySingleError
is returned
instead.
Example
fn player_scoring_system(query: Query<&PlayerScore>) {
match query.get_single() {
Ok(PlayerScore(score)) => {
println!("Score: {}", score);
}
Err(QuerySingleError::NoEntities(_)) => {
println!("Error: There is no player!");
}
Err(QuerySingleError::MultipleEntities(_)) => {
println!("Error: There is more than one player!");
}
}
}
pub fn single_mut(
&mut self
) -> <<Q as WorldQuery>::Fetch as Fetch<'_, '_>>::Item
pub fn single_mut(
&mut self
) -> <<Q as WorldQuery>::Fetch as Fetch<'_, '_>>::Item
Returns a single mutable query result when there is exactly one entity matching the query.
Example
fn regenerate_player_health_system(mut query: Query<&mut Health, With<Player>>) {
let mut health = query.single_mut();
health.0 += 1;
}
Panics
Panics if the number of query results is not exactly one. Use
get_single_mut
to return a Result
instead of panicking.
pub fn get_single_mut(
&mut self
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_, '_>>::Item, QuerySingleError>
pub fn get_single_mut(
&mut self
) -> Result<<<Q as WorldQuery>::Fetch as Fetch<'_, '_>>::Item, QuerySingleError>
Returns a single mutable query result when there is exactly one entity matching the query.
If the number of query results is not exactly one, a QuerySingleError
is returned
instead.
Example
fn regenerate_player_health_system(mut query: Query<&mut Health, With<Player>>) {
let mut health = query.get_single_mut().expect("Error: Could not find a single player.");
health.0 += 1;
}
pub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true
if there are no query results.
Example
Here, the score is increased only if an entity with a Player
component is present
in the world:
fn update_score_system(query: Query<(), With<Player>>, mut score: ResMut<Score>) {
if !query.is_empty() {
score.0 += 1;
}
}
Trait Implementations
impl<'w, 's, Q, F> SystemParam for Query<'w, 's, Q, F> where
Q: 'static + WorldQuery,
F: 'static + WorldQuery,
<F as WorldQuery>::Fetch: FilterFetch,
impl<'w, 's, Q, F> SystemParam for Query<'w, 's, Q, F> where
Q: 'static + WorldQuery,
F: 'static + WorldQuery,
<F as WorldQuery>::Fetch: FilterFetch,
type Fetch = QueryState<Q, F>
Auto Trait Implementations
impl<'world, 'state, Q, F = ()> !RefUnwindSafe for Query<'world, 'state, Q, F>
impl<'world, 'state, Q, F> Send for Query<'world, 'state, Q, F>
impl<'world, 'state, Q, F> Sync for Query<'world, 'state, Q, F>
impl<'world, 'state, Q, F> Unpin for Query<'world, 'state, Q, F>
impl<'world, 'state, Q, F = ()> !UnwindSafe for Query<'world, 'state, Q, F>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> Downcast for T where
T: Any,
impl<T> Downcast for T where
T: Any,
pub fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>ⓘNotable traits for Box<F, A>impl<F, A> Future for Box<F, A> where
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;
pub fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>ⓘNotable traits for Box<F, A>impl<F, A> Future for Box<F, A> where
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;
Convert Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
. Read more
pub fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
pub fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Convert Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more
pub fn as_any(&self) -> &(dyn Any + 'static)
pub fn as_any(&self) -> &(dyn Any + 'static)
Convert &Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read more
pub fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
pub fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Convert &mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
sourcefn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
pub fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
T: Future, type Output = <T as Future>::Output;
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
fn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more