elevator_core/config.rs
1//! Building and elevator configuration (RON-deserializable).
2
3use crate::components::{FloorPosition, Orientation};
4use crate::dispatch::{BuiltinReposition, BuiltinStrategy};
5use crate::stop::{StopConfig, StopId};
6use serde::{Deserialize, Serialize};
7
8/// Top-level simulation configuration, loadable from RON.
9///
10/// Validated at construction time by [`Simulation::new()`](crate::sim::Simulation::new)
11/// or [`SimulationBuilder::build()`](crate::builder::SimulationBuilder::build).
12#[derive(Debug, Clone, Serialize, Deserialize)]
13pub struct SimConfig {
14 /// Building layout describing the stops (floors/stations) along the shaft.
15 pub building: BuildingConfig,
16 /// Elevator cars to install in the building.
17 ///
18 /// Legacy flat list — used when `building.lines` is `None`.
19 /// When explicit lines are provided, elevators live inside each
20 /// [`LineConfig`] instead.
21 #[serde(default)]
22 pub elevators: Vec<ElevatorConfig>,
23 /// Global simulation timing parameters.
24 pub simulation: SimulationParams,
25 /// Passenger spawning parameters used by the game layer.
26 ///
27 /// The core library does not consume these directly; they are stored here
28 /// for games and traffic generators that read the config.
29 pub passenger_spawning: PassengerSpawnConfig,
30}
31
32/// Building layout.
33#[derive(Debug, Clone, Serialize, Deserialize)]
34pub struct BuildingConfig {
35 /// Human-readable building name, displayed in UIs and logs.
36 pub name: String,
37 /// Ordered list of stops in the building.
38 ///
39 /// Must contain at least one stop. Each stop has a unique [`StopId`] and
40 /// an arbitrary position along the shaft axis. Positions need not be
41 /// uniformly spaced — this enables buildings, skyscrapers, and space
42 /// elevators with varying inter-stop distances.
43 pub stops: Vec<StopConfig>,
44 /// Lines (physical paths). If `None`, auto-inferred from the flat
45 /// elevator list on [`SimConfig`].
46 #[serde(default)]
47 pub lines: Option<Vec<LineConfig>>,
48 /// Dispatch groups. If `None`, auto-inferred (single group with all lines).
49 #[serde(default)]
50 pub groups: Option<Vec<GroupConfig>>,
51}
52
53/// Configuration for a single elevator car.
54#[derive(Debug, Clone, Serialize, Deserialize)]
55pub struct ElevatorConfig {
56 /// Numeric identifier for this elevator, unique within the config.
57 ///
58 /// Mapped to an [`EntityId`](crate::entity::EntityId) at construction
59 /// time; not used at runtime.
60 pub id: u32,
61 /// Human-readable elevator name, displayed in UIs and logs.
62 pub name: String,
63 /// Maximum travel speed in distance units per second.
64 ///
65 /// Must be positive. The trapezoidal velocity profile accelerates up to
66 /// this speed, cruises, then decelerates to stop at the target.
67 ///
68 /// Default (from `SimulationBuilder`): `2.0`.
69 pub max_speed: f64,
70 /// Acceleration rate in distance units per second squared.
71 ///
72 /// Must be positive. Controls how quickly the elevator reaches
73 /// `max_speed` from rest.
74 ///
75 /// Default (from `SimulationBuilder`): `1.5`.
76 pub acceleration: f64,
77 /// Deceleration rate in distance units per second squared.
78 ///
79 /// Must be positive. Controls how quickly the elevator slows to a stop
80 /// when approaching a target. May differ from `acceleration` for
81 /// asymmetric motion profiles.
82 ///
83 /// Default (from `SimulationBuilder`): `2.0`.
84 pub deceleration: f64,
85 /// Maximum total weight the elevator car can carry.
86 ///
87 /// Must be positive. Riders whose weight would exceed this limit are
88 /// rejected during the loading phase.
89 ///
90 /// Units: same as rider weight (typically kilograms).
91 /// Default (from `SimulationBuilder`): `800.0`.
92 pub weight_capacity: f64,
93 /// The [`StopId`] where this elevator starts at simulation init.
94 ///
95 /// Must reference an existing stop in the building config.
96 pub starting_stop: StopId,
97 /// How many ticks the doors remain fully open before closing.
98 ///
99 /// During this window, riders may board or exit. Longer values
100 /// increase loading opportunity but reduce throughput.
101 ///
102 /// Units: simulation ticks.
103 /// Default (from `SimulationBuilder`): `10`.
104 pub door_open_ticks: u32,
105 /// How many ticks a door open or close transition takes.
106 ///
107 /// Models the mechanical travel time of the door panels. No boarding
108 /// or exiting occurs during transitions.
109 ///
110 /// Units: simulation ticks.
111 /// Default (from `SimulationBuilder`): `5`.
112 pub door_transition_ticks: u32,
113 /// Stop IDs this elevator cannot serve (access restriction).
114 ///
115 /// Riders whose current destination is in this list are rejected
116 /// with [`RejectionReason::AccessDenied`](crate::error::RejectionReason::AccessDenied)
117 /// during the loading phase.
118 ///
119 /// Default: empty (no restrictions).
120 #[serde(default)]
121 pub restricted_stops: Vec<StopId>,
122 /// Energy profile for this elevator. If `None`, energy is not tracked.
123 ///
124 /// Requires the `energy` feature.
125 #[cfg(feature = "energy")]
126 #[serde(default)]
127 pub energy_profile: Option<crate::energy::EnergyProfile>,
128 /// Service mode at simulation start. Defaults to `Normal`.
129 #[serde(default)]
130 pub service_mode: Option<crate::components::ServiceMode>,
131 /// Speed multiplier for Inspection mode (0.0..1.0). Defaults to 0.25.
132 #[serde(default = "default_inspection_speed_factor")]
133 pub inspection_speed_factor: f64,
134}
135
136/// Default inspection speed factor (25% of normal speed).
137const fn default_inspection_speed_factor() -> f64 {
138 0.25
139}
140
141/// Global simulation timing parameters.
142#[derive(Debug, Clone, Serialize, Deserialize)]
143pub struct SimulationParams {
144 /// Number of simulation ticks per real-time second.
145 ///
146 /// Must be positive. Determines the time delta per tick (`dt = 1.0 / ticks_per_second`).
147 /// Higher values yield finer-grained simulation at the cost of more
148 /// computation per wall-clock second.
149 ///
150 /// Default (from `SimulationBuilder`): `60.0`.
151 pub ticks_per_second: f64,
152}
153
154/// Passenger spawning parameters (used by the game layer).
155///
156/// The core simulation does not spawn passengers automatically; these values
157/// are advisory and consumed by game code or traffic generators.
158///
159/// This struct is always available regardless of feature flags. The built-in
160/// traffic generation that consumes it requires the `traffic` feature.
161#[derive(Debug, Clone, Serialize, Deserialize)]
162pub struct PassengerSpawnConfig {
163 /// Mean interval in ticks between passenger spawns.
164 ///
165 /// Used by traffic generators for Poisson-distributed arrivals.
166 ///
167 /// Units: simulation ticks.
168 /// Default (from `SimulationBuilder`): `120`.
169 pub mean_interval_ticks: u32,
170 /// `(min, max)` weight range for randomly spawned passengers.
171 ///
172 /// Weights are drawn uniformly from this range by traffic generators.
173 ///
174 /// Units: same as elevator `weight_capacity` (typically kilograms).
175 /// Default (from `SimulationBuilder`): `(50.0, 100.0)`.
176 pub weight_range: (f64, f64),
177}
178
179/// Configuration for a single line (physical path).
180///
181/// A line represents a shaft, tether, track, or other physical pathway
182/// that one or more elevator cars travel along. Lines belong to a
183/// [`GroupConfig`] for dispatch purposes.
184#[derive(Debug, Clone, Default, Serialize, Deserialize)]
185pub struct LineConfig {
186 /// Unique line identifier (within the config).
187 pub id: u32,
188 /// Human-readable name.
189 pub name: String,
190 /// Stops served by this line (references [`StopConfig::id`]).
191 pub serves: Vec<StopId>,
192 /// Elevators on this line.
193 pub elevators: Vec<ElevatorConfig>,
194 /// Physical orientation (defaults to Vertical).
195 #[serde(default)]
196 pub orientation: Orientation,
197 /// Optional floor-plan position.
198 #[serde(default)]
199 pub position: Option<FloorPosition>,
200 /// Lowest reachable position (auto-computed from stops if `None`).
201 #[serde(default)]
202 pub min_position: Option<f64>,
203 /// Highest reachable position (auto-computed from stops if `None`).
204 #[serde(default)]
205 pub max_position: Option<f64>,
206 /// Max cars on this line (`None` = unlimited).
207 #[serde(default)]
208 pub max_cars: Option<usize>,
209}
210
211/// Configuration for an elevator dispatch group.
212///
213/// A group is the logical dispatch unit containing one or more lines.
214/// All elevators within the group share a single [`BuiltinStrategy`].
215#[derive(Debug, Clone, Serialize, Deserialize)]
216pub struct GroupConfig {
217 /// Unique group identifier.
218 pub id: u32,
219 /// Human-readable name.
220 pub name: String,
221 /// Line IDs belonging to this group (references [`LineConfig::id`]).
222 pub lines: Vec<u32>,
223 /// Dispatch strategy for this group.
224 pub dispatch: BuiltinStrategy,
225 /// Optional repositioning strategy for idle elevators.
226 ///
227 /// When `None`, idle elevators in this group stay where they stopped.
228 #[serde(default)]
229 pub reposition: Option<BuiltinReposition>,
230}