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 (Source)

From ReverseEngineering.wiki
Format
Developer Valve
Versions 19-20 in SDK 2013 (BSPVERSION 20); older Source games use 17-19
Magic 56 42 53 50 ("VBSP") at offset 0
Extensions .bsp
Endianness little (Xbox 360 maps big endian)
On this wiki Facts · Code · Notes · Topics

Compiled map format of Valve's Source engine (VBSP, version 19-21 in the SDK 2013 era, 20 in most games): magic VBSP, a version, 64 lumps of (offset, length, lump version, uncompressed size) and a map revision, including an embedded ZIP (pakfile) and game lump with static props.

Identification

The file starts with the int32 'V','B','S','P' (bytes 56 42 53 50), then the int32 version. In the Source SDK 2013 public/bspfile.h MINBSPVERSION is 19 and BSPVERSION is 20. Quake and Quake II maps are different formats (Format:BSP (Quake), Format:BSP (Quake II)); Half-Life 1 uses version 30 of the Quake layout.

Header

dheader_t is int ident; int version; lump_t lumps[64]; int mapRevision; (8 + 64*16 + 4 = 1036 bytes). lump_t is 16 bytes: fileofs, filelen, version (per-lump format version, 0 default) and uncompressedSize (0 = stored raw; the field replaced an older, unused char fourCC[4], per the SDK comment at public/bspfile.h lines 374-383). Facts: Fact:BSP (Source)/struct/lump_t, Fact:BSP (Source)/struct/dheader_t. The GoldSrc predecessor is Format:BSP (GoldSrc).

Lump ids

0 entities (text), 1 planes, 2 texdata, 3 vertexes, 4 visibility, 5 nodes, 6 texinfo, 7 faces, 8 lighting, 9 occlusion, 10 leafs, 11 faceids, 12 edges, 13 surfedges, 14 models, 15 worldlights, 16 leaffaces, 17 leafbrushes, 18 brushes, 19 brushsides, 20 areas, 21 areaportals, 22-25 unused, 26 dispinfo, 27 originalfaces, 28 physdisp, 29 physcollide, 30 vertnormals, 31 vertnormalindices, 32 disp_lightmap_alphas, 33 disp_verts, 34 disp_lightmap_sample_positions, 35 game lump, 36 leafwaterdata, 37 primitives, 38 primverts, 39 primindices, 40 pakfile, 41 clipportalverts, 42 cubemaps, 43 texdata_string_data, 44 texdata_string_table, 45 overlays, 46 leafmindisttowater, 47 face_macro_texture_info, 48 disp_tris, 49 physcollidesurface (deprecated), 50 wateroverlays, 51 leaf_ambient_index_hdr, 52 leaf_ambient_index, 53 lighting_hdr, 54 worldlights_hdr, 55 leaf_ambient_lighting_hdr, 56 leaf_ambient_lighting, 57 xzippakfile (deprecated), 58 faces_hdr, 59 map_flags, 60 overlay_fades. Lump versions defined in the SDK: lighting 1, faces 1, occlusion 2, leafs 1, leaf ambient lighting 1.

Notes for readers

  • Lump 40 (pakfile) is an ordinary ZIP archive (look for PK\x03\x04/PK\x05\x06) holding files embedded in the map, such as custom materials, models and sounds; it can be read with any ZIP tool. Texture names are in lump 43 (string data) indexed by lump 44 (string table), not inline.
  • Lump 35 (game lump) is a directory dgamelumpheader_t {int lumpCount} followed by dgamelump_t {int id (four-CC); unsigned short flags; unsigned short version; int fileofs; int filelen}. Flag GAMELUMPFLAG_COMPRESSED = 1 means the stored length is the original size and the on-disk size is the distance to the next entry's offset. Static props are in the game lump with id sprp (GAMELUMP_STATIC_PROPS, version 10 in SDK 2013; read in public/gamebspfile.h lines 24-40): see Fact:BSP (Source)/struct/Static prop lump, Fact:BSP (Source)/enum/Static prop flags and Fact:BSP (Source)/enum/Game lump ids. Unverified: the order of the dictionary (128-byte model names), leaf list and prop array inside the lump body (from community documentation; the header only defines the records).
  • A non-zero uncompressedSize means the lump is compressed (the engine uses LZMA): the compressed block is a 17-byte lzma_header_t (id LZMA, u32 actualSize, u32 lzmaSize, 5 property bytes) followed by the LZMA stream, see Fact:BSP (Source)/struct/LZMA lump header. Compressed game lumps use GAMELUMPFLAG_COMPRESSED instead of uncompressedSize..
  • Leaf ambient lighting lumps (55/56) override part of the data in lump 10 (leafs).
  • Map limits from the SDK: 1024 models, 8192 brushes, 8192 entities, 65536 planes/nodes/leafs/faces/vertexes, 256000 edges, 512000 surfedges, 2048 displacement infos (power 2-4).
  • Build BSP_USE_LESS_MEMORY (Xbox 360) shrinks the limits and Xbox 360 maps are big endian.

Tools

VBSP, VVIS and VRAD are the compilers; Hammer is the editor (all in the SDK). The SDK header is the authoritative layout; third-party libraries (for example BSPSource and VBSP readers) follow it.

Code & repositories

  • https://github.com/ValveSoftware/source-sdk-2013 @ be57e3d01ac7d7aa6a2cacbfef187c0b46616db0 · license: LicenseRef-Source-SDK (declared by the contributor; GitHub's detector did not recognize LICENSE)
    Source SDK 2013: public/bspfile.h (BSP lumps), public/vtf/vtf.h and public/bitmap/imageformat.h (VTF), public/studio.h and public/optimize.h (MDL, VVD, VTX). Proprietary Source SDK license, not an open-source license.
    Tested on: source read, not run: source read, not built: headers at commit be57e3d · checked 2026-10-18; last activity 2026-10-10

Evidence & references

ValveSoftware/source-sdk-2013 src/public/bspfile.h at commit be57e3d (HEAD when read).