43 ratings
Ozhara's Modding Guide for AoE 2 HD
By Ozhara
This Guide describes how to publish a workshop mod for AoE, where to find graphic and sound files and how they work, as well as how to mod them.

If you think the guide is missing something important or a point isn't that clear - just tell me and I'll adjust the guide. :)
1) How to publish a mod to the workshop
Ok, lets do the basics first. You have some files you want to upload, a scenario for example.

1.1 Place all files in your game directory
at the place they have to be so their content shows up in your game.
This is REALLY important, as a subscribed mod extracts all contained data to exactly that folder in your game directory, you chose/uploaded it from!

1.2 Now start your game and go to the workshop:
You can also reach the workshop by going to the scenario editor and clicking the workshop button in the editors menu. For some reason larger mods did succeed the publishing for me more often when using the workshop through the scenario editor...

1.3 Choose all files your mod shall contain
such as game files, readme files and so on. The preview image you can select later:
By clicking this button, a file dialog opens where you can pick all files you want.
But this dialog doesn't support all file extensions. In case you want to publish a file whose extension is not supported, just browse to its folder and write its name down by hand. It then will be selected correctly.

1.4 Set the mods general information and publish it.
  • A) Write down the mods title.
  • B) Choose the mods type.
  • C) Here you can write down the mods description. But the length is limitated while the description directly set in the steam workshop can be much MUCH longer. So I wouldn't write it down here.
  • D) Set the visibility of the mod. In case you want to try it first in a closed beta or want to write down the description directly in steam without someone looking at it before you're ready, set it to friends or hidden. Just keep in mind, your mod will show up in the 'most recent' page at that timestamp you published it, not when you set it to public. So at days lots of mods are published, waiting too long could be bad for beeing recognized.
  • E) Click this button to choose your mods preview image. You can't set it later and only change it by updating your mod - what is very buggy, so choose the right one right now!
    In case you add additional preview screens in the workshop, this main preview image will be shown at the right and not in the normal preview section anymore.
  • F) Publish your mod - to succeed your mod, including the preview image, must be smaller then 100 MB (if it's not, you'll get error 21). And the larger it is, the more time it needs, for my larger soundtracks it was up to 45+ minutes. And the larger the mod is, the more likely it is it will fail due to server/connection errors, showing up as error 16. As I mentioned before, for me it failed less often at large mods when publishing through the scenario editor instead of the main menu.
2) AoEs modding system
This is really important, as most bugs and confusions regarding mods not working as expected are related to this.

If you subscribe to a mod, steam downloads a zip archive without an extension to your game\mods folder. If it does, you should be able to see an entry called 'AoE workshop content' in your steam download tab. Wait until it is finished.

When you start your game the next time, this mod archive will be extracted while the intro is playing. If the size of that data is larger, this can take some time, so to be sure you don't miss some mod data ingame, don't cancel the intro too early. I experienced that no data is extracted after the chess video starts, even if there is data left... In that case just start AoE one more time.

Steam seems to limit the amount of active mods, I experienced no subscriptions were taken into account after using 30 mods, until I unsubscribed some.

If you want to uninstall a mod, unsubscribing only tells steam not to take a mod into account when checking the game directory next time. So nothing will change only from unsubscribing.

To reset your game data, you have to verify your game cache.

For every game you have installed, steam has a list which files belong to the installation package.
When verifying, steam checks your game directory against this list and deletes every file on it that has been changed.

So you now have a) missing data, and b) if a mod contained additional files, like a readme, a scenario or something like that, these files aren't touched by steam and will remain.

At the end of the verification, steam will download all missing files.

Beside that the mods archive is still there too as it also is an additional file. And sometimes steam messes up your mod archives status.
For the same reason, if you don't use a mod anymore, don't just subscribe to anothermod overwriting the old one, but uninstall the old one.

So when uninstalling a mod, you should do the following:

a) unsubscribe
b) delete the mods archive file
c) delete all additional files if you don't want to further use them (for the 30 mod limit perhaps you just want to unsubscribe from a map but still use it)
e) verify your game cache
3) Where to find graphic and sound files
If you want to mod some game files, you first have to know where they are.

3.1 For sound files, check your game\sound folder.

All soundtrack files are in the 'music' subfolder.
All ui related sounds like main menu, civ related game starting as well as win and loose you can find in the 'stream' subfolder.

3.2 Non terrain graphics you can find in your game\data folder.

All interface graphics are contained in the file 'interfac.drs', all other graphics you can find in 'graphics.drs'. The file 'terrain.drs' contains the original terrains, but for the HD version Hidden Path changed the graphic system.

While you can find the default graphics here, if you want to mod these graphics, this shouldn't be done by editing these files but by using the modding system HiddenPath implemented.

Because every file can only be changed by one mod, modding the drs files would limit you to one graphical mod.
As a drawback, the modding system of AoE uses additional files for non terrain graphics.
So they will never be deleted/uninstalled until the user does it manually.

3.3 Terrain graphics can be found in your game\terrain folder.
4) Modding of sound files
When looking at the sounds (as well as some other files), in some cases you'll find two files, only differing in the one having a 'x' at its beginning. That means, the file without the leading 'x' is the files variant for 'The Age of Kings', while the other one is the eXpansion file. In case you use 'Forgotten Empires', there might be another version for that expansion. So only the last one is used.

The music for the main menu music is named xopen.mp3 and located in your game\sound\stream folder. The main menu music for FE is named xopen_x2.mp3.
In case players of both version shall be able to hear your replacement, you have to replace both files. Same with win and lost sound for example.

Without mods active there is a file called music1.mp3 which contains the 'Age of Kings' soundtrack, and about 20 named xmusic1-20.mp3 with 'The Conquerors' one in your game\sound\music folder.

'The Conqerors' soundtrack uses the new sound system that can handle multiple soundtrack files.

In case you want to combine some soundtracks or just publish a sountrack with a seperate file for every track like this (as I did for several of my soundtrack mods), you have to name them like this:


AoE will play them in their numbered order as long as there is a higher number left and there is no gap in the files numbers. If one of those two things happens, it will go back to xmusic1.mp3 and repeat looping through the files.
Of course this means the first file has to be number 1. Without that file, you will have no sound ingame at all.
5) Modding of terrain graphic files
The terrain files you can find in your game\terrain folder.
This folder contains a textures folder with 29 png images in 512x512 pixel format.

When creating a map, think of it as one layer per terrain, the png file placed side by side with itself.
By actually choosing a certain terrain at a specific area of the map, the fix terrain layer will become visible at this area.

You may have noticed, different terrains do blend into each other differently
, especially the borders of the ice terrain are unique.

The blending is defined in the blending files found in your game\terrain\blends folder.
These pngs are black and white, white for the actually placed terrain, black for the surrounding ones. The shape of the white parts edges and the grey parts define the terrains border and blending area/type. Here as an example the normal ice blending texture and the one I'm using for my space terrains to create a '3D like planet border':
Here an ingame example:
As you can see, the blending texture shows different compositions of the white and black terrain area.

Last thing on terrains is the water effect
HiddenPath implemented.
It consists of three files you can find in your game\terrain\water folder.

The files normal0 and normal1.png do look like normal maps. The wave effect is created by having one layer of the normal1 image like with the terrains, and one wit the normal0 image. The first one (normal1) can be seen beneath water terrain, the other one (normal0) moves over it from the left bottom to the right top. This moving combined with color differences (or not) at a specific pixel at a specific time, generates the generall wave effect.

But that's not all, the water terrain itself and the wave effect do interact with the last image, the sky_hemisphere.png. This file is very special.

It's not used 'completely' as the other ones. Like them, it is rotated 45° to the left and stretched to fit the ingame tiles. But instead of being placed side by side with itself to create a layer for the whole map, this one png is stretched across the whole screen.

This is the file I'm using for my moving water V4. The red rectangle shows the visible part ingame. It's the top corner (after the rotation). Depending on your resolution (width) this area can vary.

The default image is black/white too. At areas that only have one color, no effect is visible. When not modded, there is only a small part in the upper left of the screen showing 'reflections' and waves. This is for at that area different black, white and grey shades do change quickly.

If you use a different color like green for example, the water will get a touch in that color as you can see in the cinematic water mod.

When using the same color as the water terrains like in my example, the water gets a blue touch. But it is already blue. But my image isn't just blue, but has different colored areas. This way the wave effcet is more subtle as with black and white for the color shades aren't that different.

What can cause problems are water terrains that have a structure themselve or contain a lot of different colors. This way the wave effect is less visible for it interferes with the terrains structure which breaks the wave effect. With different colors, regarding to the color of your hemispere image, it can happen only some areas show a wave effect for some terrain colors do absorb it.

Sadly for the implementation of this file it's not possible to give every different colored area on a water terrain a matching area on the hemisphere image.
6) Modding of non-terrain graphic files
6.1 If you want to mod non graphic terrains, you first have to understand how these graphics are implemented.

All graphics are implemented in a drs file. For now we'll stick to graphics.drs, ui graphics are in another file.

These drs files you can find in your game\data folder.

A drs file can contain images (bmp), sounds (wav) and scripts.

The graphics are organized in slp files, that contain all images for a specific animation. So a unit for example has several slp files as it has several animations like standing, walking or attacking. A buildings image is a one-frame animation. Objects like trees have one animation for every forest type, choosing one frame for each tile randomly.

In the file empires2_x1_p1.dat there is a graphic object defined, pointing at a specific graphic entry in the drs file using the numeric id the slp has.

You now could change the bmps contained in a slp file contained in the drs file directly. That way you would simply upload that one file and that's it.
But that way you could only use one graphical mod, as every file can only be changed by one mod.

HiddenPath implemented a different system, using it themselve for the new HD cliffs and flames.
(So the originals are still in the drs file, you just installed fix mods they implemented for these graphics.)

The game checks your game\data\slp folder for seperate slp files. If it finds a file with the same name a graphic object in the dat file has, this graphic will be replaced ingame.

You will find there the files clf01_NN.slp - clf10_NN.slp and 'flm' ones. That are the new HD mods HiddenPath implemented.

Just in generall, files ending with '_NN' are main graphics, files ending with '_0N' are shadow graphics (some objects have a seperate shadows, showing up ingame as semi-transparent (buildings for example), others have their shadow in their main graphic, showing up as completelly black (units for example)).

6.2 To edit these graphics, I recommend two free tools I'm using:

1. Advanced Genie Editor[aok.heavengames.com]
2. Turtle Pack[aok.heavengames.com]

Both of them are fan made as there exist no official modding tools for AoE 2.

Turtle Pack can be used for everything regarding drs and slp files beside actually drawing.
(I'll only cover the most important functions here.)

With the Genie Editor you can edit the empires2_x1_p1.dat in your game\data folder and change the games mechanic. If you want to do this - there are a lot of tutorials out there.

For now the interesting thing is to get the slp names, for extracted slps are named with their numeric id, that is used as a pointer by AoE. But HiddenPaths modding system needs them to be named with their objects name.

6.2.1 Use Genie Editor
to get the right name for a slp do the following:

Open Advanced Genie Editor. You'll get a dialog where to choose/set general file locations.
You can choose from several path presets if you want to.

Important is the location of the dat file you want to open.

If you want you can also type in the path to your language files, then several unit texts will be shown as set in them in the editor.

Click on OK and the editor will open the dat file. For me the dialog shows up two times as well as the editor window. Just close/cancel the second one.

The editor looks like this:

Now select 'SLP' as the first filter, type in your slps id (in this example the Knights attacking animation) and apply the filter by checking it:
As a result you get the corresponding graphic object entry and it's name (without the file extension of course).

6.2.2 To get in contact with the graphics you want to change, just open the graphics.drs using turtle pack.
In the example I searched for 'Knight' to find the attacking animation (and as you can see on the id, the Knight is not the Knight. There are several units that have different names as a slp or in the dat file:

Now we can extract the slp file. It opens a folder dialog where you can set the right one:

Now you have a slp file. Open it with Turtle Pack:

  • A) AoE has no real collision system. Each object blocks an amount of tiles. The 'X' in the center is the center for the objects graphic. That one can be positioned where you want. Theoretically the graphic could show up 3 tiles away. It would still block its building tiles, but be shown somewhere else with no actual collision at the graphic. You can change the position by using the arrows or 'STRG + Arrow Keys'. This has/can not to be done on the graphic itself!

  • B) With this Button you can select all frames on the right. It also works with 'STRG + A' when you already have one selected. The Default is no selected frame.

  • C) All selected frames will be extracted as seperate bmps to the folder you will choose in the opening dialog.

  • D) AoE uses an indexed color palette. This means it uses no colors, but pointers to a color for every pixel. That color is defined in the palette. Therefore each image you want to import should be converted to the right palette first (It works without, but you WANT to convert it!).

    As you can see this works independant of the actual frames. You can convert whatever you want. Just choose the files by hitting the 'Add' button and choose a directory the converted bmps will be saved in. Hit start and then close the dialog (this doesn't work automatically).

    After doing so, you should replace the frames (you can do a complete new slp, add or delete frames, but the used frame count is defind in the dat file, so additional frames doesn't show and missing ones will result in empty frames beeing played. So for just changing existing visuals, just replace existing ones.):

    For the replacement, choose the new frame and set player color and transparency.

    The transparency defines which color of your bmpy shall be changed to the transparent one.

    The player color means which color you used in your bmp as player color. This is important as the AoE palette has 8 exactly defined values for every players color shades. When extracting a bmp, every pixel that is supposed to change it's color according to players color will be colored in the chosen player color (default is blue). To convert a real color back to the undefined player color one, you have to set this. If you choose red for example, no red pixel - even if it matches a red player color value - will be interpreted as player color but shown as red - for every player.

    On the other hand, every pixel that changed to a color shade of the chosen player color while converting - even if it wasn't meant to have players color - will have it ingame. And every pixel supposed to have the players color but doesn't have the right color value after converting - will not change its color ingame.

  • E) You can verify if a pixel has the right color by changing the player color on the left side of the editor. This changes all pixels marked as player color to the right color shade of the chosen player color. The chosen color is also the color used as player color when extracting a bmp.
< >
Ozhara  [author] Aug 16 @ 3:25am 
You have to put your files exactly where they have to be.

Then when publishing your mod, choose these files from there. Their destination place is automatically set by the folder you add them to your mod from.

When subscribing to a mod, it's first downloaded to your temp folder by steam.

At the next game start it's copied to your mods foldr by AoE and then extracted. This takes places while the intro is running. So canceling it too early also cancels the mods installation.
Just wait until the chess video starts - nothing will be copied/extracted from that point onwards. -> This also means if your subscribed mods are too large in size, it can be you have to start AoE one (or more) time(s) to get everything installed automatically.
This is problematic especially for soundtracks due to their size. Therefore I would always recommend to extract mods manually if they are a bit larger in size or to use my mod manager.
Hodor Aug 15 @ 6:38pm 
Thanks. I can publish now. The only problem now is when I have friends add the mod. Or me for that matter. The new taunts don't work. The taunts only work when I put the file with a number directly into "taunt" folder and then into "en" folder. No one can get the mod and then get the taunts. It doesn't seem to transfer over.
Ozhara  [author] Aug 14 @ 11:31pm 
Do you know where you installed steam and AoE?
For me it's 'T:\Steam\SteamApps\common\Age2HD'.

If you don't know the path, when right clicking on AoE in your steam library, there is a button in one of the tabs that leads to that folder.

Well, and in your AoE folder is a folder named Taunt. All your changes have to be placed in that folder. This is for a mod needs the contain the whole game folder structure so every file can be copied to the right place when extracting it. This is done automatically based on a files place when adding it to a mod.
Hodor Aug 14 @ 4:23pm 
All I would like to do is make a few taunts. I can go into the preferences and add them to local content etc. and that works fine. But when I try to add files to the steam workshop on AoE it errors.

"Error: You can only add files that reside within Age of Empires II HD's installation directory or a subdirectory"

How do I do this? I need to place all files in the game directory. What are the steps?
Ozhara  [author] Aug 12 @ 2:04am 
Sure it is.
You have to use Advanced Genie Editor and edit the dat file in AoE\data:

HD: empires2_x1_p1
FE: empires2_x2_p1

This means you have to do all changes twice for you can't copy/paste your changes with Genie Editor from one file to another. - as far as I know.
Ozhara  [author] Aug 12 @ 2:04am 
To Add a unit you have to define a new unit, then to define at least one technology that leads to that unit and one research that triggers the technology. For updates and other stuff you have to do more technologies and researches.

While a unit only needs one graphic per age - each representation of a building is a new unit technically, when ageing up, the buildings get replaced/updated with the new ages unit, units need 50 images, 10 per animation. And - here too each ages representation is anew unit. So you need update researches and technologies as well as all the images.

Don't forget there can only be one mod changing this file at a time. So in case you want to still use unlimited population, staying corpses, more ressources and such - you have to add them to your edits as well.
Psychocrysma Aug 11 @ 3:55pm 
Is there no way to add units, buildings and such?
Ozhara  [author] Aug 5 @ 6:28am 
The units name is shown in the 'Language DLL Name' field.

In case the text is thought to be shown differently depending on the used ingame language, this field shows the entries index number from the language file.
If you type a real text into these language fields it become static.

The language files can be found in AoE\Bin\
So - no real names in Genie editor.

And as far as I know, there is no way of making this more easy... sorry.

I always searched for a unit in the graphics.drs, used the slp number to find the internal name und filtered the units for it so all animations showed up...

But be happy - take a look at the technology-tab - they are ALL named chunk4... THAT is really annoying...
When I tried to split units so every civ has their own models I needed to changes researches and technologies too...
alwaysbehumble Aug 5 @ 6:11am 
I have One question:
How to display a unit's real name in the Genie Editor?
When unit names are displayed in the left column under the "unit" tab, (as one of the pictures on this page shows), they are all in their internal names, which makes deciphering which one corresponding to what a headache. To top on that, they are not even in alphabetical order, making track a particular unit almost impossible. (Unless one is willing to spend half an hour browsing through the entire list, playing Sherlock from term to term).
Is there a way to display units' in-game names?
Red Dragon Jul 7 @ 2:17am 
Awesome, thank you so much for your speedy reply. I'll get to it as soon as I got some time on my hands again :)