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.

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.

• The default AI aspects are, for the most part, not taken into account by the Micro AIs. For example, unless noted otherwise, specifying a value for 'aggression' does not change the MAI behavior, and locations specified in an '[avoid]' tag generally can be entered by units controlled by an MAI. This is a feature of the Micro AIs, not a bug. If you feel that a certain default AI aspect should also apply to a Micro AI, please let us know in the Micro AIs Feedback thread.

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

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.

Setting up a Micro AI

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

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

This step is not needed any more as of Wesnoth 1.11.7

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.

Note: It is not possible to combine different Micro AI types (AIs using different values of ai_type=) for the same side with this method, by using several macros in the same [side] tag. In other words, you can use several patrollers on the same side (as they are all handled by the Patrol Micro AI), but with this method it is not possible to put, for example, guardians and patrollers on the same side. If you want to do that, see Combining Different Micro AI Types below for the syntax to be used.

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]

Keys required for all Micro AIs: All [micro_ai] tags must contain the following three required keys:

• side: The side for which the Micro AI is to be added, changed or deleted. This has to be an individual side number, lists of sides are not supported.
• 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.

Keys required under certain circumstances:

• 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. The description of each Micro AI lists whether this key is required. Only required for Wesnoth 1.11.6 and earlier.
• ca_id: (string) Starting with Wesnoth 1.11.6: If several MAIs of the same type are used for the same side and one or several of these are to be changed or deleted during a scenario, this key needs to be included so that the [micro_ai] tag knows which of them needs to be changed/deleted. Notes:
  • The id(s)/name(s) actually assigned to the CA(s) of the MAI by the engine might be different from the parameter passed here. It is, however, sufficient to use this ca_id with the [micro_ai] tag add/delete/change actions to identify the MAI uniquely. (In other words: you don't have to worry about this if you always use the [micro_ai] tag, but might have to figure out the actual name(s) of the CA(s) if you want to delete or change them manually.)
• 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.

Required keys for deleting a Micro AI:

Only a subset of the required keys are needed when deleting a Micro AI. side, ai_type and action=delete always need to be provided. In addition, id is required if this is a Micro AI that attaches to a unit and ca_id needs to be given if it was provided when setting up the Micro AI. Finally, if the Micro AI consists of a set of different types of AIs (such as Animals or Guardian), the parameter specifying the type (e.g. animal_type or guardian_type) also needs to be given. [The crossed-out parts only apply to Wesnoth 1.11.6 and earlier.] In all cases, an error message will be displayed if a required parameter is missing.

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 required keys listed above.

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

Combining Different Micro AI Types for the Same Side

Starting with Wesnoth 1.11.7 no extra steps need to be taken any more to combine Micro AIs on the same side. Simply set up the [micro_ai] tags for all AIs you want to use.

Notes:

• While it is technically possible to combine any number of Micro AIs in this way, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways. Also, not all combinations that should work have been tested yet. If you find a combination that you believe should work but doesn't, please let us know and we will see if that can be fixed.
• The candidate action score almost certainly has to be set (using the ca_score= key) for one or several of the MAIs if several of them are used on the same side.

Starting with Wesnoth 1.11.6 it is possible to use different types of Micro AIs for the same side. For example, in order to use both the Patrol and Zone Guardian Micro AIs, you need to put the following code into the [side] tag (example from the "Patrols" test scenario):

        [ai]
            version=10710
            [engine]
                name="lua"
                code= <<
                    local ai = ...
                    local engine = {}
                    engine = wesnoth.require("ai/micro_ais/ais/mai_patrol_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_zone_guardian_engine.lua").init(ai, engine)
                    return engine
                >>
            [/engine]
            {RCA_STAGE}
        [/ai]

You can then use [micro_ai] tags with both 'ai_type=patrol' and 'ai_type=zone_guardian'.

Notes:

• This is a temporary syntax. Eventually, it will not be necessary to include any code at all in the [side] tag. This requires a change to the base AI functionality that does not yet exist. We will update this page as soon as that is done. [Update: this has now been implemented for Wesnoth 1.11.7]
• The exact syntax for the different Micro AI engines is as follows:

                    engine = wesnoth.require("ai/micro_ais/ais/mai_bottleneck_defense_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_goto_engine.lua").init(ai, engine)

                    engine = wesnoth.require("ai/micro_ais/ais/mai_hang_out_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_healer_support_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_lurkers_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_messenger_escort_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_patrol_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_protect_unit_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_recruit_engine.lua").init(ai, engine)

• The following engine files have been added starting from Wesnoth 1.11.7

                    engine = wesnoth.require("ai/micro_ais/ais/mai_big_animals_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_wolves_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_herding_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_hunter_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_forest_animals_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_swarm_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_wolves_multipacks_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_coward_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_return_guardian_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_stationed_guardian_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_zone_guardian_engine.lua").init(ai, engine)

• The following engine files have been removed starting from Wesnoth 1.11.7

                    engine = wesnoth.require("ai/micro_ais/ais/mai_animals_engine.lua").init(ai, engine)
                    engine = wesnoth.require("ai/micro_ais/ais/mai_guardian_engine.lua").init(ai, engine)

Animals Micro AI

Important Note: The syntax for the Animals Micro AIs has changed as of Wesnoth 1.11.7

The animal_type= parameter has been eliminated and is taken care of by the ai_type= parameter. The descriptions below are for current trunk (and for 1.11.7 as the first released version). If you are using Wesnoth 1.11.6 or earlier, use ai_type=animals and animal_type= with the latter set to the ai_type values listed below. As an example, the syntax as of 1.11.7 is

ai_type=swarm

For previous versions this should be

ai_type=animals
animal_type=swarm

Also, for Wesnoth 1.11.6 and earlier all Animals Micro AIs were enabled by putting

{MICRO_AI_ANIMALS}

into the [side] tag. Now no engine macro is needed any more.

General Comments on the Animal Micro AIs

The Animals Micro AIs are meant to simulate the behaviors of certain types of animals. They are, however, set up so that they can be used with arbitrary unit types and might be applicable in quite diverse situations. The AIs nevertheless remain named after the animals for which they were written originally, so that they are (to some extent) descriptive of their behavior.

Brief descriptions of the AI behaviors are given in the following subsections. To get a better feeling for their behavior, check out the "Animals", "Swarm", "Wolves" and "Dragon" scenarios from the test scenario. Note that some of the animal AIs are designed for animal types that do not exist in mainline. In the test scenario, other animal types are therefore substituted for them.

Animals AI: Wolves (ai_type=wolves)

The Wolves Micro AI organizes all "wolf" units (predators) of the side to hunt in a single pack. They actively chase after the closest prey and try to corner it (not always super successfully), but are easily distracted by other prey coming into range, to the point where the pack splits up. The wolves can also be told to try to avoid other types of units (such as larger predators), except when they are going in for an attack. When no prey is left, the wolves wander randomly.

This AI works best for a small number of predators (2 - 5) and sparse prey. Also, the predators should be put on the map in a pack, that is, reasonably close to each other. For a demonstration of the Wolves AI behavior, check out the "Animals" scenario from the test scenario.

Note that another wolves AI exists, called Multipack Wolves, which distributes the wolves of a side into several packs, rather than all of them into one single pack as it is done here.

Enable the Wolves Micro AI by using

ai_type=wolves

in the [micro_ai] tag together with the following keys:

Required keys:

• [filter]: A Standard Unit Filter selecting the predator units. Note: this was called [predators] in 1.11.2
• [filter_second]: A Standard Unit Filter selecting the prey units. Note: this was called [prey] in 1.11.2

Optional keys:

• avoid_type: Comma-separated list of unit types which the wolves try to avoid
• ca_score=90000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 90,000, which is lower than the default combat CA, but higher than most other default CAs which move units. It can be changed by setting this parameter but in most cases this will not make sense. Note that the Wolves AI consists of 2 CAs with scores ranging from ca_score-1 to ca_score. Available from Wesnoth 1.11.6

Note: The Wolves Micro AI modifies the attacks aspect.

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

        [micro_ai]
            side=6
            ai_type=wolves
            action=add

            [filter]
                type=Wolf
            [/filter]
            [filter_second]
                type=Deer
            [/filter_second]
            avoid_type=Yeti,Giant Spider,Tarantula,Bear,Dog
        [/micro_ai]

Animals AI: Multi-pack Wolves (ai_type=wolves_multipacks)

The Multi-pack Wolves Micro AI is different from the Wolves Micro AI in that there can be an arbitrary number of wolf packs, with the pack size being a free parameter. At the beginning of the scenario, close wolves are grouped into packs in a semi-methodical way. If the wolves are put on the map in distinct groups of close wolves of the correct number, they will be joined into packs matching these groups. If, on the other hand, they are spread out all over the map, the method of assigning them to packs is semi-random.

Wolves of the same pack begin by joining each other on the map. After that, they stay together until only one wolf is left, which then tries to join up with an incomplete pack or with other single wolves. Individual wolves entering the map during the scenario behave in that way as well.

A second difference to the other Wolves AI is that wolves do not actively hunt here. For the most part they just wander (often long distance). However, the pack ferociously (and without regard for its own health) attacks any enemy units that come into range, as long as that does not mean separating the pack by more than a few hexes. Staying together, or joining with a new wolf assigned to the pack, is the only thing that takes priority over satisfying the wolves' thirst for blood.

For a demonstration of the Multi-pack Wolves AI behavior, check out the "Wolves" scenario from the test scenario.

Enable the Multi-pack Wolves Micro AI by using

ai_type=wolves_multipacks

in the [micro_ai] tag together with the following keys:

Required keys:

There are no required keys

Optional keys:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Multi-pack Wolves AI consists of 2 CAs with scores ranging from ca_score-1 to ca_score. Available from Wesnoth 1.11.6
• pack_size=3: (integer) The size of the packs.
• show_pack_number=no: If set to "yes", the wolves' pack numbers will be shown below them. Note that this means that the pack number of a wolf killed in an attack will remain as a label on the map.
• type=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

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

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

            show_pack_number=yes
            pack_size=4
        [/micro_ai]

Animals AI: Big Animals (ai_type=big_animals)

The Big Animals Micro AI is a simulation of large predators that wander and hunt alone, such as Bears, Giant Spiders or Yetis. For the most part, these just wander on the terrain that's been defined for them, but they attack enemy units if those happen to come into range. The AI can be set up so that the Big Animals stay out of the way of other units (such as other large predators), in which case they only attack those if cornered.

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the test scenario.

Enable the Big Animals Micro AI by using

ai_type=big_animals

in the [micro_ai] tag together with the following keys:

Required keys:

• [filter]: A Standard Unit Filter selecting the animals to which this AI is applied. Note: this was called [big_animals] in 1.11.2

Optional keys:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Available from Wesnoth 1.11.6
• [filter_location]: The big animals often go for long distance (multi-turn) journeys. This tag is a Standard Location Filter describing the terrain from which the next goal is chosen. The default is all terrain on the map. Note: this was called [goal_terrain] in 1.11.2
• [filter_location_wander]: The terrain on which the big animals will end their moves. This is a Standard Location Filter. The default is all terrain on the map. Note: this was called [wander_terrain] in 1.11.2
• [avoid_unit]: A Standard Unit Filter describing all enemy units that the big animals will avoid. Note that the condition that this must be enemy units is added by the AI automatically and does not need to be included in the filter.

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

        [micro_ai]
            side=3
            ai_type=big_animals
            action=add

            [filter]
                type=Bear
            [/filter]
            [avoid_unit]
                type=Yeti,Giant Spider,Tarantula,Bear,Dog
            [/avoid_unit]
            [filter_location]
                x,y=1-40,1-18
            [/filter_location]
            [filter_location_wander]
                terrain=*
            [/filter_location_wander]
        [/micro_ai]

Animals AI: Forest Animals (ai_type=forest_animals)

The Forest Animals Micro AI simulates a number of different animal behaviors that one might find in a forest, namely animals behaving like deer, rabbits and families of tuskers. In the following, we will refer to those animals by these types, even though the actual unit types can be selected freely. They behave as follows:

• Each deer wanders randomly on (selectable) terrain, except when enemies get in its (the deer's) maximum movement range, in which case it flees to the farthest point it can reach.
• Tuskers exhibit the same behavior as deer, except when an enemy is next to one of the tusklets. This enemy is attacked unconditionally by the tuskers trying to protect their young.
• Tusklets blindly follow the closest adult tusker, except when there is no tusker left, in which case they behave the same as deer.
• Rabbits also wander randomly, but in addition disappear into their holes (if any are within reach) when enemies are close. They reappear out of their holes at the beginning of the turn, if it is safe.

For a demonstration of the Forest Animals AI behavior, check out the "Animals" scenario from the test scenario.

Enable the Forest Animals Micro AI by using

ai_type=forest_animals

in the [micro_ai] tag together with the following keys:

Required keys:

There are no required keys

Optional keys:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Forest Animals AI consists of 4 CAs with scores ranging from ca_score-3 to ca_score. Available from Wesnoth 1.11.6
• rabbit_type, tusker_type, tusklet_type, deer_type: Comma-separated lists of the unit types behaving as the respective animals. If any of these parameters are not set, those types of animal behavior are skipped by the AI.
• [filter_location]: A Standard Location Filter describing the terrain on which the forest animals wander when they are not threatened by enemies. Note: this was called [wander_terrain] in 1.11.2
• rabbit_number=6: (integer) The number of rabbits for the AI to have on the map simultaneously. The AI puts the missing number of rabbits onto the map at the beginning of the AI's turn (when the rabbits come out of their holes).
• rabbit_enemy_distance=3: (number) Rabbits won't spawn in holes that aren't more than this distance away from all enemies.
• rabbit_hole_img: Rabbit holes are marked by items on the map. If this parameter is set, it must be the file name of the item image. If it is not set, all items on the map are treated as rabbit holes.

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

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

            deer_type=Deer
            rabbit_type=Rabbit
            tusker_type=Tusker
            tusklet_type=Tusklet
            [filter_location]
                terrain=*^F*
            [/filter_location]
        [/micro_ai]

Animals AI: Herd and Herders (ai_type=herding)

The Herding Micro AI sets up an area on the map where a number of herder units (such as sheep dog) control and protect a herd (such as sheep). For convenience, we simply refer to them as sheep dogs and sheep in the following, even though arbitrary unit types can be selected for either.

Sheep dogs try to keep their sheep safe. This involves keeping them inside the herding area, positioning themselves in between the sheep and approaching enemies, and attacking the enemies if those get too close. If no active herding or protecting move is needed, the dogs go to a random location on the perimeter of the herding area.

Sheep wander aimlessly except when a sheep dog is next to them, in which case they run away from the dog. The dogs exploit this by positioning themselves on the outside of the sheep, if possible. Sheep also run away from approaching enemies.

For a demonstration of the Herding AI behavior, check out the "Animals" scenario from the test scenario.

Enable the Herding Micro AI by using

ai_type=herding

in the [micro_ai] tag together with the following keys:

Required keys:

• [filter]: A Standard Unit Filter describing the herder units (e.g. dogs). Note: this was called [herders] in 1.11.2
• [filter_second]: A Standard Unit Filter describing the herd units (e.g. sheep). Note: this was called [herd] in 1.11.2
• [filter_location]: A Standard Location Filter describing the terrain forming the perimeter of the herding area. In other words, this is the path the herders (dogs) use to patrol around the outside of the herding area. This must be a set of coordinates completely enclosing the herding area. Note: this was called [herding_perimeter] in 1.11.2. Here's an example of setting up a rectangular perimeter:

    [filter_location]
        x=10-20,10-20,10,  ,20
        y=11,   21,   11-21,11-21
    [/filter_location]

Another possibility is by defining the path by certain terrain on the map (as it is done in the "Animals" test scenario), in which case the filter can simply look like this:

    [filter_location]
        terrain=Rb
    [/filter_location]

• herd_x,herd_y: The coordinate of one hex (any one hex) inside the herding area. This is needed to define which part of the map is on the inside of the herding area perimeter defined by [herding_perimeter], and which is the outside.

Optional keys:

• attention_distance=8: (integer) If an enemy is within this distance of a herd unit, but not as close as attack_distance, the herders try to position themselves in between the enemy and the herd unit.
• attack_distance=4: (integer) If an enemy is within this distance of a herd animal, the herders attack this enemy.
• ca_score=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Herding AI consists of 6 CAs with scores ranging from ca_score-5 to ca_score. Available from Wesnoth 1.11.6

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

        [micro_ai]
            side=7
            ai_type=herding
            action=add

            [filter]
                type=Dog
            [/filter]
            [filter_second]
                type=Sheep,Ram
            [/filter_second]
            herd_x,herd_y=32,28
            [filter_location]
                terrain=Rb
            [/filter_location]
        [/micro_ai]

Animals AI: Hunter (ai_type=hunter)

Note: Before Wesnoth 1.11.7 animal_type=hunter_unit needed to be used. The _unit suffix has been dropped as of 1.11.7.

The Hunter Micro AI leads a unit (or units) through hunt-and-rest cycles. The units wander in a prescribed area of the map, their hunting ground, until an enemy unit comes within range. Note that the units do not actively chase down enemies, but wander randomly through the hunting ground until an enemy is encountered.

If enemies are within range of a hunter unit, the hunter attacks the weakest of them. If a kill is made, it then retreats to its rest location, where it stays for a certain number of turns or until fully healed.

A few more details:

• If the hunter's way home is entirely blocked on the return (so that there is no possible path), the normal RCA AI takes over its behavior.
• However, if the way is blocked by an enemy unit occupying the rest hex, that enemy will be attacked unconditionally.
• A kill only makes the hunter go home when it is the attacker, not as defender.

For a demonstration of the Hunter AI behavior, check out the "Dragon" scenario from the test scenario.

Enable the Hunter Micro AI by using

ai_type=hunter

in the [micro_ai] tag together with the following keys:

Required keys:

• id or [filter]: The ID of a unit or a Standard Unit Filter selecting the units controlled by this Micro AI.
  • One or the other is required
  • If both are given, [filter] takes priority over id=
  • The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
  • If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
  • [filter] is available from Wesnoth 1.11.7
• home_x,home_y: The coordinates of the hex to which the hunter returns and rests at after a kill.

Optional keys:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Available from Wesnoth 1.11.6
• [filter_location]: A Standard Location Filter describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map. Note: this was called [hunting_ground] in 1.11.2
• rest_turns=3: (integer) The number of turns the AI stays at home_x,home_y after a kill.
• show_messages=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase.

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

        [micro_ai]
            side=1
            ai_type=hunter
            action=add

            id=Rowck
            home_x,home_y=3,15

            [filter_location]
                x,y=5-30,1-15
            [/filter_location]
            rest_turns=2
            show_messages=yes
        [/micro_ai]

Animals AI: Swarm (ai_type=swarm)

The Swarm Micro AI uses some very simply algorithms to simulate animal swarm behavior. Without adjacent enemies, they simply do a random move, trying to stay together and at a certain distance from enemies. However, if an enemy unit is close to any bat, the swarm scatters. This is particular fun to watch when one places an enemy unit in the middle of the swarm. After being scattered, the swarm members slowly rejoin, but not in a very organized way. Sub-swarms or individual bats might roam around for quite some time before they find their way back. It is also possible that individual bats (or small groups) split off from the larger swarm at times.

For a demonstration of the Swarm AI behavior, check out the "Swarm" scenario from the test scenario.

Enable the Swarm Micro AI by using

ai_type=swarm

in the [micro_ai] tag together with the following keys:

Required keys:

There are no required keys

Optional keys:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Swarm AI consists of 2 CAs with scores ranging from ca_score-1 to ca_score. Available from Wesnoth 1.11.6
• enemy_distance=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
• scatter_distance=3: (int) Enemies within "scatter_distance" hexes of any swarm unit cause the swarm to scatter, by each unit trying to maximize its individual distance from the enemy.
• 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. This parameter is meant to simulate how far an individual member of the swarm can see, meaning that the swarm is "out of sight" (and the unit will not be able to follow it) if it is more than this distance away.

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

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

        [/micro_ai]

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.

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. [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

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.

• 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).
• ca_score=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Bottleneck Defense AI consists of 2 CAs with scores ranging from ca_score-1 to ca_score. Available from Wesnoth 1.11.6
• 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.

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]
    side=1
    ai_type=bottleneck_defense
    action=add

    x=14,14,14
    y= 7, 9, 8
    enemy_x=13,13
    enemy_y= 8, 9

    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]

Generalized Goto Micro AI (ai_type=goto)

*** Note: this Micro AI is available starting from Wesnoth 1.11.3 ***

The Goto Micro AI provides a highly configurable method of sending a unit (or units) to a location or set of locations. The units to be moved are defined using a Standard Unit Filter (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a Standard Location Filter (SLF).

By default, each unit matching the SUF will move toward the closest goal (in terms of turns needed to get there) matching the SLF via the fastest route given the current situation on the map (locations of enemy units etc.), but this behavior can be influenced by the optional keys listed below. Note that this means that a unit's goal might change from one turn to the next depending on the situation on the map.

The behavior of the unit(s) once they reach their goal location(s) is configurable as well. By default, they will stay there until the Goto Micro AI is deleted or changed.

For demonstrations of several Goto Micro AI usages, check out the "Goto" scenario from the test scenario.

Enable the Goto Micro AI by putting

{MICRO_AI_GOTO}

into the [side] tag and configure it by using

ai_type=goto

in the [micro_ai] tag. [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

Goto specific keys for the [micro_ai] tag:

Required keys:

• [filter_location]: A Standard Location Filter describing the possible goal locations for the move.

Optional keys:

• avoid_enemies: (number>0) Available from Wesnoth 1.11.6 By default, units controlled by the Goto Micro AI will not take enemy units into account for route finding, other than the enemies' ZoCs. By contrast, if this key is set, they will try to avoid traversing hexes on which they can be attacked by enemies. The larger the value of avoid_enemies, the more the units will try to stay out of the enemies' way. Notes:
  • Units are willing to take a path that is 'avoid_enemies' movement points longer for each enemy unit that can be avoided by doing so for each hex along the path. As an example, if avoid_enemies=1 and the shortest path crosses 2 hexes that can be reached by 3 enemies each, the unit is willing to take a path that is up to 6 hexes longer instead. If avoid_enemies=10 in the same situation, the unit will take a path up to 60 hexes longer.
  • Hexes adjacent to enemy units are always strongly avoided, independent of the value of avoid_enemies.
  • avoid_enemies is ignored if 'use_straight_line=true' is set.
• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs.
• [filter]: A Standard Unit Filter selecting the units to be moved. Defaults to all units of the side if not defined. Note: this used to be a required key up to 1.11.5
• ignore_enemy_at_goal=no and ignore_units=no: (boolean) In the default configuration, the Goto MAI does not move units if the path to all goal hexes is blocked by enemies. It is therefore possible to disable the Goto MAI by putting enemy units on all the goal hexes. That can be changed if either of these two keys is set to 'yes'.
  • 'ignore_enemy_at_goal=yes' makes the AI choose its goals while disregarding any enemy units at the goal hexes. Even so, a stiff rating penalty is applied to goal hexes occupied by enemies, thus that unoccupied goal hexes are chosen unless all possible goals are occupied by enemies. Note that this setting only ignores enemy units at the goal hexes themselves. It is still possible to disable the AI by putting enemies all around the goals.
  • 'ignore_units=yes' let's the AI ignore all enemy units when deciding which goal hex(es) to move toward.
  • In both cases, enemies are only ignored for deciding which unit to move toward which goal hex. For the actual move itself, all enemies and their ZoCs are considered as usual.
  • Both options only take effect if neither avoid_enemies nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers.
• release_unit_at_goal=no: (boolean) By default, a unit that reaches a goal location will stay there until the Goto Micro AI is deleted or changed (or until the conditions specified in the [goto_goals] SLF change). If this parameter is set, a unit that has reached its goal will not be controlled by this Micro AI any more starting from the next turn.
• release_all_units_at_goal=no: (boolean) Same as release_unit_at_goal, but this will deactivate the Goto Micro AI for all units once the first unit reaches a goal.
• unique_goals=no: (boolean) If set to 'yes', each unit will be sent to a different goal location. Note that the best goals are recalculated each turn, so a unit might choose a different goal this turn from what it was heading for during the previous turn if the situation on the map has changed. Also note that if there are more units than goal locations, the left over units will not be handled by the Goto MAI but follow default behavior instead.
• use_straight_line=no: (boolean) By default, units choose the route by which they will get to their goal locations in the smallest number of turns. If this parameter is set to 'yes', a straight line route (or something pretty close to it at least) will be chosen instead, irrespective of whether this leads into a dead end, whether it is blocked by enemies, etc.

Notes:

• Depending on the parameters used, the Goto Micro AI might require a lot of path finding to be done. Thus, while it is possible to set up this AI to move many units to many different locations, a usage like that might require quite a long calculation time.

Goto Micro AI example usages:

Here are several examples of goto [micro_ai] tag usages from the "Goto" test scenario:

• Send a unit toward a castle (similar to the RCA AI's Goto Candidate Action, but avoiding dead ends and areas ZoCed by enemies)

        [micro_ai]
            side=2
            ai_type=goto
            action=add
            ca_id=messenger1

            [filter]
                id=messenger1
            [/filter]
            [filter_location]
                x,y=6-7,2-4
                terrain=C*
            [/filter_location]
        [/micro_ai]

• Send all ghosts of the side toward the southern border of the map

        [micro_ai]
            side=8
            ai_type=goto
            action=add

            [filter]
                type=Ghost
            [/filter]
            [filter_location]
                 y=33
            [/filter_location]
            avoid_enemies=1
        [/micro_ai]

• Send four bats to the four corners of the map (with each bat going to a different corner)

        [micro_ai]
            side=7
            ai_type=goto
            action=add

            [filter]
                type=Vampire Bat
            [/filter]
            [filter_location]
                x=1,1,44,44
                y=1,33,1,33
            [/filter_location]
            unique_goals=yes
        [/micro_ai]

• Set up a guardian unit that doesn't move while no enemy unit is within 8 hexes (ironically, the Goto Micro AI can be used to keep units in place, although using one of the Guardian Micro AIs might often be a better idea)

        [micro_ai]
            side=3
            ai_type=goto
            action=add

            [filter]
                id=guard1
            [/filter]
            [filter_location]
                [filter]
                    id=guard1
                [/filter]
                [not]
                    [filter]
                        side=1
                    [/filter]
                    radius=8
                [/not]
            [/filter_location]
        [/micro_ai]

Guardian Micro AIs

Important Note: The syntax for the Guardian Micro AIs has changed as of Wesnoth 1.11.7

The guardian_type= parameter has been eliminated and is taken care of by the ai_type= parameter. The descriptions below are for current trunk (and for 1.11.7 as the first released version). If you are using Wesnoth 1.11.6 or earlier, use ai_type=guardian_type and guardian_type= with the latter set to the ai_type values listed below. As an example, the syntax as of 1.11.7 is

ai_type=return_guardian

For previous versions this should be

ai_type=guardian_unit
guardian_type=return_guardian

Also, for Wesnoth 1.11.6 and earlier all Guardian Micro AIs were enabled by putting

{MICRO_AI_GUARDIAN}

into the [side] tag. Now a separate engine macro exists for each Guardian MAI, as listed below. Now no macro is needed any more.

General Comments on the Guardian Micro AIs

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

For a demonstration of several different guardian behaviors, check out the "Guardians" scenario from the test scenario.

Return Guardian (ai_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.

Enable the Return Guardian Micro AI by using

ai_type=return_guardian

in the [micro_ai] tag together with the following keys:

Required keys:

• id or [filter]: The ID of a unit or a Standard Unit Filter selecting the units controlled by this Micro AI.
  • One or the other is required
  • If both are given, [filter] takes priority over id=
  • The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
  • If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
  • [filter] is available from Wesnoth 1.11.7
• return_x,return_y: The coordinate of the hex the unit returns to after each attack

Optional keys:

• ca_score=10010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score ca_score the other with ca_score-20. The default value is set so that the first CA gets executed right before the default combat CA, and the other right after. It usually will not make sense to change this value, but it is possible to do so for custom applications. Available from Wesnoth 1.11.6

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

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

            id=return1
            return_x,return_y=20,2
        [/micro_ai]

Stationed Guardian (ai_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.

Enable the Stationed Guardian Micro AI by using

ai_type=stationed_guardian

in the [micro_ai] tag together with the following keys:

Required keys:

• id or [filter]: The ID of a unit or a Standard Unit Filter selecting the units controlled by this Micro AI.
  • One or the other is required
  • If both are given, [filter] takes priority over id=
  • The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
  • If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
  • [filter] is available from Wesnoth 1.11.7
• 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:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Available from Wesnoth 1.11.6

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

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

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

Coward (ai_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.

Enable the Coward Micro AI by using

ai_type=coward

in the [micro_ai] tag together with the following keys:

Required keys:

• id or [filter]: The ID of a unit or a Standard Unit Filter selecting the units controlled by this Micro AI.
  • One or the other is required
  • If both are given, [filter] takes priority over id=
  • The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
  • If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
  • [filter] is available from Wesnoth 1.11.7
• distance: The distance within which an enemy must be to "scare" the unit

Optional keys:

• avoid_x, avoid_y: The x and y coordinate of the hex to avoid
• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Available from Wesnoth 1.11.6
• seek_x, seek_y: The x and y coordinate of the hex to seek

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

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

            id=coward3
            distance=5
            seek_x,seek_y=24,5
            avoid_x,avoid_y=24,15
        [/micro_ai]

Zone guardian (ai_type=zone_guardian)

*** Note: this Micro AI is available starting from Wesnoth 1.11.3 ***

A zone guardian is a unit that, as the name says, guards a zone. It moves randomly inside this zone until an enemy enters it (or a separately defined enemy zone, see below). Applications might be the defense of a castle or a nesting area. The zone macro can be called with an optional SLF, [filter_location_enemy]:

• If not specified, the zone guard attacks any enemy coming inside its guard zone.
• If [filter_location_enemy] is given, it attacks any enemy entering this zone and once there are no more enemies, it goes back to patrol in its basic zone.

Enable the Zone Guardian Micro AI by using

ai_type=zone_guardian

in the [micro_ai] tag together with the following keys:

Required keys:

• id or [filter]: The ID of a unit or a Standard Unit Filter selecting the units controlled by this Micro AI.
  • One or the other is required
  • If both are given, [filter] takes priority over id=
  • The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
  • If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
  • [filter] is available from Wesnoth 1.11.7
• [filter_location]: A Standard Location Filter designating the zone to guard.

Optional keys:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Available from Wesnoth 1.11.6
• [filter_location_enemy]: A Standard Location Filter designating the zone where enemies have to be attacked. If not given, it defaults to [filter_location].
• station_x,station_y: By default, the zone guardian moves randomly within the zone if there is no enemy to attack. However, if station_x/y is given, it moves to this position instead during turns when it does not have an enemy to attack. This position does not need to be inside the zone defined above. Note: obviously it does not make sense to define [filter_location], [filter_location_enemy] and station_x/y all at the same time. Only [filter_location] and either one of the latter two (or none of them) should be provided for any zone guardian. Available from Wesnoth 1.11.5

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

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

            id=zone3
            [filter_location]
                x,y=22-31,4-11  # This is intentionally chosen to extend past the lake
                terrain=W*
            [/filter_location]
            station_x,station_y=32,8
        [/micro_ai]

Hang Out Micro AI (ai_type=hang_out)

*** Note: this Micro AI is available starting from Wesnoth 1.11.6 ***

The Hang Out Micro AI instructs units of the AI side to "hang out" around a certain location, or locations, until a condition for mobilizing the side is met. If none of the optional keys are given, the AI controls all units of the side to hang around the leader while moving off castle tiles to make room for recruiting.

The AI works by moving each unit to its best hex first using the minimum amount of movement points required for this move. Once all AI units are in position, movement points are set to zero for all of them simultaneously such that they cannot be used by other AI candidate actions. This is done because the mobilizing condition might be met as result of one of the moves of the Hang Out AI, after which we want units to be able to continue with other AI actions.

For a demonstration, check out the "Hang Out and Messenger" scenario from the test scenario.

Enable the Hang Out Micro AI by putting

{MICRO_AI_HANG_OUT}

into the [side] tag and configure it by using

ai_type=hang_out

in the [micro_ai] tag. [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

Hang Out specific keys for the [micro_ai] tag:

Required keys:

There are no required keys. In its default configuration, the Hang Out MAI controls all units of a side, keeping them as close to the side leader(s) as possible while moving off castle tiles to make room for recruiting. For this purpose, the candidate action score defaults to 170,000, which is just below the score of the default recruiting CA.

Optional keys:

• [avoid]: A Standard Location Filter for the terrain which the AI units should avoid. By default, this is set to all castle terrain (terrain=C*,C*^*,*^C*) so that units move off the castle to make room for recruiting. Note that this does not include keep terrain, otherwise the leader would be moved off the keep as well.
• ca_score=170000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 170,000, which means that it is executed after the default recruitment CA, but before most of the other default CAs.
• [filter]: A Standard Unit Filter selecting the units of the AI side participating in the Hang Out action (side= is always set and does not need to be provided). It defaults to all units of the side.
• [filter_location]: A Standard Location Filter describing the locations near which the AI units should hang out. This does not mean that the units only move onto terrain specified here, but that they minimize the distance to such terrain. It defaults to the position of the side leader(s).
• mobilize_condition: (WML Condition Tag) Once the condition set up here has been met, the Hang Out MAI is disabled and the side goes over to other AI activity. The Hang Out MAI remains disabled after this, even if the condition is not met any more later in the scenario.
• mobilize_on_gold_less_than: (number) Since side gold cannot be checked in a WML condition tag without storing it in a variable first, this key is provided separately. It disables the Hang Out Micro AI once the side gold goes below the value specified here for the first time.

Notes:

• The Hang Out AI still takes effect if no locations to hang out at are found or if all map locations are to be avoided. In that case, it simply keeps all units at their current locations.

This is an example of a Hang Out Micro AI configuration:

        [micro_ai]
            side=1
            ai_type=hang_out
            action=add

            [avoid]
                terrain=C*,H*,M*,A*,S*,*^F*
            [/avoid]
            [mobilize_condition]
                [have_unit]
                    side=1
                    count=7-99
                [/have_unit]
            [/mobilize_condition]
        [/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.

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. [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

Healer Support specific keys for the [micro_ai] tag:

Required keys:

There are no required keys.

Optional keys:

• [filter]: A Standard Unit Filter selecting the healer units. If set, only units passing this filter and having the healing ability are considered by this Micro AI. Available from Wesnoth 1.11.3
• [filter_second]: A Standard Unit Filter selecting units to receive healing. If set, only units passing this filter and the other healee selection filters will be selected for healing by this Micro AI. Available from Wesnoth 1.11.3
• 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.

Standard RCA AI aspects respected by this Micro AI:

• [avoid]: The standard RCA AI aspect used to define locations that should be avoided by the AI. Available from Wesnoth 1.11.4

Notes:

• The Healer Support Micro AI modifies the attacks aspect.
• The CA evaluation scores of this AI are hard-coded. It does not work otherwise.

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 Lurker Micro AI controls some or all units of a side in "lurker mode". A lurker is a unit that is capable of moving across most terrains, but that only stops on and attacks from specific terrain. It might also have the ability to hide on this terrain (which is the reason why it is called a lurker).

Lurkers move individually without strategy and always attack the weakest enemy within their reach. If no enemy is in reach, the lurker does a random move instead - or it just sits and waits (lurks).

For a demonstration of different types of lurker behavior, check out the "Lurkers" scenario from the test scenario.

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 [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

Lurkers specific keys for the [micro_ai] tag:

Required keys:

• [filter]: Specifies which units of the side are controlled by the Lurker Micro AI. This is a Standard Unit Filter. Note: this was called [lurkers] in 1.11.2

• [filter_location]: Specifies the terrain from which the lurkers attack. This is a Standard Location Filter. Note: this was called [attack_terrain] in 1.11.2

Optional keys:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Available from Wesnoth 1.11.6
• [filter_location_wander]: Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a Standard Location Filter. If [filter_location_wander] is not given, it defaults to [filter_location]. Note: this was called [wander_terrain] in 1.11.2
• stationary=no: (boolean) If set to yes, a lurker never moves if there is no enemy within attack range.

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

        [micro_ai]
            side=4
            ai_type=lurkers
            action=add

            [filter]
                type=Naga Fighter
            [/filter]
            [filter_location]
                terrain=W*,S*
            [/filter_location]
            [filter_location_wander]
                terrain=W*
            [/filter_location_wander]
        [/micro_ai]

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.

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. [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

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:

• ca_score=300000: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Note that the Messenger Escort AI consists of 3 CAs with scores ranging from ca_score-2 to ca_score. Available from Wesnoth 1.11.6
• 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)

Note: Before Wesnoth 1.11.7 animal_type=patrol_unit needed to be used. The _unit suffix has been dropped as of 1.11.7.

The defines a number of waypoints for a unit (or units) 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.

For a demonstration of several different patrol behaviors, check out the "Patrols" scenario from the test scenario.

Enable the Patrol Micro AI by putting

{MICRO_AI_PATROL}

into the [side] tag and configure it by using

ai_type=patrol

in the [micro_ai] tag. [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

Patrol specific keys for the [micro_ai] tag:

Required keys:

• id or [filter]: The ID of a unit or a Standard Unit Filter selecting the units controlled by this Micro AI.
  • One or the other is required
  • If both are given, [filter] takes priority over id=
  • The AI contains an implicit filter for units on the AI side. Thus, if all AI units are to be selected, an empty [filter] tag can be used.
  • If several units match the filter, the order in which they are controlled is not guaranteed. If the order matters, set up several MAIs using the id= key and different values for ca_score=.
  • [filter] is available from Wesnoth 1.11.7
• waypoint_x,waypoint_y: Comma-separated lists of the waypoint coordinates through which the patrol travels (in order).

Optional keys:

• 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.
• ca_score=300000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 300,000, which is higher than any of the RCA AI candidate actions. By setting it, for example, to 170,000, we can have it be executed after the default recruitment CA, but before most of the other default CAs. Available from Wesnoth 1.11.6
• 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.
• 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.

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

        [micro_ai]
            side=2
            ai_type=patrol
            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.

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. [The macro does not need to be placed in the [side] tag any more as of Wesnoth 1.11.7.]

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.

Notes:

• The Protect Unit Micro AI modifies the attacks aspect. Depending on the parameters, it might also modify the move leader to keep candidate action.
• The CA evaluation scores of this AI are hard-coded. It does not work otherwise.

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

Important Note: The syntax for the Recruiting Micro AIs has changed as of Wesnoth 1.11.7

The recruiting_type= parameter has been eliminated and is taken care of by the ai_type= parameter. The descriptions below are for current trunk (and for 1.11.7 as the first released version). If you are using Wesnoth 1.11.6 or earlier, use ai_type=recruiting and recruiting_type= set to either 'random' or 'rushers'. As an example, the syntax as of 1.11.7 is

ai_type=recruit_random

For previous versions this should be

ai_type=recruiting
recruiting_type=random

Also, for Wesnoth 1.11.6 and earlier all Recruiting Micro AIs needed to be enabled by putting

{MICRO_AI_RECRUITING}

into the [side] tag. Now no macro is needed any more.

General Comments on the Recruiting Micro AIs

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. You can also explore the unit choices by watching the Experimental AI in a multiplayer game.

Note: Obviously, the Recruitment Micro AI modifies the recruitment candidate action.

Random Recruitment AI (ai_type=recruit_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.

Enable the Random Recruiting Micro AI by using

ai_type=recruit_random

in the [micro_ai] tag.

Required keys:

There are no required keys.

Optional keys:

• ca_score=180000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 180,000. This is identical to the default Recruiting CA which it replaces. Available from Wesnoth 1.11.6
• [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=recruit_random
            action=add

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

            skip_low_gold_recruiting=yes
        [/micro_ai]

Rush Recruitment AI (ai_type=recruit_rushers)

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

Enable the Rush Recruiting Micro AI by using

ai_type=recruit_rushers

in the [micro_ai] tag.

Required keys:

There are no required keys.

Optional keys:

• ca_score=180000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 180,000. This is identical to the default Recruiting CA which it replaces. Available from Wesnoth 1.11.6
• randomness=0.1: (number) A random number is applied to the rusher recruit engine's score to prevent the recruitment pattern from being too predictable. 0 causes no randomness to be applied, while larger numbers increase the random effect. A value of 1-2 generates results in which the random effect is approximately equal to the scored effect. Extremely high values are essentially entirely random.

Rush recruiting is set up like this:

        [micro_ai]
            side=1
            ai_type=recruit_rushers
            action=add
         [/micro_ai]

Simple Attack Micro AI (ai_type=simple_attack)

*** Note: this Micro AI is available starting from Wesnoth 1.11.7 ***

The Simple Attack Micro AI is meant as an addition to the default combat candidate action for when one wants to force the AI to do attacks that it would otherwise not do (for example on units that are 1 XP from leveling) or to execute certain attacks before all others (for example, attack with all "expendable" units first). It is not set up to be a replacement for the default attacks. Some notes:

• The algorithm is different from and simpler than that of the default combat CA. For example, no attack combinations are considered, only individual attacks. As a result, the default aspects (aggression, caution, [avoid], ...) are not taken into account. Also, if lots of units are involved, evaluation of this Micro AI is potentially quite a bit slower than of the default attacks.

• If an attack matching the Standard Unit Filters described below is found, this attack will always be executed, no matter how bad the odds are. Thus, this Micro AI can be used to force the AI to do attacks it would otherwise avoid.

• Other than selecting the attacker/defender units, this AI is currently not configurable. Let us know if you would like to see certain options to be added. (No guarantees that we will add them, but we will definitely consider them.)

For a demonstration, check out the "Simple Attack" scenario from the test scenario.

Enable the Simple Attack Micro AI by using

ai_type=simple_attack

in the [micro_ai] tag.

Simple Attack specific keys for the [micro_ai] tag:

Required keys:

There are no required keys. It is, however, in general not desirable to use this AI without at least one of the optional Standard Unit Filters below, as this AI is not meant as a replacement of the default combat candidate action.

Optional keys:

• ca_score=110000: (non-negative integer) The evaluation score of the candidate action controlling this Micro AI. By default, it is set to 110,000, which means that it is executed right before the default combat candidate action.
• [filter]: A Standard Unit Filter selecting the units of the AI side participating in the Simple Attack action (side= is always set and does not need to be provided). It defaults to all units of the side.
• [filter_second]: A Standard Unit Filter selecting the units the AI should attack. It defaults to all enemy units.

Below are 2 examples of Simple Attack Micro AI configurations. The first one shows how to force the AI to attack with all Soulless and Walking Corpse units first:

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

            ca_score=110000
            [filter]
                type=Soulless,Walking Corpse
            [/filter]
        [/micro_ai]

The sceond executes attacks by Soulless on all enemy units that are 1 XP from leveling (something the RCA AI would generally not do). Note that the Lua code bit is simply there in order to code the "1 XP from advancing" condition. It is not needed for most other SUFs, as can be seen in the previous example.

        [lua]
            code=<<
                function close_to_advancing(unit)
                    if (unit.experience >= unit.max_experience-1) then
                        return true
                    else
                        return false
                    end
                end
            >>
        [/lua]

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

            ca_score=110001
            [filter]
                type=Soulless  # No Walking Corpses; L0 units don't advance enemy
            [/filter]
            [filter_second]
                lua_function = "close_to_advancing"
            [/filter_second]
        [/micro_ai]

Several Simple Attack Micro AIs can be combined for the same AI side. The two examples above are both used (note the different values for ca_score) in the Simple Attack Micro AI test scenario.

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