# sfttech/openage architecture

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

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

## Overview

##### Major Components
- Engine Core: Representing the low-level game simulation, game state management, physics, event system, and internal systems (these are largely found in “libopenage/engine”, “libopenage/gamestate”, “libopenage/event”, “libopenage/input”, and other similar directories).
- Renderer and Visuals: A distinct module handling graphical output, shaders, camera, and GUI components. (Look at “libopenage/renderer”, “assets/shaders”, “assets/qml”, and even Qt-related parts in the codebase.)
- Audio Subsystem: Covering audio management, decoding, and sound resource handling. (See “libopenage/audio”)
- Scripting and Python Integration: Modules responsible for the integrated Python console, media conversion, code generation, and general glue code provided by Cython. (This is visible in “openage”, “libopenage/pyinterface”, “openage/codegen”, and several “.py” files.)
- Asset Conversion and Modding: Conversion tools and pipelines (e.g., “openage/convert”, “openage/convert/entity_object”, “openage/convert/processor”) that interpret original game assets and translate them into openage’s mod-friendly formats.
- Build/Configuration Infrastructure: The build system (CMake scripts, Makefiles, and buildsystem directories) that orchestrates the compilation and testing across multiple platforms (as reflected by the GitHub workflow configuration files).

##### Relationships and Interactions
- The Engine Core interacts directly with the Renderer (for drawing game world states), the Audio system (to output sound), and the Input system (to capture player actions) and is interconnected with the Event and Game State management.
- The Python integration layer acts as a higher-level interface that allows scripting of game logic, asset conversion, and potentially modding and debugging via an in-game console.
- Asset conversion tools take external assets (from directories such as assets and openage/convert) and feed processed data into the engine at runtime.
- The build and continuous integration components ensure that the engine, scripting components, and asset converters build and deploy correctly across various platforms.

##### Architectural Patterns
- Modular Design: The system is decomposed into many smaller, well-defined modules (audio, renderer, gamestate, input, etc.), promoting testability and easy modification.
- Layered Abstraction: There is a clear separation of low-level engine systems (in C++ core libraries) and higher-level scripting and customization (via Python/Cython).
- Plugin/Extensibility Approach: With modding via the nyan configuration system and clearly separated asset conversion pipelines, the design promotes extensibility.
- Use of Cross-Platform Build Tools: The project uses CMake extensively for cross-platform builds, alongside CI workflows for Windows, macOS, and Linux.

##### Relevant Technologies
- C++20 for the performance-critical engine core.
- Python3 and Cython for scripting and glue code.
- Qt6 for graphical user interface components.
- OpenGL for rendering and shader management.
- Opus for audio codec functionality.
- nyan for content configuration and modding support.
- CMake as well as Makefiles for build orchestration.
- Additional tools such as the custom Kevin CI service for continuous integration.

##### Final Suggestions
- To include the interaction between compiled native code and Python-driven modules.
- Pay attention to the build and testing infrastructure since it is extensive and cross-platform.
- Be detailed – even if it means separating the engine core into smaller modules (like gamestate, event, input, etc.) since the file structure demonstrates a highly decoupled design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core System (C++ Libraries)
    subgraph "Engine Core"
        ES["Engine Simulation"]:::core
        GSM["Game State Manager"]:::core
        EV["Event System"]:::core
        IH["Input Handler"]:::core
    end

    %% Renderer and Visuals
    subgraph "Renderer & Visuals"
        R["Renderer (OpenGL, Qt6)"]:::graphics
        SH["Shaders"]:::graphics
        QML["QML UI"]:::graphics
    end

    %% Audio Subsystem
    subgraph "Audio Subsystem"
        A["Audio System (Opus)"]:::audio
    end

    %% Scripting and Python Integration
    subgraph "Scripting & Python Integration"
        PS["Python Scripting (in-game console)"]:::scripting
        PI["Py Interface"]:::scripting
        CG["Code Generation"]:::scripting
    end

    %% Asset Conversion & Modding
    subgraph "Asset Conversion & Modding"
        ACT["Asset Conversion Tool"]:::conversion
        EOC["Entity Object Conversion"]:::conversion
        PP["Processor Pipeline"]:::conversion
    end

    %% Build/CI Infrastructure
    subgraph "Build/CI Infrastructure"
        BSD["Build System Directory"]:::build
        CMake["CMake Build"]:::build
        CI["CI Workflows"]:::build
    end

    %% Relationships
    %% Input flows into Engine Simulation
    IH -->|"sendsInput"| ES

    %% Internal engine relationships
    ES -->|"manages"| GSM
    ES -->|"triggers"| EV

    %% Engine Core connects to Renderer and Audio
    ES -->|"renders"| R
    ES -->|"outputsAudio"| A

    %% Renderer connections
    R ---|"uses"| SH
    R ---|"uses"| QML

    %% Scripting layer interactions
    PS -->|"controls"| ES
    PI -->|"interfaces"| ES
    CG -->|"generates"| PI

    %% Asset Conversion feeds into Engine Core
    ACT -->|"feedsAssets"| ES
    EOC -->|"processesAssets"| ES
    PP -->|"processesAssets"| ES

    %% Build Infrastructure supports major components
    BSD -->|"builds"| ES
    BSD -->|"builds"| PS
    BSD -->|"builds"| ACT
    CMake -->|"configures"| BSD
    CI -->|"runsTests"| BSD

    %% Styles
    classDef core fill:#f9e79f,stroke:#af601a,stroke-width:2px;
    classDef graphics fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef audio fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef scripting fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef conversion fill:#f9e79f,stroke:#af7ac5,stroke-width:2px;
    classDef build fill:#d2b4de,stroke:#6c3483,stroke-width:2px;

    %% Click Events for Engine Core
    click ES "https://github.com/sfttech/openage/tree/master/libopenage/engine"
    click GSM "https://github.com/sfttech/openage/tree/master/libopenage/gamestate"
    click EV "https://github.com/sfttech/openage/tree/master/libopenage/event"
    click IH "https://github.com/sfttech/openage/tree/master/libopenage/input"

    %% Click Events for Renderer and Visuals
    click R "https://github.com/sfttech/openage/tree/master/libopenage/renderer"
    click SH "https://github.com/sfttech/openage/tree/master/assets/shaders"
    click QML "https://github.com/sfttech/openage/tree/master/assets/qml"

    %% Click Event for Audio Subsystem
    click A "https://github.com/sfttech/openage/tree/master/libopenage/audio"

    %% Click Events for Scripting and Python Integration
    click PS "https://github.com/sfttech/openage/blob/master/openage/__main__.py"
    click PI "https://github.com/sfttech/openage/tree/master/libopenage/pyinterface"
    click CG "https://github.com/sfttech/openage/tree/master/openage/codegen"

    %% Click Events for Asset Conversion & Modding
    click ACT "https://github.com/sfttech/openage/tree/master/openage/convert"
    click EOC "https://github.com/sfttech/openage/tree/master/openage/convert/entity_object"
    click PP "https://github.com/sfttech/openage/tree/master/openage/convert/processor"

    %% Click Events for Build/CI Infrastructure
    click BSD "https://github.com/sfttech/openage/tree/master/buildsystem"
    click CMake "https://github.com/sfttech/openage/blob/master/CMakeLists.txt"
    click CI "https://github.com/sfttech/openage/tree/master/.github/workflows"
```
