Intro to Commands

Intro To Commands

To see a list of all available commands, click here.

Commands make up 99% of AI scripting, so it's important to know how they work.

Commands are always contained within a rule, and they must be enclosed in parentheses. There are two types of commands: facts and actions. Facts are conditions that must be true for a rule to execute, for example can-afford-building. Actions tell the AI player to do something if all of the Facts in the rule are true, for example buy-commodity. Facts are placed at the beginning of the rule, and Actions are placed at the end of the rule, separated by a '=>' in the middle.

Note: some Userpatch commands can be used as either a Fact or an Action. If used as a Fact, the AI will check if the command can be executed. If not, the rule will not execute its Actions. If the command can be executed, it will execute as an Action even though it's in the Facts section. If the command is used as an Action, it performs like any other action.

Parameters

Commands can have from 0 to 4 parameters. Click here for a full list of all available parameters. Parameters allow you to customize how the command is executed. If a command has parameters, you must set each parameter to a valid setting or you will get an error. Here's an example of a command with parameters as you might see it in an AI script:

(players-building-type-count any-enemy castle > 0)

The command is players-building-type-count, and it has four parameters which have been set to any-enemy, castle, > , and 0. This command is a Fact that will return true if any enemy player has more than zero castles.

Command Syntax

How else could you customize this command? First, you need to know what parameters the command uses. This reference site includes information on all available commands (see the link at the top of the article). Within the articles on each command, you will see the command's syntax (it's required structure) which looks like this:

(players-building-type-count inPlayerAnyPlayer inConstBuildingId compareOp inOpValue)

We already recognize the first part of the command, which is the command's name: players-building-type-count. Then, the command's parameters follow. In this case, the command has four parameters. The bolded link for each parameter is the parameter's name, so the players-building-type-count command uses the AnyPlayer, BuildingId, compareOp, and Value parameters. To get more information on a parameter and how it can be used, click the link. Each parameter (except for operators, such as compareOp) also has two prefixes that tell you how the parameter is used in this particular command. The first prefix tells you the parameter's direction, and the second prefix tells you the parameter's type. Below are the possible directions and parameter types you will see:

Direction - Defines how the parameter's information is used:

in - An input. The parameter provides information for the command to use.
out - An output. Most of the time an output parameter is a goal that stores information that the command found.
io - Both an input and an output. The command uses the information in this parameter, and it stores information in this parameter when the command is finished. Most of the time this is a goal.

In our example, each of the parameters were input parameters, except compareOp. Our example provided 'any-enemy' as an input for the AnyPlayer parameter, 'castle' as an input for the BuildingId, and '0' as an input for the Value.

Type - The type of information the parameter can be:

Const - the parameter must be a constant.
Goal - the parameter must be a goal.
Sn - the parameter must be a strategic number.
Op - the parameter must match the preceeding operator type (see the operators section below). If the operator is a constant operator, then the parameter must be a constant. Likewise, if the operator is a goal operator, it must be a goal, and if the operator is a strategic number operator it must be a strategic number.
Player - the parameter must be a type of player.
Text - the parameter must be text within quotation marks.

In our example, AnyPlayer must be a type of player, BuildingId must be a constant, and Value must match the compareOp operator. Since '>' is a compareOp that is used to compare constants, Value must be a constant.

So, if you wanted to customize this command, you could pick any valid player for AnyPlayer, pick any BuildingId, pick a comparison operator for compareOp, and choose whatever integer value you want for Value as long as the Value is within the allowable range.

Operators

Confused about operators? Don't be. Operators are special parameters that manipulate other parameters in ways you'll quickly recognize. There are only three types of operators. Click on the link for each one for full details.

compareOp - a comparison operator. Compares two values against each other. For example, '>' will compare two constant (numerical) values to see if the first parameter is greater than the following parameter. You can add a c: in front to specify that you're comparing constants, like 'c:>', but it's not necessary. '>' means the same thing as 'c:>'. If you want to compare values stored in two goals, you can turn the operator into a goal operator by adding a g: in front like this: 'g:>'. If you want to compare values stored in strategic numbers add a s: in front like this: 's:>'.
mathOp - a math operator. Performs math operations and stores the result in the goal in the following parameter. For example, 'c:+' will add a constant (numerical) value. Unlike compareOp, the 'c:' prefix is necessary. To do math operations with the value stored in a goal, add 'g:' before the math symbol, like 'g:+'. To do math operations with the value stored in a strategic number, add "s:' before the math symbol, like 's:+'.
typeOp - a type operator. This operator is either 'c:', 'g:', or 's:'. This operator determines whether the next parameter in the command should be treated as a constant, goal, or strategic number.

Here is an example that uses a goal operator: 'g:>'. This code will only send the message if an enemy has more than 2 castles (the value stored in gl-castle-amount).

(defconst gl-castle-amount 100)
(defrule
	(true)
=>
	(set-goal gl-castle-amount 2)
)
(defrule
	(players-building-type-count any-enemy g:> gl-castle-amount)
=>
	(chat-to-allies "An enemy has many castles. Watch out!")
)

Now you should be able to write commands in your AI with much more confidence, and you'll understand how to interpret all of the commands in this AI reference. Have fun digging into each of the many commands and parameters you have ready at your fingertips. Happy scripting!