# stcollier/samcraft architecture

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

- Interactive diagram: https://gitdiagram.com/stcollier/samcraft
- Repository: https://github.com/stcollier/samcraft

## Overview

##### Project Type and Overall Purpose
- Samcraft is a voxel engine built with OpenGL and C.
- It focuses on real-time 3D rendering (with HDR, shadows, etc.), efficient world generation (including infinite procedural worlds), physics, meshing algorithms, and a customizable client layer.
- The README and file structure show that the project covers both low-level engine functionality (graphics, physics, chunk/world management) and high-level client customization (via Lua configuration files in the client folder).

##### Main Components
a. Engine Core:
- Located in src/engine/core, this is responsible for setting up the window, camera, global engine states, shader management, and resource loading.

b. Engine Functionality / Modules:
- Engine Functionalities in src/engine/func include modules for frustum culling, meshing (greedy meshing), physics, player management, and raycasting.
- As “Game Logic / Physics” modules connected to the core.

c. Graphics (GFX) System:
- Found in src/engine/gfx, this part manages rendering pipelines: drawing block overlays, images, lights, skyboxes, sprites, text, UI elements, and postprocessing effects like HDR.
- As the Graphics Pipeline, linking the shader components (backed by the shaders in res/shaders) with textures (from res/textures) and fonts (from res/fonts).

d. Utility Modules:
- Under src/engine/util there are common utilities, thread pooling, timer functions, and other helper modules.

e. World and World Generation:
- In src/world, you have modules for block manipulation, chunk creation, world maintenance, and procedural world generation.
- This as the “World Module” that integrates with both the engine core and the physics/meshing systems to generate and render worlds dynamically.

f. Client Customization:
- The client folder contains Lua scripts and configuration files defining custom blocks such as cobblestone, dirt, grass, etc.
- This should be depicted as an external or configurable layer feeding into the engine’s block/world systems, enabling runtime customization.

g. External Libraries and Dependencies:
- The lib folder contains numerous libraries:
- cglm for vector/matrix math, used across core and graphics.
- glad – for OpenGL function loading.
- Shader dependencies, noise (osnoise) for procedural aspects, stb for image loading, and uthash for data management.

h. Resources:
- The res folder holds shaders, textures, and fonts needed for rendering.
- This as a resource pool that interacts with the graphics subsystem to load and manage visual assets.

##### Relationships and Data Flow
- That the main entry point (src/main.c) initializes the Engine Core, which in turn sets up the Game Loop.
- Interaction between the World Module and Client Customization: client-specified blocks inform the world generation and rendering modules.
- That resource files (shaders and textures) load into the Graphics Pipeline.

##### Architectural Patterns/Design Principles
- The project is modular with clearly separated concerns:
– Core initialization and management.
– Modular engine functionalities for specific tasks (physics, rendering, meshing).
– A decoupled resource pipeline.
– A client customization layer that permits extensions via Lua configurations.
- This modular design can be loosely compared to an MVC pattern where the “model” relates to the world data, “view” is the graphics/subsystems, and “controller” is provided by engine functionalities and game loop logic.
- Separation of concerns and a tight coupling between low-level systems (window, camera, shaders) and high-level gameplay systems (world, physics, custom blocks).

- Integration point for client configurations (Lua scripts and client/config.lua) and indicate how these drive customizable behavior in the engine.
- Don’t shy away from detailing inner dependencies (e.g., resources -> shaders and textures -> graphics module; engine core -> physics, frustum, and mesher modules).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Main Entry (src/main.c)"]:::main

    subgraph "Engine Core"
        EC["Engine Core"]:::engine
        EC --> EC1["Window Manager"]:::engine
        EC --> EC2["Camera"]:::engine
        EC --> EC3["Shader Manager"]:::engine
        EC --> EC4["Resource Loader"]:::engine
    end

    subgraph "Engine Functionality"
        EF["Engine Functionality"]:::func
        EF --> EF1["Frustum Culling"]:::func
        EF --> EF2["Greedy Meshing"]:::func
        EF --> EF3["Physics"]:::func
        EF --> EF4["Player Management"]:::func
        EF --> EF5["Raycasting"]:::func
    end

    subgraph "Utility Modules"
        UT["Utility Modules"]:::util
        UT --> UT1["Common Utilities"]:::util
        UT --> UT2["Thread Pool"]:::util
        UT --> UT3["Timer Functions"]:::util
        UT --> UT4["Helpers"]:::util
    end

    subgraph "World Module"
        W["World Module"]:::world
        W --> W1["Block Manipulation"]:::world
        W --> W2["Chunk Generation"]:::world
        W --> W3["World Maintenance"]:::world
        W --> W4["Procedural Generation"]:::world
    end

    subgraph "Client Customization"
        C["Client Customization"]:::client
        C --> C1["Lua Configurations"]:::client
        C --> C2["Custom Blocks"]:::client
    end

    subgraph "Graphics System"
        GFX["Graphics System"]:::gfx
        GFX --> G1["Block Overlay"]:::gfx
        GFX --> G2["Image Rendering"]:::gfx
        GFX --> G3["Lighting"]:::gfx
        GFX --> G4["Postprocessing Effects"]:::gfx
        GFX --> G5["Skybox"]:::gfx
        GFX --> G6["Sprite & Text"]:::gfx
        GFX --> G7["UI Rendering"]:::gfx
    end

    subgraph "Resources"
        RES["Resources"]:::res
        RES --> R1["Shaders"]:::res
        RES --> R2["Textures"]:::res
        RES --> R3["Fonts"]:::res
    end

    subgraph "External Libraries"
        EXT["External Libraries"]:::ext
        EXT --> X1["cglm"]:::ext
        EXT --> X2["glad"]:::ext
        EXT --> X3["noise"]:::ext
        EXT --> X4["stb"]:::ext
        EXT --> X5["uthash"]:::ext
    end

    A -->|"init"| EC
    EC -->|"initializes"| EF
    EC --> UT
    EF -->|"drives"| W
    UT -->|"supports"| EF
    C -->|"configures"| W
    EF -->|"affects"| GFX
    W -->|"supplies data"| GFX
    RES -->|"loads assets into"| GFX
    EXT -->|"provides libraries to"| EC
    EXT -->|"supports"| GFX

    classDef main fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef engine fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef func fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef util fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef world fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef client fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef gfx fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef res fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef ext fill:#98FB98,stroke:#333,stroke-width:2px;

    %% Click Events for Engine Core
    click EC "https://github.com/stcollier/samcraft/tree/main/src/engine/core"
    click EC1 "https://github.com/stcollier/samcraft/blob/main/src/engine/core/window.c"
    click EC2 "https://github.com/stcollier/samcraft/blob/main/src/engine/core/camera.c"
    click EC3 "https://github.com/stcollier/samcraft/blob/main/src/engine/core/shader.c"
    click EC4 "https://github.com/stcollier/samcraft/blob/main/src/engine/core/resources.c"

    %% Click Events for Engine Functionality
    click EF "https://github.com/stcollier/samcraft/tree/main/src/engine/func"
    click EF1 "https://github.com/stcollier/samcraft/blob/main/src/engine/func/frustum.c"
    click EF2 "https://github.com/stcollier/samcraft/blob/main/src/engine/func/mesher.c"
    click EF3 "https://github.com/stcollier/samcraft/blob/main/src/engine/func/physics.c"
    click EF4 "https://github.com/stcollier/samcraft/blob/main/src/engine/func/player.c"
    click EF5 "https://github.com/stcollier/samcraft/blob/main/src/engine/func/raycast.c"

    %% Click Events for Utility Modules
    click UT "https://github.com/stcollier/samcraft/tree/main/src/engine/util"
    click UT1 "https://github.com/stcollier/samcraft/blob/main/src/engine/util/common.h"
    click UT2 "https://github.com/stcollier/samcraft/blob/main/src/engine/util/thpool.c"
    click UT3 "https://github.com/stcollier/samcraft/blob/main/src/engine/util/timer.c"
    click UT4 "https://github.com/stcollier/samcraft/blob/main/src/engine/util/util.c"

    %% Click Events for World Module
    click W "https://github.com/stcollier/samcraft/tree/main/src/world"
    click W1 "https://github.com/stcollier/samcraft/blob/main/src/world/block.c"
    click W2 "https://github.com/stcollier/samcraft/blob/main/src/world/chunk.c"
    click W3 "https://github.com/stcollier/samcraft/blob/main/src/world/world.c"
    click W4 "https://github.com/stcollier/samcraft/blob/main/src/world/worldgen.c"

    %% Click Events for Client Customization
    click C "https://github.com/stcollier/samcraft/tree/main/client"
    click C1 "https://github.com/stcollier/samcraft/blob/main/client/config.lua"
    click C2 "https://github.com/stcollier/samcraft/tree/main/client/blocks"

    %% Click Events for Graphics System
    click GFX "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx"
    click G1 "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx/block-overlay"
    click G2 "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx/image"
    click G3 "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx/light"
    click G4 "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx/postprocess"
    click G5 "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx/skybox"
    click G6 "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx/sprite"
    click G7 "https://github.com/stcollier/samcraft/tree/main/src/engine/gfx/ui"

    %% Click Events for Resources
    click RES "https://github.com/stcollier/samcraft/tree/main/res"
    click R1 "https://github.com/stcollier/samcraft/tree/main/res/shaders"
    click R2 "https://github.com/stcollier/samcraft/tree/main/res/textures"
    click R3 "https://github.com/stcollier/samcraft/tree/main/res/fonts"

    %% Click Event for External Libraries
    click EXT "https://github.com/stcollier/samcraft/tree/main/lib"
```
