Cub3D

A 3D game engine inspired by Wolfenstein 3D, built using raycasting principles.

📖 Description

Cub3D is a graphical project that creates a dynamic 3D perspective inside a maze using ray-casting techniques. The project is inspired by the world-famous game Wolfenstein 3D, which was the first FPS ever. This project explores fundamental algorithms in computer graphics and provides hands-on experience with texture mapping, player movement, and collision detection.

✨ Features

• Raycasting Engine: Real-time 3D rendering using raycasting algorithm
• Texture Mapping: Wall textures loaded from XPM files
• Minimap: Real-time minimap showing player position and orientation
• Player Movement: Smooth movement in 4 directions with collision detection
• Mouse Control: Look around using mouse movements
• Customizable Maps: Parse and render custom maps from .cub files
• Floor & Ceiling Colors: Configurable RGB colors for floor and ceiling
• Memory Management: Garbage collector for safe memory handling

🛠️ Requirements

• Operating System: Linux
• Compiler: gcc
• Libraries:
  • MiniLibX
  • X11
  • Xext
  • Math library

📦 Installation

1. Clone the repository

   git clone https://github.com/yssrexe/Cub3d.git
   cd Cub3d

2. Install MiniLibX (if not already installed)

   # For Ubuntu/Debian
   sudo apt-get install libx11-dev libxext-dev libbsd-dev

3. Compile the project

   make

This will create an executable called cub3d.

🚀 Usage

Run the program with a map file as an argument:

./cub3d maps/map.cub

Map Format (.cub file)

The map file must contain the following elements:

F R,G,B          # Floor color (RGB values 0-255)
C R,G,B          # Ceiling color (RGB values 0-255)

NO ./path        # North wall texture
SO ./path        # South wall texture
WE ./path        # West wall texture
EA ./path        # East wall texture

111111111111     # Map (must be surrounded by walls '1')
100000000011
100000000001
10N000000001     # N/S/E/W: Player starting position and orientation
111111111111

Map Characters:

• 1 - Wall
• 0 - Empty space (walkable)
• N/S/E/W - Player starting position (North/South/East/West orientation)
• Map must be closed/surrounded by walls

🎮 Controls

Keyboard

• W or ↑ - Move forward
• S or ↓ - Move backward
• A - Move left
• D - Move right
• ← - Rotate camera left
• → - Rotate camera right
• ESC - Exit game

Mouse

• Move mouse left/right to rotate camera view

📁 Project Structure

Cub3d/
├── includes/          # Header files
│   ├── cub.h         # Main header
│   ├── type.h        # Type definitions
│   ├── libft.h       # Library functions
│   └── rendering.h   # Rendering functions
├── parsing/          # Map parsing and validation
├── rendring/         # Raycasting and rendering
├── tex_src/          # Texture management
├── minimap/          # Minimap rendering
├── get_next_line/    # File reading utility
├── LIBFT/            # Custom C library
├── maps/             # Map files and textures
├── main.c            # Entry point
├── free_exit.c       # Cleanup functions
└── Makefile          # Build configuration

🧮 How Raycasting Works

Raycasting is a rendering technique that creates a 3D perspective in a 2D map:

1. Cast rays from the player's position in the direction they're looking
2. Calculate distance to walls using DDA algorithm
3. Project walls onto the screen based on distance (farther = smaller)
4. Apply textures to wall surfaces
5. Render floor and ceiling with solid colors

This technique is much faster than true 3D rendering, allowing smooth real-time performance.

🔧 Makefile Commands

• make - Compile the project
• make clean - Remove object files
• make fclean - Remove object files and executable
• make re - Recompile the project
• make bonus - Compile with bonus features

🧪 Testing

Test the program with different map configurations:

./cub3d maps/map.cub

Make sure your maps:

• Are properly closed by walls
• Have valid floor/ceiling colors (0-255 RGB)
• Have exactly one player starting position
• Have valid texture paths

🐛 Common Issues

• Segmentation fault: Check map validity and ensure all textures exist
• Invalid colors: RGB values must be between 0-255
• Map not rendering: Ensure map is surrounded by walls (1)
• Textures not loading: Verify texture file paths are correct

📚 Learning Resources

• Lode's Raycasting Tutorial
• Wolfenstein 3D Source Code
• MiniLibX Documentation

👥 Authors

• yael-yas - Developer
• souel-bo - Developer

🎓 School Project

This project is part of the 42 School curriculum. It aims to develop skills in:

• Computer graphics
• Algorithm optimization
• C programming
• Memory management
• Mathematical applications

📄 License

This project is for educational purposes as part of the 42 School curriculum.

---

Made with ❤️ by Yassir El Yasini at 1337 School