Hi everyone,

I'm the lead programmer for Age of Mythology EX and the work on the Mod Manager continues. We have now enabled it for everyone, so if you were using the beta branch, it is gone now. This thread is designed to be the goto place to report bugs and offer suggestions as we continue to improve it.

I really want to give credit to the modding community, especially Alexastor, Ozhara, and Notud who have been instrumental in providing feedback and creating new mods. Wouldn't be half as good without their input.


Now let's move onto how the Mod Manager is designed to work


The biggest goal of mods is that files do not interfere with original files. That means all modded files live in the mods\ folder. Inside the mods\ folder, you'll have folders for each uniquely named mod -- the name of the subfolder is the name of the mod.

I wanted to make a mod called "Alfred IS Goat" which is a simple mod that replaces the goat icon with Alfred the Alpaca. So I created a folder called "Alfred IS Goat" inside mods, then found the goat icons -- textures\icons\animal goat icon 64.bti and tga. (More on ddt later). Then I copied it over to the mods folder preserving the directory structure precisely yielding mods\Alfred IS Goat\textures\icons\animal goat icon 64.bti/tga.

The game code has been altered to look for substitute files -- so if you have the mod subscribed, when the game looks up animal gaot icon 64, it'll find the modded one and use that.

For those familar with the original Age of Mythology, you may know about BAR files. BAR files in Myth are giant containers containing hundreds if not thousands of files. Early in development we moved towards loose files to mitigate conflicts and effectively open the game to be modded. We actually plan to put BAR files back into the original game assets (which speeds up load times, but not by much). We did however, permanently kill xmb files (binary versions of xml) -- human readable was an easy choice. However textures using TGAs are very expensive so DDT files are going to eventually be mandantory for all published mods. Don't worry, the conversion will be automated when that happens. If you look at our splash screen assets, as a TGA, they would be 8MB each, but as a DDT they only take up 400KB. Extreme example, but compressed textures are necessary to maintain performance.

The overall point is, modding loose files is easier from a process perspective, and conflicts will be much less frequent then if people were to mod bar files. Two modders can't have two different textures2.bar files -- one modifying icons and another modifying terrain. In that case, only one could win. With loose files, both mods can co-exist.

The desire was to make publishing as easy as possible. Everything possible has been automated:

1. Mod Titles match your directory name. If you want to change the title, rename the folder.
   
2. Author is automatically determined based on the user logged in to publish.
   
3. Visibility defaults to public, but you can change it whenever you publish.
   
4. Description is something you can enter before publishing. It'll remember what you've typed so you can edit it later.
   
5. Steam tags are automatically calculated using internal file filters and wildcards. You can have several tags depending on how extensive your mod is. In Age of Empires HD, you could only assign a single tag.
   
6. Preview icon is automatically assigned if you call it workshop-preview-icon.jpg and place it in the root of your mod folder -- so mods\Alfred IS Goat\workshopt-preview-icon.jpg. Desired size is 640x360, but can be larger or smaller (it'll just scale to fit).
   
7. The first time you publish a new mod, it is considered a publish operation. Subsequent times you publish the same mod, it is considered an update operation, which replaces the original mod. It is completely transparent and automatically does this for you. Updates are powerful because you are able to retain your ratings, comments, and other status.
   
8. In order to publish, you need to agree to these terms provided in the Steam Workshop. The game will pop this up automaticaly as needed, but you can do it outside the game too. If you don't agree to the terms, you can still publish mods, but nobody else will see them until you agree to them. This is good because it doesn't block your experience.
   
9. While actively publishing, you'll receive real-time feedback. Once you start uploading a mod to Steam, it is largely out of our control. Mod size, bandwidth, and Steam servers are all factors on how quickly a mod is uploaded (or whether it succeeds at all). The smallest mods should take 10 seconds or less, but the bigger mods around 100MB can take 2 minutes to upload and accept receipt.

Subscriptions currently take place while browsing the Steam workshop outside of the game. When you subscribe to a mod, a list of subscribe mods becomes accessible to the game when you load it up. The game then automatically downloads and applies each mod and enables them by default. The game also downloads any new updates to subscribed mods. When a mod is updated, it is a completely clean replacement, so you'll never end up with orphaned files from a previous version of the mod.

If you subscribe to a mod, then later unsubscribe to it, the Mod Manager will automatically remove those files from your game the next time you run it, and they'll no longer be accessible, unless of course, you subscribe to it again.

However, if you are the original author of the mod, unsubscribing will never remove the mod -- you made it, you own it! However, if you accidentally manually delete it, your mod will automatically download. The reasoning for this behavior is to prevent any potential accidental overwrites.


There is a fully integrated Mod Manager inside Age of Mythology, accessible from the main menu. Just click on the Steam Workshop icon. There, if you have any authored or subscribed mods, you'll be presented with a prioritized list of mods. Some of the features:

1. You can enable or disable mods without removing them.
   
2. You can change the priority of mods. The mods at top will "win" against mods with conflicts below it. So if you download 3 different terrain texture mods, the highest priority mod will be used first. Conflicts are handled on a file by file basis so both mods might actually change different files. That could have unwanted consequences.
   
3. You can view additional details of selected mods including a full list of files and tags, as well as how large the mod is.
   
4. If you authored a mod, you can publish it from here.
   
5. Whenever you change any priorities, enable or disable mods, you'll need to restart the game for them to apply, but there is a handy reload assets button that will do this for you properly. Also now, this is forced and smartly detects when a restart is necessary.

While still in beta there are several things that aren't currently set up yet -- but we'll be working through them in the coming days, and the plan will be to frequently update the Mod Manager branch with specific fixes:

• FIXED IN 1.6: Priority not hooked up (buttons do nothing). But you can edit mod-stats.txt in the root of your mods folder to change them. Just make sure the game is not running when you do this. There are also issues with mods having the same priority as another mod -- though it doesn't matter. The order in which they appear in the mod manager list is the actual effective priority.
  
• FIXED IN 1.6: Publishing currently doesn't enforce the original author -- so please be nice and don't plagerize other people's mods.
  
• According to intenral Steam documentation, published workshop items cannot be any larger than 200MB, but currently that limit is 100MB due to the way streaming is implemented. This will be resolved soon so that you can make mods of 200MB, but we'll test the limits. As it is, all mods are compressed before upload to maximize this. This is also why DDT files are going to be very important in controlling size.
  
• Speaking of the DDT format, the original Myth DDTs do not work with the new Myth (they may in some cases, but there are not intended to be supported). But you can work around that by using community tools to convert old DDTs into TGAs, then converting those to new DDTS. We will be releasing tools and documentation that will convert between the new formats.
  
• When creating TGA textures, you need to create them with an alpha channel and save it as a 32-bit TGA without RLE. If you save a TGA with RLE, you will run into texture seam issues.
  
• FIXED IN 1.6: Support for custom languages, scenarios, campaigns, replays, saves, random maps, font lists.
  
• Several file types are not yet "respected" by the mod manager. It is important to understand there are two completely systems at work here. One is the mod manager that tracks all the files. That part works fine. The other part is the loader within the game that utilizes the files. Some files cannot be modded right now -- a lot of the bigger sensitive files like techtreex.xml, protox.xml, etc.. are intentionally not loaded through the mod manager. But other files are supposed to be -- like scenarios, campaigns, replays etc... which we're expecting to be quite popular mods. For now, it's best to report files that you want respected and we'll tackle those as quickly as we can. I've added a detailed logging system that will report which files are loaded or not. You'll need to run the game with a launch option of +modmanagerdetailed. Doing so will cause the game to generate significant logging and add a few seconds to your start up time. Here's are some snippet examples:

PS: You can find the log file in Logs\<TIMESTAMP>\mod-manager.txt, but only in the modmanagerbeta branch. If you run with +modmanagerdetailed, you'll get all the extra file IO. If you don't, you'll get much less information.

Forbidden Files
For efficiency and security reasons, it was necessary to filter out certain file types from being included in any packaged mod file -- for example exe or dll files. But from a much simpler perspective, mod packages can only include files that Myth cares about.

Expected files not modded
If you modded SFX A Repeat.prt and your directories are set up properly, and that message shows up when you try to access that file, then it means the file is not yet respected.

Files that do get modded
Here you can tell which mod was selected for a particular file.

In the tools directory, you'll now find TextureCompiler.exe and TextureExtractor.exe. And below details how you use each. They are commandline tools, and they weren't really meant for end users, but you modders need them yesterday, so here they are in anycase. Also, there is one major caveat at the moment -- these tools will not create any directories, so you'll want to pre-create your output directories before running the tool, or else it'll silently do nothing. If you run the commands without any arguments, you'll get built in help text which is fairly similar to this post, and will be changed and improved over time.

An important note about DDT files. All of the old mods that were made for the original retail Myth have a different DDT format than now. The old formats are not supported by the new Myth, as the compression algorithms are completely different and vastly better now. You'll need to reconvert them by extracting them with TextureExtractor, then converting them back to DDTs via TextureCompiler. TextureExtractor will work with old DDT and new DDTs.

Texture Compiler:

Purpose: Compiles TGA + BTI files into DDT files usable by the game. The tool takes care of compression and mip map generation.

Usage:
Explanation of flags:

-o : Specifies the output file or directory. A filename must be specified when compiling a single texture or a directory name when compiling an entire directory. File or directory names containing spaces must be put in quotes.

-i (Optional): Specifies the input file or directory (same as -o). If this flag is not specified the application will look for textures in the current working directory. File or directory names containing spaces must be put in quotes.

-c (Optional): Overrides the compression format set in the BTI files. Valid options are:
DeflatedRGBA8: 32 bit (4-channel) zlib compression
DeflatedRGB8: 24 bit (3-channel) zlib compression
DeflatedRG8: 16 bit (2-channel) zlib compression
DeflatedR8: 8 bit (1-channel) zlib compression
BC1: Block Compression 1 (DXT1) compression
BC2: Block Compression 2 (DXT3) compression
BC3: Block Compression 3 (DXT5) compression
For terrain textures zlib compression must be used. For UI textures it is recommended to use zlib compression for optimal results, but this is not required.

Examples:


Purpose: Extracts both old and new DDT files into TGA and BTI files. The BTI files will automatically have all the correct options set for compiling these extracted textures back into the modern DDT file format.

Usage:
Explanation of flags:

-o : Specifies the output file or directory. A filename must be specified when extracting a single texture or a directory name when compiling an entire directory. File or directory names containing spaces must be put in quotes.

-i : Specifies the input file or directory (same as -o). File or directory names containing spaces must be put in quotes.

-m (Optional): Specifies a maximum amount of textures to extract. This only applies to full texture extraction and will have no effect when extracting a single texture.

-nm (Optional): Generates a default normal map based off of the contents of the extracted texture.

-spec (Optional): Same as -nm but for specular maps.
-gloss(Optional): Same as -nm but for gloss maps.

Examples:





Okay ask away -- the first pass was a random brain dump, so I'll update this posting as things continue to improve. Please report bugs with specific examples. Ideally you would post a mod that I could download to check out why it's not working as advertised. We take feedback really seriously and want to make Myth the best modding experience possible!