Cub3D: A High-Performance Raycasting Engine

A custom-built 3D game engine written in C using the MiniLibX library. This project implements a raycasting technique similar to classic 90s games like Wolfenstein 3D, optimized for performance and strictly compliant with the 42 Norm (Version 4.1).

---

🚀 Overview

Cub3D is a software-rendered pseudo-3D engine. It transforms a 2D map into a 3D perspective by projecting rays from the player's viewpoint and calculating intersections with world geometry.

Key Features

• DDA Algorithm: Efficient ray-wall intersection detection.
• Memory Arena: Custom allocation system to minimize heap fragmentation and improve cache locality.
• Depth Shading & Directional Shadows: Dynamic brightness scaling based on distance and wall orientation.
• Sub-Pixel Precision: Support for fractional ray densities (supersampling) to reduce aliasing.
• Optimized Trigonometry: Pre-calculated lookup tables and tangent caching to ensure smooth performance on older hardware.

---

🛠️ Architecture & Design Decisions

The project follows a Modular Modular Architecture, ensuring a "simple and clear sequence of executed instructions" as mandated by the pedagogical goals of the 42 project.

1. The Memory Philosophy: Stack vs. Arena

We utilize a two-tier memory strategy:

• The Stack: Persistent game states (t_game, t_player, t_settings) and static arrays (like the rays buffer) are kept on the stack for maximum speed.
• The Arena: All dynamic allocations (window structures, images, map data) are handled by a custom Memory Arena. This allows for instant "one-pass" cleanup and prevents memory leaks during runtime.

2. Raycasting Logic (Digital Differential Analysis)

Instead of relying on expensive trigonometric iterations, we implement the DDA Algorithm. DDA finds intersections by "stepping" through the grid in increments of one unit.

• Horizontal & Vertical Checks: The engine performs separate passes for horizontal and vertical grid lines to determine which is closer.
• Fish-eye Correction: We multiply the raw distance by the cosine of the relative ray angle to prevent the "warping" effect at the edges of the FOV.

3. Rendering Pipeline

The renderer operates in three distinct phases:

1. Update: Calculate player movement and rotation based on delta time.
2. Cast: Generate all rays and calculate their intersections and texture coordinates.
3. Draw:

• Floor & Ceiling: Horizontal scanline rendering.
• Walls: Vertical strip rendering with texture mapping and depth shading.

---

🎨 Visual Enhancements

Depth Shading (Fog)

To create atmospheric depth, pixel intensity is calculated using a linear falloff factor:

This makes far walls fade into darkness, simulating a fog effect.

Directional Shadowing

Vertical wall hits (East/West) are rendered at 90% brightness compared to horizontal hits (North/South). This adds visual contrast and helps players distinguish corners.

Anti-Aliasing (Supersampling)

By utilizing a strip_width less than 1.0, the engine can cast multiple rays per screen pixel. This high-precision math, combined with round() based vertical bounds, removes the "staircase" effect on wall edges.

---

📚 Resources & Credits

The development of this engine was heavily inspired by the following educational resources:

• LodeV's Raycasting Tutorial: The gold standard for understanding DDA and floor rendering.
• Pikuma (Raycasting Engine Tutorial): Essential for mastering the math behind projection planes and camera rotation. Link
• 3DSage (YouTube): Great insights into the "pure C" implementation of classic raycasting techniques.

---

⚙️ Compilation & Usage

The engine requires the MiniLibX library for your specific OS (Linux/X11 or MacOS/Metal).

# Clone the repository
git clone https://github.com/0-x-joseph/cub3d.git
cd cub3d

# Compile the project
make

# Run the engine with a map file
./cub3D maps/classic.cub

---