Struct SimulationBuilder 

pub struct SimulationBuilder { /* private fields */ }

Fluent builder for constructing a Simulation.

Builds a SimConfig internally and delegates to Simulation::new(). Provides a more ergonomic API for programmatic construction compared to assembling a config struct manually.

Default configuration

SimulationBuilder::new() starts with a minimal valid config:

• 2 stops at positions 0.0 and 10.0
• 1 elevator with reasonable defaults
• ScanDispatch strategy
• 60 ticks per second

Implementations

impl SimulationBuilder

pub fn new() -> Self

Create a builder with a minimal valid default configuration.

The default gives you two stops (Ground at 0.0, Top at 10.0) and one elevator with SCAN dispatch. Override any part with the fluent methods before calling build.

use elevator_core::prelude::*;

let sim = SimulationBuilder::new().build().unwrap();
assert_eq!(sim.current_tick(), 0);

pub fn from_config(config: SimConfig) -> Self

Create a builder from an existing SimConfig.

Uses ScanDispatch as the default strategy. Call .dispatch() to override.

pub fn stops(self, stops: Vec<StopConfig>) -> Self

Replace all stops with the given list.

Clears any previously added stops.

pub fn stop(self, id: StopId, name: impl Into<String>, position: f64) -> Self

Add a single stop to the building.

pub fn elevators(self, elevators: Vec<ElevatorConfig>) -> Self

Replace all elevators with the given list.

Clears any previously added elevators.

pub fn elevator(self, config: ElevatorConfig) -> Self

Add a single elevator configuration.

pub fn line(self, config: LineConfig) -> Self

Add a single line configuration.

Switches from legacy flat-elevator mode to explicit topology.

pub fn lines(self, lines: Vec<LineConfig>) -> Self

Replace all lines with the given list.

Switches from legacy flat-elevator mode to explicit topology.

pub fn group(self, config: GroupConfig) -> Self

Add a single group configuration.

pub fn groups(self, groups: Vec<GroupConfig>) -> Self

Replace all groups with the given list.

pub const fn ticks_per_second(self, tps: f64) -> Self

Set the simulation tick rate (ticks per second).

pub fn building_name(self, name: impl Into<String>) -> Self

Set the building name.

pub fn dispatch(self, strategy: impl DispatchStrategy + 'static) -> Self

Set the default dispatch strategy for the default group.

pub fn dispatch_for_group( self, group: GroupId, strategy: impl DispatchStrategy + 'static, ) -> Self

Set a dispatch strategy for a specific group.

pub fn before( self, phase: Phase, hook: impl Fn(&mut World) + Send + Sync + 'static, ) -> Self

Register a hook to run before a simulation phase.

pub fn after( self, phase: Phase, hook: impl Fn(&mut World) + Send + Sync + 'static, ) -> Self

Register a hook to run after a simulation phase.

pub fn before_group( self, phase: Phase, group: GroupId, hook: impl Fn(&mut World) + Send + Sync + 'static, ) -> Self

Register a hook to run before a phase for a specific group.

pub fn after_group( self, phase: Phase, group: GroupId, hook: impl Fn(&mut World) + Send + Sync + 'static, ) -> Self

Register a hook to run after a phase for a specific group.

pub fn reposition( self, strategy: impl RepositionStrategy + 'static, id: BuiltinReposition, ) -> Self

Set a reposition strategy for the default group.

Enables the reposition phase, which runs after dispatch to move idle elevators for better coverage.

pub fn reposition_for_group( self, group: GroupId, strategy: impl RepositionStrategy + 'static, id: BuiltinReposition, ) -> Self

Set a reposition strategy for a specific group.

pub fn with_ext<T: 'static + Send + Sync + Serialize + DeserializeOwned>( self, name: &str, ) -> Self

Pre-register an extension type for snapshot deserialization.

Extensions registered here will be available immediately after build() without needing to call register_ext manually.

pub fn validate(&self) -> Result<(), SimError>

Validate the configuration without building the simulation.

Runs the same validation as build() but does not allocate entities or construct the simulation. Useful for CLI tools, config editors, and dry-run checks.

Errors

Returns SimError::InvalidConfig if the configuration is invalid.

pub fn build(self) -> Result<Simulation, SimError>

Build the simulation, validating the configuration.

Returns Err(SimError) if the configuration is invalid.

Errors

Returns SimError::InvalidConfig if the assembled configuration is invalid.

Examples

use elevator_core::prelude::*;
use elevator_core::stop::StopConfig;

let mut sim = SimulationBuilder::new()
    .stops(vec![
        StopConfig { id: StopId(0), name: "Lobby".into(), position: 0.0 },
        StopConfig { id: StopId(1), name: "Roof".into(), position: 20.0 },
    ])
    .build()
    .unwrap();

sim.spawn_rider_by_stop_id(StopId(0), StopId(1), 75.0).unwrap();

for _ in 0..1000 {
    sim.step();
}

assert!(sim.metrics().total_delivered() > 0);

Trait Implementations

impl Default for SimulationBuilder

fn default() -> Self

Returns the “default value” for a type.