# eqmg/acid architecture

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

- Interactive diagram: https://gitdiagram.com/eqmg/acid
- Repository: https://github.com/eqmg/acid

## Overview

##### Project type and purpose
- Acid is a cross-platform, modular C++17 game engine. It provides a rendering pipeline (Vulkan + MoltenVK), physics (Bullet3), audio (OpenAL), networking, resource management, entity-component system, and a suite of subsystems (shaders, post-processing, UI, particles, animations, file I/O, etc.).

##### File-structure highlights
- Top level:
- CMake & configuration files for build generation on all platforms.
- External/ : bundled third-party libraries (GLFW, FreeType, stb, FastNoise, Bullet3, glslang, etc.).
- Sources/ : core engine code organized by subsystem (Animations, Audio, Bitmaps, Graphics, Guis, Inputs, Maths, Meshes, Models, Network, Physics, Post, Resources, Scenes, Shaders, Skyboxes, etc.).
- Resources/ : art assets (models, textures, shaders, fonts, sounds).
- Tests/ : multiple sample/test applications and unit tests demonstrating and verifying engine subsystems.

##### Architectural insights from README
- Engine is highly modular: each major feature is its own C++ namespace/folder.
- Uses an Entity-Component System (Sources/Scenes).
- Central rendering loop manages subrenders (GuisSubrender, MeshesSubrender, Post-processing, ShadowsSubrender, etc.).
- Resource loading and serialization (JSON, XML) feed subsystems with assets.
- Subsystems communicate through event callbacks, thread-safe command buffers, and shared resources.

- Application / Engine Core – the entry point, main loop, module manager.
- Scene & Entity-Component System – manages entities, components, prefabs, systems.
- Resource Manager – file search, asset serialization (JSON, XML), caching.
- Graphics Subsystem – Vulkan instance & devices, swapchain, renderpasses, pipelines.
- Shader Compiler / Reflection – on-the-fly GLSL→SPIR-V.
- Rendering Pipeline – subrenders (Deferred, Gizmos, Guis, Particles, Shadows, Post).
- Physics Subsystem – Bullet3 integration (colliders, rigidbodies, forces).
- Audio Subsystem – OpenAL backend, sound buffers (flac, mp3, ogg, opus, wave).
- Input Subsystem – keyboard, mouse, joystick, input schemes, axes/buttons.
- UI Subsystem – constraints, layout, MSDF font rendering, drivers.
- Network Subsystem – HTTP, FTP, TCP, UDP.
- Utility Modules – Maths, Timers, Logging, ThreadPool, Events/Delegates.
- External Dependencies – Vulkan SDK, MoltenVK, OpenAL SDK, Python (build scripts).

b. Relationships and data flows
- Application Core invokes Resource Manager to load assets → assets feed Graphics, Audio, Models, etc.
- Input Subsystem generates events → Scene or UI Systems consume to modify entities.
- Physics Subsystem updates collision & transform data → Scene updates entity components.
- Audio Subsystem plays sound buffers loaded by Resource Manager, triggered by game logic or physics.
- Network Subsystem requests/responses drive game state or asset downloads.
- Subrender stages communicate: Shadows → Deferred pass → Post-processing → GUI/UI.

c. Architectural patterns
- Modular singletons (e.g., Window::Get(), Timers::Get()).
- Entity-Component System for decoupling data & behavior.
- Command buffers + thread safety for multi-threaded rendering.
- Event/Delegate pattern for loosely-coupled callbacks.
- Layered rendering (deferred, compositing, post filters).
- Plugin-like External/ folder for third-party code.

d. Call out key technologies
- Vulkan + MoltenVK for cross-platform GPU API.
- Bullet3 for physics.
- OpenAL-Soft for audio.
- glslang for shader compilation.
- CMake for build & dependency management.
- JSON/XML (via custom Files/Json, Files/Xml) for serialization.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Engine Core"
        EngineCore["Application / Engine Core"]:::core
    end

    subgraph "Scene & ECS"
        SceneECS["Scene & Entity-Component System"]:::ecs
    end

    subgraph "Resource Management"
        ResourceManager["Resource Manager"]:::resource
        FileIO["File I/O & Serialization"]:::resource
    end

    subgraph "Graphics Subsystem"
        Graphics["Graphics Subsystem"]:::graphics
        subgraph "Shader Compiler / Reflection"
            ShaderCompiler["Shader Compiler / Reflection"]:::graphics
        end
    end

    subgraph "Rendering Pipeline"
        subgraph "Subrenders"
            ShadowsSubrender["Shadows Subrender"]:::graphics
            DeferredSubrender["Deferred Subrender"]:::graphics
            PostProcessing["Post-processing"]:::graphics
            GizmosSubrender["Gizmos Subrender"]:::graphics
            MeshesSubrender["Meshes Subrender"]:::graphics
            FontsSubrender["Fonts Subrender"]:::graphics
            ParticlesSubrender["Particles Subrender"]:::graphics
            GuisSubrender["UI/Guis Subrender"]:::graphics
        end
    end

    subgraph "Physics Subsystem"
        Physics["Physics Subsystem"]:::physics
    end

    subgraph "Audio Subsystem"
        Audio["Audio Subsystem"]:::audio
    end

    subgraph "Input Subsystem"
        Input["Input Subsystem"]:::input
    end

    subgraph "UI Subsystem"
        UI["UI Subsystem"]:::ui
    end

    subgraph "Network Subsystem"
        Network["Network Subsystem"]:::network
    end

    subgraph "Utility Modules"
        Maths["Maths"]:::util
        Timers["Timers"]:::util
        Logging["Logging"]:::util
        ThreadPool["ThreadPool & Events"]:::util
    end

    subgraph "External Dependencies"
        External["Third-Party Libraries"]:::external
    end

    subgraph "Build & Configuration"
        BuildConfig["CMake & Build Config"]:::config
    end

    subgraph "Tests & Samples"
        Tests["Tests & Samples"]:::test
    end

    %% Relationships
    EngineCore -->|initializes| ResourceManager
    EngineCore -->|initializes| Graphics
    EngineCore -->|initializes| Physics
    EngineCore -->|initializes| Audio
    EngineCore -->|initializes| Input
    EngineCore -->|initializes| UI
    EngineCore -->|initializes| Network
    EngineCore -->|initializes| ThreadPool
    EngineCore -->|runs main loop| SceneECS
    EngineCore --> Tests
    BuildConfig --> EngineCore
    BuildConfig --> Graphics
    BuildConfig --> ShaderCompiler

    ResourceManager -->|loads assets| Graphics
    ResourceManager -->|loads assets| Audio
    ResourceManager -->|loads assets| Physics
    ResourceManager --> FileIO

    SceneECS -->|draw calls| RenderingPipeline
    Input -->|events| SceneECS
    Input -->|events| UI
    Physics -->|updates transforms| SceneECS
    Audio -->|plays sounds| SceneECS

    RenderingPipeline --> ShadowsSubrender --> DeferredSubrender --> PostProcessing --> GuisSubrender

    ShaderCompiler --> Graphics

    External --> Graphics
    External --> Physics
    External --> Audio
    External --> ShaderCompiler

    %% Click Events
    click EngineCore "https://github.com/eqmg/acid/tree/master/Sources/Engine"
    click SceneECS "https://github.com/eqmg/acid/tree/master/Sources/Scenes"
    click ResourceManager "https://github.com/eqmg/acid/tree/master/Sources/Resources"
    click FileIO "https://github.com/eqmg/acid/tree/master/Sources/Files"
    click Graphics "https://github.com/eqmg/acid/tree/master/Sources/Graphics"
    click ShaderCompiler "https://github.com/eqmg/acid/tree/master/Sources/Graphics/Pipelines"
    click DeferredSubrender "https://github.com/eqmg/acid/blob/master/Sources/Post/Deferred/DeferredSubrender.cpp/.hpp"
    click PostProcessing "https://github.com/eqmg/acid/tree/master/Sources/Post/Filters"
    click ShadowsSubrender "https://github.com/eqmg/acid/blob/master/Sources/Shadows/ShadowsSubrender.cpp/.hpp"
    click GizmosSubrender "https://github.com/eqmg/acid/blob/master/Sources/Gizmos/GizmosSubrender.cpp/.hpp"
    click MeshesSubrender "https://github.com/eqmg/acid/blob/master/Sources/Meshes/MeshesSubrender.cpp/.hpp"
    click FontsSubrender "https://github.com/eqmg/acid/blob/master/Sources/Fonts/FontsSubrender.cpp/.hpp"
    click ParticlesSubrender "https://github.com/eqmg/acid/blob/master/Sources/Particles/ParticlesSubrender.cpp/.hpp"
    click GuisSubrender "https://github.com/eqmg/acid/blob/master/Sources/Guis/GuisSubrender.cpp/.hpp"
    click Physics "https://github.com/eqmg/acid/tree/master/Sources/Physics"
    click Audio "https://github.com/eqmg/acid/tree/master/Sources/Audio"
    click Input "https://github.com/eqmg/acid/tree/master/Sources/Inputs"
    click UI "https://github.com/eqmg/acid/tree/master/Sources/Uis"
    click Network "https://github.com/eqmg/acid/tree/master/Sources/Network"
    click Maths "https://github.com/eqmg/acid/tree/master/Sources/Maths"
    click Timers "https://github.com/eqmg/acid/tree/master/Sources/Timers"
    click Logging "https://github.com/eqmg/acid/blob/master/Sources/Engine/Log.cpp/.hpp"
    click ThreadPool "https://github.com/eqmg/acid/tree/master/Sources/Utils"
    click External "https://github.com/eqmg/acid/tree/master/External"
    click BuildConfig "https://github.com/eqmg/acid/tree/master/CMake/"
    click Tests "https://github.com/eqmg/acid/tree/master/Tests/"

    %% Styles
    classDef core fill:#FFD27F,stroke:#CC8E35,stroke-width:2px
    classDef ecs fill:#F3C3FF,stroke:#B47ECC,stroke-width:2px
    classDef resource fill:#C3E6FF,stroke:#6BAEDD,stroke-width:2px
    classDef graphics fill:#A0DFFA,stroke:#4AAAC0,stroke-width:2px
    classDef physics fill:#C0F8C0,stroke:#57C059,stroke-width:2px
    classDef audio fill:#FFE4A3,stroke:#D69E00,stroke-width:2px
    classDef input fill:#E8E8E8,stroke:#A0A0A0,stroke-width:2px
    classDef ui fill:#FFD6E8,stroke:#D46BA3,stroke-width:2px
    classDef network fill:#E0D6FF,stroke:#8C6AEC,stroke-width:2px
    classDef util fill:#F0F0F0,stroke:#A0A0A0,stroke-width:2px
    classDef external fill:#DADADA,stroke:#888888,stroke-width:2px,stroke-dasharray: 5 5
    classDef config fill:#E8F4FF,stroke:#7AAEFF,stroke-width:2px
    classDef test fill:#FFE8E8,stroke:#FF7F7F,stroke-width:2px
```
