Struct bevy::ecs::query::QueryState

pub struct QueryState<Q, F = ()>where
    Q: WorldQuery,
    F: ReadOnlyWorldQuery,{ /* private fields */ }
Expand description

Provides scoped access to a World state according to a given WorldQuery and query filter.

Implementations

Converts this QueryState reference to a QueryState that does not access anything mutably.

Converts this QueryState reference to a QueryState that does not return any data which can be faster.

This doesn’t use NopWorldQuery as it loses filter functionality, for example NopWorldQuery<Changed<T>> is functionally equivalent to With<T>.

Creates a new QueryState from a given World and inherits the result of world.id().

Checks if the query is empty for the given World, where the last change and current tick are given.

Takes a query for the given World, checks if the given world is the same as the query, and generates new archetypes for the given world.

Panics

Panics if the world.id() does not equal the current QueryState internal id.

Creates a new Archetype.

Gets the query result for the given World and Entity.

This can only be called for read-only queries, see Self::get_mut for write-queries.

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 QueryState::get_many_mut, the entities passed in do not need to be unique.

Examples
use bevy_ecs::prelude::*;
use bevy_ecs::query::QueryEntityError;

#[derive(Component, PartialEq, Debug)]
struct A(usize);

let mut world = World::new();
let entity_vec: Vec<Entity> = (0..3).map(|i|world.spawn(A(i)).id()).collect();
let entities: [Entity; 3] = entity_vec.try_into().unwrap();

world.spawn(A(73));

let mut query_state = world.query::<&A>();

let component_values = query_state.get_many(&world, entities).unwrap();

assert_eq!(component_values, [&A(0), &A(1), &A(2)]);

let wrong_entity = Entity::from_raw(365);

assert_eq!(query_state.get_many(&world, [wrong_entity]), Err(QueryEntityError::NoSuchEntity(wrong_entity)));

Gets the query result for the given World and Entity.

Returns the query results for the given array of Entity.

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

use bevy_ecs::prelude::*;
use bevy_ecs::query::QueryEntityError;

#[derive(Component, PartialEq, Debug)]
struct A(usize);

let mut world = World::new();

let entities: Vec<Entity> = (0..3).map(|i|world.spawn(A(i)).id()).collect();
let entities: [Entity; 3] = entities.try_into().unwrap();

world.spawn(A(73));

let mut query_state = world.query::<&mut A>();

let mut mutable_component_values = query_state.get_many_mut(&mut world, entities).unwrap();

for mut a in &mut mutable_component_values {
    a.0 += 5;
}

let component_values = query_state.get_many(&world, entities).unwrap();

assert_eq!(component_values, [&A(5), &A(6), &A(7)]);

let wrong_entity = Entity::from_raw(57);
let invalid_entity = world.spawn_empty().id();

assert_eq!(query_state.get_many_mut(&mut world, [wrong_entity]).unwrap_err(), QueryEntityError::NoSuchEntity(wrong_entity));
assert_eq!(query_state.get_many_mut(&mut world, [invalid_entity]).unwrap_err(), QueryEntityError::QueryDoesNotMatch(invalid_entity));
assert_eq!(query_state.get_many_mut(&mut world, [entities[0], entities[0]]).unwrap_err(), QueryEntityError::AliasedMutability(entities[0]));

Gets the query result for the given World and Entity.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

Returns an Iterator over the query results for the given World.

This can only be called for read-only queries, see Self::iter_mut for write-queries.

Returns an Iterator over the query results for the given World.

Returns an Iterator over the query results for the given World without updating the query’s archetypes. Archetypes must be manually updated before by using Self::update_archetypes.

This can only be called for read-only queries.

Returns an Iterator over all possible combinations of K query results without repetition. This can only be called for read-only queries.

A combination is an arrangement of a collection of items where order does not matter.

K is the number of items that make up each subset, and the number of items returned by the iterator. N is the number of total entities output by query.

For example, given the list [1, 2, 3, 4], where K is 2, the combinations without repeats are [1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4]. And in this case, N would be defined as 4 since the size of the input list is 4.

For combinations of size K of query taking N inputs, you will get:

  • if K == N: one combination 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)

The iter_combinations method does not guarantee order of iteration.

This can only be called for read-only queries, see Self::iter_combinations_mut for write-queries.

Returns an Iterator over all possible combinations of K query results without repetition.

A combination is an arrangement of a collection of items where order does not matter.

K is the number of items that make up each subset, and the number of items returned by the iterator. N is the number of total entities output by query.

For example, given the list [1, 2, 3, 4], where K is 2, the combinations without repeats are [1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4]. And in this case, N would be defined as 4 since the size of the input list is 4.

For combinations of size K of query taking N inputs, you will get:

  • if K == N: one combination 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)

The iter_combinations_mut method does not guarantee order of iteration.

Returns an Iterator over the read-only query items generated from an Entity list.

Items are returned in the order of the list of entities. Entities that don’t match the query are skipped.

See also

Returns an iterator over the query items generated from an Entity list.

Items are returned in the order of the list of entities. Entities that don’t match the query are skipped.

Returns an Iterator over the query results for the given World.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

Returns an Iterator over all possible combinations of K query results for the given World without repetition. This can only be called for read-only queries.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

Runs func on each query result for the given World. This is faster than the equivalent iter() method, but cannot be chained like a normal Iterator.

This can only be called for read-only queries, see Self::for_each_mut for write-queries.

Runs func on each query result for the given World. This is faster than the equivalent iter_mut() method, but cannot be chained like a normal Iterator.

Runs func on each query result for the given World. This is faster than the equivalent iter() method, but cannot be chained like a normal Iterator.

This can only be called for read-only queries.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

Runs func on each query result in parallel.

This can only be called for read-only queries, see Self::par_for_each_mut for write-queries.

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 func on each query result in parallel.

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 func on each query result in parallel.

This can only be called for read-only queries.

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.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

Returns a single immutable query result when there is exactly one entity matching the query.

This can only be called for read-only queries, see single_mut for write-queries.

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 be called for read-only queries, see get_single_mut for write-queries.

If the number of query results is not exactly one, a QuerySingleError is returned instead.

Returns a single mutable query result when there is exactly one entity matching the query.

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.

Returns a 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.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

Returns a query result when there is exactly one entity matching the query, where the last change and the current change tick are given.

If the number of query results is not exactly one, a QuerySingleError is returned instead.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query.

Trait Implementations

Formats the value using the given formatter. Read more
Creates Self using data from the given World
Safety 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