Tutorial and Basics

Making modifications to the in-game UI for AoE2:DE is surprisingly simple, albeit a bit limited. It's mostly for changing locations of specific UI elements and changing the textures of them. But you can do some really creative things if you start digging into more specific elements.

Hello World

Let's get straight into changing the in-game Main Menu.

1. Go to you widgetui folder, typically located at C:\Program Files (x86)\Steam\steamapps\common\AoE2DE\widgetui
2. It's recommend that you make a back-up of your widgetui folder. If you forget you will have to ask Steam to verify your files.
3. There, find the file dialogingamemenu.json and open it in your favourite text editor (like Visual Studio Code)
4. Find the line where it says "Text": "IDS_MAINMENU_TITLE", (at the time of writing this is located at line 66 by default)
5. Change it to "Text": "Siege Engineer's Menu",.
   Note: Outside of this tutorial it is not recommended to replace strings because the text will not be localized to other languages of the game.
6. Make sure you make no typos, as this might result in the game crashing, the Main Menu never appearing or error messages interrupting or freezing the game. Now save the file.
7. Start the game and load a Standard Game, if you haven't done so already.
8. Open the Main Menu (Hit Escape or F10 on your keyboard or click the Papyrus Scroll button at the top right by default)
9. The title where it normally says Main Menu (or equivalent to your language) will now state it's a "Siege Engineeer's Menu"
   If it doesn't work as expected please check that you don't have any other UI Mods enabled in the game, if so disable them then restart the game.
10. Congratulations! You just finished your first Widget UI mod. If you made your changes while the game was running you might have noticed that any change you make is instantly reflected in the game. While this super convenient, take note that when saving changes with illegal values or something easily missed such as skipping a colon or quotation mark, it could crash your game, so be careful before hitting that save button.

In the next section we explain how the WidgetUI works, what is in each file and how to the files work together. You can also dive into the next tutorial. Tutorial WIP -aP

Anatomy of a WidgetUI Json file

The Widget UI follows the same standards as any JSON file. If our are unfamiliar with JSON I recommend that you either "Google" it or play with the WidgetUI system and figure out how it works as you go.

File Types

There are three types of WidgetUI files

1. Layout Files - The files that describe what element should be where and what it should look like. Most of the work you will want to is is likely to be on these files.
2. Data Files - Files that point to Assets. They are there to make make sure that Layout Files are readable by simplifying long file names, and making it easy to change assets without having to go through all Layout files. Another important reason is to make it easy to make the UI work for different languages of the game.
3. Assets - The actual assets as referred to by the Data files. These include Text, Images, Sounds etc. Only the Images are stored in the widgetui folder (in the textures subfolder), assets such as sound and text are used throughout the game and have many different places where they are used and therefore are stored elsewhere.

<An image visualizing the relations between Layout Files, Data Files and Assets will appear here, someday>

An example of how we (didn't) use the Data Files and Assets can be found in the tutorial.
In Layout File dialogingamemenu.json we replaced the line where it says "Text": "IDS_MAINMENU_TITLE". IDS_MAINMENU_TITLE refers to "Main Menu" in English, but it would point to "Menú principal" in Spanish and "主菜单" in Chinese. But with our change to making it "Siege Engineer's Menu" it would be always that regardless of the users language.

However if we left it as IDS_MAINMENU_TITLE the game would have found that in the Data File stringreference.json IDS_MAINMENU_TITLE refers to a number 9446. This number is also referred to inresources\<language>\strings\key-value\key-value-strings-utf8.txt Where <language> would be a two letter code for the user's language. In the es version of that file you will find 9446 "Menú principal" written somewhere. The number referring to the Spanish version of "Main Menu".

While this isn't strictly required for you to do as well, it should give you an idea of how the Layout Data Files and Assets work together in the game, and what the benefits are of doing so. In the following section this is analyzed further for other file types.

Layout File

This is work in progress check back later <3 -aP

Coordinate System

AoE2:DE is marketed as a 4K remake of the original, for the UI this means that all coordinates are as if they are placed on a 3840 by 2160 pixel canvas. The (0,0) point being at the top left corner, and the (3840, 2160) point at the bottom right.

0,0-----------------------    
  |                       |    
  |                       |    
  |                       |    
  |                       |    
  |-------------------3840,2160

Publishing your Mod