Modding Guide

ShadoWarrior's Guide to Modding Aftershock for Beginners
(aka Modding for Dummies, aka Modding 101, original guide can be found here)

SECTION I: EXPECTATIONS
SECTION II: TOOLS OF THE TRADE
SECTION III: GETTING STARTED
SECTION IV: MAKING A MOD
SECTION V: SAVEGAME AND LOCALIZATION FILES
SECTION VI: REVERSE-ENGINEERING

SECTION I: EXPECTATIONS

The first step towards modding Aftershock (referred to as 'AS' from now on in this guide) is knowing what it is you wish to do, and whether it is even possible to accomplish. That may sound obvious, but it does require a bit of careful consideration and question-asking before you begin, or you may just find yourself wasting a lot of time and becoming very frustrated.

In general, you can change the properties of items and actors (your soldiers, allies, and enemies), add new items, change Glossary descriptions, and add new research fields. You may also, with more difficulty, change the appearance of the AS graphical interface (GUI), or even add more territories, base buildings, et cetera. Much more difficult still, but possible, is to add or change graphical models and effects in the tactical part of the game.

Some things that cannot be modded:

making people/aliens show blood/goo splatter when they are hit
more slots in armors that already have slots
more slots in drones
combined damage (such as electrical + stun, or armor-piercing + burn + explosion)
combined effects (such as damage by bullet impact plus poison)

The above list is by no means complete, just a few examples of things players commonly ask for.

Another important thing to consider when deciding to create a mod is whether one already exists that does something similar to what you want. If so, you can save much time by using their mod as the starting point for yours. More on this later.

One very important thing that you must be aware of is that your mod will conflict with another mod if your mod and the other mod both modify any of the same (internal text) files. For example, you wish to create a mod that introduces a new weapon (call it a "disruptor"). Your mod will conflict with any other mod that creates or modifies items, since both mods will be modifying the same file (in this case, "equipment.txt"). I do not know which mod will take precedence. (It may be first one loaded, or last one loaded.)

SECTION II: TOOLS OF THE TRADE

You will need a .vfs file tool. There are two available, each with its own strengths and weaknesses.

Sigget's vfs tool:
http://www.strategycore.co.uk/files/index.php?dlid=237

Flux's vfs tool:
http://www.strategycore.co.uk/files/index.php?dlid=281

Flux's tool (_VFS.exe) is easier for beginners to work with, and comes with a detailed and good documention file on how to use it. But since you have the benefit of this Guide, I will take you through the use of Sigget's tool (vfstool.exe, which is the more popular and better-known one), since it has the advantage that with it you can write batch file scripts to "automate" some tasks that you might eventually do often.

Now that you have obtained one of these tools, you may be wondering "what the heck is a .vfs file, and why should I care about them?" A .vfs is simply an archive file, much like a .ZIP, that contains the thousands of text data, sound, and graphics files that AS uses. These data files are stored in several compressed .vfs files on your disk and the game automatically decompresses them as it runs. (And before you ask, no, you cannot on your own decompress all the files to your disk to try to make the game run faster.) Savegames are also .vfs files. I'll discuss them later.

There are four essential game .vfs files:

LocalizationPack.vfs - contains all text information for the game, including the in-game Glossary, in your game's language version. If you have the German version of the game, and wish to change what you see in the game to English, copy an English-language LocalizationPack.vfs over the one you have in your game's Localization directory. (I'd advise making a backup copy first, before you did this.)
gamedata.vfs - contains the game's equipment and character data, GUI stuff (like cursors), and graphics (models, textures, etc.)
mod_multim.vfs - contains the game's font, music, sound, and video files.
mod_gamedata2.vfs - contains the game's tactical mission maps and related stuff

SECTION III: GETTING STARTED

Anxious to do something after all this reading? Okay. Create a new directory somewhere, preferably not anywhere in the UFO game directory tree. For the sake of this Guide, I'll assume it's d:\my_mods\. You will need a minimum of 1.6Gb free space (call it 2Gb to be safe) on the drive where you create this directory. Unpack "vfstool.exe" from Sigget's "UFO_vfs_tool_v13.zip" into your "my mods" directory.

Now copy gamedata.vfs from your UFO:AS root directory to d:\my_mods\ and then also copy "LocalizationPack.vfs" from the UFO:AS Localization directory to d:\my_mods\. First, you will unpack the LocalizationPack.vfs file. Create two directories named "Localization" and "Data", both at the same level in your "my_mods" directory (ie: d:\my_mods\Localization\ and d:\my_mods\Data\). Now open a command prompt window in your "my_mods" directory. (If you don't know how to do this, stop now and learn how. I'm not going to teach you how to use the OS.) Type in the following command line:

vfstool e LocalizationPack.vfs Localization

... and press the 'enter' key. This will unpack two files and create the d:\my_mods\Localization\system\ subdirectory. Within "system" is the important file "pack.txt". This file contains all the text and Glossary information in your game. Now type in:

vfstool e gamedata.vfs Data

... and press the 'enter' key. This will unpack 13,809 files in 566 directories and chew up 1Gb of your disk. It may take a while if you don't have a fast system. I recommend that after you have unpacked "d:\my_mods\gamedata.vfs" that you delete this copy, as you no longer need it and it'll save you over half a gigabyte of disk space.

Now you will create a new mod archive, which for the sake of this Guide I shall call "junkmod.vfs". Type in the command window:

vfstool mk junkmod.vfs 4096 7000 64 1

... and press the 'enter' key. This will create a 61Kb "empty" junkmod.vfs archive, ready for you to stick stuff into. Once this is done, don't close the command window. You'll have more to do in it later.

For UFO:AS to recognize a mod a file's root name must begin or end with "mod". So files named like:

mod_sample.vfs
my_mod.vfs
mymod.vfs
modofdoom.vfs

are all acceptable. A file named "DeathToAliens.vfs" will be ignored, since it doesn't have "mod" at the beginning or end.

SECTION IV: MAKING A MOD

Now that you have a mod container, I suppose you'll be wanting to put something useful in it? (Be rather a waste of time if we didn't.)

Create a directory for your mod's changed files called "junkmod" in d:\my_mods\ (ie: d:\my_mods\junkmod\). Copy the file "equipment.txt", found in the folder d:\my_mods\Data\strategic\configs\stratgame\equipment, into a folder that you must create d:\my_mods\junkmod\strategic\configs\stratgame\equipment. Note that folder tree ..\strategic\configs\stratgame\equipment in "junkmod" MUST match the one in "Data".

It is time to make some changes. Open d:\my_mods\junkmod\strategic\configs\stratgame\equipment\equipment.txt in your favorite text editor. Avoid MS Word for this sort of task (a very bloated app that's meant for sophisticated document writing with fancy fonts and such, not the sort of thing you'll be doing in modding). I highly recommend NoteTab Pro, available at http://www.notetab.com, or you can Google for it. You can, if you must, use the Notepad or WordPad apps that come with Windows, but they are very basic editors that leave much to be desired.

Do a case-sensitive search for the string "Silencer". You should find it on line 24100 in the (unmodded) file. Scroll down until you find "Influencer Influencer RECORD", and then scroll down a bit more until you see "light FLT 1" (at line 24187). Change the '1' to a '0' (zero). Save your change and exit the editor. Congratulations. You have now modded the Silencer so that it suppresses light as well as sound. Easy, huh? Go back to your still-open command prompt window. Type in:

vfstool in junkmod.vfs junkmod

... and press the 'enter' key. Voila! You now have a working mod. You can now close the command window. All you need to do is copy junkmod.vfs into your root UFO:AS directory (where you found gamedata.vfs), and then start the game to play with the modded silencer.

WARNING: You should NEVER modify gamedata.vfs, mod_multim.vfs, or mod_gamedata2.vfs in ANY way. You should extract what you want from these files and then create a new .vfs to put the changed file(s) into as shown above.

SECTION V: SAVEGAME AND LOCALIZATION FILES

Your saved games may be found at (path)\UFO Aftershock\Profiles\(profile name)\Saves. Saves from the strategic map average around 280-300Kb in size, while those made within a tactical mission may be around 600-1200Kb in size. For purposes of this Guide, create a saved game from the strategic map and call it "mysave". Copy "mysave.vfs" to your d:\my_mods\ directory. Create a "mysave" folder in d:\my_mods\ and then unpack mysave.vfs (using the export 'e' command as shown earlier) into the mysave folder. You will see 3 files (and no subfolders). The file you will want to edit is the big ~7Mb one, "strat_game". Let's assume that the reason you want to edit your savegame is because you want more power cells for your Reticulan weapons. Load "strat_game" into your text editor and do a search from the top of the file for "Reticulan power cell". The line in which you will find this will vary, so don't pay attention to where exactly it's at. A useful thing to know is that if you do a search (from the top of the file) for "itemTemplateStringId STR" you will always find the first data entry for your inventory items. From there you may scroll (or search) downwards until you find what you want. The entries for items are in alphabetical order (they are also in alpha order in equipment.txt, by the way). Now that you have found the entry for "Reticulan power cell", look 5 lines above it for an entry called "count". Change the number after "INT" to whatever positive integer number you desire (I'd avoid going beyond several thousand). Save your change and exit the editor. Open up a command window as you've done before. Type in:

vfstool sin mysave.vfs mysave

... and press the 'enter' key. Note that the command given was 'sin' (savegame import) and not 'in' (import). Savegames use a different compression process than mod or Localization files.

Now type in:

vfstool md5 mysave.vfs

... and press the 'enter' key. This updates the MD5 checksum of the .vfs. If you fail to update the MD5, your savegame will not load correctly and the game will CRASH! (You must also update the MD5 of the LocalizationPack.vfs file.) After you have successfully repacked the savegame just copy it back to your UFO Saves folder, and you're ready to play.

SECTION VI: REVERSE-ENGINEERING

As mentioned earlier, you can save yourself a lot of work if someone else has already created a mod that does something similar to what you want. Perhaps you don't like something they did and would like to do it differently. Whatever your reason, reverse-engineering is very simple. Copy their .vfs file into your mods folder (d:\my_mods\ was the example for this Guide), then rename their .vfs file to whatever you want, and unpack it as previously shown. For example, let's say that you want a mod that gives you more aliens to fight, but you think that my HeroicAssault_mod.vfs has too few/many aliens. Okay, after you copy the file into your folder rename it "myAssault_mod.vfs" (or whatever), create an empty "myAssault_mod" folder, and do the export (as I showed you in Section III). Edit whichever files need to be changed, repack myAssault_mod.vfs (as I showed you in Section IV), and then copy your 'new' mod to your UFO folder. Imitation is the sincerest form of flattery.
Please be sure to give proper credit to the orginal mod's author if you do copy someone else's hard work!