# szymonsuchanek/cub3d architecture

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

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

## Overview

##### Project type and purpose
- This is a standalone C-based 3D ray-casting engine / demo (often called “cub3D” in 42 school parlance).
- It reads a “.cub” map file, loads texture assets, runs a main loop that handles user input, computes ray intersections (math), renders walls/floor/ceiling, and displays frames via the MiniLibX (mlx) library.

##### File structure
- Top-level folders:
– src/        ← core engine code, subdivided into modules
– includes/   ← headers for each module
– lib/        ← two internal libraries (libft and garbage_collector)
– textures/   ← image assets (XPM files)
- Key subdirectories in src/:
– init/            ← startup: parse arguments, load map, init player & textures
– map/             ← map validation & “minimap” support
– controls/        ← keyboard & mouse event handlers, movement & rotation
– math/            ← ray-casting utilities, vector math
– rendering/       ← drawing routines: walls, floor/ceiling, sprites/monsters
– display_server/  ← safe wrappers around mlx (window management, hooks)
– utils/           ← miscellaneous helpers (timing, generic utils)
- Build files:
– Makefile at top level and inside each lib/ subfolder.

##### (empty) README
- No additional architectural guidance here, so structure must be inferred from filenames and directory organization.

##### Main components and their relationships

A. Core Engine (src/main.c)
– Orchestrates startup, game loop, and shutdown.

B. Init Module (src/init/)
– Reads the .cub map (42_map.cub or map.cub).
– Loads textures from textures/ folder.
– Initializes player state, screen resolution, texture buffers.

C. Map Module (src/map/)
– Validates map borders & player start.
– Builds internal map representation (2D grid).

D. Controls Module (src/controls/)
– Registers keyboard & mouse callbacks via display_server.
– Produces player movement/rotation commands.

E. Math (Ray-casting) Module (src/math/, src/raycaster_utils.c)
– Calculates ray intersections per screen column.
– Outputs distance/depth and texture coordinates.

F. Rendering Module (src/rendering/)
– Builds each frame in a pixel buffer.

G. Display Server (src/display_server/)
– Wraps MiniLibX calls to create windows, handle event loop, blit pixel buffer.

H. Asset Store (textures/)
– Contains wall, floor, ceiling, compass, animation frames.
– Used by Init Module and Rendering Module.

I. Utility Libraries (lib/lib_ft and lib/garbage_collector/)
– lib_ft: string, memory, list, I/O helpers.
– garbage_collector: automatic memory management.
– Shown as external shared libraries that all modules link against.

##### Architectural patterns & design principles
- Modular separation: each concern (init, map validation, input, math, rendering, display) lives in its own folder.
- Single responsibility: e.g. display_server only knows how to talk to mlx, controls only knows how to interpret events.
- Data flow linearity in main loop: Input → Update → Raycast → Render → Output.
- Externalization of assets (textures/) and config (map.cub) as separate data stores.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Engine
    subgraph "Core"
        Core["Core Engine"]:::core
    end

    %% Modules
    subgraph "Modules"
        Init["Init Module"]:::core
        Map["Map Module"]:::core
        Controls["Controls Module"]:::core
        Math["Ray-casting (Math) Module"]:::core
        Rendering["Rendering Module"]:::core
        Display["Display Server"]:::core
    end

    %% Data Stores
    subgraph "Data Stores"
        MapFile[".cub Map File"]:::data
        Textures["Asset Store (Textures)"]:::data
    end

    %% External Libraries
    subgraph "External Libraries"
        MiniLibX["MiniLibX"]:::ext
        LibFT["Utility Library: lib_ft"]:::ext
        GC["Utility Library: garbage_collector"]:::ext
    end

    %% Connections
    Core -->|"calls init"| Init
    Init -->|"loads map"| MapFile
    MapFile -->|"validated by"| Map
    Init -->|"loads textures"| Textures
    Init -->|"inits renderer"| Rendering

    Core -->|"main loop"| Controls
    Controls -->|"movement data"| Math
    Math -->|"ray data"| Rendering
    Rendering -->|"pixel buffer"| Display
    Display -->|"event loop tick"| Core

    Rendering -->|"uses textures"| Textures

    %% All modules link to utility libs
    Init -->|links| LibFT
    Init -->|links| GC
    Map -->|links| LibFT
    Map -->|links| GC
    Controls -->|links| LibFT
    Controls -->|links| GC
    Math -->|links| LibFT
    Math -->|links| GC
    Rendering -->|links| LibFT
    Rendering -->|links| GC
    Display -->|links| LibFT
    Display -->|links| GC

    Display -->|"wraps"| MiniLibX

    %% Click Events
    click Core "https://github.com/szymonsuchanek/cub3d/blob/main/src/main.c"
    click Init "https://github.com/szymonsuchanek/cub3d/tree/main/src/init/"
    click Map "https://github.com/szymonsuchanek/cub3d/tree/main/src/map/"
    click Controls "https://github.com/szymonsuchanek/cub3d/tree/main/src/controls/"
    click Math "https://github.com/szymonsuchanek/cub3d/blob/main/src/math/math_utils.c"
    click Math "https://github.com/szymonsuchanek/cub3d/blob/main/src/raycaster_utils.c"
    click Rendering "https://github.com/szymonsuchanek/cub3d/tree/main/src/rendering/"
    click Display "https://github.com/szymonsuchanek/cub3d/tree/main/src/display_server/"
    click Textures "https://github.com/szymonsuchanek/cub3d/tree/main/textures/"
    click LibFT "https://github.com/szymonsuchanek/cub3d/tree/main/lib/lib_ft/"
    click GC "https://github.com/szymonsuchanek/cub3d/tree/main/lib/garbage_collector/"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1976d2,color:#0d47a1;
    classDef data fill:#c8e6c9,stroke:#388e3c,color:#1b5e20,shape:cylinder;
    classDef ext fill:#fff9c4,stroke:#fbc02d,color:#f57f17,shape:parallelogram;
```
