Struct bevy_ecs::query::QueryState

#[repr(C)]
pub struct QueryState<D: QueryData, F: QueryFilter = ()> { /* private fields */ }

Provides scoped access to a World state according to a given QueryData and QueryFilter.

Implementations

impl<D: QueryData, F: QueryFilter> QueryState<D, F>

pub fn as_readonly(&self) -> &QueryState<D::ReadOnly, F>

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

pub fn as_nop(&self) -> &QueryState<NopWorldQuery<D>, F>

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

pub fn archetype_component_access(&self) -> &Access<ArchetypeComponentId>

Returns the archetype components accessed by this query.

pub fn component_access(&self) -> &FilteredAccess<ComponentId>

Returns the components accessed by this query.

pub fn matched_tables(&self) -> &[TableId]

Returns the tables matched by this query.

pub fn matched_archetypes(&self) -> &[ArchetypeId]

Returns the archetypes matched by this query.

impl<D: QueryData, F: QueryFilter> QueryState<D, F>

pub fn new(world: &mut World) -> Self

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

pub fn from_builder(builder: &mut QueryBuilder<'_, D, F>) -> Self

Creates a new QueryState from a given QueryBuilder and inherits it’s FilteredAccess.

pub fn is_empty(&self, world: &World, last_run: Tick, this_run: Tick) -> bool

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

Panics

If world does not match the one used to call QueryState::new for this instance.

pub fn update_archetypes(&mut self, world: &World)

Updates the state’s internal view of the World’s archetypes. If this is not called before querying data, the results may not accurately reflect what is in the world.

This is only required if a manual method (such as Self::get_manual) is being called, and it only needs to be called if the world has been structurally mutated (i.e. added/removed a component or resource). Users using non-manual methods such as QueryState::get do not need to call this as it will be automatically called for them.

If you have an UnsafeWorldCell instead of &World, consider using QueryState::update_archetypes_unsafe_world_cell.

Panics

If world does not match the one used to call QueryState::new for this instance.

pub fn update_archetypes_unsafe_world_cell( &mut self, world: UnsafeWorldCell<'_> )

Updates the state’s internal view of the world’s archetypes. If this is not called before querying data, the results may not accurately reflect what is in the world.

This is only required if a manual method (such as Self::get_manual) is being called, and it only needs to be called if the world has been structurally mutated (i.e. added/removed a component or resource). Users using non-manual methods such as QueryState::get do not need to call this as it will be automatically called for them.

Note

This method only accesses world metadata.

Panics

If world does not match the one used to call QueryState::new for this instance.

pub fn validate_world(&self, world_id: WorldId)

Panics

If world_id does not match the World used to call QueryState::new for this instance.

Many unsafe query methods require the world to match for soundness. This function is the easiest way of ensuring that it matches.

pub fn new_archetype(&mut self, archetype: &Archetype)

Update the current QueryState with information from the provided Archetype (if applicable, i.e. if the archetype has any intersecting ComponentId with the current QueryState).

pub fn matches_component_set( &self, set_contains_id: &impl Fn(ComponentId) -> bool ) -> bool

Returns true if this query matches a set of components. Otherwise, returns false.

pub fn update_archetype_component_access(&mut self, archetype: &Archetype)

For the given archetype, adds any component accessed used by this query’s underlying FilteredAccess to access.

pub fn transmute<NewD: QueryData>(&self, world: &World) -> QueryState<NewD>

Use this to transform a QueryState into a more generic QueryState. This can be useful for passing to another function that might take the more general form. See Query::transmute_lens for more details.

You should not call update_archetypes on the returned QueryState as the result will be unpredictable. You might end up with a mix of archetypes that only matched the original query + archetypes that only match the new QueryState. Most of the safe methods on QueryState call QueryState::update_archetypes internally, so this best used through a Query.

pub fn transmute_filtered<NewD: QueryData, NewF: QueryFilter>( &self, world: &World ) -> QueryState<NewD, NewF>

Creates a new QueryState with the same underlying FilteredAccess, matched tables and archetypes as self but with a new type signature.

Panics if NewD or NewF require accesses that this query does not have.

pub fn get<'w>( &mut self, world: &'w World, entity: Entity ) -> Result<ROQueryItem<'w, D>, QueryEntityError>

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.

pub fn get_many<'w, const N: usize>( &mut self, world: &'w World, entities: [Entity; N] ) -> Result<[ROQueryItem<'w, D>; N], QueryEntityError>

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

pub fn get_mut<'w>( &mut self, world: &'w mut World, entity: Entity ) -> Result<D::Item<'w>, QueryEntityError>

Gets the query result for the given World and Entity.

pub fn get_many_mut<'w, const N: usize>( &mut self, world: &'w mut World, entities: [Entity; N] ) -> Result<[D::Item<'w>; N], QueryEntityError>

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

pub fn get_manual<'w>( &self, world: &'w World, entity: Entity ) -> Result<ROQueryItem<'w, D>, QueryEntityError>

Gets the query result for the given World and Entity.

This method is slightly more efficient than QueryState::get in some situations, since it does not update this instance’s internal cache. This method will return an error if entity belongs to an archetype that has not been cached.

To ensure that the cache is up to date, call QueryState::update_archetypes before this method. The cache is also updated in QueryState::new, QueryState::get, or any method with mutable access to self.

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

pub unsafe fn get_unchecked<'w>( &mut self, world: UnsafeWorldCell<'w>, entity: Entity ) -> Result<D::Item<'w>, QueryEntityError>

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.

pub unsafe fn get_component_unchecked_mut<'w, T: Component>( &self, world: UnsafeWorldCell<'w>, entity: Entity, last_run: Tick, this_run: Tick ) -> Result<Mut<'w, T>, QueryComponentError>

👎Deprecated since 0.13.0: Please use QueryState::get_unchecked_manual and select for the exact component based on the structure of the exact query as required.

Returns a mutable reference to the component T of the given entity.

In case of a nonexisting entity or mismatched component, a QueryComponentError 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 iter<'w, 's>( &'s mut self, world: &'w World ) -> QueryIter<'w, 's, D::ReadOnly, F>

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.

pub fn iter_mut<'w, 's>( &'s mut self, world: &'w mut World ) -> QueryIter<'w, 's, D, F>

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

pub fn iter_manual<'w, 's>( &'s self, world: &'w World ) -> QueryIter<'w, 's, D::ReadOnly, F>

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.

pub fn iter_combinations<'w, 's, const K: usize>( &'s mut self, world: &'w World ) -> QueryCombinationIter<'w, 's, D::ReadOnly, F, K>

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.

pub fn iter_combinations_mut<'w, 's, const K: usize>( &'s mut self, world: &'w mut World ) -> QueryCombinationIter<'w, 's, D, F, K>

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.

pub fn iter_many<'w, 's, EntityList: IntoIterator>( &'s mut self, world: &'w World, entities: EntityList ) -> QueryManyIter<'w, 's, D::ReadOnly, F, EntityList::IntoIter>

where EntityList::Item: Borrow<Entity>,

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

• iter_many_mut to get mutable query items.

pub fn iter_many_manual<'w, 's, EntityList: IntoIterator>( &'s self, world: &'w World, entities: EntityList ) -> QueryManyIter<'w, 's, D::ReadOnly, F, EntityList::IntoIter>

where EntityList::Item: Borrow<Entity>,

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.

If world archetypes changed since Self::update_archetypes was last called, this will skip entities contained in new archetypes.

This can only be called for read-only queries.

See also

• iter_many to update archetypes.
• iter_manual to iterate over all query items.

pub fn iter_many_mut<'w, 's, EntityList: IntoIterator>( &'s mut self, world: &'w mut World, entities: EntityList ) -> QueryManyIter<'w, 's, D, F, EntityList::IntoIter>

where EntityList::Item: Borrow<Entity>,

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.

pub unsafe fn iter_unchecked<'w, 's>( &'s mut self, world: UnsafeWorldCell<'w> ) -> QueryIter<'w, 's, D, F>

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.

pub unsafe fn iter_combinations_unchecked<'w, 's, const K: usize>( &'s mut self, world: UnsafeWorldCell<'w> ) -> QueryCombinationIter<'w, 's, D, F, K>

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.

pub fn for_each<'w, FN: FnMut(ROQueryItem<'w, D>)>( &mut self, world: &'w World, func: FN )

👎Deprecated since 0.13.0: QueryState::for_each was not idiomatic Rust and has been moved to query.iter().for_each()

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.

Shorthand for query.iter(world).for_each(..).

pub fn for_each_mut<'w, FN: FnMut(D::Item<'w>)>( &mut self, world: &'w mut World, func: FN )

👎Deprecated since 0.13.0: QueryState::for_each_mut was not idiomatic Rust and has been moved to query.iter_mut().for_each()

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.

Shorthand for query.iter_mut(world).for_each(..).

pub unsafe fn for_each_unchecked<'w, FN: FnMut(D::Item<'w>)>( &mut self, world: UnsafeWorldCell<'w>, func: FN )

👎Deprecated since 0.13.0: QueryState::for_each_unchecked was not idiomatic Rust and has been moved to query.iter_unchecked_manual().for_each()

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.

Safety

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

pub fn par_iter<'w, 's>( &'s mut self, world: &'w World ) -> QueryParIter<'w, 's, D::ReadOnly, F>

Returns a parallel iterator over the query results for the given World.

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

Note that you must use the for_each method to iterate over the results, see par_iter_mut for an example.

pub fn par_iter_mut<'w, 's>( &'s mut self, world: &'w mut World ) -> QueryParIter<'w, 's, D, F>

Returns a parallel iterator over the query results for the given World.

This can only be called for mutable queries, see par_iter for read-only-queries.

Examples

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

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


let mut world = World::new();


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

query_state.par_iter_mut(&mut world).for_each(|mut a| {
    a.0 += 5;
});

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.

pub fn single<'w>(&mut self, world: &'w World) -> ROQueryItem<'w, D>

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.

pub fn get_single<'w>( &mut self, world: &'w World ) -> Result<ROQueryItem<'w, D>, QuerySingleError>

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.

pub fn single_mut<'w>(&mut self, world: &'w mut World) -> D::Item<'w>

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.

pub fn get_single_mut<'w>( &mut self, world: &'w mut World ) -> Result<D::Item<'w>, 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.

pub unsafe fn get_single_unchecked<'w>( &mut self, world: UnsafeWorldCell<'w> ) -> Result<D::Item<'w>, QuerySingleError>

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.

pub unsafe fn get_single_unchecked_manual<'w>( &self, world: UnsafeWorldCell<'w>, last_run: Tick, this_run: Tick ) -> Result<D::Item<'w>, QuerySingleError>

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

impl<D: QueryData, F: QueryFilter> Debug for QueryState<D, F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, D: QueryData + 'static, F: QueryFilter + 'static> ExclusiveSystemParam for &'a mut QueryState<D, F>

type State = QueryState<D, F>

Used to store data which persists across invocations of a system.

type Item<'s> = &'s mut QueryState<D, F>

The item type returned when constructing this system param. See SystemParam::Item.

fn init(world: &mut World, _system_meta: &mut SystemMeta) -> Self::State

Creates a new instance of this param’s State.

fn get_param<'s>( state: &'s mut Self::State, _system_meta: &SystemMeta ) -> Self::Item<'s>

Creates a parameter to be passed into an ExclusiveSystemParamFunction.

impl<D: QueryData, F: QueryFilter> From<QueryBuilder<'_, D, F>> for QueryState<D, F>

fn from(value: QueryBuilder<'_, D, F>) -> Self

Converts to this type from the input type.

impl<D: QueryData, F: QueryFilter> FromWorld for QueryState<D, F>

fn from_world(world: &mut World) -> Self

Creates Self using data from the given World.