Format:BSP (Quake)
| Developer | id Software |
|---|---|
| Versions | 29 (Quake, QuakeWorld); BSP2 and 2PSB are later community extensions, not covered |
| Magic | 1D 00 00 00 (int32 version 29) at offset 0 |
| Extensions | .bsp |
| Endianness | little |
| On this wiki | Facts · Code · Notes · Topics |
Compiled map format of Software:Quake, version 29: a header of the version and 15 lumps (offset, length), holding the entity text, planes, textures, vertices, compressed visibility, BSP nodes, texture projections, faces, lightmaps, clip nodes, leaves, face lists, edges, signed edge lists and sub-models. Derived formats (Half-Life v30, Quake II IBSP) are not covered here.
Half-Life 1 maps (GoldSrc) use version 30 of this layout: see Format:BSP (GoldSrc).
Identification
The file starts with the int32 version 29 (1D 00 00 00) and has no text magic. The engine refuses any other value (Mod_LoadBrushModel: %s has wrong version number (%i should be 29)). Brush models of a map (doors, platforms) are sub-models inside the same file, referenced by entities as *1, *2, ...; ammo and health boxes (maps/b_*.bsp) are small standalone BSP files.
Structure
Header: version, then 15 {fileofs, filelen} pairs, 124 bytes in all. Every lump except entities, textures, visibility and lighting is an array of fixed-size records; filelen / record size gives the count.
| # | Lump | Record | Contents |
|---|---|---|---|
| 0 | entities | text | NUL-terminated ASCII, { "key" "value" ... } blocks; entity 0 is worldspawn
|
| 1 | planes | 20 bytes | normal, distance, axial type 0-5 |
| 2 | textures | variable | count, offsets, then miptex_t with four mip levels of 8-bit pixels
|
| 3 | vertexes | 12 bytes | 3 floats |
| 4 | visibility | variable | run-length compressed PVS rows |
| 5 | nodes | 24 bytes | plane, two children, bounding box (int16), face range |
| 6 | texinfo | 40 bytes | s and t projection vectors with offsets, miptex index, flags |
| 7 | faces | 20 bytes | plane, side, edge range, texinfo, 4 light styles, lightmap offset |
| 8 | lighting | bytes | 8-bit light samples |
| 9 | clipnodes | 8 bytes | plane, two children (negative = contents) for collision hulls |
| 10 | leafs | 28 bytes | contents, vis offset, bounding box, mark-surface range, 4 ambient levels |
| 11 | marksurfaces | 2 bytes | face indices, referenced by leaves |
| 12 | edges | 4 bytes | two vertex indices |
| 13 | surfedges | 4 bytes | signed edge indices; negative = edge used reversed |
| 14 | models | 64 bytes | bounds, origin, 4 hull head nodes, vis leaf count, face range |
Trees and hulls
- Node children are
int16: a non-negative value is a node index, a negative valuecmeans leaf-(c+1)(so -1 is leaf 0). - Leaf 0 is the shared solid leaf with no visibility data. Collision uses three more hulls (point, player, large monster sizes) stored as clip nodes; there a negative child is directly a
CONTENTS_*value. - Edge 0 is never used, because surfedge sign marks direction and -0 does not exist.
Visibility
Each leaf's visofs points into the visibility lump (or is -1). A row is decompressed as: a non-zero byte is copied, a zero byte is followed by a count of zero bytes to emit; the decompressed row has (numleafs + 7) >> 3 bytes. Bit i of the row means leaf i + 1 is potentially visible, because leaf 0 is excluded.
Lighting
A face's lightofs is a byte offset into the lighting lump; it stores one block of width x height samples per light style that is not 255, one byte each. Light map sample spacing is 16 texels; the block size follows from the face's texture-space extents ((extent >> 4) + 1 per axis).
Tools that read/write it
- Engine loader
Mod_LoadBrushModeland friends inWinQuake/model.c; the original compilers (qbsp, light, vis) were released separately by id. Modern compilers (ericw-tools) and editors (TrenchBroom) write the same version 29.
Code & repositories
- https://github.com/id-Software/Quake @
bf4ac424ce754894ac8f1dae6a3981954bc9852d· license: GPL-2.0-or-later (declared by the contributor; GitHub's detector did not recognize a license file)
GPL release of the Quake source (WinQuake/bspfile.h, common.c, pr_comp.h, modelgen.h, spritegn.h).
Tested on: source read, not run: source read · checked 2026-10-18; last activity 2024-06-15
Pitfalls
- Lump order in the file does not follow lump index order: in all 23 LibreQuake BSP files planes (lump 1) come first and the entity (0), visibility (4) and texture (2) lumps last. Always seek with
fileofs. - Texture data offsets are relative to the start of the textures lump, and an offset of -1 marks a missing texture.
- Node and leaf bounding boxes are
int16, face and mark-surface countsuint16: version 29 cannot describe very large maps, which is why BSP2 exists.
Evidence & references
- id Software Quake source,
WinQuake/bspfile.h(all on-disk structures,BSPVERSION, lump numbers, contents values),model.c(Mod_LoadBrushModel,Mod_DecompressVis),r_main.c(R_MarkLeaves: bitimaps toleafs[i+1]) at commit bf4ac42. - Runtime test: all 23 BSP files of LibreQuake v0.09-beta (
pak0.pakandpak1.pak, maps andb_*item boxes) have version 29 and lump lengths that are exact multiples of the record sizes above.