Game Modifications > Game Mod Guide


A game mod or game modification changes or adds new capabilities to games at Voobly.
Voobly's mod support makes it much easier to play mods on line.

Support for mods is divided into three high level categories:

• Game Play Changes - This type of mod changes around the game rules and because of this all users in the game room need to have these types of mods installed when it's played (or the game would go out of sync). This type of mod is also known as a data mod.
• New Visuals or Content - This type of mod changes around the graphics files or adds new maps and doesn't require everyone in the game room to have it installed. This type of mod is also known as a local mod.
• Client Themes - Read more about these in the Custom Theme Guide

If you have any questions on this guide please post them at the Game Mod Forum

Contents: 1 How to find mods 2 Using a Game Play or Data Mod 3 Using a Visual or Local Mod 4 Mods in Single Player 5 Creating your own mods 5.1 Mod Installation Path 5.2 Mod Files Structure 5.3 Mod Versioning 5.4 Distributing your mods before they are submitted to Voobly 6 AoE, RoR, AoK, and AoC specific modding 6.1 File and directory structure 6.2 DRS Modifications 6.2.1 DRS to SLP conversion 6.3 Text String Modifications 6.3.1 Language INI Specification 6.3.2 Language DLL to INI Conversion Tool 6.3.3 AoC language switcher 6.4 UserPatch Extensions 7 Custom Scenario Extensions 7.1 Advanced Statistics 7.2 Hiding Age information in Score Area 7.3 Random CS Map Support

How to find mods

Go to the game mod page for your game:

• Age of Empires
• Age of Empires II: Age of Kings
• Age of Empires II: The Conquerors
• Age of Mythology: The Titans
• AoE III: The Asian Dynasties

Using a Game Play or Data Mod

Once you have installed the mod, you simply select it in game room settings:




After you have selected the game mod, it will show up in your settings:

Underlined texts are clickable.
It will open your browser and directs to the mod's or patch's page.



If a player don't have yet the data mod
you will see a blue arrow icon where normally the ping showed:



If you have the "unzip failed" error it is suggested to try download the mod with different browser, or enable UAC

Using a Visual or Local Mod

Visual mods are automatically enabled once installed.
You can disable them with the "Game->Visual or Conent Mods" menu (uncheck them), or uninstall through the mod's webpage to permanently remove.



Some Visual mod may interfere with an other when changing the same game element.
(using multiple terrain or taunt mods)

If you have the "unzip failed" error it is suggested to try download the mod with different browser, or enable UAC

Mods in Single Player

To use a Voobly mod in single player you can use the launch from single player feature at http://www.voobly.com/pages/view/310

Creating your own mods

Are you already a modder or ready to become one? On Voobly it's easy! We have also have some tools we've written and released to make your life even easier. The easiest way to start is to install some existing mods and look at how they work and start from here. Once you're done upload the mod to Voobly, for more information read the Step-by-step guide for uploading a mod.



For mods to be detected by Voobly they should be placed in the proper game subdirectory. The subdirectory is Voobly Mods\Voobly-Game-ID-Here\Voobly-Mod-Type-here\Mod-Name-Here.

Two examples:

• game id = AOC
  mod type = local mod
  mod name = Small trees
  
  C:\Program Files (x86)\Microsoft Games\Age of Empires II\Voobly Mods\AOC\Local Mods\Small Trees
• game id = AOC
  mod type = data mod
  mod name = Jurassic
  
  C:\Program Files (x86)\Microsoft Games\Age of Empires II\Voobly Mods\AOC\Data Mods\Jurassic

For most mods you put the files you want to change at the same relative path in your mod directory as they are in the game directory.

The easiest way to see how this works is to install an existing mod.

As an example, let's take a hypothetical game with these files and directories:

Lets say you were creating a mod called "MyFirstMod", you wanted to change datafile.bin, and add a new map:



All mods must have version specified in the root mod directory. The server ensures that all users in a room have the same version of the mod before the game is launched.

Simply create a text file called version.ini with the version text, e.g.:


You are free to exchange files w/ zips or create your own installer. The users you are testing with should place the files in the same path as you.

Once you're done send +chris@voobly (or) Blake (or) [MM]Gallas a message to get it added to the Voobly mod listing page as approved.

AoE, RoR, AoK, and AoC specific modding

These sections describe AoE - AoC series games modding specifics.



Files and paths:

• language.ini - text strings goes in base mod directory.
• drs\ directory, put .slp, .wav, and .bin files here.
• For everything else, use the same subdirectory as in the original game, e.g.: Scenario\ is used for maps and data\ for .dat and .drs files.

Example below for a mod called MyTestMod:



There are two methods supported for changing SLP and other types of DRS resources:

• You can put the edited DRS file in the data subdirectory of your mod. E.g.: aoc\localmods\MyGraphicsMod\gamedata_x1_p1.drs . This approach isn't recommended.
• The recommended approach is to extract only the SLP, WAV, and BIN resources that have changed and put it in the drs subdirectory, E.g.: aoc\localmods\MyFirstMod\drs\1250.slp and aoc\localmods\MyFirstMod\drs\50300.wav.

The second approach is recommended because:

• Voobly supports multiple mods being loaded at the same time. E.g.: a mod could change trees while another mod adds a new units. If every mod changed the DRS files you could only have one mod loaded at any given time.
• The resulting mod is much smaller, a mod might end up less a few kb instead of > 50 megabytes.
• Significantly easier to create mods

To help convert mods to this improved format we've created a drsdiff tool, you can download at here. This tool will compare a modified drs file against an original then output the changed SLPs.

Usage: drsdiff.exe modified.drs original.drs . This will compare the two drs and any new or change SLP/wav/bin file will be created in put in a drsdiff-output\ subdirectory the tool will create.




The recommended way to change text strings for Voobly mods is through the use of a robust new language.ini file format. Existing mods have put all the text strings in a language dll files, this has several limitations we've addressed through the use of an .ini file:

• With .dll files you're replacing all or almost all the text strings, with Voobly we support multiple mods being loaded at the same time. E.g.: a mod that changes the default hotkeys, and another mod that adds new units. With the dll approach this couldn't be supported.
• With the .ini format you only need to specify the strings that you've changed, making it much easier to create (sometimes only a 1 line text file!)
• The resulting mod is much smaller, a hotkey mod might end up less than a 1kb instead of > 400kb of language.dll mods.

The file name is 'language.ini' located in base mod directory (e.g.: aoc\localmods\MyHotKeyMod\language.ini). Only one language .ini is supported per-mod (all the strings can live in a single ini file).

Format:
Example below. First block shows the unmodified strings for the multiple game title and the I'm ready button. With two lines in a text file you can switch these strings.



To help convert mods to this improved format we've created a conversion tool called langconv.exe, you can download here.

There are two primary operations the tool supports: the first being to dump an existing language dll to an ini file, and the second to compare two ini files and produce a trimmed list of strings.

To dump an existing language dll, you use the -d option with the following parameters: langconv.exe -d output.ini source.dll

The example below, shows how you would use langconv to dump all the strings from existing language dll files to language.ini. The tool will smartly merge new strings into language.ini after each run.

Use the tool again to dump strings from your existing mod:

To find the minimal set of strings you need in your mod's ini, you use the -t option with the following parameters: langconv.exe -t output.ini yourmods.ini reference.ini

Example:

If you did it correctly, mymod_min.ini will only have the strings that have changed between mymod_from_dll.ini and game_default_language.ini. You would rename mymod_min.ini as language.ini and put it in your mod directory.


You can [You must login to view link] aok and aoc language .dll files from the [You must login to view link] website or the [You must login to view link] from aok.heaven. For aoeHD just follow the recommended installation guide.



It is possible to create a game mod that enables UserPatch extensions such as the civ support. All you need to do is add a age2_x1.xml to your game mod directory.

Example below for a mod called MyTestMod based on Forgotten Empires...

You would get 'age2_x1.xml' from C:\Program Files (x86)\Microsoft Games\Age of Empires II\Games\age2_x2.xml . Also copy files from C:\Program Files (x86)\Microsoft Games\Age of Empires II\Games\Forgotten Empires to your new mod directory.

A sample mod is at http://www.voobly.com/gamemods/mod/113/Sample-FE-Mod

Custom Scenario Extensions

(Supported for both Age of Kings and The Conquerors)

Custom Scenario authors may activate advanced statistics, revealing the local players kills and razing information in the F11 text overlay. This makes access to this information much easier than custom kill counters w/ triggers and they also allow custom scenarios to be created with less triggers increasing stability.

The statistic text is shown below:



To activate these features, simply create a trigger "Display Instruction" trigger that has the following text:



You can download a sample map that implements this:

• AoC: download here.
• AoK: download here.

Delete one of the P1 castles to activate advanced stats.

Take activate advanced statistics in data mod, create a mod.ini file with the following contents:

(Supported for The Conquerors)

Custom Scenario authors may disable the extended age information shown in the f4 score area.

The age text is shown below:



To disable the feature, simply create a trigger "Display Instruction" trigger that has the following text:

Note: this is only tested in multiplayer, it might not work in single player.



To create a "random CS maplist", you name all the maps you want in the list using the format: COLLECTIONNAME-rnd-MAPNUM-MAPTOTAL.scx

For example, a collection of three maps called "CS Random" would be named as:

To host a map using a collection the host must have all the maps. Therefore, it's recommended to package the maps in a game mod.

Any number of map count is supported, that is 2 maps to over 100.

---