elevator-core

From a 5-story office to a space elevator — same engine, same API.

An engine-agnostic, tick-based elevator simulation library for Rust.
Plug it into Bevy, Unity, your own renderer, or run headless.

Guide · API Reference · Examples

▶ Try the live playground — race two dispatch strategies on the same traffic, side-by-side in your browser.

What it does

You define stops at arbitrary positions on a 1-D axis, spawn riders, and call step(). The engine handles dispatch, trapezoidal motion, doors, boarding, and metrics — your code just reacts to events.

use elevator_core::prelude::*;
use elevator_core::config::ElevatorConfig;

fn main() -> Result<(), SimError> {
    let mut sim = SimulationBuilder::new()
        .stop(StopId(0), "Lobby", 0.0)
        .stop(StopId(1), "Floor 2", 4.0)
        .stop(StopId(2), "Floor 3", 8.0)
        .elevator(ElevatorConfig { starting_stop: StopId(0), ..Default::default() })
        .build()?;

    sim.spawn_rider(StopId(0), StopId(2), 75.0)?;

    for _ in 0..1000 {
        sim.step();
        for event in sim.drain_events() {
            match event {
                Event::RiderExited { rider, tick, .. } => {
                    println!("Tick {tick}: rider {rider:?} delivered!");
                    return Ok(());
                }
                Event::RiderAbandoned { rider, stop, tick, .. } => {
                    eprintln!("Tick {tick}: rider {rider:?} abandoned at {stop:?}");
                    return Ok(());
                }
                _ => {}
            }
        }
    }
    eprintln!("timed out after 1000 ticks");
    Ok(())
}

The README snippet above prints Tick N: rider … delivered! once the rider arrives. To run a slightly more elaborate example, with three riders and aggregate metrics:

cargo run --example basic -p elevator-core
# All riders arrived at tick 335!
# Delivered: 3
# Avg wait: 5.0 ticks
# Avg ride: 328.0 ticks

Use cases

Features

• Arbitrary stop positions: not limited to uniform floors; model buildings, towers, orbital tethers
• Pluggable dispatch: built-in SCAN, LOOK, Nearest Car, ETD, Destination; or bring your own via the DispatchStrategy trait
• Rider lifecycle: Waiting → Boarding → Riding → Exiting → Arrived/Abandoned, with hooks at each transition
• Extension storage: attach arbitrary typed data to riders, elevators, and stops
• O(1) population queries: who's waiting, riding, or resident at any stop, instantly
• Deterministic replay: same inputs produce the same simulation every time
• Snapshot save/load: serialize full simulation state for replays or networking
• Metrics: wait times, ride times, throughput, delivered counts, all built-in

Hosts

elevator-core itself is headless. Pick the host that matches your engine:

Anything not on the list? Drive Simulation::step() yourself — the API is engine-agnostic.

Non-goals

This is a simulation library, not a game. It deliberately does not include:

• Rendering or UI — see the host crates above, or roll your own
• AI passengers or traffic generation — use the optional traffic feature flag, or drive arrivals yourself
• Building layout or 2-D floor plans — the sim is 1-D by design

Visual demo

The workspace includes a Bevy frontend that renders the simulation in 2-D:

cargo run                                       # default 5-stop building
cargo run -- assets/config/space_elevator.ron    # 1,000 km orbital tether

TUI debugger

For tick-by-tick debugging or headless smoke runs, the workspace also ships elevator-tui — a terminal viewer with pause/step controls, event log, dispatch summary, and snapshot save/load on a hotkey. See the TUI Debugger guide.

cargo run -p elevator-tui -- assets/config/default.ron                    # interactive
cargo run -p elevator-tui -- assets/config/default.ron --headless --until 5000  # CI smoke

Feature flags

Workspace

elevator-core is the simulation library. The hosts above wrap it. A handful of supporting crates (elevator-contract, elevator-layout-derive, elevator-layout-runtime, elevator-layout-codegen) are build-time / test-only and exist to keep the host bindings in sync. See CLAUDE.md for the full layout.

See also

• Stability and Versioning — what counts as a breaking change and what doesn't.
• elevator-core changelog — release-please-managed.
• AI disclosure — how AI tools are used in this repo.

License

MIT or Apache 2.0, at your option.