Skip to main content

​
Quick Start

This guide will help you compile and run Cub3D on your system in just a few steps.

​
Prerequisites

Before you begin, ensure you have the following installed:
1

C Compiler

You’ll need a C compiler (gcc or clang) with C99 support.
# Install Xcode Command Line Tools
xcode-select --install
2

Development Libraries

The build process will automatically compile SDL2 from source, but you may need some system dependencies.
# macOS frameworks are included by default
# No additional dependencies required
3

Make Utility

Verify that make is installed:
make --version

​
Compilation

1

Clone the Repository

First, clone the Cub3D repository to your local machine:
git clone https://github.com/afonsopc/cub3d.git
cd cub3d
2

Build the Project

The Makefile handles all dependencies automatically, including SDL2 and miniaudio:
make
The first build will take several minutes as it compiles SDL2 from source. Subsequent builds will be much faster.
The build process will:
  1. Extract and compile SDL2 from the included archive
  2. Extract miniaudio headers
  3. Compile all source files in src/
  4. Link everything into the cub3d executable
You should see output similar to:
Compiling "SDL2".
Compiling "miniaudio".
Compiling "src/main.c" into "obj/src/main.o".
Compiling "src/utils/cub3d0.c" into "obj/src/utils/cub3d0.c".
...
Compiling "obj/..." into "cub3d".
3

Verify the Build

Check that the executable was created:
ls -lh cub3d
You should see the cub3d binary (approximately 1-2 MB).

​
Running Cub3D

​
Default Map (Hub)

To run Cub3D with the default hub map: 
./cub3d
This is equivalent to: 
./cub3d maps/hub.cub
The hub map provides access to both the 42 Lisboa campus and Wolfenstein 3D levels through interactive elevators.

​
Specific Maps

You can launch any map directly by providing its path as an argument: 
./cub3d maps/42lisboa.cub

​
Available Maps

The maps/ directory contains several pre-built levels:
Map FileDescription
hub.cubCentral hub with elevators to other maps
42lisboa.cub3D recreation of 42 Lisboa campus
e1m1.cubWolfenstein 3D Episode 1, Mission 1
e1m2.cubWolfenstein 3D Episode 1, Mission 2
smol.cubSmall test map for quick testing
subject.cubOriginal 42 project subject map

​
Controls

​
Keyboard Controls

KeyAction
W / ↑Move forward
S / ↓Move backward
AStrafe left
DStrafe right
←Turn left
→Turn right
SpaceUse/Interact (open doors, use elevators)
EUse/Interact (alternative)
MSwitch weapon (machine gun)
PSwitch weapon (pistol)
KSwitch weapon (knife)
ESCExit game

​
Mouse Controls

  • Mouse Movement: Look around / Turn
  • Left Click: Fire weapon (in Wolfenstein maps)

​
Controller Support

Cub3D supports Xbox, PlayStation, and compatible game controllers:
  • Left Stick: Move
  • Right Stick: Look around
  • A / X Button: Fire weapon
  • B / Circle Button: Use/Interact
  • Start: Pause

​
Map File Format

Cub3D uses .cub files to define maps. Here’s a minimal example:
maps/smol.cub
NO assets/wolf3d/textures/grey-wall0.bmp
SO assets/wolf3d/textures/purple-wall.bmp
WE assets/wolf3d/textures/red-wall.bmp
EA assets/wolf3d/textures/wood-wall.bmp

F 50,50,50
C 225,30,0

111111
1E00W1
100001
1E00W1
111111
Texture Definitions
  • NO: North-facing wall texture
  • SO: South-facing wall texture
  • WE: West-facing wall texture
  • EA: East-facing wall texture
Colors
  • F: Floor color (RGB)
  • C: Ceiling color (RGB)
Map Grid
  • 1: Wall
  • 0: Empty space
  • N, S, E, W: Player spawn position and orientation
Maps can also define custom entities, doors, elevators, and much more. See the included maps for advanced examples.

​
Build Targets

The Makefile provides several useful targets: 
make clean

​
Web Version (Advanced)

To build the WebAssembly version for browsers, you’ll need Emscripten installed:
1

Install Emscripten

Follow the Emscripten installation guide:
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
2

Build with Emscripten

Use the Emscripten Makefile:
make -f emcc.Makefile
This generates:
  • cub3d.html - The main HTML file
  • cub3d.js - JavaScript glue code
  • cub3d.wasm - WebAssembly binary
  • cub3d.data - Packed assets (maps, textures, sounds)
3

Run a Local Server

You’ll need a local web server to run the WASM build:
python3 server.py
Then open your browser to http://localhost:8000/cub3d.html
The web build is optimized for performance with a reduced resolution (400x300) to run smoothly in browsers.

​
Troubleshooting

If SDL2 compilation fails, ensure you have the necessary development tools:
# macOS
xcode-select --install

# Linux
sudo apt-get install build-essential autoconf libtool
Then run make fclean followed by make to rebuild from scratch.
Check that:
  1. You have a display server running (X11, Wayland, or macOS window server)
  2. You’re not trying to run it over SSH without X forwarding
  3. Your graphics drivers are up to date
The game uses miniaudio which should work out of the box. If you experience issues:
  • Check your system audio settings
  • Ensure your audio device is not muted
  • Try running with different audio backends (miniaudio auto-detects)
Ensure you’re running the game from the project root directory where the maps/ and assets/ directories are located:
cd /path/to/cub3d
./cub3d maps/yourmap.cub

​
Next Steps

Explore Maps

Try out different maps to experience the variety of environments and gameplay

Create Custom Maps

Learn the .cub format and create your own levels

Technical Reference

Dive into the codebase architecture and systems

Play Online

Try the web version at omelhorsite.pt

​
Getting Help

If you encounter issues:
  1. Check the GitHub repository for existing issues
  2. Review the source code comments for implementation details
  3. Examine the example maps in maps/ for reference
Happy raycasting!

Build docs developers (and LLMs) love

Get started for freeTalk to us