Module legion::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.