elevator_core/

lib.rs

//! # elevator-core
//!
//! Engine-agnostic, tick-based elevator simulation library for Rust.
//!
//! This crate provides the building blocks for modeling vertical transportation
//! systems — from a 3-story office building to an orbital space elevator.
//! Stops sit at arbitrary positions rather than uniform floors, and the
//! simulation is driven by a deterministic 8-phase tick loop.
//!
//! ## Key capabilities
//!
//! - **Pluggable dispatch** — five built-in algorithms ([`dispatch::scan::ScanDispatch`],
//!   [`dispatch::look::LookDispatch`], [`dispatch::nearest_car::NearestCarDispatch`],
//!   [`dispatch::etd::EtdDispatch`], [`dispatch::destination::DestinationDispatch`])
//!   plus the [`dispatch::DispatchStrategy`] trait for custom implementations.
//! - **Trapezoidal motion profiles** — realistic acceleration, cruise, and
//!   deceleration computed per-tick.
//! - **Extension components** — attach arbitrary `Serialize + DeserializeOwned`
//!   data to any entity via [`world::World::insert_ext`] without modifying the
//!   library.
//! - **Lifecycle hooks** — inject logic before or after any of the eight
//!   simulation phases. See [`hooks::Phase`].
//! - **Metrics and events** — query aggregate wait/ride times through
//!   [`metrics::Metrics`] and react to fine-grained tick events via
//!   [`events::Event`].
//! - **Snapshot save/load** — capture and restore full simulation state with
//!   [`snapshot::WorldSnapshot`].
//! - **Zero `unsafe` code** — enforced by `#![forbid(unsafe_code)]`.
//!
//! ## Quick start
//!
//! ```rust
//! use elevator_core::prelude::*;
//! use elevator_core::stop::StopConfig;
//!
//! let mut sim = SimulationBuilder::demo()
//!     .stops(vec![
//!         StopConfig { id: StopId(0), name: "Ground".into(), position: 0.0 },
//!         StopConfig { id: StopId(1), name: "Floor 2".into(), position: 4.0 },
//!         StopConfig { id: StopId(2), name: "Floor 3".into(), position: 8.0 },
//!     ])
//!     .build()
//!     .unwrap();
//!
//! sim.spawn_rider(StopId(0), StopId(2), 75.0).unwrap();
//!
//! for _ in 0..1000 {
//!     sim.step();
//! }
//!
//! assert!(sim.metrics().total_delivered() > 0);
//! ```
//!
//! ## Crate layout
//!
//! ## Stability
//!
//! Every module below is classified as **stable**, **experimental**, or
//! **internal**. Stable items break only in planned major versions
//! with a deprecation cycle; experimental items may change in any
//! minor version; internal items are not part of the supported surface.
//! See [`STABILITY.md`](https://github.com/andymai/elevator-core/blob/main/STABILITY.md)
//! for the full policy and cadence commitment.
//!
//! | Module | Purpose | Stability |
//! |--------|---------|-----------|
//! | [`builder`] | Fluent [`SimulationBuilder`](builder::SimulationBuilder) API | stable |
//! | [`sim`] | Top-level [`Simulation`](sim::Simulation) runner and tick loop | stable (selected methods — see [`STABILITY.md`](https://github.com/andymai/elevator-core/blob/main/STABILITY.md)) |
//! | [`dispatch`] | Dispatch strategies and the [`DispatchStrategy`](dispatch::DispatchStrategy) trait | stable |
//! | [`world`] | ECS-style [`World`](world::World) with typed component storage | experimental |
//! | [`components`] | Entity data types: [`Rider`](components::Rider), [`Elevator`](components::Elevator), [`Stop`](components::Stop), [`Line`](components::Line), [`Route`](components::Route), [`Patience`](components::Patience), [`Preferences`](components::Preferences), [`AccessControl`](components::AccessControl), [`DestinationQueue`](components::DestinationQueue), [`ServiceMode`](components::ServiceMode), [`Orientation`](components::Orientation), [`Position`](components::Position), [`Velocity`](components::Velocity), [`SpatialPosition`](components::SpatialPosition) | stable (units + core), experimental (rest) |
//! | [`config`] | RON-deserializable [`SimConfig`](config::SimConfig), [`GroupConfig`](config::GroupConfig), [`LineConfig`](config::LineConfig) | experimental |
//! | [`events`] | [`Event`](events::Event) variants and the [`EventBus`](events::EventBus) | stable ([`Event`](events::Event)) |
//! | [`metrics`] | Aggregate [`Metrics`](metrics::Metrics) (wait time, throughput, etc.) | stable |
//! | [`hooks`] | Lifecycle hook registration by [`Phase`](hooks::Phase) | experimental |
//! | [`query`] | Entity query builder for filtering by component composition | experimental |
//! | [`systems`] | Per-phase tick logic (dispatch, movement, doors, loading, ...) | internal |
//! | [`snapshot`] | [`WorldSnapshot`](snapshot::WorldSnapshot) save/restore with custom-strategy factory | stable |
//! | [`scenario`] | Deterministic scenario replay from recorded event streams | experimental |
//! | [`topology`] | Lazy-rebuilt connectivity graph for cross-line routing | experimental |
//! | [`traffic`] | [`TrafficSource`](traffic::TrafficSource) trait + `PoissonSource` (feature-gated) | experimental |
//! | [`tagged_metrics`] | Per-tag metric accumulators for zone/line/priority breakdowns | experimental |
//! | [`movement`] | Trapezoidal velocity-profile primitives ([`braking_distance`](movement::braking_distance), [`tick_movement`](movement::tick_movement)) | experimental |
//! | [`door`] | Door finite-state machine ([`DoorState`](door::DoorState)) | internal |
//! | [`eta`] | Per-stop arrival-time estimation used by dispatch | internal |
//! | [`time`] | Tick-to-wall-clock conversion ([`TimeAdapter`](time::TimeAdapter)) | experimental |
//! | `energy` | Simplified per-elevator energy modeling (gated behind the `energy` feature) | experimental |
//! | [`stop`] | [`StopId`](stop::StopId) and [`StopConfig`](stop::StopConfig) | stable |
//! | [`entity`] | Opaque [`EntityId`](entity::EntityId) runtime identity | stable |
//! | [`ids`] | Config-level typed identifiers ([`GroupId`](ids::GroupId), etc.) | experimental |
//! | [`error`] | [`SimError`](error::SimError), [`RejectionReason`](error::RejectionReason), [`RejectionContext`](error::RejectionContext) | stable ([`SimError`](error::SimError)) |
//!
//! ## Architecture overview
//!
//! ### 8-phase tick loop
//!
//! Each call to [`Simulation::step()`](sim::Simulation::step) runs these
//! phases in order:
//!
//! 1. **`AdvanceTransient`** — transitions `Boarding→Riding`, `Exiting→Arrived`,
//!    teleports walkers.
//! 2. **Dispatch** — builds a [`DispatchManifest`](dispatch::DispatchManifest)
//!    and calls each group's [`DispatchStrategy`](dispatch::DispatchStrategy).
//! 3. **Reposition** — optional phase; moves idle elevators via
//!    [`RepositionStrategy`](dispatch::RepositionStrategy) for better coverage.
//! 4. **`AdvanceQueue`** — reconciles each elevator's phase/target with the
//!    front of its [`DestinationQueue`](components::DestinationQueue), so
//!    imperative pushes from game code take effect before movement.
//! 5. **Movement** — applies trapezoidal velocity profiles, detects stop arrivals
//!    and emits [`PassingFloor`](events::Event::PassingFloor) events.
//! 6. **Doors** — ticks the [`DoorState`](door::DoorState) FSM per elevator.
//! 7. **Loading** — boards/exits riders with capacity and preference checks.
//! 8. **Metrics** — aggregates wait/ride times into [`Metrics`](metrics::Metrics)
//!    and per-tag accumulators.
//!
//! For full per-phase semantics (events emitted, edge cases, design rationale),
//! see the [guide](https://andymai.github.io/elevator-core/simulation-loop.html).
//!
//! ### Component relationships
//!
//! ```text
//! Group ──contains──▶ Line ──has──▶ Elevator ──carries──▶ Rider
//!   │                  │              │                      │
//!   └── DispatchStrategy              └── Position           └── Route (optional)
//!        RepositionStrategy               Velocity               Patience
//!                      │                  DoorState               Preferences
//!                      └── Stop (served stops along the shaft)
//! ```
//!
//! ### Rider lifecycle
//!
//! Riders progress through phases managed by the simulation:
//!
//! ```text
//! Waiting → Boarding → Riding → Exiting → Arrived
//!    ↑         (1 tick)           (1 tick)     │
//!    │                                         ├── settle_rider() → Resident
//!    │                                         │                       │
//!    │                                         └── despawn_rider()     │
//!    │                                                                 │
//!    └──────── reroute_rider() ────────────────────────────────────────┘
//!
//! Waiting ──(patience exceeded)──→ Abandoned ──→ settle/despawn
//! ```
//!
//! - **`Arrived`** / **`Abandoned`**: terminal states; consumer must explicitly
//!   settle or despawn the rider.
//! - **`Resident`**: parked at a stop, invisible to dispatch and loading.
//!   Query with [`Simulation::residents_at()`](sim::Simulation::residents_at).
//! - **Population queries**: O(1) via maintained reverse index —
//!   [`residents_at`](sim::Simulation::residents_at),
//!   [`waiting_at`](sim::Simulation::waiting_at),
//!   [`abandoned_at`](sim::Simulation::abandoned_at).
//!
//! ### Extension storage
//!
//! Games attach custom data to any entity without modifying the library:
//!
//! ```rust,no_run
//! # use elevator_core::prelude::*;
//! # use elevator_core::query::Ext;
//! # use serde::{Serialize, Deserialize};
//! # #[derive(Debug, Clone, Serialize, Deserialize)]
//! # struct VipTag { priority: u32 }
//! # fn run(world: &mut World, rider_id: EntityId) {
//! // Attach a VIP flag to a rider.
//! world.insert_ext(rider_id, VipTag { priority: 1 }, ExtKey::from_type_name());
//!
//! // Query it alongside built-in components.
//! for (id, rider, vip) in world.query::<(EntityId, &Rider, &Ext<VipTag>)>().iter() {
//!     // ...
//! }
//! # }
//! ```
//!
//! Extensions participate in snapshots via `serialize_extensions()` /
//! `register_ext::<T>(key)` + `load_extensions()`.
//!
//! ### Snapshot lifecycle
//!
//! 1. Capture: `sim.snapshot()` → [`WorldSnapshot`](snapshot::WorldSnapshot)
//! 2. Serialize: serde (RON, JSON, bincode, etc.)
//! 3. Deserialize + restore: `snapshot.restore(factory)` → new `Simulation`
//! 4. Re-register extensions: `world.register_ext::<T>(key)` per type
//! 5. Load extension data: `sim.load_extensions()`
//!
//! For the common case (save-to-disk, load-from-disk), skip the format choice
//! and use [`Simulation::snapshot_bytes`](sim::Simulation::snapshot_bytes) /
//! [`Simulation::restore_bytes`](sim::Simulation::restore_bytes). The byte
//! blob is postcard-encoded and carries a magic prefix plus the crate version:
//! restoring bytes from a different `elevator-core` version returns
//! [`SimError::SnapshotVersion`](error::SimError::SnapshotVersion) instead of
//! silently producing a garbled sim. Determinism is bit-exact across builds
//! of the same crate version, which makes snapshots viable as rollback-netcode
//! checkpoints or deterministic replay fixtures.
//!
//! ### Performance
//!
//! | Operation | Complexity |
//! |-----------|-----------|
//! | Entity iteration | O(n) via `SlotMap` secondary maps |
//! | Stop-passing detection | O(log n) via `SortedStops` binary search |
//! | Dispatch manifest build | O(riders) per group |
//! | Population queries | O(1) via `RiderIndex` reverse index |
//! | Topology graph queries | O(V+E) BFS, lazy rebuild |
//!
//! ## Runtime upgrades
//!
//! Elevator kinematic and door-timing parameters can be mutated at runtime
//! via the `Simulation::set_*` setters — handy for RPG-style upgrade systems
//! or scripted events that boost speed, capacity, or door behavior mid-game.
//!
//! Each setter validates its input, mutates the underlying component, and
//! emits an [`Event::ElevatorUpgraded`](events::Event::ElevatorUpgraded) so
//! game code can react (score popups, SFX, UI). Velocity is preserved when
//! kinematic parameters change — the integrator picks up the new values on
//! the next tick without jerk. Door-timing changes apply to the next door
//! cycle and never retroactively retime an in-progress transition.
//!
//! See [`examples/runtime_upgrades.rs`][rte] for an end-to-end demonstration
//! that doubles a car's `max_speed` mid-run and prints the throughput delta.
//!
//! [rte]: https://github.com/andymai/elevator-core/blob/main/crates/elevator-core/examples/runtime_upgrades.rs
//!
//! ## Door control
//!
//! Games that want to drive elevator doors directly — e.g. the player
//! pressing "open" or "close" on a cab panel in a first-person game, or an
//! RPG where the player *is* the elevator — use the manual door-control
//! API on [`Simulation`](sim::Simulation):
//!
//! - [`open_door`](sim::Simulation::open_door)
//! - [`close_door`](sim::Simulation::close_door)
//! - [`hold_door`](sim::Simulation::hold_door) (cumulative)
//! - [`cancel_door_hold`](sim::Simulation::cancel_door_hold)
//!
//! Each call is either applied immediately (if the car is in a matching
//! door-FSM state) or queued on the elevator's
//! [`door_command_queue`](components::Elevator::door_command_queue) and
//! re-tried every tick until it can be applied. The only hard errors are
//! [`NotAnElevator`](error::SimError::NotAnElevator) / [`ElevatorDisabled`](error::SimError::ElevatorDisabled) and (for `hold_door`) a
//! zero-tick argument — the rest return `Ok(())` and let the engine pick
//! the right moment. A [`DoorCommand`](door::DoorCommand) can be:
//!
//! - `Open` — reverses a closing door; no-op if already open or opening;
//!   queues while the car is moving.
//! - `Close` — forces an early close from `Loading`. Waits one tick if a
//!   rider is mid-boarding/exiting (safe-close).
//! - `HoldOpen { ticks }` — adds to the remaining open dwell; two calls
//!   of 30 ticks stack to 60. Queues if doors aren't open yet.
//! - `CancelHold` — clamps any accumulated hold back to the base dwell.
//!
//! Every command emits
//! [`Event::DoorCommandQueued`](events::Event::DoorCommandQueued) when
//! submitted and
//! [`Event::DoorCommandApplied`](events::Event::DoorCommandApplied) when
//! it actually takes effect — useful for driving UI feedback (button
//! flashes, SFX) without polling the elevator every tick.
//!
//! See [`examples/door_commands.rs`][dex] for a runnable demo.
//!
//! [dex]: https://github.com/andymai/elevator-core/blob/main/crates/elevator-core/examples/door_commands.rs
//!
//! ## Sub-tick position interpolation
//!
//! Games that render at a higher framerate than the simulation ticks (e.g.
//! a 60 Hz sim driving a 144 Hz camera, or a first-person game where the
//! player is parented to an elevator car) need a smooth position between
//! ticks. [`Simulation::position_at`](sim::Simulation::position_at) lerps
//! between the snapshot taken at the start of the current tick and the
//! post-tick position, using an `alpha` accumulator clamped to `[0.0, 1.0]`:
//!
//! ```text
//! // typical fixed-timestep render loop
//! accumulator += frame_dt;
//! while accumulator >= sim.dt() {
//!     sim.step();
//!     accumulator -= sim.dt();
//! }
//! let alpha = accumulator / sim.dt();
//! let y = sim.position_at(car, alpha).unwrap();
//! ```
//!
//! The previous-position snapshot is refreshed automatically at the start
//! of every [`step`](sim::Simulation::step). [`Simulation::velocity`](sim::Simulation::velocity) is
//! a convenience that returns the raw `f64` along the shaft axis (signed:
//! +up, -down) for camera tilt, motion blur, or cabin-sway effects.
//!
//! See [`examples/fp_player_rider.rs`][fpe] for a runnable demo.
//!
//! [fpe]: https://github.com/andymai/elevator-core/blob/main/crates/elevator-core/examples/fp_player_rider.rs
//!
//! ## Manual-drive mode
//!
//! Games where the player *is* the elevator — driving the car with a
//! velocity stick, slamming an emergency brake, stopping between floors
//! — use [`ServiceMode::Manual`](components::ServiceMode::Manual). Manual
//! elevators are skipped by the automatic dispatch and repositioning
//! phases; the consumer drives movement via:
//!
//! - [`Simulation::set_target_velocity`](sim::Simulation::set_target_velocity) — signed target speed (+up, -down), clamped to the car's `max_speed`.
//! - [`Simulation::emergency_stop`](sim::Simulation::emergency_stop) — commands an immediate deceleration to zero.
//!
//! Physics still apply: velocity ramps toward the target using the car's
//! `acceleration` / `deceleration` caps, and positions update at the same
//! rate as normal elevators. Manual elevators can come to rest at any
//! position — they are not required to align with a configured stop.
//! Door behaviour is governed by the [manual door-control API](#door-control);
//! nothing opens or closes automatically. Leaving `Manual` clears any
//! pending velocity command.
//!
//! Each command emits
//! [`Event::ManualVelocityCommanded`](events::Event::ManualVelocityCommanded)
//! with the clamped target, or `None` for an emergency stop.
//!
//! See [`examples/manual_driver.rs`][mde] for a runnable demo.
//!
//! [mde]: https://github.com/andymai/elevator-core/blob/main/crates/elevator-core/examples/manual_driver.rs
//!
//! ## ETA queries
//!
//! Hall-call dispatch UIs, scheduling overlays, and "press to call" panels
//! all need the same answer: *how long until this car shows up?* Two methods
//! on [`Simulation`](sim::Simulation) compute it from the elevator's queued
//! destinations, current kinematic state, and configured door dwell:
//!
//! - [`Simulation::eta`](sim::Simulation::eta) — seconds until a specific
//!   elevator reaches a specific stop, or an [`EtaError`](error::EtaError) if the
//!   stop isn't queued, the car is disabled, or the service mode excludes it.
//! - [`Simulation::best_eta`](sim::Simulation::best_eta) — winner across all
//!   eligible elevators, optionally filtered by indicator-lamp direction
//!   ("which up-going car arrives first?").
//!
//! Both walk the queue in service order, summing closed-form trapezoidal
//! travel time per leg plus the configured door cycle at every intermediate
//! stop. The closed-form solver lives in [`eta::travel_time`] and tracks the
//! per-tick integrator in [`movement::tick_movement`] to within a tick or
//! two — close enough for UI countdowns; not a substitute for actually
//! simulating to compare two dispatch policies.
//!
//! For narrative guides, tutorials, and architecture walkthroughs, see the
//! [mdBook documentation](https://andymai.github.io/elevator-core/).

#![forbid(unsafe_code)]
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]

#[cfg(doctest)]
mod doctests;

/// Entity-component data types for the simulation.
pub mod components;
/// Entity identity and allocation.
pub mod entity;
/// Simulation error types.
pub mod error;
/// Typed identifiers for groups and other sim concepts.
pub mod ids;
/// ECS-style query builder for iterating entities by component composition.
pub mod query;
/// Tick-loop system phases (dispatch, reposition, movement, doors, loading, metrics).
pub mod systems;
/// Central entity/component storage.
pub mod world;

/// Rolling per-stop arrival log, the signal source for rate-driven
/// dispatch and repositioning.
pub mod arrival_log;
/// Fluent builder for constructing a Simulation programmatically.
pub mod builder;
/// Building and elevator configuration (RON deserialization).
pub mod config;
/// Pluggable dispatch strategies (SCAN, LOOK, nearest-car, ETD).
pub mod dispatch;
/// Door finite-state machine.
pub mod door;
/// Simplified energy modeling for elevators.
#[cfg(feature = "energy")]
pub mod energy;
/// ETA estimation for queued elevators (closed-form trapezoidal travel time).
pub mod eta;
/// Simulation event bus and event types.
pub mod events;
/// Lifecycle hooks for injecting logic before/after simulation phases.
pub mod hooks;
/// Aggregate simulation metrics.
pub mod metrics;
/// Trapezoidal velocity-profile movement math.
///
/// Exposes [`braking_distance`](movement::braking_distance) for consumers
/// writing opportunistic dispatch strategies that need the kinematic answer
/// without constructing a `Simulation`.
pub mod movement;
/// Phase-partitioned reverse index for rider population queries.
mod rider_index;
/// Scenario replay from recorded event streams.
pub mod scenario;
/// Top-level simulation runner.
pub mod sim;
/// World snapshot for save/load.
pub mod snapshot;
/// Stop configuration helpers.
pub mod stop;
/// Tag-based per-entity metrics.
pub mod tagged_metrics;
/// Tick-to-wall-clock time conversion.
pub mod time;
/// Topology graph for cross-line connectivity queries.
pub mod topology;
/// Traffic generation (arrival patterns).
#[cfg(feature = "traffic")]
pub mod traffic;
/// Traffic-mode detector (up-peak / idle / inter-floor).
pub mod traffic_detector;

/// Register multiple extension types for snapshot deserialization in one call.
///
/// Eliminates the manual `register_ext` ceremony after snapshot restore.
///
/// # Examples
///
/// Name-less form (uses `type_name` automatically):
///
/// ```
/// use elevator_core::prelude::*;
/// use elevator_core::register_extensions;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(Clone, Debug, Serialize, Deserialize)]
/// struct VipTag { level: u32 }
///
/// #[derive(Clone, Debug, Serialize, Deserialize)]
/// struct Priority { rank: u8 }
///
/// let mut sim = SimulationBuilder::demo().build().unwrap();
/// register_extensions!(sim.world_mut(), VipTag, Priority);
/// ```
///
/// Named form (explicit storage name per type):
///
/// ```
/// use elevator_core::prelude::*;
/// use elevator_core::register_extensions;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(Clone, Debug, Serialize, Deserialize)]
/// struct VipTag { level: u32 }
///
/// let mut sim = SimulationBuilder::demo().build().unwrap();
/// register_extensions!(sim.world_mut(), VipTag => "vip_tag");
/// ```
#[macro_export]
macro_rules! register_extensions {
    ($world:expr, $($ty:ty),+ $(,)?) => {
        $( $world.register_ext::<$ty>($crate::world::ExtKey::<$ty>::from_type_name()); )+
    };
    ($world:expr, $($ty:ty => $name:expr),+ $(,)?) => {
        $( $world.register_ext::<$ty>($crate::world::ExtKey::<$ty>::new($name)); )+
    };
}

/// Common imports for consumers of this library.
///
/// `use elevator_core::prelude::*;` pulls in the types you need for the vast
/// majority of simulations — building a sim, stepping it, spawning riders,
/// reading events and metrics, and writing custom dispatch strategies.
///
/// # Contents
///
/// - **Builder & simulation:** [`SimulationBuilder`](crate::builder::SimulationBuilder),
///   [`Simulation`](crate::sim::Simulation),
///   [`RiderBuilder`](crate::sim::RiderBuilder)
/// - **Components:** [`Rider`](crate::components::Rider),
///   [`RiderPhase`](crate::components::RiderPhase),
///   [`RiderPhaseKind`](crate::components::RiderPhaseKind),
///   [`Elevator`](crate::components::Elevator),
///   [`ElevatorPhase`](crate::components::ElevatorPhase),
///   [`Stop`](crate::components::Stop), [`Line`](crate::components::Line),
///   [`Position`](crate::components::Position),
///   [`Velocity`](crate::components::Velocity),
///   [`SpatialPosition`](crate::components::SpatialPosition),
///   [`Route`](crate::components::Route),
///   [`Patience`](crate::components::Patience),
///   [`Preferences`](crate::components::Preferences),
///   [`AccessControl`](crate::components::AccessControl),
///   [`DestinationQueue`](crate::components::DestinationQueue),
///   [`Direction`](crate::components::Direction),
///   [`Orientation`](crate::components::Orientation),
///   [`ServiceMode`](crate::components::ServiceMode)
/// - **Config:** [`SimConfig`](crate::config::SimConfig),
///   [`ElevatorConfig`](crate::config::ElevatorConfig),
///   [`GroupConfig`](crate::config::GroupConfig),
///   [`LineConfig`](crate::config::LineConfig),
///   [`StopConfig`](crate::stop::StopConfig)
/// - **Dispatch:** [`DispatchStrategy`](crate::dispatch::DispatchStrategy),
///   [`RepositionStrategy`](crate::dispatch::RepositionStrategy),
///   [`DispatchDecision`](crate::dispatch::DispatchDecision),
///   [`DispatchManifest`](crate::dispatch::DispatchManifest),
///   [`ElevatorGroup`](crate::dispatch::ElevatorGroup),
///   [`AssignedCar`](crate::dispatch::AssignedCar),
///   [`RankContext`](crate::dispatch::RankContext),
///   [`DestinationDispatch`](crate::dispatch::DestinationDispatch),
///   [`ScanDispatch`](crate::dispatch::ScanDispatch),
///   [`LookDispatch`](crate::dispatch::LookDispatch),
///   [`NearestCarDispatch`](crate::dispatch::NearestCarDispatch),
///   [`EtdDispatch`](crate::dispatch::EtdDispatch),
///   plus the built-in reposition strategies
///   [`NearestIdle`](crate::dispatch::reposition::NearestIdle),
///   [`ReturnToLobby`](crate::dispatch::reposition::ReturnToLobby),
///   [`SpreadEvenly`](crate::dispatch::reposition::SpreadEvenly),
///   [`DemandWeighted`](crate::dispatch::reposition::DemandWeighted),
///   [`PredictiveParking`](crate::dispatch::reposition::PredictiveParking)
/// - **Identity:** [`EntityId`](crate::entity::EntityId),
///   [`StopId`](crate::stop::StopId), [`StopRef`](crate::stop::StopRef),
///   [`GroupId`](crate::ids::GroupId)
/// - **Errors & events:** [`SimError`](crate::error::SimError),
///   [`EtaError`](crate::error::EtaError),
///   [`RejectionReason`](crate::error::RejectionReason),
///   [`RejectionContext`](crate::error::RejectionContext),
///   [`Event`](crate::events::Event),
///   [`EventBus`](crate::events::EventBus),
///   [`EventCategory`](crate::events::EventCategory)
/// - **World & misc:** [`World`](crate::world::World),
///   [`Metrics`](crate::metrics::Metrics),
///   [`TimeAdapter`](crate::time::TimeAdapter),
///   [`ExtKey`](crate::world::ExtKey)
///
/// # Not included (import explicitly)
///
/// - Traffic generation types from [`crate::traffic`] (feature-gated)
/// - Snapshot types from [`crate::snapshot`]
pub mod prelude {
    pub use crate::builder::SimulationBuilder;
    pub use crate::components::{
        Accel, AccessControl, DestinationQueue, Direction, Elevator, ElevatorPhase, Line,
        Orientation, Patience, Position, Preferences, Rider, RiderPhase, RiderPhaseKind, Route,
        ServiceMode, SpatialPosition, Speed, Stop, UnitError, Velocity, Weight,
    };
    pub use crate::config::{ElevatorConfig, GroupConfig, LineConfig, SimConfig};
    pub use crate::dispatch::reposition::{
        DemandWeighted, NearestIdle, PredictiveParking, ReturnToLobby, SpreadEvenly,
    };
    pub use crate::dispatch::{
        AssignedCar, DestinationDispatch, DispatchDecision, DispatchManifest, DispatchStrategy,
        ElevatorGroup, EtdDispatch, LookDispatch, NearestCarDispatch, RankContext,
        RepositionStrategy, ScanDispatch,
    };
    pub use crate::entity::{ElevatorId, EntityId, RiderId};
    pub use crate::error::{EtaError, RejectionContext, RejectionReason, SimError};
    pub use crate::events::{Event, EventBus, EventCategory};
    pub use crate::ids::GroupId;
    pub use crate::metrics::Metrics;
    pub use crate::sim::{RiderBuilder, Simulation};
    pub use crate::stop::{StopConfig, StopId, StopRef};
    pub use crate::time::TimeAdapter;
    pub use crate::world::{ExtKey, World};
}

#[cfg(test)]
mod tests;