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 information. 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. Texturing --------- 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
version.
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.
