Module query 

Queries provide efficient iteration and filtering of entity components in a world.

Queries are defined by two parts; “views” and “filters”. Views declare what data you want to access, and how you want to access it. Filters decide which entities are to be included in the results.

To construct a query, we declare our view, and then call ::query() to convert it into a query with an initial filter which selects entities with all of the component types requested by the view.

View types include Entity, Read, Write, TryRead and TryWrite.

// a view can be a single view type
let mut query = <&Position>::query();

// or a tuple of views
let mut query = <(&Position, &mut Orientation)>::query();

You can attach additional filters to a query to further refine which entities you want to access.

// filters can be combined with boolean operators
let mut query = <(&Position, &mut Orientation)>::query()
    .filter(!component::<Static>() | !component::<Model>());

Once you have a query, you can use it to pull data out of a world. At its core, a query allows you to iterate over chunks. Each chunk contains a set of entities which all have exactly the same component types attached, and the chunk provides access to slices of each component. A single index in each slice in a chunk contains the component for the same entity.

let mut query = <(&Position, &mut Orientation)>::query();
for mut chunk in query.iter_chunks_mut(&mut world) {
    // we can access information about the archetype (shape/component layout) of the entities
    println!(
        "the entities in the chunk have {:?} components",
        chunk.archetype().layout().component_types(),
    );

    // we can iterate through a tuple of component references
    for (position, orientation) in chunk {
        // position is a `&Position`
        // orientation is a `&mut Orientation`
        // they are both attached to the same entity
    }
}

There are convenience functions on query which will flatten this loop for us, giving direct access to the entities.

let mut query = <(&Position, &mut Orientation)>::query();
for (position, orientation) in query.iter_mut(&mut world) {
    // position is a `&Position`
    // orientation is a `&mut Orientation`
    // they are both attached to the same entity
}

Structs

And

A filter which requires all filters within T match.

Any

A filter which always matches true.

ChunkIter

An iterator which yields entity chunks from a query.

ChunkView

Provides access to slices of components for entities which have the same component layout.

ComponentChangedFilter

A filter which performs coarse-grained change detection.

ComponentFilter

A filter which matches true when the given component exists in the archetype.

Iter

An entity chunk iterator which internally locks its filter during iteration.

Not

A filter which negates F.

Or

A filter which requires any filter within T match.

ParChunkIter

A parallel entity chunk iterator.

Passthrough

A filter which always defers.

Query

Provides efficient means to iterate and filter entities in a world.

Read

Reads a single entity data component type from a chunk.

TryComponentFilter

A filter which matches true if the entity has the given component, else it will defer.

TryRead

Reads a single entity data component type from a chunk.

TryWrite

Writes a single entity data component type from a chunk.

Write

Writes a single mutable entity data component type from a chunk.

Enums

FilterResult

Indicates if an an archetype should be accepted or rejected.

Traits

DefaultFilter

Declares the default filter type used by a view when it is converted into a query.

DynamicFilter

A filter which selects based upon the data available in the archetype.

EntityFilter

A combination of a LayoutFilter and a DynamicFilter.

Fetch

A type which holds onto a slice of entity data retrieved from a single archetype.

GroupMatcher

Allows a filter to determine if component optimization groups can be used to accelerate queries that use this filter.

IntoQuery

A type (typically a view) which can construct a query.

LayoutFilter

A filter which selects based upon which component types are attached to an entity.

View

A type which can pull entity data out of a world.

Functions

any

Constructs a filter which passes all entities.

component

Constructs a filter which requires that the entities have the given component.

maybe_changed

Constructs a filter which requires that the component cannot be certain to have not changed.

passthrough

Constructs a filter which performs a no-op and defers to any filters it is combined with.