Elevators

elevators is a C++23 elevator control library intended for simulation and game integration. It models realistic bank coordination, per-car service ranges, parking floors, door dwell timing, and front/rear door behavior for service and hospital-style elevators.

What The API Covers

• Configurable elevator banks through ElevatorBankConfig.
• Per-car configuration through ElevatorCarConfig.
• Hall calls with direction and door-side requests.
• Destination requests with front, rear, or dual-door stops.
• Bank-side coordination across multiple cars.
• Zoned dispatching for low-rise, high-rise, and service cars.
• Idle parking behavior for more realistic bank staging.
• Snapshot-based status APIs for UI, AI, and building systems.

Public API

The easiest include is:

#include "Elevators.h"

Primary types:

• Elevators::ElevatorBank
• Elevators::ElevatorBankConfig
• Elevators::ElevatorCarConfig
• Elevators::ElevatorRequest
• Elevators::DestinationRequest
• Elevators::ElevatorBankStatus
• Elevators::ElevatorStatus

Example

#include "Elevators.h"

int main()
{
    Elevators::ElevatorCarConfig passenger;
    passenger.name = "low_rise_a";
    passenger.start_floor = 1;
    passenger.end_floor = 25;
    passenger.dispatch_zone_low = 1;
    passenger.dispatch_zone_high = 12;
    passenger.parking_floor = 1;

    Elevators::ElevatorCarConfig service = passenger;
    service.name = "service";
    service.dispatch_zone_high = 25;
    service.rear_doors = true;
    service.floor_doors = {
        {.floor = 2, .side = Elevators::DoorSide::BOTH},
        {.floor = 7, .side = Elevators::DoorSide::REAR}
    };

    Elevators::ElevatorBankConfig bank_config;
    bank_config.name = "office_low_rise";
    bank_config.lobby_floor = 1;
    bank_config.cars = {passenger, service};

    Elevators::ElevatorBank bank(bank_config);

    const auto assigned = bank.requestPickup({
        .floor = 7,
        .direction = Elevators::Direction::UP,
        .door_side = Elevators::DoorSide::REAR
    });

    if (assigned.has_value())
    {
        bank.requestDestination(*assigned, 20);
    }

    bank.step();
    const auto status = bank.status();
}

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/elevators

The demo executable is built as elevators. The library target is elevator_controller, exposed publicly as elevators::controller.

Install And Package

To stage an installable package containing headers, library, CMake package files, and the demo executable:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build --prefix package

That install tree can be dropped into another C++ project or archived for distribution.

CMake Integration

If you vendor the source directly:

add_subdirectory(path/to/elevators)
target_link_libraries(your_app PRIVATE elevators::controller)

If you install the package first:

find_package(elevators CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE elevators::controller)

Door Modeling

DoorSide supports FRONT, REAR, and BOTH.

• Cars can have front doors only, rear doors only, or both.
• floor_doors lets you define which side opens on each floor.
• A stop can explicitly request rear access or dual-door opening.
• If a car is configured with both door sets and a floor supports both, the controller can open both at the same stop.

Release Builds

The workflow in .github/workflows/release.yml builds the project on Linux, macOS, and Windows for tags matching v*, installs the package layout, archives it, and attaches the artifacts to the GitHub release.