1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
//! 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`](super::world::Entity), [`Read`], [`Write`], [`TryRead`]
//! and [`TryWrite`].
//!
//! ```
//! # use legion::*;
//! # struct Position;
//! # struct Orientation;
//! // 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.
//!
//! ```
//! # use legion::*;
//! # struct Position;
//! # struct Orientation;
//! # struct Model;
//! # struct Static;
//!
//! // 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](ChunkView). 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.
//!
//! ```
//! # use legion::*;
//! # struct Position;
//! # struct Orientation;
//! # let mut world = World::default();
//! 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.
//!
//! ```
//! # use legion::*;
//! # struct Position;
//! # struct Orientation;
//! # let mut world = World::default();
//! 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
//! }
//! ```
#[cfg(feature = "parallel")]
pub use crate::internals::query::par_iter::{Iter, ParChunkIter};
pub use crate::internals::query::{
filter::{
and::And,
any::Any,
component::ComponentFilter,
filter_fns::{any, component, maybe_changed, passthrough},
maybe_changed::ComponentChangedFilter,
not::Not,
or::Or,
passthrough::Passthrough,
try_component::TryComponentFilter,
DynamicFilter, EntityFilter, EntityFilterTuple, FilterResult, GroupMatcher, LayoutFilter,
},
view::{
read::Read, try_read::TryRead, try_write::TryWrite, write::Write, DefaultFilter, Fetch,
IntoIndexableIter, ReadOnly, View,
},
ChunkIter, ChunkView, IntoQuery, Query,
};