logo

Struct bevy::ecs::system::Query

[−]
pub struct Query<'world, 'state, Q, F = ()> where
    Q: WorldQuery,
    F: WorldQuery, { /* 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:

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

You can use the ReadOnlyWorldQuery trait to abstract over read only query generics:

fn system<Q: ReadOnlyWorldQuery>(
    query: Query<Q>,
) {
    let _: Option<QueryItem<Q>> = query.iter().next();
}

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 ParamSet.

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 {
        // 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 &mut query {
        // 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

Downgrades all data accessed in this query to a read-only form.

For example, Query<(&mut A, &B, &mut C), With<D>> will become Query<(&A, &B, &C), With<D>>. This can be useful when working around the borrow checker, or reusing functionality between systems via functions that accept query types.

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 {
        println!("Say hello to {}!", player.name);
    }
}

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 &mut query {
        velocity.y -= 9.8 * DELTA;
    }
}

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)

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.

Returns an Iterator over the query results of a list of Entity’s.

This can only return immutable data (mutable data will be cast to an immutable form). See Self::iter_many_mut for queries that contain at least one mutable component.

Examples
#[derive(Component)]
struct Counter {
    value: i32
}

#[derive(Component)]
struct Friends {
    list: Vec<Entity>,
}

fn system(
    friends_query: Query<&Friends>,
    counter_query: Query<&Counter>,
) {
    for friends in &friends_query {
        for counter in counter_query.iter_many(&friends.list) {
            println!("Friend's counter: {:?}", counter.value);
        }
    }
}

Calls a closure on each result of Query where the entities match.

Examples
#[derive(Component)]
struct Counter {
    value: i32
}

#[derive(Component)]
struct Friends {
    list: Vec<Entity>,
}

fn system(
    friends_query: Query<&Friends>,
    mut counter_query: Query<&mut Counter>,
) {
    for friends in &friends_query {
        let mut iter = counter_query.iter_many_mut(&friends.list);
        while let Some(mut counter) = iter.fetch_next() {
            println!("Friend's counter: {:?}", counter.value);
            counter.value += 1;
        }
    }
}

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

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

Returns an Iterator over the query results of a list of Entity’s.

If you want safe mutable access to query results of a list of Entity’s. See Self::iter_many_mut.

Safety

This allows aliased mutability and does not check for entity uniqueness. You must make sure this call does not result in multiple mutable references to the same component. Particular care must be taken when collecting the data (rather than iterating over it one item at a time) such as via [Iterator::collect()].

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

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

Runs f on each query result in parallel using the World’s ComputeTaskPool.

This can only be called for immutable data, see Self::par_for_each_mut for mutable access.

Tasks and batch size

The items in the query get sorted into batches. Internally, this function spawns a group of futures that each take on a batch_size sized section of the items (or less if the division is not perfect). Then, the tasks in the ComputeTaskPool work through these futures.

You can use this value to tune between maximum multithreading ability (many small batches) and minimum parallelization overhead (few big batches). Rule of thumb: If the function body is (mostly) computationally expensive but there are not many items, a small batch size (=more batches) may help to even out the load. If the body is computationally cheap and you have many items, a large batch size (=fewer batches) avoids spawning additional futures that don’t help to even out the load.

Arguments
  • batch_size - The number of batches to spawn
  • f - The function to run on each item in the query
Panics

The ComputeTaskPool is not initialized. If using this from a query that is being initialized and run from the ECS scheduler, this should never panic.

Runs f on each query result in parallel using the World’s ComputeTaskPool. See Self::par_for_each for more details.

Panics

The ComputeTaskPool is not initialized. If using this from a query that is being initialized and run from the ECS scheduler, this should never panic.

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

Returns the read-only query results for the given array of Entity.

In case of a nonexisting entity or mismatched component, a QueryEntityError is returned instead.

Note that the unlike Query::get_many_mut, the entities passed in do not need to be unique.

See Query::many for the infallible equivalent.

Returns the read-only query items for the provided array of Entity

See Query::get_many for the Result-returning equivalent.

Examples
use bevy_ecs::prelude::*;

#[derive(Component)]
struct Targets([Entity; 3]);

#[derive(Component)]
struct Position{
    x: i8,
    y: i8
};

impl Position {
    fn distance(&self, other: &Position) -> i8 {
        // Manhattan distance is way easier to compute!
        (self.x - other.x).abs() + (self.y - other.y).abs()
    }
}

fn check_all_targets_in_range(targeting_query: Query<(Entity, &Targets, &Position)>, targets_query: Query<&Position>){
    for (targeting_entity, targets, origin) in &targeting_query {
        // We can use "destructuring" to unpack the results nicely
        let [target_1, target_2, target_3] = targets_query.many(targets.0);

        assert!(target_1.distance(origin) <= 5);
        assert!(target_2.distance(origin) <= 5);
        assert!(target_3.distance(origin) <= 5);
    }
}

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

Returns the query results for the given array of Entity.

In case of a nonexisting entity, duplicate entities or mismatched component, a QueryEntityError is returned instead.

See Query::many_mut for the infallible equivalent.

Returns the query items for the provided array of Entity

See Query::get_many_mut for the Result-returning equivalent.

Examples
use bevy_ecs::prelude::*;

#[derive(Component)]
struct Spring{
    connected_entities: [Entity; 2],
    strength: f32,
}

#[derive(Component)]
struct Position {
    x: f32,
    y: f32,
}

#[derive(Component)]
struct Force {
    x: f32,
    y: f32,
}

fn spring_forces(spring_query: Query<&Spring>, mut mass_query: Query<(&Position, &mut Force)>){
    for spring in &spring_query {
         // We can use "destructuring" to unpack our query items nicely
         let [(position_1, mut force_1), (position_2, mut force_2)] = mass_query.many_mut(spring.connected_entities);

         force_1.x += spring.strength * (position_1.x - position_2.x);
         force_1.y += spring.strength * (position_1.y - position_2.y);

         // Silence borrow-checker: I have split your mutable borrow!
         force_2.x += spring.strength * (position_2.x - position_1.x);
         force_2.y += spring.strength * (position_2.y - position_1.y);
    }
}

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

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

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

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

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.

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!");
        }
    }
}

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.

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

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

Returns true if the given Entity matches the query.

Example
fn targeting_system(in_range_query: Query<&InRange>, target: Res<Target>) {
    if in_range_query.contains(target.entity) {
        println!("Bam!")
    }
}

Returns the query result for the given Entity, with the actual “inner” world lifetime.

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

Returns an Iterator over the query results, with the actual “inner” world lifetime.

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 {
        println!("Say hello to {}!", player.name);
    }
}

Trait Implementations

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

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

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

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s. Read more

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

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more