Module legion::query [−][src]
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 |
Any | A filter which always matches |
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 |
Iter | An entity chunk iterator which internally locks its filter during iteration. |
Not | A filter which negates |
Or | A filter which requires any filter within |
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 |
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 |
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. |