✈️ AirControlX

ATC Concurrent Runway Scheduling Simulator

[](https://en.cppreference.com/w/cpp/17) [](https://www.raylib.com/) [](https://cmake.org/) [](LICENSE) []()

A real-time, multi-threaded Air Traffic Control simulator with a live graphical dashboard built on Raylib. Features priority-aware runway scheduling, automated violation detection (AVN), payment processing, and live performance metrics.

---

📋 Table of Contents

• Features
• Architecture
• Project Structure
• Prerequisites
• Build & Run
• Controls & Commands
• Flight Priority System
• AVN System
• Performance Metrics
• Contributing

---

🚀 Features

Feature	Description
Multi-threaded Simulation	Separate threads for the scheduler, radar (AVN detection), and user input — all synchronized via std::mutex
Priority Runway Scheduling	Emergency > Medical/Military > Cargo > Commercial, with preemption support
Live Raylib Dashboard	Real-time KPI cards, animated aircraft glyphs, event feed, and runway occupancy display
AVN Issuance & Payment	Speed violations trigger Air-traffic Violation Notices with fines; manageable through CLI commands
Ground Fault Simulation	Random ground faults during Taxi/Gate phases clear runways and log incidents
Deterministic Replay	Pass --seed <N> for fully reproducible simulation runs
Live Metrics Overlay	Press M at any time for runway utilisation, queue depth, AVN rate, and emergency response time

---

🖼 Simulation Views

Different runtime scenarios including runway allocation, live traffic management, and metrics overlays.

---

🏗 Architecture

┌─────────────────────────────────────────────────────┐
│                      main.cpp                       │
│   Launches sim thread → drives Renderer loop        │
└────────────┬────────────────────────┬───────────────┘
             │                        │
    ┌────────▼──────────┐   ┌────────▼──────────┐
    │    Simulator      │   │     Renderer       │
    │  (scheduler core) │   │  (Raylib dashboard)│
    └──┬────────────────┘   └────────────────────┘
       │
  ┌────▼──────────────┐   ┌────────────────────┐
  │  AirlinePortal    │   │  PaymentGateway     │
  │  AVN lookup &     │◄──│  Fine submission &  │
  │  auth             │   │  transaction        │
  └───────────────────┘   └────────────────────┘

Thread model

Thread	Role
Main	Raylib render loop at 30 FPS
simThread	Tick loop — scheduling, phase advance, allocation (1 tick / sec)
radarThread	Speed-violation scan every 500 ms, issues AVNs
inputThread	Reads stdin for CLI commands

---

📁 Project Structure

AirControlX/
│
├── CMakeLists.txt            # Build configuration (auto-fetches Raylib if needed)
│
├── include/                  # Public headers — one per module
│   ├── types.h               # Shared enums, structs (AVN, Flight, Runway, EventEntry)
│   ├── airline_portal.h      # AVN lookup & payment recording interface
│   ├── payment_gateway.h     # Fine payment processing interface
│   ├── simulator.h           # Core scheduling engine interface
│   └── renderer.h            # Raylib dashboard interface
│
├── src/                      # Implementations
│   ├── main.cpp              # Entry point
│   ├── airline_portal.cpp    # Portal implementation
│   ├── payment_gateway.cpp   # Gateway implementation
│   ├── simulator.cpp         # Scheduler + radar + AVN logic
│   └── renderer.cpp          # All Raylib drawing code
│
└── screenshots/              # UI previews for documentation
    └── dashboard.png

---

🛠 Prerequisites

All platforms

• CMake ≥ 3.16
• C++17 compiler (GCC 9+, Clang 10+, MSVC 2019+)
• Git (for FetchContent fallback)

Linux (Ubuntu / Debian)

sudo apt update
sudo apt install -y cmake g++ git \
    libgl1-mesa-dev libx11-dev libxrandr-dev libxinerama-dev \
    libxcursor-dev libxi-dev libxext-dev

macOS

brew install cmake
# Xcode Command Line Tools provide the compiler:
xcode-select --install

Windows

• Install CMake and Visual Studio 2022 (with C++ workload)
• Or use MSYS2 with mingw-w64

Raylib is fetched automatically from GitHub if not found on your system. No manual installation required.

---

⚙️ Build & Run

1 — Clone

git clone https://github.com/<your-username>/AirControlX.git
cd AirControlX

2 — Configure & Build

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

On first build, CMake will download and compile Raylib (~1–2 min). Subsequent builds are fast.

3 — Run

# Random seed (different every run)
./build/AirControlX

# Deterministic / reproducible run
./build/AirControlX --seed 42

Windows (Visual Studio)

cmake -B build
cmake --build build --config Release
.\build\Release\AirControlX.exe --seed 42

Install system-wide (optional)

cmake --install build --prefix /usr/local
aircontrolx

---

🎮 Controls & Commands

Keyboard (in window)

Key	Action
M	Toggle live performance metrics overlay
ESC	Exit the simulator

CLI commands (type in the terminal while running)

View AVNs for a flight

VIEW <flightID> <YYYY-MM-DD>

Example:

VIEW PIA-412 2025-05-14

Pay an AVN fine

PAY <avnID> <flightID> <flightType#> <amount> <paymentMethod>

Flight type numbers: 0=Commercial, 1=Cargo, 2=Emergency, 3=Medical, 4=Military

Example:

PAY AVN-3 PIA-412 0 575000.00 CreditCard

Response: OK TX:847291 or FAIL: <reason>

---

🛩 Flight Priority System

Runway allocation follows a strict priority ladder:

EMERGENCY  ──►  Any free runway (immediate); preempts Commercial/Cargo if needed
MEDICAL    ──►  RWY-C preferred, then any free
MILITARY   ──►  RWY-C preferred, then any free
CARGO      ──►  RWY-C preferred, then any free
COMMERCIAL ──►  RWY-A (arrivals) / RWY-B (departures)

Preemption: If an Emergency flight is waiting and all runways are occupied by Commercial or Cargo flights, the lowest-priority occupied runway is cleared and the occupant is re-queued.

Runway roles

Runway	Primary role	Colour
RWY-A	Arrivals	Blue
RWY-B	Departures	Green
RWY-C	Priority / Cargo / Overflow	Orange

---

📋 AVN (Air-traffic Violation Notice) System

Speeds are validated against per-phase limits:

Phase	Min (kph)	Max (kph)
Holding	400	600
Approach	240	290
Landing	30	240
Taxi	15	30
At Gate	0	5
Takeoff Roll	0	290
Climb	250	463

Fine schedule:

• Commercial flights: PKR 500,000 base + 15% service charge = PKR 575,000
• Other types: PKR 700,000 base + 15% = PKR 805,000
• Payment due within 72 hours of issuance

---

📊 Performance Metrics

Press M during the simulation or wait for the end-of-run summary:

Metric	Description
Avg wait time	Mean seconds a flight waited in queue before runway assignment
Peak queue depth	Maximum number of flights simultaneously waiting
RWY-A/B/C utilisation	Percentage of sim ticks each runway was occupied
AVN rate	Violations issued per simulated hour
Avg emergency response	Mean ticks from EMERGENCY arrival to runway assignment

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m "feat: add my feature"
4. Push: git push origin feature/my-feature
5. Open a Pull Request

Please keep code style consistent with the existing codebase (C++17, no external dependencies beyond Raylib).

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.

---

Built with ❤️ using C++17 & Raylib