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 this order. That is, first all unit moves are executed, then all side-wide moves are played out, and finally all candidate actions are evaluated and executed based on their evaluation scores. 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.]

Testing Setup

Testing Formula AI code is, in principle, very easy. Simply type 'f' in the Wesnoth window and then enter the code to be executed. That's a lot of typing, 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. 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_moves

or type that at the command line, since it is so short.

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.

A Few More Useful Tidbits

• dir(self): ...