MAP file format

file format spec + sample parser code for Quake .MAP files ("Valve" style, mapversion 220)

This is a technical file format specification article for programmers.

For mapping tutorials, see instead.

The .MAP file format is a 3D file format devised for Quake 1 (1996).

It is gradually emerging as the standard file type for brush-based levels in any game engine, partly because it is relatively simple to parse and edit. It's similar to how .OBJ has become a simple 3D standard too, even though it lacks many advanced features.

Parsers

There's a good chance someone has already written a generic .MAP parser for your game engine / programming language.

C++ ()
C# ( or )
Rust ( or )

For game engine-specific MAP importers and integrations, see .

File format

Text based with curly braces and line breaks
Z axis is up (Quake convention), right-handed
angle values are Euler degrees from 0-359
- -1 means "up"
- -2 means "down"
- some Quake mods implement rotations as a 3D vector called m_angle

Entities

Every object in a .MAP must be an entity, a generic actor / game object container type.

There are two types of entities:

point entities: monsters, items, lights, things with fixed size / no size
brush entities: point entities with 3D shapes embedded inside them
- worldspawn: global static brush entity, the "root" of the entire game world
- world brushes: brushes bound to worldspawn

Entity schema

{
   // classname: the type of entity
   "classname" "(ENTITY TYPE)"
   
   // moreentity data goes here
   
   {
      // (optional) brush data goes here
   }
}

Point entity

// a Point Entity is a curly brace scope
// with keyvalue pairs surrounded by quotation marks
{
    // classname: the type of entity
    "classname" "info_player_start"
    
    // spawnflags: a bitmask of toggles for the entity
    "spawnflags" "0"
    
    // origin: the entity's position in 3D space
    "origin" "32 32 24"
    
    // but this is just Quake convention, you could put any arbitrary data here
}

Brush entity

// a Brush Entity is like a Point Entity but with 3D brush definitions inside
{
    "spawnflags" "0"
    
    // remember: worldspawn is the traditional root entity of all world brushes
    "classname" "worldspawn"
    // note that 'classname' is often NOT the first keyvalue pair, don't assume!
    
    // a file path to a Quake WAD (texture set)
    "wad" "E:\q1maps\Q.wad"
    {
        // 3D brush geometry information, see next section for details
        ( -16 -64 -16 ) ( -16 -63 -16 ) ( -16 -64 -15 ) __TB_empty [ 0 -1 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
        ( -64 -16 -16 ) ( -64 -16 -15 ) ( -63 -16 -16 ) __TB_empty [ 1 0 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
        ( -64 -64 -16 ) ( -63 -64 -16 ) ( -64 -63 -16 ) __TB_empty [ -1 0 0 0 ] [ 0 -1 0 0 ] 0 1 1
        ( 64 64 16 ) ( 64 65 16 ) ( 65 64 16 ) __TB_empty [ 1 0 0 0 ] [ 0 -1 0 0 ] 0 1 1
        ( 64 16 16 ) ( 65 16 16 ) ( 64 16 17 ) __TB_empty [ -1 0 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
        ( 16 64 16 ) ( 16 64 17 ) ( 16 65 16 ) __TB_empty [ 0 1 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
    }
}

Brush geometry

A brush is a convex 3D shape defined by 4 or more planes.

It is NOT a traditional 3D mesh format made of vertices and triangles. You need an additional map compile step to process the brush data into a usable 3D mesh. For example, Quake maps use an editor-time command line tool called QBSP that outputs a compiled .BSP map file; meanwhile many .MAP parsers for other engines instead generate this mesh at runtime.

Every brush line defines one 3D plane (a triangle) and its texture coordinates:

Brush plane

(x1 y1 z1) (x2 y2 z2) (x3 y3 z3) TEXTURE_NAME [ ux uy uz offsetX ] [ vx vy vz offsetY ] rotation scaleX scaleY

Texturing / UVs

The Quake .MAP file format has two versions: the original Standard version, and an updated format by Valve Software.

Standard texture coordinates:

TEXTURE_NAME offsetX offsetY rotation scaleX scaleY

Valve format texture coordinates:

TEXTURE_NAME [ ux uy uz offsetX ] [ vx vy vz offsetY ] rotation scaleX scaleY

We generally recommend using Valve format, and there's no reason to use standard format other than backwards compatibility / porting old files to the updated format.

ValveFormatTexParse.c

// in the Valve texture format, parsing the file would yield these values in order:
// texname [ ux uy uz offsetX ] [ vx vy vz offsetY ] rotation scaleX scaleY
// NOTE: Valve format doesn't actually use the "rotation" value anymore

// per vertex and per face, coordinates can be calculated like this

Vec3 axisU = Vec3(ux, uy, uz) / scaleX;
Vec3 axisV = Vec3(vx, vy, vz) / scaleY;

for (FaceVertex& v : Vertices)
{
   // Dot product of (v.Point, axisU)
   v.TexU = v.Point.x * axisU.x + v.Point.y * axisU.y + v.Point.z * axisU.z;
   // Dot product of (v.Point, axisV)
   v.TexV = v.Point.x * axisV.x + v.Point.y * axisV.y + v.Point.z * axisV.z;
   v.TexU += offsetX;
   v.TexV += offsetY;
   v.TexU /= Texture->GetWidth();
   v.TexV /= Texture->GetHeight();
}

Example .MAP file

SimpleExampleMap.map

// entity 0
{
    "spawnflags" "0"
    "classname" "worldspawn"
    "wad" "E:\q1maps\Q.wad"
    // brush 0
    {
        ( -16 -64 -16 ) ( -16 -63 -16 ) ( -16 -64 -15 ) __TB_empty [ 0 -1 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
        ( -64 -16 -16 ) ( -64 -16 -15 ) ( -63 -16 -16 ) __TB_empty [ 1 0 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
        ( -64 -64 -16 ) ( -63 -64 -16 ) ( -64 -63 -16 ) __TB_empty [ -1 0 0 0 ] [ 0 -1 0 0 ] 0 1 1
        ( 64 64 16 ) ( 64 65 16 ) ( 65 64 16 ) __TB_empty [ 1 0 0 0 ] [ 0 -1 0 0 ] 0 1 1
        ( 64 16 16 ) ( 65 16 16 ) ( 64 16 17 ) __TB_empty [ -1 0 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
        ( 16 64 16 ) ( 16 64 17 ) ( 16 65 16 ) __TB_empty [ 0 1 0 -0 ] [ 0 0 -1 -0 ] -0 1 1
    }
}

// entity 1
{
    "spawnflags" "0"
    "classname" "info_player_start"
    "origin" "32 32 24"
}

Sources

PreviousFGD file format NextMDL file format

Last updated 5 months ago