Struct valence::ecs::prelude::QueryBuilder

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

where D: QueryData, F: QueryFilter,

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

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>(&mut self) -> &mut QueryBuilder<'w, D, F>

where T: QueryData,

Adds accesses required for T to self.

pub fn filter<T>(&mut self) -> &mut QueryBuilder<'w, D, F>

where T: QueryFilter,

Adds filter from T to self.

pub fn with<T>(&mut self) -> &mut QueryBuilder<'w, D, F>

where T: Component,

Adds With<T> to the FilteredAccess of self.

pub fn with_id(&mut self, id: ComponentId) -> &mut QueryBuilder<'w, D, F>

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

pub fn without<T>(&mut self) -> &mut QueryBuilder<'w, D, F>

where T: Component,

Adds Without<T> to the FilteredAccess of self.

pub fn without_id(&mut self, id: ComponentId) -> &mut QueryBuilder<'w, D, F>

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

pub fn ref_id(&mut self, id: ComponentId) -> &mut QueryBuilder<'w, D, F>

Adds &T to the FilteredAccess of self.

pub fn mut_id(&mut self, id: ComponentId) -> &mut QueryBuilder<'w, D, F>

Adds &mut T to the FilteredAccess of self.

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

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 QueryBuilder<'w, D, F>

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 QueryBuilder<'w, D, F>

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 FilteredAccess that will be provided to the built Query.

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

where NewD: QueryData,

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

If including a filter type see Self::transmute_filtered

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

where NewD: QueryData, NewF: QueryFilter,

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