Formula AI Howto

This page is meant as a practical guide for setting up and testing Formula AI functionality in a scenario. It does not give a complete description of the Formula AI language. See FormulaAI and FormulaAI Functions for that. Make sure you have read the General RCA AI Howto as a basic understanding of the purpose of AI engines, stages and candidate actions is assumed here.

Also note that we do not explain all the different ways of setting things up here. Instead, we focus on one specific method that works reasonably well. Using variations thereof will hopefully be straightforward once the principles are understood.

Formula AI Setup

Unlike Lua AI, Formula AI does not require an engine to be set up, and (usually) no global variables need to be defined up front either. Thus, only one component needs to be set up, the stage, or stages, controlling Formula AI behavior. Three different stages are available for Formula AI code:

Formula AI unit_formulas stage: executes unit-specific FAI moves
Formula AI side_formulas stage: executes side-wide FAI moves
RCA AI main_loop stage (cpp): the standard AI stage

The stages are executed in whichever order they are put into the side tag. That is to say, all the moves of the first stage in the [ai] tag are played out first, then all the moves of the second stage, and so on until the last stage. Then the turn ends.

Note: The AI Module module page mentions another Formula AI stage called 'rca_formulas'. However, that stage does not exist in the current version. [Todo: test whether [register_candidate_actions] works with the RCA AI stage.]

Setting up the Formula AI Unit Formulas Stage

This stage executes formulas that are attached directly to specific units. To set it up, simply put the following code into the AI's [side] tag:

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

The first line is required and ensures that we are using the latest version of the AI. 'name' and 'id' keys can also be assigned to the stage, in case we want to remove it later.

Let's now set up a unit that does nothing but move one hex south each turn, we add [ai] tags to the unit definition:

       [unit]
           x,y=10,4
           id = Rark
           type="Saurian Augur"
           name="Rark"
           [ai]
               formula="move(me.loc, loc(me.loc.x, me.loc.y + 1))"
           [/ai]
       [/unit]

Here, the variable me is set automatically and contains all the unit information, with loc being a table containing its coordinates in 'x' and 'y' sub-fields. See the Testing section below for information on how to query what fields a unit variable such as me contains.

This is all that is needed. The unit defined above will move one hex south each turn ('move()' results in the movement points being set to zero afterward) until it hits an obstacle. It will do nothing else.

Unit formulas can be attached to any unit on the map. If the order in which the units do their moves matters, a priority can be set:

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

Units with the highest priority get their moves executed first.

Note: if the above is the only [ai] tag inside the side definition, the AI will only do unit formula moves. In order to also have other behavior, other stages, such as those described in the following sections, can be added to this [ai] tag (or in their own [ai] tags).

Setting up the Formula AI side_formulas Stage

Side-wide formulas are set up very similarly to the unit-specific formulas. Here is an example of a stage that moves all units with movement points left one hex north:

       [ai]
           version=10710
           [stage]
               engine=fai
               name=side_formulas
               move=" 
                   if( size(units) != 0, 
                       move(units[0].loc, loc(units[0].loc.x, units[0].loc.y - 1)),
                       end
                   ) 

                   where units = filter(my_units, movement_left > 0)
               "
           [/stage]
       [/ai]

The 'version' line is again required and the stage can also be given 'name' and 'id' keys, as before. The main difference here is that we now have one move that applies to the side overall, resulting in the me variable not being set. Thus, we first get all the units of our side (stored in my_units) which have movement left and store them in the units variable (a table). If the length of the table is not zero, the first unit gets moved one hex north. It now has no movement points left (because 'move()' is used, not 'move_partial()') and is therefore not chosen on the next iteration of the side_formulas stage. The stage repeats this move until no unit with movement left is found, in which case the 'if' function returns 'end'.

A few notes:

If the code gets too long, it might make more sense to put it into a file and include it with

move={path/filename.fai}

instead of including it directly as is done above.

If this stage is put into the [ai] tags in addition to the unit-specific stage of the previous section, the outcome depends on the order of the stages:
- If the 'unit_formulas' stage comes first, Rark is moved south, then all other units are moved north.
- In the opposite order, all units including Rark are first moved north. We then get an error message when the unit_formulas stage tries to move Rark south because he has no movement points left.

Setting up the RCA main_loop Stage and Candidate Actions

Testing Setup

Testing Formula AI code is, in principle, very easy. Simply type 'f' in the Wesnoth window (which accesses the Formula AI command line) and then enter the code to be executed. That's a lot of typing, however. It is easier to put the code into a file (say '~add-ons/FAI_tests/fai_manual.fai') and run it by typing

run_file('~add-ons/FAI_tests/fai_manual.fai')

Still easier is to include that line as a comment in the file itself and copy it to the Formula AI command line. Then we can simply type 'f' and 'cmd-v' (or whatever the paste keyboard shortcut is) to execute our test code. As an example, consider this file:

fai 'fai_manual.fai'
# run_file('~add-ons/FAI_tests/fai_manual.fai') #
# ---- Place test code below ----- #

dir(self)

# ---- Place test code above ----- #
faiend

Here, the first and last line are technically unnecessary, but it is good practice to include them in all Formula AI files as they can be useful for debugging purposes. The second line is the 'run_file' command mentioned above, that can now be easily copy-pasted into the Formula AI command line. Note that comments in Formula AI require the '#' symbol both at the beginning and end of the line.

The body of this example is a very simple, but powerful command: 'dir(self)'. It displays all available Formula AI variables. Its output shows that there is a variable my_units. If we want to see the structure and content of this variable, we replace the body of the file above with

my_units

or type that at the command line, since it is so short. In order to get the first of these unit, use

my_units[0]

and for its location (many Formula AI functions use the unit location)

my_units[0].loc

To select the unit with id "Rark", we type

filter(my_units, id='Rark')[0]

and if we wanted to do this using a function

def get_unit(ai*, unit_id)
    filter(my_units, id = unit_id)[0];

get_unit(self, 'Rark')

In the function call, 'self' passes the set of Formula AI variables to the function, the same set that was queried with 'dir(self)' above. It is put into variable ai in the function, with the '*' denoting ai as an implicit variable (meaning the variable holding the units can be accessed with my_units instead of ai.my_units).

So much for some very simple examples. For full documentation of the Formula AI language see FormulaAI and FormulaAI Functions. We are now ready for testing AI behavior. Let's assume that we have set up a test situation with one of our units (id = "Rark") and an enemy unit (id = "Krar") within reach of Rark. We want to test how to move Rark to the hex south of Krar. The body of '~add-ons/FAI_tests/fai_manual.fai' is now

move(me.loc, loc(target.loc.x, target.loc.y+1) )

where me = filter(my_units, id = 'Rark')[0]

where target = filter(enemy_units, id = 'Krar')[0]

The important thing here is that we have now set up a mechanism that creates the me and target variables as they are used in the stages described above. We can therefore replace the simple move used here with whatever AI behavior we want to test. Once we are done with testing, we can simply copy the code above the two 'where' lines into the AI stages or candidate actions.

Note that the Formula AI functions and variables do not need to be initialized. They are available at every turn for each side. Thus, we do not need to go through the tricks described for testing Lua AI, but can simply set up Side 1 with 'controller=human' and start with the testing.

Adding / Deleting Stages and Candidate Actions

Stages and candidate actions can be added and removed at any time in the scenario. A large number of macros are available in core/macros/ca.cfg for this purpose.

Here are two code examples of deleting candidate actions from the default RCA AI stage taken from Customizing_AI_in_Wesnoth_1.8. The first is done right at the beginning during the side definition:

[side]
   side=2
   {ai/aliases/stable_singleplayer.cfg}
   [ai]
       {MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop recruitment}
       {MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop move_leader_to_keep}
   [/ai]
[/side]

The second is done in an event:

[side]
    side=2
    {ai/aliases/stable_singleplayer.cfg}
[/side]
[event]
    name=some_event
    {MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop recruitment}
    {MODIFY_AI_DELETE_CANDIDATE_ACTION 2 main_loop move_leader_to_keep}
[/side]

Examples: Formula AI Code Library

Many examples of Formula AI code can be found found in the Formula AI Code Library page and in this forum thread.