Lua AI Legacy Methods Howto

Warning

This page describes some of the old methods available for setting up Lua AI functionality. They are still working and described here because quite a bit of existing code still uses them. It is, however, generally not recommended to use these methods for new code any more. Use those described at Creating_Custom_AIs instead. Also note that this page is not being updated any more.

This page is meant as a practical guide how to set up and test Lua AI functionality in a scenario. It does not give a complete description of Lua or Lua AI. See LuaAI, LuaAI Functions or LuaWML for that. Make sure you have read 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.

Lua AI Setup

Setting up a Lua AI requires the definition of a Lua AI engine in the [side] tag and one or more stages executing the individual AI actions. We restrict ourselves here to the example of using the default main_loop stage with its candidate actions.

The example listed below is that of the Simple Lua AI Demo scenario of the AI-demos add-on. You can go there if you want to see this used in an actual campaign.

Unlike Formula AI and the default cpp AI, Lua AI requires an engine to be defined (this is obsolete). Specifically, it does not work in [modify_side]. Here is an example of such an [ai] tag:

        [ai]
            version=10710
            [engine]
                name="lua"
                code= <<
                    local ai = ...
                    return wesnoth.require("~add-ons/AI-demos/lua/luaai-demo_engine.lua").init(ai)
                >>
            [/engine]
            [stage]
                id=main_loop
                name=ai_default_rca::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_LEADER_SHARES_KEEP}
                [candidate_action]
                    engine=lua
                    name=move_spearmen
                    id=move_spearmen
                    evaluation="return (...):move_unittype_eval('Spearman', 100010)"
                    execution="(...):move_unittype_exec('Spearman', 4, 20)"
                [/candidate_action]
                [candidate_action]
                    engine=lua
                    name=move_bowmen
                    id=move_bowmen
                    evaluation="return (...):move_unittype_eval('Bowman', 99990)"
                    execution="(...):move_unittype_exec('Bowman', 34, 20)"
                [/candidate_action]
            [/stage]
        [/ai]

Note that a lot of this is simply setting up the default main_loop stage and candidate actions. The important non-default lines are:

The 'version=' line is required and ensures that we are using a version of the AI that can use a Lua AI engine.

In the [engine] tag, the 'name=' key tells Wesnoth that we are going to use the Lua engine. 'ai = ...' means that all the default Lua AI functions will be available through the ai table (they get handed down from the process creating the engine through Lua's variadic function '...').

The engine returns the return value of function init in file ~add-ons/AI-demos/lua/luaai-demo_engine.lua. This sets up the custom AI functions. Note the we are passing the ai table defined in the previous line to init(), in order to make it available to the custom AI functions.

The remaining custom lines are setting up the custom candidate actions at the end of the code, which call the move_unittype_eval() and move_unittype_exec() functions. These are defined in the luaai-demo_engine.lua file that is included in the [engine] tag:

return {
    init = function(ai)

        local luaai_demo = {}

        local H = wesnoth.require "lua/helper.lua"

        function luaai_demo:move_unittype_eval(type, score)
            local units = wesnoth.get_units {
                side = wesnoth.current.side,
                type = type,
                formula = '$this_unit.moves > 0'
            }

            if units[1] then return score end
            return 0
        end

        function luaai_demo:move_unittype_exec(type, goal_x, goal_y)
            local unit = wesnoth.get_units {
                side = wesnoth.current.side,
                type = type,
                formula = '$this_unit.moves > 0'
            }[1]

            -- Find path toward the goal
            local path, cost = wesnoth.find_path(unit, goal_x, goal_y)

            -- If there's no path to goal, or all path hexes are occupied,
            -- use current position as default
            local next_hop = { unit.x, unit.y }

            -- Go through path to find farthest reachable, unoccupied hex
            -- Start at second index, as the first is just the unit position itself
            for i = 2,#path do
                local sub_path, sub_cost = wesnoth.find_path( unit, path[i][1], path[i][2])

                -- If we can get to that hex, check whether it is occupied
                -- (can only be own or allied units as enemy unit hexes are not reachable)
                if sub_cost <= unit.moves then
                    local unit_in_way = wesnoth.get_unit(path[i][1], path[i][2])
                    if not unit_in_way then
                        next_hop = path[i]
                    end
                else  -- otherwise stop here; rest of path is outside movement range
                    break
                end
            end

            --print('Moving:', unit.id, '-->', next_hop[1], next_hop[2])
            ai.move_full(unit, next_hop[1], next_hop[2])
        end

        return luaai_demo
    end
}

These functions set up and return a Lua table called luaai_demo which contains two functions move_unittype_eval() and move_unittype_exec(). These are the evaluation and execution functions that are called by the custom AI candidate actions.

Note that the AI behavior of this example is very simple and meant as a demonstration only. It sends all units of a certain type to a certain location on the map. Note that the unit type, the location as well as the candidate action evaluation score are parameters that are passed to the functions in the [candidate_action] tags. Thus, it is possible to send Spearmen and Bowmen to different locations. Furthermore, by using evaluation scores just below and above the default combat CA, we can have the bowmen attack enemy units within reach while the spearmen avoid all combat. See what effect this has in practice by checking out the Simple Lua AI Demo scenario in the AI-demos add-on.

Notes:

• Important: The evaluation functions may not change the game state. Doing that will lead to OOS errors and may even crash the game.
• With Formula AI it is possible to add candidate actions without specifically defining the RCA AI stage. That is not possible in Lua AI, the engine and main_loop stage always need to be set up.

The data Variable

In the example above, the variable units (or unit) is defined separately in both the evaluation and the execution functions. This is not a big deal here as it is a simple (and quick) function call. Imagine however that we were doing a long evaluation of, say, the best possible attack out of a myriad of different options, that we then want to evaluate against a retreat option evaluated in a different candidate action. Both the combat and the retreat CA return their score, and the CA with the higher score is executed. If combat is chosen, we want to avoid having to redo the entire attack evaluation in the execution function just to determine, again, which attack is the best.

This duplication of code and additional calculation time can be avoided using the built-in persistent data variable. This variable is automatically produced by the engine as a field of the table returned by the custom AI. It has the added advantage that it persists through save/load cycles (see LuaAI#Persistence). It can be accessed through variable self.data inside the custom AI code. In the example above we could use:

    self.data.units = wesnoth.get_units { insert filter here }

in the evaluation function and

    local unit = self.data.units[1]

in the execution function.

Note: since move_unittype_eval() and move_unittype_exec() are written as methods of object luaai_demo (through use of ':'), self refers to the object holding them: luaai_demo. One could just as well use luaai_demo.data.units here.

Testing setup

*** This section has not yet been updated***

If we were using only the code described above, Wesnoth would have to be restarted (or the cache cleared with F5) every time we made a change to the code. That is very tedious and slow for development and testing purposes. There are much quicker options to accomplish this. One of them is to include the code in a file and then type:

:lua wesnoth.dofile(filename)

in the Wesnoth window. However, there is an even easier method through the right-click menu. In order for this to work, we need:

• The AI to be initialized, but the player having control of the side
• A right-click menu option to run Lua engine code
• Specific attention is needed if the data variable is to be used

Initializing the AI

Let's assume that Side 1 is the side for which we want to develop an AI and Side 2 is the side against which we want to test it. We need to have control of Side 1, so that the correct side's units can be manipulated using the built-in Lua AI functions (otherwise we get 'move_result::E_NOT_OWN_UNIT' errors). However, these functions are only initialized when needed, that is, when the AI plays through its first turn. Furthermore, if the ai variable in the engine is defined as a local variable, they are deleted as soon as the AI turn is done and redefined only for the next turn.

We circumvent these problems by using two little tricks. First, we define that ai variable as global, meaning it needs to be defined first in the preload event, and it needs to be defined as 'ai = ...' rather than 'local ai = ...' in the engine, as described above. Second, we let the AI play through its first turn, and then change the controller to human for the second turn. This can be done either manually in debug mode using ':droid 1', or automatically by including the following event in the scenario:

   [event]
       name=side 1 turn 1 end

       [modify_side]
           side=1
           controller=human
       [/modify_side]
   [/event]

If this event is used, it does not matter whether Side 2 is human or AI controlled, but setting it up as AI controlled means that we are immediately placed at the beginning of Turn 2 in control of Side 1, ready to test our AI code.

As a side note, it is also possible to test the AI code by controlling Side 1 units while being in (human) control of Side 2 (after the ai variable has been initialized as described above). It is, in that case, however more difficult to move those units around for testing purposes.

Right-click Menu Option to Execute Lua Code

In order to avoid having to restart Wesnoth every time we make a change, we can place the Lua code to be tested in a file ('~add-ons/LuaAI_tests/lua_manual.lua' for this example). This file can be executed at the command line by typing (or copy-pasting):

:lua wesnoth.dofile "~add-ons/LuaAI_tests/lua_manual.lua"

Even easier is placing this in a macro providing a right-click menu option:

#define LUA_RELOAD_MENU
   [event]
       name=start

       [set_menu_item]
           id = m01
           description=_"Reload Lua code"
           image=items/ring-red.png~CROP(26,26,20,20)
           [command]
               [lua]
                   code=<<wesnoth.dofile "~add-ons/LuaAI_tests/lua_manual.lua">>
               [/lua]
           [/command]
       [/set_menu_item]
   [/event]
#enddef

Once we place {LUA_RELOAD_MENU} in the [scenario] tag, all we need to do is choose this option from the right-click menu every time we change code in the file and test at will.

Putting It All Together: The Testing Environment

To summarize, we want to have the following pieces in place for easy testing of Lua AI code (using the previous example):

• Macro {LUA_AI_PRELOAD} as defined above, placed inside the [scenario] tag
• An empty Lua engine definition, and the stages and candidate actions, placed inside the [side] tag as follows:

   [ai]
       version=10710
       [engine]
           name="lua"
           code= <<
--! ==============================================================
--local ai = ...  -- use this for the final version
ai = ...          -- use this for testing

local my_ai = {}

return my_ai
--! ==============================================================
>>
       [/engine]
       [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=lua
               name=go_south
               evaluation="return (...):go_south_evaluation()"
               execution="(...):go_south_execution()"
           [/candidate_action]
       [/stage]
   [ai]

The stage and candidate action definition is, in principle, optional at this point, however, some stage doing something on Turn 1 is required, otherwise the ai variable is never defined (it only gets defined when it is needed).

• Side 1 to be set up with 'controller=ai', and the 'side 1 turn 1 event' defined above placed inside the [scenario] tag
• Macro {LUA_RELOAD_MENU} as defined above, placed inside the [scenario] tag
• Finally, we want a file '~add-ons/LuaAI_tests/lua_manual.lua' with the following content:

local my_ai = {}

function my_ai:go_south_evaluation()

   local units = wesnoth.get_units 
       { side = wesnoth.current.side, 
           formula = "(hitpoints < max_hitpoints) and ($this_unit.moves > 0)" 
       }

   local value = 0
   if units[1] then
       value = 80010
   end

   --print("Go south evaluation:", value)
   return value
end

function my_ai:go_south_execution()

   local units = wesnoth.get_units 
       { side = wesnoth.current.side, 
           formula = "(hitpoints < max_hitpoints) and ($this_unit.moves > 0)" 
       }

   for i,u in ipairs(units) do
       ai.move_full(u, u.x, u.y+1)
   end
end

-------------------------------------------------

wesnoth.clear_messages()

local eval = my_ai:go_south_evaluation()
if (eval > 0) then
   my_ai:go_south_execution()
end

The code below the dashed line can be any variation of AI function calls and can contain whatever debug message output is desired.

• Once testing is done and we are happy with the code, all we need to do is copy everything above the dashed line into the engine code. Ideally, we also make ai a local variable there and delete everything not needed from the preload event (including the global ai variable).

Setting up the data Variable

Note that the data variable is not set up in this testing environment, because it gets added by the engine to the local variable my_ai that is not available outside the engine. If data is needed, there are two ways of dealing with this:

1. Make my_ai a global variable for testing. This requires setting it up with 'my_ai = {}' in the preload event, and deleting the 'local' in front of my_ai in the engine definition as well as in the file '~add-ons/LuaAI_tests/lua_manual.lua' (or deleting it entirely from the latter).
2. Starting the code in file '~add-ons/LuaAI_tests/lua_manual.lua' with

local lurker_ai = {}
lurker_ai.data = {}

and thus specifically defining the data variable there.

Both methods include variable definitions that are unnecessary for the final AI code and should be undone for the final version. However, the code will still work even if we forget to undo these definitions.

Behavior (Sticky) Candidate Actions

Behavior (Sticky) Candidate Actions (BCAs) are entirely equivalent to "normal" CAs except that they are specifically tied to a unit. As such, the BCA is removed when the unit dies. This has two advantages:

1. The BCA code does not need to include checks whether the unit exists
2. No computation time is taken up for evaluating the BCA after the unit dies (although that is likely a very small amount of time saved)

Besides that, BCAs work in exactly the same way as other CAs. In particular, they are also evaluated against the other CAs using the same criteria. Thus, if a BCA is what a unit is supposed to do under all circumstances, it needs to be given a higher evaluation score than all other CAs that might apply to the unit.

As an example, to apply the go-south code from above only to a unit with id 'Rark' on Side 1, we would use:

   [add_ai_behavior]
       side=1
       [filter]
           id="Rark"
       [/filter]
       sticky=yes
       loop_id=main_loop
       evaluation="return 300000"
       execution="(...):go_south_execution('Rark')"
   [/add_ai_behavior]

This declaration needs to be placed inside ActionWML after the unit has been created. In the code, 'sticky' means that the candidate action is tied to the unit defined by [filter]. 'loop_id' needs to be the id of the RCA AI stage. Usually that is main_loop. The evaluation score is hard-coded to 300,000 in order for the BCA to be executed before all other CAs. 'execution' calls my_ai:go_south_execution() in the same way as before, but now using parameter 'Rark'. The execution function then needs to be:

function my_ai:go_south_execution(id)

   local unit = wesnoth.get_units { id = id }[1]
   ai.move_full(unit, unit.x, unit.y+1)

end

If go_south_execution(id) is only to be done when Rark is wounded, an evaluation function similar to the previous version can be used. Then, Rark would only go south if wounded, and partake in normal AI behavior otherwise, entirely equivalent to the previous example.

An interesting variation of BCA use could be a candidate action that applies to all units of the AI side, but is only executed if a certain unit is on the map. For example, a BCA could be tied to an evil sorcerer leader that makes all his minions attack suicidally without doing anything else. Once the sorcerer is defeated, the BCA disappears with him and the other units on his side start following the standard AI behavior again.

Using the Lua Stage

If the candidate action evaluation mechanism of the RCA AI stage is not needed, Lua AI moves can also be programmed in separate Lua stages, either in place of or in addition to the RCA AI stage:

   [stage]
       engine=lua
       id=some_id
       name=some_name
       code=<< Lua stage code >>
   [/stage]

The code can be defined directly here, or included from a file using wesnoth.dofile. However, since the Lua engine needs to be defined in any case (in the same way as for the previous example), the AI moves can just as well be defined again in the [engine] tag in exactly the same way as before. They can then be called from the Lua stages entirely analogous to what was done before:

   [stage]
       engine=lua
       id=some_id
       name=some_name
       code=<< (...):do_moves() >>
   [/stage]

where we assume that a my_ai:do_moves() function is defined in the engine. In that case, the only difference is that the evaluation functions are now not separated from the execution functions on the stage/candidate action level, but that both are taken care of by the do_moves() function.

Adding / Deleting Stages and Candidate Actions

While the Lua AI engine needs to be defined at the beginning of the scenario in the [side] tag, 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/ai.cfg for this purpose.

Here are two code examples of deleting candidate actions from the default RCA AI stage. 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]

A Few More Useful Tidbits

• Setting up aspects and goals/targets is described at LuaAI#Aspects and not repeated here
• debug_utils from Wesnoth Lua Pack is a very powerful tool to analyze what is going on when something is not working as expected. It can be used to display the content of essentially any Wesnoth Lua data structure. As an example, the following command:

debug_utils.dbms(ai, false, "variable", false)

shows all the default Lua AI functions -- assuming that the ai variable has been initialized.