L4D2 Campaign Add-on Tutorial

There are six basic steps to creating your own custom campaign Add-ons for Left 4 Dead 2:

1. Make an Add-on folder and content sub-folders.
2. Create game assets and place them in the proper sub-folder.
3. Create metadata files and place them in the proper sub-folder.
4. Pack the contents of the Add-on folder into a VPK file.
5. Test the VPK thoroughly and make changes accordingly
6. Create a homepage for the add-on where it can be downloaded by players.

Install the Authoring Tools

In order to author content for Left 4 Dead 2, you will need to install the Left 4 Dead 2 Authoring Tools. This provides you with the applications and utilities you will need to create game content. Mainly, you will be using the Hammer application to create levels, and the other utilities to create custom textures and models.

A description of how to create these assets is beyond the scope of this tutorial, but you can find useful information in the L4D Level Design Basics Tutorial. Because the focus of this article is how to assemble the assets into a campaign Add-on, we will assume that you have already learned how to successfully create these assets from this point forward.

The Authoring Tools provides an example Add-on campaign called Dead Line that has source examples.

Create an Add-on Folder

To begin, navigate to the "addons" folder of your Left 4 Dead 2 game install location. For most users, this will be similar to:

C:\Program Files\Steam\steamapps\common\left 4 dead 2\left4dead2\addons

Note:If you have a folder with a hyphen, i.e. "add-ons", make sure it's empty and go ahead and delete it. The correct folder has no hyphen: "addons".

Note: The 'addons' folder may not exist in your L4D2 Authoring tools install.

Make a new folder inside the 'addons' directory, and give it an appropriate name. This new folder will be the name of the .VPK file you'll ultimately create and distribute, so it's good practice to avoid spaces and use all lowercase letters. You may also include the game in the title, to differentiate it from add-ons for other titles, and optionally a version number. We'll use "deadline" instead of "l4d_deadline" for our example for the sake of readability.

...\left4dead2\addons\deadline2

Conceptually, this add-on folder will serve as the base “game” folder for your assets, and will mirror the layout in the shipped .VPK files as we shall see below.

Create Primary Game Assets

The assets you create will essentially append those shipped with the game. For a campaign, the primary assets are the .BSP and .NAV files for your map levels.

Make a folder called 'maps' inside your add-on project folder:

...\left4dead2\addons\deadline2\maps

Into this maps folder, copy the .BSP and .NAV files you're using for your maps. For this Dead Line tutorial example, there are three map file bsp.nav pairs:

File	Description
l4d_deadline01	Minimal starting map for co-op, versus
l4d_deadline02	Final map for co-op, versus, survival, scavenge

The advantage of having a single map function for multiple game modes is size reduction, which can be worth the additional authoring complexity.

You may also optionally create custom .VTF texture images, custom .VMT material description files, and custom .MDL models which your maps can utilize. In order to keep the size of your add-on small, it's advisable to use as many textures and models from the game as possible.

Additional .VMT and .VTF materials (see Creating a Material) should go under this folder:

...\left4dead2\addons\deadline2\materials

.MDL and related model files (see exporting and compiling a model) should go under here:

...\left4dead2\addons\deadline2\models

Note:Since "The Sacrifice" update, model .vtx files are no longer renamed when packed. For example, packing a .dx90.vtx file no longer renames to simply .vtx. All official files that were .vtx files have reverted back to .dx90.vtx. Campaigns with custom models that were released prior to the update will be invisible in-game. Before the October 2010 update, a campaign would crash if .sw.vtx and .dx80.vtx were included for packing.

And materials for your models should go under here:

...\left4dead2\addons\deadline2\materials\models

It should be noted that L4D2 treats the /deadline2 folder much the same way as the /left4dead folder, so any folders you use inside the /materials and /models that you employ must also be present in your campaign's folder.

Create Secondary Game Assets

Secondary assets such as poster and thumbnail images are not strictly required, but they can give your campaigns an extra level of polish. (Besides, the poster/concept art was likely the first thing you created, wasn't it?) If you haven't already, go ahead and make a materials folder and a vgui folder inside of it:

...\left4dead2\addons\deadline2\materials\vgui

Campaign Poster

Inside the vgui folder you'll want to place at least two .VTF files, along with .VMTs that reference them:

LoadingScreen_DeadLine2.vtf 

This is a poster image that is displayed while your campaign loads. Standard size is 1024 x 1024 pixels with an alpha channel for transparency.

OutroTitle_DeadLine2.vtf 

This is a title image that appears behind the end credits/stats. Standard size is 1024 x 256 pixels. Your design should look good against a black background and also allow white text in the foreground to be readable.

Map Thumbnail Previews

In addition to these two, you'll also want to make thumbnail images for each map in your campaign. These serve to provide a visual reinforcement indication for users while they're selecting map "chapters" in the UI.

To do so, create a new folder named 'maps' under the vgui folder:

...\left4dead2\addons\deadline2\materials\vgui\maps

In this folder, you'll want to create a .VTF/.VMT pair for each map you wish to create. They should each be 256 by 128 pixels. If appropriate, you may use a single thumbnail image to represent multiple .BSP maps, such as when you have a versus or survival variant of the same level.

.VMT files which are used for interface elements such as posters, thumbnails, etc., (I.e. Those typically found in the materials/vgui folder,) often need to specify an UnlitGeneric material. See Deadline vgui .VMT File for an example.

Creating a sound.cache File

If you wish to have custom sounds in your add-on, you need to build an audio cache file that the engine uses to load your sounds. Place your sounds in a "sound" folder in your add-on directory, then while Left 4 Dead 2 is running enter the command "snd_buildsoundcachefordirectory <path>" with the path of your sound folder. For example, in the Deadline example, we would place sounds in:

..\left4dead2\addons\deadline2\sound

Then rebuild it with:

snd_buildsoundcachefordirectory "..\left4dead2\addons\deadline2"

This will generate a sound.cache file in the sound folder that you should include when building your VPK file.

Create Metadata Files

There are a few more files that you will make in order to allow your add-on content to function in game.

Note:The addoninfo and addonimage you create will not be used by the game when you upload your addons to the steam workshop. The addon picture, description and tags will be taken from the steam workshop release upon subscribing to a mod

Note:The addoninfo and addonimage are not required for the game to recognize the files. The addoninfo is only required to see the addon listed in the addon menu and for the addon installer tool to recognize which game it belongs to.

addoninfo.txt

The first is the addoninfo.txt file. This allows your content to be recognized by the game. It should go inside your add-on root folder, which was the first one we created way back at the top:

...\left4dead2\addons\deadline2\addoninfo.txt

This file is used by the game in the Extras->Add-ons screen. It describes your add-on in general and what it provides. The example Deadline AddonInfo File includes full comments and instructions for using it as a template for your own add-on.

addonimage.jpg

Another file you can create in the root folder is an image named addonimage.jpg. This serves as an icon/thumbnail to help differentiate your add-on and is displayed when an add-on is selected in the UI along with add-on details listed in the addoninfo.txt. Some JPG files may not work, depending on which application they are saved from (such as Adobe Photoshop). If you're having trouble getting your JPG to work, try importing and exporting it from VTFEdit. It is recommended (but not required) that the image is in widescreen resolution.

Mission File

The second required file is the mission file. This describes the structure and content of your campaign and is used by the campaign selection UI, matchmaking, and the game server. This should be a .TXT file with a unique name in the 'missions' folder, which you will also need to make:

...\left4dead2\addons\deadline2\missions\deadline2.txt

The example Deadline Mission File includes full comments and instructions for using it as a template for your own mission.

Note:Adding a mission.txt file (or any text file) to the missions folder will flag the VPK as a campaign instead of a content pack. It is unknown whether there are other factors that affect how the VPK is treated. Specific sets of files in the VPK will not eclipse other campaigns. Such content includes, but are not limited to, unique and replacement materials/textures, models, sounds, sound cache, particles, and particles manifest. At the moment, script files (found in the scripts folder) and resource files are still eclipsed by add-ons regardless of the "type" of VPK it is packed. This causes conflicts with official and other add-on campaigns if file names are the same.

Test It Out

At this point, your add-on should be fully functional. You should be able to launch the game, go to Extras->Add-ons, and enable your add-on. If you type path into the console, you should see the root directory of your add-on near the bottom. This means that the game will search your add-on folder for files that it cannot find in the standard game .VPK files. Play a full game on other computers to check for an errors such as crashes and missing assets. You can continue tweaking your content in folder form until you're ready for that magical moment: Release into the wild.

Packaging and Shipping

The final remaining step is to package your add-on into a .VPK for distribution.

The .VPK serves as a convenient, one file method for others to install your add-on folder. They need simply put the .VPK in their own add-on folder. Or, assuming they, like most non-authoring players, haven't associated the .VPK extension with something else, they can double click on it and it will install itself in the correct place.

Every .VPK file contains a unique ID that allows the game to ensure everyone is running the same content. If you've put in meta-data properly, the game will also prompt users to download a newer version if it is required to play.

Navigate to this folder:

C:\Program Files\Steam\steamapps\common\left 4 dead 2\bin\

Locate the vpk.exe packaging utility and make a shortcut to it on your desktop. Drag your add-on root folder and drop it onto the shortcut. The utility should make a new .VPK next to your original folder. By default it will not include source files such as .VMF, .TGA, .SMD, .QC etc., and it will always strip out executable binaries. Remove the folder version of the add-on (or move it to a safe location) so that the .VPK is alone and test it out. The .VPK should function exactly as the add-on folder does. If it works, you're ready to upload it to a location you specified in the metadata files and from which it is available.

Ideally, you'll want an add-on "homepage" that includes ratings, screenshots, and player comments. A simple example can be found here.

Compression

Since full Left 4 Dead 2 campaigns can be very large, it is advisable to compress them before uploading to file sharing sites for distribution. The open source Windows utility 7-zip supports compressing files in the 7z format/LZMA algorithm, which provide a very high compression ratio. The bulk of a campaigns size comes from the .bsp map files, which are highly compressible, so a VPK can be reduced to 25% or less of its original size. For example an unofficial version of Death Aboard was packaged up by a fan; the vpk was 267MB uncompressed, 92MB zipped, and 55MB with 7z.

Final Testing

At this point, you should test out the download prompt. Start a lobby with a local server, and invite a friend to join. When they accept, they should be prompted to download the necessary add-on, after which a browser window will opened to your add-on homepage. They should be able to download and install the add-on without having to restart the game, and then join your lobby.

See also

• L4D Campaign Add-on Tutorial
• VPK
• VPK File Format
• L4D2 - Campaign Packager Tool