Difference between revisions of "FormulaAI"

From The Battle for Wesnoth Wiki
('switch' function)
(move Howto to new "See Also" section)
 
(65 intermediate revisions by 12 users not shown)
Line 1: Line 1:
 +
{| class="wikitable" style="text-align: center;"
 +
|'''Warning'''
 +
|-
 +
|Formula AI is still functional for the time being, but it is not maintained any more.
 +
That applies to both the code and these wiki pages.
 +
|}
 +
 
== Overview ==
 
== 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.
+
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:
 
Wesnoth already has support for AIs written in Python, but writing AIs in Python has a couple of problems:
Line 8: Line 15:
 
* Python is insecure; a malicious trojan horse Python script masquerading as an AI could do untold damage
 
* 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 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.
 
 
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]
+
== How formulas get called ==
...
 
ai_algorithm=formula_ai
 
  [ai]
 
  move="recruit('Wolf Rider')"
 
  [/ai]
 
[/side]
 
  
== Formula Command Line ==
+
=== 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
 
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
Line 36: Line 27:
 
will result in "12" appearing on the screen. You can now use Wesnoth like a calculator. :-)
 
will result in "12" appearing on the screen. You can now use Wesnoth like a calculator. :-)
  
== Formula Basics ==
+
=== 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)
  
* The Formula language supports basic arithmetic operations, such as: +, -, *, /, % and ^. It supports integers but does NOT support decimal or floating point numbers. For example:
+
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.
  
  4 + 8*7    #evaluates to 60
+
A sample AI which does nothing but recruit Wolf Riders is as follows:
(4 + 8)*7  #evaluates to 84
+
  [side]
8 % 6      #evaluates to 2
+
    ...
5 / 2      #evaluates to 2
+
    [ai]
  3 ^ 2      #evaluates to 9
+
        version=10710
 +
        [stage]
 +
            engine=fai
 +
            name=side_formulas
 +
            move="recruit('Wolf Rider')"
 +
        [/stage]
 +
    [/ai]
 +
  [/side]
  
* 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:
+
=== Unit Formulas ===
  
2 = 4    #evaluates to 0
+
You can specify a formula for any kind of unit. This is a simple way of doing it:
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:
+
[unit]
 +
  ...
 +
  [ai]
 +
    formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
 +
  [/ai]
 +
[/unit]
  
  3d5
+
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:
  
Which will give you one of results of rolling three five-sided dice (so random number between 3 and 15).
+
[side]
 +
    ...
 +
    [ai]
 +
        version=10710
 +
        [stage]
 +
            engine=fai
 +
            name=unit_formulas
 +
        [/stage]
 +
    [/ai]
 +
[/side]
  
== Data Types ==
+
If you need to execute unit formulas in a specific order, you can set a priority:
  
Formula System supports different types of data, which can be stored as a variables and are used in evaluations:
+
[unit]
 +
  ...
 +
  [ai]
 +
    formula="move(me.loc, loc(me.loc.x, me.loc.y - 1))"
 +
    priority=10
 +
  [/ai]
 +
[/unit]
  
* Numbers: like 0, 1, 2 etc. Floating-point numbers are not supported. 0 is equal to logical 'false', any other number is 'true'.
+
Units with highest priority get their formula executed first.
  
* Text strings:  
+
You can also define AI unit-specific variables and use them in you formulas:
  
  'this is a text string'
+
  [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]
  
* 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:
+
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.
  
  [4, 8, 7]  
+
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)"
  
is a list of three numbers, and  
+
=== 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
  
is a empty list. Various functions can operate on lists.
+
* 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
  
== AI Formula Language ==
+
==== Evaluation Algorithm ====
  
=== Overview ===
+
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 executing the move to do
  
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
+
The engine will run the following pseudo-code
  
  turn
+
  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
 +
      }
 +
}
  
The AI will print out the current turn number the game is on.
+
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
  
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.
+
==== Syntax ====
 +
To add a new candidate move to the RCA AI ''main_loop'' stage, use the following syntax:
  
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.
+
      [ai]
 +
          version=10710
 +
          [stage]
 +
              id=main_loop
 +
              name=testing_ai_default::candidate_action_evaluation_loop
 +
              {AI_CA_GOTO}
 +
              {AI_CA_RECRUITMENT}
 +
              {AI_CA_MOVE_LEADER_TO_GOALS}
 +
              {AI_CA_MOVE_LEADER_TO_KEEP}
 +
              {AI_CA_COMBAT}
 +
              {AI_CA_HEALING}
 +
              {AI_CA_VILLAGES}
 +
              {AI_CA_RETREAT}
 +
              {AI_CA_MOVE_TO_TARGETS}
 +
              {AI_CA_PASSIVE_LEADER_SHARES_KEEP}
 +
 +
              [candidate_action]
 +
                  engine=fai
 +
                  name=go_south
 +
                  type=movement
 +
                  evaluation="if((me.hitpoints < me.max_hitpoints), 60010, 0)"
 +
                  action="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
 +
              [/candidate_action]
 +
          [/stage]
 +
      [/ai]
  
=== Built-in functions ===
+
This is an example of a candidate action that gets added to all the standard RCA AI candidate actions and moves each unit with movement points left one hex south.  It is also possible to use
The formula language contains a large number of built-in functions which allow you to carry out all kinds of complex tasks. Syntax used to explain functions usage in this document is:
+
      {ai/aliases/stable_singleplayer.cfg}
 +
inside the [side] tag to set up the standard RCA AI candidate actions, and then add the customized candidate actions later using [modify_ai] or one of the available macros.
  
<result> = <function name>( <comma-separated list of parameters> [, <comma-separated list of optional parameters] )
+
Each [candidate_action] block describes a candidate move and must have the following fields
  
Function may return <result> as:
+
* ''name'' : the name of this candidate block
* <variable> - any of the supported variable types
+
* ''type'' : see the paragraph about types below, this describe the implicite variables that the formulas will be called with
* <boolean> - false ( 0 or null ) or true ( 1 )
+
* ''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
* <unit> - unit
+
* ''action'' : A formula that will be called if that candidate move is the best one
* <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.
+
==== Candidate move types ====
  
There are a wide variety of functions which can be used to accomplish many different tasks. You can also [[#Custom Functions|define your own functions]].
+
there are two types of candidate moves
  
==== 'attack' function ====
+
* '''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
  
<action> = attack( <attacker's position>, <destination>, <attack location> [,  <weapon> ] )
+
=== Summary : a typical AI turn ===
  
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.
+
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.
  
==== 'abs' function ====
+
Note that this means that you have to explicitely call "fallback" or set up the RCA AI ''main_loop'' stage specifically, if you want the C++ AI to finish your moves after a side-wide formula.  Also note that the stages are executed in the order in which they are put into the [ai] tag, not in the order of the above list.
  
<number> = abs( <input number> )
+
== AI Formula Language ==
  
Function returns absolute value of an <input number>, for example
+
For a detailed coverage of the language itself, see [[Wesnoth Formula Language]]. This section covers some things specific to the use of the language in FormulaAI.
  
abs( -5 )
+
=== Overview ===
  
will return 5.
+
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
  
==== 'chance to hit' function ====
+
turn
  
<number> = chance_to_hit( <unit> , <location> )
+
The AI will print out the current turn number the game is on.
  
This function returns how possible ( in % ) it is to hit given <unit> in a specific <location>. For example:
+
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.
  
chance_to_hit( my_leader , my_leader.loc )
+
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 ===
shows how easy it is to hit your leader has in a place he is currently standing on.
+
these are variables that you can call in an AI formula or from the command line.
 
 
==== 'choose' function ====
 
 
 
<result> = choose( <input list> , <formula> )
 
 
 
This function evaluates <formula> for each item in the <input list>. 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.
 
 
 
==== 'dir' function ====
 
 
 
==== '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.
 
 
 
==== 'evaluate_for_position' function ====
 
 
 
==== 'fallback' function ====
 
 
 
<action> = fallback( <name> )
 
 
 
This function allows to chose different AI which will take control over side untill the end of current turn. For example:
 
 
 
fallback( 'default' )
 
 
 
will transfer control to the default C++ AI.
 
 
 
==== 'filter' function ====
 
 
 
<reult list> = filter( <input list>, <formula> )
 
 
 
This function will run <formula> on each item in the <input list>. Will evaluate to a <result list> which only contains items the <formula> was true for. 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 ====
 
 
 
==== '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'
 
 
 
==== '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'.
 
 
 
==== 'if' function ====
 
 
 
<result> = if( <condition> , <if true> , <otherwise> )
 
 
 
 
 
If the <condition> parameter is true, the function will evaluate to being equal to its second input ( <if true> ), otherwise it will evaluate to being equal to its third input ( <otherwise> ).
 
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'))"
 
 
 
==== 'loc' function ====
 
 
 
<location> = loc( <X number>, <Y number> )
 
 
 
Function will return a location (pair of numbers) from two given input arguments.
 
 
 
==== 'map' function ====
 
 
 
<result list> = map( <input list> , <formula> )
 
 
 
This function will run <formula> on each item in the <input list>, and evaluate to a new <result list> which contains the same number of items as in <input list>, with the formulas run on each item. For example:
 
 
 
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.
 
 
 
==== 'max' function ====
 
  
<number> = max( <list of numbers> )
+
Some of these variables are complicated data structues, calling their name from the formula command line will allow you to easily see their content
  
Function will return maximal number from a list,
+
use the '''dir''' and '''debug_print''' to inspect the variables
  
  max( [ 2, 8, -10, 3] )
+
to get a coplete list, use the
 +
  dir(self)
 +
command
  
will return 8.
 
  
==== 'max_possible_damage' function ====
+
* ''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]]]"
  
==== 'min' function ====
+
* ''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
  
<number> = min( <list of numbers> )
+
=== Functions ===
  
Function will return minimal number from a list,
+
* 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 [[FormulaAI_Functions|here]].
  
min( [ 3, 7, -2, 6] )
+
* You can define your own functions in WML. 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:
 
 
will return -2.
 
 
 
==== 'move' function ====
 
 
 
<action> = move( <source> , <destination> )
 
 
 
For example unit formula like:
 
 
 
move(me.loc, loc(me.loc.x, me.loc.y - 1) )
 
 
 
will make unit move one hex north.
 
 
 
==== '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.
 
 
 
==== '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.
 
 
 
==== '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.
 
 
 
==== '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) )
 
 
 
==== '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>.
 
 
 
=== 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]
 
  [function]
Line 401: Line 296:
 
allows us to access leader info by simply writing 'my_leader'
 
allows us to access leader info by simply writing 'my_leader'
  
* You can also use 'def' [[#Keywords|keyword]] to define custom functions
+
=== Files and formulas ===
  
== Keywords ==
+
You can easily split your formulas between different files and include them when necessary. For example:
  
The formula language has some reserved keywords to provide primitive functionalityCurrently the following keywords are defined:
+
[unit]
 +
  ...
 +
  formula={my_unit_formula.fai}
 +
  [/unit]
  
* where: This keyword is used to defining statements in formulas. You can define multiple comma-separated statements. Syntax:
+
Will look for unit formula in the my_unit_formula.fai file.
  
  <formula> where <comma-separated list of statements>
+
Although it is not mandatory, we advocate to use following syntax in your fai files:
  
For example formula:
+
faifile '<filename>'
 +
...
 +
faiend
  
  a + b where a = 2, b = 4
+
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:
  
will give as result 6.
+
faifile 'my_unit_formula.fai'
 
+
...
* functions: Returns a list of all built-in and custom functions available to the AI
+
faiend
  
* def: This keyword creates functions using the syntax:
+
== Tool Support ==
  
  def function_name(arg1, arg2, ....) function_body
+
=== ctags ===
  
For example,  
+
For some rudimentary support for exuberant ctags, add the following to .ctags (or create the file if it doesn't exist):
  
  def sum(x,y) x + y
+
--langdef=formulaai
 +
--langmap=formulaai:.fai
 +
--regex-formulaai=/^def[ \t]*([a-zA-Z0-9_]+)/\1/d,definition/
  
creates a function sum taking two arguments and returns their sum.
+
This is especially nice when used with an editor or plugin with ctags support, such as Taglist for Vim.
  
 +
=== Vim ===
  
== Unit Formulas ==
+
====Syntax Highlighting====
  
You san specify a formula for any kind of unit. This is a simple way of doing it:
+
Follow these steps to enjoy vim syntax highlighting support for Formula AI.
 
 
[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.
+
# 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
  
You can also define AI unit-specific variables and use them in you formulas:
+
====Taglist Support====
  
[unit]
+
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.
  ...
 
  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), avg_damage_inflicted)"
 
  [ai_vars]
 
    guard_radius=3
 
    guard_loc="loc(8,5)"
 
  [/ai_vars]
 
[/unit]
 
 
 
This formula will get location position from variable guard_loc and make sure that unit attacks opponent which is 3 hexes (value specified by guard_radius variable) 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]
 
*location:
 
place="loc(X,Y)"
 
  
 +
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!
 +
 
  
 +
==See Also==
 +
* [[Wesnoth_AI]]
 +
* [[FormulaAI/Replacing]]
 +
* [[Formula_AI_Howto]]
  
[[Category:Development]]
+
[[Category:AI]]

Latest revision as of 15:21, 7 April 2023

Warning
Formula AI is still functional for the time being, but it is not maintained any more.

That applies to both the code and these wiki pages.

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 executing 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 to the RCA AI main_loop stage, use the following syntax:

      [ai]
          version=10710
          [stage]
              id=main_loop
              name=testing_ai_default::candidate_action_evaluation_loop
              {AI_CA_GOTO}
              {AI_CA_RECRUITMENT}
              {AI_CA_MOVE_LEADER_TO_GOALS}
              {AI_CA_MOVE_LEADER_TO_KEEP}
              {AI_CA_COMBAT}
              {AI_CA_HEALING}
              {AI_CA_VILLAGES}
              {AI_CA_RETREAT}
              {AI_CA_MOVE_TO_TARGETS}
              {AI_CA_PASSIVE_LEADER_SHARES_KEEP}

              [candidate_action]
                  engine=fai
                  name=go_south
                  type=movement
                  evaluation="if((me.hitpoints < me.max_hitpoints), 60010, 0)"
                  action="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
              [/candidate_action]
          [/stage]
      [/ai]

This is an example of a candidate action that gets added to all the standard RCA AI candidate actions and moves each unit with movement points left one hex south. It is also possible to use

      {ai/aliases/stable_singleplayer.cfg}

inside the [side] tag to set up the standard RCA AI candidate actions, and then add the customized candidate actions later using [modify_ai] or one of the available macros.

Each [candidate_action] block describes 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" or set up the RCA AI main_loop stage specifically, if you want the C++ AI to finish your moves after a side-wide formula. Also note that the stages are executed in the order in which they are put into the [ai] tag, not in the order of the above list.

AI Formula Language

For a detailed coverage of the language itself, see Wesnoth Formula Language. This section covers some things specific to the use of the language in FormulaAI.

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

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.
  • You can define your own functions in WML. 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'

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!


See Also

This page was last edited on 7 April 2023, at 15:21.