# grysha11/cub3d architecture

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

- Interactive diagram: https://gitdiagram.com/grysha11/cub3d
- Repository: https://github.com/grysha11/cub3d

## Overview

##### Project Type and Purpose
- This is a full-fledged 3D game application that uses the raycasting technique to simulate a 3D environment.
- The README indicates that it relies on MinilibX for window management and graphics, while the file tree points out dependencies on libft and get_next_line (gnl) for utility functions.
- Its core functionality deals with parsing map files (from the maps directory), initializing game state, raycasting for rendering, and handling user inputs/movement.

##### Analyzing the File Structure
- Top-Level Files: The Makefile and README are there for building and documentation.
- inc Directory: Contains various image assets in XPM format and subdirectories for:
- gnl: The get_next_line implementation.
- libft: A set of basic utility functions.
- minilibx: The graphics library used to open windows, handle input, and render images.
- Various .xpm files used as textures for game assets (walls, sprites, etc.).
- maps Directory: Organized into ‘good’ (valid map files) and ‘wrong’ (likely erroneous ones) folders that supply level data.
- src Directory: Contains the heart of the game logic split into:
- cub3d.h: Central header file defining game structures and declarations.
- execution: Modules for game initialization, drawing on the screen, raycasting computations, movement, and handling MLX interactions.
- main.c: Acts as the entry point to integrate initialization, parsing, and game loop execution.

##### Defining the Main Components
a. Game Initialization & Main Loop:
- Represented by src/main.c and src/execution/init.c.
- It kickstarts parsing, resource loading (textures from inc and maps), and initializes the game window.

b. Parsing & Resource Loading:
- Located in src/parse and related source files.

c. Raycasting Engine:
- Found within src/execution/raycast.c and raycast_helper.c.
- Performs the core 3D projection calculations, determining what portions of the map are rendered.

d. Rendering & MLX Integration:
- Interacts directly with the MiniLibX library to render images on a window, using the textures and calculations provided by the raycasting module.

e. Utility Libraries:
- libft (inc/libft) and get_next_line (inc/gnl) modules are helper libraries that provide common functions and file-reading utilities.

f. Assets and Textures:
- The inc directory holds all the xpm images used for textures, sprites, and possibly UI elements.

g. External Dependencies:
- The MinilibX (inc/minilibx) and X11 components for handling graphics and input on Linux.

##### Relationships and Interactions
- The application flow begins in main.c where the game is initialized.
- The Parser module (src/parse) reads and validates map files, applying the configuration to game data structures.
- The Execution module takes these structures and passes them to the raycasting engine, which uses algorithms to compute visible scenes.
- Utility libraries (libft and gnl) support file I/O operations and common functions across the project.
- Assets (XPM images) are loaded as textures to be rendered during the game loop.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Parsing, game logic, rendering, user input, and utility functions are modularized in independent directories.
- Procedural Design: The program is structured using C, employing a modular design rather than an object-oriented or microservices architecture.
- Layered Architecture: There’s a clear dependency chain—from input (maps/assets) to processing (parsing, raycasting) to output (rendering via MLX).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Game Initialization & Main Loop
    subgraph "Game Initialization & Main Loop"
        M["Main (src/main.c)"]:::core
        I["Initialization (src/execution/init.c)"]:::core
    end

    %% Map Parsing & Resource Loading
    subgraph "Map Parsing & Resource Loading"
        P["Parser (src/parse)"]:::core
        MF["Map Files (maps)"]:::assets
    end

    %% Raycasting Engine
    subgraph "Raycasting Engine"
        R["Raycasting (src/execution/raycast.c)"]:::core
        RH["Raycast Helper (src/execution/raycast_helper.c)"]:::core
    end

    %% Rendering & Graphics (MLX)
    subgraph "Rendering & Graphics (MLX)"
        D["Renderer (src/execution/draw.c)"]:::core
        MX["MLX Integration (src/execution/mlx.c)"]:::core
        MLX["MiniLibX Library (inc/minilibx)"]:::external
    end

    %% Utility Libraries
    subgraph "Utility Libraries"
        LF["Libft (inc/libft)"]:::utils
        GNL["GNL (inc/gnl)"]:::utils
    end

    %% Assets & Textures
    subgraph "Assets & Textures"
        TA["Texture Assets (inc)"]:::assets
    end

    %% Data Flow Arrows
    M -->|"starts"| P
    I -->|"init"| P
    MF -->|"supplies"| P
    TA -->|"loaded_by"| P
    P -->|"parses_to"| R
    RH -->|"assists"| R
    R -->|"computes"| D
    MX -->|"integrates"| D
    MLX -->|"provides"| MX

    %% Utility dependencies
    LF -->|"supports"| P
    LF -->|"supports"| R
    LF -->|"supports"| D
    GNL -->|"supports"| P
    GNL -->|"supports"| R
    GNL -->|"supports"| D
    TA -->|"used_by"| D

    %% Click Events
    click M "https://github.com/grysha11/cub3d/blob/main/src/main.c"
    click I "https://github.com/grysha11/cub3d/blob/main/src/execution/init.c"
    click P "https://github.com/grysha11/cub3d/tree/main/src/parse"
    click MF "https://github.com/grysha11/cub3d/tree/main/maps"
    click R "https://github.com/grysha11/cub3d/blob/main/src/execution/raycast.c"
    click RH "https://github.com/grysha11/cub3d/blob/main/src/execution/raycast_helper.c"
    click D "https://github.com/grysha11/cub3d/blob/main/src/execution/draw.c"
    click MX "https://github.com/grysha11/cub3d/blob/main/src/execution/mlx.c"
    click MLX "https://github.com/grysha11/cub3d/tree/main/inc/minilibx"
    click LF "https://github.com/grysha11/cub3d/tree/main/inc/libft"
    click GNL "https://github.com/grysha11/cub3d/tree/main/inc/gnl"
    click TA "https://github.com/grysha11/cub3d/blob/main/inc/HEARTSSV.xpm"

    %% Styles
    classDef core fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef utils fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef assets fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
