Struct QueryState 

pub struct QueryState<D, F = ()>
where
    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

Safety

If the query is not read-only, then before calling any other methods on a new QueryState other than QueryState::update_archetypes, QueryState::update_archetypes_unsafe_world_cell, Self::init_access must be called.

Implementations

impl<D, F> QueryState<D, F>

where D: QueryData, F: QueryFilter,

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

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

pub fn component_access(&self) -> &FilteredAccess

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.

pub unsafe fn new_unchecked(world: &mut World) -> QueryState<D, F>

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

Unlike QueryState::new, this does not check access of nested queries, so Self::init_access must be called before querying using this state or returning it to safe code.

Safety

If the query is not read-only, then before calling any other methods on the returned QueryState other than QueryState::update_archetypes, QueryState::update_archetypes_unsafe_world_cell, Self::init_access must be called.

pub fn init_access( &self, system_name: Option<&str>, component_access_set: &mut FilteredAccessSet, world: UnsafeWorldCell<'_>, )

Adds all access from this query and any nested queries to the component_access_set. Panics if the access from this query and any nested queries conflict with each other or with any previous access.

pub fn new(world: &mut World) -> QueryState<D, F>

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

pub fn try_new(world: &World) -> Option<QueryState<D, F>>

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

This function may fail if, for example, the components that make up this query have not been registered into the world.

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

Creates a new QueryState from a given QueryBuilder and inherits its FilteredAccess.

pub fn query<'w, 's>( &'s mut self, world: &'w World, ) -> Query<'w, 's, <D as QueryData>::ReadOnly, F>

Creates a Query from the given QueryState and World.

This will create read-only queries, see Self::query_mut for mutable queries.

pub fn query_manual<'w, 's>( &'s self, world: &'w World, ) -> Query<'w, 's, <D as QueryData>::ReadOnly, F>

Creates a Query from the given QueryState and World.

This method is slightly more efficient than QueryState::query in some situations, since it does not update this instance’s internal cache. The resulting query may skip an entity that 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 will create read-only queries, see Self::query_mut for mutable queries.

pub fn query_mut<'w, 's>( &'s mut self, world: impl Into<DeferredWorld<'w>>, ) -> Query<'w, 's, D, F>

Creates a Query from the given QueryState and World.

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

Creates a Query from the given QueryState and 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 query_unchecked_manual<'w, 's>( &'s self, world: UnsafeWorldCell<'w>, ) -> Query<'w, 's, D, F>

Creates a Query from the given QueryState and World.

This method is slightly more efficient than QueryState::query_unchecked in some situations, since it does not update this instance’s internal cache. The resulting query may skip an entity that 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.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query. This does not validate that world.id() matches self.world_id. Calling this on a world with a mismatched WorldId is unsound.

pub unsafe fn query_unchecked_with_ticks<'w, 's>( &'s mut self, world: UnsafeWorldCell<'w>, last_run: Tick, this_run: Tick, ) -> Query<'w, 's, D, F>

Creates a Query from the given QueryState and 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 query_unchecked_manual_with_ticks<'w, 's>( &'s self, world: UnsafeWorldCell<'w>, last_run: Tick, this_run: Tick, ) -> Query<'w, 's, D, F>

Creates a Query from the given QueryState and World.

This method is slightly more efficient than QueryState::query_unchecked_with_ticks in some situations, since it does not update this instance’s internal cache. The resulting query may skip an entity that 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.

Safety

This does not check for mutable query correctness. To be safe, make sure mutable queries have unique access to the components they query. This does not validate that world.id() matches self.world_id. Calling this on a world with a mismatched WorldId is unsound.

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, Changed or Spawned 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)

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

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 fn transmute<'a, NewD>( &self, world: impl Into<UnsafeWorldCell<'a>>, ) -> QueryState<NewD>

where NewD: SingleEntityQueryData,

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<'a, NewD, NewF>( &self, world: impl Into<UnsafeWorldCell<'a>>, ) -> QueryState<NewD, NewF>

where NewD: SingleEntityQueryData, NewF: QueryFilter,

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<'a, OtherD, NewD>( &self, world: impl Into<UnsafeWorldCell<'a>>, other: &QueryState<OtherD>, ) -> QueryState<NewD>

where OtherD: QueryData, NewD: SingleEntityQueryData,

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<'a, OtherD, OtherF, NewD, NewF>( &self, world: impl Into<UnsafeWorldCell<'a>>, other: &QueryState<OtherD, OtherF>, ) -> QueryState<NewD, NewF>

where OtherD: QueryData, OtherF: QueryFilter, NewD: SingleEntityQueryData, NewF: QueryFilter,

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<<<D as QueryData>::ReadOnly as QueryData>::Item<'w, '_>, 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.

If you need to get multiple items at once but get borrowing errors, consider using Self::update_archetypes followed by multiple Self::get_manual calls, or making a single call with Self::get_many or Self::iter_many.

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<[<<D as QueryData>::ReadOnly as QueryData>::Item<'w, '_>; 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_u32(365).unwrap();

assert_eq!(match query_state.get_many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::NotSpawned(error) => error.entity(), _ => panic!()}, wrong_entity);

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

Returns the read-only query results for the given UniqueEntityArray.

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

Examples

use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, UniqueEntityArray, UniqueEntityVec}};

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

let mut world = World::new();
let entity_set: UniqueEntityVec = world.spawn_batch((0..3).map(A)).collect_set();
let entity_set: UniqueEntityArray<3> = entity_set.try_into().unwrap();

world.spawn(A(73));

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

let component_values = query_state.get_many_unique(&world, entity_set).unwrap();

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

let wrong_entity = Entity::from_raw_u32(365).unwrap();

assert_eq!(match query_state.get_many_unique(&mut world, UniqueEntityArray::from([wrong_entity])).unwrap_err() {QueryEntityError::NotSpawned(error) => error.entity(), _ => panic!()}, wrong_entity);

pub fn get_mut<'w>( &mut self, world: &'w mut World, entity: Entity, ) -> Result<<D as QueryData>::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 as QueryData>::Item<'w, '_>; N], QueryEntityError>

where D: IterQueryData,

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_u32(57).unwrap();
let invalid_entity = world.spawn_empty().id();

assert_eq!(match query_state.get_many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::NotSpawned(error) => error.entity(), _ => panic!()}, wrong_entity);
assert_eq!(match query_state.get_many_mut(&mut world, [invalid_entity]).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity);
assert_eq!(query_state.get_many_mut(&mut world, [entities[0], entities[0]]).unwrap_err(), QueryEntityError::AliasedMutability(entities[0]));

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

where D: IterQueryData,

Returns the query results for the given UniqueEntityArray.

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

use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, UniqueEntityArray, UniqueEntityVec}};

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

let mut world = World::new();

let entity_set: UniqueEntityVec = world.spawn_batch((0..3).map(A)).collect_set();
let entity_set: UniqueEntityArray<3> = entity_set.try_into().unwrap();

world.spawn(A(73));

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

let mut mutable_component_values = query_state.get_many_unique_mut(&mut world, entity_set).unwrap();

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

let component_values = query_state.get_many_unique(&world, entity_set).unwrap();

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

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

assert_eq!(match query_state.get_many_unique(&mut world, UniqueEntityArray::from([wrong_entity])).unwrap_err() {QueryEntityError::NotSpawned(error) => error.entity(), _ => panic!()}, wrong_entity);
assert_eq!(match query_state.get_many_unique_mut(&mut world, UniqueEntityArray::from([invalid_entity])).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity);

pub fn get_manual<'w>( &self, world: &'w World, entity: Entity, ) -> Result<<<D as QueryData>::ReadOnly as QueryData>::Item<'w, '_>, 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 as QueryData>::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 as QueryData>::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.

If you need to iterate multiple times at once but get borrowing errors, consider using Self::update_archetypes followed by multiple Self::iter_manual calls.

Examples found in repository

examples/reflection/mutation_by_reflection.rs (line 111)

fn modify_selected_component(world: &mut World) {
    // We're using keyboard input to trigger modifications for simplicity.
    let button_input = world.resource::<ButtonInput<KeyCode>>();
    let direction_of_modification = if button_input.pressed(KeyCode::ArrowUp) {
        1.0
    } else if button_input.pressed(KeyCode::ArrowDown) {
        -1.0
    } else {
        return; // No modification requested
    };

    let selected = world.resource::<SelectedComponent>().clone();

    let mut sprite_query = world.query_filtered::<Entity, With<Sprite>>();

    // This entity should generally be gathered via UI selection in a real application
    let entity = sprite_query.iter(world).next().unwrap();

    // We could cheat and use `TypeId::of::<T>()` to get the type ID of a known type,
    // but real applications identify types by name (from a UI dropdown, text entry or a script).
    let type_name = match selected {
        // Note that Bevy's native types are registered under their full subcrate paths:
        // `bevy_transform`, not `bevy::transform`, `bevy::prelude`, or `bevy_transform::prelude`.
        // You can use `<T as TypePath>::type_path()` to look this up.
        SelectedComponent::Transform => "bevy_transform::components::transform::Transform",
        SelectedComponent::Sprite => "bevy_sprite::sprite::Sprite",
    };

    // Then, we need to use a type registry to resolve the type name to a `TypeId`.
    // Types are (for the most part) registered automatically by Bevy,
    // but you can also register your own types using `App::register_type`.
    // Generic types always need to be registered manually;
    // if a type is not showing up in your tool, check if that's the problem.
    // You can check which types are registered by calling `TypeRegistry::iter()`,
    // and then use the `Debug` impl for `TypeRegistration` objects to see their names and paths.
    let app_registry = world.resource::<AppTypeRegistry>().clone();
    let type_id = app_registry
        .read()
        .get_with_type_path(type_name)
        .expect("Type was not registered, or its full path was ambiguous")
        .type_id();

    let mut reflected_component: Mut<dyn Reflect> = world.get_reflect_mut(entity, type_id).unwrap();

    match selected {
        // Downcasting is the easy path:
        // if you happen to know the type, you can downcast and modify directly.
        // The problem is that each of these paths would need to be hard-coded (or rely on extensive code-gen),
        // largely defeating the purpose of using reflection in the first place.
        SelectedComponent::Sprite => {
            // Make sure that the type matches the component type you requested to modify.
            // In a real project, you would want to handle this gracefully.
            // Downcasting converts the value *directly* into a specified concrete type,
            // allowing you to escape back into faster, strongly-typed code.
            let downcast_sprite: &mut Sprite =
                reflected_component.downcast_mut::<Sprite>().unwrap();
            // Be careful not to modify a copy of the color — use `&mut`!
            let color = &mut downcast_sprite.color;

            let new_alpha = (color.alpha() + 0.01 * direction_of_modification).clamp(0.0, 1.0);
            color.set_alpha(new_alpha);
        }
        // This arm demonstrates the more realistic, generic pattern:
        // walking the reflected type info to find fields to modify.
        // The benefit is that we can use these patterns
        // to operate over *any* data based on our knowledge of its shape (recorded using reflection),
        // without needing to know the concrete type at compile time.
        SelectedComponent::Transform => {
            let reflect_mut: ReflectMut<'_> = reflected_component.reflect_mut();
            // In the fully generic case, we would need to match on the `ReflectMut` variants
            // and handle each of the arms exhaustively.
            // `struct_mut` is of type `&mut dyn Struct`, one of a number
            // of traits that encodes the logic of Rust's type system into a runtime representation.
            let ReflectMut::Struct(struct_mut) = reflect_mut else {
                error!("Expected the Transform component type to be a struct");
                return;
            };

            // Get the `translation` field as a `&mut dyn PartialReflect`,
            // which is a type-erased representation of a value that can be modified.
            let translation_field = struct_mut.field_mut("translation").unwrap();

            // Now, we can repeat the process to get the `y` field of the `translation` Vec3
            // In a real application, this would probably be done via a recursive function!
            let ReflectMut::Struct(translation_struct) = translation_field.reflect_mut() else {
                error!("Expected the translation field to be a struct");
                return;
            };

            // We could downcast to an f32 again here, but that would be cheating!
            // How do you generalize this sort of operation, if, for example,
            // you wanted to build a generic inspector that could modify any numeric field of any component type?
            // The solution lies in the way that Bevy can reflect *traits* as well as types,
            // allowing type owners to define and register additional behavior for their types.
            // This data is registered automatically at compile time using an inventory-like solution,
            // and operates on a per-type x per-trait basis,
            // just like ordinary type reflection.
            //
            // We want to increase or decrease the value here,
            // so we need the `AddAssign` trait
            // which are already implemented for f32.
            //
            // But `AddAssign` is not a supertrait of `PartialReflect`!
            // We don't have access to its methods! How could that possibly work?
            //
            // The solution is again to register the compile time information that we want to use at runtime;
            // storing function pointers to the trait methods in the type registry.
            // In order to make this work, we need shadow "reflect" versions of the traits we want to use at runtime.
            // Bevy provides a few of these out of the box, including `ReflectAddAssign` and `ReflectSubAssign`.
            // That's what the `#[reflect(Add)]` attributes that you see scattered about in Bevy's source code are doing:
            // generating implementations of the reflect versions of the traits, so they can later be registered and used at runtime.
            //
            // For more information, see the `type_data` example.
            let y_field: &mut dyn PartialReflect = translation_struct.field_mut("y").unwrap();
            let field_type_id = y_field
                .get_represented_type_info()
                .expect("Found a dynamic type unexpectedly")
                .type_id();

            let add_assign_trait_data = app_registry
                .read()
                .get_type_data::<ReflectAddAssign>(field_type_id)
                .expect("f32 failed to register ReflectAddAssign")
                .clone();

            // We need to operate on the value as a concrete type,
            // so we need to convert it into the more powerful &dyn Reflect type.
            let y_field: &mut dyn Reflect = y_field.try_as_reflect_mut().expect(
                "Found a dynamic type unexpectedly, but we need a concrete type to modify it",
            );

            // We're still cheating a bit here!
            // By doing this we just *assume* that there's an f32 value when trying to determine what to add to the field.
            // We *could* try all of the common numeric types, but that would be slow and non-extensible.
            //
            // In a real workflow, you would want a dedicated trait with additional methods that exposes
            // something like dedicated `increment` and `decrement` methods, which handle the type-specific logic of how to modify the value.
            // Remember to register that trait, and create your own analog of `ReflectAddAssign` for it!
            //
            // We don't do that here to avoid making this example *even more* complicated.
            const MAGNITUDE_OF_MODIFICATION: f32 = 10.;
            let delta = direction_of_modification * MAGNITUDE_OF_MODIFICATION;
            let boxed_delta: Box<dyn PartialReflect> = Box::new(delta);
            add_assign_trait_data
                .add_assign(y_field, boxed_delta)
                .expect("We cheated and know the types match, so this should always succeed.");
        }
    }
}

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.

Examples found in repository

examples/ecs/dynamic.rs (line 180)

fn main() {
    let mut world = World::new();
    let mut lines = std::io::stdin().lines();
    let mut component_names = HashMap::<String, ComponentId>::new();
    let mut component_info = HashMap::<ComponentId, ComponentInfo>::new();
    let mut event_names = HashMap::<String, EventKey>::new();

    println!("{PROMPT}");
    loop {
        print!("\n> ");
        let _ = std::io::stdout().flush();
        let Some(Ok(line)) = lines.next() else {
            return;
        };

        if line.is_empty() {
            return;
        };

        let Some((first, rest)) = line.trim().split_once(|c: char| c.is_whitespace()) else {
            match &line.chars().next() {
                Some('c') => println!("{COMPONENT_PROMPT}"),
                Some('s') => println!("{ENTITY_PROMPT}"),
                Some('q') => println!("{QUERY_PROMPT}"),
                Some('e') => println!("{EVENT_PROMPT}"),
                Some('t') => println!("{EMIT_PROMPT}"),
                _ => println!("{PROMPT}"),
            }
            continue;
        };

        match &first[0..1] {
            "c" => {
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };
                    let size = match component.next().map(str::parse) {
                        Some(Ok(size)) => size,
                        _ => 0,
                    };
                    // Register our new component to the world with a layout specified by its size
                    // SAFETY: [u64] is Send + Sync
                    let id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            name.to_string(),
                            StorageType::Table,
                            Layout::array::<u64>(size).unwrap(),
                            None,
                            true,
                            false,
                            ComponentCloneBehavior::Default,
                            None,
                        )
                    });
                    let Some(info) = world.components().get_info(id) else {
                        return;
                    };
                    component_names.insert(name.to_string(), id);
                    component_info.insert(id, info.clone());
                    println!("Component {} created with id: {}", name, id.index());
                });
            }
            "s" => {
                let mut to_insert_ids = Vec::new();
                let mut to_insert_data = Vec::new();
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };

                    // Get the id for the component with the given name
                    let Some(&id) = component_names.get(name) else {
                        println!("Component {name} does not exist");
                        return;
                    };

                    // Calculate the length for the array based on the layout created for this component id
                    let info = world.components().get_info(id).unwrap();
                    let len = info.layout().size() / size_of::<u64>();
                    let mut values: Vec<u64> = component
                        .take(len)
                        .filter_map(|value| value.parse::<u64>().ok())
                        .collect();
                    values.resize(len, 0);

                    // Collect the id and array to be inserted onto our entity
                    to_insert_ids.push(id);
                    to_insert_data.push(values);
                });

                let mut entity = world.spawn_empty();

                // Construct an `OwningPtr` for each component in `to_insert_data`
                let to_insert_ptr = to_owning_ptrs(&mut to_insert_data);

                // SAFETY:
                // - Component ids have been taken from the same world
                // - Each array is created to the layout specified in the world
                unsafe {
                    entity.insert_by_ids(&to_insert_ids, to_insert_ptr.into_iter());
                }

                println!("Entity spawned with id: {}", entity.id());
            }
            "q" => {
                let mut builder = QueryBuilder::<FilteredEntityMut>::new(&mut world);
                parse_query(rest, &mut builder, &component_names);
                let mut query = builder.build();
                query.iter_mut(&mut world).for_each(|filtered_entity| {
                    let terms = filtered_entity
                        .access()
                        .try_iter_access()
                        .unwrap()
                        .map(|component_access| {
                            let id = *component_access.index();
                            let ptr = filtered_entity.get_by_id(id).unwrap();
                            let info = component_info.get(&id).unwrap();
                            let len = info.layout().size() / size_of::<u64>();

                            // SAFETY:
                            // - All components are created with layout [u64]
                            // - len is calculated from the component descriptor
                            let data = unsafe {
                                std::slice::from_raw_parts_mut(
                                    ptr.assert_unique().as_ptr().cast::<u64>(),
                                    len,
                                )
                            };

                            // If we have write access, increment each value once
                            if matches!(component_access, ComponentAccessKind::Exclusive(_)) {
                                data.iter_mut().for_each(|data| {
                                    *data += 1;
                                });
                            }

                            format!("{}: {:?}", info.name(), data[0..len].to_vec())
                        })
                        .collect::<Vec<_>>()
                        .join(", ");

                    println!("{}: {}", filtered_entity.id(), terms);
                });
            }
            "e" => {
                rest.split(',').for_each(|event| {
                    let name = event.trim();
                    if name.is_empty() {
                        return;
                    }

                    // Register a ComponentId for this event, no Rust type needed.
                    // SAFETY: ZST with no drop
                    let event_component_id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            format!("event:{name}"),
                            StorageType::Table,
                            Layout::new::<()>(),
                            None,
                            false,
                            false,
                            ComponentCloneBehavior::Ignore,
                            None,
                        )
                    });
                    // SAFETY: event_component_id was just registered for this event
                    let event_key = unsafe { EventKey::new(event_component_id) };
                    event_names.insert(name.to_string(), event_key);

                    // Build a dynamic observer that prints when the event fires.
                    let runner: ObserverRunner = |mut world, _observer, ctx, _event, _trigger| {
                        println!("  Observer fired!");
                        if let Some(mut counts) = world.get_resource_mut::<EventFireCount>() {
                            *counts.0.entry(ctx.event_key).or_insert(0) += 1;
                        }
                    };

                    // SAFETY: event_key was just registered, runner ignores pointers
                    let observer =
                        unsafe { Observer::with_dynamic_runner(runner).with_event_key(event_key) };
                    world.spawn(observer);

                    println!(
                        "Event '{name}' registered (key: {}) with a dynamic observer",
                        event_component_id.index()
                    );
                });

                // Ensure the counter resource exists.
                world.init_resource::<EventFireCount>();
            }
            "t" => {
                let name = rest.trim();
                let Some(&event_key) = event_names.get(name) else {
                    println!(
                        "Event '{name}' does not exist. Register it first with 'event {name}'"
                    );
                    continue;
                };

                let mut event_data = ();
                let mut trigger_data = ();
                // SAFETY: event_key was registered in this world, both pointers are valid ZSTs
                unsafe {
                    world.trigger_dynamic(
                        event_key,
                        PtrMut::from(&mut event_data),
                        PtrMut::from(&mut trigger_data),
                    );
                }

                let count = world
                    .get_resource::<EventFireCount>()
                    .map_or(0, |c| c.0.get(&event_key).copied().unwrap_or(0));
                println!("Event '{name}' triggered ({count} fires)");
            }
            _ => continue,
        }
    }
}

pub fn iter_manual<'w, 's>( &'s self, world: &'w World, ) -> QueryIter<'w, 's, <D as QueryData>::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 as QueryData>::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>

where D: IterQueryData,

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>( &'s mut self, world: &'w World, entities: EntityList, ) -> QueryManyIter<'w, 's, <D as QueryData>::ReadOnly, F, <EntityList as IntoIterator>::IntoIter>

where EntityList: IntoIterator, <EntityList as IntoIterator>::Item: EntityEquivalent,

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. In case of a nonexisting entity or mismatched component, a QueryEntityError is generated instead.

If you need to iterate multiple times at once but get borrowing errors, consider using Self::update_archetypes followed by multiple Self::iter_many_manual calls.

See also

• iter_many_mut to get mutable query items.

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

where EntityList: IntoIterator, <EntityList as IntoIterator>::Item: EntityEquivalent,

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. In case of a nonexisting entity or mismatched component, a QueryEntityError is generated instead.

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>( &'s mut self, world: &'w mut World, entities: EntityList, ) -> QueryManyIter<'w, 's, D, F, <EntityList as IntoIterator>::IntoIter>

where EntityList: IntoIterator, <EntityList as IntoIterator>::Item: EntityEquivalent,

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

Items are returned in the order of the list of entities. In case of a nonexisting entity or mismatched component, a QueryEntityError is generated instead.

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

where EntityList: EntitySet,

Returns an Iterator over the unique read-only query items generated from an EntitySet.

Items are returned in the order of the list of entities. In case of a nonexisting entity or mismatched component, a QueryEntityError is generated instead.

See also

• iter_many_unique_mut to get mutable query items.

pub fn iter_many_unique_manual<'w, 's, EntityList>( &'s self, world: &'w World, entities: EntityList, ) -> QueryManyUniqueIter<'w, 's, <D as QueryData>::ReadOnly, F, <EntityList as IntoIterator>::IntoIter>

where EntityList: EntitySet,

Returns an Iterator over the unique read-only query items generated from an EntitySet.

Items are returned in the order of the list of entities. In case of a nonexisting entity or mismatched component, a QueryEntityError is generated instead.

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_unique to update archetypes.
• iter_many to iterate over a non-unique entity list.
• iter_manual to iterate over all query items.

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

where EntityList: EntitySet, D: IterQueryData,

Returns an iterator over the unique query items generated from an EntitySet.

Items are returned in the order of the list of entities. In case of a nonexisting entity or mismatched component, a QueryEntityError is generated instead.

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>

where D: IterQueryData,

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 as QueryData>::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>

where D: IterQueryData,

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




assert_eq!(match query_state.get_many_mut(&mut world, [invalid_entity]).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity);

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 contiguous_iter<'w, 's>( &'s mut self, world: &'w World, ) -> Result<QueryContiguousIter<'w, 's, <D as QueryData>::ReadOnly, F>, QueryNotDenseError>

where <D as QueryData>::ReadOnly: ContiguousQueryData, F: ArchetypeFilter,

Returns a contiguous iterator over the query results for the given World or Err with QueryNotDenseError if the query is not dense hence not contiguously iterable.

pub fn contiguous_iter_mut<'w, 's>( &'s mut self, world: &'w mut World, ) -> Result<QueryContiguousIter<'w, 's, D, F>, QueryNotDenseError>

where D: ContiguousQueryData, F: ArchetypeFilter,

Returns a contiguous iterator over the query results for the given World or Err with QueryNotDenseError if the query is not dense hence not contiguously iterable.

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

pub fn contiguous_par_iter<'w, 's>( &'s mut self, world: &'w World, ) -> Result<QueryContiguousParIter<'w, 's, <D as QueryData>::ReadOnly, F>, QueryNotDenseError>

where <D as QueryData>::ReadOnly: ContiguousQueryData, F: ArchetypeFilter,

Returns a parallel contiguous iterator over the query results for the given World or Err with QueryNotDenseError if the query is not dense hence not contiguously iterable.

This can only be called for read-only queries. See Self::contiguous_par_iter_mut for queries that may write to the components.

Note that you must use the QueryContiguousParIter::for_each method to iterate over the results. See Self::contiguous_par_iter_mut for an example.

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 contiguous_par_iter_mut<'w, 's>( &'s mut self, world: &'w mut World, ) -> Result<QueryContiguousParIter<'w, 's, D, F>, QueryNotDenseError>

where D: ContiguousQueryData, F: ArchetypeFilter,

Returns a parallel contiguous iterator over the query results for the given World or Err with QueryNotDenseError if the query is not dense hence not contiguously iterable.

This version of the method is for mutable queries. For read-only queries, see Self::contiguous_par_iter.

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.contiguous_par_iter_mut(&mut world).unwrap().for_each(|mut batch| {
    for a in batch {
        a.0 += 5;
    }
});




assert_eq!(match query_state.get_many_mut(&mut world, [invalid_entity]).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity);

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.

impl<D, F> QueryState<D, F>

where D: QueryData, F: QueryFilter,

pub fn single<'w>( &mut self, world: &'w World, ) -> Result<<<D as QueryData>::ReadOnly as QueryData>::Item<'w, '_>, 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 single_mut for write-queries.

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

Example

Sometimes, you might want to handle the error in a specific way, generally by spawning the missing entity.

use bevy_ecs::prelude::*;
use bevy_ecs::query::QuerySingleError;

#[derive(Component)]
struct A(usize);

fn my_system(query: Query<&A>, mut commands: Commands) {
    match query.single() {
        Ok(a) => (), // Do something with `a`
        Err(err) => match err {
            QuerySingleError::NoEntities(_) => {
                commands.spawn(A(0));
            }
            QuerySingleError::MultipleEntities(_) => panic!("Multiple entities found!"),
        },
    }
}

However in most cases, this error can simply be handled with a graceful early return. If this is an expected failure mode, you can do this using the let else pattern like so:

use bevy_ecs::prelude::*;

#[derive(Component)]
struct A(usize);

fn my_system(query: Query<&A>) {
  let Ok(a) = query.single() else {
    return;
  };

  // Do something with `a`
}

If this is unexpected though, you should probably use the ? operator in combination with Bevy’s error handling apparatus.

use bevy_ecs::prelude::*;

#[derive(Component)]
struct A(usize);

fn my_system(query: Query<&A>) -> Result {
 let a = query.single()?;

 // Do something with `a`
 Ok(())
}

This allows you to globally control how errors are handled in your application, by setting up a custom error handler. See the bevy_ecs::error module docs for more information! Commonly, you might want to panic on an error during development, but log the error and continue execution in production.

Simply unwrapping the Result also works, but should generally be reserved for tests.

pub fn single_mut<'w>( &mut self, world: &'w mut World, ) -> Result<<D as QueryData>::Item<'w, '_>, QuerySingleError>

where D: IterQueryData,

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.

Examples

Please see Query::single for advice on handling the error.

Examples found in repository

examples/window/persisting_window_settings.rs (line 56)

fn init_window_pos(app: &mut App) {
    let world = app.world_mut();
    let Some(window_settings) = world.get_resource::<WindowSettings>() else {
        return;
    };
    let window_settings = window_settings.clone();

    let Ok(mut window) = world.query::<&mut Window>().single_mut(world) else {
        warn!("window not found");
        return;
    };

    if let Some(position) = window_settings.position {
        window.position = WindowPosition::new(position);
    }

    if let Some(size) = window_settings.size {
        window.resolution = WindowResolution::new(size.x, size.y);
    }

    window.mode = if window_settings.fullscreen {
        WindowMode::BorderlessFullscreen(MonitorSelection::Current)
    } else {
        WindowMode::Windowed
    };
}

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

where D: IterQueryData,

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 single_unchecked_manual<'w>( &self, world: UnsafeWorldCell<'w>, last_run: Tick, this_run: Tick, ) -> Result<<D as QueryData>::Item<'w, '_>, QuerySingleError>

where D: IterQueryData,

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. This does not validate that world.id() matches self.world_id. Calling this on a world with a mismatched WorldId is unsound.

Trait Implementations

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

where D: QueryData, F: QueryFilter,

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

Formats the value using the given formatter.

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

where D: QueryData, F: QueryFilter,

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

Converts to this type from the input type.

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

where D: QueryData, F: QueryFilter,

fn from_world(world: &mut World) -> QueryState<D, F>

Creates Self using data from the given World.

impl<D, F> ReadOnlySystemParam for &mut QueryState<D, F>

where D: QueryData + 'static, F: QueryFilter + 'static,

impl<D, F> SystemParam for &mut QueryState<D, F>

where D: QueryData + 'static, F: QueryFilter + 'static,

type State = QueryState<D, F>

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

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

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state( world: &mut World, ) -> <&mut QueryState<D, F> as SystemParam>::State

Creates a new instance of this param’s State.

fn init_access( _state: &<&mut QueryState<D, F> as SystemParam>::State, _system_meta: &mut SystemMeta, _system_access: &mut SystemAccess, _world: &mut World, )

Registers any World access used by this SystemParam.

unsafe fn get_param<'world, 'state>( state: &'state mut <&mut QueryState<D, F> as SystemParam>::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'world>, _change_tick: Tick, ) -> Result<<&mut QueryState<D, F> as SystemParam>::Item<'world, 'state>, SystemParamValidationError>

Creates a parameter to be passed into a SystemParamFunction.

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

impl<'w, 's, D, F> SystemParamBuilder<Query<'w, 's, D, F>> for QueryState<D, F>

where D: QueryData + 'static, F: QueryFilter + 'static,

fn build(self, world: &mut World) -> QueryState<D, F>

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

fn build_state(self, world: &mut World) -> SystemState<P>

Create a SystemState from a SystemParamBuilder. To create a system, call SystemState::build_system on the result.

fn build_system<Marker, In, Out, Func>( self, func: Func, ) -> IntoBuilderSystem<Marker, In, Out, Func, Self>

where Self: 'static, Func: SystemParamFunction<Marker, Param = P>,

Create a System from a SystemParamBuilder directly.