Micro Ais - Revision history

Dalas120: Added documentation for the Regroup Micro AI

2026-08-01T21:48:23Z

Added documentation for the Regroup Micro AI

Name: Note how [micro_ai] side= can take a list of sides as of 1.17.0

2023-08-16T17:35:11Z

Note how [micro_ai] side= can take a list of sides as of 1.17.0

Name at 15:33, 16 August 2023

2023-08-16T15:33:36Z

Egallager: use [filter] tags for id= keys, to pass schema validation

2023-08-13T18:13:36Z

use [filter] tags for id= keys, to pass schema validation

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

2022-06-27T14:47:06Z

‎Custom Micro AIs: add new syntax for keys tables

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

2022-06-26T13:47:48Z

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

Celtic Minstrel: /* A Few General Words about Micro AIs */ Note the three places where [micro_ai] may be used

2022-06-26T03:54:15Z

‎A Few General Words about Micro AIs: Note the three places where [micro_ai] may be used

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

2022-06-24T21:53:10Z

‎Hang Out specific keys for the [micro_ai] tag:

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

2022-06-22T23:12:23Z

‎Rush Recruitment AI (ai_type=recruit_rushers): add reset_cache_each_turn parameter

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

2022-06-13T02:41:16Z

‎Rush Recruitment AI (ai_type=recruit_rushers)

@@ Line 1,197: / Line 1,197: @@
               action=add
            [/micro_ai]
 == Simple Attack Micro AI (ai_type=simple_attack) ==

@@ Line 46: / Line 46: @@
 '''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. As of version 1.17.0 this can be a list of sides.
+* '''side''': The side for which the Micro AI is to be added, changed or deleted. {{DevFeature1.17|0}} this can be a list of sides.
 * '''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:

@@ Line 46: / Line 46: @@
 '''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.
+* '''side''': The side for which the Micro AI is to be added, changed or deleted. As of version 1.17.0 this can be a list of sides.
 * '''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:

@@ Line 336: / Line 336: @@
               ai_type=hunter
               action=add
-−
-              id=Rowck
+              [filter]
               [filter_location]
                   x,y=5-30,1-15
@@ Line 719: / Line 721: @@
               action=add
-              id=return1
+              [filter]
               return_x,return_y=20,2
           [/micro_ai]
@@ Line 758: / Line 762: @@
               action=add
-              id=stationed1
+              [filter]
               distance=4
               station_x,station_y=2,14
@@ Line 799: / Line 805: @@
               action=add
-              id=coward3
+              [filter]
               distance=5
               seek_x,seek_y=24,5
@@ Line 835: / Line 843: @@
               action=add
-              id=zone3
+              [filter]
               [filter_location]
                   x,y=22-31,4-11  # This is intentionally chosen to extend past the lake
@@ Line 1,023: / Line 1,033: @@
               action=add
-              id=messenger
+              [filter]
               waypoint_x=31,24,27,28
               waypoint_y=20,14,7,1
@@ Line 1,066: / Line 1,078: @@
               action=add
-              id=Konrad
+              [filter]
               waypoint_x=9,24,25
               waypoint_y=21,23,15

@@ Line 1,267: / Line 1,267: @@
 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.
+*'''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).
+*'''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.

@@ Line 10: / Line 10: @@
 ** 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].
+* 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.

@@ Line 3: / Line 3: @@
 * 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.
+* 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:'''

@@ Line 868: / Line 868: @@
 * '''[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.
+* '''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:'''

@@ Line 1,175: / Line 1,175: @@
 * {{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]]:

@@ Line 1,160: / Line 1,160: @@
 === 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.
+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