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

This data is cached between system runs, and is used to:

• store metadata about which Table or Archetype are matched by the query. “Matched” means that the query will iterate over the data in the matched table/archetype.
• cache the State needed to compute the Fetch struct used to retrieve data from a specific Table or Archetype
• build iterators that can iterate over the query results

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 component_access(&self) -> &FilteredAccess<ComponentId>

Returns the components accessed by this query.

pub fn matched_tables(&self) -> impl Iterator<Item = TableId> + '_

Returns the tables matched by this query.

pub fn matched_archetypes(&self) -> impl Iterator<Item = 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 its 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.

This is equivalent to self.iter().next().is_none(), and thus the worst case runtime will be O(n) where n is the number of potential matches. This can be notably expensive for queries that rely on non-archetypal filters such as Added or Changed which must individually check each query result for a match.

Panics

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

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

Returns true if the given Entity matches the query.

This is always guaranteed to run in O(1) time.

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 unsafe fn new_archetype( &mut self, archetype: &Archetype, access: &mut Access<ArchetypeComponentId>, )

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

The passed in access will be updated with any new accesses introduced by the new archetype.

Safety

archetype must be from the World this state was initialized from.

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 unsafe fn update_archetype_component_access( &mut self, archetype: &Archetype, access: &mut Access<ArchetypeComponentId>, )

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

The passed in access will be updated with any new accesses introduced by the new archetype.

Safety

archetype must be from the World this state was initialized from.

pub fn transmute<NewD: QueryData>( &self, components: &Components, ) -> 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, components: &Components, ) -> 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 join<OtherD: QueryData, NewD: QueryData>( &self, components: &Components, other: &QueryState<OtherD>, ) -> QueryState<NewD, ()>

Use this to combine two queries. The data accessed will be the intersection of archetypes included in both queries. This can be useful for accessing a subset of the entities between two queries.

You should not call update_archetypes on the returned QueryState as the result could 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 is best used through a Query.

Performance

This will have similar performance as constructing a new QueryState since much of internal state needs to be reconstructed. But it will be a little faster as it only needs to compare the intersection of matching archetypes rather than iterating over all archetypes.

Panics

Will panic if NewD contains accesses not in Q or OtherQ.

pub fn join_filtered<OtherD: QueryData, OtherF: QueryFilter, NewD: QueryData, NewF: QueryFilter>( &self, components: &Components, other: &QueryState<OtherD, OtherF>, ) -> QueryState<NewD, NewF>

Use this to combine two queries. The data accessed will be the intersection of archetypes included in both queries.

Panics

Will panic if NewD or NewF requires accesses not in Q or OtherQ.

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.

This is always guaranteed to run in O(1) time.

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.

This is always guaranteed to run in O(1) time.

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.

This is always guaranteed to run in O(1) time.

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.

This is always guaranteed to run in O(1) time.

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

This iterator is always guaranteed to return results from each matching entity once and only once. Iteration order is not guaranteed.

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 iterator is always guaranteed to return results from each matching entity once and only once. Iteration order is not guaranteed.

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 iterator is always guaranteed to return results from each unique pair of matching entities. Iteration order is not guaranteed.

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.

This iterator is always guaranteed to return results from each matching entity once and only once. Iteration order is not guaranteed.

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.

This iterator is always guaranteed to return results from each unique pair of matching entities. Iteration order is not guaranteed.

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.