Swarm Campaign Add-on Tutorial
There are five basic steps to creating your own custom campaign Add-ons for Alien Swarm:
- Make an Add-on folder and content sub-folders.
- Create game assets and place them in the proper sub-folder.
- Create metadata files and place them in the proper sub-folder.
- Pack the contents of the Add-on folder into a .VPK file.
- Create a homepage for the add-on where it can be downloaded by players.
Install the Authoring Tools
In order to author content for Alien Swarm, you will need to install the Alien Swarm Authoring Tools (SDK). 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 Alien Swarm Mapping Basics. 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 that has source examples.
Create an Add-on folder
To begin, navigate to the 'addons' folder of your Alien Swarm game install location. For most users, this will be similar to:
C:\Program Files\Steam\steamapps\common\alien swarm\swarm\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".To create your own addon campaign, create 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 "infested" as the name of our addon.
...\swarm\addons\infested
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 files that are your individual missions.
Make a folder called 'maps' inside your add-on project folder. This is where the .BSP files will go which will make up your individual missions:
...\swarm\addons\infested\maps
To define your campaign, you'll need a campaign file that defines the missions that are in it, which order they are played and where they exist on the campaign map. Create a new folder called 'resource' and inside that create another folder called 'campaigns'.
In here will be your campaign file which (for the sake of this tutorial) you should just name 'infested_campaign.txt'. Use '...\swarm\addons\ExampleAddon\resource\campaigns\ExampleCampaign.txt' as an example.
...\swarm\addons\infested\resource\campaigns
In your campaign file you should update the name of your campaign to something unique. The file explains what each entry does so go ahead and customize how you see fit.
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. (Question: Is it really likely that a lone mapper or a small mod team will make a map/mod that is overly large, given that typical games these days can be 6 gigs or more?)
Additional .VMT and .VTF materials (see Creating a Material) should go under this folder:
...\swarm\addons\infested\materials
.MDL and related model files (see exporting and compiling a model) should go under here:
...\swarm\addons\infested\models
And materials for your models should go under here:
...\swarm\addons\infested\materials\models
It should be noted that Alien Swarm treats the /infested folder much the same way as the /swarm folder, so any folders you use inside the /materials and /models that you employ must also be present in your addon's folder.
Create secondary game assets
Secondary assets such as a campign map, mission maps, mission and objective thumbnail images are not required, but they can give your campaign an extra level of polish. If you haven't already, go ahead and make a materials folder and a vgui folder inside of it. The campaign overview map is defined in the campaign file (we called it 'infested_campaign.txt'). The individual mission thumbnails and the mission overview maps are defined in the mission overview files ('...\swarm\resource\overviews\')
...\swarm\addons\infested\materials\vgui
Campaign Map
Inside the vgui folder you'll want to place your custom campaign map .VTF file, along with the .VMTs that reference it. You can call it whatever you want, but it's a good idea to include the name of your addon in the name of the file. Once you've created your custom campaign map image, you'll want to edit the campaign file (we called it 'infested_campaign.txt') to point to it.
.VMT files which are used for interface elements such as campaign maps, thumbnails, etc., (I.e. Those typically found in the materials/vgui folder,) often need to specify an UnlitGeneric material. See L4D's Deadline vgui .VMT File for an example.
Mission Thumbnail
In addition to the campaign map image, 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 'MissionPics' under the vgui folder:
...\swarm\addons\infested\materials\vgui\swarm\MissionPics
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 256 pixels and be representative of the mission in some way.
Once you've created your custom mission image, you'll want to edit the mission's overview file (which we placed in '...\swarm\resource\overviews\').
Objective Images
Just like the mission thumbnails, we can create custom images for you mission's objectives. Once created, your objective image can be defined in the Hammer objective entity (see Swarm Objectives) inside your .VMF (see examples located in the example .VMF files here:
...\alien swarm\sdk_content\mapsrc\tutorial\
Mission Overview Map
You can optionally create an overview map for each mission that you've created, but you must create objective files for all of your missions. Under the 'resource' in your addon path, create a folder called 'overviews'. In here you should place an overview file for every mission (.BSP) that you have made. These files need to be named the same as the .BSP file. (see the files in '...\swarm\addons\ExampleAddon\resource\overviews\' as an example)
...\swarm\addons\infested\resource\overviews
For more detailed information on creating overview maps, see this page: Swarm Overview Map.
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.
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:
...\swarm\addons\infested\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 (...\swarm\addons\ExampleAddon\addoninfo.txt) includes 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 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. If you're having trouble getting you JPG to work, try exporting it from VTFEdit.
Test it out
At this point, your addon should be fully functional. You should be able to launch the game, go to Extras->Addons, and enable your addon. If you type path into the console, you should see the root directory of your addon 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. 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 addon into a .VPK for distribution.
The .VPK serves as a convenient, one file method for others to install your addon folder. They need simply put the .VPK in their own addon 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\alien swarm\bin\
Locate the vpk.exe packaging utility and make a shortcut to it on your desktop. Drag your addon 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 addon 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 addon "homepage" that includes ratings, screenshots, and player comments. A simple L4D example can be found here.
Compression
Since full Alien Swarm 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.
