Age of Empires 2: Startup Tutorial to AI Scripting - Part 2 of 2

Continued from Part 1

Advanced Script
Lets take the previous script and beef it up to demonstrate a couple more concepts. This time around, the script will build a small army of men-at-arms and attack an opponent.

Once again, due to formatting and length reasons I've uploaded the script file.  Just download it and open it with your text editor.

Now we're scripting!

Advanced but Important
If you look through the script you'll notice I added a wild-card parameter, some constants, some not-so-obvious facts and actions, a couple important strategic numbers and a goal.

Wild-card Parameter
If you look at the rule that trains the military unit, you'll notice that instead of "militiaman" or "man-at-arms", it trains a "militiaman-line". This wild-card parameter trains any of the unit-types that can be upgraded from a militiaman. This kind of parameter helps save rules by allowing you to not have to add redundant rules for training militiamen, men-at-arms, long-swordsmen, etc.

Constants
At the beginning of the script, I added a few constants to make my script easier to read and edit. A constant allows me to substitute a value with a name.

(defconst [name] [value] )

This means that after this constant declaration, you can put the name instead of the value in rules. Constants are best used if you plan on using the same value in many rules, but may need to change the value when adjusting your code in the future. Instead of changing all the values in each rule, you can just change the value in the constant declaration.

'True' and 'Disable-self'
The fact 'true' is useful for setting up strategic-numbers and goals to your preferred default values. If 'true' is the only fact, then the rule is always run.

The action 'disable-self' allows you to run a rule one-time and then never again. It is useful for turning off a rule with 'true' as a fact, like the advanced example script shows for setting the initial value of goal 1.

Builder Distribution
Just note that 'sn-percent-civilian-builders' and its sister number, 'sn-cap-civilian-builders' should be set to 100 if you want your 'build' actions to happen immediately. If you ran the first script, you may have noticed that villagers did not build a building the moment the facts were true. This is because the 'build' action actually puts the building action in a queue and only once a villager is free does the villager build.

The strategic number 'sn-initial-exploration-required is also usually set to '0' if you want your villagers to begin building as soon as the map starts.

Stop gathering and build me a house, dammit!

Goals
The most important concept I added to the new script was a goal. These are the user controlled variables of Age of Empires AI scripting. In the above example I used goal 1 to indicate whether the script should build an army (value of 1) or not (value of 0). Just to note, the line "(goal 1 0)" is read as "goal 1 is set to 0". Sadly, you can't make more broad comparisons than this using '>' or '<'.

While I didn't use a constant to replace '1' in the above example, it is common practice to do so. For example, I could have used the term 'build_army' to indicate goal 1 with the following:

(defconst build_army 1)


(defrule
(true)
=>
(set-goal build_army 0)
(disable-self)
)

You can have 70 goals (1 through 70) and the value of goals can range from -32000 to 32000.

Processing Your Script
Okay, hopefully you now have an idea of what an AI script looks like. It's time to mention a few details of how exactly the game processes your script and some of the implications.

Rule OrderThe game frequently runs a pass on your script from top to bottom. This means that your first rule will always be read before your second rule. Which in turn means that the following two scripts will yield different results:

Script 1
(defrule
(can-train archer-line)
=>
(train archer-line)
)


(defrule
(can-train skirmisher-line)
=>
(train skirmisher-line)
)


Script 2
(defrule
(can-train skirmisher-line)
=>
(train skirmisher-line)
)


(defrule
(can-train archer-line)
=>
(train archer-line)
)

The first script will try to train an archer in an archery range before a skirmisher and the second will do the opposite.

The 'can-build' Rule
A script can only attempt one 'build x' action through a single pass of the script.  This means that using the 'build x' rule when the AI doesn't have resources or space to build 'x' will cause all the following 'build x' rules to not run.  To prevent this, make sure you always use the 'can-build x' fact in rules using the 'build x' action.  You don't need to use 'can-train x' and 'can-research x', but they are useful if you have actions other than 'train x' or 'research x' in the rule.

Wrap Up
I hope that you now have the knowledge to produce an AI script or at least take an existing script and play around with it. Remember, this guide was meant to get you as far as making a functioning AI. There are still many topics that are left untouched here that need to be learned before you can produce a full-scale AI. At the end of this article, I've left some notes on important further reading. Still, your best resources are the AOKH forums and the AIScripters forums. Thank you for reading and best of luck with your AoE projects.

Further Reading
Town Size Attack (TSA) - TOAO_DaVe's Guide
Walls - see "enable-wall-placement" in CPSB
Load Statements - see "Load Command" and "Conditional Statements" in CPSB
Escrow - Scripter64's Guide

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

Minecraft: Castle Fort

While I was initially shooting for a castle,  space limitations constrained me to more of a fort.  I did my best to  keep the natural valley walls and build within it, opposed to completely levelling everything.  The castle still needs landscaping in the courtyard and various detailing.

North daytime shot.



South night shot.

In both the panoramic shots, you'll notice the lack of approach to the gate.  I plan on adding a moat on one side, a ramp on the other and gates to both.

Unlandscaped courtyard from wall.

In the courtyard, I'm planning on putting in a small pond, flowers, trees, pathways and a portal.

Partially built, walls up, but no towers.

Quick draft.

I did a really quick draft because drafting the temple helped me immensely.  Sadly, I tried to skip out on a front or side angle and wound up screwing up my draft a fair bit.  In the draft, the walls were only supposed to be three tiles thick with crenellations sticking out an extra tile on either side.  In the final castle, I accidently built the walls five tiles thick and an extra tile for the crenellations.  Being lazy didn't pay off this time around.

Minecraft: Temple Drafts

Here are the two drafts I put together before putting up the temple.  I'm fairly confident there is a mistake in one of them, but I can't remember where exactly.  Basically, something looked okay on paper, but wasn't possible in 3D.

You may notice a few numbers in the corners.  Those numbers were from me trying to figure out how many stone pieces I needed for a few of the sections.

For projects that require lots of numerical caculations (column spacing, layers, etc.) drafting the project first is much better than just winging it.  Not only do I finish the project quicker, the building looks better in the end because I don't compromise my design when something doesn't quite fit.