Quake Editing tools information

Below the info by John Carmack, April 6th, 1996.

Quake Editing

Our .map format that QuakeEd generates hasn't changed in over six
months, which is the real strength of non-game-related editors. The
BSP format has changed (literally) over a dozen times since. The world
will be a better place if everyone just uses our source format... Once
again, I plan to release lots of related source when we ship.

I started on a little documentation for the format a while ago, but 
didn't get to polish it up.  Here is what I got done:

We have not completely decided what we are going to do with our map tools,
but here is some early disclosure for those interested. Our map editor runs
under NEXTSTEP, and requires a 32 meg system with at least a 1024*768 display.  
We may be porting it to openstep for windows and releasing it as a seperate
shareware product if we can get a reasonable royalty rate from NeXT.

I will probably release the source code for the editor, but the bulk of it 
is in objective-c, which is likely of little use to most people. Some of 
the techincal stuff dealing with polyhedron operations may be usefull.

I definitely intend to release the utility suite that processes the editor 
output into game .bsp files.  There are three utilities: "qbsp", "light", 
and "vis".  These are very compute intensive tasks (especially vis).  Our 
editor remotely launches the tools on our 4 cpu dec alpha system.  Doing 
the full blown computation on a large map can take over ten minutes, but 
there are many options to make the development turnaround time faster.  
"light" and "vis" are fully multi-threaded, so those of you with access 
to SMP systems can put them to contructive use. I bet a lot of university 
computers are going to start seeing some heavy loads :-).

Irrespective of what we do with our editor, I expect several people / teams 
will be interested in creating new editors for Quake, so here is the basic 

The source format for Quake levels is conceptually very simple and robust.  
There is no way to create invalid data, like the HOM effects in DOOM.

A map consists of one or more entities.  The world is allways entity 0, 
other entities specify player positions, monsters, lights, etc.

An entity consists of zero or or more key/value pairs and zero or more 
solid brushes.

A key/value pair is just two strings that specify some information about 
the entity, like "classname" "monster_demon" or "light" "300".  The order 
of the key/value pairs is not significant.  The usable keys are defined 
in the .qc progs.  They are fully user extendable.

A brush is the basic geometric building block.  It is a convex polyhedron 
specified by four or more planes.  Each plane can have a seperate texture.  
You can freely interpenetrate brushes, and the bsper will chop things up 
as needed.  There are no restrictions whatsoever on the geometry of a map, 
but 90% of the brushes tend to be simple axial blocks.  A large map may 
have over 1000 brushes.

The planes are specified by three points in clockwise order. The
points that define the plane are not necessarlily points on the brush,
but just three non colinear points on the plane. I chose this
representation instead of an explicit normal/distance plane
representation because it allows me to keep perfect precision with
integral values: it guarantees integer values for anything we create
in our editor, lessening concern over floating point creep.

There are a couple restrictions on texturing.  In hindsight, there didn't 
need to be, but I don't have the time to fix it right now.

Textures are "naturally aligned", rather than tied to a specific brush.  
This means that if you build steps next to each other, the sides will not 
have any texture seams, no matter what size the brushes are.  If necessary, 
the texture plane on each brush face can be offset in multiples of 16 pixels, 
and the texture axis can be negated or interchanged.

Levels cary their own textures with them.  This bulks the file up, but it 
makes introducing new graphics much simpler.  We use a wadfile (similar 
to the DOOM format) to hold a palette of textures used to create a level.  
The worldspawn entity has a "wad" key that specifies the location of that 
file.  The bsp utility extracts the textures that are actually used from 
that, and puts them in the output .bsp file.  Quake never references the 
original wadfiles.

Axial planes, Entities, Lighting, Sealing the map ...

There is a small MAP file example. Note that this one does not describe the current MAP file format, as two floating point numbers have been added to each Plane definition. The Quake qtest1 release data structures are described in the current version of the Unofficial Quake Specs.

In an ealier e-mail, John Carmack provided some additional information on the utility suite used with QuakeEd and Quake:

- they run it on a 4 CPU alpha box with 128 MB RAM.
- The full map processing is actually three seperate programs:

  qbsp: which builds minimized drawing and clipping hulls from a solid geometry
        description of the world. This is the memory pig that can chew up 50+ 
        resident megs on big levels. Single threaded, but most levels only take 
        a minute or so to run.
  light: builds the surface lighting maps. Fully parallelel, generally taking a
        few minutes to make a high quality run, or less for a non-filtered 

  vis: builds the potentially visible set. Fully parallel. This is the CPU pig.
        It is wildly content dependant (combinatorially sensitve), so some 
        levels may only take a minute or so, but there is one level we have
        that takes nearly an hour even on 4 cpus.

During development, subsets of the suite are run, and only for full testing is
the vis program run.

home qdev qdev dread rsc qdev doom license web
home dEr95 r3D dread netrsc quake doom legal web
Author: B., email to bernd@nero.uni-bonn.de, with public PGP key
Copyright (©) 1995, 1996 by author. All rights reserved.
Source: $Id: qedit_info.html,v 1.3 1996/07/22 10:23:56 b1 Exp $