Pack Custom Content into a BSP: Textures, Models, Sounds

You pack your own textures, models and sounds into the BSP by writing them into the map's pakfile after the last compile, using a tool such as bspzip, CompilePal or VIDE. The engine then loads the files straight from the map, and players need no additional download for them. Without packing they see pink and black checkerboards instead of textures and red ERROR signs instead of models.

Why you should pack content

Besides geometry and lighting, a BSP contains a dedicated section for embedded files, the pakfile. Technically it is an archive inside the map. When the map loads, the engine treats its content as if the files were in the game folder. Garry's Mod sets a limit here: since the security patches of December 2023 it has checked embedded files against a whitelist, and whatever fails is not mounted. The console then shows BSP embedded file failed whitelist check. How a BSP is structured overall is explained in What is a BSP file?.

The alternative is to ship content separately, for example as an addon. That works but has more points of failure: a file is missing, an addon is not subscribed, a path is wrong. A packed map is a single file that looks the same everywhere.

What belongs in the BSP

Things that are easily forgotten:

• a model's materials, which live in a different folder than the model itself
• additional textures referenced by a VMT, such as normal maps
• custom skybox textures under materials/skybox/
• map-specific scripts such as soundscapes, and custom particle files

What does not belong in the BSP: content every player already has with the game, unused files and source files such as VMF, TGA or PSD.

The right folder structure

Inside the pakfile the same paths apply as in the game folder garrysmod/:

materials/yourname/yourmap/wall_concrete01.vmt
materials/yourname/yourmap/wall_concrete01.vtf
models/yourname/yourmap/lantern.mdl
sound/yourname/yourmap/hall_ambient.wav

Three rules spare you most problems:

1. Your own subfolder. A unique folder name means you do not overwrite files from other addons and do not get overwritten yourself.
2. Lowercase, no spaces, no special characters. Linux servers are case-sensitive. A path that works on Windows can fail there.
3. Check the paths in the VMT. A VMT refers to its VTF relative to materials/ and without a file extension. If you move files, you have to adjust the references.

Tools compared

With bspzip you pass a text file listing all files:

bspzip -addlist yourmap.bsp filelist.txt yourmap_packed.bsp
bspzip -dir yourmap_packed.bsp

The list consists of line pairs: first the path inside the map, below it the full path on your disk. The second command shows what is in the pakfile.

Automatic tools detect what the map uses directly. They can miss content that is only addressed at runtime, such as a sound that only a script plays. So always look at the list.

Packing in five steps

1. Do the final compile. Pack only once the map is finished. The process is described in VBSP, VVIS and VRAD explained.
2. Determine the content. Let the tool scan the map or write the list by hand.
3. Pack. Write into a copy of the BSP so the original is preserved.
4. Build cubemaps. Cubemaps are stored in the pakfile as well. Build them in the packed file.
5. Test. See below.

Important: every new compile produces a fresh BSP without your packed content. After every change to the map you pack again.

File size and compression

Of the packed content, textures usually account for the largest share. Choose resolutions that fit the size of the surface and save VTF files in a compressed format rather than uncompressed. Remove content you ended up not using and trim long sounds.

Transport usually adds compression on top: FastDL servers typically deliver maps as a compressed file, and the Workshop compresses on upload too. The size on disk is therefore not the download size. The help text of GMod's bspzip also lists -repack -compress, which compresses the BSP itself. In our test with the current GMod version, however, the command exited without any output and left the file unchanged, and the Valve Developer Community points to the bspzip from Team Fortress 2 instead. If you compress a map, do it as the very last step and test thoroughly whether game and server load it without issues.

Verify after packing

1. Temporarily rename your loose content folders in the game folder, or test on a second installation. Only then do you see what really comes from the BSP.
2. Load the map and look at every area. The console reports missing materials and models.
3. Compare the output of bspzip -dir with your list.
4. Upload the BSP to the Map Scanner. It lists embedded Lua and asset files in the pakfile and checks the structure of the file.

If checkerboards or ERROR models still show up, see Fix missing textures and error models.

Rights: only pack what you may redistribute

Whoever packs content into a BSP redistributes it along with the map. Only pack your own work and content whose licence allows redistribution. If you want to sell the map, the licence has to cover commercial use as well. An addon being free on the Workshop is not permission, and giving credit does not replace it. The same applies to content taken from other games. The basics are covered in GMod map copyright basics. This section is not legal advice.

FAQ

Do I have to pack again after every compile?

Yes. VBSP writes a new BSP on every run, and the pakfile of the old file is lost. Pack only after the last compile and build the cubemaps afterwards.

Why do I still see pink and black checkerboards after packing?

Usually a path is wrong. Either the file sits in a different place in the pakfile than the map expects, or the VMT was packed but its VTF was not. With models the materials are often missing because they live in a different folder.

Can packed content be extracted from the BSP again?

Yes. The pakfile is an ordinary archive, and the same tools that pack can also unpack. Packing is a matter of delivery, not protection for your content.

How large may a packed map be?

We cannot confirm a fixed upper limit for the whole file in GMod. In practice it depends on how the map is distributed. The larger the file, the longer players wait when they first join. For packed content, economical textures are therefore usually the most effective lever.