elevator_core/sim/
accessors.rs

1//! Core accessors: world, tick, metrics, groups, stop lookup.
2//!
3//! Part of the [`super::Simulation`] API surface; extracted from the
4//! monolithic `sim.rs` for readability. See the parent module for the
5//! overarching essential-API summary.
6
7use crate::components::Velocity;
8use crate::dispatch::ElevatorGroup;
9use crate::entity::EntityId;
10use crate::error::SimError;
11use crate::events::Event;
12use crate::ids::GroupId;
13use crate::metrics::Metrics;
14use crate::stop::{StopId, StopRef};
15use crate::time::TimeAdapter;
16use crate::world::World;
17
18impl super::Simulation {
19    // ── Accessors ────────────────────────────────────────────────────
20
21    /// Get a shared reference to the world.
22    //
23    // Intentionally non-`const`: a `const` qualifier on a runtime accessor
24    // signals "usable in const context", which these methods are not in
25    // practice (the `World` is heap-allocated and mutated). Marking them
26    // `const` misleads readers without unlocking any call sites.
27    #[must_use]
28    #[allow(clippy::missing_const_for_fn)]
29    pub fn world(&self) -> &World {
30        &self.world
31    }
32
33    /// Get a mutable reference to the world.
34    ///
35    /// Exposed for advanced use cases (manual rider management, custom
36    /// component attachment). Prefer `spawn_rider` / `build_rider`
37    /// for standard operations.
38    #[allow(clippy::missing_const_for_fn)]
39    pub fn world_mut(&mut self) -> &mut World {
40        &mut self.world
41    }
42
43    /// Current simulation tick.
44    #[must_use]
45    pub const fn current_tick(&self) -> u64 {
46        self.tick
47    }
48
49    /// Time delta per tick (seconds).
50    #[must_use]
51    pub const fn dt(&self) -> f64 {
52        self.dt
53    }
54
55    /// Interpolated position between the previous and current tick.
56    ///
57    /// `alpha` is clamped to `[0.0, 1.0]`, where `0.0` returns the entity's
58    /// position at the start of the last completed tick and `1.0` returns
59    /// the current position. Intended for smooth rendering when a render
60    /// frame falls between simulation ticks.
61    ///
62    /// Returns `None` if the entity has no position component. Returns the
63    /// current position unchanged if no previous snapshot exists (i.e. before
64    /// the first [`step`](Self::step)).
65    ///
66    /// [`step`]: Self::step
67    #[must_use]
68    pub fn position_at(&self, id: EntityId, alpha: f64) -> Option<f64> {
69        let current = self.world.position(id)?.value;
70        let alpha = if alpha.is_nan() {
71            0.0
72        } else {
73            alpha.clamp(0.0, 1.0)
74        };
75        let prev = self.world.prev_position(id).map_or(current, |p| p.value);
76        Some((current - prev).mul_add(alpha, prev))
77    }
78
79    /// Current velocity of an entity along the shaft axis (signed: +up, -down).
80    ///
81    /// Convenience wrapper over [`World::velocity`] that returns the raw
82    /// `f64` value. Returns `None` if the entity has no velocity component.
83    #[must_use]
84    pub fn velocity(&self, id: EntityId) -> Option<f64> {
85        self.world.velocity(id).map(Velocity::value)
86    }
87
88    /// Get current simulation metrics.
89    #[must_use]
90    pub const fn metrics(&self) -> &Metrics {
91        &self.metrics
92    }
93
94    /// The time adapter for tick↔wall-clock conversion.
95    #[must_use]
96    pub const fn time(&self) -> &TimeAdapter {
97        &self.time
98    }
99
100    /// Get the elevator groups.
101    #[must_use]
102    pub fn groups(&self) -> &[ElevatorGroup] {
103        &self.groups
104    }
105
106    /// Mutable access to the group collection. Use this to flip a group
107    /// into [`HallCallMode::Destination`](crate::dispatch::HallCallMode)
108    /// or tune its `ack_latency_ticks` after construction. Changing the
109    /// line/elevator structure here is not supported — use the dedicated
110    /// topology mutators for that.
111    pub fn groups_mut(&mut self) -> &mut [ElevatorGroup] {
112        &mut self.groups
113    }
114
115    /// Resolve a config `StopId` to its runtime `EntityId`.
116    #[must_use]
117    pub fn stop_entity(&self, id: StopId) -> Option<EntityId> {
118        self.stop_lookup.get(&id).copied()
119    }
120
121    /// Resolve a [`StopRef`] to its runtime [`EntityId`].
122    pub(super) fn resolve_stop(&self, stop: StopRef) -> Result<EntityId, SimError> {
123        match stop {
124            StopRef::ByEntity(id) => Ok(id),
125            StopRef::ById(sid) => self.stop_entity(sid).ok_or(SimError::StopNotFound(sid)),
126        }
127    }
128
129    /// Get the strategy identifier for a group.
130    #[must_use]
131    pub fn strategy_id(&self, group: GroupId) -> Option<&crate::dispatch::BuiltinStrategy> {
132        self.strategy_ids.get(&group)
133    }
134
135    /// Iterate over the stop ID → entity ID mapping.
136    pub fn stop_lookup_iter(&self) -> impl Iterator<Item = (&StopId, &EntityId)> {
137        self.stop_lookup.iter()
138    }
139
140    /// Peek at events pending for consumer retrieval.
141    #[must_use]
142    pub fn pending_events(&self) -> &[Event] {
143        &self.pending_output
144    }
145}
elevator_core/sim/accessors.rs

elevator_core/sim/
accessors.rs
