Skip to main content

​
Quick Start

Get your first Cub3D scene running in just a few steps.
Before starting, ensure you’ve completed the Installation Guide and have all dependencies installed.

​
Build and Run

1

Navigate to Source Directory

cd ~/workspace/source
2

Build the Project

make
This compiles all source files and links them with MiniLibX and Libft. The output executable is named cub3d.
The Makefile (Makefile:27-29) automatically builds both MiniLibX and Libft before compiling the main project.
3

Run Your First Scene

Launch Cub3D with one of the example maps:
./cub3d maps/COME.cub
A window should open displaying a 3D first-person view of the map.

​
Available Example Maps

The maps/ directory contains several example scenes:

COME.cub

Minimal 3x3 test map - perfect for quick testing
./cub3d maps/COME.cub

DOOMGUY.cub

Larger maze-like environment with DOOM-themed textures
./cub3d maps/DOOMGUY.cub

DOOMSLAYER.cub

Complex layout for exploring raycasting effects
./cub3d maps/DOOMSLAYER.cub

Engel.cub

Another themed environment to explore
./cub3d maps/Engel.cub

​
Controls

Once the window opens, use these controls to navigate the 3D environment:

​
Movement

The controls are defined in cub3d.h:38-41 and implemented in utils5.c:29-46:

Forward

W key - Move forward in the direction you’re facing

Backward

S key - Move backward

Strafe Left

A key - Move left (perpendicular to facing direction)

Strafe Right

D key - Move right (perpendicular to facing direction)

​
Camera Rotation

Rotate Left

Left Arrow key - Rotate camera counterclockwise

Rotate Right

Right Arrow key - Rotate camera clockwise

​
System

Exit

ESC key - Close the window and exit the program (utils5.c:32)

​
What to Expect

When you run Cub3D, here’s what happens behind the scenes:

​
1. Window Creation

The engine creates a window at 1732x1000 resolution (cub3d.h:30-31): 
#define WIDTH 1732
#define HEIGHT 1000

​
2. Map Parsing

The program reads your .cub file (main.c:83-90) and:
  • Validates the map format
  • Loads texture files (XPM format)
  • Parses floor and ceiling RGB colors
  • Finds the player starting position and direction

​
3. Raycasting Initialization

The raycasting engine initializes (main.c:51-72):
  • Sets player position based on map spawn point
  • Configures direction and plane vectors for the camera
  • Loads all four wall textures into memory
  • Creates the rendering image buffer

​
4. Real-time Rendering Loop

The main rendering loop (raycasting.c:102-127) executes every frame: 
void raycasting(t_map *mapa, int i)
{
    double camera_x;
    double side_x;
    double side_y;
    double dist;
    int start_y;

    while (++i < WIDTH)  // Cast a ray for each screen column
    {
        camera_x = 2 * i / (double)WIDTH - 1;
        mapa->ray_dir_x = mapa->dir_x + mapa->plane_x * camera_x;
        mapa->ray_dir_y = mapa->dir_y + mapa->plane_y * camera_x;
        init_dda(mapa, &side_x, &side_y);
        perform_dda(mapa, &side_x, &side_y);
        calculate_wall_data(mapa, &dist);
        select_texture(mapa);
        // ... draw the wall slice
    }
}
The engine casts 1732 rays per frame (one for each horizontal pixel), uses DDA to find wall intersections, and renders textured wall slices.

​
Visual Output

​
Rendering Components

  1. Ceiling - Solid color defined by C in the map file
  2. Walls - Textured using XPM images based on wall orientation:
    • North-facing walls use the NO texture
    • South-facing walls use the SO texture
    • East-facing walls use the EA texture
    • West-facing walls use the WE texture
  3. Floor - Solid color defined by F in the map file

​
Example: COME.cub

Let’s examine the minimal test map (maps/COME.cub): 
NO ./pizza.xpm
SO ./doom2.xpm      
WE ./doom3.xpm
EA ./eagle.xpm

F 220,100,0
C 225,30,0

111
1N1
111
Map breakdown:
  • 3x3 enclosed room with walls on all sides
  • Player spawns at center facing North (N)
  • Floor color: RGB(220, 100, 0) - orange
  • Ceiling color: RGB(225, 30, 0) - red
  • Textures: Different XPM files for each direction
When you run this map, you’ll see textured walls in all directions from the center of a small room.

​
Performance Tips

Optimization

The Makefile compiles with -O3 optimization for maximum performance. On modern hardware, you should achieve 60+ FPS at 1732x1000 resolution.
If you experience low frame rates, check:
  • System resource usage (other applications consuming CPU)
  • X11 server performance
  • Whether debug symbols (-g3) are affecting performance

​
Common Issues

Check that:
  1. X11 is running (echo $DISPLAY should show :0 or similar)
  2. You have permission to create windows
  3. No firewall is blocking X11 connections
Try running a simple test:
xeyes  # Should open a window with animated eyes
The map file references XPM texture files that must exist in the same directory as the executable or use absolute paths.
# Check if textures exist
ls -la *.xpm

# If missing, verify paths in your .cub file
cat maps/COME.cub
Common causes:
  1. Invalid map format - Map must be enclosed by walls (1s)
  2. Missing player spawn - Must have exactly one N/S/E/W in the map
  3. Invalid RGB values - Colors must be 0-255
The parser will print specific error messages defined in cub3d.h:42-66.
Ensure:
  1. The Cub3D window has focus (click on it)
  2. You’re using the correct keys (WASD + Arrow keys)
  3. Your keyboard layout is standard US/QWERTY
The key codes are defined using X11 keysyms (cub3d.h:18 and utils5.c:29-46).

​
Next Steps

Create Custom Maps

Learn how to design your own .cub map files

Understanding Raycasting

Dive deep into the rendering algorithm

Texture Creation

Create custom XPM textures for your walls

Code Architecture

Explore the codebase structure and key functions

​
Experiments to Try

1

Modify Colors

Edit a .cub file and change the F (floor) and C (ceiling) RGB values:
F 0,255,0      # Bright green floor
C 0,0,255      # Blue ceiling
2

Change Starting Position

Move the player spawn point (N, S, E, or W) to a different location in the map grid.
3

Create a Simple Map

Make a new .cub file with a basic enclosed area:
NO ./texture1.xpm
SO ./texture2.xpm
WE ./texture3.xpm
EA ./texture4.xpm

F 100,100,100
C 50,50,50

11111
10001
10N01
10001
11111
4

Explore Raycasting

Open raycasting.c and read through the DDA algorithm to understand how walls are detected.
The raycasting algorithm runs at raycasting.c:102-127, with DDA implementation at raycasting.c:15-66. Understanding these functions is key to customizing the rendering behavior.