Difference between revisions of "BSPZIP"
|Line 154:||Line 154:|
* [[Map Analyst]]
* [[Map Analyst]]
Revision as of 02:40, 2 November 2006
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.
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
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.
Embedding individual files
-addfile command with bspzip allows you to add an individual file to the BSP. The syntax is:
bspzip -addfile bspfile relativepathname fullpathname newbspfile
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
"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
-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
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.
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
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.