elevator_core/query/
mod.rs

1//! ECS-style query builder for iterating entities by component composition.
2//!
3//! # Audience
4//!
5//! This module is the **extension-author surface**: the generic
6//! builder for iterating over arbitrary component combinations,
7//! including [`Ext<T>`](crate::query::Ext) game-defined components.
8//! Use it when:
9//!
10//! - You're filtering on a combination of components
11//!   ([`With`](crate::query::With) / [`Without`](crate::query::Without)
12//!   / multiple `&T` slots) — e.g. "all riders with a `VipTag`
13//!   extension and a position".
14//! - You're operating on game-defined [`Ext<T>`](crate::query::Ext)
15//!   components that don't have hand-written iterators on
16//!   [`World`](crate::world::World).
17//!
18//! Core's per-tick hot paths intentionally use the typed
19//! [`World::iter_riders`](crate::world::World::iter_riders),
20//! [`World::iter_elevators`](crate::world::World::iter_elevators),
21//! [`World::iter_stops`](crate::world::World::iter_stops), etc. —
22//! direct accessors over the `SoA` storage that skip the generic
23//! dispatch layer. The builder is for the cases those don't cover.
24//! `query_bench` shows the builder is fast (linear in entity count
25//! with a small constant), but for known component types the typed
26//! accessor is still preferred.
27//!
28//! # Examples
29//!
30//! ```
31//! use elevator_core::components::{Position, Rider, Route};
32//! use elevator_core::prelude::*;
33//! use elevator_core::query::{Ext, With, Without};
34//! use elevator_core::world::ExtKey;
35//!
36//! use serde::{Serialize, Deserialize};
37//!
38//! #[derive(Debug, Clone, Serialize, Deserialize)]
39//! struct VipTag { level: u32 }
40//!
41//! let mut sim = SimulationBuilder::demo().build().unwrap();
42//! let rider_eid = sim.spawn_rider(StopId(0), StopId(1), 75.0).unwrap();
43//!
44//! // Attach an extension component.
45//! sim.world_mut().insert_ext(rider_eid.entity(), VipTag { level: 5 }, ExtKey::from_type_name());
46//!
47//! let world = sim.world();
48//!
49//! // All riders with a position
50//! for (id, rider, pos) in world.query::<(EntityId, &Rider, &Position)>().iter() {
51//!     println!("{id:?}: phase={:?} at {}", rider.phase(), pos.value());
52//! }
53//!
54//! // Entities with Position but without Route
55//! for (id, pos) in world.query::<(EntityId, &Position)>()
56//!     .without::<Route>()
57//!     .iter()
58//! {
59//!     println!("{id:?} at {}", pos.value());
60//! }
61//!
62//! // Extension components (cloned)
63//! for (id, vip) in world.query::<(EntityId, &Ext<VipTag>)>().iter() {
64//!     println!("VIP rider {id:?}: level {}", vip.level);
65//! }
66//! ```
67
68pub(crate) mod storage;
69
70mod fetch;
71mod filter;
72mod iter;
73
74pub use fetch::{Ext, ExtMut, WorldQuery};
75pub use filter::{ExtWith, ExtWithout, QueryFilter, With, Without};
76pub use iter::{ExtQueryMut, QueryBuilder, QueryIter};
elevator_core/query/mod.rs

elevator_core/query/
mod.rs
