Error Handling

The simulation uses a single error enum, SimError, for all fallible operations. This chapter covers the error variants, rider rejection reasons, and practical patterns for handling failures in game code.

SimError

SimError covers both configuration validation and runtime failures. It implements Display and std::error::Error, so it works with ?, anyhow, eyre, and other error-handling crates.

Configuration errors

The field string identifies which config parameter is invalid, and reason explains why. All config validation happens at construction time – if build() succeeds, the simulation is in a valid state.

Entity lookup errors

These are the most common runtime errors. They typically indicate a stale EntityId (the entity was despawned) or a config mismatch (using a StopId that was never registered).

Rider state errors

For example, calling sim.settle_rider(id) on a rider in Waiting phase returns WrongRiderPhase – settle requires Arrived or Abandoned.

Routing errors

NoRoute and AmbiguousRoute are returned by spawn_rider() and build_rider(). In multi-group buildings, use build_rider() with an explicit group to resolve ambiguity.

Topology errors

Snapshot errors

RejectionReason

When a rider cannot board an elevator, a RiderRejected event fires with a typed RejectionReason:

RejectionContext

Every RiderRejected event includes a RejectionContext with the numeric details behind the decision:

#![allow(unused)]
fn main() {
use elevator_core::prelude::*;
use ordered_float::OrderedFloat;

let context = RejectionContext {
    attempted_weight: OrderedFloat(80.0), // weight the rider tried to add
    current_load: OrderedFloat(750.0),    // elevator's load at rejection time
    capacity: OrderedFloat(800.0),        // elevator's maximum weight capacity
};
let _ = context;
}

RejectionContext implements Display for game-friendly feedback:

#![allow(unused)]
fn main() {
use elevator_core::prelude::*;
use ordered_float::OrderedFloat;
let context = RejectionContext {
    attempted_weight: OrderedFloat(80.0),
    current_load: OrderedFloat(750.0),
    capacity: OrderedFloat(800.0),
};
// "over capacity by 30.0kg (750.0/800.0 + 80.0)"
println!("{}", context);
}

EtaError

ETA queries (sim.eta(), sim.best_eta()) use a separate error type because they fail for different reasons than general simulation operations:

Handling spawn failures

The most common error path in game code is spawning riders. Here are the key failures and how to handle them:

#![allow(unused)]
fn main() {
use elevator_core::prelude::*;
let mut sim: Simulation = todo!();
match sim.spawn_rider(StopId(0), StopId(5), 75.0) {
    Ok(rider) => {
        // Rider spawned successfully.
    }
    Err(SimError::StopNotFound(id)) => {
        // StopId doesn't exist in config. Check your stop setup.
        eprintln!("Unknown stop: {id}");
    }
    Err(SimError::NoRoute { origin, destination, .. }) => {
        // No group connects these two stops.
        eprintln!("No route from {origin:?} to {destination:?}");
    }
    Err(SimError::AmbiguousRoute { groups, .. }) => {
        // Multiple groups serve both stops. Use build_rider()
        // with an explicit group instead.
        eprintln!("Ambiguous: served by {groups:?}");
    }
    Err(e) => {
        eprintln!("Spawn failed: {e}");
    }
}
}

Reacting to rejections

Rider rejections are not Rust errors – they are events. The simulation continues normally; the rejected rider stays in their current phase (usually Waiting). React to rejections by draining events:

#![allow(unused)]
fn main() {
use elevator_core::prelude::*;
fn run(sim: &mut Simulation) {
sim.step();

for event in sim.drain_events() {
    if let Event::RiderRejected { rider, elevator, reason, context, tick } = event {
        match reason {
            RejectionReason::OverCapacity => {
                // Show "elevator full" indicator in game UI.
                if let Some(ctx) = &context {
                    println!("[{tick}] {rider:?} rejected from {elevator:?}: {ctx}");
                }
            }
            RejectionReason::AccessDenied => {
                // Flash "access denied" on the panel.
            }
            RejectionReason::PreferenceBased => {
                // Rider chose to skip -- animate them stepping back.
            }
            _ => {}
        }
    }
}
}
}

Best practices

• Always handle Results from spawn_rider and build_rider. These are the most likely to fail in dynamic scenarios where stops or groups change at runtime.
• Use build_rider() in multi-group buildings to avoid AmbiguousRoute by specifying the group explicitly.
• Check is_elevator() / is_stop() before calling entity-specific methods if you are working with mixed EntityId collections.
• Treat RiderRejected as a normal game event, not an error. The simulation handles it gracefully; your game just needs to decide how to present it.
• Log SimError in debug builds. The Display impl produces clear, actionable messages that point directly at the problem.

Next steps

• Rider Lifecycle – understand the phases that trigger rejection and abandonment
• Events and Metrics – the full event system including rejection events
• Configuration – avoid InvalidConfig errors by understanding validation rules