Age of Empires 2: Startup Tutorial for AI Scripting - Part 1 of 2

Lately I've noticed a lot of hits to this blog coming from google searches for terms like "age of empires", "ai", "scripts", "scripting", and "guide".. Although I know there are some guides out there (because I read them), they seem to have been lost in the intertubes. I hope to fill this void by providing a short guide that gives interested scripters enough knowledge to write their own crude code..

You too can create a siege happy AI!

As mentioned, the goal of this guide is to introduce you to the basics of scripting AI for Age of Kings and allow you to start playing with your own code as soon as possible. By the end of this tutorial you should have the knowledge and resources to write and run an AI script.

Tools
Before you begin scripting, it is important to have the right tools and references. If you skip getting familiar with any of these, you will make scripting much harder for yourself.

An AIScripters Account
Almost all AoE2 scripters go here to discuss problems, share ideas and post resources. This forum contains a wealth of knowledge. Sadly, you need an account to access them, and each account is personally authorized, so it might take some time before you can access the site. If you sign up for an account and don't get a response within a week, contact Leif Ericson (from Age of Kings Heaven) or me.

An Age of Kings Heaven Account
While AOKH doesn't have the depth of discussion that AIScripters has, the AI & RM Scripting forum has many active members that can help answer simple questions. You can also find the continuous AI Scripting Ladder here.

CPSB
You can find this document in the "DOCS" folder on your AoE2 Expansion CD. You can also find a .pdf version here. This document contains a thorough introduction to scripting concepts, and more importantly it contains lists and descriptions of parameters, facts, strategic numbers and a bunch of other fun things.

New RMS Guide
While this guide is intended for Random Map Scripting, it contains unit reference numbers. These numbers are important for more intricate rule writing.

ScriptEd
This is the best text editor for writing AoE2 scripts. Since you need access to AIScripters to get it, you can use Notepad or AoK AI Editor in the mean time. Be warned that AoK AI Editor was not upgraded to work with Age of Conquerers code changes, so it will show errors that are not actually errors.

VegMod and/or another computer.
Vegmod allows you to play in windowed mode. This may seem trivial at first, but being able to quickly switch back and forth from testing to coding saves a lot of time. The same idea applies to having another computer testing your script while you code on the other.

Cheat Engine
Cheat Engine allows you to fast forward the game.  This allows you to test your scripts at a faster rate.  While I've never used it myself, other scripters recommend it. 

Introduction Script
Before I start blabbing on about how the game processes the script, lets just take a look at a simple script that trains villagers, advances to the Feudal Age and then researches 'town watch'.

For formatting and length reason, I didn't post the script here, so please download the uploaded copy and open with a text editor (like ScriptEd).

Now we have a basic script to work with. You may not understand all the rules in there yet, but that's no big deal. Lets just get this script running on a random map.

Saving & Running
1) Copy and paste the above script into your text editor. Save the file with the name of your choice and with a '.per' extension under the AI folder (default: Program Files/Microsoft Games/Age of Empires II/AI).

2) Open a new document in your text editor and save a document in the same place with the same name as above except with an '.ai' extension. This file lets the game know that "Hey, there's a '.per' file with the same name as me that contains the beginning of an AI script".

Note the folder contains both a '.per' and '.ai' file with the same prefix.

3) Run Age of Empires 2, go to 'Single Player' and then 'Standard Game'. On the left side, your profile name should have a drop menu that lets you select your AI. Select your AI.  Make sure you select the AI after adjusting your game settings because sometimes this causes the AI selected to revert to the default once you begin the match.



4) Click 'Start Game'.

Note: If you make any changes to your script and want to test them out, you don't need to go the main menu and start a new game, you can just restart the match from the in match menu. This is especially useful for fixing script errors.

Note II: In the in-game options menu, set your game speed to 'fast' for more efficient testing.

The Basics
Okay, now you've seen a script and maybe took the time to run one. That's great at all, but you want to learn how to write some code! Lets take a closer look at the basic building blocks.

Rules
Rules are how you tell the computer when to change what. Here's the setup of a rule.

(defrule [this just says "Hey, this is the start of a rule!"]
(fact 1)
(fact 2)
...
(fact x)
=> [this symbol indicates the transition from facts to actions]
(action 1)
(action 2)
...
(action x)
)

If all of the facts before the arrow are true, then all of the actions after the arrow will be initiated. Compare this frame to some of the rules in the example script above to make sure your comfortable with the idea of a rule. To look at all the available facts and actions that you can plug in to this frame, open up the CPSB and look at the 'Fact List' and 'Action List'. It is really that simple.

There are some limitations regarding rules. A rule can have a maximum combination of 16 facts and actions (this includes 'and' and 'or' which you'll learn later). A running script can have a maximum of 999 rules.

Strategic Numbers
You may have noticed that the script does not provide any details about where buildings are built or where units go. Yet if you ran it, you'll know that the villagers happily went on their way harvesting trees and butchering sheep. You can not control units directly via scripting, but you can mold and shape their behavior with the use of strategic numbers. Once again, you can find the entire list of strategic numbers in the CPSB.

The example script only used one set of strategic numbers to ensure the villagers split up their wood and food gathering duties. The example shows strategic numbers being compared as a fact and it shows them being set as an action. When the AI is trying to decide where to task a unit, it uses these strategic numbers to aid its decision.

Comments
I named each rule in the example script. I did this through the use of comments. To indicate a comment, just put in a semicolon (";"). The game will ignore anything on the line after a semicolon. The example script contains sparse commentary, but It is highly recommended that you comment your work thoroughly to make it more legible for yourself and others.

Onto Part 2