Wesnoth AI Framework

From The Battle for Wesnoth Wiki
Revision as of 15:20, 19 February 2016 by Mattsc (talk | contribs) (→‎The [ai] Tag — Aspects and Goals: minor change to an example)
This page is currently under construction (Feb 2016)


Wesnoth AI Framework: A Composite AI

The Wesnoth AI framework is that of a composite AI. In other words, rather than the AI being one huge monolithic block, it is composed of a variety of different components which can be combined in a modular fashion (almost) at will.

In its default configuration, Wesnoth provides a predefined combination of these components in the RCA_AI. This configuration can be modified in a multitude of different ways. Due to the modular setup, it is not only possible to add new AI behavior to the beginning or end of the default AI or replace it entirely, but to insert new bits and pieces in between existing components. This can be done either in addition to or as substitutes for existing components.

This page describes the AI components in a general sense. Check out RCA_AI for how these are assembled into the default AI and Wesnoth_AI for a collection of links to pages explaining how to configure and modify the existing AI or write a completely new AI.

Types of AI Components

The Wesnoth AI framework consists of the following types of components:

Stages

These are the fundamental building blocks of the AI. The AI is set up as a series of stages which are executed in the order in which they are put into the AI configuration. In other words, all actions of the first stage are executed first, then all actions of the second stage, etc.

While there are five different types of stages, only one of them, called the main_loop stage, is used in the default AI. In fact, this stage is sufficient for the vast majority of custom AI applications as well. We therefore postpone the description of the other stages and describe how the main_loop stage and its sub-components work first.

The Candidate Actions of the main_loop Stage

The main_loop stage consists of a number of candidate actions (CAs). For each AI move, all CAs are evaluated and assigned a score. The CA with the highest score is executed. Then all of them are evaluated again (including the one that was just executed) and the highest scoring CA is executed until no CA returns a valid score any more.

Using individual candidate actions which fulfill very specific tasks, it is possible to assemble entire AIs in a modular fashion. The CAs can be put together in whatever order and combination best suits the needs of a scenario. They do not need to be sorted in order of their evaluations scores and can even have variable evaluation scores, so that CA A will sometimes have a score higher than CA B and sometimes a lower score, depending on the situation on the map.

For a summary of the candidate actions of the default AI, click here. For more technical details, see XXX.

Aspects and Goals

Aspects are simply the return values of certain functions that can be read by the candidate actions. They thus serve as configurable input parameters to modify a CA's behavior. The return values of the aspect functions can be defined using both WML or Lua.

A goal is a special type of aspect that determines the directions into which the default AI moves its units. See here.

Engines

Engines execute the code provided for the individual components of the AI. In recent Wesnoth versions, you do not need to worry about the engines any more, they are always defined and active. It is sufficient to know that the components can be written in three different languages, C++, Lua and Formula AI (FAI). Information on how to do this is provided in the links of the Wesnoth_AI page.

It is worth noting that some stages are only set up for specific engines (see below), while the candidate actions, aspects and goals (todo: confirm the latter) of the main_loop stage can be written in any of the three languages and can be combined arbitrarily.


AI Configuration

The Wesnoth AIs are assembled from configurations provided in several different places:

  • The default AI parameters in a variety of configuration files in the 'data/ai/' directory
  • Optional [ai] or [modify_ai] tags in era configurations
  • Optional [ai] or [modify_ai] tags in multiplayer faction configurations
  • Optional [ai] or [modify_ai] tags in scenario configurations

When the game is created, all these config snippets are merged into a single configuration stored in form of an [ai] tag. Then, aspects with the same ids are merged. Furthermore, whenever a [modify_ai] tag is acted upon (for example in an event), it is added into the existing AI configuration in the same way.

In the following, we describe the syntax of the [ai] tag. We first show the top-level keys and tags that can be used. Details on the use of the tags for the individual components follow below, together with examples and links to the available types of each component.

The [ai] Tag — Top-level Elements

AI configurations are set up and stored using the [ai] tag. It has the following top-level elements:

  • description="": (translatable string) This is the text displayed in the MP setup menu when choosing an AI for a computer player.
  • id="": (string) The id of the [ai] config snippet. This was originally meant to make it possible to remove [ai] configurations during a game. However, due to the merging process described above, this information is lost. The id is therefore meaningless in the current implementation of the AI.
  • version="": (string) [ Todo: Need to look into the C++ code for complete explanation ]
  • [stage]: Configuration of the stage(s) used in the AI. Several [stage] tags can be used, even several stages of the same type. They are executed in the order in which they are put into the [ai] tag.
  • [aspect]: Configuration of the aspects to be used by the AI. These are in composite aspect format.
    • Most aspects can also be provided using the simpler syntax explained at AiWML.
  • [goal]: Configuration of the goals to be used by the AI. These are in composite aspect format.
  • [engine]: This tag used to be needed for the Lua AI engine to set up the AI code. It is not needed any more. No information on its syntax is therefore provided below. If you need information on how this used to work, check out the legacy documentation.
  • formula="": (string) Formula AI code to be executed by the AI. We recommend not using this any more except for extremely simple AIs. See legacy documentation for more information.

The [ai] Tag — Stages

The [ai] tag can contain one or several stages defined in [stage] tags. If the AI configuration contains several stages, they are executed in the order in which they are put into the [ai] tag.

While there are six different types of stages available, all AI functionality possible in Wesnoth can be achieved using only a single one, the candidate action evaluation loop stage. In the default setup, this stage has id main_loop and we generally simply refer to it as the main_loop stage.

Other stages exist mostly for legacy reasons from the times in the AI development when the main_loop stage did not exist yet. They are currently still functional and kept for backward compatibility reasons, but they are not maintained any more and might be removed in a future Wesnoth release cycle. We therefore recommend that all custom AI development is done using the main_loop stage only.

main_loop Stage Configuration

For the main_loop stage, the [ai] tag contains the following elements:

  • name: This must be set to 'testing_ai_default::candidate_action_evaluation_loop', so that the AI knows that this is the main_loop stage.
  • id: (string) This is the identifier of the AI. It is usually set to 'main_loop', but can take on any value. It only matters if you are planning to remove or modify the stage during a scenario.
  • engine=cpp: (string) This must be set to 'cpp', which is also the default value. It can therefore be omitted.
  • [candidate_action]: Candidate action configuration tags. See below for details.

Notes:

  • As an example, the configuration of the main_loop stage in the default AI is shown here.
  • Candidate actions can be using any of the three available engines. Just because the stage uses the cpp engine does not mean that the CAs need to do so as well. See below for an example.
  • While that should rarely ever be necessary, it is possible to include several main_loop stage definitions in the same [ai] tag.
    • This is done by putting several [stage] tags into the same [ai] tag
    • The AI engine then evaluates the CAs of the first stage in the usual way, until no CA returns a valid score any more.
    • After the first stage is finished, it moves on to the second stage and repeats the process, until all stages have finished. This ends the AI turn.
    • Obviously, this only makes sense if the sets of CAs of the different stages are not identical (although individual CAs might appear in several stages).

Recruitment Stage

A recruitment stage exists. However, this stage is also used by the recruitment_instruction aspect. Anything that can be done with this stage can also be done with the recruitment candidate action using the recruitment_instruction aspect. It should therefore never be necessary to use this stage and we not describe it here.

Legacy Stages

Four other stages are also available. They do, however, not provide any new functionality any more these days, only different ways of achieving the same functionality that is also possible with the main_loop stage. We therefore only list them here for completeness, with brief examples and links to old documentation.

Note that both this documentation and the stages themselves might be removed at some point.

Lua stage

Executes Lua code by calling a function created inside a Lua engine. Whatever element is returned by the code in lua [engine], is accessible here as an upvalue. So, for example, (...):execute() calls whatever_is_returned_by_lua_engine:execute()

Example: 

[stage]
    engine="lua"
    code= "(...):execute()"
[/stage]

See legacy documentation.

Formula AI Side Formulas Stage

This stage executes a given Formula AI side formula.

Example: 

[stage]
    engine=fai
    name=side_formulas
    move="write_your_formula_here"
[/stage]

See legacy documentation.

Formula AI Unit Formulas Stage

This stage takes no parameters and executes all Formula AI formulas which are attached to units.

Example: 

[stage]
    engine=fai
    name=unit_formulas
[/stage]

See legacy documentation.

Fallback stage

Fall back to other, older AI.

Example: 

[stage] 
    id=fallback
    name=testing_ai_default::fallback
    [ai]
       ai_algorithm=default_ai
    [/ai]
[/stage]

This example shows how to set up a stage to fall back to the old default AI (the one used before the current default was introduced). This was useful when it was not clear yet how well the RCA AI would work and whether it would suddenly abandon the CA evaluation loop. There is really no reason to use a fallback stage any more these days.


The [ai] Tag — Candidate Actions

The main_loop stage (and only this stage) can contain an assortment of candidate actions. They are evaluated and executed in the manner explained above. This section explains how to configure the [candidate_action] tag that goes into the [stage] tag of the main_loop stage.

All three engines can, in principle, be used to write custom CAs. However, only the use of Lua CAs is recommended for this purpose. Using the cpp engine has the obvious problem of requiring changes to the Wesnoth source code. Formula AI CAs are discouraged for the same reasons why we do not recommend using Formula AI stages any more.

The [candidate_action] Tag

The [candidate_action] tag can contains the following keys:

  • engine: This key is required for Wesnoth to know with which engine the CA is to be processed. Possible values are 'cpp', 'lua' and 'fai'.
  • id: The id of the CA is, in principle, optional. However, it is needed if you want to remove or change the CA after its initial definition.
  • name: The CAs of the default AI are identified by their name, making this a required key for the cpp engine. The key is optional for other engines.
  • max_score: The maximum score the CA evaluation function might return. This parameter is optional, but it is useful to reduce the AI move evaluation time. During each iteration through the evaluation loop, the main_loop stage only evaluates CAs with max_score larger than that of the highest-scoring CA found so far during this iteration. For that same reason, it also makes sense to order CAs by decreasing max_score in the [stage] tag, even though that is not technically necessary.
  • score: (cpp engine only) The score returned by the CA. If this parameter is given, the score of the CA is fixed to this value.

In addition, Lua CAs also contain the following keys:

  • location: File name, including path, of the AI code for the CA.
  • eval_parms, exec_parms: The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a Lua table, without the outer curly brackets. They are passed to these functions as the second argument, cfg. (add link)

Notes:

  • There is also an old syntax for defining Lua CAs. However, this method requires the definition of a Lua engine using the [engine] tag. This is much less convenient than the current method without any advantages and will therefore be deprecated at some point in the future.
    • If you need information on the old syntax, check out the legacy documentation.
    • The current syntax was originally called external Lua CAs. However, as this has now become the standard, we drop the external and simply call them Lua CAs.
  • Formula AI CAs contain some additional keys. As we do not recommend using the fai engine any more, we do not describe this syntax here and refer to the legacy documentation instead.

Here are examples of [candidate_action] tag uses:

Combat CA of the default AI: 

[candidate_action]
    id=combat
    engine=cpp
    name=ai_default_rca::combat_phase
    max_score=100000
    score=100000
[/candidate_action]

Lua AI CA: 

[candidate_action]
    engine=lua
    name=return_guardian_bob
    id=return_guardian_bob
    max_score=100010
    location="~add-ons/my_addon/lua/return_guardian.lua"
    eval_parms="id = 'Bob', return_x = 10, return_y = 15"
    exec_parms="id = 'Bob', return_x = 10, return_y = 15"
[/candidate_action]

Available Candidate Actions

  • cpp engine: The available CAs of the default AI are given here.
  • lua engine: The Micro_AIs are written using Lua CAs and can either be used as they are or as templates for creating your own CAs. They can be found here.
  • fai engine: As we said above, we do not recommend using the fai engine any more for creating custom CAs. However, if you want to do so, a few simple Formula AI CAs can be found in the legacy documentation here.

The [ai] Tag — Aspects and Goals

Aspects and goals are read by the candidate actions of the default AI as parameters that can influence the AI behavior. Thus, for the most part, they only apply to CAs of the default AI. It is, however, possible to write Lua CAs which take them into account. For example, some of the Micro_AIs respect some of the default aspects.

A huge number of aspects is available for the default AI. They are therefore given their own page. Only the syntax and internal structure of the aspect configuration is shown here.

There are two types of syntax for defining aspects. The vast majority of aspects can be defined using a straight forward syntax of simply defining their values using keys or tags. These are usually referred to as standard, or sometimes simple, aspects. Examples are 

[ai]
    time_of_day=dawn
    aggression=0.765
[/ai]

or 

[ai]
    [avoid]
        terrain=W*
    [/avoid]
[ai]

For standard aspect syntax, several additional keys are available in addition to the aspect names themselves, time_of_day (as shown in the example above) turns, and ai_algorithm. These are also explained at AiWML.

By contrast, a few aspects cannot be defined in such a way and need a more complex structure. These are called composite aspects. AiWML points out when an aspect requires composite aspect syntax and how to do this. If it is not specifically stated, an aspect can be defined using standard aspect syntax.

This distinction between standard and composite aspect is only on the WML side though. Internally, the engine treats all aspects as composite and translates the standard aspect definition into a composite configuration snippet. As a result, any standard aspect can also be defined using composite syntax. That is useful, for example, if you want to remove a certain aspect at a later time. You can do that by assigning the aspect an id, which can then be used to remove the aspect.

Let's try to explain that using the aggression example from above. If we wanted to defined this using the composite aspect structure, it would look like this: 

[ai]
    [aspect]
        id=aggression
        [facet]
            id=custom_aggression # Can be used to remove this facet later
            time_of_day=dawn
            value=0.765
        [/facet]
    [/aspect]
[/ai]

[ Todo: are the engine= keys optional? ]

The most important part is that the composite aspect structure uses so-called facets, which contain the value of the aspect. If the aspect is a single scalar value, such as in this example, that value is assigned using the value key. If it is a tag, such as [avoid], the content of the tag is added inside a [value] tag. For example 

[facet]
    engine=cpp
    id=custom_avoid
    name=standard_aspect
    [value]
        terrain=W*
    [/value]
[/facet]

That’s it for the most practical purposes, but there a few more parameters in the full aspect configuration: 

[aspect]
    engine=cpp
    id=aggression
    invalidate_on_gamestate_change=no
    invalidate_on_minor_gamestate_change=no
    invalidate_on_tod_change_change=yes
    invalidate_on_turn_start=yes
    name=composite_aspect
    [facet]
        engine=cpp
        id=
        invalidate_on_gamestate_change=no
        invalidate_on_minor_gamestate_change=no
        invalidate_on_tod_change_change=yes
        invalidate_on_turn_start=yes
        name=standard_aspect
        time_of_day=dawn
        turns=
        value=0.765
    [/facet]
    [default]
        engine=cpp
        id=
        invalidate_on_gamestate_change=no
        invalidate_on_minor_gamestate_change=no
        invalidate_on_tod_change_change=yes
        invalidate_on_turn_start=yes
        name=standard_aspect
        time_of_day=
        turns=
        value=0.4
    [/default]
[/aspect]

[ Todo: this needs to be completed and cleaned up; are engine and name optional? ]

Thus, the full list of keys and tags inside the [aspect] tag is as follows:

  • engine:
  • id:
  • name:
  • invalidate_on_turn_start="yes": (boolean) If "yes", the value of this aspect is invalidated at the start of each AI turn.
  • invalidate_on_tod_change="yes": (boolean) If "yes", the value of this aspect is invalidated when the time of day changes (not working at the moment). This implies invalidate_on_turn_start.
  • invalidate_on_gamestate_change="no": (boolean) If "yes", the value of this aspect is invalidated on each game state change (on turn start, move, attack, recruit, etc.). This implies invalidate_on_turn_start.
  • invalidate_on_minor_gamestate_change="no": (boolean) If "yes", the value of this aspect is invalidated on each minor game state change (on set unit variable, etc). This implies invalidate_on_gamestate_change.
  • [facet] or [default]:

Aspects can contain a significant amount of additional information. For example, for the attacks aspect, it contains a list of all possible attacks of the filtered attacker/target unit pairs. This list, originally established at the beginning of the AI turn, is not valid any more after the first attack has been performed and needs to be reset. The AI does this by 'invalidating' the aspect, after which the aspect information is read anew from the [ai] tags and the stored information (the list of attacks, in this case) is reevaluated.

Thus, information stored about aspects is reevaluated by default at each AI turn and when the time of day changes. It is not reevaluated after the game state changes (such as after an attack), which explains why 'invalidate_on_gamestate_change=yes' needs to be set explicitly for the attacks aspect.

Hint: If unsure, the easiest way to see the full config for any given aspect (or any other AI component, in fact) is either in savefiles, or in-game by typing :inspect in debug mode and choosing 'ai config full' for a team.

Goals

Goals are simply a special type of aspect, so they are stored in configs in exactly the same way as shown above. The only difference from many of the other aspects is that they can never be defined by a single key=value pair. Thus, they are always composite aspects.

Retrieved from "https://wiki.wesnoth.org/index.php?title=Wesnoth_AI_Framework&oldid=57151"