Targetware: Mod Creation

Building Your Datapack & Handling Updates

Ok, your mod is now assembled, you have gathered parts from all your 2D artists, 3D modelers, terrain gurus, and physics geniuses, and you have tested the scenarios to make sure they load: it's time to build a datapack that players can download. This page will cover building a datapack for distribution, as well as how to create mod patches for incremental updates.

For this example, we're going to assume the following conditions are true:

We're building a full datapack for players that have never downloaded our mod before.
We're also building a mod patch for players that have played before. This patch will be much smaller to download than the full datapack, since it only contains the new and changed files since the last datapack
We want the mod download to be available to everyone through the in-game Download Mods feature.
We have already replaced all terrain maps in TGA format with .map format files, using tool.exe
Our mod is named "Target Kiska", the short code for which is "tkiska".

Ok, let's get started...

Step 1: Update the .mod File with New Version Code and Links

We first have to pick a version code for this datapack. This could be anything, a name ("red"), a number ("001", "002", etc.), a date (102303, 10-23-2003, etc.), or some combination. What it is doesn't matter too much, as long as each version you distribute has a unique version code. Since we're distributing this version on October 23, 2003, and I personally like to tag things with dates, we're going to just call this version "102303". Here's the line in the tkiska.mod file ([Mod] section):

version = 102303

For the download link, we haven't built our datapack .zip file yet, so we obviously haven't uploaded it yet, but need to decide at this point what the file name will be, and where we'll put it. The download name could be anything, but try to use something that you (and the players) will be able to look at later and figure out what it is. We're going to use our mod short code plus the version code from above: "tkiska102303.zip". Here's the the download line from the [Mod] section of tkiska.mod:

download = http://mods.targetkiska.com/tkiska102303.zip

But what if you have mirror sites you want to use? Simple, you just list more than one link:

download = http://mods.targetkiska.com/tkiska102303.zip, http://mirrors.videogamecity.com/flightsim/tkiska102303.zip

You can have as many links as you want on the download= line, and the game will randomly assign one to a user as they click download. You can also weight the downloads so that only a portion of them go to your mirror sites, with most of the load going to your own site (or vice versa). In the example above, download will be split 50/50 between our site, and the mirror site. If we wanted it to be 75% load on us, and 25% load on the mirror site, we'd just list our site 3 times, and the mirror site once. Order does not matter, downloads are selected randomly. Separate each link with a comma.

Only one "download = " line will be read by the game engine. Adding multiple lines does not spread out downloads. All downloads must be in one list, on one line.

Update Patching
If you are going to be including one or more mod patches in this update, you need to add an [Updates] section to your .mod file, with download links. The [Updates] section allows you to specify separate mod patches for each previous version of your mod. The left side of the equation is the user's version code, the right side is one or more links pointing to the patch that will update their version. In our example, we only have one previous version out, so this is our update section:

[Updates]
061703 = http://mods.targetkiska.com/kis061703_to_102303.zip, http://mirrors.videogamecity.com/flightsim/kis061703_to_102303.zip

Patching Strategies
There are two strategies you can employ here. One is to provide a full patch for say, the last three versions of your datapack. So if the new version was "4.0", and someone had version 1.0, they could update to 4.0 in one single download. Your update section might look somethig like this:

[Updates]
v3.0 = http://www.mymod.com/downloads/v3_to_v4.zip
v2.0 = http://www.mymod.com/downloads/v2_to_v4.zip
v1.0 = http://www.mymod.com/downloads/v1_to_v4.zip

This is convenient for the users, but it requires you to create and upload separate patches for 1.0 to 4.0, 2.0 to 4.0, and 3.0 to 4.0. A second strategy is to only build one patch per version. This reduces your work load. Older users can still upgrade, they just have to go from, for example, 1.0 to 2.0, then 2.0 to 3.0, and then 3.0 to 4.0. Using the incremental patches, your [Updates] section might look like this:

[Updates]
v3.0 = http://www.mymod.com/downloads/v3_to_v4.zip
v2.0 = http://www.mymod.com/downloads/v2_to_v3.zip
v1.0 = http://www.mymod.com/downloads/v1_to_v2.zip

Step 2: Update Mod's Change Log (optional)

If you have been keeping a log of changes for your mod (tkiska_changes.txt, etc.), then this is a good time to check that you have assigned the right date to the most current changes. If you haven't bothered with a change log, then you can skip this step.

Step 3: Make a Copy of Your Dev Mod Directory

We will not build the datapack directly from your working (development) directory, because that would destroy all your TGA files in the process. So now that we have updated the .mod and change log, we make a copy of the mod's data files, both the .mod ("tkiska.mod") and the mod data dir ("tkiska/"), and work from the copy.

Step 4: Prune Unfinished Aircraft & Scenarios

You may have had aircraft or terrain objects in your working directory that were under development, but not ready for public use. In the copy of the data directory we made for the build, delete anything that isn't ready for public use. This will save you lots of bogus bug reports, and it will reduce download size. Don't forget to erase any test scenarios you have that point to the aircraft or terrain objects you just deleted.

Step 5: Search for Spaces and Illegal Characters in Filenames

Unless you are a one-man mod development team, you have been gathering files from your fellow mod builders. They may not all have been following strict filenaming rules. If a filename uses illegal characters, the .zip file may not decompress correctly when players download it. The following characters can not be used in file names:

/ ? * . , < > + [ ] \ : |

You may wish to run a quick file search on your computer to check for those names in your mod directory. If you find any files using those names, change them as needed. Make sure that in changing them, you don't break a link to a game resource.

Step 6: Pre-Process 3D Files with Tool

You can greatly improve the loading speed of your mod by pre-processing all 3D files (.LWO, .X, .3DS, .AC3D, etc.) with tool.exe's "dir2geo" command. Tool is a command-line (DOS for Windows, Terminal for Mac) utility included with your Targetware installation. The process is automated, and only needs to be done once per build. To use tool, open either a DOS prompt (if you are on Windows), or the Terminal, if you are using Mac OS X.

Note that it deletes the original 3D files after it creates .geo versions of them. This is the main reason we have been working off a copy of our development directory since Step 3 above. NEVER RUN TOOL DIR2GEO ON YOUR WORKING DIRECTORY!

NOTE: once converted to .geo format, 3D meshes cannot be translated back into .lwo, .x, .3ds, or other 3D formats.

Here is an example tool command under OS X:

cd Kiska/build_dir
tool dir2geo tkiska102303

Just as with dir2dds, you will see a list of the files being processed.

Step 7: Compress TGA Images with Tool

Compressing TGA (Targa) images into .dds files with tool.exe will help your mod run on a greater variety of computers, and at faster speed by decreasing VRAM requirements. It will also significantly reduce download size. Tool can convert every 24 bit and 32 bit TGA in your directory in seconds, with one command. Just as with using dir2geo, tool will delete the original TGAs as it creates compressed DDS versions of them, so never run the tool dir2dds command on your working directory.

Run tool.exe (tool for Mac) with the "dir2dds" option, and specify the build directory we've been working on. Here is an example under OS X, assuming you have already CD'ed into the right directory:

tool dir2dds tkiska102303

You will see a list of files being converted. Not all image files are converted, JPG files are ignored, as are 8 bit (256 color) TGA files. For more information on the compression routine, google the phrase "S3TC Compression".

Step 8: Delete DS_STORE files (Mac Only)

If you are not building on a Mac, you can skip this step.

OS X stores information on the location of icons within each directory in small invisible files named ".DS_STORE". Normally, you never see these files on your mac. But if you zip up a directory, when PC users unzip it, they will see these files cluttering up their directories. It does them no harm, but it does increase the download size a certain degree, and since in general, everything not needed for a mod should be deleted before uploading it, you should get in the habit of deleting them. Fortunately, it's very easy to get rid of them. Open up the terminal, and cd to your build directory (as we did in the above step). Then copy and paste in this command, and hit return:

find . -name .DS_Store -exec rm -rf {} \;

That's it. It will delete every .DS_STORE file in your build directory. Note: not having the DS_STORE files there does NOT hurt your Mac in any way.

Step 9: Build Mod Patch(es)

If this is the first time your are issuing a datapack, or if you don't care about users having to redownload the entire pack each time, you can skip this step.

What is a mod patch? It is a .zip file containing only the files that are new, or different, compared to the previous full datapack download. The difference between download a full datapack and downloading an incremental patch can be as significant as 120 mbs versus 1 mb, so we highly recommend you make the extra effort to provide patches to your players.

You can, of course, create the mod patch manually, by selecting the files you know to have been updated since the last directory. However, unless it is a very small update, this process can take a lot of time and effort. To make it easier to create mod patches, we are providing a link to a third-party mod patch script which will do the work for you. All you have to do is point it at a directory containing your previous datapack, and at the directory containing the new datapack you just built. It will compare the two, and build a third directory will any new or changed files. All you have to do at that point is zip up the directory, and upload the patch to the server.

Download Mod Patch Script for Mac OS X
Download Mod Patch Script for Windows

Note: Targetware cannot be responsible for any damage or loss of data resulting fro the use of the above scripts. They are provided solely for the convenience of mod builders. No guarantees are provided whatsoever. If you have trouble running a script, please contact the script's creator, or post a note on the "How To" forum on the Targetware BBS.

Once you have downloaded the patching script, you may wish to copy it to your /usr/local/bin/ directory so that it is available easily from the terminal (OS X only).

To use the script, cd to the directory containing your datapack releases. You will probably want to have both the new build directory and the previous datapack's build directory in the same directory to save typing. For our example, our previous datapack directory is named "tkiska061703" and our new one is "tkiska102303". We are going to name the patch .zip file "kis061703_to_102303.zip", so we will name the patch directory "kis061703_to_102303". Here is the command we give the script:

./buildpatch.pl -o tkiska061703 -n tkiska102303 -p kis061703_to_102303 -v

As you have no doubt guessed, "-o" stands for "old directory", "-n" for "new directory", and "-p" for "patch directory". When the script finishes running, a new directory named "kis061703_to_102303" will have been created, and populated with only the new/changed files. All we have to do now is zip the files up, and then name the resulting zip file "kis061703_to_102303.zip".

NOTE: It is very important that you zip mod datapacks and patches from the level containing the .mod file, and not from the directory above that. For example, if we zipped the "kis061703_to_102303" directory itself, the mod patch would not work. Instead, we open the directory, select everything inside, and zip that. The same is true for full datapacks. Find the .mod file, select it and the mod "tkiska" sub-folder, and zip them.

Step 10: Zip the Datapack

Your datapack is now ready to be compressed into a .zip file. Depending on which .zip software you are using, this step generally involves selecting the .mod file and mod sub-folder ("tkiska", "tr", "tk", etc.), and dragging them to an icon to zip, or using a contextual menu to zip them. Once you have created the .zip file, assign it the filename you specified in the .mod file in Step 1 above.

Step 11: Upload Datapack and Patch(es)

Upload your new datapack, and any patches you may have made, to your web site. The URL you upload them to must match the URL you put into the .mod file, or players will not be able to download and install it from within the game. If you have mirror partners, make sure you make the file available to them, and find out what URLs they will be making it available from.

Step 12: Send .mod File to Targetware

If you want your mod datapack and patch(es) to be available to players via the in-game interface, then your last step is to send your .mod file to Targetware, so it can be installed on the meta server. If you skip this step, no one will be able to download your mod from within the game. Note: if you later gain more mod mirror locations, or if you change your own URL, all you have to do is edit your .mod file and send it to Targetware again. You never have to email or FTP your entire mod datapack to Targetware.

All Done

That's it, you're all done! You may wish to post the availability of your new datapack on the Targetware forums, as well as on your own web site, and perhaps contact gaming sites with the news.

Here's a simple checklist in PDF format that may help you keep track of where you are on the days when you build updates:

Mod Build Checklist (PDF)

<<- Back to "Table of Contents"

Proceed to Next Section ->>