PAGE 7
Computer Player Strategy Builder Guide
AI Expert Documentation
Age of Empires II: The Age of Kings
Important: Age of Empires II allows you to create your own custom campaigns, scenarios, and computer player scripts. You may share these custom campaigns, scenarios, and computer player scripts for the purposes of gameplay but you may not sell or make other commercial uses of the custom campaigns, scenarios, and computer player scripts. Microsoft reserves all other rights to the editors and files.
COPYRIGHT NOTICE
This information contained in this publication/document (the “Information”) may be redistributed only as permitted by the text below and provided that such Information and this copyright notice remain intact. No part of the Information may in any form or by any electronic, mechanical, photocopied, recorded or any other means be reproduced, stored in a retrieval system, broadcast or transmitted without the prior written permission of the publisher of the Information, Ensemble Studios Corporation. Neither the Information nor any portion thereof may be stored in a computer or other electronic storage device except for personal and non-commercial use.
Users of the Information must seek permission from Ensemble Studios Corporation for all uses that are not allowed by fair use and other provisions of the U. S. Copyright Act, as amended from time to time (the “Act”). This Information may not, under any circumstances, be resold or redistributed for compensation of any kind without the prior written permission of Ensemble Studios Corporation, 10440 N. Central Expressway, Suite 1600, Dallas, TX 75231.
The Information may only be used as a source of data and may only be used for non-commercial purposes. Any copy of this Information or portion thereof must include this copyright notice.
Any published data contained in the Information, including URL and other Internet Web Site references, is subject to change from time to time without notice.
The Information does not carry a warranty of any kind, whether express or implied. Although every effort is made to provide the most accurate and up-to-date information possible, Ensemble Studios Corporation acknowledges that this Information could include certain errors, including typographical errors and technical inaccuracies. Additions and changes will be made to the Information on an on-going basis; thus the Information contained herein is subject to change without prior notice. Complying with the Act and all other applicable federal or state copyright laws is the sole responsibility of the user. The user hereby is deemed to assume all such copyright law compliance responsibility by his or her use of the Information.
Ensemble Studios Corporation may have U.S. federal and/or state patents, patent applications, trademarks, service marks, trade names, copyrights or other intellectual property rights covering subject matter in the Information. Except as expressly provided in any written license agreement from Ensemble Studios Corporation, the furnishing of the Information does not give the user any license to such patents, patent applications, trademarks, service marks, trade names, copyrights or other intellectual property rights, which are expressly retained by Ensemble Studios Corporation.
Introduction 8
Rules 8
Facts 10
Actions 10
Defrule Command 12
Deconst Command 12
Load Command 12
Load Random Command 13
Conditional Loading 14
Technical Considerations 16
System defined symbols 16
Examples 19
Conditional Loading and User Defined Constants 19
System Defined Constants 20
Facts 20
Fact List 20
Constant Facts 24
Event Detection Facts 24
Game Facts 24
Commodity Trade Facts 24
Tribute Detection Facts 24
Escrow Facts 24
Computer Player Object Count Facts 25
Computer Player Resource Facts 25
Regicide Facts 25
Computer Player Availability Facts 25
Computer Player Miscellaneous Facts 26
Opponent Facts 26
Cheating Facts 26
Fact Details 27
Actions 41
Action List 41
Input / Output Actions 43
Rule Control Actions 43
Event Actions 43
Commodity Trade Actions 43
Tribute Actions 43
Escrow Actions 43
Regicide Actions 44
Cheating Actions 44
Other Actions 44
Action Details 44
Parameters 52
Parameter List 52
Parameter Details 53
Wildcard Parameters 65
Difficulty Parameters 69
AI Player Guidelines for Age of Kings 70
AoK Level of Difficulty - Current Operation 72
Variables 72
Rule Variables 72
Timers 73
Timer Facts: 74
Timer Actions: 74
Examples: 74
Error Messages 75
Error reporting format 75
Description of error codes 76
List of errors 76
Hint for efficient debugging of scripts 77
Data Types 78
String 78
Symbol 78
Appendix A - Internal SN parameter documentation 79
Appendix B - Discontinued SN parameters 90
Appendix C - SN Parameter Defaults 91
Facts, Actions, and Parameters (combined list) 95
Unfiled Examples 99
Controlling Villager Distribution 99
How to trade 100
How to resign gracefully 101
Age of Empires II uses an all-new Artificial Intelligence (AI) Expert System to act as the intelligence behind the computer players. This expert system uses a series of Rules that are tested to cause various actions to take place. In the following sections, you will learn how to make new rules for the AI to follow, how to check game facts to trigger those rules, and how to command the AI to take action based on your instructions.
AI Files are text files that have their extension changed to '.per' (for example, 'Henry Tudor.per'). These files contain the script commands that are used to create a new customized computer player. Use a text editor (one that displays line numbers is very helpful) to create your AI scripts, and copy them into the directory where you installed Age of Empires II, in the AI folder.
An empty text file with an .AI extension (for example, 'Marko.ai') should be created to make an entry appear in the list of computer players and in the scenario editor. The game will try to find a file with a matching .per extension that will be started when you pick that player. In your game's AI directory, you would then have 2 files:
C:\Program Files\Microsoft Games\Age of Empires II\AI\MyAI.ai (This is an empty file that makes an entry in the game's list)
C:\Program Files\Microsoft Games\Age of Empires II\AI\MyAI.per (This file contains your custom AI script of rules and facts)
Rules are the basis for the Expert System. There is a list of things we know about the game world, the other players, and so on. These are called facts. We check the facts with rules until a set of conditions exists that we need the computer player to act upon. Actions are what we call those commands that cause things to happen in the game. Examples might be training a unit, researching a technology, or sending a chat message.
Rules are defined in the script with the defrule instruction. If the conditions for the rule are met (True), the instructions in that rule are followed. If the conditions for the rule are not met (False), the rule is passed by.
A defrule example:
(defrule
(cheats-enabled)
=>
(some action takes place)
)
Note that the parentheses around the rule are required – though the white-space formatting (spaces, tabs, etc.) is not important.
Rules continue to be evaluated until they are disabled. This is done with the disable-self command
(true)
(disable-self)
Going through the entire list of rules checking each one is what we call a rules pass. This system is very efficient, the rules may be checked as often as several times a second.
You will see comments throughout the AI Expert System script files. These comments start with a semicolon (;). For example:
;This line is a comment
(food-amount greater-than 75)
(train villager) ;comments at end of line too!
.
Any text that follows a semicolon on that line is a comment and is ignored by the AI script.
Once you define the rules, you can then use the all of the available facts and actions in combinations to do any action possible in the game.
Facts are those things that are tested in the rules. Player information such as how much gold you have, opponent information such as score, or game information such as time or victory conditions are some examples.
Facts are used to enable rules. For example, this will train villagers whenever we have 50 food:
(food-amount greater-than 50)
(train villager)
See: Rules
You will see <rel-op> associated with a lot of facts, this is a relative operator and allows you to test the relationship of the fact to another value, an example might be if you wanted the rule to be enabled when a certain amount of wood had been collected:
( wood-amount greater-than 1000)
( chat-to-all “I have 1000 wood!”)
For more detailed information about parameters, see the "Parameters" section later in this document.
Some facts can be tested just by checking them directly. If you want to see if cheats are enabled in the game, you can make a rule like this:
(chat-to-all ”Let the cheating begin!” )
Other facts are more complex and require you to supply additional data that is used by the fact – information like the civilization <civ> or the map size <map-size> is required. Any fact that lists parameters <example> requires those parameters in order to work correctly.
Actions are those things you want the AI to do when it executes your rules. Actions can cause the AI player to build a building, train a unit, or send a chat message to a player, for example. Rules enable your computer player to take any action a human player could.
This command creates a new rule.
Example:
(game-time greater-than 30)
(resign)
This command creates a user-defined constant. For more information on defconst, see the "Conditional Loading and User-Defined Constants section later in this document.
Syntax:
(defconst <constant-name> <value>)
<constant-name> is a user selected name. Use of the same format that the rest of the system
uses is recommended but not required (for example, words-separated-with-dashes).
<value> is a valid integer value that will fit in a C++ type short. (For non-programmers, this means that the value can not be less than -32768 or greater than 32767.)
The following example defines a decided number of villagers in the dark age:
(defconst num-dark-age-villagers 22)
The following rule then uses it:
(civilian-population < num-dark-age-villagers)
...
krystynalubicz