Struct bevy::ecs::prelude::Query

pub struct Query<'world, 'state, Q, F = ()> where
    Q: WorldQuery,
    F: WorldQuery,
    <F as WorldQuery>::Fetch: FilterFetch,  { /* fields omitted */ }

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:

1. Component access: the components that an entity must have at the same time to yield a query result.
2. 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:

• Added
• Changed
• With
• Without
• Or

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, 

pub fn iter(
    &'s self
) -> QueryIter<'w, 's, Q, <Q as WorldQuery>::ReadOnlyFetch, F>

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>

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>

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>

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>

Returns an Iterator over the query results.

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 unsafe fn iter_combinations_unsafe<const K: usize>(
    &self
) -> QueryCombinationIter<'_, '_, Q, <Q as WorldQuery>::Fetch, F, 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), 

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

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, 

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, 

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>

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>

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>

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, 

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, 

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, 

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

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>

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

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>

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

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, 

type Fetch = QueryState<Q, F>