Struct bevy_ecs::query::QueryBuilder

pub struct QueryBuilder<'w, D: QueryData = (), F: QueryFilter = ()> { /* private fields */ }

Builder struct to create QueryState instances at runtime.

let mut world = World::new();
let entity_a = world.spawn((A, B)).id();
let entity_b = world.spawn((A, C)).id();

// Instantiate the builder using the type signature of the iterator you will consume
let mut query = QueryBuilder::<(Entity, &B)>::new(&mut world)
// Add additional terms through builder methods
    .with::<A>()
    .without::<C>()
    .build();

// Consume the QueryState
let (entity, b) = query.single(&world);

Implementations

impl<'w, D: QueryData, F: QueryFilter> QueryBuilder<'w, D, F>

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

Creates a new builder with the accesses required for Q and F

pub fn world(&self) -> &World

Returns a reference to the world passed to Self::new.

pub fn world_mut(&mut self) -> &mut World

Returns a mutable reference to the world passed to Self::new.

pub fn extend_access(&mut self, access: FilteredAccess<ComponentId>)

Adds access to self’s underlying FilteredAccess respecting Self::or and Self::and

pub fn data<T: QueryData>(&mut self) -> &mut Self

Adds accesses required for T to self.

pub fn filter<T: QueryFilter>(&mut self) -> &mut Self

Adds filter from T to self.

pub fn with<T: Component>(&mut self) -> &mut Self

Adds With<T> to the FilteredAccess of self.

pub fn with_id(&mut self, id: ComponentId) -> &mut Self

Adds With<T> to the FilteredAccess of self from a runtime ComponentId.

pub fn without<T: Component>(&mut self) -> &mut Self

Adds Without<T> to the FilteredAccess of self.

pub fn without_id(&mut self, id: ComponentId) -> &mut Self

Adds Without<T> to the FilteredAccess of self from a runtime ComponentId.

pub fn ref_id(&mut self, id: ComponentId) -> &mut Self

Adds &T to the FilteredAccess of self.

pub fn mut_id(&mut self, id: ComponentId) -> &mut Self

Adds &mut T to the FilteredAccess of self.

pub fn optional(&mut self, f: impl Fn(&mut QueryBuilder<'_>)) -> &mut Self

Takes a function over mutable access to a QueryBuilder, calls that function on an empty builder and then adds all accesses from that builder to self as optional.

pub fn and(&mut self, f: impl Fn(&mut QueryBuilder<'_>)) -> &mut Self

Takes a function over mutable access to a QueryBuilder, calls that function on an empty builder and then adds all accesses from that builder to self.

Primarily used when inside a Self::or closure to group several terms.

pub fn or(&mut self, f: impl Fn(&mut QueryBuilder<'_>)) -> &mut Self

Takes a function over mutable access to a QueryBuilder, calls that function on an empty builder, all accesses added to that builder will become terms in an or expression.

QueryBuilder::<Entity>::new(&mut world).or(|builder| {
    builder.with::<A>();
    builder.with::<B>();
});
// is equivalent to
QueryBuilder::<Entity>::new(&mut world).filter::<Or<(With<A>, With<B>)>>();

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

Returns a reference to the the FilteredAccess that will be provided to the built Query.

pub fn transmute<NewD: QueryData>(&mut self) -> &mut QueryBuilder<'w, NewD>

Transmute the existing builder adding required accesses. This will maintain all exisiting accesses.

If including a filter type see Self::transmute_filtered

pub fn transmute_filtered<NewD: QueryData, NewF: QueryFilter>( &mut self ) -> &mut QueryBuilder<'w, NewD, NewF>

Transmute the existing builder adding required accesses. This will maintain all existing accesses.

pub fn build(&mut self) -> QueryState<D, F>

Create a QueryState with the accesses of the builder.

Takes &mut self to access the innner world reference while initializing state for the new QueryState

Trait Implementations

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.