# livinamuk/hell2025 architecture

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

- Interactive diagram: https://gitdiagram.com/livinamuk/hell2025
- Repository: https://github.com/livinamuk/hell2025

## Overview

##### Project Type and Purpose
- Hell2025 is a standalone C++ real-time game engine with an integrated level editor.
- It supports both OpenGL and Vulkan back-ends, physics via PhysX, audio, scripting (Python), and an ImGui-based editor.
- Primary use case: splitscreen roguelike/deathmatch survival horror.

a. Platform & Windowing
- GLFWIntegration (window creation, input callbacks)
- Main loop (Main.cpp → Core/Game.cpp)
b. Graphics API Layer
- OpenGL backend (src/API/OpenGL/…)
- Vulkan backend (src/API/Vulkan/…)
c. Renderer
- RenderPasses & ComputePasses (deferred G-buffer, lighting, post-processing)
- GlobalIllumination (custom compute shaders)
- Renderer utilities & Resource binding
d. Asset Management
- AssetManager (meshes, textures, animations)
- BakeQueue (asynchronous asset pre-processing)
- File importers (AssimpImporter)
e. Physics
- PhysX wrapper (src/Physics/Types + Physics_*.cpp)
- Collision, character controllers, ragdolls
f. Audio & MIDI
- Audio subsystem (WAV, MP3 playback)
- MidiFileManager & Synth
g. Game Logic & World
- Player & Entities (Enemies, Allies)
- World/Sector/Map/House managers
- Pathfinding (AStar, NavMesh)
- BVH structures (CPU/GPU)
h. Editor (ImGui front-end)
- Editor UI & tools (placement, heightmap, sectors)
- Gizmo, ObjectPlacement modules
i. Utilities & Tools
- JSON, Config, Util_* (math, file, debugging)
- Python scripts (Blender model exporters)
j. External Libraries
- GLFW, PhysX, Assimp, ImGui

- At startup: Config → BackEnd (GLFW) → choose API (OpenGL or Vulkan)
- AssetManager loads files → sends GPU resources to Renderer → shaders invoked via API
- Main loop:
- Input → Player & Editor
- Update: Game logic → Physics → World managers (BVH, pathfinding)
- Audio subsystem ← events from Game/Player
- Editor UI overlays on Render output and can modify World Managers in real time.
- Python scripts are invoked offline to prepare assets.

##### Architectural Patterns and Principles
- Manager pattern: single-responsibility managers for each resource type (AssetManager, MapManager, etc.).
- Modular back-ends: Abstract API interface with two interchangeable implementations.
- Data-driven: JSON configuration for maps, sectors, houses, fonts.
- Pub/Sub via Callbacks for cross-subsystem events (e.g., input, physics contact callbacks).
- Job queue for asset baking, allowing asynchronous pre-processing.

##### Essential Details to Capture
- How the Main Loop orchestrates Input → Update → Physics → World → Render → Audio.
- Editor’s connection into the same core loop but injecting UI events and scene changes.
- Resource-loading flow from disk (JSON, meshes, textures) through AssetManager into GPU memory.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Libraries
    subgraph "External Libraries"
        style ExternalLibs fill:#FFA500,stroke:#000
        GLFW["GLFW"]:::external
        PhysXLib["PhysX"]:::external
        AssimpLib["Assimp"]:::external
        ImGuiLib["ImGui"]:::external
    end
    click GLFW "https://github.com/livinamuk/hell2025/blob/main/src/BackEnd/GLFWIntegration.cpp"
    click PhysXLib "https://github.com/livinamuk/hell2025/blob/main/src/Physics/Physics.cpp"
    click AssimpLib "https://github.com/livinamuk/hell2025/blob/main/src/File/AssimpImporter.cpp"
    click ImGuiLib "https://github.com/livinamuk/hell2025/blob/main/src/Imgui/ImguiBackEnd.cpp"

    %% Platform & Windowing
    subgraph "Platform & Windowing"
        style PW fill:#ADD8E6,stroke:#000
        GLFWIntegration["GLFWIntegration"]:::api
        MainEntry["Main Entry\n(src/Main.cpp)"]:::coreEngine
        GameLoop["Core Game Loop\n(src/Core/Game.cpp)"]:::coreEngine
    end
    click MainEntry "https://github.com/livinamuk/hell2025/blob/main/src/Main.cpp"
    click GameLoop "https://github.com/livinamuk/hell2025/blob/main/src/Core/Game.cpp"
    click GLFWIntegration "https://github.com/livinamuk/hell2025/blob/main/src/BackEnd/GLFWIntegration.cpp"

    %% Main Loop orchestrator
    MainLoop["Main Loop"]:::coreEngine

    %% Graphics API Layer
    subgraph "Graphics API Layer"
        style API fill:#98FB98,stroke:#000
        GLBackend["OpenGL Backend"]:::api
        VKBackend["Vulkan Backend"]:::api
    end
    click GLBackend "https://github.com/livinamuk/hell2025/blob/main/src/API/OpenGL/GL_backEnd.cpp"
    click VKBackend "https://github.com/livinamuk/hell2025/blob/main/src/API/Vulkan/VK_backEnd.cpp"

    %% Renderer
    subgraph "Renderer"
        style R fill:#ADD8E6,stroke:#000
        CoreRenderer["Renderer Core\n(src/Renderer/Renderer.cpp)"]:::coreEngine
        RenderData["RenderDataManager\n(src/Renderer/RenderDataManager.cpp)"]:::coreEngine
        GI["GlobalIllumination\n(src/Renderer/GlobalIllumination.cpp)"]:::coreEngine
        OGLPasses["OpenGL RenderPasses"]:::api
        OGLCompute["OpenGL ComputePasses"]:::api
        VKRenderer["Vulkan Renderer\n(src/API/Vulkan/Renderer/vk_renderer.cpp)"]:::api
    end
    click CoreRenderer "https://github.com/livinamuk/hell2025/blob/main/src/Renderer/Renderer.cpp"
    click RenderData "https://github.com/livinamuk/hell2025/blob/main/src/Renderer/RenderDataManager.cpp"
    click GI "https://github.com/livinamuk/hell2025/blob/main/src/Renderer/GlobalIllumination.cpp"
    click OGLPasses "https://github.com/livinamuk/hell2025/tree/main/src/API/OpenGL/Renderer/RenderPasses"
    click OGLCompute "https://github.com/livinamuk/hell2025/tree/main/src/API/OpenGL/Renderer/ComputePasses"
    click VKRenderer "https://github.com/livinamuk/hell2025/blob/main/src/API/Vulkan/Renderer/vk_renderer.cpp"

    %% Asset Management
    subgraph "Asset Management"
        style AM fill:#ADD8E6,stroke:#000
        AssetMgr["AssetManager\n(src/AssetManagement/AssetManager.cpp)"]:::coreEngine
        BakeQ["BakeQueue\n(src/AssetManagement/BakeQueue.cpp)"]:::coreEngine
        Importer["AssimpImporter\n(src/File/AssimpImporter.cpp)"]:::coreEngine
    end
    click AssetMgr "https://github.com/livinamuk/hell2025/blob/main/src/AssetManagement/AssetManager.cpp"
    click BakeQ "https://github.com/livinamuk/hell2025/blob/main/src/AssetManagement/BakeQueue.cpp"
    click Importer "https://github.com/livinamuk/hell2025/blob/main/src/File/AssimpImporter.cpp"

    %% Physics
    subgraph "Physics"
        style PHY fill:#ADD8E6,stroke:#000
        PhysXWrap["PhysX Wrapper\n(src/Physics/Physics.cpp)"]:::coreEngine
        Callbacks["Physics Callbacks\n(src/Physics/Physics_callbacks.cpp)"]:::coreEngine
        Controllers["CharControllers\n(src/Physics/Physics_character_controllers.cpp)"]:::coreEngine
        Ragdoll["Ragdoll Type\n(src/Physics/Types/Ragdoll.cpp)"]:::coreEngine
    end
    click PhysXWrap "https://github.com/livinamuk/hell2025/blob/main/src/Physics/Physics.cpp"
    click Callbacks "https://github.com/livinamuk/hell2025/blob/main/src/Physics/Physics_callbacks.cpp"
    click Controllers "https://github.com/livinamuk/hell2025/blob/main/src/Physics/Physics_character_controllers.cpp"
    click Ragdoll "https://github.com/livinamuk/hell2025/blob/main/src/Physics/Types/Ragdoll.cpp"

    %% Audio & MIDI
    subgraph "Audio & MIDI"
        style AMU fill:#ADD8E6,stroke:#000
        AudioSS["Audio Subsystem\n(src/Audio/Audio.cpp)"]:::coreEngine
        MIDIMan["MidiFileManager\n(src/Audio/MidiFileManager.cpp)"]:::coreEngine
        Synth["Synth\n(src/Audio/Synth.cpp)"]:::coreEngine
    end
    click AudioSS "https://github.com/livinamuk/hell2025/blob/main/src/Audio/Audio.cpp"
    click MIDIMan "https://github.com/livinamuk/hell2025/blob/main/src/Audio/MidiFileManager.cpp"
    click Synth "https://github.com/livinamuk/hell2025/blob/main/src/Audio/Synth.cpp"

    %% Game Logic & World
    subgraph "Game Logic & World"
        style GLW fill:#ADD8E6,stroke:#000
        PlayerCtrl["Player Controller\n(src/Player/Player.cpp)"]:::coreEngine
        Entities["Entities (Enemies/Allies)"]:::coreEngine
        WorldMgrs["World Managers\n(src/World/World.cpp)"]:::coreEngine
        Pathfind["AStar Pathfinding\n(src/Pathfinding/AStar.cpp)"]:::coreEngine
        BVH["BVH Structures"]:::coreEngine
    end
    click PlayerCtrl "https://github.com/livinamuk/hell2025/blob/main/src/Player/Player.cpp"
    click WorldMgrs "https://github.com/livinamuk/hell2025/blob/main/src/World/World.cpp"
    click Pathfind "https://github.com/livinamuk/hell2025/blob/main/src/Pathfinding/AStar.cpp"

    %% Editor
    subgraph "Editor (ImGui)"
        style ED fill:#ADD8E6,stroke:#000
        EditorCore["Editor Core\n(src/Editor/Editor.cpp)"]:::coreEngine
        Tools["Editor Tools"]:::coreEngine
        Gizmo["Gizmo\n(src/Editor/Gizmo.cpp)"]:::coreEngine
        ImGuiInt["ImGui Integration\n(src/Imgui/ImguiBackEnd.cpp)"]:::coreEngine
    end
    click EditorCore "https://github.com/livinamuk/hell2025/blob/main/src/Editor/Editor.cpp"
    click Gizmo "https://github.com/livinamuk/hell2025/blob/main/src/Editor/Gizmo.cpp"
    click ImGuiInt "https://github.com/livinamuk/hell2025/blob/main/src/Imgui/ImguiBackEnd.cpp"

    %% Utilities & Tools
    subgraph "Utilities & Tools"
        style UT fill:#D3D3D3,stroke:#000
        Config["Config/JSON\n(src/Config/Config.cpp)"]:::utils
        FileIO["File I/O\n(src/File/File.cpp)"]:::utils
        Helpers["Common Helpers\n(src/Common/HellTypes.h)"]:::utils
        ImageTools["ImageTools\n(src/Tools/ImageTools.cpp)"]:::utils
        Timer["Timer\n(src/Timer.hpp)"]:::utils
        PubSub["Callbacks Pub/Sub\n(src/Callbacks/Callbacks.cpp)"]:::utils
    end
    click Config "https://github.com/livinamuk/hell2025/blob/main/src/Config/Config.cpp"
    click FileIO "https://github.com/livinamuk/hell2025/blob/main/src/File/File.cpp"
    click ImageTools "https://github.com/livinamuk/hell2025/blob/main/src/Tools/ImageTools.cpp"
    click PubSub "https://github.com/livinamuk/hell2025/blob/main/src/Callbacks/Callbacks.cpp"

    %% Core Loop and Data Flow
    Config -->|load settings| GLFWIntegration
    GLFWIntegration -->|create window/input| MainLoop
    MainLoop -->|init game| GameLoop
    MainLoop -->|choose API| GLBackend
    MainLoop -->|choose API| VKBackend

    AssetMgr -->|Mesh→GPU| CoreRenderer
    BakeQ -->|async bake| AssetMgr
    Importer --> AssetMgr

    GameLoop -->|Input events| PlayerCtrl
    GameLoop -->|Input events| EditorCore
    GameLoop -->|update| PhysXWrap
    PhysXWrap -->|collision callbacks| Callbacks
    PhysXWrap -->|controllers/ragdolls| Controllers
    Controllers --> Ragdoll
    PhysXWrap -->|BVH data| BVH
    GameLoop -->|update| WorldMgrs
    WorldMgrs -->|path queries| Pathfind
    GameLoop -->|audio events| AudioSS
    GameLoop -->|scene data| CoreRenderer

    CoreRenderer -->|draw/compute| GLBackend
    CoreRenderer -->|draw/compute| VKBackend
    GLBackend --> OGLPasses
    GLBackend --> OGLCompute
    VKBackend --> VKRenderer
    GI --> CoreRenderer

    EditorCore -->|UI overlay| CoreRenderer
    EditorCore --> WorldMgrs
    Gizmo --> EditorCore

    AudioSS --> MIDIMan
    AudioSS --> Synth

    Config -->|file formats| FileIO
    Config -->|data| Helpers
    FileIO --> ImageTools
    PubSub --> PhysXWrap

    %% Styles
    classDef coreEngine fill:#ADD8E6,stroke:#000
    classDef api fill:#98FB98,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef utils fill:#D3D3D3,stroke:#000
```
