Introduction into AoE3 modding

– by BilboBeutlin
Created: 5th May 2006
Last Edited: 8th June 2006

What is ‘modding’? … some basics

‘Modding’ is a usual short word for mod’ing, modifying – that means changing existing stuff (espec. for games) to get a new outlook, other behavior, adapt on individual requirements or to add new features.

Strictly speaking it’s already modding, if you change anything from the delivered original program state. That may be color settings or the keyboard layout. In most cases such changes are already doable with the program’s inbuilt features.

Most programs come with one or more setup files, which are editable with normal text editors like eg. Windows’ Notepad. From programming aspect, also the files which determine game behavior (like AoE3’s proto.xml, techtree.xml) are also merely setup files, which the program’s exe(cutable) reads in the initializing startup phase. So changes on such files will usually only take effect at a new game start.

Only to mention by the way: very experienced users can mod the program’s exe (executable code) or a dll (dynamic link library). But this requires specialised, advanced know-how and particular tools.

What is to be considered?

Modder’s first rule: Never touch a non-backup’ed file!

That can’t be told often enough. A failure in an edited file can ruin the program – if you have no possibility to restore the previous (last running) state, a new installation is required. A backup is nothing else than copying and saving the file(s) to a safe place.

In AoE3 there’s additionally a special reason to have a backup of the original files: You can only play online (on ESO) or install a proper patch/update, if the game is in default state.

Another point is the distribution, publishing of modded files. In doubt, read carefully the EULA (end user license agreement), which you confirmed by installing the program.

You may only distribute AoE3 relating files (also modded) for private, non-commercial purposes. The original files are copyrighted by Ensemble Studios and Microsoft. Also a modification doesn’t touch this.

The EULA isn’t very verbose relating modding and there are often discussions, whether modding is strictly speaking permitted. In doubt, your country’s laws have the last word. Here (in germany): for own, private usage you can do (nearly) all, and be it for test purposes. But for distribution you have to keep in eye also the EULA.

To make it less complicated: I don’t think, ES and MS would opponent against a private hobby exchange of files – so they didn’t in the past with AoE, AoK, AoM. An active user community supports the interest on a program.

How to backup files

As mentioned above, a backup is a safety-copy of the whole program or particular, certain files. It is not needed, to backup the whole program directory – though it’s easy .. and if you have space abounding on harddisk or perhaps a CD/DVD writing drive. But merely the files you’re actually going to change need a backup.

1) manually saving the file(s)

For this you use the ‘copy and paste’ method from Windows. If you’re unsure how to use, consider to read the appropriate Windows help. You select a file with left mouseclick (or multiple files with Ctrl-leftclick) within Windows Explorer (not Internet Explorer), rightclick -> Copy, go to a separate directory (which you perhaps created before) and place the stuff with rightclick -> Paste.

Hint: hotkey for copy is “Ctrl-c”, for paste “Ctrl-v”.

2) using a backup program

Of course you can also use such program. Windows XP has an ‘inbuilt’ backup program. But perhaps you have such program on a computer magazine disc or found in a freeware collection. For the usage see respectively the program’s manual/help.

A backup program has the advantage, that you can ‘teach’ it once what to backup and the next backup or restoring files can be executed semi-automatically.

Btw: also usual archiver/packer like eg. WinZip can be used as backup program.

3) advanced methods

Sometimes renaming files/folders is more effective than copy’ing.

For an auto-backup you can also use a batchfile (DOS-commands) which copies, swaps or renames certain files or whole folders.

Clever guys can also use the MS Installer for such.

The basic modding tools

1) The most important tool is a text editor. With this you edit nearly all non-graphics files. In emergency Windows’ Notepad can be used with care. But it must be seen as BTN-Editor (better than nothing). NP tends to wreck the files by auto-reformat (inserting unwanted new-line chars) even when word-wrap is disabled.

Much more suitable is a so-called “programming editor”, which has additionally very handy features like auto-indent, syntax-highlighting, macro ability, etc. You can find such editors in good freeware collections – I recommand to try out a few. If you have absolutely no idea, a good choice was eg. “SuperEdi” from WoLoSoft.

2) For deeper modding you need access to the datas in the .bar files. Though there are some other bar readers, a ‘must-have’ is AoE3Ed. For download and usage read carefully the whole topic.

This tool package comes with an ArchiveViewer, which lets you preview and extract certain files. Hint: when unpacking, the user given path + bar file path is used. It’s recommanded, to unpack to a work directory, not directly into AoE3’s.

The AoE3Ed FileConverter transforms xmb <-> xml and ddt <-> tga.

AoE3Ed can’t re-import extracted files into a .bar – but it is not needed (see below)

3) For working on the graphics files (like textures or images) you need an image processing software which is capable to handle .tga (Targa) files.

For a quick overview or simple manipulations like resizing/exchange a good viewer/converter is sufficient. Recommandable is eg. the free IrfanView.

For other gfx software browse in the usual freeware collections to find the right thing. Perhaps have also a look at GIMP.

4) Creating new models is at present not possible – unless you have 12,500 US$ abounding to acquire the Granny 3D SDK.

But (for advanced users) it’s possible to combine from present stuff models and animations. A great help to lookup something is the free Granny Viewer from RAD Gametools itself.

Where are the important files?

AoE3 installation uses different directories on HD drive.

At first the “program directory” (often referenced as “PROGDIR”). This is the folder where the program’s executable resides. In a standard installation usually “C:\Program Files\Microsoft Games\Age Of Empires 3\”. But this depends on language version (eg. in german version “Program Files” = “Programme”). Of course with a custom installation the PROGDIR could be elsewhere.

Then there is at least one “user directory” (often referenced as “USERDIR”). Every user registrated on your computer has his own USERDIR. You have access to this folder from desktop with “My Documents\My Games\Age Of Empires 3\”. The absolute path is “C:\Documents and Settings\{user name}\My Documents\My Games\Age Of Empires 3\”. But this may also differ depending on language version.

Important note:

After a fresh installation, most files are write protected = read-only. If you want to change something, you have to delete the read-only flag: right-click on the file, select ‘properties’ and disable the ‘read only’ flag.

Overview of folders and files: (green = relevant for modding/designing)

The AoE3 program directory (PROGDIR)

The root directory has since patch0.5 DataP.bar – not mod’able, but for looking up some changes: the files inside override existing files from other .bar’s – in doubt check it for latest versions.

\1025 – \3082 : language dependent configuration files – system only

\AI : contains the ‘Artificial Intelligence’ files to control the CPU player.

\art : all models, animations, graphics

\avi : “Audio/Video Interleave” files in .bik format – the ingame cinematics, ‘films’

\Campaign : all AoE3 campaign data – also custom HC files should be placed here

\data : the ‘number one’ folder for modders – contains all stats, gameplay relevant datas

proto.xml : the units’ prototypes descriptions, units’ stats

techtree.xml : civilisations’ techtrees, enhancements, shipments

stringtable.xml : all texts for a certain language referred by a text ID

\FONTS : self-explanatory

\render : datas for the rendering engine – for profis only

\RM : the standard/default “Random Maps” and auxiliary files

\Sound : what the name says – all the noises

\Startup : default configurations for game setup, hotkeys – see user startup below

\ rigger : only important is typetest.xml for manipulating trigger conditions/effects

\Users : contains the DefaultProfile.xml for new users

The AoE3 user directory (USERDIR)

\AI : the AI log files – at present only used for dumb taunts

\campaign : temporary campaign intermediate states

\Data : at present unused

\HomeCities : at present unused

\RM : this is the place for custom/downloaded RMS files

\Savegame : not only saved games, also skirmish homecities or campaign HC stats reside here

\Scenario : this is the place for created/downloaded scenarios

\Screenshots : self-explanatory

\Startup : additional custom game setup or hotkeys should be placed here

\Trigger : interesting for debugging triggers is trigtemp.xs

\Users : profiles for current and new users – editable

Note: Many – most of the datas is packed in .bar files. These require a special tool to view or extract something (see tools and below).

Overview of important file types (suffixes) in AoE3 (alphabetical)

.age3scn : a scenario file from AoE3’s scenario editor – don’t confuse with a RMS (random map script): these are from type .xs

.bar : a packed/compressed file archive/library. It can contain hundreds of single files. It’s at present not possible to change bar files easily – but it is not needed to re-import extracted files. The files have a relative path description and must be merely placed according the given path. For example the bar file “Alpha\Bravo\Charlie\some.thing”: “some.thing” goes into folder “Alpha\Bravo\Charlie\” (perhaps to be created).

.cfg : a ConFiGuration file – mostly editable, but could effect OOS errors if done in program’s directory.

.con : a keyboard (CONsole) definition

.ddt : a pre-compiled graphics file – usually converted from a .tga

.gr2 : a GRanny2 file from the Granny 3D system. At present not possible to edit – unless you have 12,500 US$ abounding to acquire the Granny SDK.

.tactics : from type xml – but never append a .xml suffix behind!

The tactics files describe the objects behavior and are technically the connective link from proto to anim file.

.tga : a TarGA graphics file – used for all images and textures.

.xmb : a pre-compiled xml file
In most cases it’s more effective to use xmb instead raw xml files – xmb files are quicker processed by the AoE3 parser, they are always accepted and you have a basic syntax check when converting xml -> xmb. So it’s recommanded to use xmb’s only and keep the source xml’s in a separate work directory.

.xml : the most used filetype – editable with a text editor. Don’t doubleclick on file – it will by default open with Internet Explorer.
XML = Extensible Markup Language. It’s often used for simplifying data handling and transfer. For more background info see W3C

.xs : XS is the programming/scripting language of AoM and now also AoE3. This filetype is used for RMS as well as for AI files. Also the HC people are controlled by XS scripts.