2.1.1 Coordinate System:

Quake uses a standard right-handed (X,Y,Z) coordinate system. If you're not familiar with the reference of "right-handed" to a coordinate system, it basically provides a tactile and visual discription of the mechanics of the system. If you 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+

Some entities also need to have an angle tag that tells the direction it is facing. The values possible are listed below, and all are from the overhead view:

0-359: Normal Angle (zero == east)
-1: Up
-2: Down

2.1.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 non-colinear points. These points must go in a clockwise orientation:

1--2----------------->
|
3
|
|
|
|
|
,

Each brush statement looks like this:

 {
  ( 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
 }

That's probably just a bit confusing when you first see it. It defines a rectangular region that extends from (128,128,64) to (256,384,128). Here's what a single line 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  
                                               

Now, you're probably wondering what those last five numbers are. I've listed what they do below:

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.1.3 General MAP Info:

The actual MAP file format is quite simple. It is simply a text file. All Quake editing tools should support either UNIX or DOS text formats, as id's tools do.

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. 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 generalized format for a MAP file is as follows:

{
 entity
 {
  brush (optional)
 }
}
...

Comments in the MAP file are indicated by a "//" (C++ style comment).

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 the worldspawn class:

"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 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"
}

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.

2.1.4 MAP file corruption:

I've seen MAP files get screwed up more than once. I don't know if it's Worldcraft's fault or not. WC doesn't spot the problems, either, which leads me to think it's the culprit in the first place. When I suspect a problem, or get a compile error, I use QuakeMap because it will find these problems and report that a polyhedron has less than six sides, and the line number in the map where it can be found.

Problem one: If you've been working on a complex map for a long time, and have made a number of edits, you may find that there are only two or three X/Y/Z coordinates between the braces instead of the usual six. I recommend loading your MAP in QuakeMap to check for errors in the MAP as it grows, until Ben adds something comparable to this to Worldcraft.

Problem number two has frequently occurred when using a solid brush that was partially carved with a cylinder, thus making a curved arch. The Forge has documented on how you can mess up a map badly with carving, and there are tutorials on how to keep it clean and minimize the damage. I won't reinvent the wheel, so just go there and read the Tips/Tricks section for a tutorial called Carving Carefully.


Nicholas J. Kain on MAP corruption:

Most map file corruption is caused directly because of bad subtraction algorithms in Quake editors. In the level I have done for Quake using Worldcraft, I have noticed that its subtraction algorithm is of rather poor quality and frequently overlaps brushes and duplicates planes, which gives QBSP fits. In other words, save before you do subtractions into complex surfaces, because chances are Worldcraft will mess things up. Generally, Worldcraft does a fine job of subtraction as long as both surfaces are orthagonal to each other. In other circumstances, however, bad things have a tendency to happen.


2.1.5 The Value of Clean MAPs:

This is something I discovered quite by accident. It all started when I downloaded the Start Map, a conversion of the intro MAP you first see when starting Quake. When I opened it, I was amazed at how clean it is. Download it and see for yourself. So I decided to experiment.

I'd been modifying my first map, The Hidden Fortress, for 32-player QuakeWorld. I knew it was big enough with enough space to support that many players. So, in the process of adding all the start points, items, etc. I decided to clean things up and nest all of the brushes. Below are before and after shots of the same section.



Now mind you, I only modified the top view. I didn't even work on the front/right view, where you have multiple layers. Just these minor mods, which I estimate was maybe 10% of the job, reduced the numportals during VIS from 5990 to 5640, a 6% reduction. Naturally, this reduces VIS time. Assuming my estimate was right, that I only modified 10% of the map's brushes, then I could reduce the VIS time by 60% (more or less).

I found mention of this on QuakeLab, but it's kinda buried. Let this be a lesson: keep your maps clean, and nest all of the brushes. Use Snap To Grid whenever you can to avoid the problem in the first place.


Portions Copyright (c)1996-97 Niklata and Thomas Winzig.