The Battle for Wesnoth Wiki - User contributions [en]

FormulaAI

2009-04-28T19:37:33Z

Benetnash: /* Available variables */ typo

== 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].

== 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 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]

=== 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]

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.

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

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.

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 [http://www.wesnoth.org/wiki/FormulaAI_Functions 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' [[#Keywords|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, [http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/tools/vim/formulaai.vim 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 [http://www.vim.org/scripts/script.php?script_id=273 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|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!

[[Category:Development]]

[[Category:Development]]

FormulaAI Functions

2009-04-25T18:46:31Z

Benetnash: /* 'calculate_outcome' function */ fixed description

= Overview =

Syntax used to explain functions usage in this document is:

<result> = <function name>( <comma-separated list of parameters> [, <comma-separated list of optional parameters] )

Function may return <result> as:
* <variable> - any of the supported variable types
* <boolean> - false ( 0 or null ) or true ( 1 )
* <unit> - unit
* <location> - place on a gamemap
* <action> - object, which, if later passed to 'move= ' as the result of formula evaluation, make the AI perform a desired action.
* <result> - any of the above

Also function may return only single argument, or be able to return a whole list or a map.

There are a wide variety of functions which can be used to accomplish many different tasks. You can also [http://www.wesnoth.org/wiki/FormulaAI#Custom_Functions define your own functions].

=core functions=

=== 'abs' function ===

<number> = abs( <input number> )

Function returns absolute value of an <input number>, for example

abs( -5 )

will return 5.

=== 'choose' function ===

<result> = choose( <input list> , [ <string> ,] <formula> )

This function evaluates <formula> for each item in the <input> (which can be a list ro a map). Will evaluate to the one item which <formula> gave the highest value. For example:

choose(my_units, level)

gives back the unit with the highest level.

'''Note:''' The implicit input when evaluating a mapping/filtering function's <formula> component will be that specific item under evaluation (in this example one of "my_units"), and it can be explicitly referenced as 'self' when necessary. Optional <string> paremater indicates what word used in <formula> is equivalent to 'self'.

When evaluating the map data type, we can reference to each key by 'key' and each value by 'value'. For example:

choose( [ 'elf' -> 10, 'dwarf' -> 20 ], value )

Will return a key-value pair

{ key->'dwarf', value->20 }

=== 'contains_string' function ===

<boolean> = contains_string( <string>, <key> )

Returns 1 if <key> can be found withing <string>, 0 otherwise

contains_string( 'Testing', 'ing' )

returns

1

=== 'debug_print' function ===

{{DevFeature}} '''you need to enable formula log (--log-info=formula_ai) to see the result of this call'''

<formula> = debug_print( [ <optional string> ,] <formula> )

This function can be used for debging the formulas. It takes formula, writes output to the console and return it unchanged. For example:

debug_print( [ 1, 2, 3 ] )

will result in printing to the console

[ 1, 2, 3 ]

Return value is the same.

We can specify optional parameter that helps to distinguish what each of debug_print outputs is (useful if we have multiple debug_print functions):

debug_print( 'My array: ', [ 1, 2, 3 ] )

will write in the console:

My array: [ 1, 2, 3 ]

And return

[ 1, 2, 3 ]

=== 'debug_float' function {{DevFeature}} ===

<formula> = debug_float( <location>, [ <optional string> ,] <formula> )

This function can be used for debging the formulas. It takes formula, floats a label containing the output on the hex specified (in the same way damage is displayed) and return it unchanged. For example:

debug_float(me.loc, me.id )

will make a label containing the id of the unit "me" float over the unit

Return value is also the unit id.

We can specify optional parameter that helps to distinguish what each of debug_print outputs is (useful if we have multiple debug_print functions):

debug_float( me.loc, 'id: ', me.id )

will make the following label

id: <unit id

And return the unit id

=== 'dir' function ===

<list of names> = dir ( <input object> )

This function return list with all names of <input object's> members. For example:

dir( my_leader )

will result in output:

[ 'x', 'y', 'loc', 'id', 'leader', 'hitpoints', 'max_hitpoints', 'experience', 'max_experience', 'level',
'total_movement', 'movement_left', 'side', 'is_enemy', 'is_mine']

This command is useful in formula command line, to get information about members of different type of data. To get list of members of the ai, type:

dir( self )

=== 'filter' function ===

<result> = filter( <input>, [ <string> ,] <formula> )

This function will run <formula> on each item in the <input> (which can be a list or a map). Will evaluate to a <result> which only contains items the <formula> was true for. Optional <string> indicates what word used in <formula> is equivalent to 'self'. For example:

filter(my_units, hitpoints < max_hitpoints)

will return all of your units which have less than maximum hitpoints. For instance this could be used if looking for candidates for healing.

=== 'find' function ===

<result> = find( <input>, [ <string>,] <formula> )

This function will run <formula> on each item in the <input> (which can be a list or a map) and will return a first item for which <formula> was true. Optional <string> indicates what word used in <formula> is equivalent to 'self'. For example:

filter(units, id = 'Elvish Archer' )

will return first unit with id equal to 'Elvish Archer'.

=== 'head' function ===

<variable> = head( <list of variables> )

Head returns first item from the <list of variables>, for example

head( [ 5, 7, 9] ) #returns 5
head( [ 'Orc', 'Human' ] ) #returns 'Orc'

=== 'if' function ===

<result> = if( <condition> , <if true> [, <condition 2>, <if true 2>, ... ] [, <otherwise> ] )

If the <condition> parameter is true, the function will evaluate to being equal to its second input ( <if true> ), otherwise, if third imput is specified ( <otherwise> ), it will evaluate to being equal to it, else it will evaluate to null.
For instance, an AI that recruits Wolf Riders on the first turn, and Orcish Grunts thereafter might look like this:

move="if(turn = 1, recruit('Wolf Rider'), recruit('Orcish Grunt'))"

You can specify more than one pair of <condition> and <if true> paramters, for example such formulas:

if( var = 'first', 1, var = 'second', 2, var = 'third', 3 )
if( var = 'first', 1, var = 'second', 2, var = 'third', 3, 100 )

In case that var is equal to 'second' above will evaluate to

2
2

And in case of var equal to 'fifth':

null
100

=== 'index_of' function ===

<result> = index_of( <value>,<list> )

This function will return the first index where <value> can be found in <list>

It will return -1 if the value is not found

=== 'keys' function ===

<result list> = keys( <input map> )

Extract key values from a <input map> and return them as a <result list>

keys( [ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ] )

Returns

[ 'Elvish Fighter', 'Elvish Archer' ]

=== 'map' function ===

<result> = map( <input> , [ <string> ,] <formula> )

This function will run <formula> on each item in the <input> (which can be a list or a map), and evaluate to a new <result> list, or a map, which contains the same number of items as in <input>, with the formulas run on each item. Optional <string> indicates what word used in <formula> is equivalent to 'self'. For example:

map( [10,20], self*self)

and

map( [10,20], 'value', value*value)

both will result in [100, 400]. Formula:

map(my_units, hitpoints)

will give a list back with the number of hitpoints each unit has. This is more useful in conjunction with other functions.

map( [ 'elf' -> 10, 'dwarf' -> 20 ], value*2 )

Above will produce [ 'elf' -> 20, 'dwarf' -> 40 ]. Note that in case of a map data type, 'map' function can modify only the value.

map( tomap([3,5,8,8]), value+key*100 )

Above will produce [3 -> 301, 5 -> 502, 8 -> 801]. This can be used to take a list and make a map containing pairs [element_from_that_list -> f(element_from_that_list,number_of_repetitions_of_that_element_in_that_list) ] where f is an arbitrary function.

=== 'max' function ===

<number> = max( <list of numbers> )

Function will return maximal number from a list,

max( [ 2, 8, -10, 3] )

will return 8.

=== 'min' function ===

<number> = min( <list of numbers> )

Function will return minimal number from a list,

min( [ 3, 7, -2, 6] )

will return -2.

=== 'size' function ===

<number> = size( <list of variables> )

This function returns how many variables are stored in a list:

size( [ 5, 7, 9] ) #return 3
size( [ 'Archer', 'Fighter' ] ) #return 2

=== 'sort' function ===

<result list> = sort( <input list> , <formula> )

This function evaluates to a <result list> sorted according to the comparison <formula> for each item 'a' and its successor 'b'. For instance, sorting units according to hitpoints would be done by:

sort( my_units, a.hitpoints > b.hitpoints )

=== 'sum' function ===

<number> = sum( <list of numbers> )

This function evaluates to the sum of the items in the <list of numbers>. For example

sum( [ 2, 5, 8] )

returns 15, and:

sum( map( my_units, max_hitpoints - hitpoints ) )

finds the total damage your units have taken.

=== 'switch' function ===

<result> = switch( <variable>, <value 1>, <outcome 1>, ... , <value N>, <outcome N> [, <default outcome> ] >

Switch funtion takes variable, and checks if it is equal to any of the specified <values>. If matching value is found, <outcome> assigned to it is returned, if not, then function returns either <default outcome> (if specified) or null.

=== 'tolist' function ===

<list> = tolist( <input map> )

This function takes map and return a list of key-value pairs objects. For example:

tolist( [ 'Elf' -> 10, 'Dwarf' -> 20] )

will return:

[{key->'Elf',value->10}, {key->'Dwarf',value->20}]

=== 'tomap' function ===

<map> = tomap( <input list A> [, <input list B> ] )

This function takes one or two lists as input and returns a map. If only one list is specified, then function will evaluate this list, count how many simmilar elements are withing this list, and return a map with keys being these elements, and values being a number representing of them list contains, For example:

tomap( ['elf', 'dwarf', 'elf', 'elf', 'human', 'human' ] )

will return:

[ 'elf' -> 3, 'dwarf' -> 1, 'human' -> 2 ]

If two lists are specified, then elements of the first one will be used as a keys, and elements of second one as a values, when creating a output map. Note that these input lists must be of the same length.

tomap( [ 'elf', 'dwarf' ], [10, 20] )

will result in:

[ 'elf' -> 10, 'dwarf' -> 20 ]

=== 'values' function ===

<result list> = values( <input map> )

Extract values assigned to keys from a <input map> and return them as a <result list>

values( [ 'Elvish Fighter' -> 50, 'Elvish Archer' -> 60 ] )

Returns

[ 50, 60 ]

=== 'wave' function ===

<value> = wave( <value> )

given a value V, returns

sin(2*pi/(V%1000/1000) )

= AI specific functions =

== Base functions ==

=== 'attack' function ===

<action> = attack( <attacker's position>, <destination>, <attack location> [, <weapon> ] )

The first three parameters are locations. At the begining, unit which is standing at <attacker's position> is moved to <destination> place. Then, from that place unit is attacking unit which stands in place marked by <attack location>. Fourth optional parameter is number, and indicates which weapon attacker should use - if not specified, best possible weapon is chosed automatically.

=== 'fallback' function ===

<action> = fallback( [<name>] )

This function allows to chose different AI or to human player, who will take control over side untill the end of current turn. For example:

fallback()

will transfer control to the default C++ AI. You can specify a name of different AI (for example python_ai) to transfer control to it. If you want to give control to the player, use:

fallback( 'human' )

=== 'get_unit_type' function ===

<unit> = get_unit_type( <unit name> )

Function returns unit_type object of desired type, for example:

get_unit_type( 'Mage' )

will result in returning unit_type of a Mage.

=== 'move' function ===

<action> = move( <source> , <destination> )

Moves unit from <source> to <destination> and sets unit movement to 0. For example unit formula like:

move(my_leader.loc, loc(my_leader.loc.x, my_leader.loc.y - 1) )

will make leader move one hex north. Leader's movement points will be reset to 0.

=== 'move_partial' function ===

<action> = move_partial( <source> , <destination> )

Moves unit from <source> to <destination>. For example unit formula like:

move(my_leader.loc, loc(my_leader.loc.x, my_leader.loc.y - 1) )

will make leader move one hex north.

=== 'run_file' function {{DevFeature}} ===

<formula> = run_file( <string_file_location> )

Parses and runs the specified .fai file. 'def'-style functions in the file are added to the function table of the current AI.
File location follows the usual WML convention, for example, run_file('ai/formula/test.fai') will lead to './data/ai/formula/test.fai' being loaded.

At the moment, this function is useful mainly for debugging from the game console.

=== 'set_unit_var' function ===

<action> = set_unit_var( <key>, <value> , <location>)

This action creates a new variable which is attached to the unit at <location>

=== 'set_var' function ===

<action> = set_var( <key> , <value> )

This action sets new variable, for example:

set_var( 'Number one' , 1 )

Will create variable with name 'Number one' and assign 1 to it.

== Evaluation ==
=== 'calculate_outcome' function ===

[<list of outcomes>] = calculate_outcome(<attacker current location>, <attacker location> , <defender location> , [<weapon>] )

returns a list of possible outcomes when unit standing at <attacker current location> attacks the unit at <defender location> from <attacker location>

if no weapon is provided, it will return for the weapon considered the best by the C++ weapon choice algorithm (the one used to select default weapon in normal games)

=== 'chance to hit' function ===

<number> = chance_to_hit( <unit> , <location> )

This function returns how possible ( in % ) it is to hit given <unit> in a specific <location>. For example:

chance_to_hit( my_leader , my_leader.loc )

shows how easy it is to hit your leader has in a place he is currently standing on.

=== 'evaluate_for_position' function ===

<variant> = evaluate_for_position(<position>, <formula> )

Returns the result of <formula> as if <formula> was evaluated with a position of <position> instead of the current position

=== 'max_possible_damage' function ===

<number> = max_possible_damage( <attacking unit> , <defending unit> )

Function returns highest possible damage that <attacking unit> can inflict to <defending unit>.

=== 'max_possible_damage_with_retaliation' function ===

<number> = max_possible_damage_with_retaliation( <attacking unit> , <defending unit> )

Function returns an array:

[ <attacker_melee>, <attacker_ranged>, <defender_melee>, <defender_ranged> ]

in which first two elements are highest possible damage that <attacking unit> can inflict to <defending unit> with melee and ranged attacks, and latter two elements are highest possible damage that <defending unit> can inflict to <attacking unit> also with melee and ranged attacks.

=== 'movement_cost' function ===

<number> = movement_cost( <unit> , <location> )

This function returns movememtn cost of given <unit> in a specific <location>. For example:

movement_cost( my_leader , my_leader.loc )

shows what movement cost your leader has in a place he is currently standing on.

=== 'outcomes' function ===
[<list of positions>] = outcomes( <attack> )

this function take an attack (i.e a member of the "attacks" global variable) and return an array of positions

each position has a "chance" readable member that gives the chance of this outcome of occuring

other members of the position are not readable

positions are used as parameters for the '''evaluate_for_position''' function

=== 'timeofday_modifier' function {{DevFeature}} ===

<number> = timeofday_modifier(<unit> [, <location>] )

This function returns combat modifier (percentage, such as 25 for lawful unit during the day) due to time of day, taking alignment, illuminate, time of day and fearless trait into account. note: 'leadership' and 'slowed' are not taken into account.

unit - unit for which to evaluate

location - location for which to evaluate (optional, defaults to unit's current location)

== Gamemap functions ==

=== 'adjacent_locs' function ===

<loc list> = adjacent_locs( <location> )

Returns a list containing the list of the six locations adjacent to <location>

=== 'castle_locs' function ===

[<loc list>] = castle_locs(<location>)

given a hex, this function will return the list of all locations that is connected to <location> only by keeps or castle. I.e the hexes you can recruit from, assumin that you are at a keep at <location>

=== 'close enemies' function ===

<units list> = close_enemies( <location> , <distance> )

This function gets a list of enemies in the given or smaller distance from the location. For example:

close_enemies(loc(10,10), 5)

gives back a list of enemies in the distance of 5 tiles or less from the tile (10, 10).

=== 'distance_between' function ===

<number> = distance_between( <location A> , <location B> )

This function returns distance (in hexes) between <location A> and <location B>. For example:

distance_between( loc( 1, 1) , loc( 3, 3) )

will return 3.

=== 'distance_to_nearest_unowned_village' function ===

<number> = distance_to_nearest_unowned_village( <location A> )

This function returns distance (in hexes) between <location A> and nearest unowned village.

=== 'defense_on' function ===

<number> = defense_on( <unit> , <location> )

This function returns defense rate of given <unit> in a specific <location>. For example:

defense_on( my_leader , my_leader.loc )

shows how good defense your leader has in a place he is currently standing on.

=== 'find_shroud' function ===

<locations list> = find_shroud()

This function will return a list of locations of shrouded hexes.

=== 'is_unowned_village' function ===

<boolean> = is_unowned_village( <map or ai.map> , <location> ) #1

<boolean> = is_unowned_village( <map or ai.map> , <coordinate x> , <coordinate y> ) #2

The first argument is always a 'map' - member of the ai which provides information about the gamemap.

This will return true if we don't own the village (i.e it is unowned, owned by an ennemy, or owned by al allie)

=== 'is_village' function ===

<boolean> = is_village( <map or ai.map> , <location> ) #1

<boolean> = is_village( <map or ai.map> , <coordinate x> , <coordinate y> ) #2

The first argument is always a 'map' - member of the ai which provides information about the gamemap.

In #1 usage, we put in as a second argument location. In #2, second and third arguments are numbers: coordniates of the certain hex on a map. Function checks if that place is a village, and returns either 1 (yes, it is village) or 0 (no, it isn't village). Example of usage:

is_village( map , loc( 2, 3) )

is_village( map , 2, 3)

Both check, if hex with coordinates 2,3 is a village.

Remember, when using is_village in custom function, you either have to access map by writing 'ai.map', or specify ai as a 'default input'.

=== 'loc' function ===

<location> = loc( <X number>, <Y number> )

Function will return a location (pair of numbers) from two given input arguments.

=== 'shortest_path' function ===

<list of locations> = shortest_path( <location A> , <location B> [, <unit location> ] )

When only 2 parameters are specified, function returns list with all locations that unit standing on <location A> has to move through to get to <location B>. If optional 3rd parameter is specified, it returns list with all locations that unit standing on <unit location> would need to move through to get from <location A> to <location B>. This function takes into account zone of control of enemy units.

=== 'simplest_path' function ===

<list of locations> = simplest_path( <location A> , <location B> [, <unit location> ] )

When only 2 parameters are specified, function returns list with all locations that unit standing on <location A> has to move through to get to <location B>. If optional 3rd parameter is specified, it returns list with all locations that unit standing on <unit location> would need to move through to get from <location A> to <location B>. This function does not take into account zone of control or enemy units.

=== 'unit_at' function ===

<unit> = unit_at( <location> )

This function takes only one argument - location, and returns unit if there is one standing in that location, or null otherwise. Example of usage:

unit_at( loc( 4, 4) )

=== 'nearest_keep' function ===

<keep location> = nearest_keep( <input location> )

Function returns location of nearest keep to the specified <input location>, or null if there is no keep on the map.

=== 'nearest_loc' function ===

<keep location> = nearest_keep( <input location>, <list of locations> )

Function returns location that is the nearest to <input location>.

=== 'unit_moves' function ===

<locations list> = unit_moves( <unit location> )

Function returns list of all possible locations which unit standing at <unit location> can reach. If unit can't move, or there is no unit standing at given location, empty list is returned.

=== 'units_can_reach' function ===

<units list> = units_can_reach( <possible moves list>, <location> )

Function takes as an input list of possible moves ( ai.my_moves for units that belong to AI, or ai.enemy_moves for units that belong to the opponent ) and checks which units from that list can reach <location>.

== Recruitment ==

=== 'recruit' function ===

<action> = recruit( <unit name> [, <location> ] )

This function results in recruting a unit specifed by <unit name> at first free castle hex, or at given <location>. Function:

recruit('Footpad', loc(3,3) )

will result in recruting Footpad at castle hex with coordinates 3,3.

[[Category:Development]]
[[Category:Create]]
[[Category:WML Reference]]

FormulaAI

2009-04-11T14:45:37Z

Benetnash: my_attacks description

== 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].

== 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 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]

=== 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]

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.

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

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.

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_far 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 [http://www.wesnoth.org/wiki/FormulaAI_Functions 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' [[#Keywords|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, [http://svn.gna.org/viewcvs/*checkout*/wesnoth/trunk/data/tools/vim/formulaai.vim 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 [http://www.vim.org/scripts/script.php?script_id=273 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|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!

[[Category:Development]]

[[Category:Development]]