BSPZIP is a command-line tool that allows arbitrary files to be embedded within a BSP. When the map is being loaded the files will be mounted as if they were present in the game's real content folders.
While it is usually a good idea to BSPZIP content, there are times when it can cause problems and other times when it won't work at all (e.g. for Maplist Thumbnails). When this happens a resource list can be used instead.
BSPZIP is found at
"common\<gamename>\<gamefolder>\bin\bspzip.exe". It performs several functions:
Adding a list of files
The most common function. There are two related commands:
-addlist <input bsp> <file list> <output bsp> -addorupdatelist <input bsp> <file list> <output bsp>
Include file extensions. The former command packs all files in the list, the latter (untested, Orange Box only) packs only those that have changed since the last operation.
The 'file list' is a .txt file containing this pattern:
internal_path\file1 external_path\file1 internal_path\file2 external_path\file2 ...
- Internal paths ('relative paths') are the location the file will take within the BSP, e.g.
- External paths ('full paths') are the location of the file to be packed, e.g.
Adding a single file
The same principle as above, but without a file list.
-addfile <input bsp> <internal path> <external path> <output bsp>
Viewing and extracting files
If you have an archive tool installed that is able to look inside BSPs it's better to use that. If you don't, these are the commands you need:
-extract <bsp file> <output.zip> -extractfiles <bsp file> -dir <bsp file>
Should be self-evident:
-extractcubemaps <bsp file> <output folder> -deletecubemaps <bsp file>
Example of usage
Taken from Left 4 Dead Mapping
- Go to C:\Program Files (x86)\Steam\steamapps\common\left 4 dead 2\bin
- Create a new text file name it for example: customsBSPZIPPING.
- Open this file and copy paste this:
bspzip -addfile "%vproject%/maps/palacev3_6_night.bsp" "sound/cinema/lit_app_cin.wav" "%vproject%/sound/cinema/lit_app_cin.wav" "%vproject%/maps/palacev3_6_night.bsp"
- Just replace the two palacev3_6_night.bsp by your map name and the good path of your sound. Don't forgot .bsp and the .wav/.mp3 at the end.
- Save the file. Rename the .txt into a .bat
- (Later if you need to add others sound just open the .bat with notepad++ and correct the paths.)
- Run the .bat you created and voilà.
There are situations where files won't be loaded from BSP files correctly. As time goes on they become fewer in number, but it's always worth checking regardless. The easiest way to do so is moving all of the embedded content out of the game's folders -- or even better, not storing it there in the first place.
GUIs / Replacements
The following GUI tools are often preferred to BSPZIP directly, and may aid you in determining which files need to be packed into your map.
- Resource list (Alternative method to push content to users)
- GCFScape (Read-only tool for inspecting BSP contents)