BSPZIP

From Valve Developer Community
Revision as of 02:40, 2 November 2006 by Nem (talk | contribs) (→‎Alternative Programs)

Jump to: navigation, search

Source engine .BSP format maps can contain embedded custom materials and models that are unique to that map. Bspzip is a command-line utility that allows MOD and map-makers to embed, extract, and list game content in .BSP files. This allows for easier distribution of custom map content.

The bspzip.exe application can be used in four separate modes, with the following syntax: 

bspzip -dir bspfile
bspzip -addfile bspfile relativepathname fullpathname newbspfile
bspzip -addlist bspfile listfile newbspfile
bspzip -extract bspfile files.zip

Basic usage

The Windows environment variable "%sourcesdk%" can be utilized to locate bspzip.exe easily in a command-line statement. This variable contains the location of the Source SDK installation directory.

For example, to list all of the embedded contents of a Half-Life 2 Deathmatch map called "dm_lockdown.bsp", you would open a command prompt, change to the directory to "half-life 2/hl2/maps" and type this at the command-line: 

"%sourcesdk%\bin\bspzip" -dir dm_lockdown.bsp

This will generate a list of files embedded into the .BSP file, like this: 

materials/maps/dm_lockdown/tile/tilewall009b_-3792_3120_72.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-3488_2752_80.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-3488_3104_72.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-3192_3120_72.vmt
materials/maps/dm_lockdown/tile/tilewall009b_-2944_3136_72.vmt
...

In this case, all of the cubemap materials used in dm_lockdown.bsp are listed.

Note:It is very important that you set the Current Game in either the SDK Launcher or VConfig to the correct game directory before you open a command prompt to compile textures. Changing the Current Game will not affect any command prompt windows that are already open. This is due to how Windows uses environment variables.

Embedding individual files

Using the -addfile command with bspzip allows you to add an individual file to the BSP. The syntax is: 

bspzip -addfile bspfile relativepathname fullpathname newbspfile

where bspfile is the original map file; relativepathname is the file to be added, expressed as a path relative to the game directory; fullpathname is the same file, expressed as an absolute path; and newbspfile is the name of the resulting map file.

For example, if you had a .VMT at "/half-life 2 deathmatch/hl2mp/materials/metal/sample.vmt" that you wished to embed into a map called "dm_mymap.bsp", you would type this at the command-line: 

"%sourcesdk%\bin\bspzip" -addfile dm_mymap.bsp "materials/metal/sample.vmt" "%vproject%/materials/metal/sample.vmt" dm_mymap.bsp

This would read the map "dm_mymap.bsp", add "materials/metal/sample.vmt", and output the result back into the original file "dm_mymap.bsp". The environment variable "%vproject%" was used to locate the game directory.

Embedding a list of files

Using the -addlist command with bspzip allows you to add a number of files specified in a .TXT file list: 

bspzip -addlist bspfile listfile newbspfile

The list file uses a similar format to the -addfile command -- a path relative to the game directory, as well as an absolute path to the files you wish to add. The file should list the relative and absolute path for each file, like this: 

relativepath/file1
absolutepath/file1
relativepath/file2
absolutepath/file2

...

For example, if you had several .VMT files in "/half-life 2 deathmatch/hl2mp/materials/metal/" that you wished to embed, you would create a list file like this in a text editor: 

materials/metal/sample.vmt
C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample.vmt
materials/metal/sample.vtf
C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample.vtf
materials/metal/sample2.vmt
C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample2.vmt
materials/metal/sample2.vtf
C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample2.vtf

It is important to leave a line break after the last file, or it will not be added. Save the file in the maps directory (where the .BSP is located). It can be placed anywhere, but it's most convenient to find it in this location.

If you wanted to add files in a list called "addmaterials.txt" to a .BSP called "dm_mymap.bsp", you would type this at the console: 

"%sourcesdk%\bin\bspzip" -addlist dm_mymap.bsp addmaterials.txt dm_mymap.bsp

This would read the map "dm_mymap.bsp", add all the files referenced in "addmaterials.txt" and output the result back into the original file "dm_mymap.bsp". The bspzip application should generate the following output when this command is executed: 

Opening bsp file: C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/maps/dm_mymap.bsp
Adding file: C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample.vmt
Adding file: C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample.vtf
Adding file: C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample2.vmt
Adding file: C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/materials/metal/sample2.vtf

Writing new bsp file: C:/Program Files/Valve/Steam/SteamApps/username/half-life 2 deathmatch/hl2mp/maps/dm_mymap.bsp

Extracting files

You can extract content embedded in a .BSP file with bspzip using the following syntax: 

bspzip -extract bspfile files.zip

This will create a new .ZIP format file that contains all of the embedded content in the .BSP you specify. For example: 

"%sourcesdk%\bin\bspzip" -extract dm_mymap.bsp dm_mymap_content.zip

This would create a file called "dm_mymap_content.zip" that contains all of the embedded files in "dm_mymap.bsp". The .ZIP file can now be opened and decompressed to examine the contents.

Scripting

To automate the process of adding files to a map, save the following as a .bat file: 

"%sourcesdk%/bin/bspzip.exe" -addlist <BSP NAME> <.TXT FILE LIST> <NEW BSP NAME>
pause

You will need to fill in the values in brackets. Then whenever you want to update the existing zipped content in your map, run the file.


To view files within a map with a script, save the following as a .bat file: 

"%sourcesdk%/bin/bspzip.exe" -dir %1
pause

Drag any map over it and it's contents will be displayed.

Testing and Conclusion

Note:You can add custom model content using the same method. Just make sure you add all of the relevant model files (.MDL, .VTX, .PHY, etc.) as well as any materials that the models have referenced.

Once you're done adding custom content to the .BSP files, it's also important to test to make sure you've added all of the necessary files. One way to do this is to move the necessary content files (models, materials) out of their proper directory into another directory temporarily. Then, launch the game and load the map. If you've done things correctly, the content should still appear in the map, since they are now loaded from inside the .BSP file instead of the materials or models directory. This is an accurate simulation of what another user loading your map would experience.

If some of the content does not load correctly, and you receive error messages that files are missing in the console, go back and check your process and make sure you made no mistakes when you added the files. Using the bspzip -dir command to list the contents of your .BSP file can be useful to find errors, such as an improper directory path.

Once you've tested for errors, you can restore the content back to the proper locations and you're ready to distribute your .BSP file.

Alternative Programs

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=BSPZIP&oldid=58517"