Struct bevy_ecs::query::QueryState

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

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

Implementations§

source§

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

source

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

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

source

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

source

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

Returns the archetype components accessed by this query.

source

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

Returns the components accessed by this query.

source

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

Returns the tables matched by this query.

source

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

Returns the archetypes matched by this query.

source§

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

source

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

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

source

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

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

source

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.

source

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.

source

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.

source

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.

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

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.

source

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

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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
source

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
source

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.

source

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.

source

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.

source

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

source

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

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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§

source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

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

Creates a new instance of this param’s State.
source§

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

Creates a parameter to be passed into an ExclusiveSystemParamFunction.
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Creates Self using data from the given World.

Auto Trait Implementations§

§

impl<D, F> RefUnwindSafe for QueryState<D, F>

§

impl<D, F> Send for QueryState<D, F>

§

impl<D, F> Sync for QueryState<D, F>

§

impl<D, F> Unpin for QueryState<D, F>
where <D as WorldQuery>::State: Unpin, <F as WorldQuery>::State: Unpin,

§

impl<D, F> UnwindSafe for QueryState<D, F>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Downcast for T
where T: Any,

source§

fn into_any(self: Box<T>) -> Box<dyn Any>

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

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
source§

fn as_any(&self) -> &(dyn Any + 'static)

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

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

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

impl<T> DowncastSync for T
where T: Any + Send + Sync,

source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

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

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

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

fn with_current_subscriber(self) -> WithDispatch<Self>

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