|
|
| Line 1: |
Line 1: |
| __TOC__
| | {{toc-right}} |
| The [[BSP]] maps used in [[Source]] engine can have embedded custom materials and models. '''Bspzip''' is a command-line utility that allows level designers to embed, extract, and list game content in .BSP files, simplifying the distribution of custom map content.
| |
|
| |
|
| The <code>bspzip.exe</code> application can be used in four separate modes, with the following syntax:
| | '''BSPZIP''' is a command-line tool that allows arbitrary files to be embedded within a BSP map file. When the map is being loaded the files will be mounted as if they were present in the game's real content folders. |
|
| |
|
| <pre>
| | {{tip|Embedded content can be examined with archive tools that support .zip by opening the BSP file.}} |
| bspzip -dir bspfile
| |
| bspzip -addfile bspfile relativepathname fullpathname newbspfile
| |
| bspzip -addlist bspfile listfile newbspfile
| |
| bspzip -extract bspfile files.zip
| |
| </pre>
| |
|
| |
|
| == Basic usage ==
| | 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 [[Quicklist thumbnails]]). A [[resource list]] can be used at these times instead. |
| The Windows environment variable <code>"%sourcesdk%"</code> can be utilized to locate <code>bspzip.exe</code> 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 <code>"dm_lockdown.bsp"</code>, you would open a command prompt, change to the directory to <code>"half-life 2/hl2/maps"</code> and type this at the command-line:
| | == Usage == |
|
| |
|
| <pre>
| | {{note|Remember to set the appropriate [[VPROJECT]] before starting to use the tool.}} |
| "%sourcesdk%\bin\bspzip" -dir dm_lockdown.bsp
| |
| </pre>
| |
|
| |
|
| {{note|For Orange Box games the path is "%sourcesdk%\bin\orangebox\bin\bspzip" rather than "%sourcesdk%\bin\bspzip".}}
| | BSPZIP is found at <code>"%sourcesdk%\bin\[orangebox|ep1]\bin\bspzip.exe"</code>. It performs several functions: |
|
| |
|
| This will generate a list of files embedded into the .BSP file, like this:
| | === Adding a list of files === |
|
| |
|
| <pre>
| | The most common function. There are two related commands: |
| 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
| |
| ...
| |
| </pre>
| |
|
| |
|
| In this case, all of the cubemap materials used in <code>dm_lockdown.bsp</code> are listed.
| | -addlist <input bsp> <file list> <output bsp> |
| | -addorupdatelist <input bsp> <file list> <output bsp> |
|
| |
|
| {{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.}}
| | The former command packs all files in the list, the latter (untested) packs only those that have changed since the last operation. In both cases it is possible for the input and output files to be the same. |
|
| |
|
| == Embedding individual files ==
| | The 'file list' is a .txt file containing this pattern: |
| Using the <code>-addfile</code> command with Bspzip allows you to add an individual file to the .BSP. The syntax is:
| |
|
| |
|
| <pre>
| | internal_path\file1 |
| bspzip -addfile bspfile relativepathname fullpathname newbspfile
| | external_path\file1 |
| </pre>
| | internal_path\file2 |
| | external_path\file2 |
| | ... |
|
| |
|
| where <code>bspfile</code> is the original map file; <code>relativepathname</code> is the file to be added, expressed as a path relative to the game directory; <code>fullpathname</code> is the same file, expressed as an absolute path; and <code>newbspfile</code> is the name of the resulting map file.
| | * Internal paths ('relative paths') are the location the file will take within the BSP, e.g. <code>materials\metal\new_steel.vmt</code>. |
| | * External paths ('full paths') are the location of the file to be packed, e.g. <code>C:\Users\Public\our_maps\materials\metal\new_steel.vmt</code>. |
|
| |
|
| For example, if you had a .VMT at <code>"/half-life 2 deathmatch/hl2mp/materials/metal/sample.vmt"</code> that you wished to embed into a map called <code>"dm_mymap.bsp"</code>, you would type this at the command-line:
| | === Adding a single file === |
|
| |
|
| <pre>
| | The same principle as above, but without a file list. |
| "%sourcesdk%\bin\bspzip" -addfile dm_mymap.bsp "materials/metal/sample.vmt" "%vproject%/materials/metal/sample.vmt" dm_mymap.bsp
| |
| </pre>
| |
|
| |
|
| This would read the map <code>"dm_mymap.bsp"</code>, add <code>"materials/metal/sample.vmt"</code>, and output the result back into the original file <code>"dm_mymap.bsp"</code>. The environment variable <code>"%vproject%"</code> was used to locate the game directory.
| | -addfile <input bsp> <internal path> <external path> <output bsp> |
|
| |
|
| == Embedding a list of files == | | === Viewing and extracting files === |
| Using the <code>-addlist</code> command with Bspzip allows you to add a number of files specified in a .TXT file list:
| |
|
| |
|
| <pre>
| | 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: |
| bspzip -addlist bspfile listfile newbspfile
| |
| </pre>
| |
|
| |
|
| The list file uses a similar format to the <code>-addfile</code> 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:
| | -extract <bsp file> <output.zip> |
| | -extractfiles <bsp file> |
| | -dir <bsp file> |
|
| |
|
| <pre>
| | === Handling cubemaps === |
| relativepath/file1
| |
| absolutepath/file1
| |
| relativepath/file2
| |
| absolutepath/file2
| |
| ...
| |
| </pre>
| |
|
| |
|
| For example, if you had several .VMT files in <code>"/half-life 2 deathmatch/hl2mp/materials/metal/"</code> that you wished to embed, you would create a list file like this in a text editor:
| | Should be self-evident: |
|
| |
|
| <pre> | | -extractcubemaps <bsp file> <output folder> |
| materials/metal/sample.vmt
| | -deletecubemaps <bsp file> |
| 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
| |
| </pre> | |
|
| |
|
| 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.
| | == Testing == |
|
| |
|
| If you wanted to add files in a list called <code>"addmaterials.txt"</code> to a .BSP called <code>"dm_mymap.bsp"</code>, you would type this at the console:
| | 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. |
|
| |
|
| <pre>
| | == See also == |
| "%sourcesdk%\bin\bspzip" -addlist dm_mymap.bsp addmaterials.txt dm_mymap.bsp
| |
| </pre>
| |
|
| |
|
| This would read the map <code>"dm_mymap.bsp"</code>, add all the files referenced in <code>"addmaterials.txt"</code> and output the result back into the original file <code>"dm_mymap.bsp"</code>. Bspzip generates the following output when this command is executed:
| | * [[Resource list]] |
| | | * [[GCFScape]] (for extraction only) |
| <pre>
| |
| 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
| |
| </pre>
| |
| | |
| == Extracting files ==
| |
| You can extract content embedded in a .BSP file with Bspzip using the following syntax:
| |
| | |
| <pre>
| |
| bspzip -extract bspfile files.zip
| |
| </pre>
| |
| | |
| This will create a new .ZIP format file that contains all of the embedded content in the .BSP you specify. For example:
| |
| | |
| <pre>
| |
| "%sourcesdk%\bin\bspzip" -extract dm_mymap.bsp dm_mymap_content.zip
| |
| </pre>
| |
| | |
| This would create a file called <code>"dm_mymap_content.zip"</code> that contains all of the embedded files in <code>"dm_mymap.bsp"</code>. 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 <code>bspzip -dir</code> 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.
| |
| | |
| == Similar applications ==
| |
| * [[GCFScape]] - extraction only. | |
| * [[Map Analyst]] | | * [[Map Analyst]] |
| * [[Pakrat]] | | * [[Pakrat]] |
| * [[WinBSPZip]] - a GUI frontend for Bspzip.
| |
| {{note|WinBSPZip is no longer compatible with current map format (since August 2006 SDK update).}}
| |
|
| |
|
| [[Category:Level Design]] | | [[Category:Level Design]] |
| [[Category:Tutorials]]
| |
| [[Category:Tools]] | | [[Category:Tools]] |
BSPZIP is a command-line tool that allows arbitrary files to be embedded within a BSP map file. When the map is being loaded the files will be mounted as if they were present in the game's real content folders.
Tip:Embedded content can be examined with archive tools that support .zip by opening the BSP file.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 Quicklist thumbnails). A resource list can be used at these times instead.
Usage
Note:Remember to set the appropriate VPROJECT before starting to use the tool.BSPZIP is found at "%sourcesdk%\bin\[orangebox|ep1]\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>
The former command packs all files in the list, the latter (untested) packs only those that have changed since the last operation. In both cases it is possible for the input and output files to be the same.
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.
materials\metal\new_steel.vmt.
- External paths ('full paths') are the location of the file to be packed, e.g.
C:\Users\Public\our_maps\materials\metal\new_steel.vmt.
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>
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.
See also