Oriental Empires – Official Modding Guide

This guide explains how to use the new modding features in the 18 November 2021 update to Oriental Empires.


Oriental Empires now contains support for user created mods. You can create your own mods, or download them from the workshop. Mods may make minor changes to the game such as adjusting the combat strength of certain units, or the time taken for a technology to be developed or make major changes such as adding new units or a completely redesigned tech tree. Players may use several mods combined.

At present only limited support is included for adding new graphics.

Using a Mod

If you have any mods available, either because you’ve made them yourself or subscribed to them in the Steam Workshop then a new menu will appear after the publisher video allowing you select which mods to use. Select the mods by clicking on their selection indicator. You can use several mods at once if you wish. If they both modify the same game file, then the first in the list will take precedence. Use the up and down arrows to change the order of the mods.

Alternatively, you can specify which mods to use by making a shortcut to the game and using command line arguments. E.g.

Oriental Empires -mod MyAwesomeMod


Oriental Empires -mod mod_one -mod mod_two

If no folder is given, the game assumes the mod name is the name of a folder within “Documents\My Games\Oriental Empires\Mods” . Alternatively you can give a full path name to your mod.

Saved Games and Multiplayer Games

It is strongly suggested that players always use the same set of mods for a particular saved game. Although it may be possible to change around minor mods, it’s hard to predict what will and what won’t work.

Similarly in multi-player games all players should launch the game with the same mods.

Making a Mod Basics

Mod Location

The game expects to find mods in the folder “Documents\My Games\Oriental\Empires\Mods”. Each mod should have its own folder which is the name of the mod.

Folder Structure

Within its folder, the mod should follow the same layout as the game’s “StreamingAssets\Moddable” folder. Simply copy any files you wish to modify from this folder to the corresponding folder within your mod folder. You do not need to make copies of any files that you are not modifying.

To find the “StreamingAssets” folder use the Steam client to open the folder where the game is installed and then open the “Oriental Empires_Data” folder.

Extra XML Files

If you are making a small mod, it may be better not to modify the original game file, but to include your mod in a new file. This makes it easier to combine mods, since only one mod is allowed to modify a particular game file.

The game automatically loads certain files it finds within your mod, provided they are named correctly. It is suggested that you include the name of or acronym for your mod in the file names. For instance. if your mod is called “Imjin War” you might include the following files to describe its units

  • Mod Units IJW Korean.xml
  • Mod Units IJW Japanese.xml
  • Mod Units IJW Chinese.xml

Since the file names begin with “Mod Units” the game will automatically load them, and the IJW will mean that the names will not collide with files from other mods. If two mods have files with the same name, only the file from the first in the mod list will be loaded.

Supported Extra Files

Files with a “.xml” extension and names beginning with one of the following will be loaded form the “XML” folder.

  • Mod Factions
  • Mod Encounters
  • Mod Events
  • Mod Buildings
  • Mod Edicts
  • Mod Technology
  • Mod Units
  • Mod Resources
  • Mod PortraitSets

Files with a “.utf” extension and names beginning with the following will be loaded from the “Text” folder. Do not use “-“ in filenames in the text folder, except in a localization suffix

  • Mod Text

The Example Mod

In the game’s StreamingAssets folder is a folder called “Example Mod”. The easiest way to start experimenting with modding is copy this folder into your “Documents/My Games/Oriental Empires/Mods” folder. The example shows how to add units, buildings, techs, factions and portrait sets. It also shows how to remove items without modifying the existing game files, and similarly how to make modifications to existing units. It also shows how to add text for the new mod items, and how to include a scenario and a script.

Uploading Your Mod to the Workshop

If you want to upload your mod to the Workshop to share with others, press “~” key to open the console and type

  • UploadMod modFolder

modfoler can either be the folder name within the game’s usual mod folder, or a full path. The name of the folder will be used as the mod’s name in the Workshop. Alternatively, you can specify the Workshop name in the command.

  • UploadMod modFolder, modName

Text and Localization

Mod Text

If your game includes new units, tech items etc, you will need to create a text file that contains their names and descriptions. Place any text files you need to create inside the Text folder and make sure their names begin with “Mod Text” and have the “utf” extensions. Their file format should be utf8. E.g.

  • Mod Text My Unit Text.utf
  • Mod Text My Edict Text.utf

You do not have to create separate files for each type of object, you can just combine them into one big file

  • Mod Text IJW All Text.utf

See the text file in the example mod for the format and naming conventions to use in text files.

Localizing Mod Text

While most mods won’t supply text for more than one language, the possibility is supported. Simply supply versions of your mod’s text files with the relevant language suffix after the file name. e.g.

  • Mod Text IJW Unit Names -de.utf

Supported language suffixes are “-de” “-fr” “sc” “ru” and “pl”. English text does not have a language suffix, and the version without the suffix will be loaded if the correct version for the player’s language is not found.

Supporting a New Language

While there is a lot of text to translate, it is possible to make mods to translate the game to languages other than those officially supported. Doing this is much the same as making any other mod, just copy the text files into your mod folder and change the text. The game only recognized the language extensions for the officially supported languages, so choose one of these languages and change the text in the files with that extension. Players will have to choose that language to use your mod. Alternatively make versions of the translated files with all language extensions so that players will see your translated text, whatever language they have selected.


Viewing Errors

The game contains a certain amount of error checking for xml files. Press the “~” key to open the console to see any errors. You may need to click on the text area and use the down arrow to scroll to the bottom of the text to see all the reports. The error checking is not guaranteed to be exhaustive, so the game may well just crash if you make mistake, particularly if you include a malformed file.

Schema Files

The “Moddable/XML” also contains xml schema files with “.xsd” extension. It is suggested that you copy the appropriate ones of these to your mod xml folder, and use an editor such Microsoft Visual Studio to edit your xml files. This will help prevent you making errors in your editing, and allow the editor to show allowed elements and attributes and help with auto-complete etc.

Including Graphics

Tech, Unit, Building and Resource Icons

These should be “png” files, and placed in the “UI/Icons” folder. The example mod includes examples that show the correct format and size. These can be referenced from the xml files “without the png extension”as if they were built in files.

Faction Symbols

Place any custom faction symbols you wish to use in the “UI/Faction Symbols” folder. The example mod contains a large selection that you can use.


Place any portraits in the “UI/LeaderPortraits” folder. The example mod does not include any custom portraits, but you can look at the game files in the “StreamingAssets/Moddable” folder to see the format and naming conventions. Portraits are organized into sets, with each set in its own folder. Within that folder are separate folders for generals, scholars, ladies and optionally heroes. If you add your own portrait set, you will also need to include a “Mod PortraitSets.xml” file in your xml folder. The example mod shows how to do this.

Each portrait set must be complete in itself, you cannot add extra portraits to an existing set. You could however copy over the game files and mod the PortraiSets.xml to point to your new set.

Other Graphics

You can also include your own graphics for encounter and events.

Scenarios and Maps

You can include scenarios and maps to show off the features of your mod. Place these in the “Scenarios” folder. These can reference any new faction icons you’ve included in your mod, so do not place custom faction icons in the Scenarios folder.

Any scenarios in your mod will show up in the Scenarios section when you start a new game and load a scenario file.

You can’t edit scenarios in your mod with the scenario editor, instead create them the usual way in the “Oriental Empires/Scenarios” folder then copy the map and scenario files into your mod.

Scenario Script Files

Your scenario files can also scripts with special events. These should be given a .script extension and placed in the Scenarios folder. Note this a change from before when scripts had an xml extension.

Special Xml Modding Elements

Some new “command elements” have been added to assist making mods by adding new xml files rather than modding the existing game files. The standard games files don’t use these, but the example mod xml files show how to use them.


This element can be used in unit, building, tech and edict xml files to effectively remove an already defined item from the game. It doesn’t actually delete the item, but instead adds a “Never” requirement so that they cannot be used.


This lets you replace the definition of a unit, tech, building or edict with a new one. Simply copy the orginal definition into your xml file, make the changes you want and change the element type to “Replace”.

ReplaceArmorVariant and ReplaceEraVariant

Many units are defined with these elements, so there are also Replace versions of these. Note that when the game reads these, it copies the data from base unit afresh, so you do not need to include any changes you’ve made to the base unit (e.g. adding a requirement or changing the cost) in your ReplaceArmorVariant or ReplaceEraVariant elements, but you do need to copy the values from the original xml file.


Since unit definitions can be long and complicated, and sometimes you only want to make a small change, you can use the “Modify” element which is just for units. It can include any of the usual elements used to define a unit, but only needs to include the ones you wish to change. See the example mod for how to use it. Generally it will be easier than using Replace, but modifying a unit does not modify any armor or era variants, so you will need to include separate modify elements for each of these.

Unit Cost Modifiers

If you have a lot of units defined, and want to balance the cost, it can be very tedious to modify the recruitment and upkeep costs of each individual unit. Therefore a unit xml file can include “CostModifier” elements that include percantage modifiers that apply for all units defined afterwards in that file, or until another CostModifier element is reached. The standard game files use modifiers of 140%, so if you copy any values from these you will also need to include in your file to make the values match. Upkeep and recruitment costs are rounded to multiples of 5.

Written by Neutron

Be the first to comment

Leave a Reply

Your email address will not be published.