Age of Mythology
Scripting Guide
Outline











Game overview
Adding your agent to the game
Renaming your agent
AI vs. AI: we’re almost there
AI vs. AI setup
Setting up the AI debugger
Scripting overview
AI library reference
Sample code from default AI
Explanation of sample code
Link to AoM scripting website
Game overview


Age of Mythology is a real-time-strategy game where players
start by choosing one of three civilizations: the Greek, the
Egyptian, or the Norse. Players choose the gods they wish to
worship, and each god provides different strengths for the
player's civilization. Players then wage war against other armies
and must lead their civilization to victory by managing their
civilization’s military and economy.
In addition, the game allows you to create AI scripts that
control the computer players which you play against in the
game. This guide shows how to set up Age of Mythology for AI
scripting, how to play AI vs. AI games, and provides a brief
description of AoM scripting.
Adding your agent to the game

The code for your agent is saved as a .xs file (e.g. admiral.xs).

Your agent appears in the player-select drop down menu when
you add the .xml file.

To add your agent to the game simply:



Add your xs file to AoM's AI folder.
Add your xml file to AoM's AI folder.
If you want to rename your agent, you’ll need to edit the xml
file as shown in the next slide.
Renaming your agent

To rename your agent you need to edit your xml file, it should look something like this:
<AI>
</AI>

<script>the name of your xs file without the file extension</script>
<name> the name of your agent</name>
<playerNames>
<name>the name of your agent</name>
</playerNames>
For example, if our agent is admiral.xs, then we need an xml file to go with it. We can name
it admiral.xml and it should look like this:
<AI>
</AI>
<script>admiral</script>
<name>Admiral AI</name>
<playerNames>
<name>Admiral AI</name>
</playerNames>
AI vs. AI: we’re almost there



After adding your agent to the AI folder, its name should appear
in the list of computer player opponents, and you can play
against your agent.
However, if you want to play AI vs. AI random map games then
we have more work to do because AoM doesn’t have a graphical
interface for assigning an AI script to player 1.
The next slide shows how to set up AI vs. AI matches by using
a text editor such as WordPad to edit a .prf file, which tells the
game that player 1 will be controlled by an AI script.
AI vs. AI setup

1.
2.
3.
4.
5.
6.
7.
To run AI vs. AI battles you'll need to take these steps:
Create a new profile in the options screen, named AIvsAI (or anything else)
Using that profile, start a 1v1 random map game (you vs. AI)
Quit a few seconds in and exit AoM
Open AIvsAI.prf in the users folder and scroll down to playerid 0 data (shown below)
Set aiscript to your xml file
Set type to 1
Save AIvsAI.prf. Your playerdata section for playerid 0 would look like this:
<singleplayerrandommapdata>
<playerdata>
<playerid>0</playerid>
<aiscript>name of your xml file without the file extension</aiscript>
<type>1</type>
<civilization>9</civilization>
</playerdata>


When you want to set up AI vs. AI battles select the AIvsAI profile.
When you want to change player 1’s agent, update the aiscript value in AIvsAI.prf.
Setting up the AI debugger


The following changes provide access to AI debugging info. Without this, if your
script has an error the compiler will tell you, but the compiler will not tell you on
what line it detected the error. To find the error type “Alt-Shift-d”. If your agent
compiled successfully and you want to see what goes on behind the scenes,
type “Alt-q”.
Create a user.cfg file in your AoM startup directory, and include these three lines
in it:
aiDebug
showAIEchoes
developer

Create a user.con file in the AoM startup directory, and add this line:
map ("alt-shift-d", "root","gadgetToggle(\"XSDebugger\")")
Scripting overview


Age of Mythology’s AI uses a new language called XS (expert
system), which combines the simplicity of a rule-based system
with the power of the C++ language. In XS, most of the time,
you are sending commands to an AI library and interacting with
this library.
As far as syntax is concerned, XS allows you to declare
variables, write methods, and use condition statements. In
almost every case with AoM scripting you will be using the int,
string, and float data types; methods are declared and used in
the same way that they are in C++; and there are two types of
condition statements in the XS language, the if-else approach
and the switch approach.
AI library reference


The AI library reference is a list of AoM variables and function calls, located in
AoM’s docs folder under the name “aom ai script help file.rtf”, you should
become familiar with this library.
The AI library reference provides descriptions in the following manner:
int aiPlanCreate( string planName, int typeName )
Creates a plan of the given name and type.


The first thing this description tells us is that the function aiPlanCreate returns
an integer. The second thing we know about this function call is that we need to
give it two parameters, a string and an integer. The integer it returns is the
plan’s ID, which is always non-negative; the string parameter is an arbitrary
name we give to the plan; and the integer parameter is an AoM constant that
identifies the plan type, e.g. cPlanAttack or cPlanExplore.
The next slide has sample code from the game’s default AI. Line 18 makes a call
to aiPlanCreate.
Sample code from default AI
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
//==============================================================================
// RULE: startLandScouting
//
// grabs the first scout in the scout list and starts scouting with it.
// this rule runs just once, creates a land scouting plan, and disables itself.
//==============================================================================
rule startLandScouting
// marks the start of the rule
minInterval 1
// ensures that this rule will not run more frequently than once a second
active
// indicates that this rule starts out active, so it will automatically run very early in the game
{
//If no scout, go away.
if (gLandScout == -1)
// tests that gLandScout has a valid value, the value was assigned elsewhere
{
xsDisableSelf();
// turns this rule off, so that we don’t create a new land scouting rule several times a second
return;
// exits the startLandScouting rule
}
//Land based Scouting.
gLandExplorePlanID=aiPlanCreate("Explore_Land", cPlanExplore);
if (gLandExplorePlanID >= 0)
{
aiPlanAddUnitType(gLandExplorePlanID, gLandScout, 1, 1, 1);
aiPlanSetActive(gLandExplorePlanID);
17.
18.
19.
20.
21.
22.
// creates an explore plan, gives it a name, assigns plan ID to a variable
// makes sure the plan creation succeeded
// adds a gLandScout unit to the plan, if there is one alive
// activates the plan, from here on one gLandScout will explore
23.
24.
25.
26.
}
27.
28.
29.
30.
}
//Don't loop as egyptian.
if (cMyCulture == cCultureEgyptian)
aiPlanSetVariableBool(gLandExplorePlanID, cExplorePlanDoLoops, 0, false); // do not do loops, just random searches
//Go away now.
xsDisableSelf();
// turns this rule off
Explanation of sample code

Line 18:
gLandExplorePlanID=aiPlanCreate("Explore_Land", cPlanExplore);
Creates an explore plan. An explore plan merely assigns living units to exploration,
which is different from creating units for exploration. Plans know how to perform specific
tasks such as exploring, gathering, attacking, defending, fishing, and many more. Each
plan created generates a plan ID number. Line 18 assigns the plan’s ID number to the
variable gLandExplorePlanID. You will need the plan ID later on when you set the plan’s
behavior in lines 21 and 22.

Line 21:
aiPlanAddUnitType(gLandExplorePlanID, gLandScout, 1, 1, 1);
Assigns a unit of type gLandScout to the explore plan. The unit assigned to the plan is
the unit that will explore. The arguments 1, 1, 1 represent the need, want, and max
values for the assigned unit.

Line 22:
aiPlanSetActive(gLandExplorePlanID);
Activates the explore plan. At this point a unit of type gLandScout is exploring the map.
Link to AoM scripting website

A tutorial for AI scripting, written by one of the game’s
programmers is available. Download “AoM tutorial (revision 2)”
from the following website:
http://aom.heavengames.com/downloads/lister.php?category=ai

Another tutorial:
http://aom.heavengames.com/scendesign/advanced/aiscript