The Battle for Wesnoth Wiki - User contributions [en]

LuaAPI/wesnoth/interface

2022-07-09T13:48:16Z

Mattsc: /* wesnoth.interface.add_overlay_text */ add wesnoth.interface.handle_user_interact

<div class="tright"> __TOC__ </div>

{{DevFeature1.15|0}}

The entire interface module is only available in the game. It is not available to plugins or map generators.

== Interface functions ==

=== wesnoth.interface.delay ===

* {{LuaGameOnly}} '''wesnoth.interface.delay'''(''milliseconds'')

Delays the engine for a period of time, specified in milliseconds.

<syntaxhighlight lang=lua>
wesnoth.delay(500)
</syntaxhighlight>

=== wesnoth.interface.deselect_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.deselect_hex'''()

Reverses any highlight_hex call, leaving all locations unhighlighted. Takes no arguments.

=== wesnoth.interface.highlight_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.highlight_hex'''(''x'', ''y'')

Draws an outline around the specified hex.

=== wesnoth.interface.select_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.select_unit'''(''x'', ''y'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} '''wesnoth.units.select'''(''unit'', [''show_movement'', [''fire_events'']])
* {{LuaGameOnly}} ''unit'':'''select'''([''show_movement'', [''fire_events'']])

Selects the given unit in the game map as if the player had clicked on it.
Argument 3: boolean, whether to show the movement range of any unit on that location (def: true)
Argument 4: boolean, whether to fire any select events (def: false).

This function is available under two different names, but the possible arguments are the same in both cases. In other words, '''wesnoth.units.select''' can be called with a location instead of a unit, and '''wesnoth.interface.select_unit''' can be called with a unit instead of a location.

<syntaxhighlight lang=lua>
wesnoth.interface.select_unit(14, 6, true, true)
</syntaxhighlight>

If called without arguments, this function deselects the current unit from the map as long as the mouse cursor is not on its hex. It will continue to be displayed on the UI sidebar in any case.

=== wesnoth.interface.float_label ===

* {{LuaGameOnly}} '''wesnoth.interface.float_label'''(''x'', ''y'', ''text'')

Pops some text above a map tile.

<syntaxhighlight lang=lua>
wesnoth.float_label(unit.x, unit.y, "<span color='#ff0000'>Ouch</span>")
</syntaxhighlight>

=== wesnoth.interface.get_displayed_unit ===

* {{LuaGameOnly}} '''wesnoth.interface.get_displayed_unit'''() → ''unit''
* {{LuaGameOnly}} '''wesnoth.units.get_hovered'''() → ''unit''

Returns a proxy to the unit currently displayed in the side pane of the user interface, if any.

<syntaxhighlight lang=lua>
local name = tostring(wesnoth.interface.get_displayed_unit().name)
</syntaxhighlight>

=== wesnoth.interface.get_hovered_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_hovered_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently hovered tile, that is, where the mouse cursor is located. This is mostly useful for defining command-mode helpers.

=== wesnoth.interface.get_selected_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.get_selected_hex'''() → ''x'', ''y''

Returns the two coordinates of the currently selected (highlighted) tile. This is mostly useful for defining command-mode helpers.

<syntaxhighlight lang=lua>
function chg_unit(attr, val)
local x, y = wesnoth.interface.get_selected_hex()
if not x then wesnoth.message("Error", "No unit selected."); return end
wesnoth.units.modify({ x = x, y = y }, { [attr] = val })
end
-- Function chg_unit can be used in command mode to modify unit attributes on the fly:
-- :lua chg_unit("status.poisoned", true)
</syntaxhighlight>

=== wesnoth.interface.get_viewing_side ===

* {{LuaGameOnly}} '''wesnoth.interface.get_viewing_side'''() → ''side'', ''full_vision''

Returns the viewing side of the current client in a multiplayer game.

For a player participating in the game, this will always be the side that they control, or, if they control multiple sides, the one they most recently had control over. However, for an observer client, this will return the currently-active side instead.

The second return value indicates whether the current client has full vision. This can only happen in replays or for observers.

For obvious reasons, use of this function can easily cause out-of-sync errors. Use with care.

=== wesnoth.interface.lock===

* {{LuaGameOnly}} '''wesnoth.interface.lock'''(''lock'')

Locks or unlocks gamemap view scrolling for human players. If true is passed as the first parameter, the view is locked; pass false to unlock.

Human players cannot scroll the gamemap view as long as it is locked, but Lua or WML actions such as wesnoth.scroll_to_hex still can; the locked/unlocked state is preserved when saving the current game. This feature is generally intended to be used in cutscenes to prevent the player scrolling away from scripted actions.

<syntaxhighlight lang=lua>
wesnoth.interface.lock_view(true)
wesnoth.interface.scroll_to_hex(12, 14, false, true)
</syntaxhighlight>

=== wesnoth.interface.is_locked ===

* {{LuaGameOnly}} '''wesnoth.interface.is_locked'''() → ''locked?''

Returns a boolean indicating whether gamemap view scrolling is currently locked.

=== wesnoth.interface.scroll_to_hex ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll_to_hex'''(''x'', ''y'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} '''wesnoth.units.scroll_to'''(''unit'', [''only_if_visible'', [''instant'', [''only_if_needed'']]])
* {{LuaGameOnly}} ''unit'':'''scroll_to'''([''only_if_visible'', [''instant'', [''only_if_needed'']]])

Scrolls the map to the given location. If true is passed as the third parameter, scrolling is disabled if the tile is hidden under the fog. If true is passed as the fourth parameter, the view instantly warps to the location regardless of the scroll speed setting in Preferences. If true is passed as the fifth parameter, no scrolling occurs if the target location is already visible onscreen. It is also possible to pass a unit instead of a pair of tile coordinates (regardless of which module the function is called from).

<syntaxhighlight lang=lua>
local u = wesnoth.units.get "hero"
u:scroll_to()
</syntaxhighlight>

=== wesnoth.interface.scroll ===

* {{LuaGameOnly}} '''wesnoth.interface.scroll'''(''dx'', ''dy'')

Scrolls the map by the given amount, which may be either positive or negative.

=== wesnoth.interface.zoom ===

* {{LuaGameOnly}} '''wesnoth.interface.zoom'''(''factor'', [''relative'']) → ''new_zoom''

Changes the zoom level of the map. If relative is false, which is the default, it simply sets the zoom level. If relative is true, it zooms relative to the current zoom level. So, for example, if the zoom level is currently 0.5, then
<syntaxhighlight lang=lua inline>wesnoth.zoom(2)</syntaxhighlight>
sets it to 2, while
<syntaxhighlight lang=lua inline>wesnoth.zoom(2, true)</syntaxhighlight>
sets it to 1 (2 * 0.5).

This function also returns the resulting zoom level. Because of this, you can call
<syntaxhighlight lang=lua inline>wesnoth.zoom(1, true)</syntaxhighlight>
to simply get the current zoom level.

Note that this function cannot zoom to a level that the user would not be able to reach from the UI. Attempting to do so will simply select the nearest allowed zoom level.

=== wesnoth.interface.skip_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.skip_messages'''([''skip?''])

Sets the skip messages flag. By default it sets it to true, but you can also pass false to unset the flag.

=== wesnoth.interface.is_skipping_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.is_skipping_messages'''()

Returns true if messages are currently being skipped, for example because the player has chosen to skip replay, or has pressed escape to dismiss a message.

=== wesnoth.interface.add_chat_message ===

* {{LuaGameOnly}} '''wesnoth.interface.add_chat_message'''([''speaker'',] ''message'')

Displays a string in the onscreen chat. The chat line speaker is "Lua" by default, but it can be changed by passing a string before the message.

<syntaxhighlight lang=lua>
wesnoth.interface.add_chat_message "Hello World!" -- will result in "<Lua> Hello World!"
wesnoth.interface.add_chat_message("Big Brother", "I'm watching you.") -- will result in "<Big Brother> I'm watching you."
</syntaxhighlight>

See also [[LuaAPI/wml#wml.error|wml.error]] for displaying error messages.

=== wesnoth.interface.clear_chat_messages ===

* {{LuaGameOnly}} '''wesnoth.interface.clear_chat_messages'''()

Removes all messages from the onscreen chat, including error messages.

=== wesnoth.interface.add_item_image ===

* {{LuaGameOnly}} '''wesnoth.interface.place_item_image'''(''location'', ''filename'')

Places an image at a given location and registers it as a WML ''[item]'' would do, so that it can be restored after save/load. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.place_item_image(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.add_item_halo ===

* {{LuaGameOnly}} '''wesnoth.interface.place_item_halo'''(''location'', ''filename'')

Behaves the same as [[#wesnoth.interface.add_item_image]] but for halos.

=== wesnoth.interface.remove_item ===

* {{LuaGameOnly}} '''wesnoth.interface.remove_item'''(''location'', [''filename''])

Removes an overlay set by [[#wesnoth.interface.add_item_image]] or [[#wesnoth.interface.add_item_halo]]. If no filename is provided, all the overlays on a given tile are removed. Note that the location must be passed as separate x and y coordinates, as in the example.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_item(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.get_items ===

* {{LuaGameOnly}} '''wesnoth.interface.get_items'''(''location'') → ''array of item tables''

Get all items placed on the specified location. Note that the location must be passed as separate x and y coordinates.

=== wesnoth.interface.add_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.add_hex_overlay'''(''location'', ''item_wml'')

Places a hex overlay (either an image or a halo) on the given location. The overlay is described by a table supporting the same fields as [[InterfaceActionsWML|[item]]]. This is a lower-level version of the item functions above. Note that the overlay is not kept over save/load cycles.

<syntaxhighlight lang=lua>
wesnoth.interface.add_hex_overlay(17, 42, { image = "items/orcish-flag.png" })
</syntaxhighlight>

=== wesnoth.interface.remove_hex_overlay ===

* {{LuaGameOnly}} '''wesnoth.remove_hex_overlay'''(''location'', [''filename''])

Removes all the overlays at the given location, including any added by '''wesnoth.interface.add_item_halo''' or '''wesnoth.interface.add_item_image''' (however, such a removal will not be kept over save/load cycles). If a filename is passed as a third argument, only this overlay (either image or halo) is removed.

<syntaxhighlight lang=lua>
wesnoth.interface.remove_hex_overlay(17, 42, "items/orcish-flag.png")
</syntaxhighlight>

=== wesnoth.interface.end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.end_turn'''([''next_side''])

Immediately ends the current side's turn. By default, the next sequential side will gain control, but if you pass an argument that side gains control instead.

The ''next_side'' can either be a valid side number, or a valid side number plus the total number of sides in the scenario. In the latter case, this function also increases the turn counter by 1.

Using this, it's entirely possible to pass control around without ever increasing the turn counter.

=== wesnoth.interface.allow_end_turn ===

* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''allow'')
* {{LuaGameOnly}} '''wesnoth.interface.allow_end_turn'''(''reason'')

Enables or disables ending the turn in the UI. You can optionally pass a translatable string to show to the player if they attempt to do so anyway. It will be shown to the player without any additional framing, so it should normally be phrased similar to "You cannot end your turn because...".

To allow the player to end their turn again, just pass '''true'''. If you pass '''false''', a default message will be shown.

=== wesnoth.interface.color_adjust ===

* {{LuaGameOnly}} '''wesnoth.interface.color_adjust'''(''red'', ''green'', ''blue'')

Adjust the screen tint. (0,0,0) is no tint, and possible values range from -255 to 255.

=== wesnoth.interface.add_overlay_text ===

{{DevFeature1.17|3}}

* {{LuaGameOnly}} '''wesnoth.interface.add_overlay_text'''(''text'' [, ''options'']) → ''text handle''

Adds a text overlay to the screen that does not move with the map. [[Pango formatting]] is supported. The ''options'' table supports the following keys:

* ''size'' - The font size.
* ''max_width'' - Sets the maximum width the text can occupy on the screen, either in screen units (pixels) or as a percentage (a string ending in <tt>%</tt>). If the text is too long to fit in that width, it will automatically be word-wrapped. Defaults to 100%.
* ''color'' - The text color, either as a six-digit hex string (no leading <tt>#</tt>) or an array of three integers (red, green, and blue).
* ''bgcolor'' - If present, a background in this color is placed behind the text to enhance readability. This works like the background behind chat messages, but can be any colour. It is formatted the same as ''color''. If omitted, the background is fully transparent (ie, there is no background).
* ''bgalpha'' - If a background colour is specified, this sets its transparency. The default is fully opaque.
* ''duration'' - How long the text should be displayed, in milliseconds, or the string <syntaxhighlight lang=lua inline>'unlimited'</syntaxhighlight> for an infinite duration. Defaults to two seconds.
* ''fade_time'' - When the label is removed, either explicitly or because its duration expired, this is the time it takes to fade out, in milliseconds. A value of 0 means the label disappears instantly. Defaults to 100.
* ''halign'' - Where to anchor the text horizontally on the screen. Must be one of <syntaxhighlight lang=lua inline>'left', 'center', 'right'</syntaxhighlight>.
* ''valign'' - Where to anchor the text vertically on the screen. Must be one of <syntaxhighlight lang=lua inline>'top', 'center', 'bottom'</syntaxhighlight>.
* ''location'' - The screen offset where the text should be placed, relative to the specified anchor. Defaults to (0,0).

The text handle returned from this function supports the following method calls:

* ''handle'':'''move'''(''x'', ''y'')

Moves the text to a new location on the screen. The provided ''x'' and ''y'' are offsets from its current location.

* ''handle'':'''remove'''([''fade_time''])

Remove the text from the screen, optionally overriding the fade-out time.

* ''handle'':'''replace'''(''text'', ''options'') → ''handle''

Replaces the text with new text. Options are the same as in ''add_overlay_text'', and the returned handle is the same one.

=== wesnoth.interface.handle_user_interact ===

{{DevFeature1.17|6}}

* {{LuaGameOnly}} '''wesnoth.interface.handle_user_interact'''()

Handle user interaction with the game interface. This can be inserted into Lua code that takes a long time to execute in order to prevent the user interface from freezing.

== wesnoth.interface.game_display ==

* {{LuaGameOnly}} '''wesnoth.interface.game_display'''.''theme_item'' ↔ '''function'''() → ''wml table of theme elements''

This is an associative table linking item names to functions that describe the content of the in-game user interface. These functions are called with no arguments whenever the user interface is refreshed, and must return a WML table containing '''[element]''' children. Each subtag shall contain either a '''text''' or an '''image''' field that is displayed to the user. It can also contain a '''tooltip''' field that is displayed to the user when moused over, and a '''help''' field that points to the help section that is displayed when the user clicks on the theme item.

Note that the '''wesnoth.interface.game_display''' cannot be iterated using '''pairs''' or '''next''' to retrieve the items from the current theme. However, built-in items ''can'' be recovered as long as their name is known. The example below shows how to modify the ''unit_status'' item to display a custom status:

<syntaxhighlight lang=lua>
local old_unit_status = wesnoth.interface.game_display.unit_status
function wesnoth.interface.game_display.unit_status()
local _ = wesnoth.textdomain "mydomain"
local u = wesnoth.interface.get_displayed_unit()
if not u then return {} end
local s = old_unit_status()
if u.status.entangled then
table.insert(s, wml.tag.element {
image = "entangled.png",
tooltip = _"entangled: This unit is entangled. It cannot move but it can still attack."
})
end
return s
end
</syntaxhighlight>

The things that would need to be to modified in the above code are:

* the domain of your addon ("mydomain"), assuming that you are using translations. Otherwise just remove the underscore in the tooltip line.
* the name of the status (u.status.entangled). Note that if the attribute happens to be inside [variables], so be it: u.variables.whatever.
* the path to the image ("entangled.png").
* the tooltip of the status ("entangled: This unit ...").

The following is a list of valid entries in '''wesnoth.interface.game_display''' which will have an effect in the game, together with sample output and a brief description of their use.

=== unit_name ===

Shows the name of the unit the mouse is hovering over.

=== unit_type ===

Shows the type of the unit the mouse is hovering over.

=== unit_race ===

Shows the race of the unit the mouse is hovering over.

=== unit_side ===

Shows the side number and team color of the unit the mouse is hovering over.

=== unit_level ===

Shows the level of the unit the mouse is hovering over.

=== unit_amla ===

Similar to unit_advancement_options but shows AMLAs only.

=== unit_traits ===

Shows the list of trait names for the unit the mouse is hovering over.

=== unit_status ===

Shows the status icons for statuses afflicting the unit the mouse is hovering over.

=== unit_alignment ===

Shows the alignment of the unit the mouse is hovering over.

=== unit_abilities ===

Shows the ability names of the unit the mouse is hovering over.

=== unit_hp ===

Shows the current and maximum hit points of the unit the mouse is hovering over.

=== unit_xp ===

Shows the current and target experience points of the unit the mouse is hovering over.

=== unit_advancement_options ===

Shows the options the unit the mouse is hovering over has for advancement, including both level ups and AMLAs. This item is not used in the default theme.

=== unit_defense ===

Shows the defense of the unit the mouse is hovering over.

=== unit_vision ===

Shows the current and maximum vision points of the unit the mouse is hovering over.

=== unit_moves ===

Shows the current and maximum movement points of the unit the mouse is hovering over.

=== unit_weapons ===

Shows the available weapons of the unit the mouse is hovering over. The default generator expresses each weapon line (basic details, specials, etc) as a separate <code>element</code>. For example:

<syntaxhighlight lang=wml>
[element]
image="melee.png"
tooltip="...stuff..."
[/element]
[element]
image="arcane.png"
tooltip="...stuff..."
[/element]
[element]
text="6×3 holy sword"
tooltip="...stuff..."
[/element]
[element]
# This is empty if the range and type icons both exist.
text="melee-arcane"
tooltip="...stuff..."
[/element]
# If the weapon has accuracy or parry...
[element]
text="+20%/-10%"
tooltip="Accuracy: +20%
Parry: -10%
"
[/element]
# If the weapon has special abilities...
[element]
text="magical"
tooltip="...stuff..."
[/element]
</syntaxhighlight>

=== unit_image ===

Shows the sprite of the unit the mouse is hovering over.

=== unit_profile ===

Shows the portrait of the unit the mouse is hovering over.

=== selected_unit ===

Nearly every item beginning with '''unit_''' has a corresponding item beginning with '''selected_unit_''', which describes the currently-selected unit (if any) rather than the unit the mouse is hovering over. These items are not used in the default theme.

There is no '''selected_unit_amla''' however.

=== highlighted_unit_weapons ===

This is almost the same as '''selected_unit_weapons''' but with slightly different logic of choosing which unit to show.

=== tod_stats and selected_tod_stats ===

Shows the time of day stats for the hex the mouse is hovering over or the hex the selected unit is on. The time of day stats shows the counter of your position in the schedule as well as the entire cycle.

=== time_of_day and selected_time_of_day ===

Shows the time of day image for the hex the mouse is hovering over or the hex the selected unit is on.

=== unit_box ===

This is an experimental item that combines a unit display and the time of day.

=== turn ===

Shows the current turn count.

=== gold ===

Shows the amount of gold for the active side.

=== villages ===

Shows the number of villages owned by the active side.

=== num_units ===

Shows the number of units owned by the active side.

=== upkeep ===

Shows the upkeep and expenses for the active side.

=== income ===

Shows the income for the active side

=== terrain_info ===

Shows the icons of the terrain on hex the mouse is hovering over.

=== terrain  ===



Shows the name of the terrain on the hex the mouse is hovering over. For example:

<syntaxhighlight lang=wml>
[element]
text="Grassland (Flat)"
[/element]
</syntaxhighlight>

=== position ===

Shows the map coordinates of the hex the mouse is hovering over.

=== zoom_level ===

Shows the zoom level as a percentage. This item is not used in the default theme.

=== side_playing ===

Shows the active side's flag.

=== observers ===

When there is no observer, it returns an empty table. When there are observers, it returns:

<syntaxhighlight lang=wml>
[element]
tooltip="Observers
<observer1>
<observer2>
"
image="misc/eye.png"
[/element]
</syntaxhighlight>

=== report_clock ===

This returns the current time in HH:MM format according to the user's preferences, for example:

<syntaxhighlight lang=wml>
[element]
text="22:32"
[/element]
</syntaxhighlight>

=== report_countdown ===

This returns the current chess-timer countdown in MM:SS format for the player's turn, for example:

<syntaxhighlight lang=wml>
[element]
text="12:43"
[/element]
</syntaxhighlight>

Depending on the turn limit, it may also be colored using Pango markup.

[[Category:Lua Reference]]

Micro AIs

2022-06-27T14:47:06Z

Mattsc: /* Custom Micro AIs */ add new syntax for keys tables

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag placed in an event, requiring only a few lines of WML code. {{DevFeature1.15|?}} Starting in 1.16 the [micro_ai] tag may also be used in [side][ai] or [unit][ai]. These are both shorthands for placing it in the prestart event with "action=add", side set to the side, and in the case of [unit][ai], a [filter] tag set to limit the Micro AI to that one unit.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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. The exception is the ''[avoid]'' tag which is taken into account by many Micro AIs (except those for which it would interfere with the Micro AI behavior or those that already use a a [[StandardLocationFilter|Standard Location Filter]] that can be used for the same purpose). 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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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. This behavior is intentional to help UMC authors note where units might have made suicidal mistakes.
* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Assassin Squad Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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''': (integer) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 recruiting used in the Experimental AI [[Experimental_AI#Recruitment|as described here]].

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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.
* {{DevFeature1.17|6}} '''reset_cache_each_turn'''=no: (bool) Many of the operations of the rush recruitment evaluation are expensive and are therefore cached. For the most part, this cache can be kept from turn to turn, but in case there are events that change, for example, the map or the recruit list, this parameter can be set to 'yes' to force a reset of the cache each turn.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed. {{DevFeature1.17|6}} In order to enable better error handling, the syntax of this table has been changed. It is now of format <syntaxhighlight lang='lua' inline>{ param1 = 'param1_type', ... }</syntaxhighlight>. The supported parameter types can be found at the link to examples below.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags). {{DevFeature1.17|6}} The format of this table has been changed in the same way as for 'required'. Also, a warning message is now issued if the '[micro_ai]' tag contains a key or tag that is not listed in either 'required' or 'optional'.
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2022-06-26T13:47:48Z

Mattsc: /* A Few General Words about Micro AIs */ [avoid] is taken into account by many MAIs

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag placed in an event, requiring only a few lines of WML code. {{DevFeature1.15|?}} Starting in 1.16 the [micro_ai] tag may also be used in [side][ai] or [unit][ai]. These are both shorthands for placing it in the prestart event with "action=add", side set to the side, and in the case of [unit][ai], a [filter] tag set to limit the Micro AI to that one unit.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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. The exception is the ''[avoid]'' tag which is taken into account by many Micro AIs (except those for which it would interfere with the Micro AI behavior or those that already use a a [[StandardLocationFilter|Standard Location Filter]] that can be used for the same purpose). 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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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. This behavior is intentional to help UMC authors note where units might have made suicidal mistakes.
* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Assassin Squad Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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''': (integer) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 recruiting used in the Experimental AI [[Experimental_AI#Recruitment|as described here]].

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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.
* {{DevFeature1.17|6}} '''reset_cache_each_turn'''=no: (bool) Many of the operations of the rush recruitment evaluation are expensive and are therefore cached. For the most part, this cache can be kept from turn to turn, but in case there are events that change, for example, the map or the recruit list, this parameter can be set to 'yes' to force a reset of the cache each turn.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2022-06-24T21:53:10Z

Mattsc: /* Hang Out specific keys for the [micro_ai] tag: */

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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. This behavior is intentional to help UMC authors note where units might have made suicidal mistakes.
* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Assassin Squad Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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''': (integer) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 recruiting used in the Experimental AI [[Experimental_AI#Recruitment|as described here]].

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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.
* {{DevFeature1.17|6}} '''reset_cache_each_turn'''=no: (bool) Many of the operations of the rush recruitment evaluation are expensive and are therefore cached. For the most part, this cache can be kept from turn to turn, but in case there are events that change, for example, the map or the recruit list, this parameter can be set to 'yes' to force a reset of the cache each turn.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

LuaAPI/ai

2022-06-23T11:28:01Z

Mattsc: /* ai.aspects */ add allow_ally_villages

<div class="tright"> __TOC__ </div>

Code executed by [[Wesnoth AI]] components has access to the <tt>ai</tt> module, which contains functions for controlling the AI and querying AI information. Thus, all functions on this page are only available to AI code.

== Game State Queries ==

=== ai.read_only ===

* {{LuaGameOnly}} '''ai.read_only''' → ''boolean''

The AI module operates in two modes: read-only, and read-write. Read-write mode is used in the execution function for stages and candidate actions, while read-only mode is used in goals and aspects and in the evaluation function for candidate actions. The '''read_only''' key allows you to distinguish these cases at runtime, if necessary. Functions that are only available in read-write mode will be tagged (mutable) in the descriptions on this page.

=== ai.side ===

* {{LuaGameOnly}} '''ai.side''' → ''number''

The side number that the AI module is bound to.

=== ai.aspects ===

* {{LuaGameOnly}} '''ai.aspects'''.''aspect'' → ''value''

Provides access to the aspects of the AI engine. This fetches the result of the aspect evaluation given the game state when it was last refreshed (see [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|aspect invalidation rules]]), not its definition. So, for example, '''ai.aspects.avoid''' returns the list of avoided hexes, not the
[[StandardLocationFilter|Standard Location Filter]] that produced them, and a [[#Dynamic_Lua_Aspects|dynamic Lua aspect]] will return the result of calling the function, not the function itself. For more details, see the definition of each aspect on [[AiWML]].

The following aspects return scalar values (numbers, strings, or booleans):
* '''aggression'''
* '''allow_ally_villages''' {{DevFeature1.17|6}}
* '''caution'''
* '''grouping'''
* '''leader_aggression'''
* '''leader_ignores_keep'''
* '''leader_value'''
* '''passive_leader'''
* '''passive_leader_shares_keep'''
* '''recruitment_diversity'''
* '''recruitment_randomness'''
* '''retreat_enemy_weight'''
* '''retreat_factor'''
* '''scout_village_targeting'''
* '''simple_targeting'''
* '''support_villages'''
* '''village_value'''
* '''villages_per_scout'''

The following aspects return tables:

* '''advancements''' – the values of a [[LuaAPI/location_set|location set]] mapping locations to a list of possible advancements for the unit on that hex. To convert this to a fully functional standard location set:
*:<syntaxhighlight lang=lua>
local location_set = wesnoth.require "location_set"
local ls = location_set.create()
ls.values = ai.aspects.advancements
-- Now you can use it as a regular location set
print(ls[{5,6}]) -- might print out {"Elvish Hero", "Elvish Captain"} for example
</syntaxhighlight>
*:{{DevFeature1.17|?}} It's now even simpler to convert:<syntaxhighlight lang=lua>
local location_set = wesnoth.require "location_set"
local ls = location_set.of_raw(ai.aspects.advancements)
</syntaxhighlight>
* '''attacks''' – a table with keys '''own''' containing all units that may attack and '''enemy''' containing all units that may be attacked.
* '''avoid''' – an array of locations.
* '''leader_goal''' – the WML content of the leader_goal aspect
* '''recruitment_instructions''' – the WML content of the recruitment_instructions aspect
* '''recruitment_more''' – an array of strings where each string is a usage, a unit type ID, or an integer
* '''recruitment_pattern''' – an array of usage strings (see [[UnitTypeWML]] for an explanation of usage)
* '''recruitment_save_gold''' – the WML content of the recruitment_save_gold aspect

=== ai.get_attacks ===

* {{LuaGameOnly}} '''ai.get_attacks'''() → ''array of attack analyses''

Get all possible attacks the AI is able to perform, and an analysis of each. If multiple AI units can attack the same enemy, all different combinations of AI units are listed. However, for a given combination of AI units, only one attack (the one the AI considers best) is listed. In other words, permutations of those units placed on different hexes are not included, as that would result in too long a list.

Each attack analysis table has the following keys:

* ''analysis''.'''rating'''() → ''numeric rating''
* ''analysis''.'''movements''' → ''array of location pairs''
** ''move''.'''src''' → ''location''
** ''move''.'''dst''' → ''location''
* ''analysis''.'''target''' → ''location''
* ''analysis''.'''target_value''' → ''number''
* ''analysis''.'''avg_losses''' → ''number''
* ''analysis''.'''chance_to_kill''' → ''probability''
* ''analysis''.'''avg_damage_inflicted''' → ''number''
* ''analysis''.'''target_starting_damage''' → ''integer''
* ''analysis''.'''avg_damage_taken''' → ''number''
* ''analysis''.'''resources_used''' → ''number''
* ''analysis''.'''terrain_quality''' → ''number''
* ''analysis''.'''alternative_terrain_quality''' → ''number''
* ''analysis''.'''vulnerability''' → ''number''
* ''analysis''.'''support''' → ''number''
* ''analysis''.'''leader_threat''' → ''boolean''
* ''analysis''.'''uses_leader''' → ''boolean''
* ''analysis''.'''is_surrounded''' → ''boolean''

=== ai.get_targets ===

* {{LuaGameOnly}} '''ai.get_targets'''() → ''array of targets''

Get a list of all the current AI targets. Each target has the following keys:

* '''loc''': The coordinates of the target, as a 2-element array.
* '''type''': The type of target, as a string.
* '''value''': The value of the target, as a real number.

The possible target types are <syntaxhighlight lang='lua' inline>'village', 'leader', 'explicit', 'threat', 'battle aid', 'mass', 'support'</syntaxhighlight>. More information on the meaning of each type can be found in the [[LuaAI#Lua_Goals_and_Targets|LuaAI documentation]].

=== ai.suitable_keep ===

* {{LuaGameOnly}} '''ai.suitable_keep'''(''unit'') → ''x'', ''y''

This returns the location of the closest keep to the unit passed as argument.

== Move Maps ==

* {{LuaGameOnly}} '''ai.get_dst_src'''() → ''move map''
* {{LuaGameOnly}} '''ai.get_src_dst'''() → ''move map''
* {{LuaGameOnly}} '''ai.get_enemy_dst_src'''() → ''move map''
* {{LuaGameOnly}} '''ai.get_enemy_src_dst'''() → ''move map''

These functions return move maps – tables that relate the current positions of units with the hexes they can move to. A move map is a [[LuaAPI/location_set|location set]], similar to the advancements map, which can be converted to a standard location set with the following code:

<syntaxhighlight lang=lua>
local location_set = wesnoth.require "location_set"
local ls = location_set.create()
ls.values = ai.get_dst_src()
-- Now you can use it as a regular location set
print(ls[{1,4}]) -- prints out something like {{5,4},{5,3}} or the like
</syntaxhighlight>
{{DevFeature1.17|?}} It's now even simpler to convert:<syntaxhighlight lang=lua>
local location_set = wesnoth.require "location_set"
local ls = location_set.of_raw(ai.get_dst_src())
</syntaxhighlight>

These functions are defined in ''ai/lua/stdlib.lua'', which is loaded by default if you allow the game to implicitly define a Lua [engine] tag. However, if you require a custom Lua [engine] tag, it must load this file manually with the following code in order to use these functions:

<syntaxhighlight lang='lua'>
local ai_stdlib = wesnoth.require('ai/lua/stdlib.lua')
ai_stdlib.init(ai)
</syntaxhighlight>

* {{LuaGameOnly}} '''ai.recalculate_move_maps'''()
* {{LuaGameOnly}} '''ai.recalculate_enemy_move_maps'''()

Force the move maps to be recalculated. This might be necessary if you've moved units around using '''wesnoth.units.to_map'''.

== AI Actions ==

All these functions instruct the AI to check or perform a specific action, and return a result table indicating the success of the action. The table has the following keys:

* '''gamestate_changed''': a boolean indicating whether anything actually changed as a result of the action
* '''ok''': a boolean indicating the success of the action
* '''status''': a numeric status code indicating why the action failed
* '''result''': a string error code indicating why the action failed

=== ai.attack ===

* {{LuaGameOnly}} (mutable) '''ai.attack'''(''attacker'', ''defender'', ''weapon'', [''aggression'']) → ''result''

Execute attack by ''attacker'' against ''defender''. If ''weapon'' is provided, it is the number of the weapon to be used (count starts at 1, not 0, as always in Lua), otherwise the choice of the weapon is left to the AI engine. If ''aggression'' is provided, it is used to influence the choice of the best weapon. Obviously, this only makes sense if this choice is left to the engine, that is, if ''weapon'' is set to either 'nil' or '-1'.

=== ai.check_attack ===

* {{LuaGameOnly}} '''ai.check_attack'''(''attacker'', ''defender'', ''weapon'', [''aggression'']) → ''result''

Similar to '''ai.attack''', but does not execute the attack – it merely checks if it would succeed.

=== ai.move ===

* {{LuaGameOnly}} (mutable) '''ai.move'''(''unit'', ''to'') → ''result''

Execute a "partial" move of ''unit'' to hex (''to.x'', ''to.y''). A "partial" move means that the unit keeps whatever movement points it has left after the move.

=== ai.move_full ===

* {{LuaGameOnly}} (mutable) '''ai.move_full'''(''unit'', ''to'') → ''result''

Execute a "full" move of ''unit'' to hex (''to.x'', ''to.y''). A "full" move means that the unit's movement points are set to zero at the end of the move.

=== ai.check_move ===

* {{LuaGameOnly}} '''ai.check_move'''(''unit'', ''to'') → ''result''

Similar to '''ai.move''' or '''ai.move_full''', but does not execute the move – it merely checks if it would succeed.

=== ai.recall ===

* {{LuaGameOnly}} (mutable) '''ai.recall'''(''unit_id'', [''location'']) → ''result''

Recall the unit with id ''unit_id''. An optional recruit location can be given. If the location is omitted, a suitable hex is automatically chosen by the AI engine.

{{DevFeature1.17|0}} The location may be specified as an object (for example, <tt>{x,y}</tt> or a unit) rather than separate ''x'' and ''y'' parameters.

=== ai.check_recall ===

* {{LuaGameOnly}} '''ai.check_recall'''(''unit_id'', [''location'']) → ''result''

Similar to '''ai.recall''', but does not execute the recall – it merely checks if it would succeed.

=== ai.recruit ===

* {{LuaGameOnly}} (mutable) '''ai.recruit'''(''unit_type'', [''location'']) → ''result''

Recruit a unit of type ''unit_type''. An optional recruit location can be given. If the location is omitted, a suitable hex is automatically chosen by the AI engine.

{{DevFeature1.17|0}} The location may be specified as an object (for example, <tt>{x,y}</tt> or a unit) rather than separate ''x'' and ''y'' parameters.

=== ai.check_recruit ===

* {{LuaGameOnly}} '''ai.check_recruit'''(''unit_type'', [''location'']) → ''result''

Similar to '''ai.recruit''', but does not execute the recruit – it merely checks if it would succeed.

=== ai.stopunit_attacks ===

* {{LuaGameOnly}} (mutable) '''ai.stopunit_attacks'''(''unit'') → ''result''

Remove remaining attacks from ''unit''. This is equivalent to setting <code>attacks_left=0</code>.

=== ai.stopunit_moves ===

* {{LuaGameOnly}} (mutable) '''ai.stopunit_moves'''(''unit'') → ''result''

Remove remaining movement points from ''unit''. This is equivalent to setting <code>moves=0</code>.

=== ai.stopunit_all ===

* {{LuaGameOnly}} (mutable) '''ai.stopunit_all'''(''unit'') →

Remove both remaining attacks and remaining movement points from ''unit''.

=== ai.check_stopunit ===

* {{LuaGameOnly}} '''ai.check_stopunit'''(''unit'') → ''result''

Similar to '''ai.stopunit_attacks''', '''ai.stopunit_moves''', or '''ai.stopunit_all''', but does not execute the stop – it merely checks if it would succeed.

=== ai.fallback_human ===

* {{LuaGameOnly}} (mutable) '''ai.fallback_human'''()

Hands over control of this side to the local human player until the end of the current turn. This action does not return a result; it always succeeds.

== See Also ==

There are two other functions that are not in the AI module but are important for AI coding:

* [[LuaAPI/wesnoth/sides#wesnoth.sides.debug_ai|wesnoth.sides.debug_ai]]
* [[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]]

[[Category:Lua Reference]]

AiWML

2022-06-22T23:20:03Z

Mattsc: /* List of AI Aspects */ add allow_ally_villages aspect

{{WML Tags}}

== Customizing the Default AI Using WML ==

This page describes how the behavior of the default (RCA) AI can be customized using simple WML commands. The descriptions below assume a basic understanding of how the RCA AI evaluates moves, what '''candidate actions''', '''aspects''' and '''goals''' are, and how they interact. If you do not know these things yet, check out the [[RCA AI]] page.

This page contains:
* Descriptions of the aspects and goals of the default AI
* Instructions for setting them up at the beginning of the scenario in a [side] tag

This page does '''not''' contain:
* Instructions for [[LuaAI#Dynamic_Lua_Aspects|setting up aspects dynamically using Lua]].
* Instructions for [[Modifying_AI_Components#Modifying_Standard_Aspects|changing aspects and goals mid scenario]], although for many of them (for example, for all [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]]) the methods are almost identical
* Instructions for some of the [[Modifying_AI_Components|more complex AI customization tasks]].
* Anything about [[Micro_AIs|MicroAIs]]
* [[AI_Recruitment|Advanced recruitment details]]

== Defining Aspects and Goals of the RCA AI ==

[[RCA_AI#Use_of_Aspects_in_the_RCA_AI|Aspects]] and [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|goals]] of the [[RCA_AI|default (RCA) AI]] can be defined at the beginning of a scenario with [ai] tags inside the [side] tags. They are used to customize certain aspects of the AI. The [ai] tag, when used for this purpose, takes the [[#List_of_AI_Aspects|aspects themselves]] as arguments, as well as the following general keys:
* '''time_of_day''': (string) The time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/schedules.cfg data/core/macros/schedules.cfg] (see also [[TimeWML]]). Note that it is the ''id'' (not the ''name'') of the time of day that needs to be used here. Also note that this aspect did not work for a long time due to a bug (versions 1.7.4 - 1.11.6). It has been fixed for BfW 1.11.7.

* '''turns''': (string) During which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes (-) and commas (,) as is described under Filtering Locations in [[FilterWML]], except of course they apply to turns not locations.

* '''ai_algorithm''': (string) Allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game only comes with ''idle_ai'', which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys ''turns'' and ''time_of_day'', but must be given either in an [ai] tag without the aforementioned keys or in the [side] tag outside all [ai] tags. {{DevFeature1.13|5}} In 1.13, the meaning of '''ai_algorithm''' has changed and no longer selects a native AI that's built into the engine, as the RCA AI has now become the core system and no alternatives exist anymore. Instead, it selects a predefined ''[ai]'' definition, such as those defined in ''data/ai/ais''. Since these are defined in WML, you can easily build your own.

An example of a simple use of the [ai] tag to set AI parameters (aspects) is

<syntaxhighlight lang=wml>
[ai]
time_of_day=dusk
aggression=0.99
caution=0.01
[avoid]
[filter]
side=2,3
[/filter]
radius=2
[/avoid]
[/ai]
</syntaxhighlight>

'''Important Note:''' If you use a different AI engine ([[FormulaAI]] or [[LuaAI]]) for a side, setting aspects in the [side] tag might not work due to a bug in the AI setup mechanism (or it might; there's no general rule that catches all cases). In that case, you might have to use [modify_side][ai] in a ''prestart'' or ''start'' event instead. If unsure, you can use <code>:inspect</code> in debug mode to verify whether an aspect was changed successfully.

==List of AI Aspects==

'''Note:''' Only one instance of each aspect will be active for a side at any time. Where multiple instances of the same aspect are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''advancements''': (string) Defines a list of unit types to which AI units can advance. If a unit type is listed here, units that can advance to this type will <u>only</u> advance to this type, even if they have, in principle, several advancement options. As an example, if this aspect is set to 'Javelineer,Elvish Hero', then all Spearmen advance to Javelineers, and all Elvish Fighters advance to Elvish Heroes. All other units follow their usual advancement choices as determined by the AI. '''Important notes:'''
** This is a simplified version of the more complex (and arguably more useful) application of a dynamic Lua ''advancements'' aspect, as described [[LuaAI#The_advancements_Aspect|here]].
** The ''advancements'' aspect only takes effect during the AI turn, that is, on offense only, not on defense.
** Listing more than one advancement unit type for a given unit still results in only one of the types being used (generally the one listed last).

* '''aggression'''=0.4: (double: ranging from -infinity to 1.0) This key affects how the AI selects its attack targets. The higher the value, the more likely the AI is to attack even if odds are not in its favor. The description below applies as written to the ''combat'' CA only, but aggression is taken into account by the ''high_xp_attack'' and ''spread_poison'' CAs as well (as of '''Wesnoth 1.13.5''' and '''1.15.3''' respectively).
** '''Important: do not set aggression to values greater than 1''' as this makes the AI ''prefer'' attacks in which it receives more damage (see below) unless that is specifically the effect you want to achieve.
** In the attack evaluation, each attack (this includes attack combinations of several AI units against the same enemy unit) is assigned a score. The attack with the highest score is done first. Then the next attack is evaluated, until no attack with a score greater than 0 is found any more. (Note that this ''attack score'' is different from the ''combat CA score'', which is always 100,000 as long as an individual attack score >0 is found. The combat CA score is zero if the highest attack score is <=0).
** The attack score is a complex combination of many different aspects of the attacks. Positive (additive) contributions to the score are things like the value (cost and XP) of the target, the chance to kill the target, whether it is already wounded, how much damage the attack is likely to inflict, etc. Negative (additive) factors include how much damage the AI's units are likely to take, how valuable they are, how exposed they will be after the attack, etc. There are also multiplicative factors that are used if the attack target is a threat to the AI's leader etc.
** All the negative contributions to the score are multiplied by '(1-aggression)'. This means that:
*** If 'aggression=1', no negative contributions are added to the score. Thus, the AI disregards damage done to its own units and selects attacks based solely on the damage it can do to enemy units. If the AI can inflict 1 damage and take 0, or inflict 2 damage and take 20, it will take the latter option.
*** The smaller the value of ''aggression'', the more weight is put on value of and potential damage to the AI's units as compared to the attack target.
*** Roughly speaking, 'aggression=0' results in the AI valuing its units approximately as much as the enemy units. This is not a one-to-one relation, but can be used as an approximate guideline.
*** Very large negative values of ''aggression'' mean that the value of the AI's units is much more important than that of the enemy units. As a result, the AI never attacks unless it will receive no damage in exchange.
*** The rating for damage received in an attack actually becomes a positive contribution to the score for values of aggression larger than 1. This usually does not result in sensible behavior and values greater than 1 should therefore not be used.
** Note: ''aggression'' is always set to 1.0 for attacks on units that pose a direct threat to the AI's leader. Currently this only means units adjacent to the leader.

*'''allow_ally_villages'''=no (bool) {{DevFeature1.17|6}} Affects ''retreat-injured'' CA only. Normally, the AI is not allowed to take villages from an ally. If this is set to 'yes', the AI may retreat injured units to allied villages (and thereby capture them).

*'''[attacks]''': Filters the units considered for combat, both on the AI and the enemy sides. Applies to the ''combat'', ''high_xp_attacks'' and ''spread_poison'' CAs only. It cannot be set in the same way as the other aspects and is therefore described in a [[#Filtering_Combat_with_the_attacks_Aspect|separate section]] below.

* '''[avoid]''': Makes the AI avoid specific locations. The AI never moves a unit to these locations except for trying to move its leader to a keep or toward [leader_goal]s, and thus applies to all CAs except ''move-leader-to-goals'' and ''move-leader-to-keep''.
** '''[[StandardLocationFilter]]''': The locations for the AI to avoid. Do not use a [filter_location] tag.
**'''Note:''' Only one instance of an [avoid] aspect will be active for a side at any time. Where multiple instances are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''caution'''=0.25: (double) Defines how cautious the AI is in several ways. It determines whether the leader should move toward [leader_goal], if attacks are worth moving onto less favorable terrain, whether units should retreat, and whether the AI should move units toward targets individually, as groups or not at all. Affects several CAs (listed in the order of their [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|evaluation scores]]):
** ''Move-leader-to-goals CA'': If ''max_risk'' is not set in [leader_goal], its default value is '1-caution'. This determines whether the leader takes the next step toward his goal. See description of [leader_goal].
** ''Combat'' CA:
*** During the evaluation of attacks, the AI considers whether the attacking units could get onto more favorable terrain if they didn't attack but moved somewhere else instead. The difference between the two terrain ratings, together with a number of other factors, determines the "exposure" rating of the units. This exposure is then subtracted from the 'attack score' as described for ''aggression'' above.
*** The exposure rating also contains a multiplication by ''caution'', meaning that 'caution=0' results in exposure not being taken into account, and that it becomes more and more important for larger values. In other words, the higher the values of ''caution'', the more reluctant is the AI to attack from unfavorable terrain. (Note that exposure is one of the negative contributions to the attack score as described for ''aggression'', and therefore is also ignored if 'aggression=1' is set.)
*** If the AI leader is used in an attack, the AI ''always'' uses 'caution=2' for the evaluation of that attack.
** ''Retreat'' CA: {{DevFeature1.15|3}} This CA has been removed.
*** If caution is greater than 0, there is an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location by either side, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat takes place, if <tt>caution × their_power > our_power</tt>. There is also a terrain factor involved if the attacker is not on optimal terrain, similar to the exposure described above for the combat CA.
*** So let's say the AI has its default caution of 0.25. Then the enemy forces have to be at least 4 times as strong before the unit retreats. For a caution of 1, as soon as the enemy is stronger, the unit retreats.
*** The AI never retreats if caution is set to 0 or lower.
** ''Move-to-targets'' CA:
*** If grouping for the AI is enabled and the path along which to move toward a target is considered to be dangerous, caution has an influence, too. "Dangerous" mainly means that there is a good chance for a unit to be killed if it's by itself. In that case, the AI compares its units to the enemy units and based on the result moves forward or not. All units that can reach the next location of the move are considered. The formula for deciding whether to move toward the target as a group is <tt>our_strength / their_strength > 0.5 + caution</tt>. If this condition holds true, units are moved toward the goal as a group, otherwise they try to group together in a location favorable for a attack on the enemy during the next turn.
***So if caution is 0.5, the AI side needs to be at least as strong as the enemy. If it is 0, the AI moves toward the target, even if the enemy is up to twice as strong as the AI. Setting caution to 1.5 means the AI needs to be at least twice as strong as the enemy.
*** The AI also considers retreating units during the move-to-target phase based on criteria similar to those for the retreat CA.

* '''grouping'''="offensive": (string) How the AI should try to group units. Applies to ''move-to-targets'' CA only. Possible values:
** ''offensive'': Makes the AI try to group units together before attacking.
** ''defensive'': Makes the AI group units together very conservatively, only advancing them much beyond its castle if it has overwhelming force.
** ''no'': Makes the AI use no grouping behavior.

* '''leader_aggression'''="-4.0": Exactly as aggression, but for units which can recruit. Applies to ''combat'' CA only. Note that the move-leader-to-keep CA has a higher score than the combat CA. A leader therefore usually only attacks if he is on his keep at the beginning of the turn, otherwise he moves toward the closest keep instead, even with ''leader_aggression=1''.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location. Applies to ''move-leader-to-goals'' CA only.
** '''x''', '''y''': The location toward which the AI should move its leader.
** '''auto_remove'''=no: (bool) If 'no' (default), the AI moves the leader to the goal, after which he stays there until [leader_goal] is [[Modifying_AI_Components#Modifying_Standard_Aspects|removed manually]]. If 'yes', the leader_goal is removed upon the leader getting there. Important: this ''only'' works if ''id'' is set correctly (see the next bullet).
** '''id'''="": (string) An internal id key of the [leader_goal] tag. An id is required for ''auto_remove'' to work. However, setting this id does not automatically set the id of the [leader_goal] [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]]. Thus, in principle for this to work, you need to set the id of the facet as described [[Modifying_AI_Components#Modifying_Standard_Aspects|here]] ''and'' set the ''id'' key in [leader_value] to the same value. Since you are probably only going to use one [leader_goal] tag at a time, there is a much simpler way: setting 'id=0' (which refers to the first facet) or 'id=*' (which means all facets) in [leader_goal] allows ''auto_remove'' to work without the extra step of setting the facet id. {{DevFeature1.13|5}} Setting this now also sets the id of the [leader_goal] facet, allowing auto_remove to work with multiple leader goals without using the fully-expanded aspect syntax.
**'''max_risk'''=1-caution: (double: meaningful values are >=0) How much risk the leader may be exposed to by moving toward the goal. For evaluating this risk, the AI multiplies the leader's hitpoints by this number. The leader is only moved toward the goal if the resulting value is larger than the expected damage the leader is going to take during the next enemy turn. Thus, 'max_risk=0' means he will only move if no attack on him is possible at the target hex of the move. 'max_risk=1' (or larger) results in him moving even if he's almost certainly going to die.

* '''leader_ignores_keep'''=no: (bool) Set to 'yes' for this aspect to apply to all leaders of a side. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list. Setting leader_ignores_keep for some or all leaders means that:
** The affected AI leaders do not move to the closest keep at the beginning of the turn. Instead, they participate in the ''move_to_targets'' candidate action (and all other CAs in which they already participated anyway, of course). Thus, these leaders behave in the same way as any other unit of the AI side.
** This also means that these AI leaders do not recruit except on the first turn if they start on a keep, or if they accidentally end up on a keep. Thus, if a leader is supposed to recruit first and then participate in the action, leader_ignores_keep should be set to 'no' at the beginning of the scenario, and be changed to 'yes' in an event later.

* '''leader_value'''=3: (double) A number 0 or higher which determines the value of enemy leaders as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets CA'' only (and therefore specifically does not apply to attacks).

* '''passive_leader'''=no: (bool) If 'yes', the AI leader never moves or attacks, not even to move back to the keep (unless 'passive_leader_shares_keep=yes' is set) or to attack adjacent units, except to obey [leader_goal]s. Affects all CAs except ''recruitment'' and ''move-leader-to-goals''. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

* '''passive_leader_shares_keep'''=no: (bool) If 'yes', lets the AI leader moves off the keep to share it with allied leaders (if they can reach it next turn) if 'passive_leader=yes' is set. He also returns to keep to recruit when possible and attacks adjacent enemy units. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

*'''recruitment_diversity''', '''recruitment_instructions''', '''recruitment_more''', '''recruitment_pattern''', '''recruitment_randomness''', '''recruitment_save_gold''': These aspects can be used to customize recruiting with the new recruitment CA introduced in Wesnoth 1.11. They are described on a [[AI_Recruitment|separate page]].

*'''retreat_factor'''=0.25 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. Determines how injured AI units have to be before they attempt retreating. This is approximately the fraction of the units' hitpoints, but other factors play a role also, such as the terrain the units are on, and leaders and poisoned units retreat somewhat earlier. Setting this to 0 (or negative values) disables retreating. Note that even setting this to very large values still requires units to be somewhat injured before they start retreating.

*'''retreat_enemy_weight'''=1.0 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. When deciding where to retreat to, the AI considers how much healing a location provides and weighs it against the threat of all the enemies that can get there (balanced by the own units that can get there). In this evaluation, it multiplies the enemy threat rating by ''retreat_enemy_weight'', meaning that the larger its value is, the more a unit tries to move away from enemies. There are three regimes for this aspect:
** Positive values: Only locations that provide healing (both from terrain and from adjacent healers which have no MP left) are considered. For regenerating units, all hexes are treated as if they provide healing.
** Zero: Enemy threats are ignored
** Negative values: All hexes are considered for retreating. The enemy threat rating is multiplied by the absolute value of the aspect value. Thus, if very negative values are used (e.g. -100), this can be used to make units run away from enemies with little consideration for anything else.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village [[#AI_Targets_and_Goals|targets]] for scouts by this value. Affects ''move-to-targets'' CA only.

* '''simple_targeting'''=no: (bool) If 'yes', the AI moves its units toward [[#AI_Targets_and_Goals|targets]] one by one (sequentially), without considering whether another unit might be better suited for the current move or target. If 'no' (the default), all units are considered for all targets. This is slower, but might result in better moves. Affects ''move-to-targets'' CA only.

* '''support_villages'''=no: (bool) Trigger a code path that tries to protect those villages that are threatened by the enemy. This seems to cause the AI to 'sit around' a lot, so it's only used if it's explicitly enabled. Affects ''move-to-targets'' CA only.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to go for villages as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets'' CA only.

* '''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages. Affects ''recruitment'' CA only.

=== Removed AI Aspects ===

The following AI parameters (aspects) can still be set, their values can be retrieved, and they can be viewed in the gamestate inspector dialog, but they do not have an effect in the RCA AI code any more. Some other parameters will also likely be removed in the future. We will update this list accordingly. {{DevFeature1.13|5}} Except for attack_depth, these have now all been removed. {{DevFeature1.15|0}} attack_depth is now removed as well.

* '''attack_depth'''=5: (int)
* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double)
* '''recruitment''': This aspect was used to customize the recruitment of the old default AI (the one used before the RCA AI). This recruitment code is not used in the RCA AI any more. Setting recruitment instructions with this aspect is therefore meaningless. Use the '''recruitment_instructions''' aspect instead.
** It is, in principle, still possible to use this aspect together with the [[Wesnoth_AI_Framework#Recruitment_Stage|recruitment stage]], but this is discouraged for the reasons given at this link.
* '''recruitment_ignore_bad_combat'''=no: (bool)
* '''recruitment_ignore_bad_movement'''=no: (bool)

==AI Targets and Goals==

AI targets are used in the ''move-to-targets'' candidate action (CA) to move the AI's units toward selected units or locations. The AI engine automatically selects all enemy leaders, enemy units that pose a threat to the AI leader and unowned or enemy-owned villages as targets and assigns them certain [[RCA_AI#RCA_AI_Aspect_and_Goal_Configuration|base values]]. Additional targets can be defined using the [goal] tag.

It is '''very important''' to realize that these targets apply to the ''move-to-targets'' CA only and have no influence on other CAs. In particular, they have no effect whatsoever on which enemies the AI attacks. This is often a source of confusion for scenario creators. More background information on RCA AI targets and goals can be found [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|here]]. The sections below only describe how to set up goals in order to add targets for the ''move-to-targets'' CA.

===The [goal] Tag===

The [goal] tag defines units or locations as [[#AI_Targets_and_Goals|move targets]] (not attack targets!) for the AI. '''Applies to ''move-to-targets'' CA only'''. <-- That is '''extremely important''' to understand, in particular the fact that the [goal] tag has '''no influence whatsoever on attacks'''.

The following keys/tags can be used:
* '''name'''="target": (string) The following values are possible and result in different types of targets, as shown in the examples below:
** ''target'': The (default) target goal specifies target units (not necessarily enemy units) toward which the AI should move its units. {{DevFeature1.13|5}} target_unit is now a synonym for this.
** ''target_location'': Specifies target locations toward which the AI should move its units.
** ''protect_location'': Specifies locations that the AI should protect. Enemy units within the specified distance (''protect_radius'') of one of these locations are marked as targets with the provided value. Note that the AI will ''not'' station any units around the protected locations. It will only send units toward enemy units that come within ''protect_radius'' of them.
** ''protect_unit'': Specifies units (of all sides) that the AI should protect. Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.
** ''protect_my_unit'': ('''deprecated''') <s>Specifies units from the AI's own side that the AI should protect. (This is basically the ''protect_unit'' goal with an implied ''side='' in the filter, restricting matching units to the AI's side.) Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.</s>
** ''lua_goal'': A dynamically calculated goal written in Lua. See [[LuaAI#Lua_Goals_and_Targets|here]] for details on how this works.

* '''[criteria]'''="": Contains a [[StandardUnitFilter]] (for ''target'', ''protect_unit'' or ''protect_my_unit'') or [[StandardLocationFilter]] (for ''target_location'' or ''protect_location'') describing the targets.

* '''value'''=0: (double) The value of the goal.

* '''protect_radius'''=20: (int) The protection radius. Applies to ''protect_location'', ''protect_unit'' and ''protect_my_unit''.

* '''id'''="": (string) Optional ID used for [[Modifying_AI_Components#Modifying_Goals|modifying the goal]].

===Examples of [goal] Tag Usage===

'''target:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
[criteria] #NOTE: this is a SUF, because we're targeting a unit
side=3
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''target_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=target_location
[criteria] #NOTE: this is a SLF, because we're targeting a location
x,y=42,20
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_location
[criteria] #NOTE: this is a SLF, because we're protecting a location
x,y=42,20
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_unit:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria] #NOTE: this is a SUF, because we're protecting a unit
side=3
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''How to use protect_unit to protect the own leader''' (We are side 2)
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria]
side=2
canrecruit=yes
[/criteria]
protect_radius=8
value=5
[/goal]
[/ai]
</syntaxhighlight>

=== Deprecated AI Targeting Aspects ===

The following AI targeting parameters currently still work, but have been superseded by the [[#The_.5Bgoal.5D_Tag|[goal] tag]]. They should not be used any more as they will likely be removed at some point. These tags only apply to the move-to-targets CA.

* '''[target]'''="": '''Deprecated'''. Any number of [target] tags can be used to set targets for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get to a target worth '2.0' as for a target worth '1.0'. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': Do not use a [filter] tag.
** '''value'''=1: (double) A number greater than 0 (default=1) which determines how much the AI tries to move toward units which pass the filter.

* '''[protect_location]'''="": '''Deprecated'''. Gives the AI a location to protect. Note that the AI does ''not'' station any units around the location, it only sends units to attack any enemy units that come within the guarding radius of the target. Applies to move-to-targets CA only.
** '''x''', '''y''': Standard coordinates. These indicate the location the AI is protecting.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this location.

* '''[protect_unit]'''="": '''Deprecated'''. Gives the AI a set of units to protect. Note once again that the AI does not place units around the protected units if there are no enemies nearby. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this unit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: '''Deprecated'''. Target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader'. Applies to move-to-targets CA only.

== Filtering which Units Participate in which Actions==

{{DevFeature1.15|3}}

Each [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|candidate action of the default AI]] can be restricted to apply to only a subset of the AI units. This is done by adding a '''[filter_own]''' tag to the '''[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Candidate_Actions|[candidate_action]]]''' tag definition.

Typical use cases:
* Restricting an action to certain units so that other units are not used to this. For example, village grabbing could be restricted to scout units only, so that slower units do not take detours on their way toward the enemies. See the example below.
* Excluding units from a certain action in order to have them available for other actions afterward. For example, one might want to add a custom candidate action which moves healers behind injured units (or use the existing [[Micro_AIs|Micro AI]] for this). Ideally, this should happen after ''all'' other units have moved, specifically also after the move-to-targets candidate action (MtT CA) is done. In the default setting, however, the MtT CA would also move the healers. Thus, we would want to exclude them using a '''[filter_own]''' tag.
* Adding two instances of the same candidate action with different scores to force the order in which units participate in this action. For example, one could add another instance of the move-leader-to-keep CA with a '''[filter_own]''' tag restricting it to one leader, in order to make this leader move to a keep (and therefore recruit) first.

Note that for the combat AI, using the attacks aspect to filter units as described in the next section '''is slightly more efficient'''. Thus, that should be the preferred method if there are many units on the map.

Example:
<syntaxhighlight lang='wml'>
[candidate_action]
id=villages
engine=cpp
name=ai_default_rca::get_villages_phase
max_score=60000
score=60000
[filter_own]
type=Wolf Rider
[/filter_own]
[/candidate_action]
</syntaxhighlight>

== Filtering Combat with the ''attacks'' Aspect==

The ''attacks'' aspect lets us filter the units considered by the ''combat'', ''high_xp_attacks'' and ''spread_poison'' candidate actions. Units on the AI side can be selected with the '''[filter_own]''' tag and enemy units are filtered via '''[filter_enemy]''', both of which take a [[StandardUnitFilter]]. Only units defined in these tags are considered as attacker/target pairs. To define, for example, an ''attacks'' aspect in which units from the elvish sorceress line are the only attackers, and undead units are the only targets, use
<syntaxhighlight lang='wml'>
[ai]
[aspect]
id=attacks
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/aspect]
[/ai]
</syntaxhighlight>
Several important notes:
* The ''attacks'' aspect is a ''composite'' aspect and cannot be defined using the simple syntax of the other ''standard'' aspects. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|here]] for a description of the syntax of the example.
* This only works if <code>invalidate_on_gamestate_change=yes</code> is set. The reason is that the ''attacks'' aspect internally contains information about all available attacker/target pairs. These need to be recalculated after each move. This is explained [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|here]].
* If [filter_own] or [filter_enemy] are omitted, the selection defaults to all units of the respective sides.
* '''Most importantly''': The above example results in sorceress-line vs undead attacks being the <u>only</u> attacks done by the AI. No other attacks are executed, no matter how advantageous their outcomes may be. There is no simple way around that, but it can be accomplished by one of the following means:
** Setting up the [filter_own] or [filter_enemy] [[StandardUnitFilter]]s to adapt dynamically to the situation on the map.
** Adding a Lua candidate action which dynamically adjusts the aspect depending on the current situation on the map. An example of dealing with this is given in the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|Micro AI test scenario]] [https://github.com/wesnoth/wesnoth/blob/master/data/ai/micro_ais/scenarios/protect_unit.cfg ''Protect Unit''].
** Using [[LuaAI#Dynamic_Lua_Aspects|dynamic Lua aspects]] is in principle also possible, but far from easy due to the complex tables this aspect returns.

{{DevFeature1.13|5}}

Though the above code still works in 1.13.5 and later (and will continue to work indefinitely), it can also be simplified a little:
<syntaxhighlight lang='wml'>
[ai]
[attacks]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/attacks]
[/ai]
</syntaxhighlight>

'''See also:''' [[Wesnoth AI]]
[[Category: WML Reference]]
[[Category:AI]]

Experimental AI

2022-06-22T23:14:55Z

Mattsc: /* Recruitment */

== Experimental AI Summary ==

{{DevFeature1.15|3}} Several of the Experimental AI candidate actions (CAs) '''have been merged into the [[RCA_AI|default (RCA) AI]]''', see descriptions below for the individual CAs.

An ''Experimental AI'' is available for use in both MP maps and SP scenarios. At the moment, this AI contains the following [[Wesnoth_AI_Framework#The_Candidate_Actions_of_the_main_loop_Stage|candidate actions]]:
* New and improved recruiting
* More aggressive village grabbing
* Healer placement behind injured units and more assertive retreating of injured units to healing locations.
* Leader castle switching: useful on certain MP maps
* Poison spreading
* Moving toward any enemy, if there are no enemy leaders or villages
* All the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default RCA AI candidate actions]] except for recruiting

== Experimental AI Setup ==

In multiplayer maps, this AI is available from the game setup menu as 'Experimental AI'. In single-player scenarios, it can be included by using the following code in a [side] tag
[ai]
# Deprecated version (for Wesnoth 1.14 and earlier)
{EXPERIMENTAL_AI}
[/ai]
{{DevFeature1.15|0}} The EXPERIMENTAL_AI Macro is deprecated now. The Experimental AI should be included as follows instead (this works in Wesnoth 1.14 already):
[ai]
# Current version (works from Wesnoth 1.14 on)
ai_algorithm=experimental_ai
[/ai]

Note that the EXPERIMENTAL_AI macro must be inside <code>[side][ai]</code>, it does not work with <code>[modify_side]</code> or <code>[modify_ai]</code>. If the <code>ai_algorithm</code> version is used, the Experimental AI can also be added as
[modify_side]
side=2
[ai]
ai_algorithm=experimental_ai
[/ai]
[/modify_side]
or
[modify_side]
side=2
switch_ai=ai/ais/ai_generic_rush.cfg # Wesnoth 1.14 and earlier
#switch_ai=ai/ais/ai_experimental.cfg # Wesnoth 1.15 and later
[/modify_side]

=== Custom Parameter Setup ===

{{DevFeature1.15|2}}
A small number of custom parameters can be passed to the Experimental AI. These cannot be set up using the <code>ai_algorithm</code> syntax, but require the use of a macro in the <code>[side][ai]</code> tag:
[side]
[ai]
{CUSTOMIZABLE_EXPERIMENTAL_AI (
high_level_fraction=0.33
randomness=0.2
)}
[/ai]
[/side]
Note that only the parameters one wants changed need to be defined in the macro, those omitted will take their default values.

'''Custom parameters:'''

* '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''randomness'''=0.1: (number) A random number is applied to the Experimental AI recruiting 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.

== Experimental AI Details ==

The Experimental AI uses most of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|candidate actions]] (CAs) of the [[RCA AI]], the one exception being the recruitment CA which is replaced by another recruiting CA. In addition, it also adds a number of new CAs. The following are the differences between the Experimental AI and the default (RCA) AI:

====Recruitment====

{{DevFeature1.15|3}} At the moment, the recruiting CA remains the main difference between the default and the Experimental AI.

The Experimental AI has a completely different recruiting algorithm that was designed to emulate the choices of a human player, especially in the first few turns. As such, it tries to pick units that counter both what is on the battlefield and that the opponent could recruit. As it gains more units relative to the enemy, it picks harder hitting units, even at the cost of fragility, to break through enemy lines.

Unlike the default recruitment algorithm, it also chooses where the units are recruited in order to maximize the number of villages that can be captured and if it knows the leader will be moving to a "better" keep (see below), it will under-recruit at the first keep to project more forward power, recruiting just enough to capture all villages.

It also adjusts its recruitment based on map size, favouring faster units on larger maps, trusting that the economy advantage from capturing more villages will more than offset the price.

It knows about poison and avoids recruiting units that depend on it for damage if the enemy is immune.

It also looks at the expected cost of the unit over the next few turns, which prevents the recruitment of too many fast weak units unless the additional gold from an expected capture of a village is enough to offset the increased cost.

Time of day is taken into account and it prefers units that will reach the current closest enemy at the favoured time of day. This allows, for example, for a slight bias towards saurians during the day and drakes at night on small maps (because they will reach the fight at the right time).

Because the AI cannot use them well, it does not accurately measure the damage done by a unit with berserk, causing them to almost never be recruited.

There is also a small amount of randomness added to allow two units that are almost equally good according to the evaluation to be chosen evenly, instead of only picking the first one every time.

'''Configuration parameters:''' The [args] tag of the recruitment CA can take configuration parameters '''high_level_fraction''', '''randomness''' and '''reset_cache_each_turn''' to modify its behavior. They are described under the [[Micro_AIs#Rush_Recruitment_AI_.28ai_type.3Drecruit_rushers.29|Rush Recruitment AI]] entry on the Micro AI wiki page.

====Villages====

The Experimental AI prefers to capture villages over fighting. This weakens it somewhat in raw fighting but it tends to get enough extra gold that this is actually to its advantage vs. the default AI, although its current implementation is probably too focused on villages.

{{DevFeature1.15|3}} This CA has '''not''' been merged into the default AI. It is too simple to work in a general setting (and therefore not suited for the default AI) and there is a separate village grabbing CA in the default AI, so it does not make much of a difference. This CA needs to be either improved or removed.

====Healing and Retreating====

If a healer is not used to attack, the Experimental AI will try to heal units, instead of positioning to attack later.

In a separate CA, units retreat to villages/healers when injured.

{{DevFeature1.15|3}} These two CAs have been merged into the default AI.

====Castle Switching====

The leader will move to different keeps, providing a forward force. Usually this works very well, especially at the beginning of the game, but it keeps moving later, which sometimes might get it killed in some scenarios. In that case, it might be worth stopping this behaviour after several turn by removing this CA.

====Enemy Poisoning====

There is also an explicit poison attack routine that tries to poison unpoisoned units instead of repeatedly poisoning the same one.

{{DevFeature1.15|3}} This CA has been merged into the default AI.

====Move to Any Enemy====

This is a fall-back CA that kicks in only when no other actions are taken. Its purpose is to not let the AI units sit idle on maps without enemy leaders and villages.

{{DevFeature1.15|3}} This CA has been merged into the default AI.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2022-06-22T23:12:23Z

Mattsc: /* Rush Recruitment AI (ai_type=recruit_rushers) */ add reset_cache_each_turn parameter

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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. This behavior is intentional to help UMC authors note where units might have made suicidal mistakes.
* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Assassin Squad Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 recruiting used in the Experimental AI [[Experimental_AI#Recruitment|as described here]].

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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.
* {{DevFeature1.17|6}} '''reset_cache_each_turn'''=no: (bool) Many of the operations of the rush recruitment evaluation are expensive and are therefore cached. For the most part, this cache can be kept from turn to turn, but in case there are events that change, for example, the map or the recruit list, this parameter can be set to 'yes' to force a reset of the cache each turn.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Experimental AI

2022-06-20T15:36:35Z

Mattsc: /* Recruitment */ add [args] parameters

== Experimental AI Summary ==

{{DevFeature1.15|3}} Several of the Experimental AI candidate actions (CAs) '''have been merged into the [[RCA_AI|default (RCA) AI]]''', see descriptions below for the individual CAs.

An ''Experimental AI'' is available for use in both MP maps and SP scenarios. At the moment, this AI contains the following [[Wesnoth_AI_Framework#The_Candidate_Actions_of_the_main_loop_Stage|candidate actions]]:
* New and improved recruiting
* More aggressive village grabbing
* Healer placement behind injured units and more assertive retreating of injured units to healing locations.
* Leader castle switching: useful on certain MP maps
* Poison spreading
* Moving toward any enemy, if there are no enemy leaders or villages
* All the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default RCA AI candidate actions]] except for recruiting

== Experimental AI Setup ==

In multiplayer maps, this AI is available from the game setup menu as 'Experimental AI'. In single-player scenarios, it can be included by using the following code in a [side] tag
[ai]
# Deprecated version (for Wesnoth 1.14 and earlier)
{EXPERIMENTAL_AI}
[/ai]
{{DevFeature1.15|0}} The EXPERIMENTAL_AI Macro is deprecated now. The Experimental AI should be included as follows instead (this works in Wesnoth 1.14 already):
[ai]
# Current version (works from Wesnoth 1.14 on)
ai_algorithm=experimental_ai
[/ai]

Note that the EXPERIMENTAL_AI macro must be inside <code>[side][ai]</code>, it does not work with <code>[modify_side]</code> or <code>[modify_ai]</code>. If the <code>ai_algorithm</code> version is used, the Experimental AI can also be added as
[modify_side]
side=2
[ai]
ai_algorithm=experimental_ai
[/ai]
[/modify_side]
or
[modify_side]
side=2
switch_ai=ai/ais/ai_generic_rush.cfg # Wesnoth 1.14 and earlier
#switch_ai=ai/ais/ai_experimental.cfg # Wesnoth 1.15 and later
[/modify_side]

=== Custom Parameter Setup ===

{{DevFeature1.15|2}}
A small number of custom parameters can be passed to the Experimental AI. These cannot be set up using the <code>ai_algorithm</code> syntax, but require the use of a macro in the <code>[side][ai]</code> tag:
[side]
[ai]
{CUSTOMIZABLE_EXPERIMENTAL_AI (
high_level_fraction=0.33
randomness=0.2
)}
[/ai]
[/side]
Note that only the parameters one wants changed need to be defined in the macro, those omitted will take their default values.

'''Custom parameters:'''

* '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''randomness'''=0.1: (number) A random number is applied to the Experimental AI recruiting 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.

== Experimental AI Details ==

The Experimental AI uses most of the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|candidate actions]] (CAs) of the [[RCA AI]], the one exception being the recruitment CA which is replaced by another recruiting CA. In addition, it also adds a number of new CAs. The following are the differences between the Experimental AI and the default (RCA) AI:

====Recruitment====

{{DevFeature1.15|3}} At the moment, the recruiting CA remains the main difference between the default and the Experimental AI.

The Experimental AI has a completely different recruiting algorithm that was designed to emulate the choices of a human player, especially in the first few turns. As such, it tries to pick units that counter both what is on the battlefield and that the opponent could recruit. As it gains more units relative to the enemy, it picks harder hitting units, even at the cost of fragility, to break through enemy lines.

Unlike the default recruitment algorithm, it also chooses where the units are recruited in order to maximize the number of villages that can be captured and if it knows the leader will be moving to a "better" keep (see below), it will under-recruit at the first keep to project more forward power, recruiting just enough to capture all villages.

It also adjusts its recruitment based on map size, favouring faster units on larger maps, trusting that the economy advantage from capturing more villages will more than offset the price.

It knows about poison and avoids recruiting units that depend on it for damage if the enemy is immune.

It also looks at the expected cost of the unit over the next few turns, which prevents the recruitment of too many fast weak units unless the additional gold from an expected capture of a village is enough to offset the increased cost.

Time of day is taken into account and it prefers units that will reach the current closest enemy at the favoured time of day. This allows, for example, for a slight bias towards saurians during the day and drakes at night on small maps (because they will reach the fight at the right time).

Because the AI cannot use them well, it does not accurately measure the damage done by a unit with berserk, causing them to almost never be recruited.

There is also a small amount of randomness added to allow two units that are almost equally good according to the evaluation to be chosen evenly, instead of only picking the first one every time.

'''Configurable parameters:''' The [args] tag of the recruitment CA can take two parameters, '''high_level_fraction''' and '''randomness''' to modify its behavior. They are described under the [[Micro_AIs#Rush_Recruitment_AI_.28ai_type.3Drecruit_rushers.29|Rush Recruitment AI]] entry on the Micro AI wiki page.

====Villages====

The Experimental AI prefers to capture villages over fighting. This weakens it somewhat in raw fighting but it tends to get enough extra gold that this is actually to its advantage vs. the default AI, although its current implementation is probably too focused on villages.

{{DevFeature1.15|3}} This CA has '''not''' been merged into the default AI. It is too simple to work in a general setting (and therefore not suited for the default AI) and there is a separate village grabbing CA in the default AI, so it does not make much of a difference. This CA needs to be either improved or removed.

====Healing and Retreating====

If a healer is not used to attack, the Experimental AI will try to heal units, instead of positioning to attack later.

In a separate CA, units retreat to villages/healers when injured.

{{DevFeature1.15|3}} These two CAs have been merged into the default AI.

====Castle Switching====

The leader will move to different keeps, providing a forward force. Usually this works very well, especially at the beginning of the game, but it keeps moving later, which sometimes might get it killed in some scenarios. In that case, it might be worth stopping this behaviour after several turn by removing this CA.

====Enemy Poisoning====

There is also an explicit poison attack routine that tries to poison unpoisoned units instead of repeatedly poisoning the same one.

{{DevFeature1.15|3}} This CA has been merged into the default AI.

====Move to Any Enemy====

This is a fall-back CA that kicks in only when no other actions are taken. Its purpose is to not let the AI units sit idle on maps without enemy leaders and villages.

{{DevFeature1.15|3}} This CA has been merged into the default AI.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2022-06-13T02:41:16Z

Mattsc: /* Rush Recruitment AI (ai_type=recruit_rushers) */

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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. This behavior is intentional to help UMC authors note where units might have made suicidal mistakes.
* '''type'''=Wolf: Comma-separated list of the unit types which the AI controls. The default value is "Wolf".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Assassin Squad Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 recruiting used in the Experimental AI [[Experimental_AI#Recruitment|as described here]].

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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

AiWML

2022-06-13T02:39:01Z

Mattsc: /* The [goal] Tag */ add id=

{{WML Tags}}

== Customizing the Default AI Using WML ==

This page describes how the behavior of the default (RCA) AI can be customized using simple WML commands. The descriptions below assume a basic understanding of how the RCA AI evaluates moves, what '''candidate actions''', '''aspects''' and '''goals''' are, and how they interact. If you do not know these things yet, check out the [[RCA AI]] page.

This page contains:
* Descriptions of the aspects and goals of the default AI
* Instructions for setting them up at the beginning of the scenario in a [side] tag

This page does '''not''' contain:
* Instructions for [[LuaAI#Dynamic_Lua_Aspects|setting up aspects dynamically using Lua]].
* Instructions for [[Modifying_AI_Components#Modifying_Standard_Aspects|changing aspects and goals mid scenario]], although for many of them (for example, for all [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]]) the methods are almost identical
* Instructions for some of the [[Modifying_AI_Components|more complex AI customization tasks]].
* Anything about [[Micro_AIs|MicroAIs]]
* [[AI_Recruitment|Advanced recruitment details]]

== Defining Aspects and Goals of the RCA AI ==

[[RCA_AI#Use_of_Aspects_in_the_RCA_AI|Aspects]] and [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|goals]] of the [[RCA_AI|default (RCA) AI]] can be defined at the beginning of a scenario with [ai] tags inside the [side] tags. They are used to customize certain aspects of the AI. The [ai] tag, when used for this purpose, takes the [[#List_of_AI_Aspects|aspects themselves]] as arguments, as well as the following general keys:
* '''time_of_day''': (string) The time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/schedules.cfg data/core/macros/schedules.cfg] (see also [[TimeWML]]). Note that it is the ''id'' (not the ''name'') of the time of day that needs to be used here. Also note that this aspect did not work for a long time due to a bug (versions 1.7.4 - 1.11.6). It has been fixed for BfW 1.11.7.

* '''turns''': (string) During which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes (-) and commas (,) as is described under Filtering Locations in [[FilterWML]], except of course they apply to turns not locations.

* '''ai_algorithm''': (string) Allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game only comes with ''idle_ai'', which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys ''turns'' and ''time_of_day'', but must be given either in an [ai] tag without the aforementioned keys or in the [side] tag outside all [ai] tags. {{DevFeature1.13|5}} In 1.13, the meaning of '''ai_algorithm''' has changed and no longer selects a native AI that's built into the engine, as the RCA AI has now become the core system and no alternatives exist anymore. Instead, it selects a predefined ''[ai]'' definition, such as those defined in ''data/ai/ais''. Since these are defined in WML, you can easily build your own.

An example of a simple use of the [ai] tag to set AI parameters (aspects) is

<syntaxhighlight lang=wml>
[ai]
time_of_day=dusk
aggression=0.99
caution=0.01
[avoid]
[filter]
side=2,3
[/filter]
radius=2
[/avoid]
[/ai]
</syntaxhighlight>

'''Important Note:''' If you use a different AI engine ([[FormulaAI]] or [[LuaAI]]) for a side, setting aspects in the [side] tag might not work due to a bug in the AI setup mechanism (or it might; there's no general rule that catches all cases). In that case, you might have to use [modify_side][ai] in a ''prestart'' or ''start'' event instead. If unsure, you can use <code>:inspect</code> in debug mode to verify whether an aspect was changed successfully.

==List of AI Aspects==

'''Note:''' Only one instance of each aspect will be active for a side at any time. Where multiple instances of the same aspect are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''advancements''': (string) Defines a list of unit types to which AI units can advance. If a unit type is listed here, units that can advance to this type will <u>only</u> advance to this type, even if they have, in principle, several advancement options. As an example, if this aspect is set to 'Javelineer,Elvish Hero', then all Spearmen advance to Javelineers, and all Elvish Fighters advance to Elvish Heroes. All other units follow their usual advancement choices as determined by the AI. '''Important notes:'''
** This is a simplified version of the more complex (and arguably more useful) application of a dynamic Lua ''advancements'' aspect, as described [[LuaAI#The_advancements_Aspect|here]].
** The ''advancements'' aspect only takes effect during the AI turn, that is, on offense only, not on defense.
** Listing more than one advancement unit type for a given unit still results in only one of the types being used (generally the one listed last).

* '''aggression'''=0.4: (double: ranging from -infinity to 1.0) This key affects how the AI selects its attack targets. The higher the value, the more likely the AI is to attack even if odds are not in its favor. The description below applies as written to the ''combat'' CA only, but aggression is taken into account by the ''high_xp_attack'' and ''spread_poison'' CAs as well (as of '''Wesnoth 1.13.5''' and '''1.15.3''' respectively).
** '''Important: do not set aggression to values greater than 1''' as this makes the AI ''prefer'' attacks in which it receives more damage (see below) unless that is specifically the effect you want to achieve.
** In the attack evaluation, each attack (this includes attack combinations of several AI units against the same enemy unit) is assigned a score. The attack with the highest score is done first. Then the next attack is evaluated, until no attack with a score greater than 0 is found any more. (Note that this ''attack score'' is different from the ''combat CA score'', which is always 100,000 as long as an individual attack score >0 is found. The combat CA score is zero if the highest attack score is <=0).
** The attack score is a complex combination of many different aspects of the attacks. Positive (additive) contributions to the score are things like the value (cost and XP) of the target, the chance to kill the target, whether it is already wounded, how much damage the attack is likely to inflict, etc. Negative (additive) factors include how much damage the AI's units are likely to take, how valuable they are, how exposed they will be after the attack, etc. There are also multiplicative factors that are used if the attack target is a threat to the AI's leader etc.
** All the negative contributions to the score are multiplied by '(1-aggression)'. This means that:
*** If 'aggression=1', no negative contributions are added to the score. Thus, the AI disregards damage done to its own units and selects attacks based solely on the damage it can do to enemy units. If the AI can inflict 1 damage and take 0, or inflict 2 damage and take 20, it will take the latter option.
*** The smaller the value of ''aggression'', the more weight is put on value of and potential damage to the AI's units as compared to the attack target.
*** Roughly speaking, 'aggression=0' results in the AI valuing its units approximately as much as the enemy units. This is not a one-to-one relation, but can be used as an approximate guideline.
*** Very large negative values of ''aggression'' mean that the value of the AI's units is much more important than that of the enemy units. As a result, the AI never attacks unless it will receive no damage in exchange.
*** The rating for damage received in an attack actually becomes a positive contribution to the score for values of aggression larger than 1. This usually does not result in sensible behavior and values greater than 1 should therefore not be used.
** Note: ''aggression'' is always set to 1.0 for attacks on units that pose a direct threat to the AI's leader. Currently this only means units adjacent to the leader.

*'''[attacks]''': Filters the units considered for combat, both on the AI and the enemy sides. Applies to the ''combat'', ''high_xp_attacks'' and ''spread_poison'' CAs only. It cannot be set in the same way as the other aspects and is therefore described in a [[#Filtering_Combat_with_the_attacks_Aspect|separate section]] below.

* '''[avoid]''': Makes the AI avoid specific locations. The AI never moves a unit to these locations except for trying to move its leader to a keep or toward [leader_goal]s, and thus applies to all CAs except ''move-leader-to-goals'' and ''move-leader-to-keep''.
** '''[[StandardLocationFilter]]''': The locations for the AI to avoid. Do not use a [filter_location] tag.
**'''Note:''' Only one instance of an [avoid] aspect will be active for a side at any time. Where multiple instances are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''caution'''=0.25: (double) Defines how cautious the AI is in several ways. It determines whether the leader should move toward [leader_goal], if attacks are worth moving onto less favorable terrain, whether units should retreat, and whether the AI should move units toward targets individually, as groups or not at all. Affects several CAs (listed in the order of their [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|evaluation scores]]):
** ''Move-leader-to-goals CA'': If ''max_risk'' is not set in [leader_goal], its default value is '1-caution'. This determines whether the leader takes the next step toward his goal. See description of [leader_goal].
** ''Combat'' CA:
*** During the evaluation of attacks, the AI considers whether the attacking units could get onto more favorable terrain if they didn't attack but moved somewhere else instead. The difference between the two terrain ratings, together with a number of other factors, determines the "exposure" rating of the units. This exposure is then subtracted from the 'attack score' as described for ''aggression'' above.
*** The exposure rating also contains a multiplication by ''caution'', meaning that 'caution=0' results in exposure not being taken into account, and that it becomes more and more important for larger values. In other words, the higher the values of ''caution'', the more reluctant is the AI to attack from unfavorable terrain. (Note that exposure is one of the negative contributions to the attack score as described for ''aggression'', and therefore is also ignored if 'aggression=1' is set.)
*** If the AI leader is used in an attack, the AI ''always'' uses 'caution=2' for the evaluation of that attack.
** ''Retreat'' CA: {{DevFeature1.15|3}} This CA has been removed.
*** If caution is greater than 0, there is an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location by either side, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat takes place, if <tt>caution × their_power > our_power</tt>. There is also a terrain factor involved if the attacker is not on optimal terrain, similar to the exposure described above for the combat CA.
*** So let's say the AI has its default caution of 0.25. Then the enemy forces have to be at least 4 times as strong before the unit retreats. For a caution of 1, as soon as the enemy is stronger, the unit retreats.
*** The AI never retreats if caution is set to 0 or lower.
** ''Move-to-targets'' CA:
*** If grouping for the AI is enabled and the path along which to move toward a target is considered to be dangerous, caution has an influence, too. "Dangerous" mainly means that there is a good chance for a unit to be killed if it's by itself. In that case, the AI compares its units to the enemy units and based on the result moves forward or not. All units that can reach the next location of the move are considered. The formula for deciding whether to move toward the target as a group is <tt>our_strength / their_strength > 0.5 + caution</tt>. If this condition holds true, units are moved toward the goal as a group, otherwise they try to group together in a location favorable for a attack on the enemy during the next turn.
***So if caution is 0.5, the AI side needs to be at least as strong as the enemy. If it is 0, the AI moves toward the target, even if the enemy is up to twice as strong as the AI. Setting caution to 1.5 means the AI needs to be at least twice as strong as the enemy.
*** The AI also considers retreating units during the move-to-target phase based on criteria similar to those for the retreat CA.

* '''grouping'''="offensive": (string) How the AI should try to group units. Applies to ''move-to-targets'' CA only. Possible values:
** ''offensive'': Makes the AI try to group units together before attacking.
** ''defensive'': Makes the AI group units together very conservatively, only advancing them much beyond its castle if it has overwhelming force.
** ''no'': Makes the AI use no grouping behavior.

* '''leader_aggression'''="-4.0": Exactly as aggression, but for units which can recruit. Applies to ''combat'' CA only. Note that the move-leader-to-keep CA has a higher score than the combat CA. A leader therefore usually only attacks if he is on his keep at the beginning of the turn, otherwise he moves toward the closest keep instead, even with ''leader_aggression=1''.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location. Applies to ''move-leader-to-goals'' CA only.
** '''x''', '''y''': The location toward which the AI should move its leader.
** '''auto_remove'''=no: (bool) If 'no' (default), the AI moves the leader to the goal, after which he stays there until [leader_goal] is [[Modifying_AI_Components#Modifying_Standard_Aspects|removed manually]]. If 'yes', the leader_goal is removed upon the leader getting there. Important: this ''only'' works if ''id'' is set correctly (see the next bullet).
** '''id'''="": (string) An internal id key of the [leader_goal] tag. An id is required for ''auto_remove'' to work. However, setting this id does not automatically set the id of the [leader_goal] [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]]. Thus, in principle for this to work, you need to set the id of the facet as described [[Modifying_AI_Components#Modifying_Standard_Aspects|here]] ''and'' set the ''id'' key in [leader_value] to the same value. Since you are probably only going to use one [leader_goal] tag at a time, there is a much simpler way: setting 'id=0' (which refers to the first facet) or 'id=*' (which means all facets) in [leader_goal] allows ''auto_remove'' to work without the extra step of setting the facet id. {{DevFeature1.13|5}} Setting this now also sets the id of the [leader_goal] facet, allowing auto_remove to work with multiple leader goals without using the fully-expanded aspect syntax.
**'''max_risk'''=1-caution: (double: meaningful values are >=0) How much risk the leader may be exposed to by moving toward the goal. For evaluating this risk, the AI multiplies the leader's hitpoints by this number. The leader is only moved toward the goal if the resulting value is larger than the expected damage the leader is going to take during the next enemy turn. Thus, 'max_risk=0' means he will only move if no attack on him is possible at the target hex of the move. 'max_risk=1' (or larger) results in him moving even if he's almost certainly going to die.

* '''leader_ignores_keep'''=no: (bool) Set to 'yes' for this aspect to apply to all leaders of a side. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list. Setting leader_ignores_keep for some or all leaders means that:
** The affected AI leaders do not move to the closest keep at the beginning of the turn. Instead, they participate in the ''move_to_targets'' candidate action (and all other CAs in which they already participated anyway, of course). Thus, these leaders behave in the same way as any other unit of the AI side.
** This also means that these AI leaders do not recruit except on the first turn if they start on a keep, or if they accidentally end up on a keep. Thus, if a leader is supposed to recruit first and then participate in the action, leader_ignores_keep should be set to 'no' at the beginning of the scenario, and be changed to 'yes' in an event later.

* '''leader_value'''=3: (double) A number 0 or higher which determines the value of enemy leaders as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets CA'' only (and therefore specifically does not apply to attacks).

* '''passive_leader'''=no: (bool) If 'yes', the AI leader never moves or attacks, not even to move back to the keep (unless 'passive_leader_shares_keep=yes' is set) or to attack adjacent units, except to obey [leader_goal]s. Affects all CAs except ''recruitment'' and ''move-leader-to-goals''. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

* '''passive_leader_shares_keep'''=no: (bool) If 'yes', lets the AI leader moves off the keep to share it with allied leaders (if they can reach it next turn) if 'passive_leader=yes' is set. He also returns to keep to recruit when possible and attacks adjacent enemy units. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

*'''recruitment_diversity''', '''recruitment_instructions''', '''recruitment_more''', '''recruitment_pattern''', '''recruitment_randomness''', '''recruitment_save_gold''': These aspects can be used to customize recruiting with the new recruitment CA introduced in Wesnoth 1.11. They are described on a [[AI_Recruitment|separate page]].

*'''retreat_factor'''=0.25 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. Determines how injured AI units have to be before they attempt retreating. This is approximately the fraction of the units' hitpoints, but other factors play a role also, such as the terrain the units are on, and leaders and poisoned units retreat somewhat earlier. Setting this to 0 (or negative values) disables retreating. Note that even setting this to very large values still requires units to be somewhat injured before they start retreating.

*'''retreat_enemy_weight'''=1.0 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. When deciding where to retreat to, the AI considers how much healing a location provides and weighs it against the threat of all the enemies that can get there (balanced by the own units that can get there). In this evaluation, it multiplies the enemy threat rating by ''retreat_enemy_weight'', meaning that the larger its value is, the more a unit tries to move away from enemies. There are three regimes for this aspect:
** Positive values: Only locations that provide healing (both from terrain and from adjacent healers which have no MP left) are considered. For regenerating units, all hexes are treated as if they provide healing.
** Zero: Enemy threats are ignored
** Negative values: All hexes are considered for retreating. The enemy threat rating is multiplied by the absolute value of the aspect value. Thus, if very negative values are used (e.g. -100), this can be used to make units run away from enemies with little consideration for anything else.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village [[#AI_Targets_and_Goals|targets]] for scouts by this value. Affects ''move-to-targets'' CA only.

* '''simple_targeting'''=no: (bool) If 'yes', the AI moves its units toward [[#AI_Targets_and_Goals|targets]] one by one (sequentially), without considering whether another unit might be better suited for the current move or target. If 'no' (the default), all units are considered for all targets. This is slower, but might result in better moves. Affects ''move-to-targets'' CA only.

* '''support_villages'''=no: (bool) Trigger a code path that tries to protect those villages that are threatened by the enemy. This seems to cause the AI to 'sit around' a lot, so it's only used if it's explicitly enabled. Affects ''move-to-targets'' CA only.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to go for villages as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets'' CA only.

* '''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages. Affects ''recruitment'' CA only.

=== Removed AI Aspects ===

The following AI parameters (aspects) can still be set, their values can be retrieved, and they can be viewed in the gamestate inspector dialog, but they do not have an effect in the RCA AI code any more. Some other parameters will also likely be removed in the future. We will update this list accordingly. {{DevFeature1.13|5}} Except for attack_depth, these have now all been removed. {{DevFeature1.15|0}} attack_depth is now removed as well.

* '''attack_depth'''=5: (int)
* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double)
* '''recruitment''': This aspect was used to customize the recruitment of the old default AI (the one used before the RCA AI). This recruitment code is not used in the RCA AI any more. Setting recruitment instructions with this aspect is therefore meaningless. Use the '''recruitment_instructions''' aspect instead.
** It is, in principle, still possible to use this aspect together with the [[Wesnoth_AI_Framework#Recruitment_Stage|recruitment stage]], but this is discouraged for the reasons given at this link.
* '''recruitment_ignore_bad_combat'''=no: (bool)
* '''recruitment_ignore_bad_movement'''=no: (bool)

==AI Targets and Goals==

AI targets are used in the ''move-to-targets'' candidate action (CA) to move the AI's units toward selected units or locations. The AI engine automatically selects all enemy leaders, enemy units that pose a threat to the AI leader and unowned or enemy-owned villages as targets and assigns them certain [[RCA_AI#RCA_AI_Aspect_and_Goal_Configuration|base values]]. Additional targets can be defined using the [goal] tag.

It is '''very important''' to realize that these targets apply to the ''move-to-targets'' CA only and have no influence on other CAs. In particular, they have no effect whatsoever on which enemies the AI attacks. This is often a source of confusion for scenario creators. More background information on RCA AI targets and goals can be found [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|here]]. The sections below only describe how to set up goals in order to add targets for the ''move-to-targets'' CA.

===The [goal] Tag===

The [goal] tag defines units or locations as [[#AI_Targets_and_Goals|move targets]] (not attack targets!) for the AI. '''Applies to ''move-to-targets'' CA only'''. <-- That is '''extremely important''' to understand, in particular the fact that the [goal] tag has '''no influence whatsoever on attacks'''.

The following keys/tags can be used:
* '''name'''="target": (string) The following values are possible and result in different types of targets, as shown in the examples below:
** ''target'': The (default) target goal specifies target units (not necessarily enemy units) toward which the AI should move its units. {{DevFeature1.13|5}} target_unit is now a synonym for this.
** ''target_location'': Specifies target locations toward which the AI should move its units.
** ''protect_location'': Specifies locations that the AI should protect. Enemy units within the specified distance (''protect_radius'') of one of these locations are marked as targets with the provided value. Note that the AI will ''not'' station any units around the protected locations. It will only send units toward enemy units that come within ''protect_radius'' of them.
** ''protect_unit'': Specifies units (of all sides) that the AI should protect. Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.
** ''protect_my_unit'': ('''deprecated''') <s>Specifies units from the AI's own side that the AI should protect. (This is basically the ''protect_unit'' goal with an implied ''side='' in the filter, restricting matching units to the AI's side.) Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.</s>
** ''lua_goal'': A dynamically calculated goal written in Lua. See [[LuaAI#Lua_Goals_and_Targets|here]] for details on how this works.

* '''[criteria]'''="": Contains a [[StandardUnitFilter]] (for ''target'', ''protect_unit'' or ''protect_my_unit'') or [[StandardLocationFilter]] (for ''target_location'' or ''protect_location'') describing the targets.

* '''value'''=0: (double) The value of the goal.

* '''protect_radius'''=20: (int) The protection radius. Applies to ''protect_location'', ''protect_unit'' and ''protect_my_unit''.

* '''id'''="": (string) Optional ID used for [[Modifying_AI_Components#Modifying_Goals|modifying the goal]].

===Examples of [goal] Tag Usage===

'''target:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
[criteria] #NOTE: this is a SUF, because we're targeting a unit
side=3
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''target_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=target_location
[criteria] #NOTE: this is a SLF, because we're targeting a location
x,y=42,20
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_location
[criteria] #NOTE: this is a SLF, because we're protecting a location
x,y=42,20
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_unit:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria] #NOTE: this is a SUF, because we're protecting a unit
side=3
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''How to use protect_unit to protect the own leader''' (We are side 2)
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria]
side=2
canrecruit=yes
[/criteria]
protect_radius=8
value=5
[/goal]
[/ai]
</syntaxhighlight>

=== Deprecated AI Targeting Aspects ===

The following AI targeting parameters currently still work, but have been superseded by the [[#The_.5Bgoal.5D_Tag|[goal] tag]]. They should not be used any more as they will likely be removed at some point. These tags only apply to the move-to-targets CA.

* '''[target]'''="": '''Deprecated'''. Any number of [target] tags can be used to set targets for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get to a target worth '2.0' as for a target worth '1.0'. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': Do not use a [filter] tag.
** '''value'''=1: (double) A number greater than 0 (default=1) which determines how much the AI tries to move toward units which pass the filter.

* '''[protect_location]'''="": '''Deprecated'''. Gives the AI a location to protect. Note that the AI does ''not'' station any units around the location, it only sends units to attack any enemy units that come within the guarding radius of the target. Applies to move-to-targets CA only.
** '''x''', '''y''': Standard coordinates. These indicate the location the AI is protecting.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this location.

* '''[protect_unit]'''="": '''Deprecated'''. Gives the AI a set of units to protect. Note once again that the AI does not place units around the protected units if there are no enemies nearby. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this unit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: '''Deprecated'''. Target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader'. Applies to move-to-targets CA only.

== Filtering which Units Participate in which Actions==

{{DevFeature1.15|3}}

Each [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|candidate action of the default AI]] can be restricted to apply to only a subset of the AI units. This is done by adding a '''[filter_own]''' tag to the '''[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Candidate_Actions|[candidate_action]]]''' tag definition.

Typical use cases:
* Restricting an action to certain units so that other units are not used to this. For example, village grabbing could be restricted to scout units only, so that slower units do not take detours on their way toward the enemies. See the example below.
* Excluding units from a certain action in order to have them available for other actions afterward. For example, one might want to add a custom candidate action which moves healers behind injured units (or use the existing [[Micro_AIs|Micro AI]] for this). Ideally, this should happen after ''all'' other units have moved, specifically also after the move-to-targets candidate action (MtT CA) is done. In the default setting, however, the MtT CA would also move the healers. Thus, we would want to exclude them using a '''[filter_own]''' tag.
* Adding two instances of the same candidate action with different scores to force the order in which units participate in this action. For example, one could add another instance of the move-leader-to-keep CA with a '''[filter_own]''' tag restricting it to one leader, in order to make this leader move to a keep (and therefore recruit) first.

Note that for the combat AI, using the attacks aspect to filter units as described in the next section '''is slightly more efficient'''. Thus, that should be the preferred method if there are many units on the map.

Example:
<syntaxhighlight lang='wml'>
[candidate_action]
id=villages
engine=cpp
name=ai_default_rca::get_villages_phase
max_score=60000
score=60000
[filter_own]
type=Wolf Rider
[/filter_own]
[/candidate_action]
</syntaxhighlight>

== Filtering Combat with the ''attacks'' Aspect==

The ''attacks'' aspect lets us filter the units considered by the ''combat'', ''high_xp_attacks'' and ''spread_poison'' candidate actions. Units on the AI side can be selected with the '''[filter_own]''' tag and enemy units are filtered via '''[filter_enemy]''', both of which take a [[StandardUnitFilter]]. Only units defined in these tags are considered as attacker/target pairs. To define, for example, an ''attacks'' aspect in which units from the elvish sorceress line are the only attackers, and undead units are the only targets, use
<syntaxhighlight lang='wml'>
[ai]
[aspect]
id=attacks
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/aspect]
[/ai]
</syntaxhighlight>
Several important notes:
* The ''attacks'' aspect is a ''composite'' aspect and cannot be defined using the simple syntax of the other ''standard'' aspects. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|here]] for a description of the syntax of the example.
* This only works if <code>invalidate_on_gamestate_change=yes</code> is set. The reason is that the ''attacks'' aspect internally contains information about all available attacker/target pairs. These need to be recalculated after each move. This is explained [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|here]].
* If [filter_own] or [filter_enemy] are omitted, the selection defaults to all units of the respective sides.
* '''Most importantly''': The above example results in sorceress-line vs undead attacks being the <u>only</u> attacks done by the AI. No other attacks are executed, no matter how advantageous their outcomes may be. There is no simple way around that, but it can be accomplished by one of the following means:
** Setting up the [filter_own] or [filter_enemy] [[StandardUnitFilter]]s to adapt dynamically to the situation on the map.
** Adding a Lua candidate action which dynamically adjusts the aspect depending on the current situation on the map. An example of dealing with this is given in the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|Micro AI test scenario]] [https://github.com/wesnoth/wesnoth/blob/master/data/ai/micro_ais/scenarios/protect_unit.cfg ''Protect Unit''].
** Using [[LuaAI#Dynamic_Lua_Aspects|dynamic Lua aspects]] is in principle also possible, but far from easy due to the complex tables this aspect returns.

{{DevFeature1.13|5}}

Though the above code still works in 1.13.5 and later (and will continue to work indefinitely), it can also be simplified a little:
<syntaxhighlight lang='wml'>
[ai]
[attacks]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/attacks]
[/ai]
</syntaxhighlight>

'''See also:''' [[Wesnoth AI]]
[[Category: WML Reference]]
[[Category:AI]]

EasyCoding

2021-09-15T03:28:34Z

Mattsc: /* Improvements to AI */ remove tasks that have been taken care of

'''We are permanently updating this page. Parts marked by <s>strikeout</s> will likely be deleted shortly.

This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature we'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

If none of these are to your liking, feel free to check our [http://bugs.wesnoth.org/?q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%22 bug tracker] with a broad spectrum of tasks.

== Engine related features ==

=== Make a "map diff" tool to visualizes changes between two version of a map ===

Maintainers of maps often make small tweaks for balance purposes. For someone who doesn't know the map like the back of their hand it may be very difficult to spot exactly what changed. There isn't any really good way to do this right now -- using the 'diff' tool at command line doesn't give good results for .map files.

Such a tool would be helpful for someone who maintains a map pool containing maps made by others, also for someone who wants to browse a repository and examine balance changes on several maps, which could be instructive for someone who wants to make and balance their own maps.

There's any number of ways to actually do this, one might be to have a feature in the map editor that takes the name of another map and adds map labels to indicate what hexes changed. It could also be a command accessible in debug mode when playing the game, or it could be an additional command-line argument (--diff [map1] [map2] ?) for the game. (It could be a standalone application but that's probably going to end up with much more work for you.)

https://github.com/wesnoth/wesnoth/issues/2323

=== Add an option to not store replays ===

As noted in https://wiki.wesnoth.org/SavefileWML all normal savefiles usually contain [replay] and [replay_start] tags that usually take over 50% of the total savefile size and are only used for providing the possibilty to replay scenarios. It's be nice to have an option to skip these information to reduce the savefile size. Alternativeley one could create a tool inrtegated in a load/savegame dialog to remove the replay information from a given savegame file.

See the feature request https://github.com/wesnoth/wesnoth/issues/1457

== MP related features ==

=== Add possibility to switch off mod dependency checking ===
MP modifications can define dependencies. Currently there's no way to force a "broken" configuration, although overzealous use of the system by UMC authors could make this feature useful. Add an option to the MP game creation screen to switch on/off dependency checking. Ask lipk (forum)/lipkab (IRC).

https://github.com/wesnoth/wesnoth/issues/2324

=== Make a header for the add-on when we organize scenarios by add-on in the MP create dialog ===

Using an established GUI technique to signal when one block of scenarios for an add-on ends and the next begins would make it much easier to use this dialog, if the user has several add-ons.

See one proposal here:
https://github.com/wesnoth/wesnoth/issues/1365

=== Timer pause button ===

Longstanding feature request here:
https://github.com/wesnoth/wesnoth/issues/1237

Request is for either a button, or a simple chat command like :pause, :unpause, to allow players to put the timer on hold if they are interrupted.

Ideally would be accompanied with a multiplayer-only scenario attribute "number_of_pauses" which decreases each time a client pauses the game. Pause should use a blindfold object to black out the screen, and send a chat message automatically when it occurs / resume occurs. For an example of how it might look, start a local hotseat mp game and enable the Preferences->General->Turn Dialog option. (This behavior was introduced in this commit: https://github.com/wesnoth/wesnoth/commit/bab03d554bea92f1ce6f585ef1123202173a3491)

Wintermute/happygrue also has other ideas about how the timer should/could work. For example, instead of their client ending their turn, the networked opponents could be required to "confirm" the time out. (This is probably a networked MP-only idea.)

A very fancy implementation might instead of a counter, allow the other players to vote on whether a pause request is granted.

Make sure that the paused client still responds to network commands, so that it is possible to kick a person who pauses and then doesn't ever unpause.

=== Add a "concede" button ===

Often times in mp, players concede the game before their leader is actually killed. When the game ends 'officially' the map is revealed, which can sometimes be instructive for the losing player. Additionally, it makes it easier to analyze the results of many games, for purposes of balancing, or for maintaining a ladder. So while it may seem small, this would actually be a pretty useful feature.

FIXME: figure out gh issue id

This could be implemented in lua.

=== Show [options] values in the mp lobby gameslist ===

It' be useful for newly joining payer to see the chosen [options] of a mp game, since most likeley there isn't enough space we could for example wigher show the options via an extra dropdown button in th elobby or show them in the mp waiting dialog instead.

See the featurerequest https://github.com/wesnoth/wesnoth/issues/1514

== WML-related features ==

=== Side filter support in [item] ===

currently [items] allows a team_name= attribute to specify for which side the item is displayed, it would be better if [item] allowed a side filter to specify for which side the item is displayed.

See the bug report https://github.com/wesnoth/wesnoth/issues/1477

=== Support variable poison properties ===

See a feature request here:

https://github.com/wesnoth/wesnoth/issues/1339

=== Events Manipulation ===

* [event] persistent="yes" - creates an event that lasts for the rest of the campaign
* [disable_event][/disable_event] disables the event within which it appears (useful with conditionals). A more complex take on first_time_only=yes/no.
''This is largely possible with event IDs, but could be useful when multiple copies of an event should be floating around''

https://github.com/wesnoth/wesnoth/issues/2326

=== Game Information ===

* [query_location] - queries a location from the user
** variable
** [filter_location]
''Regarding [query_location]: probably a better name would be choose_location. This is used when a wml event is running and needs to get a target location hex from the user. For example, you right click on a catapult unit and choose the menu item "fire Catapult." Now a [message] says to click on any target within 5 hexes. Now [choose_location] is encountered and the mouse cursor changes to a target sign (possibly customizable). If the user's mouse drifts outside of the allowed locations it changes to a cancel icon. If the operation is cancelled then the variable is cleared and no location stored. --Sapient''

''This can be implemented in lua by using wesnoth.game_events.on_mouse_action and wesnoth.syncronize_choice''

https://github.com/wesnoth/wesnoth/issues/2325

== Improvements to AI ==

=== Existing bugs or undesirable features ===

Most of these are probably relatively easy to fix, although we can, of course, not guarantee that.

* Bug: Adding a candidate action mid-turn does not include it where it belongs in terms of its evaluation score. Instead, it gets added at the end of the candidate action list and might not be executed on the current turn, because other CAs with lower scores get evaluated first.

https://github.com/wesnoth/wesnoth/issues/2345

* Bug: ai.get_new_enemy_dst_src and related functions have several problems:
** They use the current moves of the enemy units, which generally are all zero.
** Hexes occupied by other enemy units count as not reachable.
** Working around this with a Lua wrapper makes this actually slower than ai_helper.get_enemy_dst_src, which makes the functions pretty much useless, as speed is the only thing speaking for them.

https://github.com/wesnoth/wesnoth/issues/2346

== GUI2 features ==

Although mordante developed a new GUI system, GUI2, some dialogs still use the older GUI1 and could be improved or transferred. mordante has since disappeared, leaving GUI2's core code unmaintained; shadowm and vultraz should be able to answer most GUI2 (and even GUI1) related questions in his absence.

* Information on the wiki can be found under [[GUIToolkit]] on the wiki.
* The source code is under [https://github.com/wesnoth/wesnoth/tree/master/src/gui src/gui/]
* All mainline GUI2 WML resides in [https://github.com/wesnoth/wesnoth/tree/master/data/gui data/gui/]

* Make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* The biggest feature yet to be converted to GUI2 is the in-game Help documentation (first available from the main screen).

== Miscellaneous ==

=== Debug mode ===

* New debug command functionality (setting additional status.variables, possibly terrain)

=== woptipng / wesnoth-optipng ===

For lossless png compression we use woptipng, a script using an external toolchain (ImageMagick, OptiPNG, Advdef). Perhaps the performance could be improved by using PNGOut instead of advdef. This task includes
* a quick profiling of compression ratio and decompression speed for both tools
* if it provides a higher compression while not significantly slowing down decompression, adapt woptipng to use PNGOut

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

EasyCoding

2021-09-15T03:24:50Z

Mattsc: /* Existing bugs or undesirable features */ remove issues that have been taken care of

'''We are permanently updating this page. Parts marked by <s>strikeout</s> will likely be deleted shortly.

This page is here to document easy to do coding tasks. It is not here to double the feature request database, and should only be filled by people that know the code well enough to judge the difficulty of a given task.

If you are such a person, you should feel free to edit this page.

If you're not, you should post a feature request and discuss your idea on the forum or IRC. A coder with better knowledge of the code might give you the green light to add your feature here.

Anybody should feel free to add "clues" to any tasks, that is entry points, traps to avoid, person to contact to discuss and so on.

If you plan to work on a feature, write your name at the bottom of the feature, with the date. Note that if you are too long at working on a feature we'll "free" it back (that is if you're not working on it. If you have problems implementing it, just tell us....)

If none of these are to your liking, feel free to check our [http://bugs.wesnoth.org/?q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%22 bug tracker] with a broad spectrum of tasks.

== Engine related features ==

=== Make a "map diff" tool to visualizes changes between two version of a map ===

Maintainers of maps often make small tweaks for balance purposes. For someone who doesn't know the map like the back of their hand it may be very difficult to spot exactly what changed. There isn't any really good way to do this right now -- using the 'diff' tool at command line doesn't give good results for .map files.

Such a tool would be helpful for someone who maintains a map pool containing maps made by others, also for someone who wants to browse a repository and examine balance changes on several maps, which could be instructive for someone who wants to make and balance their own maps.

There's any number of ways to actually do this, one might be to have a feature in the map editor that takes the name of another map and adds map labels to indicate what hexes changed. It could also be a command accessible in debug mode when playing the game, or it could be an additional command-line argument (--diff [map1] [map2] ?) for the game. (It could be a standalone application but that's probably going to end up with much more work for you.)

https://github.com/wesnoth/wesnoth/issues/2323

=== Add an option to not store replays ===

As noted in https://wiki.wesnoth.org/SavefileWML all normal savefiles usually contain [replay] and [replay_start] tags that usually take over 50% of the total savefile size and are only used for providing the possibilty to replay scenarios. It's be nice to have an option to skip these information to reduce the savefile size. Alternativeley one could create a tool inrtegated in a load/savegame dialog to remove the replay information from a given savegame file.

See the feature request https://github.com/wesnoth/wesnoth/issues/1457

== MP related features ==

=== Add possibility to switch off mod dependency checking ===
MP modifications can define dependencies. Currently there's no way to force a "broken" configuration, although overzealous use of the system by UMC authors could make this feature useful. Add an option to the MP game creation screen to switch on/off dependency checking. Ask lipk (forum)/lipkab (IRC).

https://github.com/wesnoth/wesnoth/issues/2324

=== Make a header for the add-on when we organize scenarios by add-on in the MP create dialog ===

Using an established GUI technique to signal when one block of scenarios for an add-on ends and the next begins would make it much easier to use this dialog, if the user has several add-ons.

See one proposal here:
https://github.com/wesnoth/wesnoth/issues/1365

=== Timer pause button ===

Longstanding feature request here:
https://github.com/wesnoth/wesnoth/issues/1237

Request is for either a button, or a simple chat command like :pause, :unpause, to allow players to put the timer on hold if they are interrupted.

Ideally would be accompanied with a multiplayer-only scenario attribute "number_of_pauses" which decreases each time a client pauses the game. Pause should use a blindfold object to black out the screen, and send a chat message automatically when it occurs / resume occurs. For an example of how it might look, start a local hotseat mp game and enable the Preferences->General->Turn Dialog option. (This behavior was introduced in this commit: https://github.com/wesnoth/wesnoth/commit/bab03d554bea92f1ce6f585ef1123202173a3491)

Wintermute/happygrue also has other ideas about how the timer should/could work. For example, instead of their client ending their turn, the networked opponents could be required to "confirm" the time out. (This is probably a networked MP-only idea.)

A very fancy implementation might instead of a counter, allow the other players to vote on whether a pause request is granted.

Make sure that the paused client still responds to network commands, so that it is possible to kick a person who pauses and then doesn't ever unpause.

=== Add a "concede" button ===

Often times in mp, players concede the game before their leader is actually killed. When the game ends 'officially' the map is revealed, which can sometimes be instructive for the losing player. Additionally, it makes it easier to analyze the results of many games, for purposes of balancing, or for maintaining a ladder. So while it may seem small, this would actually be a pretty useful feature.

FIXME: figure out gh issue id

This could be implemented in lua.

=== Show [options] values in the mp lobby gameslist ===

It' be useful for newly joining payer to see the chosen [options] of a mp game, since most likeley there isn't enough space we could for example wigher show the options via an extra dropdown button in th elobby or show them in the mp waiting dialog instead.

See the featurerequest https://github.com/wesnoth/wesnoth/issues/1514

== WML-related features ==

=== Side filter support in [item] ===

currently [items] allows a team_name= attribute to specify for which side the item is displayed, it would be better if [item] allowed a side filter to specify for which side the item is displayed.

See the bug report https://github.com/wesnoth/wesnoth/issues/1477

=== Support variable poison properties ===

See a feature request here:

https://github.com/wesnoth/wesnoth/issues/1339

=== Events Manipulation ===

* [event] persistent="yes" - creates an event that lasts for the rest of the campaign
* [disable_event][/disable_event] disables the event within which it appears (useful with conditionals). A more complex take on first_time_only=yes/no.
''This is largely possible with event IDs, but could be useful when multiple copies of an event should be floating around''

https://github.com/wesnoth/wesnoth/issues/2326

=== Game Information ===

* [query_location] - queries a location from the user
** variable
** [filter_location]
''Regarding [query_location]: probably a better name would be choose_location. This is used when a wml event is running and needs to get a target location hex from the user. For example, you right click on a catapult unit and choose the menu item "fire Catapult." Now a [message] says to click on any target within 5 hexes. Now [choose_location] is encountered and the mouse cursor changes to a target sign (possibly customizable). If the user's mouse drifts outside of the allowed locations it changes to a cancel icon. If the operation is cancelled then the variable is cleared and no location stored. --Sapient''

''This can be implemented in lua by using wesnoth.game_events.on_mouse_action and wesnoth.syncronize_choice''

https://github.com/wesnoth/wesnoth/issues/2325

== Improvements to AI ==

=== Existing bugs or undesirable features ===

Most of these are probably relatively easy to fix, although we can, of course, not guarantee that.

* Bug: Adding a candidate action mid-turn does not include it where it belongs in terms of its evaluation score. Instead, it gets added at the end of the candidate action list and might not be executed on the current turn, because other CAs with lower scores get evaluated first.

https://github.com/wesnoth/wesnoth/issues/2345

* Bug: ai.get_new_enemy_dst_src and related functions have several problems:
** They use the current moves of the enemy units, which generally are all zero.
** Hexes occupied by other enemy units count as not reachable.
** Working around this with a Lua wrapper makes this actually slower than ai_helper.get_enemy_dst_src, which makes the functions pretty much useless, as speed is the only thing speaking for them.

https://github.com/wesnoth/wesnoth/issues/2346

=== Add new features to the AI ===

* Add a cost function to the C++ path finding code that takes avoided hexes into account, that is, hexes defined in an [ai][avoid] tag onto which the AI never moves. Also add an option to the Lua wesnoth.find_path() function with which using this cost functions can be turned on and off.
** The background behind this task is the way how the default AI's move-to-targets candidate action works. It does path finding for units without taking avoided hexes into account, and ''afterwards'' eliminates moves for which the end point falls onto an avoided hex. As a result, some units might not move at all, even if it is, in principle, easily possible to move around an avoided area. The inclusion of the new path-finding in the AI's move-to-targets phase could therefore be a follow-up task.

https://github.com/wesnoth/wesnoth/issues/2347

* Add a Lua function ai.get_individual_attacks() that returns all the single attacks the side can do (as opposed to attack combinations). This needs to include an option to recalculate and take the current situation on the map into account (making the function believe that the game state has changed).

https://github.com/wesnoth/wesnoth/issues/2348

* Set up an option the allows us to exclude units from the move-to-targets phase similar to [filter_own] for the combat phase (other than setting ai_special=guardian, which has a number of other side effects). Actually, having this option for all CA's would be nice.

https://github.com/wesnoth/wesnoth/issues/2349

* Change the aspects "passive_leader", "passive_leader_shares_keep", "leader_ignores_keep" to work with multiple leaders. The idea is to change the type of those aspects from yes/no to string so both "passive_leader=yes" and "passive_leader=leader_id_1,leader_id_2" is possible.

https://github.com/wesnoth/wesnoth/issues/2350

== GUI2 features ==

Although mordante developed a new GUI system, GUI2, some dialogs still use the older GUI1 and could be improved or transferred. mordante has since disappeared, leaving GUI2's core code unmaintained; shadowm and vultraz should be able to answer most GUI2 (and even GUI1) related questions in his absence.

* Information on the wiki can be found under [[GUIToolkit]] on the wiki.
* The source code is under [https://github.com/wesnoth/wesnoth/tree/master/src/gui src/gui/]
* All mainline GUI2 WML resides in [https://github.com/wesnoth/wesnoth/tree/master/data/gui data/gui/]

* Make games sortable in the lobby (open slots, total number of players, era, XP modifier, gold per village, fog/shroud)
* The biggest feature yet to be converted to GUI2 is the in-game Help documentation (first available from the main screen).

== Miscellaneous ==

=== Debug mode ===

* New debug command functionality (setting additional status.variables, possibly terrain)

=== woptipng / wesnoth-optipng ===

For lossless png compression we use woptipng, a script using an external toolchain (ImageMagick, OptiPNG, Advdef). Perhaps the performance could be improved by using PNGOut instead of advdef. This task includes
* a quick profiling of compression ratio and decompression speed for both tools
* if it provides a higher compression while not significantly slowing down decompression, adapt woptipng to use PNGOut

== Bugs ==

== See Also ==

[[NotSoEasyCoding]]

[[Category:Development]]
[[Category:Future]]

LuaAPI/ai

2021-07-10T14:52:21Z

Mattsc: Various minor changes

<div class="tright"> __TOC__ </div>

Code executed by [[Wesnoth AI]] components has access to the <tt>ai</tt> module, which contains functions for controlling the AI and querying AI information. Thus, all functions on this page are only available to AI code.

== Game State Queries ==

* {{LuaGameOnly}} '''ai.read_only''' → ''boolean''

The AI module operates in two modes: read-only, and read-write. Read-write mode is used in the execution function for stages and candidate actions, while read-only mode is used in goals and aspects and in the evaluation function for candidate actions. The '''read_only''' key allows you to distinguish these cases at runtime, if necessary. Functions that are only available in read-write mode will be tagged (mutable) in the descriptions on this page.

* {{LuaGameOnly}} '''ai.side''' → ''number''

The side number that the AI module is bound to.

=== ai.aspects ===

* {{LuaGameOnly}} '''ai.aspects'''.''aspect'' → ''value''

Provides access to the aspects of the AI engine. This fetches the result of the aspect evaluation given the game state when it was last refreshed (see [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|aspect invalidation rules]]), not its definition. So, for example, '''ai.aspects.avoid''' returns the list of avoided hexes, not the
[[StandardLocationFilter|Standard Location Filter]] that produced them, and a [[#Dynamic_Lua_Aspects|dynamic Lua aspect]] will return the result of calling the function, not the function itself. For more details, see the definition of each aspect on [[AiWML]].

The following aspects return scalar values (numbers, strings, or booleans):
* '''aggression'''
* '''caution'''
* '''grouping'''
* '''leader_aggression'''
* '''leader_ignores_keep'''
* '''leader_value'''
* '''passive_leader'''
* '''passive_leader_shares_keep'''
* '''recruitment_diversity'''
* '''recruitment_randomness'''
* '''retreat_enemy_weight'''
* '''retreat_factor'''
* '''scout_village_targeting'''
* '''simple_targeting'''
* '''support_villages'''
* '''village_value'''
* '''villages_per_scout'''

The following aspects return tables:

* '''advancements''' – the values of a [[LuaAPI/location_set|location set]] mapping locations to a list of possible advancements for the unit on that hex. To convert this to a fully functional standard location set:
*:<syntaxhighlight lang=lua>
local location_set = wesnoth.require "location_set"
local ls = location_set.create()
ls.values = ai.aspects.advancements
-- Now you can use it as a regular location set
print(ls[{5,6}]) -- might print out {"Elvish Hero", "Elvish Captain"} for example
</syntaxhighlight>
* '''attacks''' – a table with keys '''own''' containing all units that may attack and '''enemy''' containing all units that may be attacked.
* '''avoid''' – an array of locations.
* '''leader_goal''' – the WML content of the leader_goal aspect
* '''recruitment_instructions''' – the WML content of the recruitment_instructions aspect
* '''recruitment_more''' – an array of strings where each string is a usage, a unit type ID, or an integer
* '''recruitment_pattern''' – an array of usage strings (see [[UnitTypeWML]] for an explanation of usage)
* '''recruitment_save_gold''' – the WML content of the recruitment_save_gold aspect

=== ai.get_attacks ===

* {{LuaGameOnly}} '''ai.get_attacks'''() → ''array of attack analyses''

Get all possible attacks the AI is able to perform, and an analysis of each. If multiple AI units can attack the same enemy, all different combinations of AI units are listed. However, for a given combination of AI units, only one attack (the one the AI considers best) is listed. In other words, permutations of those units placed on different hexes are not included, as that would result in too long a list.

Each attack analysis table has the following keys:

* ''analysis''.'''rating'''() → ''numeric rating''
* ''analysis''.'''movements''' → ''array of location pairs''
** ''move''.'''src''' → ''location''
** ''move''.'''dst''' → ''location''
* ''analysis''.'''target''' → ''location''
* ''analysis''.'''target_value''' → ''number''
* ''analysis''.'''avg_losses''' → ''number''
* ''analysis''.'''chance_to_kill''' → ''probability''
* ''analysis''.'''avg_damage_inflicted''' → ''number''
* ''analysis''.'''target_starting_damage''' → ''integer''
* ''analysis''.'''avg_damage_taken''' → ''number''
* ''analysis''.'''resources_used''' → ''number''
* ''analysis''.'''terrain_quality''' → ''number''
* ''analysis''.'''alternative_terrain_quality''' → ''number''
* ''analysis''.'''vulnerability''' → ''number''
* ''analysis''.'''support''' → ''number''
* ''analysis''.'''leader_threat''' → ''boolean''
* ''analysis''.'''uses_leader''' → ''boolean''
* ''analysis''.'''is_surrounded''' → ''boolean''

=== ai.get_targets ===

* {{LuaGameOnly}} '''ai.get_targets'''() → ''array of targets''

Get a list of all the current AI targets. Each target has the following keys:

* '''loc''': The coordinates of the target, as a 2-element array.
* '''type''': The type of target, as a string.
* '''value''': The value of the target, as a real number.

The possible target types are <syntaxhighlight lang='lua' inline>'village', 'leader', 'explicit', 'threat', 'battle aid', 'mass', 'support'</syntaxhighlight>. More information on the meaning of each type can be found in the [[LuaAI#Lua_Goals_and_Targets|LuaAI documentation]].

=== ai.suitable_keep ===

* {{LuaGameOnly}} '''ai.suitable_keep'''(''unit'') → ''x'', ''y''

This returns the location of the closest keep to the unit passed as argument.

== Move Maps ==

* {{LuaGameOnly}} '''ai.get_dst_src'''() → ''move map''
* {{LuaGameOnly}} '''ai.get_src_dst'''() → ''move map''
* {{LuaGameOnly}} '''ai.get_enemy_dst_src'''() → ''move map''
* {{LuaGameOnly}} '''ai.get_enemy_src_dst'''() → ''move map''

These functions return move maps – tables that relate the current positions of units with the hexes they can move to. A move map is a [[LuaAPI/location_set|location set]], similar to the advancements map, which can be converted to a standard location set with the following code:

<syntaxhighlight lang=lua>
local location_set = wesnoth.require "location_set"
local ls = location_set.create()
ls.values = ai.get_dst_src()
-- Now you can use it as a regular location set
print(ls[{1,4}]) -- prints out something like {{5,4},{5,3}} or the like
</syntaxhighlight>

These functions are defined in ''ai/lua/stdlib.lua'', which is loaded by default if you allow the game to implicitly define a Lua [engine] tag. However, if you require a custom Lua [engine] tag, it must load this file manually with the following code in order to use these functions:

<syntaxhighlight lang='lua'>
local ai_stdlib = wesnoth.require('ai/lua/stdlib.lua')
ai_stdlib.init(ai)
</syntaxhighlight>

* {{LuaGameOnly}} '''ai.recalculate_move_maps'''()
* {{LuaGameOnly}} '''ai.recalculate_enemy_move_maps'''()

Force the move maps to be recalculated. This might be necessary if you've moved units around using '''wesnoth.units.to_map'''.

== AI Actions ==

All these functions instruct the AI to check or perform a specific action, and return a result table indicating the success of the action. The table has the following keys:

* '''gamestate_changed''': a boolean indicating whether anything actually changed as a result of the action
* '''ok''': a boolean indicating the success of the action
* '''status''': a numeric status code indicating why the action failed
* '''result''': a string error code indicating why the action failed

=== ai.attack ===

* {{LuaGameOnly}} (mutable) '''ai.attack'''(''attacker'', ''defender'', ''weapon'', ''aggression'') → ''result''

Execute attack by ''attacker'' against ''defender''. If ''weapon'' is provided, it is the number of the weapon to be used (count starts at 1, not 0, as always in Lua), otherwise the choice of the weapon is left to the AI engine. If ''aggression'' is provided, it is used to influence the choice of the best weapon. Obviously, this only makes sense if this choice is left to the engine, that is, if ''weapon'' is set to either 'nil' or '-1'.

=== ai.check_attack ===

* {{LuaGameOnly}} '''ai.check_attack'''(''attacker'', ''defender'', ''weapon'', ''aggression'') → ''result''

Similar to '''ai.attack''', but does not execute the attack – it merely checks if it would succeed.

=== ai.move ===

* {{LuaGameOnly}} (mutable) '''ai.move'''(''unit'', ''to'') → ''result''

Execute a "partial" move of ''unit'' to hex (''to.x'', ''to.y''). A "partial" move means that the unit keeps whatever movement points it has left after the move.

=== ai.move_full ===

* {{LuaGameOnly}} (mutable) '''ai.move_full'''(''unit'', ''to'') → ''result''

Execute a "full" move of ''unit'' to hex (''to.x'', ''to.y''). A "full" move means that the unit's movement points are set to zero at the end of the move.

=== ai.check_move ===

* {{LuaGameOnly}} '''ai.check_move'''(''unit'', ''to'') → ''result''

Similar to '''ai.move''' or '''ai.move_full''', but does not execute the move – it merely checks if it would succeed.

=== ai.recall ===

* {{LuaGameOnly}} (mutable) '''ai.recall'''(''unit_id'', ''location'') → ''result''

Recall the unit with id ''unit_id''. An optional recruit location can be given. If the location is omitted, a suitable hex is automatically chosen by the AI engine.

{{DevFeature1.15|14}} The location must be specified as separate ''x'' and ''y'' parameters.

=== ai.check_recall ===

* {{LuaGameOnly}} '''ai.check_recall'''(''unit_id'', ''location'') → ''result''

Similar to '''ai.recall''', but does not execute the recall – it merely checks if it would succeed.

=== ai.recruit ===

* {{LuaGameOnly}} (mutable) '''ai.recruit'''(''unit_type'', ''location'') → ''result''

Recruit a unit of type ''unit_type''. An optional recruit location can be given. If the location is omitted, a suitable hex is automatically chosen by the AI engine.

{{DevFeature1.15|14}} The location must be specified as separate ''x'' and ''y'' parameters.

=== ai.check_recruit ===

* {{LuaGameOnly}} '''ai.check_recruit'''(''unit_type'', ''location'') → ''result''

Similar to '''ai.recruit''', but does not execute the recruit – it merely checks if it would succeed.

=== ai.stopunit_attacks ===

* {{LuaGameOnly}} (mutable) '''ai.stopunit_attacks'''(''unit'') → ''result''

Remove remaining attacks from ''unit''. This is equivalent to setting <code>attacks_left=0</code>.

=== ai.stopunit_moves ===

* {{LuaGameOnly}} (mutable) '''ai.stopunit_moves'''(''unit'') → ''result''

Remove remaining movement points from ''unit''. This is equivalent to setting <code>moves=0</code>.

=== ai.stopunit_all ===

* {{LuaGameOnly}} (mutable) '''ai.stopunit_all'''(''unit'') →

Remove both remaining attacks and remaining movement points from ''unit''.

=== ai.check_stopunit ===

* {{LuaGameOnly}} '''ai.check_stopunit'''(''unit'') → ''result''

Similar to '''ai.stopunit_attacks''', '''ai.stopunit_moves''', or '''ai.stopunit_all''', but does not execute the stop – it merely checks if it would succeed.

=== ai.fallback_human ===

* {{LuaGameOnly}} (mutable) '''ai.fallback_human'''()

Hands over control of this side to the local human player until the end of the current turn. This action does not return a result; it always succeeds.

== See Also ==

There are two other functions that are not in the AI module but are important for AI coding:

* [[LuaAPI/wesnoth/sides#wesnoth.sides.debug_ai|wesnoth.sides.debug_ai]]
* [[LuaAPI/wesnoth/sync#wesnoth.sync.invoke_command|wesnoth.sync.invoke_command]]

[[Category:Lua Reference]]

AiWML

2021-06-30T14:00:13Z

Mattsc: /* Removed AI Aspects */ attack_depth is removed also

{{WML Tags}}

== Customizing the Default AI Using WML ==

This page describes how the behavior of the default (RCA) AI can be customized using simple WML commands. The descriptions below assume a basic understanding of how the RCA AI evaluates moves, what '''candidate actions''', '''aspects''' and '''goals''' are, and how they interact. If you do not know these things yet, check out the [[RCA AI]] page.

This page contains:
* Descriptions of the aspects and goals of the default AI
* Instructions for setting them up at the beginning of the scenario in a [side] tag

This page does '''not''' contain:
* Instructions for [[LuaAI#Dynamic_Lua_Aspects|setting up aspects dynamically using Lua]].
* Instructions for [[Modifying_AI_Components#Modifying_Standard_Aspects|changing aspects and goals mid scenario]], although for many of them (for example, for all [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]]) the methods are almost identical
* Instructions for some of the [[Modifying_AI_Components|more complex AI customization tasks]].
* Anything about [[Micro_AIs|MicroAIs]]
* [[AI_Recruitment|Advanced recruitment details]]

== Defining Aspects and Goals of the RCA AI ==

[[RCA_AI#Use_of_Aspects_in_the_RCA_AI|Aspects]] and [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|goals]] of the [[RCA_AI|default (RCA) AI]] can be defined at the beginning of a scenario with [ai] tags inside the [side] tags. They are used to customize certain aspects of the AI. The [ai] tag, when used for this purpose, takes the [[#List_of_AI_Aspects|aspects themselves]] as arguments, as well as the following general keys:
* '''time_of_day''': (string) The time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/schedules.cfg data/core/macros/schedules.cfg] (see also [[TimeWML]]). Note that it is the ''id'' (not the ''name'') of the time of day that needs to be used here. Also note that this aspect did not work for a long time due to a bug (versions 1.7.4 - 1.11.6). It has been fixed for BfW 1.11.7.

* '''turns''': (string) During which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes (-) and commas (,) as is described under Filtering Locations in [[FilterWML]], except of course they apply to turns not locations.

* '''ai_algorithm''': (string) Allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game only comes with ''idle_ai'', which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys ''turns'' and ''time_of_day'', but must be given either in an [ai] tag without the aforementioned keys or in the [side] tag outside all [ai] tags. {{DevFeature1.13|5}} In 1.13, the meaning of '''ai_algorithm''' has changed and no longer selects a native AI that's built into the engine, as the RCA AI has now become the core system and no alternatives exist anymore. Instead, it selects a predefined ''[ai]'' definition, such as those defined in ''data/ai/ais''. Since these are defined in WML, you can easily build your own.

An example of a simple use of the [ai] tag to set AI parameters (aspects) is

<syntaxhighlight lang=wml>
[ai]
time_of_day=dusk
aggression=0.99
caution=0.01
[avoid]
[filter]
side=2,3
[/filter]
radius=2
[/avoid]
[/ai]
</syntaxhighlight>

'''Important Note:''' If you use a different AI engine ([[FormulaAI]] or [[LuaAI]]) for a side, setting aspects in the [side] tag might not work due to a bug in the AI setup mechanism (or it might; there's no general rule that catches all cases). In that case, you might have to use [modify_side][ai] in a ''prestart'' or ''start'' event instead. If unsure, you can use <code>:inspect</code> in debug mode to verify whether an aspect was changed successfully.

==List of AI Aspects==

'''Note:''' Only one instance of each aspect will be active for a side at any time. Where multiple instances of the same aspect are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''advancements''': (string) Defines a list of unit types to which AI units can advance. If a unit type is listed here, units that can advance to this type will <u>only</u> advance to this type, even if they have, in principle, several advancement options. As an example, if this aspect is set to 'Javelineer,Elvish Hero', then all Spearmen advance to Javelineers, and all Elvish Fighters advance to Elvish Heroes. All other units follow their usual advancement choices as determined by the AI. '''Important notes:'''
** This is a simplified version of the more complex (and arguably more useful) application of a dynamic Lua ''advancements'' aspect, as described [[LuaAI#The_advancements_Aspect|here]].
** The ''advancements'' aspect only takes effect during the AI turn, that is, on offense only, not on defense.
** Listing more than one advancement unit type for a given unit still results in only one of the types being used (generally the one listed last).

* '''aggression'''=0.4: (double: ranging from -infinity to 1.0) This key affects how the AI selects its attack targets. The higher the value, the more likely the AI is to attack even if odds are not in its favor. The description below applies as written to the ''combat'' CA only, but aggression is taken into account by the ''high_xp_attack'' and ''spread_poison'' CAs as well (as of '''Wesnoth 1.13.5''' and '''1.15.3''' respectively).
** '''Important: do not set aggression to values greater than 1''' as this makes the AI ''prefer'' attacks in which it receives more damage (see below) unless that is specifically the effect you want to achieve.
** In the attack evaluation, each attack (this includes attack combinations of several AI units against the same enemy unit) is assigned a score. The attack with the highest score is done first. Then the next attack is evaluated, until no attack with a score greater than 0 is found any more. (Note that this ''attack score'' is different from the ''combat CA score'', which is always 100,000 as long as an individual attack score >0 is found. The combat CA score is zero if the highest attack score is <=0).
** The attack score is a complex combination of many different aspects of the attacks. Positive (additive) contributions to the score are things like the value (cost and XP) of the target, the chance to kill the target, whether it is already wounded, how much damage the attack is likely to inflict, etc. Negative (additive) factors include how much damage the AI's units are likely to take, how valuable they are, how exposed they will be after the attack, etc. There are also multiplicative factors that are used if the attack target is a threat to the AI's leader etc.
** All the negative contributions to the score are multiplied by '(1-aggression)'. This means that:
*** If 'aggression=1', no negative contributions are added to the score. Thus, the AI disregards damage done to its own units and selects attacks based solely on the damage it can do to enemy units. If the AI can inflict 1 damage and take 0, or inflict 2 damage and take 20, it will take the latter option.
*** The smaller the value of ''aggression'', the more weight is put on value of and potential damage to the AI's units as compared to the attack target.
*** Roughly speaking, 'aggression=0' results in the AI valuing its units approximately as much as the enemy units. This is not a one-to-one relation, but can be used as an approximate guideline.
*** Very large negative values of ''aggression'' mean that the value of the AI's units is much more important than that of the enemy units. As a result, the AI never attacks unless it will receive no damage in exchange.
*** The rating for damage received in an attack actually becomes a positive contribution to the score for values of aggression larger than 1. This usually does not result in sensible behavior and values greater than 1 should therefore not be used.
** Note: ''aggression'' is always set to 1.0 for attacks on units that pose a direct threat to the AI's leader. Currently this only means units adjacent to the leader.

*'''[attacks]''': Filters the units considered for combat, both on the AI and the enemy sides. Applies to the ''combat'', ''high_xp_attacks'' and ''spread_poison'' CAs only. It cannot be set in the same way as the other aspects and is therefore described in a [[#Filtering_Combat_with_the_attacks_Aspect|separate section]] below.

* '''[avoid]''': Makes the AI avoid specific locations. The AI never moves a unit to these locations except for trying to move its leader to a keep or toward [leader_goal]s, and thus applies to all CAs except ''move-leader-to-goals'' and ''move-leader-to-keep''.
** '''[[StandardLocationFilter]]''': The locations for the AI to avoid. Do not use a [filter_location] tag.
**'''Note:''' Only one instance of an [avoid] aspect will be active for a side at any time. Where multiple instances are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''caution'''=0.25: (double) Defines how cautious the AI is in several ways. It determines whether the leader should move toward [leader_goal], if attacks are worth moving onto less favorable terrain, whether units should retreat, and whether the AI should move units toward targets individually, as groups or not at all. Affects several CAs (listed in the order of their [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|evaluation scores]]):
** ''Move-leader-to-goals CA'': If ''max_risk'' is not set in [leader_goal], its default value is '1-caution'. This determines whether the leader takes the next step toward his goal. See description of [leader_goal].
** ''Combat'' CA:
*** During the evaluation of attacks, the AI considers whether the attacking units could get onto more favorable terrain if they didn't attack but moved somewhere else instead. The difference between the two terrain ratings, together with a number of other factors, determines the "exposure" rating of the units. This exposure is then subtracted from the 'attack score' as described for ''aggression'' above.
*** The exposure rating also contains a multiplication by ''caution'', meaning that 'caution=0' results in exposure not being taken into account, and that it becomes more and more important for larger values. In other words, the higher the values of ''caution'', the more reluctant is the AI to attack from unfavorable terrain. (Note that exposure is one of the negative contributions to the attack score as described for ''aggression'', and therefore is also ignored if 'aggression=1' is set.)
*** If the AI leader is used in an attack, the AI ''always'' uses 'caution=2' for the evaluation of that attack.
** ''Retreat'' CA: {{DevFeature1.15|3}} This CA has been removed.
*** If caution is greater than 0, there is an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location by either side, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat takes place, if <tt>caution × their_power > our_power</tt>. There is also a terrain factor involved if the attacker is not on optimal terrain, similar to the exposure described above for the combat CA.
*** So let's say the AI has its default caution of 0.25. Then the enemy forces have to be at least 4 times as strong before the unit retreats. For a caution of 1, as soon as the enemy is stronger, the unit retreats.
*** The AI never retreats if caution is set to 0 or lower.
** ''Move-to-targets'' CA:
*** If grouping for the AI is enabled and the path along which to move toward a target is considered to be dangerous, caution has an influence, too. "Dangerous" mainly means that there is a good chance for a unit to be killed if it's by itself. In that case, the AI compares its units to the enemy units and based on the result moves forward or not. All units that can reach the next location of the move are considered. The formula for deciding whether to move toward the target as a group is <tt>our_strength / their_strength > 0.5 + caution</tt>. If this condition holds true, units are moved toward the goal as a group, otherwise they try to group together in a location favorable for a attack on the enemy during the next turn.
***So if caution is 0.5, the AI side needs to be at least as strong as the enemy. If it is 0, the AI moves toward the target, even if the enemy is up to twice as strong as the AI. Setting caution to 1.5 means the AI needs to be at least twice as strong as the enemy.
*** The AI also considers retreating units during the move-to-target phase based on criteria similar to those for the retreat CA.

* '''grouping'''="offensive": (string) How the AI should try to group units. Applies to ''move-to-targets'' CA only. Possible values:
** ''offensive'': Makes the AI try to group units together before attacking.
** ''defensive'': Makes the AI group units together very conservatively, only advancing them much beyond its castle if it has overwhelming force.
** ''no'': Makes the AI use no grouping behavior.

* '''leader_aggression'''="-4.0": Exactly as aggression, but for units which can recruit. Applies to ''combat'' CA only. Note that the move-leader-to-keep CA has a higher score than the combat CA. A leader therefore usually only attacks if he is on his keep at the beginning of the turn, otherwise he moves toward the closest keep instead, even with ''leader_aggression=1''.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location. Applies to ''move-leader-to-goals'' CA only.
** '''x''', '''y''': The location toward which the AI should move its leader.
** '''auto_remove'''=no: (bool) If 'no' (default), the AI moves the leader to the goal, after which he stays there until [leader_goal] is [[Modifying_AI_Components#Modifying_Standard_Aspects|removed manually]]. If 'yes', the leader_goal is removed upon the leader getting there. Important: this ''only'' works if ''id'' is set correctly (see the next bullet).
** '''id'''="": (string) An internal id key of the [leader_goal] tag. An id is required for ''auto_remove'' to work. However, setting this id does not automatically set the id of the [leader_goal] [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]]. Thus, in principle for this to work, you need to set the id of the facet as described [[Modifying_AI_Components#Modifying_Standard_Aspects|here]] ''and'' set the ''id'' key in [leader_value] to the same value. Since you are probably only going to use one [leader_goal] tag at a time, there is a much simpler way: setting 'id=0' (which refers to the first facet) or 'id=*' (which means all facets) in [leader_goal] allows ''auto_remove'' to work without the extra step of setting the facet id. {{DevFeature1.13|5}} Setting this now also sets the id of the [leader_goal] facet, allowing auto_remove to work with multiple leader goals without using the fully-expanded aspect syntax.
**'''max_risk'''=1-caution: (double: meaningful values are >=0) How much risk the leader may be exposed to by moving toward the goal. For evaluating this risk, the AI multiplies the leader's hitpoints by this number. The leader is only moved toward the goal if the resulting value is larger than the expected damage the leader is going to take during the next enemy turn. Thus, 'max_risk=0' means he will only move if no attack on him is possible at the target hex of the move. 'max_risk=1' (or larger) results in him moving even if he's almost certainly going to die.

* '''leader_ignores_keep'''=no: (bool) Set to 'yes' for this aspect to apply to all leaders of a side. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list. Setting leader_ignores_keep for some or all leaders means that:
** The affected AI leaders do not move to the closest keep at the beginning of the turn. Instead, they participate in the ''move_to_targets'' candidate action (and all other CAs in which they already participated anyway, of course). Thus, these leaders behave in the same way as any other unit of the AI side.
** This also means that these AI leaders do not recruit except on the first turn if they start on a keep, or if they accidentally end up on a keep. Thus, if a leader is supposed to recruit first and then participate in the action, leader_ignores_keep should be set to 'no' at the beginning of the scenario, and be changed to 'yes' in an event later.

* '''leader_value'''=3: (double) A number 0 or higher which determines the value of enemy leaders as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets CA'' only (and therefore specifically does not apply to attacks).

* '''passive_leader'''=no: (bool) If 'yes', the AI leader never moves or attacks, not even to move back to the keep (unless 'passive_leader_shares_keep=yes' is set) or to attack adjacent units, except to obey [leader_goal]s. Affects all CAs except ''recruitment'' and ''move-leader-to-goals''. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

* '''passive_leader_shares_keep'''=no: (bool) If 'yes', lets the AI leader moves off the keep to share it with allied leaders (if they can reach it next turn) if 'passive_leader=yes' is set. He also returns to keep to recruit when possible and attacks adjacent enemy units. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

*'''recruitment_diversity''', '''recruitment_instructions''', '''recruitment_more''', '''recruitment_pattern''', '''recruitment_randomness''', '''recruitment_save_gold''': These aspects can be used to customize recruiting with the new recruitment CA introduced in Wesnoth 1.11. They are described on a [[AI_Recruitment|separate page]].

*'''retreat_factor'''=0.25 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. Determines how injured AI units have to be before they attempt retreating. This is approximately the fraction of the units' hitpoints, but other factors play a role also, such as the terrain the units are on, and leaders and poisoned units retreat somewhat earlier. Setting this to 0 (or negative values) disables retreating. Note that even setting this to very large values still requires units to be somewhat injured before they start retreating.

*'''retreat_enemy_weight'''=1.0 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. When deciding where to retreat to, the AI considers how much healing a location provides and weighs it against the threat of all the enemies that can get there (balanced by the own units that can get there). In this evaluation, it multiplies the enemy threat rating by ''retreat_enemy_weight'', meaning that the larger its value is, the more a unit tries to move away from enemies. There are three regimes for this aspect:
** Positive values: Only locations that provide healing (both from terrain and from adjacent healers which have no MP left) are considered. For regenerating units, all hexes are treated as if they provide healing.
** Zero: Enemy threats are ignored
** Negative values: All hexes are considered for retreating. The enemy threat rating is multiplied by the absolute value of the aspect value. Thus, if very negative values are used (e.g. -100), this can be used to make units run away from enemies with little consideration for anything else.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village [[#AI_Targets_and_Goals|targets]] for scouts by this value. Affects ''move-to-targets'' CA only.

* '''simple_targeting'''=no: (bool) If 'yes', the AI moves its units toward [[#AI_Targets_and_Goals|targets]] one by one (sequentially), without considering whether another unit might be better suited for the current move or target. If 'no' (the default), all units are considered for all targets. This is slower, but might result in better moves. Affects ''move-to-targets'' CA only.

* '''support_villages'''=no: (bool) Trigger a code path that tries to protect those villages that are threatened by the enemy. This seems to cause the AI to 'sit around' a lot, so it's only used if it's explicitly enabled. Affects ''move-to-targets'' CA only.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to go for villages as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets'' CA only.

* '''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages. Affects ''recruitment'' CA only.

=== Removed AI Aspects ===

The following AI parameters (aspects) can still be set, their values can be retrieved, and they can be viewed in the gamestate inspector dialog, but they do not have an effect in the RCA AI code any more. Some other parameters will also likely be removed in the future. We will update this list accordingly. {{DevFeature1.13|5}} Except for attack_depth, these have now all been removed. {{DevFeature1.15|0}} attack_depth is now removed as well.

* '''attack_depth'''=5: (int)
* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double)
* '''recruitment''': This aspect was used to customize the recruitment of the old default AI (the one used before the RCA AI). This recruitment code is not used in the RCA AI any more. Setting recruitment instructions with this aspect is therefore meaningless. Use the '''recruitment_instructions''' aspect instead.
** It is, in principle, still possible to use this aspect together with the [[Wesnoth_AI_Framework#Recruitment_Stage|recruitment stage]], but this is discouraged for the reasons given at this link.
* '''recruitment_ignore_bad_combat'''=no: (bool)
* '''recruitment_ignore_bad_movement'''=no: (bool)

==AI Targets and Goals==

AI targets are used in the ''move-to-targets'' candidate action (CA) to move the AI's units toward selected units or locations. The AI engine automatically selects all enemy leaders, enemy units that pose a threat to the AI leader and unowned or enemy-owned villages as targets and assigns them certain [[RCA_AI#RCA_AI_Aspect_and_Goal_Configuration|base values]]. Additional targets can be defined using the [goal] tag.

It is '''very important''' to realize that these targets apply to the ''move-to-targets'' CA only and have no influence on other CAs. In particular, they have no effect whatsoever on which enemies the AI attacks. This is often a source of confusion for scenario creators. More background information on RCA AI targets and goals can be found [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|here]]. The sections below only describe how to set up goals in order to add targets for the ''move-to-targets'' CA.

===The [goal] Tag===

The [goal] tag defines units or locations as [[#AI_Targets_and_Goals|move targets]] (not attack targets!) for the AI. '''Applies to ''move-to-targets'' CA only'''. <-- That is '''extremely important''' to understand, in particular the fact that the [goal] tag has '''no influence whatsoever on attacks'''.

The following keys/tags can be used:
* '''name'''="target": (string) The following values are possible and result in different types of targets, as shown in the examples below:
** ''target'': The (default) target goal specifies target units (not necessarily enemy units) toward which the AI should move its units. {{DevFeature1.13|5}} target_unit is now a synonym for this.
** ''target_location'': Specifies target locations toward which the AI should move its units.
** ''protect_location'': Specifies locations that the AI should protect. Enemy units within the specified distance (''protect_radius'') of one of these locations are marked as targets with the provided value. Note that the AI will ''not'' station any units around the protected locations. It will only send units toward enemy units that come within ''protect_radius'' of them.
** ''protect_unit'': Specifies units (of all sides) that the AI should protect. Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.
** ''protect_my_unit'': ('''deprecated''') <s>Specifies units from the AI's own side that the AI should protect. (This is basically the ''protect_unit'' goal with an implied ''side='' in the filter, restricting matching units to the AI's side.) Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.</s>
** ''lua_goal'': A dynamically calculated goal written in Lua. See [[LuaAI#Lua_Goals_and_Targets|here]] for details on how this works.

* '''[criteria]'''="": Contains a [[StandardUnitFilter]] (for ''target'', ''protect_unit'' or ''protect_my_unit'') or [[StandardLocationFilter]] (for ''target_location'' or ''protect_location'') describing the targets.

* '''value'''=0: (double) The value of the goal.

* '''protect_radius'''=20: (int) The protection radius. Applies to ''protect_location'', ''protect_unit'' and ''protect_my_unit''.

===Examples of [goal] Tag Usage===

'''target:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
[criteria] #NOTE: this is a SUF, because we're targeting a unit
side=3
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''target_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=target_location
[criteria] #NOTE: this is a SLF, because we're targeting a location
x,y=42,20
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_location
[criteria] #NOTE: this is a SLF, because we're protecting a location
x,y=42,20
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_unit:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria] #NOTE: this is a SUF, because we're protecting a unit
side=3
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''How to use protect_unit to protect the own leader''' (We are side 2)
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria]
side=2
canrecruit=yes
[/criteria]
protect_radius=8
value=5
[/goal]
[/ai]
</syntaxhighlight>

=== Deprecated AI Targeting Aspects ===

The following AI targeting parameters currently still work, but have been superseded by the [[#The_.5Bgoal.5D_Tag|[goal] tag]]. They should not be used any more as they will likely be removed at some point. These tags only apply to the move-to-targets CA.

* '''[target]'''="": '''Deprecated'''. Any number of [target] tags can be used to set targets for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get to a target worth '2.0' as for a target worth '1.0'. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': Do not use a [filter] tag.
** '''value'''=1: (double) A number greater than 0 (default=1) which determines how much the AI tries to move toward units which pass the filter.

* '''[protect_location]'''="": '''Deprecated'''. Gives the AI a location to protect. Note that the AI does ''not'' station any units around the location, it only sends units to attack any enemy units that come within the guarding radius of the target. Applies to move-to-targets CA only.
** '''x''', '''y''': Standard coordinates. These indicate the location the AI is protecting.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this location.

* '''[protect_unit]'''="": '''Deprecated'''. Gives the AI a set of units to protect. Note once again that the AI does not place units around the protected units if there are no enemies nearby. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this unit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: '''Deprecated'''. Target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader'. Applies to move-to-targets CA only.

== Filtering which Units Participate in which Actions==

{{DevFeature1.15|3}}

Each [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|candidate action of the default AI]] can be restricted to apply to only a subset of the AI units. This is done by adding a '''[filter_own]''' tag to the '''[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Candidate_Actions|[candidate_action]]]''' tag definition.

Typical use cases:
* Restricting an action to certain units so that other units are not used to this. For example, village grabbing could be restricted to scout units only, so that slower units do not take detours on their way toward the enemies. See the example below.
* Excluding units from a certain action in order to have them available for other actions afterward. For example, one might want to add a custom candidate action which moves healers behind injured units (or use the existing [[Micro_AIs|Micro AI]] for this). Ideally, this should happen after ''all'' other units have moved, specifically also after the move-to-targets candidate action (MtT CA) is done. In the default setting, however, the MtT CA would also move the healers. Thus, we would want to exclude them using a '''[filter_own]''' tag.
* Adding two instances of the same candidate action with different scores to force the order in which units participate in this action. For example, one could add another instance of the move-leader-to-keep CA with a '''[filter_own]''' tag restricting it to one leader, in order to make this leader move to a keep (and therefore recruit) first.

Note that for the combat AI, using the attacks aspect to filter units as described in the next section '''is slightly more efficient'''. Thus, that should be the preferred method if there are many units on the map.

Example:
<syntaxhighlight lang='wml'>
[candidate_action]
id=villages
engine=cpp
name=ai_default_rca::get_villages_phase
max_score=60000
score=60000
[filter_own]
type=Wolf Rider
[/filter_own]
[/candidate_action]
</syntaxhighlight>

== Filtering Combat with the ''attacks'' Aspect==

The ''attacks'' aspect lets us filter the units considered by the ''combat'', ''high_xp_attacks'' and ''spread_poison'' candidate actions. Units on the AI side can be selected with the '''[filter_own]''' tag and enemy units are filtered via '''[filter_enemy]''', both of which take a [[StandardUnitFilter]]. Only units defined in these tags are considered as attacker/target pairs. To define, for example, an ''attacks'' aspect in which units from the elvish sorceress line are the only attackers, and undead units are the only targets, use
<syntaxhighlight lang='wml'>
[ai]
[aspect]
id=attacks
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/aspect]
[/ai]
</syntaxhighlight>
Several important notes:
* The ''attacks'' aspect is a ''composite'' aspect and cannot be defined using the simple syntax of the other ''standard'' aspects. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|here]] for a description of the syntax of the example.
* This only works if <code>invalidate_on_gamestate_change=yes</code> is set. The reason is that the ''attacks'' aspect internally contains information about all available attacker/target pairs. These need to be recalculated after each move. This is explained [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|here]].
* If [filter_own] or [filter_enemy] are omitted, the selection defaults to all units of the respective sides.
* '''Most importantly''': The above example results in sorceress-line vs undead attacks being the <u>only</u> attacks done by the AI. No other attacks are executed, no matter how advantageous their outcomes may be. There is no simple way around that, but it can be accomplished by one of the following means:
** Setting up the [filter_own] or [filter_enemy] [[StandardUnitFilter]]s to adapt dynamically to the situation on the map.
** Adding a Lua candidate action which dynamically adjusts the aspect depending on the current situation on the map. An example of dealing with this is given in the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|Micro AI test scenario]] [https://github.com/wesnoth/wesnoth/blob/master/data/ai/micro_ais/scenarios/protect_unit.cfg ''Protect Unit''].
** Using [[LuaAI#Dynamic_Lua_Aspects|dynamic Lua aspects]] is in principle also possible, but far from easy due to the complex tables this aspect returns.

{{DevFeature1.13|5}}

Though the above code still works in 1.13.5 and later (and will continue to work indefinitely), it can also be simplified a little:
<syntaxhighlight lang='wml'>
[ai]
[attacks]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/attacks]
[/ai]
</syntaxhighlight>

'''See also:''' [[Wesnoth AI]]
[[Category: WML Reference]]
[[Category:AI]]

Micro AIs

2021-03-22T16:03:06Z

Mattsc: /* Animals AI: Swarm (ai_type=swarm) */ add optional parameter [filter]

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''enemy_distance'''=5: (int) The minimum distance kept between units of the swarm and enemies when the swarm moves as a whole.
* '''[filter]''': {{DevFeature1.15|12}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the swarm. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2021-03-21T15:56:48Z

Mattsc: /* Patrol specific keys for the [micro_ai] tag: */ add attack_invisible_enemies parameter

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''attack_invisible_enemies'''=no: {{DevFeature1.15|12}} If set to 'yes', the unit also attacks invisible enemies (according to the criteria set by '''attack''' and '''attack_range''').
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2021-03-20T23:08:56Z

Mattsc: /* Patrol specific keys for the [micro_ai] tag: */ add dev version number

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: {{DevFeature1.15|12}} If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2021-03-20T23:08:11Z

Mattsc: /* Patrol Micro AI (ai_type=patrol) */ add attack_range parameter

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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.

With the default settings, getting to the next waypoint takes priority over attacking for a patroller, but this can be overridden (as of '''Wesnoth 1.15.12''', using the '''attack_range''' option). Unless instructed otherwise, 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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, or that is within '''attack_range''' (see below). 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 or if it gets within attack_range. It 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. The exception to this is an enemy on the last waypoint with ''one_time_only=yes'', which will always be attacked.
* '''attack_range'''=1: If the patrol comes within this many hexes of an enemy unit, it interrupts its patrol route and attacks that enemy (assuming it still has enough movement left to get to the enemy). The '''attack=''' instructions are taken into account for this. Note that the patrol generally tries to move around enemies, which means that for the default value of 1, enemies are usually not within attack range, except at the end of the move.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2021-03-14T02:19:42Z

Mattsc: /* Messenger Escort specific keys for the [micro_ai] tag: */ add [avoid] tag

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|11}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|11}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2021-03-03T20:19:53Z

Mattsc: /* Goto specific keys for the [micro_ai] tag: */ add new remove_movement= parameters

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.
* '''remove_movement'''=yes: (boolean): {{DevFeature1.15|11}} By default, when the Goto MAI cannot move a unit (for example, because the path is blocked by enemies), its movement points are still removed. If this option is set to 'no', this step does not happen, so that other AI candidate actions (or even another Goto MAI with different parameters) can take over instead.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2021-02-27T18:49:38Z

Mattsc: /* Goto specific keys for the [micro_ai] tag: */ minor change to wording

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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 is used, nor use_straight_line is set to 'yes', as neither of these consider enemies as blockers. Or in other words, if avoid_enemies is used, or use_straight_line=yes, it is unnecessary to set ignore_enemy_at_goal or ignore_units to yes.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

AiWML

2021-02-27T16:41:04Z

Mattsc: /* List of AI Aspects */ Minor wording update to retreat aspects

{{WML Tags}}

== Customizing the Default AI Using WML ==

This page describes how the behavior of the default (RCA) AI can be customized using simple WML commands. The descriptions below assume a basic understanding of how the RCA AI evaluates moves, what '''candidate actions''', '''aspects''' and '''goals''' are, and how they interact. If you do not know these things yet, check out the [[RCA AI]] page.

This page contains:
* Descriptions of the aspects and goals of the default AI
* Instructions for setting them up at the beginning of the scenario in a [side] tag

This page does not contain:
* Instructions for [[LuaAI#Dynamic_Lua_Aspects|setting up aspects dynamically using Lua]].
* Instructions for [[Modifying_AI_Components#Modifying_Standard_Aspects|changing aspects and goals mid scenario]], although for many of them (for example, for all [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]]) the methods are almost identical
* Instructions for some of the [[Modifying_AI_Components|more complex AI customization tasks]].

== Defining Aspects and Goals of the RCA AI ==

[[RCA_AI#Use_of_Aspects_in_the_RCA_AI|Aspects]] and [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|goals]] of the [[RCA_AI|default (RCA) AI]] can be defined at the beginning of a scenario with [ai] tags inside the [side] tags. They are used to customize certain aspects of the AI. The [ai] tag, when used for this purpose, takes the [[#List_of_AI_Aspects|aspects themselves]] as arguments, as well as the following general keys:
* '''time_of_day''': (string) The time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/schedules.cfg data/core/macros/schedules.cfg] (see also [[TimeWML]]). Note that it is the ''id'' (not the ''name'') of the time of day that needs to be used here. Also note that this aspect did not work for a long time due to a bug (versions 1.7.4 - 1.11.6). It has been fixed for BfW 1.11.7.

* '''turns''': (string) During which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes (-) and commas (,) as is described under Filtering Locations in [[FilterWML]], except of course they apply to turns not locations.

* '''ai_algorithm''': (string) Allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game only comes with ''idle_ai'', which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys ''turns'' and ''time_of_day'', but must be given either in an [ai] tag without the aforementioned keys or in the [side] tag outside all [ai] tags. {{DevFeature1.13|5}} In 1.13, the meaning of '''ai_algorithm''' has changed and no longer selects a native AI that's built into the engine, as the RCA AI has now become the core system and no alternatives exist anymore. Instead, it selects a predefined ''[ai]'' definition, such as those defined in ''data/ai/ais''. Since these are defined in WML, you can easily build your own.

An example of a simple use of the [ai] tag to set AI parameters (aspects) is

<syntaxhighlight lang=wml>
[ai]
time_of_day=dusk
aggression=0.99
caution=0.01
[avoid]
[filter]
side=2,3
[/filter]
radius=2
[/avoid]
[/ai]
</syntaxhighlight>

'''Important Note:''' If you use a different AI engine ([[FormulaAI]] or [[LuaAI]]) for a side, setting aspects in the [side] tag might not work due to a bug in the AI setup mechanism (or it might; there's no general rule that catches all cases). In that case, you might have to use [modify_side][ai] in a ''prestart'' or ''start'' event instead. If unsure, you can use <code>:inspect</code> in debug mode to verify whether an aspect was changed successfully.

==List of AI Aspects==

'''Note:''' Only one instance of each aspect will be active for a side at any time. Where multiple instances of the same aspect are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''advancements''': (string) Defines a list of unit types to which AI units can advance. If a unit type is listed here, units that can advance to this type will <u>only</u> advance to this type, even if they have, in principle, several advancement options. As an example, if this aspect is set to 'Javelineer,Elvish Hero', then all Spearmen advance to Javelineers, and all Elvish Fighters advance to Elvish Heroes. All other units follow their usual advancement choices as determined by the AI. '''Important notes:'''
** This is a simplified version of the more complex (and arguably more useful) application of a dynamic Lua ''advancements'' aspect, as described [[LuaAI#The_advancements_Aspect|here]].
** The ''advancements'' aspect only takes effect during the AI turn, that is, on offense only, not on defense.
** Listing more than one advancement unit type for a given unit still results in only one of the types being used (generally the one listed last).

* '''aggression'''=0.4: (double: ranging from -infinity to 1.0) This key affects how the AI selects its attack targets. The higher the value, the more likely the AI is to attack even if odds are not in its favor. The description below applies as written to the ''combat'' CA only, but aggression is taken into account by the ''high_xp_attack'' and ''spread_poison'' CAs as well (as of '''Wesnoth 1.13.5''' and '''1.15.3''' respectively).
** '''Important: do not set aggression to values greater than 1''' as this makes the AI ''prefer'' attacks in which it receives more damage (see below) unless that is specifically the effect you want to achieve.
** In the attack evaluation, each attack (this includes attack combinations of several AI units against the same enemy unit) is assigned a score. The attack with the highest score is done first. Then the next attack is evaluated, until no attack with a score greater than 0 is found any more. (Note that this ''attack score'' is different from the ''combat CA score'', which is always 100,000 as long as an individual attack score >0 is found. The combat CA score is zero if the highest attack score is <=0).
** The attack score is a complex combination of many different aspects of the attacks. Positive (additive) contributions to the score are things like the value (cost and XP) of the target, the chance to kill the target, whether it is already wounded, how much damage the attack is likely to inflict, etc. Negative (additive) factors include how much damage the AI's units are likely to take, how valuable they are, how exposed they will be after the attack, etc. There are also multiplicative factors that are used if the attack target is a threat to the AI's leader etc.
** All the negative contributions to the score are multiplied by '(1-aggression)'. This means that:
*** If 'aggression=1', no negative contributions are added to the score. Thus, the AI disregards damage done to its own units and selects attacks based solely on the damage it can do to enemy units. If the AI can inflict 1 damage and take 0, or inflict 2 damage and take 20, it will take the latter option.
*** The smaller the value of ''aggression'', the more weight is put on value of and potential damage to the AI's units as compared to the attack target.
*** Roughly speaking, 'aggression=0' results in the AI valuing its units approximately as much as the enemy units. This is not a one-to-one relation, but can be used as an approximate guideline.
*** Very large negative values of ''aggression'' mean that the value of the AI's units is much more important than that of the enemy units. As a result, the AI never attacks unless it will receive no damage in exchange.
*** The rating for damage received in an attack actually becomes a positive contribution to the score for values of aggression larger than 1. This usually does not result in sensible behavior and values greater than 1 should therefore not be used.
** Note: ''aggression'' is always set to 1.0 for attacks on units that pose a direct threat to the AI's leader. Currently this only means units adjacent to the leader.

*'''[attacks]''': Filters the units considered for combat, both on the AI and the enemy sides. Applies to the ''combat'', ''high_xp_attacks'' and ''spread_poison'' CAs only. It cannot be set in the same way as the other aspects and is therefore described in a [[#Filtering_Combat_with_the_attacks_Aspect|separate section]] below.

* '''[avoid]''': Makes the AI avoid specific locations. The AI never moves a unit to these locations except for trying to move its leader to a keep or toward [leader_goal]s, and thus applies to all CAs except ''move-leader-to-goals'' and ''move-leader-to-keep''.
** '''[[StandardLocationFilter]]''': The locations for the AI to avoid. Do not use a [filter_location] tag.
**'''Note:''' Only one instance of an [avoid] aspect will be active for a side at any time. Where multiple instances are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''caution'''=0.25: (double) Defines how cautious the AI is in several ways. It determines whether the leader should move toward [leader_goal], if attacks are worth moving onto less favorable terrain, whether units should retreat, and whether the AI should move units toward targets individually, as groups or not at all. Affects several CAs (listed in the order of their [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|evaluation scores]]):
** ''Move-leader-to-goals CA'': If ''max_risk'' is not set in [leader_goal], its default value is '1-caution'. This determines whether the leader takes the next step toward his goal. See description of [leader_goal].
** ''Combat'' CA:
*** During the evaluation of attacks, the AI considers whether the attacking units could get onto more favorable terrain if they didn't attack but moved somewhere else instead. The difference between the two terrain ratings, together with a number of other factors, determines the "exposure" rating of the units. This exposure is then subtracted from the 'attack score' as described for ''aggression'' above.
*** The exposure rating also contains a multiplication by ''caution'', meaning that 'caution=0' results in exposure not being taken into account, and that it becomes more and more important for larger values. In other words, the higher the values of ''caution'', the more reluctant is the AI to attack from unfavorable terrain. (Note that exposure is one of the negative contributions to the attack score as described for ''aggression'', and therefore is also ignored if 'aggression=1' is set.)
*** If the AI leader is used in an attack, the AI ''always'' uses 'caution=2' for the evaluation of that attack.
** ''Retreat'' CA: {{DevFeature1.15|3}} This CA has been removed.
*** If caution is greater than 0, there is an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location by either side, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat takes place, if <tt>caution × their_power > our_power</tt>. There is also a terrain factor involved if the attacker is not on optimal terrain, similar to the exposure described above for the combat CA.
*** So let's say the AI has its default caution of 0.25. Then the enemy forces have to be at least 4 times as strong before the unit retreats. For a caution of 1, as soon as the enemy is stronger, the unit retreats.
*** The AI never retreats if caution is set to 0 or lower.
** ''Move-to-targets'' CA:
*** If grouping for the AI is enabled and the path along which to move toward a target is considered to be dangerous, caution has an influence, too. "Dangerous" mainly means that there is a good chance for a unit to be killed if it's by itself. In that case, the AI compares its units to the enemy units and based on the result moves forward or not. All units that can reach the next location of the move are considered. The formula for deciding whether to move toward the target as a group is <tt>our_strength / their_strength > 0.5 + caution</tt>. If this condition holds true, units are moved toward the goal as a group, otherwise they try to group together in a location favorable for a attack on the enemy during the next turn.
***So if caution is 0.5, the AI side needs to be at least as strong as the enemy. If it is 0, the AI moves toward the target, even if the enemy is up to twice as strong as the AI. Setting caution to 1.5 means the AI needs to be at least twice as strong as the enemy.
*** The AI also considers retreating units during the move-to-target phase based on criteria similar to those for the retreat CA.

* '''grouping'''="offensive": (string) How the AI should try to group units. Applies to ''move-to-targets'' CA only. Possible values:
** ''offensive'': Makes the AI try to group units together before attacking.
** ''defensive'': Makes the AI group units together very conservatively, only advancing them much beyond its castle if it has overwhelming force.
** ''no'': Makes the AI use no grouping behavior.

* '''leader_aggression'''="-4.0": Exactly as aggression, but for units which can recruit. Applies to ''combat'' CA only. Note that the move-leader-to-keep CA has a higher score than the combat CA. A leader therefore usually only attacks if he is on his keep at the beginning of the turn, otherwise he moves toward the closest keep instead, even with ''leader_aggression=1''.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location. Applies to ''move-leader-to-goals'' CA only.
** '''x''', '''y''': The location toward which the AI should move its leader.
** '''auto_remove'''=no: (bool) If 'no' (default), the AI moves the leader to the goal, after which he stays there until [leader_goal] is [[Modifying_AI_Components#Modifying_Standard_Aspects|removed manually]]. If 'yes', the leader_goal is removed upon the leader getting there. Important: this ''only'' works if ''id'' is set correctly (see the next bullet).
** '''id'''="": (string) An internal id key of the [leader_goal] tag. An id is required for ''auto_remove'' to work. However, setting this id does not automatically set the id of the [leader_goal] [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]]. Thus, in principle for this to work, you need to set the id of the facet as described [[Modifying_AI_Components#Modifying_Standard_Aspects|here]] ''and'' set the ''id'' key in [leader_value] to the same value. Since you are probably only going to use one [leader_goal] tag at a time, there is a much simpler way: setting 'id=0' (which refers to the first facet) or 'id=*' (which means all facets) in [leader_goal] allows ''auto_remove'' to work without the extra step of setting the facet id. {{DevFeature1.13|5}} Setting this now also sets the id of the [leader_goal] facet, allowing auto_remove to work with multiple leader goals without using the fully-expanded aspect syntax.
**'''max_risk'''=1-caution: (double: meaningful values are >=0) How much risk the leader may be exposed to by moving toward the goal. For evaluating this risk, the AI multiplies the leader's hitpoints by this number. The leader is only moved toward the goal if the resulting value is larger than the expected damage the leader is going to take during the next enemy turn. Thus, 'max_risk=0' means he will only move if no attack on him is possible at the target hex of the move. 'max_risk=1' (or larger) results in him moving even if he's almost certainly going to die.

* '''leader_ignores_keep'''=no: (bool) Set to 'yes' for this aspect to apply to all leaders of a side. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list. Setting leader_ignores_keep for some or all leaders means that:
** The affected AI leaders do not move to the closest keep at the beginning of the turn. Instead, they participate in the ''move_to_targets'' candidate action (and all other CAs in which they already participated anyway, of course). Thus, these leaders behave in the same way as any other unit of the AI side.
** This also means that these AI leaders do not recruit except on the first turn if they start on a keep, or if they accidentally end up on a keep. Thus, if a leader is supposed to recruit first and then participate in the action, leader_ignores_keep should be set to 'no' at the beginning of the scenario, and be changed to 'yes' in an event later.

* '''leader_value'''=3: (double) A number 0 or higher which determines the value of enemy leaders as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets CA'' only (and therefore specifically does not apply to attacks).

* '''passive_leader'''=no: (bool) If 'yes', the AI leader never moves or attacks, not even to move back to the keep (unless 'passive_leader_shares_keep=yes' is set) or to attack adjacent units, except to obey [leader_goal]s. Affects all CAs except ''recruitment'' and ''move-leader-to-goals''. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

* '''passive_leader_shares_keep'''=no: (bool) If 'yes', lets the AI leader moves off the keep to share it with allied leaders (if they can reach it next turn) if 'passive_leader=yes' is set. He also returns to keep to recruit when possible and attacks adjacent enemy units. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

*'''recruitment_diversity''', '''recruitment_instructions''', '''recruitment_more''', '''recruitment_pattern''', '''recruitment_randomness''', '''recruitment_save_gold''': These aspects can be used to customize recruiting with the new recruitment CA introduced in Wesnoth 1.11. They are described on a [[AI_Recruitment|separate page]].

*'''retreat_factor'''=0.25 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. Determines how injured AI units have to be before they attempt retreating. This is approximately the fraction of the units' hitpoints, but other factors play a role also, such as the terrain the units are on, and leaders and poisoned units retreat somewhat earlier. Setting this to 0 (or negative values) disables retreating. Note that even setting this to very large values still requires units to be somewhat injured before they start retreating.

*'''retreat_enemy_weight'''=1.0 (double) {{DevFeature1.15|11}} Affects ''retreat-injured'' CA only. When deciding where to retreat to, the AI considers how much healing a location provides and weighs it against the threat of all the enemies that can get there (balanced by the own units that can get there). In this evaluation, it multiplies the enemy threat rating by ''retreat_enemy_weight'', meaning that the larger its value is, the more a unit tries to move away from enemies. There are three regimes for this aspect:
** Positive values: Only locations that provide healing (both from terrain and from adjacent healers which have no MP left) are considered. For regenerating units, all hexes are treated as if they provide healing.
** Zero: Enemy threats are ignored
** Negative values: All hexes are considered for retreating. The enemy threat rating is multiplied by the absolute value of the aspect value. Thus, if very negative values are used (e.g. -100), this can be used to make units run away from enemies with little consideration for anything else.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village [[#AI_Targets_and_Goals|targets]] for scouts by this value. Affects ''move-to-targets'' CA only.

* '''simple_targeting'''=no: (bool) If 'yes', the AI moves its units toward [[#AI_Targets_and_Goals|targets]] one by one (sequentially), without considering whether another unit might be better suited for the current move or target. If 'no' (the default), all units are considered for all targets. This is slower, but might result in better moves. Affects ''move-to-targets'' CA only.

* '''support_villages'''=no: (bool) Trigger a code path that tries to protect those villages that are threatened by the enemy. This seems to cause the AI to 'sit around' a lot, so it's only used if it's explicitly enabled. Affects ''move-to-targets'' CA only.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to go for villages as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets'' CA only.

* '''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages. Affects ''recruitment'' CA only.

=== Removed AI Aspects ===

The following AI parameters (aspects) can still be set, their values can be retrieved, and they can be viewed in the gamestate inspector dialog, but they do not have an effect in the RCA AI code any more. Some other parameters will also likely be removed in the future. We will update this list accordingly. {{DevFeature1.13|5}} Except for attack_depth, these have now all been removed.

* '''attack_depth'''=5: (int)
* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double)
* '''recruitment''': This aspect was used to customize the recruitment of the old default AI (the one used before the RCA AI). This recruitment code is not used in the RCA AI any more. Setting recruitment instructions with this aspect is therefore meaningless. Use the '''recruitment_instructions''' aspect instead.
** It is, in principle, still possible to use this aspect together with the [[Wesnoth_AI_Framework#Recruitment_Stage|recruitment stage]], but this is discouraged for the reasons given at this link.
* '''recruitment_ignore_bad_combat'''=no: (bool)
* '''recruitment_ignore_bad_movement'''=no: (bool)

==AI Targets and Goals==

AI targets are used in the ''move-to-targets'' candidate action (CA) to move the AI's units toward selected units or locations. The AI engine automatically selects all enemy leaders, enemy units that pose a threat to the AI leader and unowned or enemy-owned villages as targets and assigns them certain [[RCA_AI#RCA_AI_Aspect_and_Goal_Configuration|base values]]. Additional targets can be defined using the [goal] tag.

It is '''very important''' to realize that these targets apply to the ''move-to-targets'' CA only and have no influence on other CAs. In particular, they have no effect whatsoever on which enemies the AI attacks. This is often a source of confusion for scenario creators. More background information on RCA AI targets and goals can be found [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|here]]. The sections below only describe how to set up goals in order to add targets for the ''move-to-targets'' CA.

===The [goal] Tag===

The [goal] tag defines units or locations as [[#AI_Targets_and_Goals|move targets]] (not attack targets!) for the AI. '''Applies to ''move-to-targets'' CA only'''. <-- That is '''extremely important''' to understand, in particular the fact that the [goal] tag has '''no influence whatsoever on attacks'''.

The following keys/tags can be used:
* '''name'''="target": (string) The following values are possible and result in different types of targets, as shown in the examples below:
** ''target'': The (default) target goal specifies target units (not necessarily enemy units) toward which the AI should move its units. {{DevFeature1.13|5}} target_unit is now a synonym for this.
** ''target_location'': Specifies target locations toward which the AI should move its units.
** ''protect_location'': Specifies locations that the AI should protect. Enemy units within the specified distance (''protect_radius'') of one of these locations are marked as targets with the provided value. Note that the AI will ''not'' station any units around the protected locations. It will only send units toward enemy units that come within ''protect_radius'' of them.
** ''protect_unit'': Specifies units (of all sides) that the AI should protect. Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.
** ''protect_my_unit'': ('''deprecated''') <s>Specifies units from the AI's own side that the AI should protect. (This is basically the ''protect_unit'' goal with an implied ''side='' in the filter, restricting matching units to the AI's side.) Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.</s>
** ''lua_goal'': A dynamically calculated goal written in Lua. See [[LuaAI#Lua_Goals_and_Targets|here]] for details on how this works.

* '''[criteria]'''="": Contains a [[StandardUnitFilter]] (for ''target'', ''protect_unit'' or ''protect_my_unit'') or [[StandardLocationFilter]] (for ''target_location'' or ''protect_location'') describing the targets.

* '''value'''=0: (double) The value of the goal.

* '''protect_radius'''=20: (int) The protection radius. Applies to ''protect_location'', ''protect_unit'' and ''protect_my_unit''.

===Examples of [goal] Tag Usage===

'''target:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
[criteria] #NOTE: this is a SUF, because we're targeting a unit
side=3
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''target_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=target_location
[criteria] #NOTE: this is a SLF, because we're targeting a location
x,y=42,20
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_location
[criteria] #NOTE: this is a SLF, because we're protecting a location
x,y=42,20
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_unit:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria] #NOTE: this is a SUF, because we're protecting a unit
side=3
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''How to use protect_unit to protect the own leader''' (We are side 2)
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria]
side=2
canrecruit=yes
[/criteria]
protect_radius=8
value=5
[/goal]
[/ai]
</syntaxhighlight>

=== Deprecated AI Targeting Aspects ===

The following AI targeting parameters currently still work, but have been superseded by the [[#The_.5Bgoal.5D_Tag|[goal] tag]]. They should not be used any more as they will likely be removed at some point. These tags only apply to the move-to-targets CA.

* '''[target]'''="": '''Deprecated'''. Any number of [target] tags can be used to set targets for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get to a target worth '2.0' as for a target worth '1.0'. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': Do not use a [filter] tag.
** '''value'''=1: (double) A number greater than 0 (default=1) which determines how much the AI tries to move toward units which pass the filter.

* '''[protect_location]'''="": '''Deprecated'''. Gives the AI a location to protect. Note that the AI does ''not'' station any units around the location, it only sends units to attack any enemy units that come within the guarding radius of the target. Applies to move-to-targets CA only.
** '''x''', '''y''': Standard coordinates. These indicate the location the AI is protecting.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this location.

* '''[protect_unit]'''="": '''Deprecated'''. Gives the AI a set of units to protect. Note once again that the AI does not place units around the protected units if there are no enemies nearby. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this unit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: '''Deprecated'''. Target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader'. Applies to move-to-targets CA only.

== Filtering which Units Participate in which Actions==

{{DevFeature1.15|3}}

Each [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|candidate action of the default AI]] can be restricted to apply to only a subset of the AI units. This is done by adding a '''[filter_own]''' tag to the '''[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Candidate_Actions|[candidate_action]]]''' tag definition.

Typical use cases:
* Restricting an action to certain units so that other units are not used to this. For example, village grabbing could be restricted to scout units only, so that slower units do not take detours on their way toward the enemies. See the example below.
* Excluding units from a certain action in order to have them available for other actions afterward. For example, one might want to add a custom candidate action which moves healers behind injured units (or use the existing [[Micro_AIs|Micro AI]] for this). Ideally, this should happen after ''all'' other units have moved, specifically also after the move-to-targets candidate action (MtT CA) is done. In the default setting, however, the MtT CA would also move the healers. Thus, we would want to exclude them using a '''[filter_own]''' tag.
* Adding two instances of the same candidate action with different scores to force the order in which units participate in this action. For example, one could add another instance of the move-leader-to-keep CA with a '''[filter_own]''' tag restricting it to one leader, in order to make this leader move to a keep (and therefore recruit) first.

Note that for the combat AI, using the attacks aspect to filter units as described in the next section '''is slightly more efficient'''. Thus, that should be the preferred method if there are many units on the map.

Example:
<syntaxhighlight lang='wml'>
[candidate_action]
id=villages
engine=cpp
name=ai_default_rca::get_villages_phase
max_score=60000
score=60000
[filter_own]
type=Wolf Rider
[/filter_own]
[/candidate_action]
</syntaxhighlight>

== Filtering Combat with the ''attacks'' Aspect==

The ''attacks'' aspect lets us filter the units considered by the ''combat'', ''high_xp_attacks'' and ''spread_poison'' candidate actions. Units on the AI side can be selected with the '''[filter_own]''' tag and enemy units are filtered via '''[filter_enemy]''', both of which take a [[StandardUnitFilter]]. Only units defined in these tags are considered as attacker/target pairs. To define, for example, an ''attacks'' aspect in which units from the elvish sorceress line are the only attackers, and undead units are the only targets, use
<syntaxhighlight lang='wml'>
[ai]
[aspect]
id=attacks
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/aspect]
[/ai]
</syntaxhighlight>
Several important notes:
* The ''attacks'' aspect is a ''composite'' aspect and cannot be defined using the simple syntax of the other ''standard'' aspects. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|here]] for a description of the syntax of the example.
* This only works if <code>invalidate_on_gamestate_change=yes</code> is set. The reason is that the ''attacks'' aspect internally contains information about all available attacker/target pairs. These need to be recalculated after each move. This is explained [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|here]].
* If [filter_own] or [filter_enemy] are omitted, the selection defaults to all units of the respective sides.
* '''Most importantly''': The above example results in sorceress-line vs undead attacks being the <u>only</u> attacks done by the AI. No other attacks are executed, no matter how advantageous their outcomes may be. There is no simple way around that, but it can be accomplished by one of the following means:
** Setting up the [filter_own] or [filter_enemy] [[StandardUnitFilter]]s to adapt dynamically to the situation on the map.
** Adding a Lua candidate action which dynamically adjusts the aspect depending on the current situation on the map. An example of dealing with this is given in the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|Micro AI test scenario]] [https://github.com/wesnoth/wesnoth/blob/master/data/ai/micro_ais/scenarios/protect_unit.cfg ''Protect Unit''].
** Using [[LuaAI#Dynamic_Lua_Aspects|dynamic Lua aspects]] is in principle also possible, but far from easy due to the complex tables this aspect returns.

{{DevFeature1.13|5}}

Though the above code still works in 1.13.5 and later (and will continue to work indefinitely), it can also be simplified a little:
<syntaxhighlight lang='wml'>
[ai]
[attacks]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/attacks]
[/ai]
</syntaxhighlight>

'''See also:''' [[Wesnoth AI]]
[[Category: WML Reference]]
[[Category:AI]]

AiWML

2021-02-27T16:35:27Z

Mattsc: /* List of AI Aspects */ add retreat_factor and retreat_enemy_weight aspects

{{WML Tags}}

== Customizing the Default AI Using WML ==

This page describes how the behavior of the default (RCA) AI can be customized using simple WML commands. The descriptions below assume a basic understanding of how the RCA AI evaluates moves, what '''candidate actions''', '''aspects''' and '''goals''' are, and how they interact. If you do not know these things yet, check out the [[RCA AI]] page.

This page contains:
* Descriptions of the aspects and goals of the default AI
* Instructions for setting them up at the beginning of the scenario in a [side] tag

This page does not contain:
* Instructions for [[LuaAI#Dynamic_Lua_Aspects|setting up aspects dynamically using Lua]].
* Instructions for [[Modifying_AI_Components#Modifying_Standard_Aspects|changing aspects and goals mid scenario]], although for many of them (for example, for all [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]]) the methods are almost identical
* Instructions for some of the [[Modifying_AI_Components|more complex AI customization tasks]].

== Defining Aspects and Goals of the RCA AI ==

[[RCA_AI#Use_of_Aspects_in_the_RCA_AI|Aspects]] and [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|goals]] of the [[RCA_AI|default (RCA) AI]] can be defined at the beginning of a scenario with [ai] tags inside the [side] tags. They are used to customize certain aspects of the AI. The [ai] tag, when used for this purpose, takes the [[#List_of_AI_Aspects|aspects themselves]] as arguments, as well as the following general keys:
* '''time_of_day''': (string) The time(s) of day when the AI should use the parameters given in this [ai] tag. Possible values are listed in [https://github.com/wesnoth/wesnoth/blob/master/data/core/macros/schedules.cfg data/core/macros/schedules.cfg] (see also [[TimeWML]]). Note that it is the ''id'' (not the ''name'') of the time of day that needs to be used here. Also note that this aspect did not work for a long time due to a bug (versions 1.7.4 - 1.11.6). It has been fixed for BfW 1.11.7.

* '''turns''': (string) During which turns the AI should use the parameters given in this [ai] tag. This takes the same syntax of dashes (-) and commas (,) as is described under Filtering Locations in [[FilterWML]], except of course they apply to turns not locations.

* '''ai_algorithm''': (string) Allows an alternate AI algorithm (cannot be created with WML) to be used. Besides the default, the game only comes with ''idle_ai'', which makes the AI do nothing and can be used to create a passive, unmoving side. Cannot be applied only to a set of turns or a given time of day using the keys ''turns'' and ''time_of_day'', but must be given either in an [ai] tag without the aforementioned keys or in the [side] tag outside all [ai] tags. {{DevFeature1.13|5}} In 1.13, the meaning of '''ai_algorithm''' has changed and no longer selects a native AI that's built into the engine, as the RCA AI has now become the core system and no alternatives exist anymore. Instead, it selects a predefined ''[ai]'' definition, such as those defined in ''data/ai/ais''. Since these are defined in WML, you can easily build your own.

An example of a simple use of the [ai] tag to set AI parameters (aspects) is

<syntaxhighlight lang=wml>
[ai]
time_of_day=dusk
aggression=0.99
caution=0.01
[avoid]
[filter]
side=2,3
[/filter]
radius=2
[/avoid]
[/ai]
</syntaxhighlight>

'''Important Note:''' If you use a different AI engine ([[FormulaAI]] or [[LuaAI]]) for a side, setting aspects in the [side] tag might not work due to a bug in the AI setup mechanism (or it might; there's no general rule that catches all cases). In that case, you might have to use [modify_side][ai] in a ''prestart'' or ''start'' event instead. If unsure, you can use <code>:inspect</code> in debug mode to verify whether an aspect was changed successfully.

==List of AI Aspects==

'''Note:''' Only one instance of each aspect will be active for a side at any time. Where multiple instances of the same aspect are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''advancements''': (string) Defines a list of unit types to which AI units can advance. If a unit type is listed here, units that can advance to this type will <u>only</u> advance to this type, even if they have, in principle, several advancement options. As an example, if this aspect is set to 'Javelineer,Elvish Hero', then all Spearmen advance to Javelineers, and all Elvish Fighters advance to Elvish Heroes. All other units follow their usual advancement choices as determined by the AI. '''Important notes:'''
** This is a simplified version of the more complex (and arguably more useful) application of a dynamic Lua ''advancements'' aspect, as described [[LuaAI#The_advancements_Aspect|here]].
** The ''advancements'' aspect only takes effect during the AI turn, that is, on offense only, not on defense.
** Listing more than one advancement unit type for a given unit still results in only one of the types being used (generally the one listed last).

* '''aggression'''=0.4: (double: ranging from -infinity to 1.0) This key affects how the AI selects its attack targets. The higher the value, the more likely the AI is to attack even if odds are not in its favor. The description below applies as written to the ''combat'' CA only, but aggression is taken into account by the ''high_xp_attack'' and ''spread_poison'' CAs as well (as of '''Wesnoth 1.13.5''' and '''1.15.3''' respectively).
** '''Important: do not set aggression to values greater than 1''' as this makes the AI ''prefer'' attacks in which it receives more damage (see below) unless that is specifically the effect you want to achieve.
** In the attack evaluation, each attack (this includes attack combinations of several AI units against the same enemy unit) is assigned a score. The attack with the highest score is done first. Then the next attack is evaluated, until no attack with a score greater than 0 is found any more. (Note that this ''attack score'' is different from the ''combat CA score'', which is always 100,000 as long as an individual attack score >0 is found. The combat CA score is zero if the highest attack score is <=0).
** The attack score is a complex combination of many different aspects of the attacks. Positive (additive) contributions to the score are things like the value (cost and XP) of the target, the chance to kill the target, whether it is already wounded, how much damage the attack is likely to inflict, etc. Negative (additive) factors include how much damage the AI's units are likely to take, how valuable they are, how exposed they will be after the attack, etc. There are also multiplicative factors that are used if the attack target is a threat to the AI's leader etc.
** All the negative contributions to the score are multiplied by '(1-aggression)'. This means that:
*** If 'aggression=1', no negative contributions are added to the score. Thus, the AI disregards damage done to its own units and selects attacks based solely on the damage it can do to enemy units. If the AI can inflict 1 damage and take 0, or inflict 2 damage and take 20, it will take the latter option.
*** The smaller the value of ''aggression'', the more weight is put on value of and potential damage to the AI's units as compared to the attack target.
*** Roughly speaking, 'aggression=0' results in the AI valuing its units approximately as much as the enemy units. This is not a one-to-one relation, but can be used as an approximate guideline.
*** Very large negative values of ''aggression'' mean that the value of the AI's units is much more important than that of the enemy units. As a result, the AI never attacks unless it will receive no damage in exchange.
*** The rating for damage received in an attack actually becomes a positive contribution to the score for values of aggression larger than 1. This usually does not result in sensible behavior and values greater than 1 should therefore not be used.
** Note: ''aggression'' is always set to 1.0 for attacks on units that pose a direct threat to the AI's leader. Currently this only means units adjacent to the leader.

*'''[attacks]''': Filters the units considered for combat, both on the AI and the enemy sides. Applies to the ''combat'', ''high_xp_attacks'' and ''spread_poison'' CAs only. It cannot be set in the same way as the other aspects and is therefore described in a [[#Filtering_Combat_with_the_attacks_Aspect|separate section]] below.

* '''[avoid]''': Makes the AI avoid specific locations. The AI never moves a unit to these locations except for trying to move its leader to a keep or toward [leader_goal]s, and thus applies to all CAs except ''move-leader-to-goals'' and ''move-leader-to-keep''.
** '''[[StandardLocationFilter]]''': The locations for the AI to avoid. Do not use a [filter_location] tag.
**'''Note:''' Only one instance of an [avoid] aspect will be active for a side at any time. Where multiple instances are included in an [ai] tag, the last whose conditions (time of day, turns, etc.) match will be the only one that applies.

* '''caution'''=0.25: (double) Defines how cautious the AI is in several ways. It determines whether the leader should move toward [leader_goal], if attacks are worth moving onto less favorable terrain, whether units should retreat, and whether the AI should move units toward targets individually, as groups or not at all. Affects several CAs (listed in the order of their [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|evaluation scores]]):
** ''Move-leader-to-goals CA'': If ''max_risk'' is not set in [leader_goal], its default value is '1-caution'. This determines whether the leader takes the next step toward his goal. See description of [leader_goal].
** ''Combat'' CA:
*** During the evaluation of attacks, the AI considers whether the attacking units could get onto more favorable terrain if they didn't attack but moved somewhere else instead. The difference between the two terrain ratings, together with a number of other factors, determines the "exposure" rating of the units. This exposure is then subtracted from the 'attack score' as described for ''aggression'' above.
*** The exposure rating also contains a multiplication by ''caution'', meaning that 'caution=0' results in exposure not being taken into account, and that it becomes more and more important for larger values. In other words, the higher the values of ''caution'', the more reluctant is the AI to attack from unfavorable terrain. (Note that exposure is one of the negative contributions to the attack score as described for ''aggression'', and therefore is also ignored if 'aggression=1' is set.)
*** If the AI leader is used in an attack, the AI ''always'' uses 'caution=2' for the evaluation of that attack.
** ''Retreat'' CA: {{DevFeature1.15|3}} This CA has been removed.
*** If caution is greater than 0, there is an evaluation of forces for the map location a unit stands on. This is basically the sum of damage that can be done to that location by either side, reduced by terrain defense and relative hitpoints if attackers don't have full health. A retreat takes place, if <tt>caution × their_power > our_power</tt>. There is also a terrain factor involved if the attacker is not on optimal terrain, similar to the exposure described above for the combat CA.
*** So let's say the AI has its default caution of 0.25. Then the enemy forces have to be at least 4 times as strong before the unit retreats. For a caution of 1, as soon as the enemy is stronger, the unit retreats.
*** The AI never retreats if caution is set to 0 or lower.
** ''Move-to-targets'' CA:
*** If grouping for the AI is enabled and the path along which to move toward a target is considered to be dangerous, caution has an influence, too. "Dangerous" mainly means that there is a good chance for a unit to be killed if it's by itself. In that case, the AI compares its units to the enemy units and based on the result moves forward or not. All units that can reach the next location of the move are considered. The formula for deciding whether to move toward the target as a group is <tt>our_strength / their_strength > 0.5 + caution</tt>. If this condition holds true, units are moved toward the goal as a group, otherwise they try to group together in a location favorable for a attack on the enemy during the next turn.
***So if caution is 0.5, the AI side needs to be at least as strong as the enemy. If it is 0, the AI moves toward the target, even if the enemy is up to twice as strong as the AI. Setting caution to 1.5 means the AI needs to be at least twice as strong as the enemy.
*** The AI also considers retreating units during the move-to-target phase based on criteria similar to those for the retreat CA.

* '''grouping'''="offensive": (string) How the AI should try to group units. Applies to ''move-to-targets'' CA only. Possible values:
** ''offensive'': Makes the AI try to group units together before attacking.
** ''defensive'': Makes the AI group units together very conservatively, only advancing them much beyond its castle if it has overwhelming force.
** ''no'': Makes the AI use no grouping behavior.

* '''leader_aggression'''="-4.0": Exactly as aggression, but for units which can recruit. Applies to ''combat'' CA only. Note that the move-leader-to-keep CA has a higher score than the combat CA. A leader therefore usually only attacks if he is on his keep at the beginning of the turn, otherwise he moves toward the closest keep instead, even with ''leader_aggression=1''.

* '''[leader_goal]'''="": Makes the AI try to move its leader to a specific location. Applies to ''move-leader-to-goals'' CA only.
** '''x''', '''y''': The location toward which the AI should move its leader.
** '''auto_remove'''=no: (bool) If 'no' (default), the AI moves the leader to the goal, after which he stays there until [leader_goal] is [[Modifying_AI_Components#Modifying_Standard_Aspects|removed manually]]. If 'yes', the leader_goal is removed upon the leader getting there. Important: this ''only'' works if ''id'' is set correctly (see the next bullet).
** '''id'''="": (string) An internal id key of the [leader_goal] tag. An id is required for ''auto_remove'' to work. However, setting this id does not automatically set the id of the [leader_goal] [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|facet]]. Thus, in principle for this to work, you need to set the id of the facet as described [[Modifying_AI_Components#Modifying_Standard_Aspects|here]] ''and'' set the ''id'' key in [leader_value] to the same value. Since you are probably only going to use one [leader_goal] tag at a time, there is a much simpler way: setting 'id=0' (which refers to the first facet) or 'id=*' (which means all facets) in [leader_goal] allows ''auto_remove'' to work without the extra step of setting the facet id. {{DevFeature1.13|5}} Setting this now also sets the id of the [leader_goal] facet, allowing auto_remove to work with multiple leader goals without using the fully-expanded aspect syntax.
**'''max_risk'''=1-caution: (double: meaningful values are >=0) How much risk the leader may be exposed to by moving toward the goal. For evaluating this risk, the AI multiplies the leader's hitpoints by this number. The leader is only moved toward the goal if the resulting value is larger than the expected damage the leader is going to take during the next enemy turn. Thus, 'max_risk=0' means he will only move if no attack on him is possible at the target hex of the move. 'max_risk=1' (or larger) results in him moving even if he's almost certainly going to die.

* '''leader_ignores_keep'''=no: (bool) Set to 'yes' for this aspect to apply to all leaders of a side. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list. Setting leader_ignores_keep for some or all leaders means that:
** The affected AI leaders do not move to the closest keep at the beginning of the turn. Instead, they participate in the ''move_to_targets'' candidate action (and all other CAs in which they already participated anyway, of course). Thus, these leaders behave in the same way as any other unit of the AI side.
** This also means that these AI leaders do not recruit except on the first turn if they start on a keep, or if they accidentally end up on a keep. Thus, if a leader is supposed to recruit first and then participate in the action, leader_ignores_keep should be set to 'no' at the beginning of the scenario, and be changed to 'yes' in an event later.

* '''leader_value'''=3: (double) A number 0 or higher which determines the value of enemy leaders as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets CA'' only (and therefore specifically does not apply to attacks).

* '''passive_leader'''=no: (bool) If 'yes', the AI leader never moves or attacks, not even to move back to the keep (unless 'passive_leader_shares_keep=yes' is set) or to attack adjacent units, except to obey [leader_goal]s. Affects all CAs except ''recruitment'' and ''move-leader-to-goals''. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

* '''passive_leader_shares_keep'''=no: (bool) If 'yes', lets the AI leader moves off the keep to share it with allied leaders (if they can reach it next turn) if 'passive_leader=yes' is set. He also returns to keep to recruit when possible and attacks adjacent enemy units. {{DevFeature1.15|3}} In addition to 'yes/no', the aspect can now also be set to a comma-separated list of unit ids. The aspect then only applies to leaders with ids matching an id on that list.

*'''recruitment_diversity''', '''recruitment_instructions''', '''recruitment_more''', '''recruitment_pattern''', '''recruitment_randomness''', '''recruitment_save_gold''': These aspects can be used to customize recruiting with the new recruitment CA introduced in Wesnoth 1.11. They are described on a [[AI_Recruitment|separate page]].

*'''retreat_factor'''=0.25 (double) {{DevFeature1.15|11}} Determines how injured AI units have to be before they attempt retreating. This is approximately the fraction of the units' hitpoints, but other factors play a role also, such as the terrain the units are on, and leaders and poisoned units retreat somewhat earlier. Setting this to 0 (or negative values) disables retreating. Note that even setting this to very large values still requires units to be somewhat injured before they start retreating. Affects ''retreat-injured'' CA only.

*'''retreat_enemy_weight'''=1.0 (double) {{DevFeature1.15|11}} When deciding where to retreat to, the AI considers how much healing a location provides and weighs it against the threat of all the enemies that can get there (balanced by the own units that can get there). In this evaluation, it multiplies the enemy threat rating by ''retreat_enemy_weight'', meaning that the larger its value is, the more a unit tries to move away from enemies. There are three regimes for this aspect:
** Positive values: Only locations that provide healing (both from terrain and from adjacent healers which have no MP left) are considered. For regenerating units, all hexes are treated as if they provide healing.
** Zero: Enemy threats are ignored
** Negative values: All hexes are considered for retreating. Thus, if very negative values are used (e.g. -100), this can be used to make units run away from enemies with little consideration for anything else.
Affects ''retreat-injured'' CA only.

* '''scout_village_targeting'''=3: (double) The AI multiplies the value of village [[#AI_Targets_and_Goals|targets]] for scouts by this value. Affects ''move-to-targets'' CA only.

* '''simple_targeting'''=no: (bool) If 'yes', the AI moves its units toward [[#AI_Targets_and_Goals|targets]] one by one (sequentially), without considering whether another unit might be better suited for the current move or target. If 'no' (the default), all units are considered for all targets. This is slower, but might result in better moves. Affects ''move-to-targets'' CA only.

* '''support_villages'''=no: (bool) Trigger a code path that tries to protect those villages that are threatened by the enemy. This seems to cause the AI to 'sit around' a lot, so it's only used if it's explicitly enabled. Affects ''move-to-targets'' CA only.

* '''village_value'''=1: (double) A number 0 or higher which determines how much the AI tries to go for villages as [[#AI_Targets_and_Goals|targets]]. Affects ''move-to-targets'' CA only.

* '''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If 0, the AI doesn't recruit scouts to capture villages. Affects ''recruitment'' CA only.

=== Removed AI Aspects ===

The following AI parameters (aspects) can still be set, their values can be retrieved, and they can be viewed in the gamestate inspector dialog, but they do not have an effect in the RCA AI code any more. Some other parameters will also likely be removed in the future. We will update this list accordingly. {{DevFeature1.13|5}} Except for attack_depth, these have now all been removed.

* '''attack_depth'''=5: (int)
* '''number_of_possible_recruits_to_force_recruit'''=3.1: (double)
* '''recruitment''': This aspect was used to customize the recruitment of the old default AI (the one used before the RCA AI). This recruitment code is not used in the RCA AI any more. Setting recruitment instructions with this aspect is therefore meaningless. Use the '''recruitment_instructions''' aspect instead.
** It is, in principle, still possible to use this aspect together with the [[Wesnoth_AI_Framework#Recruitment_Stage|recruitment stage]], but this is discouraged for the reasons given at this link.
* '''recruitment_ignore_bad_combat'''=no: (bool)
* '''recruitment_ignore_bad_movement'''=no: (bool)

==AI Targets and Goals==

AI targets are used in the ''move-to-targets'' candidate action (CA) to move the AI's units toward selected units or locations. The AI engine automatically selects all enemy leaders, enemy units that pose a threat to the AI leader and unowned or enemy-owned villages as targets and assigns them certain [[RCA_AI#RCA_AI_Aspect_and_Goal_Configuration|base values]]. Additional targets can be defined using the [goal] tag.

It is '''very important''' to realize that these targets apply to the ''move-to-targets'' CA only and have no influence on other CAs. In particular, they have no effect whatsoever on which enemies the AI attacks. This is often a source of confusion for scenario creators. More background information on RCA AI targets and goals can be found [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|here]]. The sections below only describe how to set up goals in order to add targets for the ''move-to-targets'' CA.

===The [goal] Tag===

The [goal] tag defines units or locations as [[#AI_Targets_and_Goals|move targets]] (not attack targets!) for the AI. '''Applies to ''move-to-targets'' CA only'''. <-- That is '''extremely important''' to understand, in particular the fact that the [goal] tag has '''no influence whatsoever on attacks'''.

The following keys/tags can be used:
* '''name'''="target": (string) The following values are possible and result in different types of targets, as shown in the examples below:
** ''target'': The (default) target goal specifies target units (not necessarily enemy units) toward which the AI should move its units. {{DevFeature1.13|5}} target_unit is now a synonym for this.
** ''target_location'': Specifies target locations toward which the AI should move its units.
** ''protect_location'': Specifies locations that the AI should protect. Enemy units within the specified distance (''protect_radius'') of one of these locations are marked as targets with the provided value. Note that the AI will ''not'' station any units around the protected locations. It will only send units toward enemy units that come within ''protect_radius'' of them.
** ''protect_unit'': Specifies units (of all sides) that the AI should protect. Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.
** ''protect_my_unit'': ('''deprecated''') <s>Specifies units from the AI's own side that the AI should protect. (This is basically the ''protect_unit'' goal with an implied ''side='' in the filter, restricting matching units to the AI's side.) Enemy units within ''protect_radius'' of one of these units are marked as targets with the provided value. Note once again that the AI will not place units around the protected units if there are no enemies nearby.</s>
** ''lua_goal'': A dynamically calculated goal written in Lua. See [[LuaAI#Lua_Goals_and_Targets|here]] for details on how this works.

* '''[criteria]'''="": Contains a [[StandardUnitFilter]] (for ''target'', ''protect_unit'' or ''protect_my_unit'') or [[StandardLocationFilter]] (for ''target_location'' or ''protect_location'') describing the targets.

* '''value'''=0: (double) The value of the goal.

* '''protect_radius'''=20: (int) The protection radius. Applies to ''protect_location'', ''protect_unit'' and ''protect_my_unit''.

===Examples of [goal] Tag Usage===

'''target:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
[criteria] #NOTE: this is a SUF, because we're targeting a unit
side=3
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''target_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=target_location
[criteria] #NOTE: this is a SLF, because we're targeting a location
x,y=42,20
[/criteria]
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_location:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_location
[criteria] #NOTE: this is a SLF, because we're protecting a location
x,y=42,20
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''protect_unit:'''
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria] #NOTE: this is a SUF, because we're protecting a unit
side=3
[/criteria]
protect_radius=16
value=5
[/goal]
[/ai]
</syntaxhighlight>

'''How to use protect_unit to protect the own leader''' (We are side 2)
<syntaxhighlight lang='wml'>
[ai]
[goal]
name=protect_unit
[criteria]
side=2
canrecruit=yes
[/criteria]
protect_radius=8
value=5
[/goal]
[/ai]
</syntaxhighlight>

=== Deprecated AI Targeting Aspects ===

The following AI targeting parameters currently still work, but have been superseded by the [[#The_.5Bgoal.5D_Tag|[goal] tag]]. They should not be used any more as they will likely be removed at some point. These tags only apply to the move-to-targets CA.

* '''[target]'''="": '''Deprecated'''. Any number of [target] tags can be used to set targets for the AI. For anything related to 'values', set them relative to other targets. An AI is willing to dedicate twice as many resources and travel twice as far to get to a target worth '2.0' as for a target worth '1.0'. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': Do not use a [filter] tag.
** '''value'''=1: (double) A number greater than 0 (default=1) which determines how much the AI tries to move toward units which pass the filter.

* '''[protect_location]'''="": '''Deprecated'''. Gives the AI a location to protect. Note that the AI does ''not'' station any units around the location, it only sends units to attack any enemy units that come within the guarding radius of the target. Applies to move-to-targets CA only.
** '''x''', '''y''': Standard coordinates. These indicate the location the AI is protecting.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this location.

* '''[protect_unit]'''="": '''Deprecated'''. Gives the AI a set of units to protect. Note once again that the AI does not place units around the protected units if there are no enemies nearby. Applies to move-to-targets CA only.
** '''[[StandardUnitFilter]]''': The unit(s) to protect. Do not use a [filter] tag.
** '''radius''': The radius around it to protect (0 indicates a single hex). {{DevFeature1.13|5}} This key has been changed to protect_radius, though it's preferred to change old code to use the [goal] tag instead.
** '''value''': The importance of protecting this unit.

* '''protect_leader'''=2.0 and '''protect_leader_radius'''=10: '''Deprecated'''. Target any enemy units that come within 'protect_leader_radius' of the AI leader with a value of 'protect_leader'. Applies to move-to-targets CA only.

== Filtering which Units Participate in which Actions==

{{DevFeature1.15|3}}

Each [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|candidate action of the default AI]] can be restricted to apply to only a subset of the AI units. This is done by adding a '''[filter_own]''' tag to the '''[[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Candidate_Actions|[candidate_action]]]''' tag definition.

Typical use cases:
* Restricting an action to certain units so that other units are not used to this. For example, village grabbing could be restricted to scout units only, so that slower units do not take detours on their way toward the enemies. See the example below.
* Excluding units from a certain action in order to have them available for other actions afterward. For example, one might want to add a custom candidate action which moves healers behind injured units (or use the existing [[Micro_AIs|Micro AI]] for this). Ideally, this should happen after ''all'' other units have moved, specifically also after the move-to-targets candidate action (MtT CA) is done. In the default setting, however, the MtT CA would also move the healers. Thus, we would want to exclude them using a '''[filter_own]''' tag.
* Adding two instances of the same candidate action with different scores to force the order in which units participate in this action. For example, one could add another instance of the move-leader-to-keep CA with a '''[filter_own]''' tag restricting it to one leader, in order to make this leader move to a keep (and therefore recruit) first.

Note that for the combat AI, using the attacks aspect to filter units as described in the next section '''is slightly more efficient'''. Thus, that should be the preferred method if there are many units on the map.

Example:
<syntaxhighlight lang='wml'>
[candidate_action]
id=villages
engine=cpp
name=ai_default_rca::get_villages_phase
max_score=60000
score=60000
[filter_own]
type=Wolf Rider
[/filter_own]
[/candidate_action]
</syntaxhighlight>

== Filtering Combat with the ''attacks'' Aspect==

The ''attacks'' aspect lets us filter the units considered by the ''combat'', ''high_xp_attacks'' and ''spread_poison'' candidate actions. Units on the AI side can be selected with the '''[filter_own]''' tag and enemy units are filtered via '''[filter_enemy]''', both of which take a [[StandardUnitFilter]]. Only units defined in these tags are considered as attacker/target pairs. To define, for example, an ''attacks'' aspect in which units from the elvish sorceress line are the only attackers, and undead units are the only targets, use
<syntaxhighlight lang='wml'>
[ai]
[aspect]
id=attacks
[facet]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/facet]
[/aspect]
[/ai]
</syntaxhighlight>
Several important notes:
* The ''attacks'' aspect is a ''composite'' aspect and cannot be defined using the simple syntax of the other ''standard'' aspects. See [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|here]] for a description of the syntax of the example.
* This only works if <code>invalidate_on_gamestate_change=yes</code> is set. The reason is that the ''attacks'' aspect internally contains information about all available attacker/target pairs. These need to be recalculated after each move. This is explained [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|here]].
* If [filter_own] or [filter_enemy] are omitted, the selection defaults to all units of the respective sides.
* '''Most importantly''': The above example results in sorceress-line vs undead attacks being the <u>only</u> attacks done by the AI. No other attacks are executed, no matter how advantageous their outcomes may be. There is no simple way around that, but it can be accomplished by one of the following means:
** Setting up the [filter_own] or [filter_enemy] [[StandardUnitFilter]]s to adapt dynamically to the situation on the map.
** Adding a Lua candidate action which dynamically adjusts the aspect depending on the current situation on the map. An example of dealing with this is given in the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|Micro AI test scenario]] [https://github.com/wesnoth/wesnoth/blob/master/data/ai/micro_ais/scenarios/protect_unit.cfg ''Protect Unit''].
** Using [[LuaAI#Dynamic_Lua_Aspects|dynamic Lua aspects]] is in principle also possible, but far from easy due to the complex tables this aspect returns.

{{DevFeature1.13|5}}

Though the above code still works in 1.13.5 and later (and will continue to work indefinitely), it can also be simplified a little:
<syntaxhighlight lang='wml'>
[ai]
[attacks]
invalidate_on_gamestate_change=yes
[filter_own]
type=Elvish Sorceress,Elvish Enchantress,Elvish Sylph
[/filter_own]
[filter_enemy]
race=undead
[/filter_enemy]
[/attacks]
[/ai]
</syntaxhighlight>

'''See also:''' [[Wesnoth AI]]
[[Category: WML Reference]]
[[Category:AI]]

Micro AIs

2021-02-07T01:30:59Z

Mattsc: /* Custom Micro AIs */ add link to MAI definition examples

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

'''Examples''' of micro AI setup functions can be found in the [https://github.com/wesnoth/wesnoth/tree/1.14/data/ai/micro_ais/mai-defs default MAI definitions directory]. See the [https://github.com/wesnoth/wesnoth/blob/1.14/data/ai/micro_ais/mai-defs/animals.lua#L4-L12 Big Animals MAI definition] for a simple example. For custom micro AIs, the setup code should be put into a ''[lua]'' tag inside a preload event.

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]

Micro AIs

2021-02-07T01:19:41Z

Mattsc: /* Simple Attack specific keys for the [micro_ai] tag */ add preload event to code example

== A Few General Words about Micro AIs ==

* Micro AIs allow Wesnoth campaign and scenario authors to add new AI functionality without the need for any AI programming. They 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.

* A Micro AI is activated and configured (or deleted) via the [micro_ai] tag, requiring only a few lines of WML code.

* '''Before Wesnoth 1.13.6''', the Micro AI behavior was inconsistent when it came to '''hidden enemies and petrified units'''. Some Micro AIs ignored those, while others did not. In some case there was even a potential for AI errors when an AI unit ran into hidden or petrified enemies. As of 1.13.6, this has all been fixed. The Micro AIs now correctly and consistently ignore hidden units and treat petrified units as blocking the hex they are on but having no effect otherwise, in the same way as the default AI does. '''Important notes:'''
** It is not possible to re-include hidden/petrified units via the Standard Unit Filters (SUFs) used by some of the Micro AIs. In fact, if this is attempted, the filters will generally not match any unit.
*** This only applies to SUFs which go directly into the [micro_ai] tag. Any SUF that is a sub-tag of another filter (for example, of a Standard Location Filter) is taken literally and returns all units matching the filter. If hidden or petrified units are to be excluded from such a sub-filter, that needs to be specified directly in that filter.
** We also note that, because all the Micro AIs are written in Lua, it is possible to [[Micro_AIs#Using_Development_.281.13.29_Version_Micro_AIs_in_your_Stable_.281.12.29_Version_Add-on|move a Micro AI's code into one's add-on]] and modify it to whatever scenario-specific behavior is desired (this does not only apply to hidden/petrified units, but to all behavior). Setting up general Micro AI behavior that works in every possible setting is not feasible, but adapting it to work (only) in the specific setting of a given scenario is often quite simple. If you do not know how to do this, please post a message on the Wesnoth forums and we will be happy to help you with it.

* The '''[[AiWML#List_of_AI_Aspects|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 [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 Micro AIs Feedback thread].

* '''Before Wesnoth 1.13.7''', the Micro AIs did not all work reliably when the '''AI side is under shroud''' and it may have been necessary to turn shroud off for the side when using a Micro AI. {{DevFeature1.13|7}} The Micro AIs now all work for sides under shroud. They do this by disregarding shroud for terrain purposes when path finding, consistent with default Wesnoth AI behavior, while still ignoring hidden units (including those hidden under shroud) correctly.

* 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 AIs are available in mainline since Wesnoth 1.11/1.12.

== Micro AI Test and Demo Scenarios ==

All Micro AIs described here can be checked out in a number of test and demo scenarios. The easiest way to access the test scenarios is by assigning a hotkey to "Start Test Scenario" in the preferences (as of Wesnoth 1.13.8). Then, simply press the hotkey in the titlescreen and select the desired scenario from the list (e.g. 'micro_ai_test' for the overall "switchboard scenario").

Test scenarios can also be accessed from the command line by typing
path/wesnoth-executable -t micro_ai_test
or (depending on your system and Wesnoth version)
path/wesnoth-executable -tmicro_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 requires only one simple step:
==== 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:'''
* '''ca_id''': (string) 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. The same is also true if a Micro AI is changed more than once during a scenario. We therefore '''strongly recommend always setting ''ca_id''''' for MAIs which are, or might be, changed or deleted during a scenario.
** '''Note:''' 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 sections on the individual Micro AIs for details.

'''Required keys for deleting a Micro AI:'''

Only a subset of the keys required for setting up a Micro AI are needed when deleting it. '''side''', '''ai_type''' and '''action'''=delete always need to be provided. '''ca_id''' needs to be given if it was provided when adding the Micro AI (see above for when this is needed).

'''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===

No extra steps need to be taken when combining different 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, this does not mean that all Micro AIs work together in practice. Some are not compatible because they control units in contradictory ways.
* Not all combinations that ''should'' work have been tested yet. If you find a combination that you believe should work but doesn't, [http://forums.wesnoth.org/viewtopic.php?f=10&t=39456 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.

== Animals Micro AIs ==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy units coming into attack range, to the point where the pack might split up. The wolves can, however, be told to attack only prey units as well as to try to avoid other types of units (such as larger predators). 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Note that another wolves AI exists, called [[Micro_AIs#Animals_AI:_Multi-pack_Wolves_.28ai_type.3Dwolves_multipacks.29|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the predator units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the prey units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''attack_only_prey'''=no: In the default configuration, the wolves attack all enemy units in attack range. If this key is set to 'yes', they only attack prey units.
* '''avoid_type''': Comma-separated list of unit types (on enemy sides) which the wolves try to avoid. They try to stay out of these units' way as much as possible when moving around (except when they are moving in to attack another enemy unit) and never attack them.
* '''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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.

'''Notes on default (RCA) AI aspects:'''
* If ''attack_only_prey'' or ''avoid_type'' are set, the Wolves Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]].
* Attacks by the wolves are left to the default (RCA) AI, meaning that the value of ''aggression'' has an influence on the behavior.
*'''[avoid]''': The standard RCA AI aspect used to define locations that should be avoided by the AI is taken into account. Note: as attacks by the wolves are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

Here's an example of a wolves [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=6
ai_type=wolves
action=add

[filter]
type=Wolf
[/filter]
[filter_second]
type=Vampire Bat
[/filter_second]
avoid_type=Yeti,Giant Spider,Ghast,Footpad
[/micro_ai]

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

The Multi-pack Wolves Micro AI is different from the [[Micro_AIs#Animals_AI:_Wolves_.28ai_type.3Dwolves.29|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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".

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a wolves_multipacks [micro_ai] tag usage from the "Wolves" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or if they run into them accidentally (such as ambushers).

For a demonstration of the Big Animals AI behavior, check out the "Animals" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the animals to which this AI is applied. The filter automatically includes the side= key set to the AI side.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': The big animals often go for long distance (multi-turn) journeys. This tag is a [[StandardLocationFilter|Standard Location Filter]] describing the terrain from which the next goal is chosen. The default is all terrain on the map.
* '''[filter_location_wander]''': The terrain on which the big animals will end their moves. This is a [[StandardLocationFilter|Standard Location Filter]]. The default is all terrain on the map.
* '''[avoid_unit]''': A [[StandardUnitFilter|Standard Unit Filter]] describing all enemy units that the big animals will avoid. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

Here's an example of big_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=3
ai_type=big_animals
action=add

[filter]
type=Ghast
[/filter]
[avoid_unit]
type=Yeti,Giant Spider,Ghast,Footpad
[/avoid_unit]
[filter_location]
x,y=1-40,1-18
[/filter_location]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-3</tt> to <tt>ca_score</tt>.
* '''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 [[StandardLocationFilter|Standard Location Filter]] describing the terrain on which the forest animals wander when they are not threatened by enemies.
* '''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.
** {{DevFeature1.14|10}} Items used for rabbit holes on the map border used to produce an error. Placing them on the map border therefore needed to be avoided on the scenario setup side. They are now automatically excluded from consideration by the AI code.

Here's an example of forest_animals [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=forest_animals
action=add

deer_type=Vampire Bat
rabbit_type=Giant Rat
tusker_type=Ogre
tusklet_type=Young Ogre
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] describing the herder units (e.g. dogs). The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] describing the herd units (e.g. sheep). The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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. 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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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''. {{DevFeature1.15|0}} '''herd_loc''' can be used instead with a named/special location.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-5</tt> to <tt>ca_score</tt>.

Here's an example of a Herding [micro_ai] tag usage from the "Animals" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=7
ai_type=herding
action=add

[filter]
type=Footpad
[/filter]
[filter_second]
type=Troll Whelp
[/filter_second]
herd_x,herd_y=32,28
[filter_location]
terrain=Rb
[/filter_location]
[/micro_ai]

=== Animals AI: Hunter (ai_type=hunter) ===

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 and until fully healed (whatever happens later).

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''home_x,home_y''': The coordinates of the hex to which the hunter returns and rests at after a kill. {{DevFeature1.15|0}} '''home_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the unit's hunting ground. If this tag is not provided, the hunter uses all of the map.
* '''rest_turns'''=3: (integer) The number of turns the AI stays at home_x,home_y after a kill. It will not leave its home until this number of turns have passed ''and'' it is fully healed.
* '''show_messages'''=no: (boolean) If set to yes, the hunter announces whenever its behavior changes to the next phase. Note that this is meant as debug output for the scenario author. The messages are not translated and are not included in replays (and are only visible to the host in an MP game).

Here's an example of a hunter [micro_ai] tag usage from the "Dragon" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=hunter
action=add

id=Rowck
[filter_location]
x,y=5-30,1-15
[/filter_location]
home_x,home_y=3,15
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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists).
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

Here's an example of a Swarm [micro_ai] tag usage from the "Swarm" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=2
ai_type=swarm
action=add
[/micro_ai]

== Assassin Squad Micro AI (ai_type=assassin) ==

{{DevFeature1.13|6}}

This Micro AI controls one or several assassin units which try to circle around enemy units with the goal of hitting a target unit without being distracted or impeded by other enemies. The units will always attack the target if such attacks are possible, otherwise they will follow the path of least resistance toward it. Notes:

* The main priority for the AI is to find paths that avoid enemy units. However, if no such path can be found, the assassins will still advance toward the target, taking the path exposing the units to the least potential damage from enemies.

* The units will not necessarily follow the same path. The best path is chosen individually for each unit.

* While it is not a requirement for the AI to work, using ambusher or skirmisher units, or units with the quick trait, makes this AI more lethal in many cases.

* The CA evaluation scores of this AI are hard-coded, it does not work otherwise. That means that '''ca_score''' is not a valid key for the [micro_ai] tag.

Enable the Simple Attack Micro AI by using
ai_type=assassin
in the [micro_ai] tag.

===Assassin Squad specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the assassin units. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] defining the target unit.
** It is important to realize that the AI currently only works correctly with a single target unit. It is thus the responsibility of the scenario designer to make sure that this filter matches an individual enemy unit. If several enemy units are to be targeted in the same scenario, several instances of the Assassin Micro AI can be used.
** The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.

'''Optional keys:'''

* '''[prefer]''': A [[StandardLocationFilter|Standard Location Filter]] selecting locations on the map for the assassins to prefer when making their way toward the target unit. This could be used, for example, to make units with the ambush ability move (mostly) through forest or to have the assassins circle around the, say, northern part of the map rather than the south if that is desirable for scenario design purposes.
** As with avoiding enemies, the units will still move across non-preferred terrain if that is either the only option or ''much'' shorter than preferred terrain
** Attacking, once the target unit is in range, is not influenced by the [prefer] SLF.

Here is an example of an Assassin Squad [micro_ai] tag usage:
[micro_ai]
side=2
ai_type=assassin
action=add

[filter]
type=Assassin,Master at Arms,Duelist
[/filter]
[filter_second]
id=Konrad
[/filter_second]
[prefer] # Circle around northern part of map
x=1-9, 10-99
y=1-37, 1-17
[/prefer]
[/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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Bottleneck Defense Micro AI 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. {{DevFeature1.15|0}} '''location_id''' can be used instead with named/special locations.
* '''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. {{DevFeature1.15|0}} '''enemy_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-1</tt> to <tt>ca_score</tt>.
* '''[filter]''': {{DevFeature1.15|3}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the units. Only AI units matching this filter participate in the bottleneck defense. The filter automatically includes the side= key set to the AI side.
* '''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. {{DevFeature1.15|0}} '''healer_loc''' can be used instead with named/special locations.
* '''leadership_x,leadership_y''': Same as ''healer_x,healer_y'', but for units with the leadership ability. {{DevFeature1.15|0}} '''leadership_loc''' can be used instead with named/special locations.

As an example, in the "Bottleneck" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]

== Fast Micro AI (ai_type=fast_ai) ==

{{DevFeature1.13|0}}

This AI is meant as a fall-back AI for scenarios where there are so many units that attacks and moves done by the default AI are slow with long delays before each move. It replaces the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions (CAs). It should be obvious that in order to achieve the faster speed, compromises concerning the quality of the moves have to be made.

Enable the Fast Micro AI by using
ai_type=fast_ai
in the [micro_ai] tag.

'''Combat candidate action:'''
* Attackers are considered individually one at a time. The best attack found for a unit is executed without checking whether a better attack by another unit might be possible.
* The default order in which attackers are considered is by decreasing hitpoints, starting with the strongest unit (in terms of HP). This can be modified with the optional keys below.
* By default, if weaker units block attack hexes for a stronger unit, they do not move out of the way (this is the same as for the default AI). If a hex becomes available after an attack (e.g. due to a weaker unit dying in the attack), all attacks that were possible ''before'' this happened are finished first. Only after that are attacks by the stronger unit reconsidered.
* If include_occupied_attack_hexes=yes is set, weaker units move out of the way for stronger units if possible. This can, however slow down the AI depending on the situation on the map. Use with caution.
* {{DevFeature1.13|2}} Previous to this version, attacks by the leader were bunched in with the attacks by the other units. Now leader attacks are treated separately and contain an extra layer of analysis to determine whether the attack position is "safe" (in an approximate way). Currently, this is done with two simple considerations:
** Count all enemy units that can reach the leader's attack position. If there are more than given by optional parameter 'leader_attack_max_units' (default value 3), do not attack.
** Add up the hitpoints of all enemies that can reach the leader's attack position. If this value, multiplied by optional parameter 'leader_weight'(default value 2), is larger than the leaders hitpoints, do not attack.
** Two optional parameters, 'threatened_leader_fights' and 'leader_additional_threat', can also be used to let the leader attack when the threat at the attack hex is comparable to that at the leader's current position.
** In order to keep this AI as fast as possible, leader attacks are done by a separate candidate action that is only evaluated when all other CAs are done.

'''Move-to-targets, villages and retreat candidate actions:'''
* The move-to-targets, villages and retreat candidate actions of the default AI are removed. Move-to-targets and villages are taken over by the Fast Micro AI, whereas retreat is simply not done.
* This CA moves units toward goals after attacks are done. Goals are unowned (if the AI side has a leader only) and enemy-owned villages and enemy leaders.
* For each goal, units are pre-sorted in order of the fewest moves needed to cover the ''distance'' toward the goal (that is, as if move cost on each hex toward the goal were 1). Units are then considered sequentially and if a unit can get there "efficiently", its move is executed without considering other units.
** A move is considered efficient if the move cost to get to the hex is not more than 'move_cost_factor' larger than the distance to the hex. 'move_cost_factor' is an optional key that defaults to 2. It can be set to values of 1.1 or larger (see below).
** If the move for the current unit is not found to be efficient, the AI considers the next unit instead. If no unit can do an efficient move toward the goal, the best (fastest) of the inefficient moves is selected instead.

* Village goals:
** Village goals are considered before enemy leader goals so that the AI preferentially chooses scouts (or otherwise fast units) for them.
** The number of units sent toward villages depends on the value of the default AI aspect village_value. It is set to village_value/4 times the number of units the AI has left to move. Thus, by default (village_value=1.0) the AI sends a quarter of its units toward villages, and the rest toward enemy leaders. This means that the meaningful range of values for village_value is 0..4.
** Only one unit is moved toward each village. This consideration also overrides the number of units to move toward villages defined by village_value, topping it at the number of unowned/enemy-owned villages on the map.
** Setting village_value=0 disables moving units toward villages altogether. That is, not only are no units chosen, but the village targeting phase of the AI is entirely disabled with no evaluation time used for it. Note that, unlike with the default AI, this also means that no villages within range of an AI unit are grabbed.
** The order in which villages are chosen as goals is some combination of them being close to the AI side's leader and being spread out over the map.

* Enemy leader goals:
** The order of enemy leaders goals is set according to their distance from the AI leader with the closest enemy leader being targeted first (if the AI has a leader, otherwise their order is random). One unit is sent toward each enemy leader in this order, after which the AI starts with the first enemy leader again. This is repeated until all units have moved.

* Guardians (units with ai_special=guardian set) are ignored by the fast move-to-targets CA.

'''Tips for speeding up/modifying the Fast Micro AI in specific scenarios:'''

A number of optional keys and default AI aspects can be used to modify the behavior of the Fast Micro AI. The MAI is set up so that it is a reasonable compromise between speed and quality of the moves in most situations. However, this might not be ideal for all scenarios here are some things that can be done to speed up the AI (or to get better behavior in some situations by doing the opposite):
* Use large values for the default AI aspect aggression. The largest delays before attacks happen (in some circumstances) when the Fast MAI has to consider lots of units with attacks left but decides not to attack with them. See below for a description of how aggression is used by the fast AI.
* Use large values of move_cost_factor (see above for description of what this does). If you want to emphasize units that can move across terrain easily (e.g. bats) to be chosen for village grabbing, you might want to use low values of move_cost_factor, but this might slow down the AI. The default value should work reasonably well in most standard situations, but modifying the value might work better on specific maps.
* Don't use dungeon_mode=yes unless absolutely necessary, even in most dungeon crawls. Test the AI without this setting first and only use it if it is the only way to solve the problem. Often, a minor tweak to the map will have the same effect, without the speed penalty.
* Use include_occupied_attack_hexes=yes with caution. It might (or might not) slow down the attack CA significantly, depending on the scenario.
* Set village_value=0, which makes the AI not consider villages as goals. This has not been found to make a large difference on the maps tested so far, but it might have an effect on maps with a very large number of villages.
* Use attack_hidden_enemies=yes on maps where there are no hidden enemies. Excluding hidden enemies from the attack calculation requires an additional filter to be evaluated that takes extra time. In most cases this will not result in a large computation time saving.

'''Required keys:'''

There are no required keys.

'''Optional keys:'''

* '''attack_hidden_enemies'''=no: (boolean) By default, hidden enemies are excluded from the attack calculation. Setting this to 'yes' makes the AI also consider those enemies as attack targets.
* '''[avoid]''': {{DevFeature1.13|2}} A [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). As with the default AI, units will not step on hexes defined by the [avoid] tag. In addition, no goals will be chosen that lie on those hexes. The one minor exception is that a unit stepping out of the way for another unit might temporarily enter the avoided zone.
* '''dungeon_mode'''=no: (boolean) As much as possible, the Fast Micro AI works with distances between hexes rather than path finding. This works pretty well on open maps and even most dungeon crawls (and similar scenarios), but it might result in some units getting temporarily (and in rare cases permanently) stuck on maps with convoluted labyrinths. If that is the case, setting dungeon_mode=yes triggers more path finding that avoids such situations (but as a result is somewhat slower).
* '''include_occupied_attack_hexes'''=no: (boolean) If set to 'yes', the AI moves weaker units out of the way for a stronger attacker. This might lead to better attacks but is slower, so don't use if speed is essential.
* '''[filter]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the attackers. Only AI units matching this filter will attack, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes the side= key set to the AI side. It does not affect the move-to-targets CA.
* '''[filter_second]''': {{DevFeature1.13|2}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the enemies. Only enemy units matching this filter will be attacked, analog to filtering units using [filter_own] with the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] for the default AI. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side. It does not affect the move-to-targets CA.
* '''leader_weight'''=2: (number >= 0) {{DevFeature1.13|2}} A factor specifying how much more valuable the AI considers side leaders than non-leader units in the attack evaluation. This is also used to determine whether an attack by the leader is safe (see description of the combat candidate action above).
* '''leader_additional_threat'''=1: (number > 0) {{DevFeature1.13|2}} If threatened_leader_fights=yes, the threat at the attack position may be larger by this factor for the leader to leave the keep for an attack.
* '''leader_attack_max_units'''=3: (number >= 0) {{DevFeature1.13|2}} A number specifying how many enemy units within reach are acceptable when determining whether an attack by the leader is safe (see description of the combat candidate action above).
* '''move_cost_factor'''=2: (number >= 1.1) The factor by which the move cost to a goal hex may be larger than the distance to the goal hex for a move to be considered "efficient". See description above. 1.1 is used if this is set to values smaller than 1.1. Smaller values might lead to better behavior, while larger values might speed up the AI.
* '''weak_units_first'''=no: (boolean) If set to 'yes', inverts the order in which units are considered by the combat CA. Attacks are then done in order of increasing hitpoints of the attackers.
* '''skip_combat_ca'''=no: (boolean) If set to 'yes', the fast combat CA is not used. The default AI's high_xp_attack and combat CAs remains in place in this case.
* '''skip_move_ca'''=no: (boolean) If set to 'yes', the fast move-to-targets CA is not used. The default AI's retreat, villages and move-to-targets CAs remains in place in this case.
* '''threatened_leader_fights'''=no: (boolean) {{DevFeature1.13|2}} By default, the AI leader will not attack if the threat at the attack position is too high. If this key is set to 'yes', the leader will attack if the threat there is not larger than the threat at his current position multiplied by the value of 'leader_additional_threat'. This is meant as an option for the endgame: when the AI leader is under attack, he might as well go down fighting.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''aggression''': The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to set how aggressive the AI should attack. It works in roughly the same way as the default AI aspect:
** The value of (1 - aggression) determines how much the AI values its own units compared to the enemy's units. Thus, aggression=0 means that attacks are only done if the AI expects to deal (roughly) the same amount of damage as it will receive. aggression=1 means that expected damage to the AI's units is not considered, only the expected damage to enemy units matters.
** Damage is calculated as a combination of hitpoints and chance to die, in "gold equivalent units".
** Unlike the default AI, aggression is set to 1 for values larger than 1. Allowed values are thus anything from -infinity to +infinity, although only -infinity to +1.0 make sense.
*'''[avoid]''': {{DevFeature1.13|2}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.
*'''attacks aspect''': {{DevFeature1.13|2}} The standard RCA AI [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]] used to filter own and enemy units for attacks is now also taken into account as long as neither [filter] nor [filter_second] (see above under 'optional keys') are defined in the [micro_ai] tag.
*'''village_value=1''': (number ranging from 0 to 4) The [[AiWML#List_of_AI_Aspects|default RCA AI aspect]] used to define how much villages should be targeted by the move-to-targets CA. In the Fast MAI, this defines which fraction of the AI units are moved toward village goals (see above for details). If set to 0, villages are ignored as goals.

'''Notes:'''
* The CA evaluation scores of this AI are hard-coded to the same values as those of the respective [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|default candidate actions]]. ca_score is therefore not a valid optional key.
* The fast Micro AI modifies (removes) the default castle-switch, retreat-injured, spread-poison, high-xp-attack, combat, place-healers, move-to-targets, villages and retreat candidate actions.

Enabling the Fast Micro AI in its default configuration is as simple as this usage example from the "Fast AI" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=fast_ai
action=add
[/micro_ai]

== Generalized Goto Micro AI (ai_type=goto) ==

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 [[StandardUnitFilter|Standard Unit Filter]] (SUF) [alternatively, all side units are used if the SUF is not provided), while the goto locations are given in a [[StandardLocationFilter|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Goto Micro AI by using
ai_type=goto
in the [micro_ai] tag.

===Goto specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''[filter_location]''': A [[StandardLocationFilter|Standard Location Filter]] describing the possible goal locations for the move.

'''Optional keys:'''

* '''[avoid]''': {{DevFeature1.15|0}} A [[StandardLocationFilter|Standard Location Filter]] for the locations which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). Note that the area defined by [avoid] is not entered at all, even if the end point of the move would lie outside the area again.
* '''avoid_enemies''': (number>0) 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.
** Due to an issue with the path finding code, '''tunnels and teleports are ignored in Wesnoth 1.14 and before''' if 'avoid_enemies' is used. This has been fixed in Wesnoth 1.15.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units to be moved. Defaults to all units of the side if not defined. The filter automatically includes the side= key set to the AI side.
* '''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.

'''Standard RCA AI aspects respected by this Micro AI:'''
*'''[avoid]''': {{DevFeature1.15|0}} The standard RCA AI aspect used to define locations that should be avoided by the AI. See above (under 'optional keys') for details.

'''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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]
ca_score=210001
[/micro_ai]
* Send all units of the side toward the southern border of the map
[micro_ai]
side=8
ai_type=goto
action=add

[filter_location]
y=33
[/filter_location]
avoid_enemies=1
[/micro_ai]
* Send units to the four corners of the map (with each unit going to a different corner).
[micro_ai]
side=7
ai_type=goto
action=add

[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 ==
=== General Comments on the Guardian Micro AIs ===

The Guardian Micro AIs can be used to set up different kind of guardian behaviors for a unit or a set of units. 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 the default AI, which might result in the guardian not attacking if the enemy is deemed too strong (this can be influenced by setting the default ''aggression'' value to a different value).
* 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 [[StandardUnitFilter|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=.
* '''return_x,return_y''': The coordinate of the hex the unit returns to after each attack. {{DevFeature1.15|0}} '''return_loc''' can be used instead with a named/special location.

'''Optional keys:'''

* '''ca_score'''=100010: (non-negative integer) The evaluation score of the candidate actions controlling this Micro AI. This AI consist of 2 CAs, one with score <tt>ca_score</tt> the other with <tt>ca_score-20</tt>. 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. {{DevFeature1.13|6}}: This is now changed to 100100 and 99900 in order to avoid conflicts with the new high_XP_attacks candidate action.

Here's an example of a return guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 (or keep the guard in place if the station is unreachable).
* 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 [[StandardUnitFilter|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=.
* '''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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.
* '''guard_x, guard_y''': The x and y position of the guarded location. {{DevFeature1.13|0}} These are now optional keys, defaulting to station_x,station_y if not provided. {{DevFeature1.15|0}} '''guard_loc''' can be used instead with a named/special 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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.

Here's an example of a stationed guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|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=.
* '''distance''': The distance within which an enemy must be to "scare" the unit

'''Optional keys:'''

* '''attack_if_trapped'''='no': {{DevFeature1.13|0}} With the default settings, a coward never attacks. If this key is set to 'yes', the coward attacks the weakest (lowest hitpoints) enemy next to which it ends up after moving (such as a cornered animal would do, blindly lashing out without regards for its own safety).
* '''avoid_x, avoid_y''': The x and y coordinate of the hex to avoid. {{DevFeature1.15|0}} '''avoid_loc''' can be used instead with a named/special location.
* '''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units from which the cowards flee. If not set, this defaults to all enemy units. Note, however, that no "enemy of AI side" condition is added if [filter_second] is specified, meaning that it can include allied and/or enemy units as desired (and even units on the same side as the coward).
* '''seek_x, seek_y''': The x and y coordinate of the hex to seek. {{DevFeature1.15|0}} '''seek_loc''' can be used instead with a named/special location.

Here's an example of a coward [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ===

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, a nesting area or for protecting an unit. 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 [[StandardUnitFilter|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_location]''': A [[StandardLocationFilter|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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_enemy]''': A [[StandardLocationFilter|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. {{DevFeature1.15|0}} '''station_loc''' can be used instead with a named/special location.

Here's an example of a zone guardian [micro_ai] tag usage from the "Guardians" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Hang Out Micro AI by using
ai_type=hang_out
in the [micro_ai] tag.

===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 [[StandardLocationFilter|Standard Location Filter]] for the terrain which the AI units should avoid. If it is not given, the existence of the default (RCA) AI's [avoid] tag is checked (and used if it exists). If neither of these two exists, this parameter is set to default to all castle terrain (<tt>terrain=C*,C*^*,*^C*</tt>) 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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Hang Out action (<tt>side=</tt> is always set and does not need to be provided). It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': A [[StandardLocationFilter|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]''': Contains ([[ConditionalActionsWML#Condition_Tags|WML Condition Tags]]) 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.

'''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. See above (under 'optional keys') for details.

'''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 from the "Hang Out and Messenger" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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.

'''Notes'''
* By default, ''all'' healers of the AI side are controlled by this AI. This includes in particular also the side leader, if the leader is a healer. If you do not want the leader to be included (and possibly be moved away from the keep etc.) use the [filter] tag with canrecruit=no (see below).
* 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.
* {{DevFeature1.15|3}} This Micro AI now takes unit guardian status and the passive_leader aspect into account.

For a demonstration, check out the "Healers" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Healer Support Micro AI 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:'''

* '''[filter]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the healer units. If set, only units on the AI side passing this filter ''and'' having the healing ability are considered by this Micro AI.
*'''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting units to receive healing. If set, only units on the AI side passing this filter ''and'' the other healee selection criteria will be selected for healing by this Micro AI.
* '''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. Note: as attacks by the healers are left to the default AI, there is no separate ''[avoid]'' tag for this Micro AI in order to prevent inconsistencies.

'''Notes:'''
* The Healer Support Micro AI modifies the [[AiWML#Filtering_Combat_with_the_attacks_Aspect|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 from the "Healers" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Lurkers Micro AI by using
ai_type=lurkers
in the [micro_ai] tag

===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 [[StandardUnitFilter|Standard Unit Filter]]. The filter automatically includes the side= key set to the AI side.
* '''[filter_location]''': Specifies the terrain from which the lurkers attack. This is a [[StandardLocationFilter|Standard Location Filter]].

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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_location_wander]''': Specifies the terrain on which lurkers end their moves if there is no enemy in reach. This is a [[StandardLocationFilter|Standard Location Filter]]. If [filter_location_wander] is not given, it defaults to [filter_location].
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 or several of its units, the messenger(s). The other units escort the messenger, trying to protect it and attacking enemies that are in its way. Note that a 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.

'''Notes on the use of several messengers:''' {{DevFeature1.13|0}}
* This Micro AI can control several messengers at the same time, which can but do not have to move in a group. They can be put on the map altogether in one location, or be spread out on the map or across different turns.
* The farther a messenger has moved through the chain of waypoints, the higher a priority it is for the AI, meaning that farther advanced (on the map) messengers are moved first, and that the escort units try to clear the way and stay with those messengers more so than with those further back on the map. This order can be inverted using the invert_order= key.
* If several messengers are on the map, escort units might move from one to the other, the AI making a judgement call where they are needed most. Closeness to a messenger is generally the most important criterion, but not the only one.
* If a messenger dies, the escort units previously staying with it now join one of the other messengers if there are any left (otherwise they follow default AI behavior).
* If you want certain escort units to stay always with the same messenger, use several messenger [micro_ai] tags with different [filter]/[filter_second] combinations.

For a demonstration, check out the "Messenger" scenario from the [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Messenger Escort Micro AI by using
ai_type=messenger_escort
in the [micro_ai] tag.

===Messenger Escort specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': {{DevFeature1.13|0}} (Previous to 1.13.0, only id= was allowed.) The id of a unit or a [[StandardUnitFilter|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.
* '''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. {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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 <tt>ca_score-2</tt> to <tt>ca_score</tt>.
* '''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).
* '''[filter_second]''': {{DevFeature1.13|0}} A [[StandardUnitFilter|Standard Unit Filter]] selecting the escort units. If not set, this defaults to all enemy units. The filter automatically includes the side= key set to the AI side.
* '''invert_order'''=no: {{DevFeature1.13|0}} If set to 'yes', the order of priority with which messenger units are considered is inverted, starting with the messenger unit that is the least advanced on the map (see description above). In most cases, selecting this option results in worse performance of the AI, so use it with caution. (And obviously it has no effect at all if there is only one messenger controlled by the AI.)

Here's an example of [micro_ai] tag usage from the "Messenger Escort" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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) ==

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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Patrol Micro AI it by using
ai_type=patrol
in the [micro_ai] tag.

===Patrol specific keys for the [micro_ai] tag:===

'''Required keys:'''

* '''id''' or '''[filter]''': The ID of a unit or a [[StandardUnitFilter|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=.
* '''waypoint_x,waypoint_y''': Comma-separated lists of the waypoint coordinates through which the patrol travels (in order). {{DevFeature1.15|0}} '''waypoint_loc''' can be used instead with named/special locations.

'''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#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 enemy 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

Enable the Protect Unit Micro AI 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. {{DevFeature1.15|0}} '''goal_loc''' can be used instead with a named/special location.

'''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 [[AiWML#Filtering_Combat_with_the_attacks_Aspect|attacks aspect]]. Depending on the parameters, it might also modify the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
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==
=== 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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|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.
* '''[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_recruiting'''=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" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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.
* {{DevFeature1.15|2}} '''high_level_fraction'''=0: (non-negative number) The approximate fraction of units of level 2 or higher to be recruited. This is defined as fraction of units on the map, not of new units being recruited during a turn or over several turns (which makes a difference if there are already units on the map). The effect is also cumulative per level (starting from level 2), meaning that 1/3 of L2 units will be recruited in the example above, 1/3*1/3=1/9 L3s etc. The default value is zero, which leaves the high-level unit recruiting to the default Experimental AI algorithm resulting usually in very few such units being recruited.
* '''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.

Here's an example of a rush recruiting [micro_ai] tag usage from the "Recruiting" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]:
[micro_ai]
side=1
ai_type=recruit_rushers
action=add
[/micro_ai]

== Simple Attack Micro AI (ai_type=simple_attack) ==

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 [[AiWML#List_of_AI_Aspects|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 [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|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 [[StandardUnitFilter|Standard Unit Filter]] selecting the units of the AI side participating in the Simple Attack action. It defaults to all units of the side. The filter automatically includes the side= key set to the AI side.
* '''[filter_second]''': A [[StandardUnitFilter|Standard Unit Filter]] selecting the units the AI should attack. It defaults to all enemy units. The filter automatically includes a [[StandardSideFilter|Standard Side Filter]] set to all enemies of the AI side.
* '''weapon'''=-1: (integer) The number of the weapon that should be used for this attack. Weapon numbers start at 1 (not 0). -1 stands for "best weapon" (by whatever criterion the AI chooses to use). '''Available from Wesnoth 1.11.8'''

Below are 2 examples of Simple Attack Micro AI configurations from the "Simple Attack" [[Micro_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]]. 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 second example executes attacks by Soulless on all enemy units that are 1 XP from leveling. Note that the Lua code in the preload event is there simply 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.
[event]
name=preload
first_time_only=no
[lua]
code=<<
function close_to_advancing(unit)
if (unit.experience >= unit.max_experience-1) then
return true
else
return false
end
end
>>
[/lua]
[/event]

[event]
name=prestart
[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]
[/event]
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_AIs#Micro_AI_Test_and_Demo_Scenarios|test scenario]].

== Custom Micro AIs ==

{{DevFeature1.13|5}}

From 1.13.5 onwards, adding a new Micro AI can be easily done without altering any core files or overriding the micro_ai tag. The [micro_ai] tag now looks up its ''ai_type'' parameter in the <code>wesnoth.micro_ais</code> table and uses the micro AI setup function found there to determine which keys are required and allowed and what candidate actions to add.

A micro AI setup function takes as its single parameter the contents of the [micro_ai] tag and returns three separate values:
*'''required''': A list of required keys and tags, as strings. Tags are indicated by enclosing them within square brackets in the string. If a key or tag in this list is missing from the [micro_ai] tag, an error will be printed.
*'''optional''': Similar to above, a list of optional keys and tags, as strings. No error will be printed if a key or tag in this list is missing, nor will an error be printed if it is present (as would be the case for unrecognized keys or tags).
*'''ca_params''': A table specifying the candidate actions that constitute the micro AI. It should contain an ''ai_id'' key (which specifies a base ID to be used for candidate actions of this micro AI) and a series of candidate action definitions. Each candidate action definition is a table containing the following keys:
**'''ca_id''': The ID used for the candidate action. This will be combined with the ''ai_id'' to produce the final ID.
**'''location''': Path to the Lua file that defines the candidate action.
**'''score''': The maximum score for the candidate action. If the [micro_ai] tag specified a ''ca_score'' parameter, the score here should normally be based on that.

(The return statement would thus look like <syntaxhighlight lang='lua' inline>return required, optional, ca_params</syntaxhighlight>.)

Since the function has full access to the contents of the [micro_ai] tag, it can conditionally add candidate actions to '''ca_params''' depending on the values of other keys within the [micro_ai] tag. It can also perform other actions such as adding facets to an aspect; if it does such things, it should pay attention to the ''action'' key to determine whether it's being added or removed.

There are two useful helper functions that can be used by Micro AI setup functions requiring aspect changes. They can be brought into scope by a line similar to the following:
<syntaxhighlight lang='lua>local MAIH = wesnoth.require("ai/micro_ais/micro_ai_helper.lua")</syntaxhighlight>
* MAIH.add_aspects(side, aspect_params)
* MAIH.delete_aspects(side, aspect_params)

The ''aspect_params'' parameter is an array of tables, each of which contains the following keys:
*'''aspect''': The aspect to change.
*'''facet''': The WML defining the facet. This must include an ''id'' key in order for the aspect to be correctly deleted. For maximum compatibility, incorporate the ''ca_id'' key from the [micro_ai] tag.

'''See also:''' [[Wesnoth AI]]
[[Category:AI]]