# thbmelatoe/openage architecture

> Architecture diagram of the GitHub repository thbmelatoe/openage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thbmelatoe/openage
- Repository: https://github.com/thbmelatoe/openage

## Overview

Based on our review of the complete file tree and the README, we can conclude that openage is a full-featured game engine project whose goal is to reproduce the look and feel of the Genie Engine (used in Age of Empires) with a modern, modular design that integrates C++20 for the engine core with Python for scripting, asset conversion, an in-game console, and code generation. In addition, openage uses Cython to “glue” Python and C++ together, Qt6 for the GUI, OpenGL for rendering, and a range of other technologies (such as Opus for audio and nyan for modding assets) to form a robust, extensible game engine system.

##### Main Components
- Engine Core (C++20): This represents the main simulation and game processing logic.
- Rendering Subsystem: Built with OpenGL (and possibly Vulkan later) and includes modules for shaders, camera, GUI integration (via Qt6), fonts, and other visual components.
- Audio Subsystem: Handling audio management, codecs (Opus), dynamic loading, and resource management.
- Game State & Simulation: Includes gamestate management, entity component systems, activity and event handling (found throughout libopenage/gamestate) that are essential for in-game simulation.
- Input/ Event Handling: Managed through dedicated libraries for handling user input, controllers (camera, game, HUD), and event loops.
- Media Conversion / Content Pipeline: Encompasses the directories under “openage/convert” and “cfg/converter” which turn original assets (from the Age of Empires series) into openage-friendly formats, leveraging the nyan API.
- Python/C++ Glue & Scripting: Happening via Cython as well as Python modules (e.g., in openage/pyinterface, openage/cppinterface) to expose engine functionality to scripting, in-game consoles, and modding.
- Build and Code Generation: Tools such as CMake, Makefiles, and custom Python code generation techniques (openage/codegen) support the build process.
- Auxiliary Components: Job system, logging, debugging support and error handling (as seen in libopenage/log, libopenage/event, libopenage/error, etc).

##### Relationships and Interactions
- The Engine Core drives the simulation loop and interacts with subsystems such as Rendering, Audio, and Input.
- The Rendering subsystem communicates with both the Engine Core (to fetch game entity visual data) and the GUI (via Qt integration).
- The Audio subsystem responds to game events and simulation states to trigger sound playback.
- The Game State components interact with Input and Event systems to update entity state. These are often coordinated via a central event loop or message–passing mechanism.
- The Python/C++ binding layer (via Cython) exposes core engine functionality to Python; for example, the in-game console and media conversion scripts.
- Media Conversion feeds processed assets into the engine (and is highly integrated with the nyan API for content/mapping configuration).

##### Architectural Patterns and Design Principles
- Modular design: Each main feature of the engine is divided into dedicated libraries and modules (e.g., libopenage/audio, libopenage/gamestate, libopenage/renderer), which improves maintainability and extensibility.
- Separation of Concerns: There’s clear separation between core simulation, rendering, audio, input, and external subsystem interfacing (Python, GUI, asset conversion).
- Event Driven / Game Loop Pattern: The engine’s reactive architecture is built around an event loop that integrates input, simulation, and rendering each frame.
- Interoperability via Cython: The project uses a blend of C++ for performance-critical modules and Python for rapid development and scripting, bridged by Cython for efficient communication.

##### Relevant External Technologies and Frameworks
- C++20 – core simulation and engine modules.
- Python3 – scripting, media conversion, in-game console and code generation.
- Cython – to bind Python with C++.
- Qt6 – for extensive GUI elements.
- CMake – as the primary build system.
- OpenGL – for rendering (with shader handling, camera systems, etc.).
- Opus – for audio codec support.
- nyan – for content configuration and modding support.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        A["Engine Core (C++20)"]:::cpp
        D["Game State & Simulation"]:::cpp
    end

    %% Subsystems Layer
    subgraph "Subsystems Layer"
        B["Rendering Subsystem (OpenGL/Qt6)"]:::cpp
        C["Audio Subsystem (Opus)"]:::cpp
        subgraph "Input/Event Handling"
            E1["Input Handling"]:::cpp
            E2["Event Handling"]:::cpp
        end
    end

    %% Scripting/Python Integration Layer
    subgraph "Scripting/Python Integration Layer"
        F1["Python Interface (Glue)"]:::python
        F2["C++ Interface (Glue)"]:::python
    end

    %% Media Conversion Layer
    subgraph "Media Conversion Layer"
        G1["Media Conversion Pipeline (openage/convert)"]:::python
        G2["Converter Config (cfg/converter)"]:::python
    end

    %% Build/Infrastructure Tools Layer
    subgraph "Build/Infrastructure Tools Layer"
        H1["Build: Code Generation"]:::build
        H2["Build: Build System"]:::build
    end

    %% Auxiliary Components Layer
    subgraph "Auxiliary Components Layer"
        I1["Job System"]:::aux
        I2["Logging & Debugging"]:::aux
    end

    %% Connections between components
    A -->|"simulation_loop"| D
    A -->|"visual_data"| B
    A -->|"sound_triggers"| C
    E1 -->|"input_event"| D
    E2 -->|"event_broadcast"| D
    F1 -->|"exposes_API"| A
    F2 -->|"exposes_API"| A
    G1 -->|"asset_conversion"| B
    G2 -->|"config_mapping"| G1
    H1 -->|"code_generation"| A
    H2 -->|"build_system"| A
    I1 -->|"job_scheduling"| A
    I2 -->|"logging_debug"| A

    %% Click Events
    click A "https://github.com/thbmelatoe/openage/tree/master/libopenage/engine"
    click B "https://github.com/thbmelatoe/openage/tree/master/libopenage/renderer"
    click B "https://github.com/thbmelatoe/openage/tree/master/assets/shaders"
    click C "https://github.com/thbmelatoe/openage/tree/master/libopenage/audio"
    click D "https://github.com/thbmelatoe/openage/tree/master/libopenage/gamestate"
    click E1 "https://github.com/thbmelatoe/openage/tree/master/libopenage/input"
    click E2 "https://github.com/thbmelatoe/openage/tree/master/libopenage/event"
    click F1 "https://github.com/thbmelatoe/openage/tree/master/openage/pyinterface"
    click F2 "https://github.com/thbmelatoe/openage/tree/master/openage/cppinterface"
    click G1 "https://github.com/thbmelatoe/openage/tree/master/openage/convert"
    click G2 "https://github.com/thbmelatoe/openage/tree/master/cfg/converter"
    click H1 "https://github.com/thbmelatoe/openage/tree/master/openage/codegen"
    click H2 "https://github.com/thbmelatoe/openage/tree/master/buildsystem"
    click I1 "https://github.com/thbmelatoe/openage/tree/master/libopenage/job"
    click I2 "https://github.com/thbmelatoe/openage/tree/master/libopenage/log"

    %% Class Definitions
    classDef cpp fill:#ffcccc,stroke:#000,stroke-width:2px;
    classDef python fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef build fill:#ccccff,stroke:#000,stroke-width:2px;
    classDef aux fill:#ffffcc,stroke:#000,stroke-width:2px;
```
