# thecherno/sparky architecture

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

- Interactive diagram: https://gitdiagram.com/thecherno/sparky
- Repository: https://github.com/thecherno/sparky

## Overview

##### Project Type and Purpose
- Sparky is a C++‐based, cross‐platform high‐performance game engine.
- It includes:
- Sparky-core: the engine runtime (subsystems: windowing, input, graphics, audio, VFS, entity-component, math, debug).
- Demo apps:
– Sandbox (native C++)
– SandboxCS (C#/.NET)
- SparkyCLI: a console‐mode tool for experiments or asset inspection.
- Tools/SPMBuild: a standalone content‐packaging utility.
- Dependencies: physics (Box2D), image loading (FreeImage), font (FreeType), audio (Gorilla-audio/OpenAL, libogg, libvorbis), OpenGL/DirectX loaders (GLEW), etc.

A. Applications (Sandbox, SandboxCS, SparkyCLI)
B. Engine Core Library (Sparky-core)
C. Third-Party Libraries & Asset Pipeline
D. Platform Abstraction & OS/Hardware

##### Main Components & Their Relationships
- Applications
– Depend on Sparky-core API.
– Provide entry point, game logic, test scenes, UI.
- Sparky-core Subsystems (each as a distinct block):
1. System & Platform: windowing (Window), file I/O (VFS), memory, threading, timers.
2. Input: keyboard/mouse events → EventDispatcher/EventListeners.
3. Graphics:
– API Abstraction Layer (Context, Buffer, Texture, Framebuffer…)
– Renderer (ForwardRenderer, DeferredRenderer, GBuffer, RenderCommand)
– Shader Management (ShaderFactory, ShaderManager)
– UI & Debug over‐lays (DebugRenderer, UI widgets)
4. Audio: SoundManager → Gorilla-audio/OpenAL → codecs (libogg/libvorbis).
5. Entity-Component System: Scene, Entity, Components (Transform, Mesh, Sprite…).
6. Math & Utilities: vectors/matrices, AABB, file utilities, image loaders.
- Third-Party & Asset Pipeline
– Images/fonts: FreeImage, FreeType
– Physics: Box2D (optional integration)
– Audio codecs: libogg, libvorbis
– Model loaders: OBJModel, PBR materials
– Tools: SPMBuild for packaging .spm scenes & assets
- Platform Backends (selected at compile/run):
– OpenGL (sp/platform/opengl + GLEW)
– DirectX (sp/platform/directx)
– POSIX/Win32 glue for window, input, file system

##### Data Flows & Interactions
- Application → calls Engine Core to initialize subsystems
- Engine Core → Platform layer to create window/context & dispatch OS events
- Input events → Engine Core → Entity/Component or App layer via EventDispatcher
- Graphics: Scene data → Renderer → Graphics API → GPU
- Audio: Sound requests → SoundManager → OpenAL → Audio hardware
- Asset loading: VFS → FreeImage/FreeType → memory → engine resources
- Packaging tool: SPMBuild reads raw assets → writes runtime package (.spm)

##### Architectural Patterns & Principles
- Layered architecture: clear separation of application, engine, third-party, and platform layers.
- Facade: high-level Sparky API hides platform/third-party details.
- ECS pattern: decouples data (components) from behavior (systems).
- Strategy pattern: pluggable platform backends (OpenGL vs. DirectX).
- Resource‐manager singletons for textures, shaders, sounds.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Swimlanes
    subgraph "Applications" 
        direction TB
        Sandbox["Sandbox (C++)"]:::app
        SandboxCS["SandboxCS (C#)"]:::app
        SparkyCLI["SparkyCLI (CLI Tool)"]:::app
    end

    subgraph "Engine Core Library" 
        direction TB
        subgraph "Application Subsystem"
            direction TB
            Window["Window"]:::engine
            Input["Input"]:::engine
            EventSystem["EventDispatcher/EventListeners"]:::engine
        end
        subgraph "Graphics Subsystem"
            direction TB
            APIAbstraction["API Abstraction Layer"]:::engine
            Renderer["Renderer (Forward/Deferred)"]:::engine
            ShaderMgmt["ShaderFactory/ShaderManager"]:::engine
            UIDebug["UI & Debug Overlays"]:::engine
        end
        subgraph "Audio Subsystem"
            direction TB
            SoundMgr["SoundManager"]:::engine
        end
        subgraph "Entity-Component System"
            direction TB
            ECS["Scene/Entity/Components"]:::engine
        end
        subgraph "Math & Utilities"
            direction TB
            MathLib["Math Library"]:::engine
            VFS["VFS & File/Image Utils"]:::engine
        end
    end

    subgraph "Third-Party Libraries & Asset Pipeline"
        direction TB
        Box2D["Box2D (Physics)"]:::third
        FreeImage["FreeImage"]:::third
        FreeType["FreeType"]:::third
        GorillaAudio["Gorilla-audio"]:::third
        LibOgg["libogg/libvorbis"]:::third
        GLEW["GLEW"]:::third
        OpenAL["OpenAL"]:::third
        SPMBuild["SPMBuild Tool"]:::third
    end

    subgraph "Platform Abstraction & OS/Hardware"
        direction TB
        OpenGL["OpenGL Backend"]:::platform
        DirectX["DirectX Backend"]:::platform
        POSIX["POSIX Glue"]:::platform
        Win32["Win32 Glue"]:::platform
    end

    %% Connections
    Sandbox -->|"uses"| Window
    SandboxCS -->|"uses"| Window
    SparkyCLI -->|"uses"| VFS
    Window -->|"dispatches events to"| EventSystem
    Input -->|"sends events to"| EventSystem
    EventSystem -->|"updates"| ECS
    ECS -->|"provides scene data to"| Renderer
    APIAbstraction -->|"calls"| OpenGL
    APIAbstraction -->|"calls"| DirectX
    Renderer -->|"uses shaders from"| ShaderMgmt
    UIDebug -->|"renders overlays via"| Renderer
    SoundMgr -->|"calls"| OpenAL
    OpenAL -->|"depends on"| LibOgg
    VFS -->|"loads images from"| FreeImage
    VFS -->|"loads fonts from"| FreeType
    Box2D -->|"integrates optional physics"| ECS
    SPMBuild -->|"packages assets for"| VFS

    %% Click Events - Applications
    click Sandbox "https://github.com/thecherno/sparky/tree/master/Sandbox/"
    click SandboxCS "https://github.com/thecherno/sparky/tree/master/SandboxCS/"
    click SparkyCLI "https://github.com/thecherno/sparky/tree/master/SparkyCLI/"

    %% Click Events - Engine Core
    click Window "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/app/Window.cpp"
    click Input "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/app/Input.cpp"
    click EventSystem "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/events/"
    click APIAbstraction "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/graphics/API/"
    click Renderer "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/graphics/ForwardRenderer.cpp"
    click Renderer "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/graphics/DeferredRenderer.cpp"
    click ShaderMgmt "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/graphics/shaders/ShaderFactory.cpp"
    click ShaderMgmt "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/graphics/shaders/ShaderManager.cpp"
    click UIDebug "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/debug/"
    click UIDebug "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/graphics/ui/"
    click SoundMgr "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/audio/SoundManager.cpp"
    click ECS "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/entity/"
    click MathLib "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/maths/"
    click VFS "https://github.com/thecherno/sparky/blob/master/Sparky-core/src/sp/system/VFS.cpp"
    click VFS "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/utils/"

    %% Click Events - Platform
    click OpenGL "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/platform/opengl/"
    click DirectX "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/platform/directx/"
    click POSIX "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/platform/posix/"
    click Win32 "https://github.com/thecherno/sparky/tree/master/Sparky-core/src/sp/platform/windows/"

    %% Click Events - Third-Party
    click Box2D "https://github.com/thecherno/sparky/tree/master/Dependencies/Box2D/"
    click FreeImage "https://github.com/thecherno/sparky/tree/master/Dependencies/FreeImage/"
    click FreeType "https://github.com/thecherno/sparky/tree/master/Dependencies/FreeType/"
    click GorillaAudio "https://github.com/thecherno/sparky/tree/master/Dependencies/gorilla-audio/"
    click LibOgg "https://github.com/thecherno/sparky/tree/master/Dependencies/libogg/"
    click GLEW "https://github.com/thecherno/sparky/tree/master/Dependencies/GLEW/"
    click OpenAL "https://github.com/thecherno/sparky/tree/master/Dependencies/OpenAL/"
    click SPMBuild "https://github.com/thecherno/sparky/tree/master/Tools/SPMBuild/"

    %% Styles
    classDef app fill:#FFA500,stroke:#333,stroke-width:1px
    classDef engine fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef third fill:#90EE90,stroke:#333,stroke-width:1px
    classDef platform fill:#D3D3D3,stroke:#333,stroke-width:1px
```
