As you may know with version 4.0 a new workshop implementation was introduced.

Most content of this guide is still usable, but some has to be updated.

I'll do so soon! :)

In case there is anything not working as intended with AoE, you can make Steam to check if there is everything right with the games installation.
You don't need to have done something manually for a file to be 'corrupted'. This might be from your anti virus software doing 'stuff', a mod download having issues and all other sort of things.
This check is done by Steam verifying your game data is as it should be and reseting all files that got changed back to its default.
This does only apply to official game files and no local mod files, personal file copies or anything not beeing part of the default installation!

For Steam to verify your game cache do this:

If you subscribe to a mod, Steam downloads the mod to T:\Steam\SteamApps\workshop\content\221380\Mod_Id where Mod_Id is the mods id from its Steam sites url. 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, the mod shows up in the ingame workshop manager. Here you can enable or disable the mod and change its priority.

If several mods do change the same file, the mod with the highest priority wins.
Getting the correct order mostly breaks down to 'A specialized mod should have a higher priority than a more broad mod changing the same file'.

Not sure which mod to use?
Subscribe to several ones and switch between them by en/disabling them depending on your current mood.

To uninstall a mod, just select it in the ingame workshop manager and click 'unsubscribe'.
You might want to keept it for later though and just disable it for now.

If a mod was not updated to the 'new' file/folder structure introduced with patch 4.0, the mod is not compatible with AoE anymore. You can see this from a mod beeing labeled as 'old workshop' in Steam and shown red in the ingame workshop manager.
You can either try to contact the mods author so the mod gets updated, or you can try to get it back working manually.

My own mod manager also has a conversion functionality that can help you with this.

Ok, lets do the basics first. You have some files ready you want to test or upload.

by browsing to your AoE game folder in your windows explorer. By default this will be 'C:\Steam\SteamApps\Common\AoE2HD'.

In there is a folder named 'mods'. This is the modding area that solves only one purpose - giving modders a place to create and test their creations.

In there, create a new folder named like you want you mod beeing named in the Steam workshop.
In your new mod folder recreate the folder structure from within your game folder needed to place all modded files at the same location inside the mod as they reside at in the game folder.

So in case you want to replace the soundtracks first track, take a look where the default file is placed.
It is 'C:\Steam\SteamApps\CommonAoE2HD\resources\_common\sound\music\xmusic1.mp3'

Therefore you need to create all those folders so you can place your modded version here:
'C:\Steam\SteamApps\Common\AoE2HD\mods\resources\_common\sound\music\xmusic1.mp3'

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!

by adding the corresponding files to your mods main folder.

The thumbnail is your mods main preview that will also be shown in the Steam workshop and really advertises (or doesn't) your mod as it will be the first impression people will have of your work.

For an image to be recognized as the thumbnail image it has to be named _preview-image.png!

If you don't add an image, in the process of uploading your mod, the default preview image will be added - but you don't really want that one, right?

While the need for adding an image here is pretty much self explanatory, the addition of a description isn't.

'I can do that in Steam itself' you might think - and you are right.
BUT in case you ever want to update your mod and there is no description present in your mods main folder on its first upload, the default description will be added to your mod like with the preview.

If there is a description present, it will be used though - this means your detailed mod description you might have saved no where outside Steam will be overwritten with the default one when updating your mod later - except you added your wanted description to the _mod-description.txt file.

This file is no plain txt file though, but needs to use a specific syntax. Easiest is to take a look at a downloaded mod for this. Just exchange that files text after the 'Value=' tag.

by running the game.
You will see your local mod is automatically added to your load order that consists of all your subscriptions and all subfolders found in the 'mods' folder.

You can use it like any other mod now.

works the same way.
When selecting an local mod, you will see a 'publish' button beneath the mod list.

Left of it you can also check all legit content of this mod (this is somewhat irritating - EVERY content your mod might contain will get published - but only the files replacing default ones are listed and used for the estimated mod size).

In the process of publishing a mod, you get a second entry for this mod in your mod list.
This is for you are subscribed to your upload too.

So now you have the uploaded and local version as separate entries.
This is pretty helpfull as you can at every time compare your local copy to the uploaded one this way when applying changes later on.

works exactly like publishing it.
Select the local version of your mod.

In case you have no subscription of the uploaded version at this point, your local copy can not be linked with it and therefore counts as a new, never before published mod.

Publishing it means that there are two uploaded mods then.

When you are subscribed to the uploaded version as well, the 'publish' button is now labeled 'update'. Clicking it will replace the uploaded version with your local one.

An important note - the local and upladed mod versions are linked through their name.

So in case you edit your mods title in steam, you NEED to also rename your mods local folder. Otherwise the local mod will not be detected as your authors copy of the uploaded version even if you are subscribed to it.

If you want to mod some game files, you first have to know where they are.


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.

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 of 'The Conquerors'. In case you use 'Forgotten Empires' or another dlc, there might be another version (ending with _x2, _x3, ...) for those too. Only the last file (depending on a players used dlcs) is used.

The music for the main menu music is named xopen.mp3 and located in your game\resources\_common\sound\stream folder. The main menu music for FE is named xopen_x2.mp3, the AK one xopen_x3.mp3.
In case players with different dlcs are supposed being able to hear your replacement, you have to replace all the files. Same with win and lost sound for example.

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

The 'new' sound system currently used by AoE can handle multiple soundtrack files, so the original one-file-soundtrack isn't used anymore.

AoE will play all found xmusic files 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.

This also means, in case you use an old soundtrack mod that does not cover the multiple-track-files system, all default tracks that are not replaced will play before the mods soundtrack restarts.

So to replace the whole default soundtrack, you should add at least 23 track files to your mod.
In case I don't have enough tracks, I achieve this by adding the soundtrack multiple times and/or by adding an empty mp3 file from time to time.

There seems to be no limit, so you can add as many soundtrack files as you want. My Touhou sounbdtrack ends around xmusic150.mp3 for example.

This folder contains a textures folder with multiple 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.

For the ingame map is no square, but rotated and clinched, the same will happen to the png images. So your terrain images witll be rotated 45° to the left and get clinched.

, especially the borders of the ice terrain are unique.

The blending is defined in the blending files found in your 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.










HiddenPath implemented.
It consists of five 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 general wave effect.
Same for normal3 and normal4.png.
With the AoR dlc, the wave effect got splitted up, so shallow water has its own wave effect now.

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 clinched 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 afterwards.

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 (see the orange rectangle as an example).

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 the water is already blue and my sky_hemisphere 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 sky_hemisphere image, it can happen only some areas show a wave effect for some terrain colors do kind of '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.

All graphics are implemented as slp files.

These slp files you can find in your game\resources\_common\drs\gamedata_x2 folder.

A slp file contains all images (bmp) 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.

For more information about slp file naming conditions and stuff, take a look at guide to graphic objects

In the file empires2_x1_p1.dat there is a graphic object defined, pointing at a specific slp file using the numeric id the slp has as well as its object name. So both can be used for naming your modded file. I personally prefer to name slps using their graphics name, for everyone knowing the naming conditions will immediately be able to know what your file contains without the need to open or search for it or the need to memorize thousands of numbers.

For modded graphics, the game checks your game\resources\_common\slp folder for slp files using the graphics name and your game\resources\_common\drs\gamedata_x2 folder for slp files using the graphics id. If it finds a file with the same id or name a graphic object in the dat file has, this graphic will be replaced ingame.

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


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 by default. But you can also name them with their objects name now. -> Always use the objects name, this makes identifying specific slp files much more easy later on.

do the following:

Either look it up from my guide to graphic objects, or open Advanced Genie Editor.

If you use 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).

you want to change, just open the slp file with Turtle Pack then:

• 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.