# beddinao/cub3d architecture

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

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

## Overview

##### High-Level Architecture Components
A. Core Application (src/)
- main.c: application entry point, initializes subsystems and enters main loop
- Parsing modules (src/parsing/…):
- Config parser & validator
- Parser & multi-stage validator
- Texture parser & validator
- Rendering modules (src/rendering/…):
- raycasting_init & raycasting_engine: compute wall slices
- hooks & movement: input handling & player state updates
- rendering: orchestrates per-frame rendering
- Utility modules (src/utils/…): common helpers for config, errors, rendering utilities

B. Asset Layer (assets/)
- maps/*.cub: level definitions
- textures (external image files loaded via MLX42)
- recordings: demo animations/screenshots

C. External Libraries (lib/)
- MLX42: window creation, input events, image/shader handling, drawing primitives
- get_next_line: buffered file I/O for parsing
- libft: common C utility functions (string, memory, list, etc.)

D. Build & Configuration
- Makefile/CMakeLists.txt drive compilation, link external libs, generate executable
- /: public headers (cub3d.h, engine.h) defining data structures & APIs

##### Data Flow & Component Interactions
1. Startup
→ main initializes logging/error handlers
→ initialize MLX42: create window, load shaders/textures into GPU memory
2. Main Loop
a. Input (hooks module) captures key/mouse events → updates player position/orientation
b. Rendering (raycasting_engine): cast rays against map grid, compute distances, wall heights
c. Drawing: write pixel data to MLX42 image buffer → MLX42 present to screen
d. Repeat until exit hook triggers mlx_exit
3. Shutdown
→ free allocated memory (libft, parsing structures)
→ destroy MLX42 resources

##### Architectural Patterns & Principles
- Modular separation: parsing, rendering, utilities, external libs
- Single-responsibility: each parser/validator handles one aspect of file input
- Event-driven loop: MLX42 hooks trigger state updates & re-renders

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Startup Phase
    subgraph "Startup Phase"
        direction TB
        Assets["Asset Layer"]:::data
        subgraph "Parsing Pipeline"
            direction TB
            ColorParser["Color Parser"]:::parse
            ColorValidator["Color Validator"]:::parse
            ConfigParser["Config Parser"]:::parse
            ConfigValidator["Config Validator"]:::parse
            MapParser["Map Parser"]:::parse
            MapValidator1["Map Validator Stage1"]:::parse
            MapValidator2["Map Validator Stage2"]:::parse
            TextureParser["Texture Parser"]:::parse
            TextureValidator["Texture Validator"]:::parse
        end
        Assets -->|"reads .cub files"| ColorParser
        ColorParser -->|"validates"| ColorValidator
        Assets --> ConfigParser
        ConfigParser --> ConfigValidator
        Assets --> MapParser
        MapParser --> MapValidator1
        MapValidator1 --> MapValidator2
        Assets --> TextureParser
        TextureParser --> TextureValidator
        ColorValidator --> DataModels
        ConfigValidator --> DataModels
        MapValidator2 --> DataModels
        TextureValidator --> DataModels
    end

    %% Data Models
    subgraph "Data Models"
        direction TB
        MapData["Map Grid"]:::data
        ColorData["Color Config"]:::data
        TextureData["Texture Assets"]:::data
        PlayerState["Player State"]:::data
    end

    %% Runtime Loop
    subgraph "Runtime Loop (Real-Time)"
        direction TB
        InputHooks["Input & Event Handling"]:::input
        Movement["Movement & State Update"]:::input
        RenderOrch["Frame Render Orchestrator"]:::render
        RayInit["Raycasting Init"]:::render
        RayEngine["Raycasting Engine"]:::render
        Drawing["Drawing Module"]:::render
        Screen["Frame Buffer → Screen"]:::render
        InputHooks --> Movement
        Movement --> RenderOrch
        RenderOrch --> RayInit
        RayInit --> RayEngine
        RayEngine --> Drawing
        Drawing --> Screen
        Screen --> InputHooks
        DataModels --> RenderOrch
    end

    %% Core Application Entry
    Main["main.c"]:::core
    Main -->|"startup"| ColorParser
    Main --> ConfigParser
    Main --> MapParser
    Main --> TextureParser
    Main --> RayInit
    Main --> InputHooks

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        MLX["MLX42"]:::ext
        GNL["get_next_line"]:::ext
        Libft["libft"]:::ext
    end
    GNL --> ColorParser
    GNL --> ConfigParser
    GNL --> MapParser
    GNL --> TextureParser
    Libft --> UtilityModules
    MLX --> InputHooks
    MLX --> Drawing
    MLX --> RayEngine

    %% Utility Modules
    subgraph "Utility Modules"
        direction TB
        ConfigUtils["Configuration Utilities"]:::util
        ErrorUtils["Error Handling Utilities"]:::util
        RendUtils1["Rendering Utilities"]:::util
        RendUtils2["Additional Rendering Utilities"]:::util
    end
    ErrorUtils --> Main
    ConfigUtils --> Main
    RendUtils1 --> RenderOrch
    RendUtils2 --> RayEngine

    %% Build & Configuration
    subgraph "Build & Config"
        direction TB
        Make["Makefile/CMakeLists"]:::build
        Headers["Public Headers"]:::build
    end
    Make --> Main
    Headers --> Main

    %% Mapping DataModels
    DataModels["Data Models"]:::data

    %% Click Events
    click Main "https://github.com/beddinao/cub3d/blob/main/src/main.c"
    click ColorParser "https://github.com/beddinao/cub3d/blob/main/src/parsing/color/color_parsing.c"
    click ColorValidator "https://github.com/beddinao/cub3d/blob/main/src/parsing/color/color_validation.c"
    click ConfigParser "https://github.com/beddinao/cub3d/blob/main/src/parsing/config/config_parsing.c"
    click ConfigValidator "https://github.com/beddinao/cub3d/blob/main/src/parsing/config/config_validation.c"
    click MapParser "https://github.com/beddinao/cub3d/blob/main/src/parsing/map/map_parsing.c"
    click MapValidator1 "https://github.com/beddinao/cub3d/blob/main/src/parsing/map/map_validation.c"
    click MapValidator2 "https://github.com/beddinao/cub3d/blob/main/src/parsing/map/map_validation2.c"
    click TextureParser "https://github.com/beddinao/cub3d/blob/main/src/parsing/texture/texture_parsing.c"
    click TextureValidator "https://github.com/beddinao/cub3d/blob/main/src/parsing/texture/texture_validation.c"
    click RayInit "https://github.com/beddinao/cub3d/blob/main/src/rendering/raycasting_init.c"
    click RayEngine "https://github.com/beddinao/cub3d/blob/main/src/rendering/raycasting_engine.c"
    click Drawing "https://github.com/beddinao/cub3d/blob/main/src/rendering/drawing.c"
    click InputHooks "https://github.com/beddinao/cub3d/blob/main/src/rendering/hooks.c"
    click Movement "https://github.com/beddinao/cub3d/blob/main/src/rendering/movement.c"
    click RenderOrch "https://github.com/beddinao/cub3d/blob/main/src/rendering/rendering.c"
    click ConfigUtils "https://github.com/beddinao/cub3d/blob/main/src/utils/config_utils.c"
    click ErrorUtils "https://github.com/beddinao/cub3d/blob/main/src/utils/error_utils.c"
    click RendUtils1 "https://github.com/beddinao/cub3d/blob/main/src/utils/rendering_utils.c"
    click RendUtils2 "https://github.com/beddinao/cub3d/blob/main/src/utils/rendering_utils2.c"
    click Assets "https://github.com/beddinao/cub3d/tree/main/assets/maps/"
    click Assets "https://github.com/beddinao/cub3d/tree/main/assets/textures/"
    click Assets "https://github.com/beddinao/cub3d/tree/main/assets/recordings/"
    click MLX "https://github.com/beddinao/cub3d/tree/main/lib/MLX42/"
    click GNL "https://github.com/beddinao/cub3d/tree/main/lib/get_next_line/"
    click Libft "https://github.com/beddinao/cub3d/tree/main/lib/libft/"
    click Make "https://github.com/beddinao/cub3d/tree/main/Makefile"
    click Headers "https://github.com/beddinao/cub3d/blob/main/include/cub3d.h"
    click Headers "https://github.com/beddinao/cub3d/blob/main/include/engine.h"

    %% Styles
    classDef parse fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef render fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef input fill:#fff9c4,stroke:#f57f17,color:#f57f17
    classDef ext fill:#eceff1,stroke:#546e7a,color:#546e7a
    classDef util fill:#d1c4e9,stroke:#4a148c,color:#4a148c
    classDef data fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef core fill:#f5f5f5,stroke:#212121,color:#212121
    classDef build fill:#e1bee7,stroke:#6a1b9a,color:#6a1b9a
```
