Running Cub3D

Learn how to execute Cub3D, load map files, handle errors, and understand the command-line interface

Command Line Usage

Cub3D requires exactly one command-line argument: the path to a .cub map file.

Basic Syntax

./cub3d <map_file.cub>

The map file must have the .cub extension and follow the Cub3D map format specification.

Running with Example Maps

The Cub3D repository includes several example maps in the maps/ directory:

Simple Map

./cub3d maps/COME.cub

Available Example Maps

COME.cub

Minimal 3x3 test map - Perfect for testing basic functionality

DOOMGUY.cub

Medium-sized map with multiple rooms and corridors

Dommed.cub

Complex layout testing advanced map features

DOOMSLAYER.cub

Large map with intricate room design

Command-Line Validation

Cub3D performs strict validation of command-line arguments before attempting to load a map.

Argument Count Validation

The program requires exactly 2 arguments (program name + map file):

if (ac != 2)
    return (msg(1, ARGERROR), 1);

Error: “Debes introducir dos argumentos por terminal”

This error appears when you run Cub3D without arguments or with too many arguments.

Example errors:

# No arguments - ERROR
./cub3d

# Too many arguments - ERROR  
./cub3d maps/COME.cub maps/DOOMGUY.cub

# Correct usage
./cub3d maps/COME.cub

Empty Argument Validation

if (av[1][0] == '\0')
    return (msg(1, ARGERROR2), 1);

Error: “Argumento vacio, especifica un mapa”

This occurs when an empty string is passed as the map file argument.

File Extension Validation

The map file must have a .cub extension:

if (ismap(av[1], &mapa) == 1)
{
    mapa.path = ft_strdup(av[1]);
    // ... continue processing
}
else
    return (msg(1, ARGERROR3), 1);

Error: “El mapa tiene que acabar en .cub”

The map file must end with the .cub extension.

Valid extensions:

./cub3d mymap.cub          ✓ Valid
./cub3d maps/test.cub      ✓ Valid
./cub3d map.txt            ✗ Invalid
./cub3d map.CUB            ✗ Invalid (case-sensitive)

Map File Validation

After command-line validation, Cub3D validates the map file contents:

File Name Requirements

From utils.c:15-36, the validation checks:

1. Minimum length: Filename must be at least 5 characters (name + .cub)
2. Extension: Must end with .cub
3. Printable characters: Filename must contain only printable characters

if (i - ii < 5)
    return (msg(2, FORMAT), exit(1), 0);
// Error: "Tiene que tener nombre y extension .cub"

File Access Validation

The program attempts to open the map file:

fd = open(map->path, O_RDONLY);
if (fd > 0)
{
    // Process map...
}
else
    return (msg(2, MAPERROR2), 0);
// Error: "El mapa no se ha podido abrir"

Ensure the map file exists and you have read permissions:

chmod +r maps/COME.cub

Initialization Process

When you run Cub3D successfully, the following initialization occurs:

1. Parse map attributes

   The program reads texture paths, floor color, and ceiling color from the map file:

   parsefloorceilingdirections(map, i, fd);
   
2. Load map grid

   The map layout is copied and validated:

   mapcpy(map, fd);
   getfinalmap(map);
   
3. Validate map closure

   Flood fill algorithm ensures the map is properly closed by walls:

   flood_staff(map);
   
4. Initialize graphics

   MiniLibX window and textures are loaded:

   cubed_init(&mapa);
   

   Window dimensions from cub3.h:30-31:

   #define WIDTH 1732
   #define HEIGHT 1000
   
5. Setup event hooks

   Keyboard and window events are registered:

   mlx_hook(mapa.win_ptr, 2, KeyPressMask, handle_key, &mapa);
   mlx_hook(mapa.win_ptr, 3, KeyReleaseMask, key_release, &mapa);
   mlx_hook(mapa.win_ptr, DestroyNotify, StructureNotifyMask,
       closewindow, &mapa);
   
6. Start render loop

   The main rendering loop begins:

   mlx_loop_hook(mapa.mlx_ptr, cubed_render, &mapa);
   mlx_loop(mapa.mlx_ptr);
   

Error Messages Reference

Here are the common error messages you might encounter when running Cub3D:

Error Message	Cause	Solution
”Debes introducir dos argumentos por terminal”	Wrong number of arguments	Provide exactly one map file: ./cub3d map.cub
”Argumento vacio, especifica un mapa”	Empty string argument	Provide a valid file path
”El mapa tiene que acabar en .cub”	Wrong file extension	Use a .cub file extension
”Tiene que tener nombre y extension .cub”	Filename too short	Filename must be at least 1 character + .cub
”El mapa no se ha podido abrir”	File doesn’t exist or no permissions	Check file exists and is readable
”Error: Empty map”	Map file is empty	Add valid map content
”Map is not closed”	Map has holes or isn’t surrounded by walls	Fix map boundaries
”Should have only one player…”	Multiple players or invalid characters	Ensure exactly one player (N/S/E/W)
“Error cargando textura”	Texture file not found	Verify texture paths in map file

Runtime Information

Window Specifications

When Cub3D runs successfully, it creates a window with these specifications:

• Width: 1732 pixels
• Height: 1000 pixels
• Title: The map filename (without path and extension)

Player Initialization

From main.c:51-62, the player is initialized at:

mapa->xx = mapa->y * SIZE + (SIZE / 2);
mapa->yy = mapa->x * SIZE + (SIZE / 2);
mapa->speed = 1;

Where:

• SIZE: 30 pixels per map cell (defined in cub3.h:33)
• speed: 1 pixel per frame
• Initial position: Center of the player’s starting cell
• Initial direction: Based on player character (N/S/E/W)

Rendering

The game renders at the maximum frame rate your system allows, driven by the MiniLibX event loop:

mlx_loop_hook(mapa.mlx_ptr, cubed_render, &mapa);

Each frame:

1. Clears the image buffer
2. Performs raycasting for each screen column (1732 rays)
3. Draws textured walls with proper perspective
4. Updates the window display

Exiting the Program

There are multiple ways to exit Cub3D:

ESC Key

Press the ESC key to close the window and exit gracefully

Window Close

Click the window’s close button (X) to exit

Both methods properly clean up resources:

int closewindow(t_map *mapa)
{
    mlx_destroy_image(mapa->mlx_ptr, mapa->img_ptr);
    mlx_destroy_image(mapa->mlx_ptr, mapa->tex_north.img_ptr);
    mlx_destroy_image(mapa->mlx_ptr, mapa->tex_south.img_ptr);
    mlx_destroy_image(mapa->mlx_ptr, mapa->tex_east.img_ptr);
    mlx_destroy_image(mapa->mlx_ptr, mapa->tex_west.img_ptr);
    mlx_destroy_window(mapa->mlx_ptr, mapa->win_ptr);
    mlx_destroy_display(mapa->mlx_ptr);
    freeall(mapa);
    free(mapa->mlx_ptr);
    exit(EXIT_SUCCESS);
}

Next Steps

Now that you know how to run Cub3D, learn how to control the player:

Controls

Master the keyboard controls for movement and camera rotation