.cub File Format

The .cub file is the startup contract between the map author and the engine. It provides the mandatory texture paths, floor and ceiling colors, then the 2D grid that will be validated before any MiniLibX initialization is allowed.

.cub contract

The `.cub` file format is a startup contract, not just a text blob with a map at the end

A valid `.cub` file carries enough information for the engine to load textures, parse floor and ceiling colors, build the map grid, validate the player spawn, then decide whether runtime initialization may proceed.

Three logical sections

The format is easier to understand when separated by responsibility: wall textures, color configuration, and the map payload consumed by validation and rendering.

NO SO WE EA

Wall texture headers

North, south, west, and east wall textures define the mandatory directional texture set.

F C

Floor and ceiling colors

Both color headers use `r,g,b` values in `0..255` and are parsed before the map block starts.

map

2D map body

Once the first map-like line is reached, remaining lines are treated as map data until end of file.

Defense sequence

For oral defense, the useful explanation is chronological: what is parsed first, what becomes irreversible at `map_start`, and what must pass before MLX can be touched.

01 parse headers reject duplicates, unknown identifiers, bad texture values, and malformed RGB colors

02 detect `map_start` the first non-empty map-looking line switches the parser into map mode

03 validate spawn and symbols exactly one player marker, then accepted map alphabet

04 run enclosure checks BFS and closure rules decide whether the playable area is safe

05 initialize runtime only successful parsing and validation may lead to `init_mlx()` and rendering startup

Reference skeleton

This is the minimum readable structure the parser expects before deeper validation rules are applied.

NO ./textures/mandatory/no.xpm
SO ./textures/mandatory/so.xpm
WE ./textures/mandatory/we.xpm
EA ./textures/mandatory/ea.xpm
F 80,80,80
C 120,180,255

111111
100001
10N001
100001
111111

Parsing rules

These are the structure rules the parser enforces before deeper validation begins.

The input path must use the `.cub` extension

File selection is constrained before content parsing begins.

extension

Unknown identifiers are rejected before the map block

Only `NO`, `SO`, `WE`, `EA`, `F`, and `C` are valid configuration headers.

reject

Duplicate headers are invalid

Each required config slot must be filled once; duplicate texture or color slots fail immediately.

slots

Texture values must resolve to `.xpm` resources

Real parsing also checks readability, not just the suffix.

open() + .xpm

Color headers require `r,g,b` values in `0..255`

Malformed color syntax fails before any map validation happens.

rgb

Empty lines inside the map block are invalid

Whitespace is tolerated before map start, but not after map parsing has begun.

map block

A header after the map start is no longer a header

It becomes map content and fails during map validation, often as an extra spawn or invalid character.

validate_map

✓

Startup contract

Graphics initialization is downstream from parsing, never concurrent with it.

If headers, colors, map start detection, spawn validation, or enclosure fail, the program stops before window creation. A valid `.cub` file is therefore a prerequisite for entering the rendering pipeline at all.

Expected Sections

A valid .cub file contains three logical blocks:

texture headers: NO, SO, WE, EA
color headers: F, C
map body: the 2D grid consumed by validation, collision, and raycasting

All required headers must exist before the runtime can continue. Texture paths must resolve to readable .xpm files, either as absolute paths or as paths relative to the .cub file location.

Accepted Layout

Header order is flexible. The parser accepts NO/SO/WE/EA/F/C in any order as long as each required identifier appears exactly once before the map block.

Empty lines before the map are allowed and ignored. Once the map begins, every remaining line is treated as map content until end of file.

Map Start Detection

The map starts at the first non-empty line that looks like map data. In this repository, that means a line composed only of accepted map characters from the shared mandatory/bonus alphabet. From that point forward, trailing configuration-like text is no longer parsed as headers: it becomes invalid map content instead.

Scope

This page focuses on parser-facing structure rules: headers, duplicates, RGB syntax, map-start detection, and spawn presence.

Deeper checks such as full enclosure, BFS leak detection, and open-area validation belong to the dedicated map validation and parsing pipeline pages.