Unofficial Quake 3 Map Specs

This document describes the Quake 3 BSP file format. This is an unofficial document. Quake 3 is a registered trademark of id Software, which does not sponsor, authorize, or endorse this document.

This document describes the Quake 3 BSP file format as the author understands it. While every effort has been made to ensure that the contents of this document are accurate, the author does not guarantee that any portion of this document is actually correct. In addition, the author cannot be held responsible the consequences of the any use or misuse of the information contained in this document.

Copyright © 2000 Kekoa Proudfoot. All rights reserved.

File structure

Quake 3 BSP files are IBSP files, and therefore have a structure similar to previous BSP files from id Software. Every IBSP file begins with a header, which in turn contains a lump directory. The lump directory describes the layout of the rest of the file, which contains some number of lumps. Each lump stores a particular kind of map data.

Header / Directory Lump Lump Lump ... The layout of an IBSP file. An IBSP file consists of a header followed by a number of lumps. The header contains a directory which identifies the locations and sizes of the lumps.

Data types

Quake 3 BSP files contains only four basic data types. They are:

Type Description ubyte unsigned byte int 4-byte integer, little-endian float 4-byte IEEE float, little-endian string[n] string of n ASCII bytes, not necessarily null-terminated

All data in a BSP file is organized into records composed of these four data types. Header and Directory The header record looks like this: header string[4] magic Magic number. Always "IBSP". int version Version number. 0x2e for the BSP files distributed with Quake 3. direntry[17] direntries Lump directory, seventeen entries. Each direntry locates a single lump in the BSP file: direntry int offset Offset to start of lump, relative to beginning of file. int length Length of lump. Always a multiple of 4. Lumps There are 17 lumps in a Quake 3 BSP file. In the order that they appear in the lump directory, they are:

Index Lump Name Description 0 Entities Game-related object descriptions. 1 Textures Surface descriptions. 2 Planes Planes used by map geometry. 3 Nodes BSP tree nodes. 4 Leafs BSP tree leaves. 5 Leaffaces Lists of face indices, one list per leaf. 6 Leafbrushes Lists of brush indices, one list per leaf. 7 Models Descriptions of rigid world geometry in map. 8 Brushes Convex polyhedra used to describe solid space. 9 Brushsides Brush surfaces. 10 Vertexes Vertices used to describe faces. 11 Meshverts Lists of offsets, one list per mesh. 12 Effects List of special map effects. 13 Faces Surface geometry. 14 Lightmaps Packed lightmap data. 15 Lightvols Local illumination data. 16 Visdata Cluster-cluster visibility data.

Known Issues and Missing Items [top]

This document is very brief. I have gathered more information, but have not had time to write it up. Occasionally, I add more information to this document.

At some point I put together a page that describes triangle meshes and other q3 leaf elements. I forget the exact reason I created that page, but you might find it interesting.

Feel free to ask for clarification, but please accept my apologies if I can't find the time to answer.

Copyright © 2000 Kekoa Proudfoot. All rights reserved.