# cmpgamedevs/supercold architecture

> Architecture diagram of the GitHub repository cmpgamedevs/supercold, 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/cmpgamedevs/supercold
- Repository: https://github.com/cmpgamedevs/supercold

## Overview

##### Main Components
- Game/Application Core:
– Represents the main loop (located in source/main.cpp and source/common/application.cpp/hpp) that initializes and manages the game states and overall flow.
– Includes game states (e.g., play-state, menu-state, entity-test-state, etc.) found in the source/states directory.
- Asset & Configuration Management:
– Asset Loader: In source/common/asset-loader.*; responsible for loading shaders, models (.obj files in assets/models), textures (assets/textures), and other assets.
– Configuration Manager: Uses JSONC files located in the config/ directory to set up various tests and default parameters, including pipelines, materials, and renderer configurations.
- ECS (Entity Component System):
– Constitutes the world, entities, components (e.g., camera, movement, mesh-renderer) and systems (e.g., forward renderer, free-camera-controller) found in source/common/ecs, source/common/components, and source/common/systems.
- Rendering & Graphics Pipeline:
– Shader System: A suite of shader programs found in assets/shaders along with a shader loader in source/common/shader.
– Pipeline State, Material, and Texture Subsystems: Modules for pipeline configurations, material management, texture handling, samplers (source/common/material, source/common/texture).
– Postprocessing: Special effects managed through additional shaders in the assets/shaders/postprocess directory.
- Input Handling:
– Input management (source/common/input) that captures keyboard and mouse events, crucial for the “time only moves when you move” gameplay.
- Testing and Validation:
– A suite of test configuration files (in config/ and expected/ folders) and scripts (in scripts/) that ensure various components (entity, mesh, shader, pipeline, etc.) work as expected.

##### Relationships and Interactions
- The Application Core initializes the engine, loads configurations, and sets up the essential subsystems.
- The Asset Loader fetches models, textures, and shaders from the assets/ directory based on configuration details in the config/ files.
- The Renderer uses the Shader System to compile and manage graphical effects while applying materials and pipeline states.
- The Input Handler observes player inputs, influencing game state transitions and triggering updates in the ECS, which in turn affect rendering.
- Testing components are external but interact with nearly every piece to validate the proper configuration of entities, materials, pipelines, and shaders.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Each major subsystem (asset management, ECS, rendering, input) is isolated in its own module or folder.
- Modular Design: The project’s clear separation between shader programs, configuration settings, and core engine code allows for extensibility and easier maintenance.
- Data-Driven Design: Utilization of JSONC configuration files to drive the behavior of materials, pipelines, and test scenarios.
- ECS Pattern: Decoupling game object behavior from data to allow flexible and scalable game logic.

- Architecture’s modular design and the fact that it’s driven by external configuration, which is essential for a project that frequently tests different engine parts.
- Notes on important files and directories (e.g., source/common for engine code, assets and config directories for data), so that other engineers can trace how components are implemented.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Game/Application Core"
        LC("Main Loop"):::core
        GS("Game States"):::core
    end

    subgraph "Asset & Config Management"
        AL("Asset Loader"):::asset
        A("Assets"):::asset
        CI("Configurations"):::asset
    end

    subgraph "ECS Layer"
        ECS("ECS Framework"):::ecs
        COMP("Components"):::ecs
    end

    subgraph "Rendering Engine"
        R("Renderers"):::render
        SS("Shader System"):::render
        MM("Material Management"):::render
        TS("Texture Subsystem"):::render
    end

    IH("Input Handler"):::input
    TEST("Testing & Validation"):::testing

    %% Flow connections
    LC -->|"initializes"| AL
    AL -->|"loads"| A
    AL -->|"reads"| CI
    AL -->|"provisions assets to"| ECS
    AL -->|"provides shaders to"| SS
    ECS -->|"updates objects"| R
    IH <-->|"input_events"| ECS

    %% Testing validations
    TEST -->|"validates"| LC
    TEST -->|"validates"| AL
    TEST -->|"validates"| ECS
    TEST -->|"validates"| R

    %% Class definitions for styling
    classDef core fill:#f8b500,stroke:#333,stroke-width:2px;
    classDef asset fill:#a1d490,stroke:#333,stroke-width:2px;
    classDef ecs fill:#f08080,stroke:#333,stroke-width:2px;
    classDef render fill:#87ceeb,stroke:#333,stroke-width:2px;
    classDef input fill:#e0bbff,stroke:#333,stroke-width:2px;
    classDef testing fill:#c0c0c0,stroke:#333,stroke-width:2px;

click LC "https://github.com/cmpgamedevs/supercold/blob/main/source/main.cpp"
click LC "https://github.com/cmpgamedevs/supercold/blob/main/source/common/application.cpp"
click LC "https://github.com/cmpgamedevs/supercold/blob/main/source/common/application.hpp"
click GS "https://github.com/cmpgamedevs/supercold/tree/main/source/states"

click AL "https://github.com/cmpgamedevs/supercold/blob/main/source/common/asset-loader.cpp"
click AL "https://github.com/cmpgamedevs/supercold/blob/main/source/common/asset-loader.hpp"
click A "https://github.com/cmpgamedevs/supercold/tree/main/assets"
click CI "https://github.com/cmpgamedevs/supercold/tree/main/config"

click ECS "https://github.com/cmpgamedevs/supercold/tree/main/source/common/ecs"
click COMP "https://github.com/cmpgamedevs/supercold/tree/main/source/common/components"

click R "https://github.com/cmpgamedevs/supercold/blob/main/source/common/systems/forward-renderer.cpp"
click R "https://github.com/cmpgamedevs/supercold/blob/main/source/common/systems/forward-renderer.hpp"
click SS "https://github.com/cmpgamedevs/supercold/tree/main/source/common/shader"
click SS "https://github.com/cmpgamedevs/supercold/tree/main/assets/shaders"
click MM "https://github.com/cmpgamedevs/supercold/tree/main/source/common/material"
click TS "https://github.com/cmpgamedevs/supercold/tree/main/source/common/texture"

click IH "https://github.com/cmpgamedevs/supercold/tree/main/source/common/input"

click TEST "https://github.com/cmpgamedevs/supercold/tree/main/config"
click TEST "https://github.com/cmpgamedevs/supercold/tree/main/expected"
click TEST "https://github.com/cmpgamedevs/supercold/tree/main/scripts"
```
