How szymonsuchanek/cub3d works
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.