View source for BSPZIP

{{LanguageBar}}
{{src topicon}}
{{map compile pipeline|source1}}

{{toc-right}}
'''BSPZIP''' is a [[command-line]] tool that allows arbitrary files to be embedded within a [[BSP (Source 1)|BSP]]. When the map is being loaded the files will be mounted as if they were present in the game's real content folders.
{{tip|Several [[#GUIs/Replacements|GUI utilities]] have been created that may be more convenient than using BSPZIP directly.}}
{{tip|Embedded content can be examined with archive tools that support <tt>.zip</tt> by opening the BSP file.}}
{{bug|tested={{bms}}|Custom [[VMT]] files located in the root of {{path|materials/}} folder may fail to be packed into the BSP, use subfolders for custom materials.<br>example: {{path|materials/my_custom_materials/}}}}

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.

== Usage ==
BSPZIP is found at <tt>"common\<gamename>\bin\bspzip.exe"</tt>. 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.
{{tip|The input and output files can be the same.}}

The "file list" is a <tt>.txt</tt> 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., <tt>materials/metal/new_steel.vmt</tt>.
* External paths (absolute paths) are the location of the file to be packed, e.g., <tt>C:\Users\Public\our_maps\materials\metal\new_steel.vmt</tt>.

For example:
 materials/foo/bar.vtf
 D:\Steam\steamapps\common\Counter-Strike Source\cstrike\custom\stuff\materials\foo\bar.vtf
 materials/foo/bar.vmt
 D:\Steam\steamapps\common\Counter-Strike Source\cstrike\custom\stuff\materials\foo\bar.vmt
 sound/lorem/ipsum.mp3
 D:\Steam\steamapps\common\Counter-Strike Source\cstrike\custom\stuff\sound\lorem\ipsum.mp3

=== 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>

=== Handling Cubemaps ===
Should be self-evident:

 -extractcubemaps <bsp file> <output folder>
 -deletecubemaps <bsp file>
{{warning|<tt>-deletecubemaps</tt> actually deletes all <tt>.vtf</tt> files in the <tt>.bsp</tt>—handle with caution!}}
{{bug|(tested in {{src13mp}}){{code|-deletecubemaps}} may actually delete the entire PAKFILE lump, rendering the map broken! Use {{vide|4}} or {{vpkedit|4}} instead.}}

== Testing ==
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.

== Compression ==
{{only|{{src13mp}}{{strata}}{{jbep3}}}}
Repacking allows you to compress your map using {{w|LZMA}} to save hard drive space and download times. To repack a map and compress it, these commands are used:

 -repack -compress <bsp file>

To decompress repacked maps, run the same command but ommit the <code>-compress</code> command:

 -repack <bsp file>

{{warning|
* Repacked maps won't work in {{sfm|4.1}} and will crash the program on load!
* Map compression isn't supported by {{src13sp}}, but ''is'' supported by {{src13mp}}.}}

{{bug|tested={{tf2}} {{css}}|Map compression may sometimes result in packed [[ADPCM]] audio files not properly caching, resulting in improper playback on subsequent loads. This does not happen if the [[soundcache|audio cache]] was created when the BSP file was uncompressed, or when using other audio formats (8-bit, 16-bit, [[MP3]], etc). This also does not seem to occur when using {{tf2|4.1|addtext='s}} workshop uploader.
{{confirm|Can the map's audio cache be BSPZIPed once generated?}}
Since files which are flagged as streaming ({{code|<nowiki>*</nowiki>}} [[sound character]]) are not loaded from the cache, they are unaffected by this bug.}}
{{bug|[[ANI]] files will not load correctly from a compressed BSP.}}

{{note|
* Currently, the BSPZIP included with {{csgo}} Authoring Tools doesn't support repacking.
* {{tf2}} automatically compresses BSPs when uploading to the workshop.}}
{{tip|The map will need to be decompressed before BSPZIP will allow new files to be packed into the BSP.
{{workaround|[https://github.com/ficool2/map_batch_updater Ficool2's Map Batch Updater] can edit the contents of compressed BSPs, including changing the compression level of the ZIP lump. although the same compression level will apply to ''all'' packed files
{{modernConfirm|Can the ZIP lump in a compressed BSP be edited in some other way (using some other tool), allowing for custom levels of compression of different contained files? Perhaps using [[Lump file format|LMPFIX]]?<br>For example, the compression method used ({{wiki|LZMA}}) significantly impacts the load latency of audio files at high compression levels compared to faster methods.}}}}
}}

== GUIs/Replacements ==
The following GUI tools are often preferred to BSPZIP directly, and they may aid you in determining which files need to be packed into your map.
* {{compilepal|4}}
* [[Packbsp]]
* {{Map Analyst|4}}
* {{Pakrat|4}}
* {{vide|4}}
* {{vpkedit|4}}
* {{bspzipgui moltard|4}}(2020) - This app allows you to embed a folder with your files into BSP file, repack (compress and decompress) and can save different map configurations. It uses bspzip for the actual packing.
* [https://github.com/geotavros/BspZipGui BspZipGui](2016) - The app allows you to embed a folder with your files into BSP file in just a few clicks. It uses bspzip for the actual packing.
* {{autobspp|4}} - Automatically detects content that is used in the map and packs it. It has a GUI as well as a command line interface which makes it easy to add as a compile step in Hammer.
* [https://github.com/jackson-c/quickpack QuickPack] - This script quickly finds and packs all dependencies in a map. For models with different skins, it only packs used skins to save file space.
* {{teamspen|4}} - This includes a post-compiler which automatically finds and packs custom content, and adds entities to control auto-packing.

== See also ==
* [[Resource list]] (Alternative method to push content to users)
* [[GCFScape]] (Read-only tool for inspecting BSP contents)


[[Category:Official Source Tools]]