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 it, 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 extactly 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 course-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 all filters 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 entitiy 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 entitiy 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.