This guide will explain how to pack custom content into your map so others can see it. You will learn how to use the Expert Compile window in Hammer, how to use the Autopack feature of vbsp, and learn more compile options.

Please see further down for technical information and the FAQ.

If you're an advanced mapper who already understands the packfile and Expert Compile, please see the Quickstart section for what you need to know!

I already know what a packfile is, and how to use Expert Compile, how do I use the autopack feature in vbsp?

• Move all the custom content that you used in your map from the KreedzClimbing/kz folders to KreedzClimbing/kz/hammer_resources. For example:
  
  kz/materials/mymap/wallpaper.vmt should be moved to:
  kz/hammer_resources/materials/mymap/wallpaper.vmt
  
  The hammer_resources folder is not loaded by the game, so whatever you see in your packed map is what others will see! You must move the custom content to this folder, otherwise autopack will not pack it.
  
  
• On the BSP command line in Expert Compile, add -autopack (it's recommended to use
  -autopackstrict which won't finish the compile if expected custom content isn't found for packing).
  
  
• If you never want to override base content (or don't know what that means), add -ignoreoverrides to the command line as well.
  
  
• Test your map ingame, if anything expected is missing, check the BSP stage of the compile log for error messages. You can use -dependencies to see exactly what custom content vbsp thinks your map is using.

For a full listing of packing options in vbsp, please see later in the guide!

What is the packfile?

The packfile is a .zip file that is embedded in every Source map, used to provide content (i.e. materials, sounds etc) within the map, so they don't need to be downloaded seperately. Kreedz Climbing's workshop requires that all custom content your map uses be embedded in the map's packfile, as only maps can be uploaded to the workshop.

How does the packfile work in-game?

When the game is searching for a file, it will first look inside the bsp packfile to see if it can be found, before checking the game's folders. This allows packfiles to override existing game content (more on that later).

How do I modify the packfile?

Kreedz Climbing's new Autopack feature allows automated packing of the map's resources, meaning you don't actually need to pack anything yourself. Other tools, such as Pakrat and VIDE are capable of adding and removing files from the packfile, but those are outside the scope of this article.

Is the packfile compressed?

No, however the workshop uploader (Kreedz Climbing Development Tools) is capable of compressing your map on upload, including the packfile.

What types of files can I add to the packfile?

Filetypes such as .vmt, .vtf, .wav etc can be added to it. Note the game will only load the accepted filetypes, and even then only files the map actually needs. Adding extra files not used by the map will increase your map file size for no benefit.

Before you can use vbsp autopack, you need to know how to use Hammer's Expert Compile dialogue. This dialogue lets you add extra commands to your compile, more than would be available in Normal mode.

To start, you need to open the Expert Compile window by choosing the Expert option in Run Map...



You'll see the following dialogue. Select the drop-down box at the top left...



And choose the HDR Full Compile option. This is the one you want to use, as it enables HDR lighting in your map (the fancy glowy lighting) - the Default option does not compile HDR!



You'll see a list of items on the left with tickboxes. Each item is a different compile stage. BSP compiles the most basic form of the map, VIS(ibility) adds visibility to improve FPS, and RAD(iosity) adds the lighting. Copy file copies the finished .bsp file to your Kreedz Climbing map directory, and the final Game option runs the game. Note that it's usually best to untick this and run the game yourself for testing your map.



The list of options (Parameters) on the right control how that stage of the compile will work. Since we chose HDR Full Compile as the profile, the settings are correct for a good map compile! Each compile tool (BSP, VIS, RAD) have different options you can set.



You can find more information about the Expert Compile window at the Valve Developer Community!

Now that you understand how the Expert Compile window works, let's move on to Autopack!

To use Autopack, you need to know how to use the Expert Compile window. Please read above if you don't know how to!

Autopack is a feature of Kreedz Climbing's vbsp compiler that can automatically pack the custom content in your map into the finished .bsp, during the compile stage. You do not need to do anything overly complicated to enable this feature!

Autopack uses the hammer_resources folder to function. This folder is only loaded by Hammer, not by the game. This means that anything you put in here will not show up in the map unless used with Autopack, letting you see exactly what other players of your map will see! This prevents annoying issues where you might upload a workshop map, and other players don't see textures and so on, but you do.

• First you need to make sure any custom content (materials, sounds etc) are in the KreedzClimbing/kz/hammer_resources folder. Inside that folder you will find a materials, models, sounds etc folder, these are where you will place your custom content.
  
  For example, move your custom texture
  
  kz/materials/mymap/walltexture.vmt to
  
  kz/hammer_resources/materials/mymap/walltexture.vmt
  
  Do this for everything custom you've used in your map, and place future content in this folder as well.
  
  You can safely move the files even if they're currently in use in your map! Make sure Hammer is closed before moving them!
  
  
• Next you need to open the Expert Compile window as shown before, and add -autopack to the BSP Parameters, as shown in the picture (click it to make it bigger):
  
  
  
  Tip: Use -autopackstrict, it won't compile the map if your custom content can't be found, making it easy to find mistakes!
  
  
• And you're done! You can now load up the game and test it. Since autopack is automatic, all you need to do now is make sure any new custom files you make (materials, sounds etc) go in the hammer_resources folder!

A full list of standard BSP compile options is available here.

Kreedz Climbing Options

-autopack: Enables automatic packing of custom content in the map, please see above for more information.
-autopackstrict: Like -autopack, but won't finish compiling the .bsp if some custom content can't be found, very useful for making sure everything is packing correctly.

-dependencies: Shows all the custom files this map depends on in the compile log.
-onlydependencies: Like -dependencies, but doesn't actually compile the map into a .bsp, used for information only.

-allowoverrides: Opt-in to having override content in your map. You must use this if you actually want to enable overriding, or you must choose to ignore overrides, otherwise vbsp won't compile the map!
-ignoreoverrides: Completely ignores all override files, no content overriding will be performed by autopack.

-packmapfolder: Embeds whatever is in the <vmf directory>/packfiles/<mapname> folder into the map. This can be used to override certain content you don't want to use autopack for, or to pack files that autopack would not pack by itself (a credits file for example).

-embed <path>: Like -packmapfolder, but will embed the directory you enter instead of performing any automatic searches.

-allowleaks: Kreedz Climbing VBSP will refuse to compile a map with a leak unless you add this. Note that there is never a situation where having a leak is acceptable and it will prevent your map compiling properly. Fix the leak!


A full list of standard VIS compile options is available here.


A full list of standard RAD compile options is available here.

-both: Compiles lighting for LDR and HDR modes - you need to use this when compiling your map!

Kreedz Climbing Options

-maxquality: Implies -final, -staticproplighting, -staticproppolys and -TextureShadows. Highly recommended, use this in your RAD compile!

The packfile can do one more unique thing: It is capable of overriding existing game content. That means if you have files with the same name as original HL2/Kreedz Climbing files in your hammer_resources folder, when someone plays your map, they will see your content instead of the original!

For example, say you have your own models/weapons/v_usp files, and put that into the packfile. Players playing the map will see your usp model, not the original. The packfile version is overriding the original.

Note: Overriding in most cases isn't a good idea. Since the packfile always has priority over the game files, any changes to the original by the developers won't be seen in your map!

If you understand exactly what all this means and wish to override, you'll need to add -allowoverrides to the vbsp command line, otherwise the map will refuse to compile.

If you don't want to override ever and you're getting errors (perhaps due to extracting a HL2 .vpk to your hammer_resources directory), you can use -ignoreoverrides to ignore the override files.

There are several different script files you can include in your map to get additional functionality, these are listed below - please click the titles to see the SDK information on each:

Soundscapes:

In order to have custom soundscapes in your map, you'll need to place the file in hammer_resources/scripts/soundscapes_[mapname].txt (replace [mapname] with the map name).

Sound Scripts:

Soundscripts allow you to apply extra information to sounds, such as a volume, pitch etc, more than you can customise in an entity. The file name for this is hammer_resources/scripts/[mapname]_level_sounds.txt (replace [mapname] with the map name).

Particles:

You can have custom particle systems in your map! The .pcf files must go in the hammer_resources/particles folder, whereas the script file will go in hammer_resources/maps/[mapname]_particles.txt (replace [mapname] with the map name)

Autopack will pack the required files for these automatically.

I'm trying to use autopack, but vbsp won't run! It doesn't even appear to start, what's going on? I'm not getting any messages at all!

This seems to be caused by a bug in Hammer where it's specifying invalid paths to the compile tools. Please try a different compile config (for example the HDR Full Compile (final)), one, and adjust the commands to match what you want.

What will Autopack pack for me in the map?

The short answer to this is, everything the map needs (if something your map need was not packed, this is a bug, please report it on the forums! More specifically:

• Materials used by the map (including .vtf, normal maps, env maps etc).
  
• Models used by the map (including materials and animations for the models).
  
• Sounds used by the map.
  
• Particles used by the map (including materials used by the particles).
  
• Soundscapes used by the map (sounds referenced by the soundscape, and the .txt file).
  
• Level sounds script file, if it exists, and the sounds used by it.
  
• Color correction files.

I want to see if my resources are working properly (outside of the packfile), how do I make them loaded by the game?

Add -use_hammer_resources to the game's launch options. Make sure you remove it when you're done testing - the game must not load these files for you to be able to test if the packfile works properly.

I'm getting messages about "overrides" when I try and use autopack, and it's showing me a bunch of paths, what is going on here? I never wanted to override anything?

This might happen if you extracted a HL2 or Kreedz Climbing .vpk to the hammer_resources folder and now have a lot of files that are also included with the game. The proper way to fix this is to delete the files that autopack is complaining about, but if you don't want to do that, you can add -ignoreoverrides to also fix the problem, at the cost of not being able to override automatically anymore.

Can I selectively ignore some overrides?

That is not possible at this time, but you could use the -packmapfolder option to manually pack the items you want. Please see the documentation above for more details on that command.

Why isn't Autopack on by default?

I considered this, but autopack is a complicated procedure and has certain requirements (like no accidental overrides), that make it tricky to just work silently behind the scenes. On the bright side, learning more about compile options is always helpful!

Do I have to pack the map using Autopack?

No, you may also use tools such as Pakrat or VIDE, but those are 3rd party and not officially supported.

Do I have to pack my map at all?

The workshop requires the map be packed, as it only accepts .bsp files, you can send the texture files etc to your friends other ways (for them to put in their materials folders), but packing is much simpler, safer (as no files will be forgotten) and easier to do.

You should now understand how to use custom content with Kreedz Climbing! If you need any further help or have any questions, please leave a comment below or make a post on the Community Forums.