Micro AIs

Mirco AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code. Note that this is a new functionality and theat we are very much looking for feedback on bugs, new feature requests for the existing AIs or ideas for new Micro AIs.

Micro AIs are available in mainline Wesnoth starting from Version 1.11.2. Additional AIs that are still in an experimental stage are available in the AI Modification Demos add-on, which also might contain more advanced (development) versions of the mainline Micro AIs.

1 A Few General Words about Micro AIs
- 1.1 Micro AI Test and Demo Scenarios
2 Setting up a Micro AI
- 2.1 1. Enabling the Micro AI functionality in the [side] tag
- 2.2 2. Activating and configuring (or deleting) a Micro AI
3 Animals Micro AI (ai_type=animals)
4 Bottleneck Defense Micro AI (ai_type=bottleneck_defense)
- 4.1 Bottleneck Defense specific keys for the [micro_ai] tag:
5 Guardian Micro AI (ai_type=guardian_unit)
6 Healer Support Micro AI (ai_type=healer_support)
- 6.1 Healer Support specific keys for the [micro_ai] tag:
7 Lurkers Micro AI (ai_type=lurkers)
- 7.1 Lurkers specific keys for the [micro_ai] tag:
8 Messenger Escort Micro AI (ai_type=messenger_escort)
- 8.1 Messenger Escort specific keys for the [micro_ai] tag:
9 Patrol Micro AI (ai_type=patrol_unit)
- 9.1 Patrol specific keys for the [micro_ai] tag:
10 Protect Unit Micro AI (ai_type=protect_unit)
- 10.1 Protect Unit specific keys for the [micro_ai] tag:
11 Recruiting Micro AI (ai_type=recruiting)
- 11.1 Random Recruitment AI (recruiting_type=random)
- 11.2 Rush Recruitment AI (recruiting_type=rushers)
12 Other Potential Micro AIs

A Few General Words about Micro AIs

Micro AIs are meant to bring new specialized behavior to Wesnoth that cannot be achieved, at least not easily, by adjusting default AI parameters (such as those described at AiWML) or with WML code.

Most Micro AIs in their default setting apply to all units of a side, although many of them provide parameters for filtering the units that should be affected by the new behavior. If the Micro AI is applied only to part of the units of a side, the other units follow the default Wesnoth AI behavior.

By contrast, a few Micro AIs attach directly to a unit and only affect that unit's behavior. These are so-called Behavior Candidate Actions (BCAs). This type of Micro AI has an ai_type= value ending in _unit, in order to distinguish it from the side-wide Micro AIs.

Micro AI Test and Demo Scenarios

All Micro AIs described here can be checked out in a number of test and demo scenarios. Test scenarios can be accessed from the command line by typing

path/wesnoth-executable -t micro_ai_test

This starts up a "switchboard scenario" in which you can select the Micro AI demonstration scenario you want to check out. Here, path/wesnoth-executable needs to be replaced by whatever the path and filename of the Wesnoth executable is on your system.

Another way to test the Micro AIs (as well as some other AIs still under development) is to download the AI Modification Demos add-on. All the test/demo scenarios are also available there.

Setting up a Micro AI

Setting up a Micro AI is done in two simple steps:

1. Enabling the Micro AI functionality in the [side] tag

The desired AI functionality needs to be enabled for a side before it can be used. This is done by including a single macro line inside the [side] tag, such as:

    {MICRO_AI_HEALER_SUPPORT}

The exact macro name depends on the specific Micro AI and is given below for each AI. This macro must be put directly into the [side] tag, it does not go inside an [ai] tag. This step does not yet activate the Micro AI, it simply sets up the desired functionality.

2. Activating and configuring (or deleting) a 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]

All [micro_ai] tags must contain the following three (or four) required keys:

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.
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.
id: If the Micro AI attaches directly to a unit, rather than being side-wide, the id of the unit is also a required parameter.

Other keys may also be required depending on the Micro AI. In additional, a number of optional keys may be available to configure the AI behavior. See the following sections on the individual Micro AIs for details.

Notes:

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 (or four) required keys listed here.

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 modifies any default AI components.

It is currently not possible to combine different Micro AI types (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.

Animals Micro AI (ai_type=animals)

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:

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.

Bottleneck Defense Micro AI (ai_type=bottleneck_defense)

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 the "Bottleneck" scenario from the test scenario or in the AI Modification Demos add-on.

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 (can 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.

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).

As an example, in the "Bottleneck" scenario of the test scenario, 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 by using the following keys settings (check out the scenario to see which hex is which):

[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]

Guardian Micro AI (ai_type=guardian_unit)

The Guardian Micro AI attaches to an individual unit and can be used to set up different kind of guardian behaviors. Three different types of guardians are available and are described below.

Multiple guardian units can be used on the same side, by setting up a separate [micro_ai] tag for each unit.

For a demonstration of several different guardian behaviors, check out the "Guardians" scenario from the test scenario or in the AI Modification Demos add-on.

Enable the Guardians Micro AI by putting

{MICRO_AI_GUARDIAN}

into the [side] tag and configure it by using

ai_type=guardian_unit

in the [micro_ai] tag. The guardian_type= key also needs to be set, as shown in the following.

Return Guardian (guardian_type=return_guardian)

A 'return guardian' is a variation of the standard Wesnoth guardian. It has an assigned guard position (GP) to which it returns after attacks on approaching enemies:

If at GP with no enemy in reach, do nothing.
If at GP with an enemy in reach, attack (note that the attack is done by default AI, which might result in the guardian not attacking if the enemy is deemed too strong).
If not at GP, return there, no matter whether an enemy is in reach or not.
If enemies are blocking the way back to GP, do your best to move around them.
If the guardian ends up next to an enemy on the way back, attack that enemy after the move.

You can configure each return guardian using the following keys in the [micro_ai] tag:

Required keys:

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

Optional keys:

There are no optional keys.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" test scenario:

        [micro_ai]
            side=2
            ai_type=guardian_unit
            action=add
            id=return1

            guardian_type=return_guardian
            return_x,return_y=20,2
        [/micro_ai]

Stationed Guardian (guardian_type=stationed_guardian)

A 'stationed guardian' is another variation of the standard Wesnoth guardian with a somewhat more complex behavior than that of the 'return guardian'. Two positions are defined for it, a 'station' and a 'guarded location', as well as a distance. The behavior is as follows:

If no enemy is within 'distance' of the guard's current position, do nothing. This is independent of the guardian being at its station or not.
Otherwise: If an enemy is within 'distance' of the guard, but not also within the same distance of the guarded location and the station (all of this simultaneously), move the guard in the direction of the station.
Otherwise:
- Pick the enemy unit that is closest to the guarded location.
- If we can reach it, pick the adjacent hex with the highest defense rating and attack from there.
- If not in reach, move toward this unit.

You can configure each stationed guardian using the following keys in the [micro_ai] tag:

Required keys:

guardian_type: Must be "stationed_guardian"
id: The ID of the unit to which this AI should be attached
distance: The distance parameter as explained above
station_x,station_y: The x and y position of the hex that serves as the guardians station.
guard_x, guard_y: The x and y position of the guarded location.

Optional keys:

There are no optional keys.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" test scenario:

        [micro_ai]
            side=2
            ai_type=guardian_unit
            action=add

            guardian_type=stationed_guardian
            id=stationed1
            distance=4
            station_x,station_y=2,14
            guard_x,guard_y=3,13
        [/micro_ai]

Coward (guardian_type=coward)

Cowards are units that, like guardians, sit around doing nothing until an enemy comes into range. Unlike guardians, however, they run away once enemies approach. Applications might be wild animals, unarmed civilians getting in the way of a battle, etc. The coward macro can be called with two optional locations, 'seek' and 'avoid':

If neither is given, the coward retreats to the position farthest away from the approaching enemies.
If 'seek' is given, it preferentially goes toward that location (but getting away from enemies takes priority).
If 'avoid' is given, it in addition tries to avoid that location (with both maximizing distance from enemies and going toward 'seek' taking priority).
Both 'seek' and 'avoid' may consist of only one coordinate ('x' or 'y'), in which case not a single hex, but a line of hexes is sought or avoided.

You can configure each coward using the following keys in the [micro_ai] tag:

Required keys:

guardian_type: Must be "coward"
id: The ID of the unit to which this AI should be attached
distance: The distance within which an enemy must be to "scare" the unit

Optional keys:

seek_x, seek_y: The x and y coordinate of the hex to seek
avoid_x, avoid_y: The x and y coordinate of the hex to avoid

Here's an example of a coward [micro_ai] tag usage from the "Guardians" test scenario:

        [micro_ai]
            side=2
            ai_type=guardian_unit
            action=add
            id=coward3

            guardian_type=coward
            distance=5
            seek_x,seek_y=24,5
            avoid_x,avoid_y=24,15
        [/micro_ai]

Healer Support Micro AI (ai_type=healer_support)

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. Note that it is not always better to use this Micro AI than the default AI, as it takes healers (which can be strong units) away from the pool of units to choose for attacks.

For a demonstration, check out the "Healers" scenario from the test scenario or in the AI Modification Demos add-on.

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:

Required keys:

There are no required keys.

Optional keys:

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: (boolean) If set to 'yes', 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.

This is an example of a Healer Support Micro AI configuration:

        [micro_ai]
            side=2
            ai_type=healer_support
            action=add
            aggression=0
        [/micro_ai]

Lurkers Micro AI (ai_type=lurkers)

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.

Messenger Escort Micro AI (ai_type=messenger_escort)

The Messenger Escort Micro AI lets you define a set of waypoints through which it tries to move one of its units, the messenger. The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that the messenger might not strictly hit intermediate waypoints, but that getting close is good enough, especially if a waypoint is occupied by an enemy unit. It does, however, always try to get to the last waypoint.

For a demonstration, check out the "Messenger" scenario from the test scenario or in the AI Modification Demos add-on.

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 of the side protect the messenger.
waypoint_x,waypoint_y: Comma-separated list of waypoint coordinates through which the messenger will go in the given order to reach its goal, given by the last coordinate. 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 hit each waypoint exactly (except for the final one), getting close to them is good enough.

Optional keys:

enemy_death_chance=0.67 and messenger_death_chance=0.0: (both floats; ranging from 0 to 1) If the messenger is adjacent to an enemy at the end of the move, it will only attack the enemy if the chance of death of the enemy is >= enemy_death_chance and if the messenger's chance of death is <= messenger_death_chance (or if it is an attack at a range for which the enemy does not have a weapon).

Here's an example of [micro_ai] tag usage from the "Messenger Escort" test scenario:

        [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]

Patrol Micro AI (ai_type=patrol_unit)

The Patrol Micro AI attaches to an individual unit and defines a number of waypoints for that unit to follow. Options can be set whether the route should be followed in a loop, as an out-and back, only once, whether units encountered along the way should be attacked, etc.

No matter what options are chosen, getting to the next waypoint always takes priority over attacking for a patroller. The AI thus prefers to move the patrol unit around enemies rather than straight for them. Also, if a waypoint is occupied by a unit the AI is not instructed to attack, it will (eventually) abandon that waypoint once it gets close enough and move on to the next one.

Multiple patrol units can be used on the same side, by setting up a separate [micro_ai] tag for each unit.

For a demonstration of several different patrol behaviors, check out the "Patrols" scenario from the test scenario or in the AI Modification Demos add-on.

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 unit.
waypoint_x,waypoint_y: Comma-separated lists of the waypoint coordinates through which the patrol travels (in order).

Optional keys:

out_and_back=no: (boolean) By default, a patrol unit returns to the first waypoint after reaching the last, doing the patrol route as a loop. If this parameter is set to 'yes', the unit instead reverses its course and perpetually does out and backs of the route.
one_time_only=no: (boolean) If set to 'yes', the unit goes through the patrol route only once and then hangs out at the last waypoint. It also always attacks any enemy unit on the last waypoint, independent of what attack= is set to.
attack: By default (if this key is not set), the patrol unit attacks any unit it ends up next to after a move. Alternatively, this parameter can be set to a comma-separated list of unit ids. If that is done, the patrol only attacks these units when it ends up next to them and ignores any other unit. This can in turn be used to have the patroller not attack at all, by setting attack= to a non-existing id.

Here's an example of the [micro_ai] tag usage from the "Patrols" test scenario:

        [micro_ai]
            side=2
            ai_type=patrol_unit
            action=add

            id=Konrad
            waypoint_x=9,24,25
            waypoint_y=21,23,15
            one_time_only=yes
            attack=Gertburt
        [/micro_ai]

Protect Unit Micro AI (ai_type=protect_unit)

The Protect Unit Micro AI tries to move one or several units to a given location while keeping them safe from enem attacks. It does so by keeping the protected units away from enemy units and close to friendly units. Other units on the AI side are controlled by the default Wesnoth AI.

For a demonstration, check out the "Protect Unit" and "The Elves Besieged" scenarios from the test scenario or in the AI Modification Demos add-on.

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, as shown in the example below.

Optional keys:

disable_move_leader_to_keep=no: (boolean) If set to 'yes', side leaders protected by this AI do not try to return to their keep. This is necessary for this Micro AI to work with units that are side leaders and that are supposed to move to an off-keep location.

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 [micro_ai] tag usage from the "HttT: The Elves Besieged" test scenario:

        [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]

Recruiting Micro AI (ai_type=recruiting)

The Recruiting Micro AI replaces the default recruitment AI by alternative recruiting patterns. Currently there are two recruiting algorithms you can choose from, random recruiting and the rush recruiting used in the new (as of Version 1.11.1) Experimental AI (see below).

For a demonstration of a different recruiting pattern, check out the "Recruiting" scenario from the test scenario or in the AI Modification Demos add-on. You can also explore the unit choices by watching the Experimental AI in a multiplayer game.

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.

Random Recruitment AI (recruiting_type=random)

This AI randomly selects a unit type from the recruitment list of the side. The probability of choosing each type and the behavior in low-gold situations can be influenced with optional parameters.

Required keys:

recruiting_type: Must be "random"

Optional keys:

[probability]: This tag sets the probability of selecting the given unit type. It has two required sub-keys:
- type: comma-separated list of unit types to which this probability is to be applied
- probability: (non-negative float) The probability with which these unit types is to be selected. All unit types for which no [probability] tag is defined receive a default probability of 1.0, thus values should be chosen relative to that. As an example, in the code below swordsmen and peasants are given a probability of 8, while no other units have assigned probabilities. Thus, each of these two unit types is 8 times more likely to be selected than any other individual unit type.
skip_low_gold_recruit=no: (boolean) By default, the random recruitment AI chooses a unit to recruit only from those types for which it has sufficient gold. If this parameter is set to 'yes', it will instead choose from all available unit types and end recruiting for the turn if there is not enough gold to recruit it this turn (even if other, affordable unit types exist).

Here's an example of a random recruiting [micro_ai] tag usage from the "Recruiting" test scenario:

        [micro_ai]
            side=1
            ai_type=recruiting
            recruiting_type=random
            action=add

            [probability]
                type=Swordsman,Peasant
                probability=8
            [/probability]

            skip_low_gold_recruiting=yes
        [/micro_ai]

Rush Recruitment AI (recruiting_type=rushers)

This AI replaces the default recruiting with the rush recruiting used in the new (as of Version 1.11.1) Experimental AI.

Required keys:

recruiting_type: Must be "rushers"

Optional keys:

There are no optional keys.

Rush recruiting is set up like this:

        [micro_ai]
            side=1
            ai_type=recruiting
            action=add
            recruiting_type=rushers
        [/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)
Orderly retreat

Micro AIs

Contents

A Few General Words about Micro AIs

Micro AI Test and Demo Scenarios

Setting up a Micro AI

1. Enabling the Micro AI functionality in the [side] tag

2. Activating and configuring (or deleting) a Micro AI

Animals Micro AI (ai_type=animals)

Keys for the hunter_unit AI:

Keys of the wolves AI:

Keys of the wolves_multipacks AI:

Keys of the big_animals AI:

Optional keys of the swarm AI:

Required keys of the herding AI:

Optional keys of the forest_animals AI:

Bottleneck Defense Micro AI (ai_type=bottleneck_defense)

Bottleneck Defense specific keys for the [micro_ai] tag:

Guardian Micro AI (ai_type=guardian_unit)

Return Guardian (guardian_type=return_guardian)

Stationed Guardian (guardian_type=stationed_guardian)

Coward (guardian_type=coward)

Healer Support Micro AI (ai_type=healer_support)

Healer Support specific keys for the [micro_ai] tag:

Lurkers Micro AI (ai_type=lurkers)

Lurkers specific keys for the [micro_ai] tag:

Messenger Escort Micro AI (ai_type=messenger_escort)

Messenger Escort specific keys for the [micro_ai] tag:

Patrol Micro AI (ai_type=patrol_unit)

Patrol specific keys for the [micro_ai] tag:

Protect Unit Micro AI (ai_type=protect_unit)

Protect Unit specific keys for the [micro_ai] tag:

Recruiting Micro AI (ai_type=recruiting)

Random Recruitment AI (recruiting_type=random)

Rush Recruitment AI (recruiting_type=rushers)

Other Potential Micro AIs