You must be logged in to post messages.
Please login or register

Modding Discussions
Moderated by Alexastor, MosheLevi, Mister SCP

Hop to:    
Welcome! You are not logged in. Please Login or Register.5 replies
Age of Empires III Heaven » Forums » Modding Discussions » The Beginners Guide to AI scripting - Comprehensive Tutorial, Part 1
Topic Subject:The Beginners Guide to AI scripting - Comprehensive Tutorial, Part 1
posted 04-04-13 05:00 PM EDT (US)         
The Beginners' Guide to AI scripting - Comprehensive Tutorial, Part 1

My fellow forumers, I write what has not been written before for AOE3, a Comprehensive Beginners Guide to AI scripting. This guide is intended for anyone who has a basic knowledge of English and who is tired about fighting the same old dumb computer player. It is for those who want to make the AI build the right units and upgrade their units properly. Hopefully it will tell you some basic tips which took me over two month to figure out, in just one reading. Since there is much to cover, I do plan to write this guide in several parts.

Disclaimer: I, only an experienced player at this game, in both treaty and supremacy, did not touch AI coding until about a year and a half ago. I had a year before begun regular modification to the game, in other words, "coding" our Clan's Custom Patch. I say these things to let you know that I am recently a noob at coding, and even at AI modification, but want to share what I know. Hopefully this is the first of many great leaps forward in Age of Empires III modification.

Even as I plan, I do present this first part.

Comprehensive Beginners' Guide to AI modification

Question 1: What is an/the AI?

Answer: The AI, or Artificial Intelligence, is the computer player that comes with the game, which you can combat in skirmish, scenarios and multiplayer games.

It governs five main areas:

- Computer Strategy; "what should I prefer, Infantry or cavalry or artillery, or a mix of them?", in addition to being aggressive/defensive, favouring trading posts or native posts, also which specific units should be trained

- Computer build orders, in "Void" setups; "how many houses do we need before we age up?", and activation of Tech Monitors, i.e. allowing the computer to upgrade certain techs in certain ages

- Amount of Villagers the AI should train/maintain, and which types of villagers should be built for each civilization; economic bias on food, wood or coin, and the max gatherers needed for hunting, wood harvesting, mining, on mills or plantations.

- Naval Warfare; "How many ships/fishing boats should we maintain and which naval techs should we upgrade?"

- Homecity Cards; which card types should be preferred and which should be excluded; For instance, mortars are excluded because the AI doesn't use them properly...yet.


Question 2: How can I modify the AI? Where is it found?

Answer: You can modify the AI by opening AImain.xs with the simple program Notepad, which is included on every computer that has Windows installed on it. This file, AImain.xs, is found in your Age of Empires III folder in the Program Files (exact location explained later). However, if you have Windows Vista, it does not allow you to save things in Program Files. You must first copy and paste the file on your desktop, and modify it, then save, the copy and paste it back into the Program Files where you copied the original from.


Question 3: But what is AImain.xs, and why should I choose it instead of the other AI files?

Answer: The AImain.xs is the bulk of the Artificial Intelligence, and as described above, deals with most things relating to the AI. Thus, it is reasonable that modifying this file will greatly enhance the standard dumb-as-dirt AI.

To be sure, this file is found in the Program Files. If you have Age of Empires III installed via disk, the path should be this:

My Computer/Local Disk(C/Program Files (86x)/Microsoft Games/Age of Empires III/

The AImain.xs is found in the AI folder, which is inside the Age of Empires III folder. If you have Age of Empires III from Steam, however, the AI file is found in this following folder:

My Computer/Local Disk(C/Program Files (86x)/Steam/SteamApps/Common/Age of Empires III/bin

Then, once here you will find again the AImain.xs within the folder titled "AI."


Question 4: But hold on a moment. I see three "AI" folders, "AI", "AI2", and "AI3"; what do they mean?

Answer: "AI" contains the Artificial Intelligence for Age of Empires III without expansion packs, "AI2" contains the AI for Age of Empires III with the Warchiefs Expansion Pack, and "AI3" contains the AI for The Asian Dynasties Expansion Pack.

NOTE!!!! The AImain.xs in "AI2" contains the AI for both European and Native American civs, so if you want to modify the AI for the Warchiefs expansion, you do it here; If the player has Warchiefs and The Asian Dynasties Expansions installed, the AImain.xs from the AI3 folder contains the AI for European, Native American and Asian Civs, so that if you want to modify the AI for The Asian Dynasties Expansion pack, you do it here.


Enough of questions! I want to modify!

Don't be hasty, for with a little patience comes great reward. However, we will get right to business.

There are several who have made significant modifications to the AI, so it would be actually redundant to simply begin from the original AImain.xs, without at least taking a look at what others have successfully done before us. Let us put away our pride and arrogance and be ready to learn even yet the hard way.

Among these modifications, the most known is Felix Hermasson's Draugur AI, compatible with all versions of the game.

File link:

"What does it do, his modification?" you might ask. Felix was the first to make an AI that attempts to counter your units with the best available unit type, use the European church upgrades, upgrade its soldiers, use mercenaries from the homecity, fight better on sea, and ultimately, bring up a competitiveness that was lacking in the original computer.

However, Felix last did his final modifications in late 2008. Since that time, the Online Activity of ESO has slowly decayed, and people have stopped playing for the reason that the game doesn't have a good single player or LAN AI.

Thus, as you, reader, will understand, many of recent have attempted to make certain improvements to his famous modification, with some success. Some have even tried to do his same work from scratch, building off the original AImain.xs. However, as Felix did his work over several years, it would be foolishness to utterly disdain what he worked so hard on. We could at least use it as a rubric, especially since he has not updated it in the past five years.

So there, my friends, my fellow companions, with the goodwill of all those who play the Age of Empires series, I, being inspired, decided to take Felix's work further.

Here is where I have gotten so far, N3O FP AI for TAD 1.03:


The Coding: Fact or Fiction?

The greatest misconception of all AOE3 coding is that coding is complicated. In fact, most of coding of Age of Empires III is in ordinary English. However, there are times when you need special programs to convert files to a legible script, in order that you may modify them, and in turn, convert them to their original form. This latter way of coding is often what is called "proper" coding, or other coding which uses its own special "language," usually a set of four words, used in randomized order, of which we shall not get into here.

First of all, your first time editing a file in notepad is scary. I knew the first time I began coding two and a half years ago, and I nearly was shaking, hoping that I wouldn't make something unplayable. Thankfully, however, whenever we code, we make a backup. Yes, before we change anything in any file, we first copy and paste it into a folder we create, and create another (second) backup after that, so that when we modify the file, and copy and paste it back into Program Files, and something goes wrong, such as the game won't load, we can always use the original or our latest functioning version by copying and pasting it into Program Files, thus making the game once again playable.

If you didn't get what I said there, I meant this: make more than one backup. Make a folder on your desktop, Call it "AI Backup". Inside that folder make another folder. Call it "Backup Again". Now copy and save the original file you want to modify, in case anything goes wrong.


In Business

When we are in business we do work, correct? When we have tasks at school, we do them, correct? Well, hopefully we do. Similarly, when we do AOE3 coding, we do it correctly.

Important: Even one error in the AI coding can make the whole coding not function and make the game unplayable against the computer. If you make an error and try to play a skirmish game, you will load the map, but you will have this error:

'AIstandard.xs failed to Load' (forgive me, I forget if it could be AIMain.xs, but anyways, you understand the point)

This means that the AI has an error in its coding.


What is an error in the AI coding?

Answer: Simple enough, something that doesn't work. Errors are generally telling the Computer to upgrade techs that aren't in the Techtree, to build units that don't exist, or if there is a mere typo in a name of something, the computer won't recognize the intended name. Also, there are errors that do not cause the coding to fail. Among these are telling the computer to include cards when you don't allow them to "buy" the prerequisite card, i.e, if you want France to use Cavalry Combat in their deck, you have to "pre-research" or "pre-buy" the proper cards for them (by their name in the techtree, and not in the game itself) in the AI coding. Here, it becomes evident, then that a knowledge of the Proto and Techtree files is quite important while doing AI coding; in fact, to properly understand anything I will tell later, this is imperative. I will explain this later.


The Proto and Techtree Files

The Proto and Techtree files are found in the same Age of Empires III folder, under the sub-folder "data". They show up as openable via Internet Explorer, but are also openable with Notepad.

You have six files: they are called Proto, Techtree, Protox, Techtreex, Protoy, Techtreey. There are also a copy of these files in the same folder in .xml.xmb format, but in order for these to be opened, you would have to use a conversion program.

The Proto defines the statistics of units, buildings, ships: their hitpoints, attack, what they train, which techs are available at which building, etc. The Techtree defines what techs do, and which team gets which tech. It also determines prerequisite techs to other techs, and the like.


Question: What is the difference between Proto, Protox, and Protoy, then? And the Techtree, Techtreex and Techtreey?

Answer: "x" means first expansion pack, and "y" means the second expansion pack.

If you want to modify unit and techs, and or add them into Vanilla (Original Age of Empires III without expansion packs), then you must open Proto and Techtree, and modify those. Similarly, Protox and Techtreex are for Warchiefs units, buildings and techs, and Protoy and Techtreey are for The Asian Dynasties.

All units and techs in the Proto and Techtree files are NOT Alphabetically listed, but are rather listed in the order that they were created in. Thus is can be problamatic to find your way in the coding, and find exactly what you are looking for, if you do not know its exact name.


But how does this connect with coding AI?

Answer: When we want to tell the computer to research a tech, we need to know what that tech is called in the Techtree, or else, the AI will not research it. When we want the AI to train a specific unit, or not train a specific unit, we need to have the proper "Proto" name. Usually, they are about the same as the unit ingame, excluding spaces in the unit name. For instance, Cassadors are simply "Cacadore" in the Proto. Musketeers are simply "Musketeer", Pikemen "Pikeman", Hussars "Hussar", Cuirassiers "Cuirassier", etc., while you also have the Iroquois Forest Prowler called "xpMusketWarrior" in the Proto list and even when you want to modify units in the scenario editor. Kanya Horsemen are simply called "xpHorseman", Tashunke Prowlers are called "xpCoupRider", Cetan Bows are called "xpWarBow", Wakina Rifles "xpWarRifle", etc.

Units, as you can see above, which belong specifically to the Warchiefs expansion, generally have an "xp" before them. The same goes for Homecity Techs in the Techtree; They are called HCXPShipTravois1, for instance. For the Asian Dynasties, most things begin with "yp", then the unit name. A peculiar instance is the Japanese Samurai, which is simply called "ypKensei" in the editor. Also, Indian Gurkha are called "ypNatMercGurkha", and the Mansabdar Gurkha is called "ypNatMercGurkhaJemadar", as Gurkha were originally meant to be native warriors in the game, and Urumi Swordsmen the Indian "Skirmisher" unit. Flail Elephants are likewise called "ypMercFlailiphant", and for the Mansabdar, "ypMercFlailiphantMansabdar". Indian Brahmin are called "ypMonkIndian1" and "ypMonkIndian2". These are but few examples of how things are in the proto/techtree files.


We have not yet begun with our modification of the game AI. However, this above information is necessary to know before you really begin. If you have worked with the Age of Empires III scenario editor before, you will have a distinct advantage and it will be easier for you to actually start modifying the game. This is because, when you place units by triggers, you have a long list of names to choose from of different units - and these are the very same names in the Proto. Also, when you Upgrade Techs via triggers in the editor, you choose by what they are called in the Techtree. Thus as you now see, proper English in scenario design is not very far from modifying and "coding" this game.


But now I must come and write the rest of this another time. Meanwhile, the next week I will be out of the country, so writing will be postponed until after that time.

Link to next Part of the Guide:,38885,,10

Best of heartwarming regards,


[This message has been edited by murdilator (edited 04-27-2013 @ 06:13 AM).]

posted 04-04-13 09:03 PM EDT (US)     1 / 5       
I have not read all of it yet, but I'm really glad that someone is creating an AI tutorial, that's something that the database has always lacked. Thanks!
Location: Ohio, USA
Hey, me too! *highfive*

[This message has been edited by musketeer925 (edited 04-04-2013 @ 09:05 PM).]

posted 04-27-13 04:29 AM EDT (US)     2 / 5       
The Second part of this guide will be up and coming shortly.

Stay tuned!
posted 05-02-13 06:37 AM EDT (US)     3 / 5       
I write what has not been written before for AOE3, a Comprehensive Beginners Guide to AI scripting.
Certainly, I have never seen a guide to AoE3 scripting before. However, AoE3 uses the same AI system as Age of Mythology, and a member of Ensemble Studios has published tutorials on AoM scripting which may be of some relevance. You can find it here.
You can modify the AI by opening AImain.xs with the simple program Notepad, which is included on every computer that has Windows installed on it.
Certainly, Notepad can edit the .xs files, but it is more convenient to have a text editor that can highlight the syntax. I suggest that you download something like Notepad++ or Sublime Text, and set the language/syntax to C:
- In Notepad++, go to Language -> C -> C
- In Sublime Text, go to View -> Syntax -> C
This will highlight keywords, comments, etc. in different colors, making the code much more readable than it is in Notepad. Once you get used to the colors, you will be able to easily spot simple typos (like forgetting a "}"), by the changes in color that they cause.

[This message has been edited by EmperorJustinian (edited 05-02-2013 @ 07:50 PM).]

posted 05-03-13 08:53 AM EDT (US)     4 / 5       
Interesting what you say, EmperorJustinian. I myself will have to take a look at the Age of Mythology file.

Thank you for your suggestion about the Notepad++. I thought about introducing that in part 3 of the guide, but now since you mention it, I think adding its link would be appropriate to this first part of the guide, at the top, as to make it easier for people to go and modify.

C++ language is a good thing too; I had simply used the Notepad++ a few months and never bothered to set any features on.

In this next upcoming part I will show how to make the AI build walls/gates, plus explain how to make them train specific units. Still, I must admit, I do not understand everything, and in many ways am an amateur in AI coding. However, I want to help with what I know, and hopefully others can build from there.

At this moment I've gotten them two build two layers of wall - one defensive and the other aggressive, and also made it longer for them to change their gatherers from their resources (hopefully) so that they do not just run around with their villagers all the time and waste villager seconds by doing that.

Note: I also found that the AI gathers phenominally faster if their villagers are given +10-25% more speed. I played against them one game where they had 3000+ score, and one even got 5000 score before I managed to beat them.

However, I still encounter bugs such as late-game, once you have raided them, their villagers will just stand around their town center. It is almost as if the AI gets "exhausted", or loses its brain (this could happen 1 1/2 hours into the game). However, it still trains troops in this reflex, so I wonder if it has to do with the defensive reflex being somehow greater than gathering from mills/plantations. Anyways, I may have a fix for this issue upcoming.

Thanks for your comments!


posted 06-01-13 01:25 AM EDT (US)     5 / 5       
I didn't read it, but I don't need to read it because I'm not doing AI scripting right now, and I trust that it is the only AI scripting tutorial for AoE3 in existance so I propose that this tutorial be added to the modding database.
You must be logged in to post messages.
Please login or register

Hop to:    

Age of Empires III Heaven | HeavenGames