Micro AIs

More information: Google Code-in Micro AI Tasks

The add-on AI Modification Demos contains a number of so-called Micro AIs (well, currently there are only three, 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 AI-Demos add-on is only supported for Wesnoth 1.11 any more. In time, fewer and fewer of the AIs (and Micro AIs) will function with Wesnoth 1.10.

Setting up a Micro AI

After installing the AI Modification Demos add-on, there are currently 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.

2. Setting up the Lua AI engine

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

    {MICRO_AI_HEALER_SUPPORT}

This does not yet activate any Micro AIs, but it is currently still necessary to define the Lua AI engine inside the side definition for the Micro AIs to work. This requirement will go away for one of the upcoming Wesnoth 1.11 releases.

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. A Micro AI that attaches to a unit, that is, a Behavior Candidate Action (BCA), generally has an ai_type ending with '_unit' (sometimes the '_unit' is added to another key, if several different AIs can be accessed by the given ai_type).

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.

Notes:

• Some of the Micro AIs use and/or modify default AI components (candidate actions or aspects) when they are added, or reset these components to their default values when they are deleted. Thus, if you have modified the AI yourself using the default CAs or aspects, some of these modifications might be affected, or might be interfering with the Micro AI. The sections below indicate whether a Micro AI changes any default AI components.

• It is currently not possible to combine different types of Micro AIs (AIs using different values of ai_type=) on the same side. In other words, you can use several guardians (and even different guardian types) on the same side (as they are all handled by the Guardian Micro AI), but it is not possible to put, for example, guardians and patrollers on the same side. This restriction will be lifted in an upcoming release. In the meantime, you will have to use different (allied) sides to accomplish this.

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.

Note: The Healer Support Micro AI modifies the attacks aspect.

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]

Messenger Escort Micro AI

The Messenger Escort Micro AI lets you define a set of waypoints on the map through which the AI will attempt to move to safely reaching it's last waypoint(goal). One unit is defined as a messenger, and the other units will escort the messenger.

For a demonstration, check out scenario "Messenger Escort" of the AI-Demos campaign.

Enable the Messenger Escort Micro AI by putting

{MICRO_AI_MESSENGER_ESCORT}

into the [side] tag and configure it by using

ai_type=messenger_escort

in the [micro_ai] tag.

Messenger Escort specific keys for the [micro_ai] tag:

Required keys:

• id: The id of the messenger. All other units with the AI will protect the messenger.
• waypoint_x,waypoint_y: Comma-spearated list of waypoint coordinates through which the messenger will go in the given order to reach it's goal, the the last pair of coordinates. If you want the messenger to go directly to the goal, simply enter a single x,y coordinate here. Note that the messenger does not have to get exactly to each waypoint (except for the final one), getting close to them is good enough.

Optional keys:

• enemy_death_chance=0.67: (float; ranging from 0 to 1) When a unit is adjacent to an enemy unit, if the probability of the enemy dying is greater than or equal to this value, then the unit will attack.
• messenger_death_chance: (float; ranging from 0 to 1) When a unit is adjacent to an enemy unit, if the probability of the unit dying is lesser than or equal to this value, then the unit will attack.

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

[micro_ai]
    side=2
    ai_type=messenger_escort
    action=add
    
    id=messenger
    waypoint_x=31,24,27,28
    waypoint_y=20,14,7,1
[/micro_ai]

Guardian Micro AI

The Guardian Micro AI defines a number of a guardian AIs. Guardians typically protect certain locations on the map. Different guardian AIs behave differently, some moving, some remaining in place. All Guardian AIs attach to a unit and only affect the moves of that particular unit. For details, see below.

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

Enable the Guardians Micro AI by putting

{MICRO_AI_GUARDIAN}

into the [side] tag. Configure using the [micro_ai] tag with ai_type as "guardian_unit". Different types of guardians are specified below.

Guardian types and their specific keys for the [micro_ai] tag:

Stationed Guardian:

The stationed guardian will remain at its station until an enemy unit enters its radius of defense. It will continuously attack any unit within this radius until there are no more, at which time it returns to its station.

Enemies will only be attacked if they enter within the radius from both the unit's station and guarded hex. Thus ensure that the guarded hex and the station are at most 2*radius hexes apart.

You can configure it using the micro_ai tag as follows (all keys are required):

• guardian_type: Must be "stationed_guardian"
• id: The ID of the unit to which this AI should be applied.
• radius: The maximum distance from its station that this unit will move to attack an enemy unit.
• station_x and station_y: The x and y position of the hex that the unit must take as its station (point to which it returns)
• guard_x and guard_y: The x and y position of the hex this unit is guarding

For example:

[micro_ai]
    side=1
    ai_type=guardian_unit
    action=add
  
    guardian_type=stationed_guardian   
  
    id=stationed1
    radius=4
    station_x,station_y=3,5
    guard_x,guard_y=4,5
[/micro_ai]

Coward:

The coward will remain where it is until an enemy unit enters its radius. It then run to the hex furthest from all enemies (ie with least distance sum to enemies). It also attempts to move towards the "seek" hex and away from the "avoid" hex (if specified).

You can configure it using the micro_ai tag as follows:

Required keys:

• guardian_type: Must be "coward"
• id: The ID of the unit to which this AI should be applied.
• radius: The distance that an enemy must be to "scare" the unit

Optional keys:

• seek_x and seek_y: The x and y position of the hex to seek
• avoid_x and avoid_y: The x and y position of the hex to avoid

For example:

[micro_ai]
    side=1
    ai_type=guardian_unit
    action=add
  
    guardian_type=coward
  
    id=coward1
    radius=4
    seek_x,seek_y=3,5
    avoid_x,avoid_y=4,5
[/micro_ai]

Return Guardian:

The return guardian moves towards the hex passed to it.

You can configure it using the micro_ai tag as follows:

Required keys:

• guardian_type: Must be "return_guardian"
• id: The ID of the unit to which this AI should be applied.
• return_x,return_y: The coordinate of the hex the unit returns to after each attack

For example:

[micro_ai]
    side=1
    ai_type=guardian_unit
    action=add
  
    guardian_type=return_guardian
  
    id=return1
    return_x,return_y=3,5
[/micro_ai]

Lurkers Micro AI

The Lurkers Micro AI defines a lurker battle AI. A lurker can move across most terrains but stop only on thoes that are explicitly defined. They always attack the weakest enemy within their reach from only explicitly defined terrains. If no enemy is in reach, the lurker does a random move instead.

For a demonstration, check out scenario "Swamp Lurkers" of the AI-Demos campaign.

Enable the Lurkers Micro AI by putting

{MICRO_AI_LURKERS}

into the [side] tag and configure it by using

ai_type=lurkers

in the [micro_ai] tag

Lurkers specific keys for the [micro_ai] tag:

Required keys:

• [lurkers]: Specifies which units of the side are to be controlled by the Lurker Micro AI. This is a Standard Unit Filter.
• [attack_terrain]: Specifies terrains from which the lurkers attack. This is a Standard Location Filter.

Optional keys:

• [wander_terrain]: Specifies terrains on which lurkers end there moves if there is no enemy in reach. This is a Standard Location Filter. If [wander_terrain] is not given, it defaults to [attack_terrain].
• stationary=no: (boolean) If set to yes, a lurker never moves if there is no enemy within attack range.

Protect Unit Micro AI

The Protect Unit Micro AI lets you define a location on the map where a chosen unit will attempt to move to safely. The chosen unit will stay away from enemy units, and stay close to friendly units. Other units with the AI will protect the chosen unit.

For a demonstration, check out scenario "Protect Unit" of the AI-Demos campaign.

Enable the Protect Unit Micro AI by putting

{MICRO_AI_PROTECT_UNIT}

into the [side] tag and configure it by using

ai_type=protect_unit

in the [micro_ai] tag.

Protect Unit specific keys for the [micro_ai] tag:

Required keys:

• [unit]: A separate [unit] tag is required for each protected unit(s). Each tag has required keys id=, goal_x=, goal_y= for each unit, see the example below. All units not described in a [unit] tag will protect this/these unit(s).

Optional keys:

• disable_move_leader_to_keep (boolean): If true, will prevent protected leaders from returning to their keep.

Note: The Protect Unit Micro AI modifies the attacks aspect. Depending on the parameters, it might also modify the move leader to keep candidate action.

Here's an example of the [micro_ai] tag usage from scenario "HttT: The Elves Besieged" of the AI-Demos campaign:

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

    [unit]
        id=Delfador
        goal_x,goal_y=1,2
    [/unit]
    [unit]
        id=Konrad
        goal_x,goal_y=1,1
    [/unit]

    disable_move_leader_to_keep=true
[/micro_ai]

Animals Micro AI

The Animals Micro AI defines a number of a animal AIs. Different animal AIs behave differently. For details, see below.

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

Enable the Animals Micro AI by putting

{MICRO_AI_ANIMALS}

into the [side] tag and configure it by using

ai_type=animals

in the [micro_ai] tag. The animal_type tag is used to choose from different animal AIs.

An example of the tag's usage:

1. Set up the hunter_unit micro AI

[micro_ai]
    # Required keys of [micro_ai] tag
    side=1
    ai_type=animals
    animal_type=hunter_unit
    action=add
    # Required keys of hunter_unit micro AI
    id=Rowck
    hunt_x,hunt_y="9-38","4-19"
    home_x,home_y=4,3
    rest_turns=2
[/micro_ai]

Animal types:

• hunter_unit: hunts in a specific area, then stays home for a specified time/until fully healed. This AI attaches to a unit, rather than controlling all units of a side.
• wolves: they hunt in a pack of arbitrary number of predators. Note: The Wolves Micro AI modifies the attacks aspect.
• wolves_multipacks: same as above but this AI supports an arbitrary number of units and this can't avoid specific types of enemies.
• big_animals: these just go to random places, avoid other big animals and stay at their preferred types of terrain.
• swarm: the animals in the side with this AI will try to stay together and avoid enemies.
• herding: this AI controls both the sheep and the dogs of a side. The dogs keep the sheep in a herd. This AI only requires the animal_type key in addition to the needed [micro_ai] keys.
• forest_animals: This AI controls a set of animals: tuskers, tusklets, rabbits.

Keys for the hunter_unit AI:

Required keys:

• id: The ID of the unit to which this AI should be applied.
• animal_type: This has to be "hunter_unit" (without quotation marks) if you want a hunter_unit AI.
• hunt_x: The x range of the area where the AI will wander.
• hunt_y: The y range of the area where the AI will wander.
• home_x: The x coordinate of the place where the AI will return.
• home_y: The y coordinate of the place where the AI will return.
• rest_turns: The number of turns the AI will stay at "home".

Optional keys:

• show_messages=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase

Keys of the wolves AI:

• animal_type: You have to set this to "wolves".
• avoid_type: The wolves will try to avoid creatures with these types. Optional.
• [predators]: A SUF WML tag. Required.
• [prey]: A SUF WML tag. Required.

Keys of the wolves_multipacks AI:

• animal_type: You have to set this to "wolves_multipacks". Required.
• type: the type of units the AI controls. The default value is "Wolf".
• pack_size: the size of the packs the units will hunt in. (default: 3)
• show_pack_number: if "yes", the wolves' pack numbers will be shown below them.

Keys of the big_animals AI:

Required keys:

• animal_type: You have to set this to "big_animals" if you want a big_animals AI.
• [big_animals]: SUF describing the animals of the side to which this AI is applied.
• [goal_terrain]: The terrain which the big animal will aim for. This is a Standard Location Filter.
• [wander_terrain]: The terrain which the big animal will wander on. This is a Standard Location Filter.
• [avoid_unit]: The units which the big animals will avoid. This is a Standard Unit Filter.

Optional keys of the swarm AI:

• scatter_distance=3: (int) Enemies within "scatter_distance" hexes of any swarm unit will cause the swarm to scatter.
• enemy_distance=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
• vision_distance=12: (int) Only units within this distance follow the overall swarm motion (either away from an enemy or of the swarm as a whole). The smaller this value is set, the less likely the swarm is to stay together or rejoin. Its meaning is that if the swarm is more than this distance away, it is "out of sight" and the unit will therefore not be able to follow it.

Required keys of the herding AI:

• [herd]: The units that are being herded. This is a Standard Unit Filter.
• [herders]: The units that are herding. This is a Standard Location Filter.
• herd_x,herd_y: The coordinate of the (approximate) herding area center.
• [herder_area]: The terrain of which the herders prefer. This is a Standard Location Filter.

Optional keys:

• attention_distance=8: (integer) The radius within which enemies must be to attract the attention of the herders.
• attack_distance=4: (integer) The radius within which enemies must be to be attacked by the herders.

Optional keys of the forest_animals AI:

• rabbits_number: The number of rabbits to be on the map.
• radius: Rabbits won't spawn in holes that aren't more than radius hexes away from enemies.
• rabbit_hole: The image/halo of the rabbit hole item.
• [move_filter]: The terrain the animals prefer to move on. This is a Standard Location Filter.
• rabbit_type: The unit types that should behave as rabbits.
• tusker_type: The unit types that should behave as tuskers.
• tusklet_type: The unit types that should behave as tusklets.
• other_types: The unit types that should behave as deers.

Patrol Micro AI

The Patrol Micro AI lets you define locations on the map where a unit will move in order in a loop. Optionally, attack targets can be specified, which the unit will attack if it ends up next to them.

For a demonstration, check out Goblin Handler Jabb in scenario "Patrols" of the AI-Demos campaign.

Enable the Patrol Micro AI by putting

{MICRO_AI_PATROL}

into the [side] tag and configure it by using

ai_type=patrol_unit

in the [micro_ai] tag.

NOTE: The [micro_ai] tag needs to be placed after the creation of the unit it controls in the scenario event.

Patrol specific keys for the [micro_ai] tag:

Required keys:

• id: The id of the patrol.
• waypoint_x,waypoint_y: The x and y-value(s) of the hex(es) of the waypoints(s), where the patrol will travel to in order.

Optional keys:

• attack: The id(s) of the attack target(s). The patrol will attack this/these unit(s) when it ends up next to them. If not specified, then all units are considered as enemies. This can in turn be used to have the patroller not attack at all, by setting attack= to a non-existing id.
• one_time_only=no: (boolean) If set to 'yes', the unit will only go through the patrol route once and then hang out at the last waypoint. In this case, it will also always attack an enemy unit on the last waypoint, whether that is specified by the other options or not.
• out_and_back=no: (boolean) By default, a patrol unit will return to the first waypoint after reaching the last. If this parameter is set, the unit will reverse course instead and perpetually do out and backs of the route.

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

[micro_ai]
    # Required keys of [micro_ai] tag
    side=3
    ai_type=patrol_unit
    action=add

    id=Goblin Handler Jabb
    waypoint_x=6,7,11,11
    waypoint_y=17,14,14,18
    attack=Jacques
[/micro_ai]

Recruiting Micro AI

The Recruiting Micro AI lets you use alternate recruitment strategies.

Currently there are two strategies you can choose from:

• random: recruits random units. The behavior when there is a little gold available has to be set through the low_gold_recruit tag (see below).
• rushers: this AI tries to simulate a player. It is used by the multiplayer AIs in the add-on.

You can check out the Recruiting scenario for a demo (side one uses the random recruit AI), or you can explore the unit choices by watching one of the experimental multiplayer AIs in the add-on.

Enable the Recruiting Micro AI by putting

{MICRO_AI_RECRUITING}

into the [side] tag and configure it by using

ai_type=recruiting

in the [micro_ai] tag.

Required keys:

• recruit_type: The type of the recruit AI. (This can be set to 'random' or 'rushers'.)

Optional keys:

• skip_low_gold_recruit=yes: (boolean) This describes the behavior of the random recruit AI when it's running out of gold. If set to 'yes', it will skip recruiting when a unit was selected randomly that is too expensive, but when affordable units are still available. If set to 'no' (default), the AI recruits cheaper units instead of nothing. Only applicable to the random recruit AI.
• [probability]: requires type and probability subtags.

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