Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:BSP (Quake)

From ReverseEngineering.wiki
Format
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 value c means 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_LoadBrushModel and friends in WinQuake/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 counts uint16: 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: bit i maps to leafs[i+1]) at commit bf4ac42.
  • Runtime test: all 23 BSP files of LibreQuake v0.09-beta (pak0.pak and pak1.pak, maps and b_* item boxes) have version 29 and lump lengths that are exact multiples of the record sizes above.