# glagan/42-cub3d architecture

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

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

## Overview

##### Project type and purpose
- This is a single‐player raycasting “game engine” project in C, inspired by Wolfenstein 3D.

##### File structure
- Top‐level C modules:
- main.c, cub3d.c, game.c – orchestrate initialization, game loop, and state updates
- bmp.c – BMP screenshot writer
- engine/: core raycasting and rendering logic (camera, raycast, draw_wall/floor/sky, sprites, UI, shadow, crosshair, shortcuts)
- gnl/: get_next_line helper for file I/O
- mlx/: wrapper around the MiniLibX graphics/input API (window, image, event hook, string‐drawing)
- textures/: .xpm image assets used by engine
- utils/: generic C helpers (string, memory, conversions, position struct)
- maps/: sample .cub files for testing

##### README insights
- Describes controls, features (shadows, crosshair, sprites), and dependencies on MiniLibX and BMP export.

##### Main components
a. Components
2. Core Game Loop (main.c, cub3d.c, game.c) – initializes subsystems, enters loop: process input, update, render
3. Input Handler (engine/shortcuts.c + mlx event hooks) – translates keyboard events (WASD, QE, I/O/L toggles, ESC) into game actions
4. Raycasting & Rendering Engine (engine/*)
– Camera & view/projection (camera.c, tables.c)
– Raycasting per pixel (raycast.c)
– Sprite management (sprite.c, sprite_utils.c)
– UI overlay (crosshair.c, ui.c, minimap in quest.c)
5. Graphics Abstraction Layer (mlx/*) – creates window, handles events, manages frame buffer (mlx_image.swift/C), draws pixels/text
6. Asset Store (textures/*) – XPM files used by rendering engine
7. Utility Library (utils/* & gnl/*) – low‐level helpers for strings, memory, file reading
8. BMP Exporter (bmp.c) – writes current frame buffer to BMP on demand

b. Relationships & Data Flow
- Core Loop → Input Handler: registers callbacks, polls events via MLX
- Core Loop → Rendering Engine: passes camera state, map data, asset pointers → produces frame buffer
- Rendering Engine → Graphics Layer (MLX): pushes frame buffer each tick, draws UI overlays
- User via MLX → Input Handler → Core Loop: changes camera position/orientation or toggles UI options
- Core Loop → BMP Exporter: when user requests screenshot
- Utility Library used by nearly every component for common operations

c. Architectural patterns & design principles
- Modular separation by responsibility (parsing, game logic, rendering, I/O, utilities)
- Single‐threaded game loop
- Layered architecture: Core → Engine → Graphics API
- Data‐driven design: map files and textures external to code
- Use of callback/event model for input via MLX

d. Key technologies/libraries
- C language, POSIX file I/O
- MiniLibX (MLX) for windowing, events, image buffer
- XPM textures, BMP export
- get_next_line for line‐by‐line file parsing

##### Final advice
- Be extremely detailed: include each submodule (e.g., render_wall vs. render_floor) if desired.
- Configuration flow, game‐state updates, rendering pipeline, and I/O event flow clearly.
- Avoid over‐abstracting—show the real .c/.h boundaries so maintenance and scaling decisions are evident.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Module
    subgraph "Configuration Module" 
        direction TB
        Config_Parse["config/config.c"]:::config
        Config_Map["config/map.c"]:::config
        Config_Check["config/map_check.c"]:::config
        Config_Params["config/parse_params.c"]:::config
        Config_Texture["config/parse_texture.c"]:::config
        Config_H["config/config.h"]:::config
    end

    %% Core Game Loop
    subgraph "Core Game Loop"
        direction TB
        Main["main.c"]:::core
        Cub3d["cub3d.c"]:::core
        Game["game.c"]:::core
        Cub3d_H["cub3d.h"]:::core
    end

    %% Input Handler
    subgraph "Input Handler"
        direction TB
        Shortcuts["engine/shortcuts.c"]:::core
        Window["engine/window.c"]:::core
    end

    %% Raycasting & Rendering Engine
    subgraph "Raycasting & Rendering Engine"
        direction TB
        Camera["engine/camera.c"]:::core
        Tables["engine/tables.c"]:::core
        Raycast["engine/raycast.c"]:::core
        DrawWall["engine/draw_wall.c"]:::core
        DrawFloorSky["engine/draw_sky_floor.c"]:::core
        DrawUtils["engine/draw.c"]:::core
        Screen["engine/screen.c"]:::core
        TextureMgr["engine/texture.c"]:::core
        Sprite["engine/sprite.c"]:::core
        SpriteUtils["engine/sprite_utils.c"]:::core
        UI["engine/ui.c"]:::core
        Quest["engine/quest.c"]:::core
        Crosshair["engine/crosshair.c"]:::core
        ColorCalc["engine/color.c"]:::core
        Engine_H["engine/engine.h"]:::core
    end

    %% Graphics Abstraction Layer
    subgraph "Graphics Abstraction Layer (MLX)"
        direction TB
        MLX_Font["mlx/font.c"]:::gfx
        MLX_Image["mlx/mlx_image.swift"]:::gfx
        MLX_Window["mlx/mlx_window.swift"]:::gfx
        MLX_Init["mlx/mlx_init.swift"]:::gfx
        MLX_H["mlx/mlx.h"]:::gfx
        MLX_PNG["mlx/mlx_png.c"]:::gfx
        MLX_RGB["mlx/mlx_rgb.c"]:::gfx
        MLX_String["mlx/mlx_string_put.c"]:::gfx
        MLX_XPM["mlx/mlx_xpm.c"]:::gfx
        MLX_Interface["mlx/interface.swift"]:::gfx
        MLX_Version["mlx/version"]:::gfx
        MLX_Makefile["mlx/Makefile"]:::gfx
    end

    %% Asset Store
    Textures["textures/*.xpm"]:::assets

    %% Utility Library
    subgraph "Utility Library"
        direction TB
        Utils_C["utils/*.c"]:::utils
        Utils_H["utils/utils.h"]:::utils
        Pos["utils/pos.c"]:::utils
        Str["utils/str.c"]:::utils
        GNL_C["gnl/get_next_line.c"]:::utils
        GNL_Utils["gnl/get_next_line_utils.c"]:::utils
        GNL_H["gnl/get_next_line.h"]:::utils
    end

    %% BMP Exporter
    BMP["bmp.c"]:::core

    %% Relationships
    Config_Parse -->|provides config| Main
    Config_Map -->|provides map| Main
    Config_Check --> Main
    Config_Params --> Main
    Config_Texture --> Main

    Main -->|"initializes"| Cub3d
    Cub3d -->|runs loop| Game

    Game -->|"registers hooks"| Shortcuts
    Game -->|opens window| Window

    Game -->|"update & render"| Raycast
    Raycast --> DrawWall
    Raycast --> DrawFloorSky
    Raycast --> Sprite
    DrawWall --> TextureMgr
    Sprite --> SpriteUtils
    UI --> Quest
    UI --> Crosshair

    Raycast -->|"frame buffer"| MLX_Image
    MLX_Image --> MLX_Window
    MLX_Window --> MLX_Init

    MLX_Window -->|user input| Shortcuts
    Shortcuts --> Game

    Game -->|screenshot| BMP

    Main --> Utils_C
    Main --> GNL_C
    Raycast --> Utils_C
    Game --> Utils_C
    BMP --> Utils_C

    Textures --> DrawWall
    Textures --> TextureMgr

    %% Click events
    click Config_Parse "https://github.com/glagan/42-cub3d/blob/master/config/config.c"
    click Config_Map "https://github.com/glagan/42-cub3d/blob/master/config/map.c"
    click Config_Check "https://github.com/glagan/42-cub3d/blob/master/config/map_check.c"
    click Config_Params "https://github.com/glagan/42-cub3d/blob/master/config/parse_params.c"
    click Config_Texture "https://github.com/glagan/42-cub3d/blob/master/config/parse_texture.c"
    click Config_H "https://github.com/glagan/42-cub3d/blob/master/config/config.h"

    click Main "https://github.com/glagan/42-cub3d/blob/master/main.c"
    click Cub3d "https://github.com/glagan/42-cub3d/blob/master/cub3d.c"
    click Game "https://github.com/glagan/42-cub3d/blob/master/game.c"
    click Cub3d_H "https://github.com/glagan/42-cub3d/blob/master/cub3d.h"

    click Shortcuts "https://github.com/glagan/42-cub3d/blob/master/engine/shortcuts.c"
    click Window "https://github.com/glagan/42-cub3d/blob/master/engine/window.c"

    click Camera "https://github.com/glagan/42-cub3d/blob/master/engine/camera.c"
    click Tables "https://github.com/glagan/42-cub3d/blob/master/engine/tables.c"
    click Raycast "https://github.com/glagan/42-cub3d/blob/master/engine/raycast.c"
    click DrawWall "https://github.com/glagan/42-cub3d/blob/master/engine/draw_wall.c"
    click DrawFloorSky "https://github.com/glagan/42-cub3d/blob/master/engine/draw_sky_floor.c"
    click DrawUtils "https://github.com/glagan/42-cub3d/blob/master/engine/draw.c"
    click Screen "https://github.com/glagan/42-cub3d/blob/master/engine/screen.c"
    click TextureMgr "https://github.com/glagan/42-cub3d/blob/master/engine/texture.c"
    click Sprite "https://github.com/glagan/42-cub3d/blob/master/engine/sprite.c"
    click SpriteUtils "https://github.com/glagan/42-cub3d/blob/master/engine/sprite_utils.c"
    click UI "https://github.com/glagan/42-cub3d/blob/master/engine/ui.c"
    click Quest "https://github.com/glagan/42-cub3d/blob/master/engine/quest.c"
    click Crosshair "https://github.com/glagan/42-cub3d/blob/master/engine/crosshair.c"
    click ColorCalc "https://github.com/glagan/42-cub3d/blob/master/engine/color.c"
    click Engine_H "https://github.com/glagan/42-cub3d/blob/master/engine/engine.h"

    click MLX_Font "https://github.com/glagan/42-cub3d/blob/master/mlx/font.c"
    click MLX_Image "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx_image.swift"
    click MLX_Window "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx_window.swift"
    click MLX_Init "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx_init.swift"
    click MLX_H "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx.h"
    click MLX_PNG "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx_png.c"
    click MLX_RGB "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx_rgb.c"
    click MLX_String "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx_string_put.c"
    click MLX_XPM "https://github.com/glagan/42-cub3d/blob/master/mlx/mlx_xpm.c"
    click MLX_Interface "https://github.com/glagan/42-cub3d/blob/master/mlx/interface.swift"
    click MLX_Version "https://github.com/glagan/42-cub3d/tree/master/mlx/version"
    click MLX_Makefile "https://github.com/glagan/42-cub3d/tree/master/mlx/Makefile"

    click Textures "https://github.com/glagan/42-cub3d/tree/master/textures/"

    click Utils_C "https://github.com/glagan/42-cub3d/blob/master/utils/*.c"
    click Utils_H "https://github.com/glagan/42-cub3d/blob/master/utils/utils.h"
    click Pos "https://github.com/glagan/42-cub3d/blob/master/utils/pos.c"
    click Str "https://github.com/glagan/42-cub3d/blob/master/utils/str.c"
    click GNL_C "https://github.com/glagan/42-cub3d/blob/master/gnl/get_next_line.c"
    click GNL_Utils "https://github.com/glagan/42-cub3d/blob/master/gnl/get_next_line_utils.c"
    click GNL_H "https://github.com/glagan/42-cub3d/blob/master/gnl/get_next_line.h"

    click BMP "https://github.com/glagan/42-cub3d/blob/master/bmp.c"

    %% Styles
    classDef config fill:#D0E6FF,stroke:#0066CC,color:#003366
    classDef core fill:#E0FFD8,stroke:#229922,color:#115511
    classDef gfx fill:#FFE4CC,stroke:#FF8000,color:#993D00
    classDef assets fill:#F0F0F0,stroke:#999999,color:#666666
    classDef utils fill:#E8F0FF,stroke:#6699CC,color:#335577
```
