Micro AIs

The add-on AI Modification Demos contains a number of so-called Micro AIs (well, currently there are only two, but the goal is to add more). Mirco AIs add specific functionalities to a side's AI that can be added to a scenario easily using only a few lines of WML code. Adding (or deleting) a Micro AI is done via the [micro_ai] tag, which also lets the campaign designer configure the AI behavior to the specific need of the scenario.

Note that the current Micro AIs are written for Wesnoth 1.10 in order to maximize the number of people that can give feedback on the AI behaviors. They should work in Wesnoth 1.11 as well (please report if you find that they don't), but they don't make use of the new features of the development version (yet).

Setting up a Micro AI

After installing the AI Modification Demos add-on, there are currently (for Wesnoth 1.10) three steps required to set up a Micro AI:

1. Making the Micro AIs and [micro_ai] tag available in your add-on

The following line needs to be added to your _main.cfg file, inside the #ifdef for your campaign:

{~add-ons/AI-demos/micro_ais/activate_micro_ais.cfg}

This loads the required AI files and sets up the [micro_ai] tag.

Note: If the Micro AIs were ever mainlined (in BfW 1.16 or so), this would not be needed any more, of course.

2. Setting up the Lua AI engine

Add the following line (the exact macro name depends on the specific Micro AI - see below for the available Micro AIs and respective macro names) to the [side] tag of the side that should use the Micro AI:

    {MICRO_AI_HEALER_SUPPORT}

This does not yet activate any Micro AIs, but in Wesnoth 1.10 it is necessary to define the Lua AI engine inside the side definition, thus the need for this line. This requirement will go away for Wesnoth 1.11 making this step unnecessary. Note, however, that the current version of the add-on does not make use of this yet so as to be compatible with Wesnoth 1.10, so this line is currently required even if you are using Wesnoth 1.11.

3. Activating and configuring the Micro AI

Micro AIs are activated, deleted and configured using the [micro_ai] tag. This tag needs to be placed in ActionWML, that is, in an event, a menu option or the like. As an example, the following code activates the healer_support Micro AI in its default configuration for Side 2 from the beginning of the scenario:

    [event]
        name=prestart

        # Configure the healer support micro AI
        [micro_ai]
            side=2
            ai_type=healer_support
            action=add
        [/micro_ai]
    [/event]

For the full syntax of the [micro_ai] tag and the available Micro AIs, see the next sections.

The [micro_ai] Tag

The [micro_ai] tag activates, deletes and configures the Micro AIs for use in a scenario. It needs to be placed in ActionWML and must contain the following three required keys:

• action (string): The action to take concerning the Micro AI. The following values are allowed:
  • add: Add a Micro AI to a side.
  • change: Change the configuration of an existing Micro AI. Note that this does not only change the specific parameters provided in the tag, but it replaces the entire existing Micro AI by a new version with the new (and only the new) configuration. It is therefore equivalent to using first the delete and then the add action.
  • delete: Delete an existing Micro AI from a side.
• side: The side for which the Micro AI is to be added, changed or deleted
• ai_type: The type of Micro AI to be added, changed or deleted. See the following sections for allowed values.

If no other keys are given, the Micro AI is set up in its default configuration when using the add and change actions. Additional keys allowed for each Micro AI are listed below. The add and change actions ignore all keys that do not apply to the respective Micro AI type. The delete action ignores all keys other than the three listed above.

Healer Support Micro AI

The Healer Support Micro AI configures the healers of a side to stay behind the battle lines and heal injured and/or threatened units rather than participate in combat under all circumstances. You can set different levels of aggressiveness for the healers, from "never attack" to "only heal if you cannot attack" (not all implemented yet).

For a demonstration, check out scenario "Healer Support" of the AI-Demos campaign.

Enable the Healer Support Micro AI by putting

{MICRO_AI_HEALER_SUPPORT}

into the [side] tag and configure it by using

ai_type=healer_support

in the [micro_ai] tag.

Healer Support specific keys for the [micro_ai] tag:

• aggression=1.0: (float) Sets the aggressiveness of the AI. This parameter is set up as a float to accommodate future functionality, but it currently acts as a boolean: if set to zero, the AI will never let its healers participate in combat, for all other values it allows them to attack after all other units have attacked and if the healers cannot find any more units to support. The former behavior might be appropriate in scenarios with only one or few valuable healers, while the latter might work better in scenarios with many healers.
• injured_units_only=no/false: (boolean) If set to 'yes' or 'true', the AI will only move healers next to units that are already injured and skip units that currently have full hitpoints, but might get injured during the next enemy turn.
• max_threats=9999: (integer) The maximum allowable number of enemies that can attack a hex in order for it to be considered for a healer. As an example, setting 'max_threats=0' means that the AI only moves healers to locations that are entirely safe from the enemy (assuming that none of the units currently on the map dies). Note that the value of this key is checked against the number of enemies that can make it to the hex, not the number of adjacent hexes from which the healer could be attacked.

Bottleneck Defense Micro AI

The Bottleneck Defense Micro AI lets you define a location on the map where the AI can take a defensive stance behind a narrow passage (bottleneck). Units on the front line are backed up by healers and/or units with the leadership ability. Injured units are moved to the back and replaced by uninjured (or less injured) units. The units on the front line only attack when it is safe (no retaliation) or when there is a high chance that they will make a kill or level up. Using this Micro AI only makes sense if there is no way for the enemy sides to move around the bottleneck and attack the AI's units from behind.

For a demonstration, check out scenario "Bottleneck Defense" of the AI-Demos campaign.

Enable the Bottleneck Defense Micro AI by putting

{MICRO_AI_BOTTLENECK_DEFENSE}

into the [side] tag and configure it by using

ai_type=bottleneck_defense

in the [micro_ai] tag.

Bottleneck Defense specific keys for the [micro_ai] tag:

Required keys:

The Bottleneck Defense AI requires two sets of coordinates that define where it should be taking up its defensive stance, and from which side the enemy attacks at that location.

• x,y: Comma separated lists of the hexes on the front line, where strong units are placed. All hexes on which the AI makes contact with (be attacked by) the enemy need to be included here. Units are placed on them in the order in which they are listed here.
• enemy_x,enemy_y: Comma separated list of the hexes from which the enemy can attack the AI front line units. This is needed for the AI to know on which side of the front line support units (healers etc.) need to be placed. In many cases, it is sufficient to provide only one of the enemy front line hexes, but there are geometries for which that does not work. It is therefore safer to list all enemy front line hexes here.

Optional keys:

By default, the AI places healers and units with the leadership ability both on the front line itself (if they are the strongest units available) and on hexes adjacent to and behind the line. If different placement is desired, these locations can be overridden with the following keys.

As an example, in the Bottleneck Defense scenario of the AI-Demos add-on, there are three front line hexes, two of which are on hill terrain, while the third is a road with a lower defense rating. The healer and side leader are supposed to participate in combat because they are strong units, but only from the hill hexes to keep them safer. This is accomplished but using the following keys (see code example below):

• healer_x,healer_y: Comma separated list of hexes where healers are placed. This can be used to keep healers from the front line (or to take up only certain positions on the front line), and/or to override the default healing positions behind the line. Healers are placed on them in the order in which the hexes are listed, with the exception that hexes on the line always take priority over hexes behind the line.
• leadership_x,leadership_y: Same as healer_x,healer_y, but for units with the leadership ability.
• active_side_leader=no: (boolean) If set to 'yes', the side leader participates in the bottleneck defense action after the side's gold has been spent. If set to 'no' (default), the leader follows default AI behavior (sitting on the keep and recruiting, for the most part).

Here's an example of the [micro_ai] tag usage from scenario "Bottleneck Defense" of the AI-Demos campaign:

[micro_ai]
    # Required keys of [micro_ai] tag
    side=1
    ai_type=bottleneck_defense
    action=add

    # Required keys of Bottleneck Defense Micro AI
    x=14,14,14
    y= 7, 9, 8
    enemy_x=13,13
    enemy_y= 8, 9

    # Optional keys of Bottleneck Defense Micro AI
    healer_x=14,14,15,15
    healer_y= 7, 9, 8, 9
    leadership_x=14,14,15,15
    leadership_y= 7, 9, 9 ,8
    active_side_leader=yes
[/micro_ai]

Other Potential Micro AIs

The following Micro AIs might be added at some point. Feel free to add to this list, if you have other ideas.

• Leader support
• Targeted enemy poisoning
• Protect unit/location/area
• Annoying AI (grab targets and avoid fights as much as possible)
• Hunter AI (e.g. wolves)
• Orderly retreat