TUTORIAL: How To Prepare A Map For Distribution

This tutorial will explain how to prepare a .zip file for your map for distribution or testing. This tutorial centers around creating map zips for Half-life and its Mods but it can apply equally well to many other games as the general concept is the same.

You will need WinZip, an application for creating compressed ("zipped") archives. Properly created ZIP files allow their contents to be extacted simply, in the correct locations, and without much user interference. This tutorial will show you how to simply and reliably create zip files that contain the directory structure required to "auto-install" your map components into the game directories. I'll also discuss some common practices that you can use to help avoid user installation errors as well as communicate information to map testers during the maps beta testing phase.

Setting Up The Directories

Lets walk though preparing two maps for a testing release. I will assume you already have map fully compiled, locally tested, and ready for an online beta test. Start by creating a new folder and name it such that it references your maps name (I find using the map name works very well here). You can create this folder anywhere but I would suggest having a specific directory just for building map zips from.

For Example, in my system I have a directory called c:maps for each of my maps. Within this maps folder I have a subfolder for each of my maps each named to match the final .bsp name. This directories hold all the files I used to actually create the map and its custom components (.rmf, .rad, .map, .psd, .bmp, etc.). I also have a subdirectory under maps called "zips", this is where I keep yet another set of subfolders once again one for each map that hold all the master "production" files, the ones that are acutally used to play the map. See the image below of a sample directory tree.

Now, inside the folder you created you'll want to mirror the directory structure of your game directory but ONLY the directories that contain files specific to your map or its custom components. Lets use a standard Halflife Deathmatch level as an example we'll assume it uses only the textures, sprites, sounds, etc. that are found in a default Halflife installation (i.e. no custom components). Just so we can reference this map later lets call this example map "dm1". So for this map you'll need to add a valve folder and inside of that a maps folder.

As a second example lets say our map was a more advanced/customized map this time for TFC. Lets assume this map has a custom sky, a number of new models, a sprite, and some sounds and is named "tfc1" for further reference. For this map we'd have to create a tfc folder. Then inside that folder we would need the following folders sound, models, sprites, and gfx. Because the files for a custom sky are in the ./gfx/env/ directory we will need to add the env directory inside our gfx directory.

I hope you can see how all I am doing is duplicating the directory structure of the Halflife Mod only where the map (.bsp) references non-standard components.

Copy The Files

Back to my first example, the standard Deathmatch map called "dm1". Its time to copy the map file into the directory structure we just created. To do this open your halflife/valve/maps directory and locate the map file, dm1.bsp (I'm assuming you've placed it here to test it first because only a fool would compile and distribute without first seeing if it works and looks right). Copy the map file to the directory structure we made above. If your following my example layout it would be C:/maps/zips/dm1/maps/

For the more complex TFC map example there is a bit more work to do but the process is the same. Locate all of your maps custom components and copy them into the matching folders in the directories we created above. Start by locating the halflfie/tfc/maps directory and find your .bsp, in the case of the example it would be tfc1.bsp as well as tfc1.txt and tfc1.res (more on these special tfc files in a moment) and copy them to your ./tfc1/tfc/maps/ dir. Move your sky files into ./tfc1/gfx/env/ your sprite file into ./tfc1/sprites/ the models into ./tfc1/models/ and so on.
Once these directories are created, as in the case of a beta map, you can keep them around so all you need to do is copy in a freshly compiled version of your map, alter your text files if required and re-zip.

I mentioned the .txt and .res files for the example TFC map above. In tfc if a text file exists in the map directory that matches the name of the current map then that text file will be displayed as the info screen and at map load. These text files always take the for [mapname].txt. Usually you'll want to describe the key features to your map or if your tfc maps gameplay is more than simple capture the flag you'll want to describe what the players should be doing. Look at some of the other TFC maps .txt files for examples.

The .res file works for all mods. It is used to tell the game engine what files are required to play your map so should a player try downloading your map from the server, the server will check the [mapname].res file and download all the other required files to the client (player) before sending the map. This ensures that the client will have all the models, sounds, skys, sprites, etc. required so thier mapload will not fail. Look at .res files from other maps for examples on how to create them as I won't go into that here.

Creating The Actual Zip File

If you've installed winzip you should be able to right click on the icon for your mod folder ( c:/maps/zip/dm1/valve and c:/maps/zip/tfc1/tfc in the examples) and have an option to Add to xxxxx.zip. Select this and the zip file will be created for you. You will then need to rename the .zip to match your map's name. See below on naming conventions
If you want to, or have to use the Winzip UI to create your zip follow the following steps...

    Open Winzip
    Open your top level folder (dm1 or tfc1 from the examples)
    Drag and drop your mod folder (valve or tfc from examples) onto the winzip window

The Add window will pop up. Make sure the "save full path info" and "Store in 8.3 format" boxes are UNCHECKED and set your zips filename in the "Add to archive" section. See image on right
Click the "Add" button[/list]

Assuming everything went well and you should have a new.zip file. You should now open it to double check that all the files are in it and that the directory structure was preserved properly. The image below is a Winzip window showing the contents of one of my TFC maps. Notice how the "path" for each file is relative to the halflife directory. So when this file is unzipped into the Halflife directory (default is C:SierraHalflife) the files will be placed inside the already existing tfc folder and its subfolders exactly where the .bsp expects to find them. I shouls also point out the naming I've used on my text files in this zip, because they start with the map name all the files will stay together in the maps directory (assuming alpha sorted)

Map Naming Conventions and Readme Files

Whenever your distributing beta maps for testing you should always try to keep some kind of naming convention in mind. This helps to avoid the situation where your testers try to connect to the server but get the "Your map differs from servers" error.

So here are some very simple guidelines to help you out.

    All beta maps should have denoting suffix either "_beta##" or "_b##" where the ## is the revision number.
    This suffix should be on the .bsp as well as any text files associated with the map.
    The zip file should be named to match the name of the map file including its suffix

All beta maps should include a readme file, in plain text format. Please don't include MS Word .doc files remember that your maps documentation should be linux friendly too. Also keep in mind that there are lots of other mappers out there and if everyone just included a "readme.txt" file every time you installed a new map you'd bash the previous readme.txt. So be sure to name your readme file uniquely so that other people can figure out what map it belongs to later. I suggest this naming format for readmes... "[mapname]_readme.txt" for your main readme file (name first so it alpha sorts next to your .bsp) and "[mapname]_readme_betaXX.txt" for information you want beta testers to read (this should include specific things to want tested or for noting areas where you think problems might arise)

Well that's pretty much it. You should now be able to create a "clean" .zip file with all the trimmings ready to fire off and have tested or posted for all gamers to enjoy your super-uber map. I look forward to seeing your freshly zipped maps up for testing here at the Department of Engineering.

Maintainer, Department of Engineering - Leader, Clan[WTF?]

0 comment(s)

© 2007, BigBadaBoom