Embedding Files into BSPs with PakRat

03-05-2007, 06:26 AM
Let's say you take the time to create custom textures, sprites, sounds, materials, decals, etc... and bring them into hammer. Yet, when you compile your map and give it to others for testing your custom stuff ends up looking like a pink checkerboard. :( No doubt you've seen the pink checkerboard in other maps and games using the source engine. Of course you know it's a missing texture or whatever but did you assume it was somehow your fault as the player? Don't be silly of course it's not your fault. It's the map designer's fault.

Here is all you need to know so that your map doesn't fall prey to the gruesome ghoul that is called the pink checkerboard.

What you'll need:
PakRat for Source - http://www.geocities.com/cofrdrbob/pakrat.html

PakRat is a post compile process for embedding your custom materials into your map for purposes of distribution.
You should not do this process until you are ready to distribute your map for public consumption. It is ok to give out your map with missing textures to your friends for testing purposes. I'm sure they'll understand and know what the deal is as tests need to be repeated many times prior to a finalization.

I've used BSPZip and BSPZipGUI. Both are extremely basic, hard to use, and inefficient. PakRat will make your life a whole lot easier.
Unfortunately there is zero documentation out there for it's usage. The program is simple enough but I did hit a snag and needed help, there was none, and this is the explanation of the self-discovery. I hope this will clear some things up with it's usage. Once you learn how to use it properly you can add all the textures and models into your map within seconds.

Embedding Files into BSPs with PakRat - By LG Devil

Though this tutorial might be long winded the actual process takes seconds so please don't be put off or intimidated by the length of this tutorial.

Step 1. Open up PakRat using the pakrat.bat file. PakRat requires JAVA. Without JAVA it will not run.
PakRat Tutorial Image 1 (http://www.legendarygamers.net/modules/coppermine/albums/userpics/10002/pakrat-1.jpg)

Step 2. You should be see a dos screen quickly followed by a java screen then finally a window explorer expecting you to select the bsp you want to post process. Select your bsp.
For this example I'll be working with my map Legendary_Gamers_Range. Usually your map will be labeled dod_mymap.bsp in all lowercase. I'm using this as an example what to do for capitialized bsp titles as well.
PakRat Tutorial Image 2 (http://www.legendarygamers.net/modules/coppermine/albums/userpics/10002/pakrat-2.jpg)

Step 3. Your white java console should start spitting out the map information such as visleafs etc... You can ignore all of that really. What you are looking for is the new console that popped up with your map information. You may or may not see the default cubemapdefault.vtf.
PakRat Tutorial Image 3 (http://www.legendarygamers.net/modules/coppermine/albums/userpics/10002/pakrat-3.jpg)

Step 4. Here's the easy part. PakRat allows drag and drop capability or the ability to use the "add" button to get all of your textures etc.. into your bsp. You can do either method however from my experience neither of those methods work for filenames using capitialization. Ahh now you see why I mentioned that in step 2. I recommend naming all of your maps in lowercase simply to avoid the confusion here. I'm covering both because using caps can cause some path errors of which I'll address here. The recommended and quickest method is this little magical button called AUTO. It will search your steam directory for any filenames matching your BSP filepath name. If you notice any missing add them in manually and make sure to get the filepaths and filenames in the same capitialization structure. Once it's found all the files it can go ahead and select yes to add them to the bsp.

You'll want to include both your vmt and vtf files. Make sure your vtf text files have the correct relative path to the texture. PakRat does a good job of working with you on getting the paths right.
PakRat Tutorial Image 4 (http://www.legendarygamers.net/modules/coppermine/albums/userpics/10002/pakrat-4.jpg)

Step 5. You should now have a list of all your custom textures, sounds, sprites, etc.. that you want to have added to the final version of your map. Without them no one will see your customized stuff. Instead it will most likely show up as pink and black checkerboard patterns throughout your map.

I've highlighted the soundcache file and will delete it. You don't need a soundcache file included because the map will create one for the user when they run the game if it's needed. You can tell PakRat not to look for soundcache or any other file actually from within it's preferences. The preference options for PakRat are very basic and straightforward.
PakRat Tutorial Image 5 (http://www.legendarygamers.net/modules/coppermine/albums/userpics/10002/pakrat-5.jpg)

Now you'll notice that if you were to drag and drop or add files manually instead of using AUTO all of the filenames and filepaths would be lowercase. If your map name includes capitilization that's a bad thing right? Indeed it is. So with AUTO it will work regardless, why I don't know, but it does. My actual filename and file path is Legendary_Gamers_Range not LEGENDARY_GAMERS_RANGE or legendary_gamers_range. With AUTO though PakRat was able to somehow get it all right so I've learned to ignore it. If anyone knows why PakRat does this please let me someone here know so the tutorial can be modified. From my experience and what I recommend, AUTO is definitely the way the to go.

Step 6. Confirm that you have everything in there that you need included with the public consumption version of your map. Go to File-Save BSP and save it where you want. You can overwrite your bsp if you would like or save final bsps into their own directory for safe storage.

Close out of PakRat, open it up again and check your bsp. You'll now see that everything is packaged in the bsp. The checkbox noted as "in" confirms that your materials are "in" the bsp.

As you can see the whole process is quick and extremely efficient. If you have all of your files come up when doing AUTO you can get the whole post process done in seconds! Now when you distribute your map to your friends, your game server, or mapping community everything is included with the bsp that should be.

03-05-2007, 11:25 AM
nice tut! you may also want to point out that the .bsp absolutely must be in the dod/maps dir. If not, you can add the textures all you like, even manually, but they just won't show up.

way to keep the tutorials section alive ;).

Day of Defeat Forum Archive created by Neil Jedrzejewski.

This in an partial archive of the old Day of Defeat forums orignally hosted by Valve Software LLC.
Material has been archived for the purpose of creating a knowledge base from messages posted between 2003 and 2008.