What Is a BSP File? Header, Lumps and Pakfile Explained

A BSP file is the compiled, ready-to-play version of a map for the Source engine, and therefore for Garry's Mod. It is produced when the compilers take the editable VMF file from the Hammer editor and calculate geometry, visibility and lighting. The file contains almost everything a server and its players need to load the map: geometry, entities, lightmaps and often embedded textures, models and sounds.

What BSP stands for and how the file is created

BSP means Binary Space Partitioning. It is a technique that splits the space of a map into a tree of smaller regions. The engine uses that tree to decide quickly what is visible and what a player collides with.

You build a map in Hammer as a VMF file. That is a text file you can keep editing at any time. Compiling runs three programs in sequence: VBSP creates geometry and entities, VVIS calculates visibility, VRAD calculates light. The article VBSP, VVIS and VRAD explained covers the three steps in detail. The result is a single binary file ending in .bsp that is optimised for loading, not for editing.

The structure: header and lumps

Every BSP starts with a header. It contains:

• the identifier VBSP, which tells tools this is a Source map
• the format version number (usually 20 for Garry's Mod)
• a directory with 64 entries, the lump table
• the map revision, meaning how often the VMF was saved before compiling

A lump is a block of data with a fixed job. For each block, the lump table states where in the file it starts and how long it is. Not all 64 slots are used. The most important groups:

If a table entry is wrong, for example because a block reaches past the end of the file, the file is damaged. This happens with interrupted uploads, for example.

The entity lump: plain text inside a binary file

The entity lump is ordinary text. Each entity is a block in curly braces made of key and value pairs:

{
"classname" "info_player_start"
"origin" "0 0 64"
"angles" "0 90 0"
}

The first entity is always worldspawn, which holds the basic settings of the map such as the skybox name. After that come point entities like spawns, lights and logic, and brush entities like doors and triggers. The connections between entities (inputs and outputs) are stored here as text too.

Some entities are not in the entity lump, because the compiler absorbs them: prop_static ends up in the game lump, for example, and func_detail becomes part of the world geometry.

Because the lump is plain text, anyone can read it with simple tools. That affects the names and logic of your map, and it affects security: a lua_run entity runs Lua code on the server, while point_servercommand, which issues console commands in other Source games, is disabled in Garry's Mod. Before you put someone else's map on your server, it is worth looking at this section.

The pakfile: custom content inside the map

The pakfile lump is a ZIP archive inside the BSP. It holds files the map brings along: materials, textures, models, sounds. When loading, the engine treats them as if they were in the game folder. The engine writes to it as well, for example the cubemap textures created by buildcubemaps.

The pakfile is filled with Valve's BSPZIP tool or with utilities such as Pakrat, VIDE or CompilePal. The article Pack custom content into a BSP shows how to do that.

Everything in the pakfile is delivered to every player. That affects file size, and it means that files packed by accident become public.

How to open a BSP file

• Hammer does not open BSP files, only VMF. To go back you need a decompiler such as BSPSource. BSP decompiling explained describes what you get from that.
• Viewing the pakfile: VIDE, Pakrat or GCFScape show the embedded files.
• Reading entities: an entity editor such as Entspy, or a text or hex editor if need be, shows the entity lump.
• Automated checks: the Map Scanner on bspmarket.de checks the header, lump table and offsets for consistency, finds risky entities and lists the files in the pakfile.

Why the structure matters for troubleshooting and protection

Many typical problems can be traced to one part of the file. If a material is neither in the game folder nor in the pakfile, you see the familiar checkerboard pattern. If a lump exceeds an engine limit, the compile fails or the map does not load. If you know which section is responsible for what, you find the cause faster.

One property is decisive for protecting a map: the engine has to be able to read the file, and every player who joins your server receives it. A BSP therefore contains nothing that stays secret for long. Protection measures work on the structure. A fingerprint makes a copy traceable, obfuscation reduces information that is only useful to an editor. Protect your GMod map from leaks gives the overview.

FAQ

Can I open a BSP file directly in Hammer?

No. Hammer works with VMF files. A BSP has to be decompiled first, and the result is a reconstruction, not the original working file.

Is a BSP file encrypted?

No. The format is well known and read by many tools. The entity lump is plain text and the pakfile is a ZIP archive. According to the Valve wiki, GMod also loads maps whose lumps and pakfile contents are LZMA-compressed; that is compression, not encryption.

Why is my BSP file so large?

Usually because of the lightmaps, which a compile for LDR and HDR stores twice, and because of the pakfile with embedded textures, models, sounds and cubemaps. The lump table shows which block dominates, and the pakfile listing shows which files take up the space.

Which BSP version does Garry's Mod use?

Maps built with the usual compile tools for Garry's Mod carry version 20. The number sits in the header right after the identifier. According to the Valve wiki, GMod's engine also reads version 21. Other Source games use different versions in some cases, and even maps with the same number are not freely interchangeable between games.