Patching levels with lump files

Half-Life 2: Episode One added a simple system to allow mapmakers to patch levels by shipping only the level lumps that have changed. It was written to handle any .bsp file lump, but right now it's really only useful for lumps that don't depend on other lumps, until a tool exists that will find all the changed lumps. For example, changing geometry in a map changes many lumps, and each changed lump would need to be selected by hand. Once many lumps have been changed, you may as well ship a new .bsp.

For now, it's a great way of shipping new entity lumps, or new game data lumps without having to re-ship the entire .bsp.

Creating and using new lumps

The steps involved are as follows (assuming that a previous version of the .bsp file has already been shipped):

1. Make a backup copy of the current .bsp.
2. Make the desired changes to the level, and compile a new (revised) .bsp.
3. Use "%sourcesdk%\bin\vbspinfo" -X bspname to extract the entity lump into a .lmp file.

   Note:The .lmp file will be created in the same directory as the input .bsp.

4. Put the .lmp files into your gamedir\maps directory (if they aren't already), and ensure their <id> numbers are correct (see below).
5. Make a backup copy of the revised .bsp.
6. Restore the backup of the old .bsp, and run the map to test it with the new .lmp. Make sure it works properly with the updated entities.
7. Ship the .lmp files only.

ID numbers

.lmp files are automatically named in the following format:

<bsp name>_l_<id>.lmp

After loading the .bsp, the engine will then load .lmp files starting at id 0, and stopping as soon as it fails to find a .lmp for the next id. Each .lmp file overrides any existing lump in the .bsp, or preceding .lmp files. If a new lump has already been shipped as a <bsp_name>_l_0.lmp file, that lump can overridden with a <bsp_name>_l_1.lmp file.

A list of known lump IDs can be found here.

Hammer compile profile

The following lines of code can be entered into Hammer's advanced compile dialogue to automate lump creation:

$bsp_exe
-game $gamedir -onlyents -keepstalezip $path\$file

C:\Program Files\Steam\steamapps\<Steam account name>\sourcesdk\bin\vbspinfo
-x $path\$file.bsp

Copy File
$path\$file_l_0.lmp $bspdir\$file_l_0.lmp

Delete File
$path\$file_l_0.lmp

If you are creating a lump file with an ID other than zero, change the last two commands accordingly.

Note also that a Hammer bug currently prevents the use of $SteamUserDir or %sourcesdk% in the second command; using either will lead to "access denied" error messages.

Lump file format

Each .lmp file contains a 20 bytes long header before the actual lump data. It contains some information about the lump that were stored in the .bsp file before extraction.

struct lmpheader_t
{
	int	lumpOffset;  // offset in the file where the lump data begins (should be 0x14)
	int	lumpId;      // the lump ID according to the lump table
	int	lumpVersion; // same as "version" in lump_t	
	int	lumpSize;    // same as "filelen" in lump_t
	int	mapRevision; // same as in dheader_t
};

Tip:It is possible to edit an extracted entity lump with a plain text editor, if the lumpSize field is corrected afterwards. lmpfix, a third-party tool, is available to automate the process.

See also

• Source BSP File Format