FormulaAI

Overview

The Wesnoth Formula AI is an attempt to develop an AI framework for Wesnoth that allows easy and fun development and modification of AIs for Wesnoth.

Wesnoth already has support for AIs written in Python, but writing AIs in Python has a couple of problems:

• it's still rather difficult, especially for a non-programmer, to develop an AI, even in Python
• Python is insecure; a malicious trojan horse Python script masquerading as an AI could do untold damage

The Wesnoth Formula AI aims to create a fairly simple, pure functional language which allows one to implement an AI. It also aims to allow AIs to be tweaked and modified by people with relatively little technical skill; anyone who can use WML should also be able to use the Formula AI to tweak an AI to make the AI in a scenario behave how they want.

The Wesnoth Formula AI is currently in an experimental stage of development. One can play with it and develop a rudimentary AI. Feedback is appreciated.

To develop an AI using the Formula AI, set ai_algorithm=formula_ai in [side].

Approach

To use the Formula AI, one should put an [ai] tag inside the [side] tag. Inside this [ai] tag, one should specify the 'move' attribute to be a formula which specifies what movement the AI will make. Each time it's the AI's move, this formula will be run, and the move it results in will be executed. Then the formula will be run again; it'll continue to be run until it stops producing a valid move, at which point the AI will end its turn. Alternatively there is a command that the formula may return which will make it end its turn immediately.

A sample AI which does nothing but recruit Wolf Riders is as follows:

[side]
...
ai_algorithm=formula_ai
  [ai]
  move="recruit('Wolf Rider')"
  [/ai]
[/side]

Formula Command Line

To attempt to make it convenient to debug formulas, one can run formulas from within Wesnoth, and see the results. To run a formula, just start game and type 'f'. A command textbox will appear, where you can type a formula, and the results will be printed. For instance, typing

8 + 4 

will result in "12" appearing on the screen. You can now use Wesnoth like a calculator. :-)

Formula Basics

• The Formula language supports basic arithmetic operations, such as: +, -, *, /, % and ^. It supports integers but does NOT support decimal or floating point numbers. For example:

4 + 8*7     #evaluates to 60
(4 + 8)*7   #evaluates to 84
8 % 6       #evaluates to 2
5 / 2       #evaluates to 2
3 ^ 2       #evaluates to 9

• It also supports equality, = and !=, and comparison operators, <, >, <=, and >=. 'false' values are 0 (integer) and null. Other values are true. It also supports common operators such as and, or, and not:

2 = 4     #evaluates to 0
2 <= 3    #evaluates to 1
0 != 1    #evaluates to 1
not 4     #evaluates to 0
not 0     #evaluates to 1
(2 < 4) and (3 > 6)    #evaluates to 1 and 0 which evaluates to 0
(2 < 4) or (3 > 6)     #evaluates to 1 or 0 which evaluates to 1

• Formula language supports also 'dice' operator 'd'. Example usage is:

3d5

Which will give you one of results of rolling three five-sided dice (so random number between 3 and 15).

Data Types

Formula System supports different types of data, which can be stored as a variables and are used in evaluations:

• Numbers: like 0, 1, 2 etc. Floating-point numbers are not supported. 0 is equal to logical 'false', any other number is 'true'.

• Text strings:

'this is a text string' 

• Lists: A list is a sequence of values. For example, ai.my_units is a list of unit objects. A list is represented as square brackets, [], surrounding a comma-seperated list. For instance:

[4, 8, 7] 

is a list of three numbers, and

[]

is a empty list. Various functions can operate on lists.

To acces one particular element of a list we can use operator [], for example:

my_list[0]

Returns first element from the my_list, so:

[ 10, 20, 30, 40][2]

Returns

30

• Maps: A map is a sequence of pairs, each pair is a key and assigned to it value. For example:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ]

Is a map which consist of two pairs, first one assigns to the text string 'Elvish Fighter' the value 50, second one assigns 60 to the 'Elvish Archer' string.

To access value assigned to the key, we can use operator []:

[ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ][ 'Elvish Fighter' ]

Above example returns

50

AI Formula Language

Overview

The formula language must be able to access information about the scenario being played to make intelligent decisions. Thus there are various 'inputs' that one may access. A simple example of an input is the turn number one is on, given by the input, 'turn'. Try bringing up the formula command line using 'f' and then type in

turn

The AI will print out the current turn number the game is on.

The 'turn' input is a simple integer. However, some inputs are complex types which contain other inputs, or which may be lists of inputs. For instance, the input 'my_units' contains a list of all the AI's units.

A complex input such as a unit will contain a variety of inputs inside it. If one has a unit input, called 'u' for instance, one can access the 'x' co-ordinate of that unit by using u.loc.x -- u.loc accesses the 'location' object inside the 'unit' object, and the 'location' object contains 'x' and 'y' inputs inside it, which are the x and y co-ordinate of the unit.

Available variables

these are variables that you can call in an AI formula or from the command line.

• turn the current turn number
• units the complete list of all units
• my_units the complete list of all units owned by the current player
• enemy_units all units that are enemy to the current player
• villages all the villages on the map
• my_villages all the villages owned by the current player
• enemy_and_unowned_villages all villages that you don't own
• map all the data about the map
• teams all the data about all the teams

Built-in functions

The formula language contains a large number of built-in functions which allow you to carry out all kinds of complex tasks. List of these functions, usage and simple examples can be found here.

Custom Functions

• You can define your own functions. A function is a formula which takes some inputs as parameters. Suppose we wanted to define a function that puts some value on a unit, we might add the following to the [ai] tag:

[function]
name=value_unit
inputs="unit"
formula="unit.hitpoints + unit.level*4"
[/function]

This has defined a new function which takes a 'unit' as an input, and runs the given calculation over it.

• We can have multiple inputs in our functions, to define them, just create comma-separated inputs list:

inputs="attacker,defender"

This has defined a new function which takes both 'attacker' and 'defender' as an inputs.

• Sometimes, we use one of our inputs really often in our function - to make our life easier we can make its members (inputs) directly accessible from within the formula. This is improved version of function from above:

[function]
name=value_unit
inputs="unit*"
formula="hitpoints + level*4"
[/function]

As you can see, if we define input with a * char at the end, we make it a 'default input' for a formula. Note, that you can define only one default input per function.

• It is important to know difference between formulas defined in custom functions, and formula defined by a 'move=' in a [ai] tag. For example, if we want to get info about leader, we write in formula 'my_leader' - which acces member of the AI. To be able to use 'my_leader' in custom functions we have to add 'ai' as an input for our function:

inputs="ai"

allows us to access leader info by writing 'ai.my_leader', or:

inputs="ai*"

allows us to access leader info by simply writing 'my_leader'

• You can also use 'def' keyword to define custom functions

Comments

Comments in Formula AI scripts are enclosed by # #:

#Define opening move#
def opening(*ai) 
 if(turn = 1,
  move(loc(11,23), loc(14,22)),
 [])

Comments may also be included at the end of a line:

def opening(*ai) 
 if(turn = 1,
  move(loc(11,23), loc(14,22)), #capture village#
 []) #do nothing#

and they may also be used inline:

def opening(*ai)
 if(turn = 1,
  move(loc(11,23) #my_leader#, loc(14,24) #closest village#),
 [] #do nothing# )

Keywords

The formula language has some reserved keywords to provide primitive functionality. Currently the following keywords are defined:

• where: This keyword is used to defining statements in formulas. You can define multiple comma-separated statements. Syntax:

 <formula> where <comma-separated list of statements>

For example formula:

 a + b where a = 2, b = 4

will give as result 6.

• functions: Returns a list of all built-in and custom functions available to the AI

• def: This keyword creates functions using the syntax:

 def function_name(arg1, arg2, ....) function_body

For example,

 def sum(x,y) x + y

creates a function sum taking two arguments and returns their sum.

Unit Formulas

You san specify a formula for any kind of unit. This is a simple way of doing it:

[unit]
  ...
  formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
[/unit]

Custom unit formulas are executed first at the begining of side's turn. Above formula will simply move unit one hex to the north every turn. Note how "me" keyword allows access to unit itself.

You can also define AI unit-specific variables and use them in you formulas:

[unit]
 ...
 formula="if(attack, attack, move(me.loc, choose(unit_moves(me.loc), -distance_between(self, me.vars.guard_loc))))
 where attack = choose(filter(attacks, units = [me.loc] and distance_between(me.vars.guard_loc, target) <= me.vars.guard_radius and unit_at(target).side=me.vars.hostile_side-1 ), avg_damage_inflicted)"
 [ai_vars]
   guard_radius=3
   guard_loc="loc(8,5)"
   hostile_side=1
 [/ai_vars]
[/unit]

This formula will get location position from variable guard_loc and make sure that unit attacks only opponent from side 1 (value specified by hostile_side variable) which is 3 hexes (guard_radius) or less from guard_loc.

Types of variables that are supported:

• number:

variable=3

• text (important: note the ' ' within " "):

name="'I am variable'"

• list:

number_list=[ 1, 2, 3]

• map:

map=[ 'Elvish Archer' -> 70, 'Elvish Shaman' -> 60 ]

• location:

place="loc(X,Y)"

Files and formulas

You can easily split your formulas between different files and include them when necessary. For example:

[unit]
 ...
 formula={my_unit_formula.fai}
[/unit]

Will look for unit formula in the my_unit_formula.fai file.

Although it is not mandatory, we advocate to use following syntax in your fai files:

faifile '<filename>'
...
faiend

This makes formula system know which file it is working with now, and gives you improved error reporting, which is often really helpful. Valid syntax for my_unit_formula.fai would be:

faifile 'my_unit_formula.fai'
...
faiend

Tool Support

ctags

For some rudimentary support for exuberant ctags, add the following to .ctags (or create the file if it doesn't exist):

--langdef=formulaai
--langmap=formulaai:.fai
--regex-formulaai=/^def[ \t]*([a-zA-Z0-9_]+)/\1/d,definition/

This is especially nice when used with an editor or plugin with ctags support, such as Taglist for Vim.

Vim

Syntax Highlighting

Follow these steps to enjoy vim syntax highlighting support for Formula AI.

1. Grab the Formula AI vim syntax file, formulaai.vim.
2. Copy formulaai.vim to .vim/syntax
3. Add the following to .vimrc :

autocmd! BufRead,BufNewFile *.fai setfiletype formulaai

Taglist Support

First you will need the very nice taglist plugin. Follow the link for downloads and install directions if you don't already have it installed.

Next, you'll need Formula AI support for exuberant ctags, follow the instructions in the ctags section.

Once you have all that, simply add the following line to your .vimrc:

let tlist_formulaai_settings = 'formulaai;d:definition'

To test it all out, open a Formula AI script file and enter the command

:Tlist

You should now have some nice highlighting and be able to easily navigate through formula, enjoy!