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. In addition to the technical information on this page, a tutorial-style guide is also available at Formula AI Howto.

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 programming experience; 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.

How formulas get called

Formulas 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. :-)

Side-wide formulas

The first way to get a formula called is to assign it to a [side] in a WML map. This formula will be called every turn, so it is best used for very simple sides (a couple of special units which should have semi-scripted moves, or a simple handling followed by calls to the standard C++ AI)

To use the Formula AI, one should put an [ai] tag inside the [side] tag. Inside this [ai] tag, one should set up the side_formulas stage and specify the 'move' attribute to be a formula for the 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]
        version=10710
        [stage]
            engine=fai
            name=side_formulas
            move="recruit('Wolf Rider')"
        [/stage]
    [/ai]
[/side]

Unit Formulas

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

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

Above formula will simply move unit one hex to the north every turn. Note how "me" keyword allows access to unit itself. In addition, the unit_formulas stage also needs to be set up in the side definition:

[side]
    ...
    [ai]
        version=10710
        [stage]
            engine=fai
            name=unit_formulas
        [/stage]
    [/ai]
[/side]

If you need to execute unit formulas in a specific order, you can set a priority:

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

Units with highest priority get their formula executed first.

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

[unit]
 ...
  [ai]
    formula="if(attack, attack, move(me.loc, 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)"

    [vars]
      guard_radius=3
      guard_loc="loc(8,5)"
      hostile_side=1
    [/vars]
  [/ai]
[/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)"

Candidate move evaluation

Overview

Units in wesnoth have all sort of special abilities, special powers and special usages. Thus, it was needed to have an easy way to describe special behaviour for special units. Adding an formula to a unit only partially solves the problem. It allows easily to have special units (like ennemy heroes) have special behaviour but not normal units with special powers to to behave smartly.

Candidate moves are a way to have formula that will

evaluate a given situation
see if they are able to provide "special moves" for the case they know how to handle
give a move to do if the situation match their condition

Evaluation Algorithm

Each side will have some candidate move blocks made of

a name for the move
a type (see below for description of the different types and how they are called)
a formula returning a score for the move
a formula returning the move to do

The engine will run the following pseudo-code

while (a formula returned a score greatern than 0) {
     foreach (registered candidate move) {
          foreach (set of parameters for that candidate move's type) {
              call the evaluation formula, note the score returned
          }
     }
     if (the highest score returned was greater than 0) {
         call the candidate move that returned the highest score with the corresponding set of parameters
     }
}

in other word, we evaluate all candidate moves, then run the candidate move with the highest score, then re-evaluate everything, until no candidate move wants to play anymore

Syntax

to add a new candidate move you should add [register_candidate_move] blocks within the [ai] block.

Each block will describe a candidate move and must have the following fields

name : the name of this candidate block
type : see the paragraph about types below, this describe the implicite variables that the formulas will be called with
evaluation : a formula returning an integer. This number reflects how good the move is compared to other moves. Values of zero will mean the move is not a good idea and should be skipped
action : A formula that will be called if that candidate move is the best one

Candidate move types

there are two types of candidate moves

attack : these are called once for every pair <me,target> where me is a variable set to a unit on the AI side, and target is a variable set to an ennemy unit that "me" can reach
movement : these are called once for every unit on the AI side, the "me" variable is set to the corresponding unit

Summary : a typical AI turn

An AI turn will run the following formulas. Any formula returning an "end turn" move will (of course) finish the turn. But assuming this doesn't happen :

All unit formulas are called once
All candidate moves are evaluated and played
All move= formulas are called until they don't return valid moves
If no move= formula is provided, we drop automatically to C++
Turn is ended.

Note that this means that you have to explicitely call "fallback" if you want the C++ AI to finish your moves after a side-wide formula

Formula Basics

The Formula language supports basic arithmetic operations, such as: +, -, *, /, % and ^. It supports integers and decimal/floating point numbers, but operations will default to integer math unless operands are specified as floating point. For example:

4 + 8*7     #evaluates to 60
(4 + 8)*7   #evaluates to 84
8 % 6       #evaluates to 2
5 / 2       #evaluates to 2
5.0 / 2     #evaluates to 2.5
5 / 2.0     #evaluates to 2.5
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). NOTE: We encourage you to use this operator only when it is really needed. In most cases, you should not base the AI decisions on random results except for scenario replayability purposes.

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

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

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.

Some of these variables are complicated data structues, calling their name from the formula command line will allow you to easily see their content

use the dir and debug_print to inspect the variables

to get a coplete list, use the

dir(self)

command

attacks a list of all possible attacks

NOTE: this variable returns a list of all possible attacks (including attack combinations - attacking a single enemy unit with several units) , which is immediately treated as list of attack orders, which is evaluated (so, evaluation of this variable results in attacks being made). If you want to get the list without such evaluation, wrap it inside the array, "[attacks]". If you want to get the first attack, wrap it inside the array twice, "[[attacks[0]]" ]

my_attacks a list of all possible attacks. It returns slightly different list then attacks. I.e. when only two units (attacker and dedenter) are on the board attacks return one attack, from the position with the highest defence and my_attacks returns all 6 attacks from all adjacent tiles.
my_side global variables describing your own side
teams all the data about all the teams
turn the current turn number
time_of_day the current time of day
keeps all keep locations
vars all localy set varables using the set_var function
allies a list of all sides that are friendly
ennemies a list of all sides that are enemy
my_moves a list of all my moves
enemy_moves a list of all enemy moves
my_leader our leader unit
my_recruits the list of units that can be recruited by us
recruits_of_side foreach side the list of units that can be recruited
units the complete list of all units
units_of_side foreach side, a list of all owned 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
villages_of_side for each side, the list of villages owned
enemy_and_unowned_villages all villages that you don't own
map all the data about the map

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.

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.

Grab the Formula AI vim syntax file, formulaai.vim.
Copy formulaai.vim to .vim/syntax
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!

FormulaAI

Contents

Overview

How formulas get called

Formulas Command Line

Side-wide formulas

Unit Formulas

Candidate move evaluation

Overview

Evaluation Algorithm

Syntax

Candidate move types

Summary : a typical AI turn

Formula Basics

Data Types

AI Formula Language

Overview

Available variables

Built-in functions

Custom Functions

Comments

Keywords

Files and formulas

Tool Support

ctags

Vim

Syntax Highlighting

Taglist Support