Struct flax::Query

pub struct Query<Q, F = All>where
    Q: for<'x> Fetch<'x>,
    F: for<'x> Filter<'x>,{ /* private fields */ }

Represents a query and state for a given world. The archetypes to visit is cached in the query which means it is more performant to reuse the query than creating a new one.

The archetype borrowing assures aliasing. Two of the same queries can be run at the same time as long as they don’t borrow an archetype’s component mutably at the same time.

Implementations

impl<Q> Query<Q>where
    Q: for<'x> Fetch<'x>,

pub fn new(query: Q) -> Self

Construct a new query which will fetch all items in the given query. The query can be either a singular component, a tuple of components, or any other type which implements crate::Fetch.

Note: The query will not yield components, as it may not be intended behaviour since the most common intent is the entities. See Query::with_components

A fetch may also contain filters

impl<Q> Query<Q, All>where
    Q: for<'x> Fetch<'x>,

pub fn with_components(self) -> Self

Include component entities for the query. The default is to hide components as they are usually not desired during iteration.

impl<Q, F> Query<Q, F>where
    Q: for<'x> Fetch<'x>,
    F: for<'x> Filter<'x>,

pub fn filter<G: for<'x> Filter<'x>>(self, filter: G) -> Query<Q, And<F, G>>

Adds a new filter to the query. This filter is and:ed with the existing filters.

pub fn without<T: ComponentValue>(
    self,
    component: Component<T>
) -> Query<Q, And<F, Without>>

Shortcut for filter(without)

pub fn with<T: ComponentValue>(
    self,
    component: Component<T>
) -> Query<Q, And<F, With>>

Shortcut for filter(with)

pub fn change_tick(&self) -> u32

Returns the last change tick the query was run on. Any changes > change_tick will be yielded in a query iteration.

pub fn is_mut(&self) -> bool

Returns true if the query will mutate any components

pub fn borrow<'w>(&'w mut self, world: &'w World) -> QueryBorrow<'w, Q, F>

Borrow the world for the query.

Allows for both random access and efficient iteration. See: QueryBorrow::get and QueryBorrow::iter

The returned value holds the borrows of the query fetch. As such, all references from iteration or using QueryBorrow::get] will have a lifetime of the [QueryBorrow`.

This is because iterators can not yield references to internal state as all items returned by the iterator need to coexist.

It is safe to use the same prepared query for both iteration and random access, Rust’s borrow rules will ensure aliasing rules.

pub fn as_vec<'w, C>(&'w mut self, world: &'w World) -> Vec<C>where
    for<'q> <Q as FetchItem<'q>>::Item: TupleCloned<Cloned = C>,

Gathers all elements in the query as a Vec of owned values.

Trait Implementations

impl<Q: Clone, F: Clone> Clone for Query<Q, F>where
    Q: for<'x> Fetch<'x>,
    F: for<'x> Filter<'x>,

fn clone(&self) -> Query<Q, F>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Q, F> Debug for Query<Q, F>where
    Q: for<'x> Fetch<'x>,
    F: for<'x> Filter<'x>,
    F: Debug,

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

Formats the value using the given formatter.

impl<Q, F> SystemAccess for Query<Q, F>where
    Q: for<'x> Fetch<'x>,
    F: for<'x> Filter<'x>,

fn access(&self, world: &World) -> Vec<Access>

Returns all the accesses for a system

impl<'a, Q, F> SystemData<'a> for Query<Q, F>where
    Q: for<'x> Fetch<'x> + 'static,
    F: for<'x> Filter<'x> + Debug + 'static,

type Value = QueryData<'a, Q, F>

The borrow from the system context

fn acquire(&'a mut self, ctx: &'a SystemContext<'_>) -> Result<Self::Value>

Get the data from the system context