Next Previous Contents

2. Quake MAP Files

2.1 Coordinate System

Quake uses a standard right-handed (X,Y,Z) coordinate system (RHS). If you are not familiar with the reference of "right-handed" to a coordinate system, it basically provides an intuitive visual description of the system: point your fingers towards the positive x-axis and bend your fingers so that your knuckles face the positive y-axis, your thumb will point towards the positive z-axis: 

        ^ z+
        |
        |
        |
        |
        |------------> y+
       /
      /
     /
    /
   <
 x+
In other words: if the thumb is oriented along x+, and the index finger along y+, your middle finger could be raised to point along +z, using your right hand.

Some entities also need to have an angle that tells the direction it is facing within the xy plane. The units are degrees, the values possible are thus 0-359, which zero pointing east and 90 pointing ???north???, that is, we are using a counterclockwise (CCW) system. Some angles have special values:

2.2 Brushes

Brushes are one of the two primary components of a MAP file. Each brush defines a solid region. Brushes define this region as the intersection of four or more planes. Each plane is defined by three noncolinear vertices. These vertices must go in a clockwise oriented sequence: 

              |
              |
           ---v1--v2-------
              |
              |
              v3
              |
              |
These would define a triangle (v1,v2,v3) in a 2D plane, and by that they also define plane.

The Quake brushes are meant to be 3D volumes, thus four planes are needed. If you share as many vertices as possible, you will need four vertices to define all four planes (each combination of three vertices defining one plane). In this case, the lines connecting two vertices would also be the edges of the faces, and the vertices would be the vertices of the brush, sharing a (more or less distorted) tetrahedron.

Each brush statement looks like this: 


 // A Brush.
 {
  ( 128 0 0 ) ( 128 1 0 ) ( 128 0 1 ) GROUND1_6 0 0 0 1.0 1.0
  ( 256 0 0 ) ( 256 0 1 ) ( 256 1 0 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 128 0 ) ( 0 128 1 ) ( 1 128 0 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 384 0 ) ( 1 384 0 ) ( 0 384 1 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 0 64 ) ( 1 0 64 ) ( 0 1 64 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 0 128 ) ( 0 1 128 ) ( 1 0 128 ) GROUND1_6 0 0 0 1.0 1.0
 }
This defines a rectangular region that extends from (128,128,64) to (256,384,128). Here is what a single line (defining a plane) means: 

  ( 128 0 0 ) ( 128 1 0 ) ( 128 0 1 ) GROUND1_6 0 0 0 1.0 1.0

  // 1st Point   2nd Point   3rd Point   Texture
The last five numers are: 
x_off     - Texture x-offset (must be multiple of 16)
y_off     - Texture y-offset (must be multiple of 16)
rot_angle - floating point value indicating texture rotation
x_scale   - scales x-dimension of texture (negative value to flip)
y_scale   - scales y-dimension of texture (negative value to flip)

2.3 General MAP Info

The actual MAP file format is quite simple. It is simply a text file. All Quake editing tools should support both UNIX or DOS text formats, as id's tools do - that is, handle both CR/LF and LF.

MAP files are the development format for Quake levels. It is preferred that all editors work with MAP files, as all tools released by id Software also use the MAP file format. A map file is basically un-'compiled' level data. The actual MAP file is totally unusable by Quake itself until it is coverted to a BSP file by a BSP builder such as id Software's QBSP.

???MOVE: For a MAP file's lightmaps to be calculated by Quake, the level must also be run through a light builder, such as LIGHT. Otherwise, everything will be displayed at full brightness. Finally, to speed up the level and ensure proper display, visibility lists should be calculated by a program such as VIS. The process for building levels in Quake is quite time-consuming compared to building Doom levels, even on a fast computer.

The grammar of a MAP file is roughly as follows: 

{
 entity
 {
  brush (optional)
 }
}
...
Comments in the MAP file are indicated by a "//" (C++ style comment). ???SGML, VRML, JavaCC, BNF.

Many entity/brush combinations can be put into a map file. All MAP files must contain with a worldspawn entity, usually as the first entry. This entry defines all of the normal brushes that make up the structure of the level. There should be only one worldspawn entity per MAP file. Here's the syntax of a worldspawn entity: 


   "classname" "worldspawn" // Tells Quake to spawn the world
   "wad" "DIRPATH"          // tells what graphics (texture) WAD2 file to use.
   "message" "TITLE"        // The title of the level
   "worldtype" "#"          // Describes time of environment
                            //   (changes appearance/name of keys)
                            // 0 == Medieval (medieval)
                            // 1 == Runic (metal)
                            // 2 == Present (base)
   "sounds" "#"             // Tells the CD player which track to play.
   "light" "#"              // Default light level

A complete, minimal, simple map file would look like this: 

{
 "sounds" "1"
 "classname" "worldspawn"
 "wad" "/gfx/base.wad"
 "worldtype" "0"
 {
  ( 128 0 0 ) ( 128 1 0 ) ( 128 0 1 ) GROUND1_6 0 0 0 1.0 1.0
  ( 256 0 0 ) ( 256 0 1 ) ( 256 1 0 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 128 0 ) ( 0 128 1 ) ( 1 128 0 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 384 0 ) ( 1 384 0 ) ( 0 384 1 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 0 64 ) ( 1 0 64 ) ( 0 1 64 ) GROUND1_6 0 0 0 1.0 1.0
  ( 0 0 128 ) ( 0 1 128 ) ( 1 0 128 ) GROUND1_6 0 0 0 1.0 1.0
 }
}
{
 "classname" "info_player_start"
 "origin" "256 384 160"
}
Note that this just defines a ground - you would need at least four brushes do create an empty space (e.g. six cubes to create acubic room).

As you can see, all brushes are contained in entities, even those that make up the main level. The most complex part of MAP files are the entities. They are what the rest of this document are about.

Next Previous Contents