AI Recruitment - Revision history

Celtic Minstrel: /* Aspect recruitment_instructions */ Add some anchors that can be linked to

2024-02-27T05:25:27Z

‎Aspect recruitment_instructions: Add some anchors that can be linked to

Soliton: /* Map analysis */

2023-07-27T12:36:04Z

‎Map analysis

Egallager: /* Other Recruitment Related Aspects */ oops, missed a punctuation fix

2023-02-24T23:30:29Z

‎Other Recruitment Related Aspects: oops, missed a punctuation fix

Egallager: /* Other Recruitment Related Aspects */ minor punctuation tweaks

2023-02-24T23:29:52Z

‎Other Recruitment Related Aspects: minor punctuation tweaks

Celtic Minstrel: Syntax highlighting

2018-03-26T05:13:00Z

Syntax highlighting

Show changes

Holius: fix errors (title levels)

2017-11-30T15:28:17Z

fix errors (title levels)

Celtic Minstrel: /* Aspect recruitment_instructions */ Update with new features

2016-07-14T18:25:31Z

‎Aspect recruitment_instructions: Update with new features

Mattsc: /* Making recruitment strong */ Add changes done in 1.13.5

2016-03-25T00:57:22Z

‎Making recruitment strong: Add changes done in 1.13.5

Mattsc: /* Aspect recruitment_instructions */ fix a link

2016-02-29T03:33:03Z

‎Aspect recruitment_instructions: fix a link

Mattsc: /* Score Map */ fix a link

2016-02-29T03:31:30Z

‎Score Map: fix a link

@@ Line 102: / Line 102: @@
 * The [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|other keys possible in [facet] tags]] can, in principle, also be used, but note that ''invalidate_on_gamestate_change'' and ''invalidate_on_minor_gamestate_change'' have no effect on [recruit] tags.  They are read at the beginning of the turn and are immutable for the remainder of the turn.
-Attributes inside '''[recruit]''':
+Attributes inside {{anchor|instructions-recruit|'''[recruit]'''}}:
 * '''id''': (string) {{DevFeature1.13|5}} By specifying an ID it becomes possible to manipulate the [recruit] tags using [[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]]. This is entirely optional.
 * '''type='''"": (string) This key takes a comma separated list containing unit types, usages or levels. Common values for ''usage'' are 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means 'all units'. If more than one unit is specified, the AI decides what to recruit according to the score map.
@@ Line 112: / Line 112: @@
 * '''pattern'''=no: (boolean) If set to 'yes', the unit to recruit is not chosen by the AI, but randomly according to the frequency in the type attribute. For example, when <code>type=Orcish Grunt, Orcish Grunt, scout</code> and <code>number=6</code>, the AI recruits 6 units, with the probability that one unit is a grunt being twice as high as that of a scout. If the ''type'' attribute is empty, the AI recruits randomly. (See also [[#Other_Recruitment_Related_Aspects|''recruitment_pattern'']])
-Attributes inside '''[limit]''':
+Attributes inside {{anchor|instructions-limit|'''[limit]'''}}:
 * '''id''': (string) {{DevFeature1.13|5}} By specifying an ID it becomes possible to manipulate the [limit] tags using [[DirectActionsWML#.5Bmodify_ai.5D|modify_ai]]. This is entirely optional.
 * '''type'''="": (string) This key takes a comma separated list containing unit types, usages or levels. An empty string means 'all units'.

@@ Line 5: / Line 5: @@
 In a first step, the CA analyzes the map and tries to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense rating for the combatants.
-When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with white 'x' markers on the map.
+When the game is running in debug mode ('''must''' be started with <code>--debug</code>, enabling debug mode in-game is not the same) ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with white 'x' markers on the map.
 ===Score Map===

@@ Line 370: / Line 370: @@
 *'''recruitment_diversity'''=2.0: (double) When this value is high, the AI recruits more units which are currently rare on the map. When the value is 0.0, the AI only recruits the best unit. See [[#Implementation_details_for_interested_readers|above]] for implementation details.
-*'''recruitment_more'''="": (string) This key takes a comma separated list containing unit types, usages, or levels. This is meant to let a scenario editor make an easy hack for making the AI recruit more units of a specific type. (25 will be added to the unit type's score.) The same unit type can also be used several time.  For example, with <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add a total of 50 to the Grunt's score.
+*'''recruitment_more'''="": (string) This key takes a comma separated list containing unit types, usages, or levels. This is meant to let a scenario editor make an easy hack for making the AI recruit more units of a specific type. (25 will be added to the unit type's score.) The same unit type can also be used several time.  For example, with <code>recruitment_more="Orcish Grunt, Orcish Grunt"</code> it is possible to add a total of 50 to the Grunt's score.
 *'''recruitment_randomness'''=50: (int) A random value between 0 and ''recruitment_randomness'' is added to each score. Use a high value, such as '200', to increase randomness.
 *'''recruitment_pattern'''="": (string) This key takes a comma-separated list containing unit types, usages or levels. Common values for ''usage'' are 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).

@@ Line 370: / Line 370: @@
 *'''recruitment_diversity'''=2.0: (double) When this value is high, the AI recruits more units which are currently rare on the map. When the value is 0.0, the AI only recruits the best unit. See [[#Implementation_details_for_interested_readers|above]] for implementation details.
-*'''recruitment_more'''="": (string) This key takes a comma separated list containing unit types, usages or levels. This is meant to let a scenario editor make an easy hack for making the AI recruit more units of a specific type. (25 will be added to the unit type's score.) The same unit type can also be used several time.  For example, with <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add a total of 50 to the Grunt's score.
+*'''recruitment_more'''="": (string) This key takes a comma separated list containing unit types, usages, or levels. This is meant to let a scenario editor make an easy hack for making the AI recruit more units of a specific type. (25 will be added to the unit type's score.) The same unit type can also be used several time.  For example, with <code>recruitment-more="Orcish Grunt, Orcish Grunt"</code> it is possible to add a total of 50 to the Grunt's score.
 *'''recruitment_randomness'''=50: (int) A random value between 0 and ''recruitment_randomness'' is added to each score. Use a high value, such as '200', to increase randomness.
-*'''recruitment_pattern'''="": (string) This key takes a comma separated list containing unit types, usages or levels. Common values for ''usage'' are 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
+*'''recruitment_pattern'''="": (string) This key takes a comma-separated list containing unit types, usages or levels. Common values for ''usage'' are 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. This tells the AI with what probability it should recruit different types of units. The usage is listed in the unit type config files (see data/core/units/ for mainline units; see also [[UnitTypeWML]]).
 **For example, <code>recruitment_pattern=fighter,fighter,2</code> means that the AI recruits on average twice as many fighters as level 2 units. It does not mean that it recruits two fighters first, then a level 2 unit, then two fighters again, etc.
 **Internally ''recruitment_pattern'' expands into a ''recruitment_instructions'' facet with <code>pattern=yes</code> and <code>importance=1</code>. Make sure that there is no ''recruitment_instructions'' facet with <code>importance=1</code> when using ''recruitment_pattern''.

@@ Line 1: / Line 1: @@
 A new [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|recruitment candidate action]] (CA) was introduced and made the default in Wesnoth 1.11.  It is much more configurable than previous versions and supports multiple leader recruiting.  This page describes how it works and the parameters available for customizing it.
-=How it works=
+==How it works==
-==Map analysis==
+===Map analysis===
 In a first step, the CA analyzes the map and tries to find "important hexes". Those are locations on the map where a fight will occur with high probability. The important hexes are later used in combat simulations to calculate an average defense rating for the combatants.
 When the game is running in debug mode ''and'' the game is started with the parameter <code>--log-info=ai/recruitment</code> the important hexes are marked with white 'x' markers on the map.
-==Score Map==
+===Score Map===
 A score map is created for all leaders who are able to recruit. All unit types from the recruit and recall lists are mapped to a score.
@@ Line 23: / Line 23: @@
 * The aspects ''recruitment_more'', ''recruitment_diversity'' and ''recruitment_randomness'' are handled ([[#Other_Recruitment_Related_Aspects|see below]]).
-==Combat Analysis==
+===Combat Analysis===
 For each unit type the AI leaders can recruit, the CA simulates fights against all enemy units on the map. If there are less then 5 enemy units, the enemy recruitment list(s) are also taken into account.
@@ Line 36: / Line 36: @@
   Wolf Rider score:		0
-===Implementation details for interested readers===
+====Implementation details for interested readers====
 The combat analysis uses the function ''compare_unit_types(A, B)''. It takes two unit types and simulates a fight, using a cache because simulation is expensive. The function returns a positive value if unit type ''A'' is better than ''B'' and a negative value if unit type ''B'' is better than ''A''. If the return value is 2.0, it means that unit type A is twice as good as unit type B.
@@ Line 71: / Line 71: @@
+  }
-=Aspect ''recruitment_instructions''=
+==Aspect ''recruitment_instructions''==
 This is a powerful aspect for controlling recruitment via WML.  Its syntax is quite complex and requires the [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|''composite'' aspect configuration]].  At its core are the ''[recruit]'' tags, which are the instructions to the candidate action defining which units are to be recruited.
@@ Line 124: / Line 124: @@
 * {{DevFeature1.13|5}} The tags '''[total]''' and '''[pattern]''' may be used instead of [recruit]. These have basically the same meaning and contents as [recruit], but imply either total=yes or pattern=yes. They are converted to [recruit] tags and can be manipulated as such by modify_ai.
-==Examples==
+===Examples===
 Recruit 3 grunts (and nothing else) on turns 3-5.
   [ai]
@@ Line 272: / Line 272: @@
 Instead, one has to use <code>turns=1-2,4-10</code> in the first facet.
-=Aspect ''recruitment_save_gold''=
+==Aspect ''recruitment_save_gold''==
-==How it works==
+===How it works===
 For several reasons it can be a good idea not to spend all gold at once:
@@ Line 299: / Line 299: @@
 '''Important note:''' While one might assume that the AI plays better when it tries to save some gold, tests show that this is generally not the case. They indicate that, for the current AI, it is always better for the AI to have as many units on the map as possible. This aspect is therefore deactivated by default.
-==The Aspect==
+===The Aspect===
 This aspect also requires the [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|composite syntax]].
   [ai]
@@ Line 318: / Line 318: @@
 * '''save_on_negative_income''': (boolean) If this is set to yes, the AI switches to state SAVE_GOLD even if the income is negative (estimated over 5 turns, village gain and unit loss estimation included).
-==Example==
+===Example===
   [ai]
     [aspect]
@@ Line 338: / Line 338: @@
   {AI_ASPECT recruitment_save_gold {AI_DEACTIVATE_SAVE_GOLD} }
-=Other Recruitment Related Aspects=
+==Other Recruitment Related Aspects==
 *'''recruitment_diversity'''=2.0: (double) When this value is high, the AI recruits more units which are currently rare on the map. When the value is 0.0, the AI only recruits the best unit. See [[#Implementation_details_for_interested_readers|above]] for implementation details.
@@ Line 348: / Line 348: @@
 *'''villages_per_scout'''=4: (int) A number 0 or higher which determines how many scouts the AI recruits. If set to '0', the AI does not recruit scouts to capture villages.
-=Making recruitment strong=
+==Making recruitment strong==
 The default values for the recruitment aspects are chosen to provide variety in the units the AI recruits.  Tests have shown that it plays slightly better (against other AIs, at least) when it mostly recruits the units that score highest in the evaluation explained above.  The best values found are:
@@ Line 358: / Line 358: @@
 In Multiplayer games, the AI 'Strong AI (RCA)' can be chosen with the settings as described here.  {{DevFeature1.13|5}}  As this is only a very minor modification of the default AI, this AI has been changed to a [[Wesnoth_AI#AIs_Available_in_the_Multiplayer_Setup_Menu|Dev AI]] (available in debug mode only) and has been renamed to 'Default AI (RCA) with Alternate Recruiting'.
-=Some notes on multiple leaders=
+==Some notes on multiple leaders==
 The new recruitment CA is able to recruit with multiple leaders — even with different recruitment lists for each leader.  However there are some drawbacks:

@@ Line 97: / Line 97: @@
 Attributes inside '''[recruit]''':
 * '''type='''"": (string) This key takes a comma separated list containing unit types, usages or levels. Common values for ''usage'' are 'scout', 'fighter', 'archer', 'healer' and 'mixed fighter'. An empty string means 'all units'. If more than one unit is specified, the AI decides what to recruit according to the score map.
 * '''number'''=-1: (integer) A number ''n'' greater than 0 instructs the AI to recruit ''n'' units. '-1' means 'as much as possible'. '0' means 'do not recruit'.
@@ Line 106: / Line 107: @@
 Attributes inside '''[limit]''':
 * '''type'''="": (string) This key takes a comma separated list containing unit types, usages or levels. An empty string means 'all units'.
 * '''max'''=0: (int) The maximum of units of the given type(s).
@@ Line 117: / Line 119: @@
   [/recruit]
 The AI then falls back to normal recruiting when all other [recruit] tags are dealt with. This is also the content of the [default] facet for the aspect.
-* Even if only a [limit] tag is used in the aspect declaration, the [default] facet will get overwritten. Include the [recruit] tag mentioned in the previous point to let the AI recruit something.
+* Even if only a [limit] tag is used in the aspect declaration, the [default] facet will get overwritten. Include the [recruit] tag mentioned in the previous point to let the AI recruit something. {{DevFeature1.13|5}} As of 1.13.5, if there is a [limit] tag but no [recruit] tag, an empty [recruit] tag is implied, allowing the AI to recruit. If both [limit] and [recruit] tags are present, no additional [recruit] tag is ever implied.
-* Only one facet at a time can be active. When there are more [facet]s defined in a turn, the behavior is undefined. Use several [recruit] and/or [limit] tags in the same facet instead.
+* Only one facet at a time can be active. When there are more [facet]s defined in a turn, only one will be used (usually the first one). Use several [recruit] and/or [limit] tags in the same facet instead.
 * Do not define more than one [recruit] tag with the same importance. Also note that the aspect ''recruitment_pattern'' expands into a [recruit] tag with importance=1.
 ==Examples==

@@ Line 353: / Line 353: @@
 * '''deactivate recruitment_save_gold''': The AI plays better when it spends all money.
-<s>In Multiplayer games, the AI 'Strong AI (RCA)' can be chosen with the settings as described here.</s>  As this is only a very minor modification of the default AI, it will be removed as a choice available by default in the MP setup menu shortly.  It will still be available in debug mode.
+In Multiplayer games, the AI 'Strong AI (RCA)' can be chosen with the settings as described here.  {{DevFeature1.13|5}}  As this is only a very minor modification of the default AI, this AI has been changed to a [[Wesnoth_AI#AIs_Available_in_the_Multiplayer_Setup_Menu|Dev AI]] (available in debug mode only) and has been renamed to 'Default AI (RCA) with Alternate Recruiting'.
 =Some notes on multiple leaders=

@@ Line 103: / Line 103: @@
 * '''total'''=no: (boolean) If set to 'yes', the AI counts the own units on the map which match at least one of the given types and then recruits the difference between ''number'' and the counted amount.
 * '''blocker'''=yes: (boolean) If set to 'yes', the AI stops recruiting if this job cannot be done (for example, because of lack of gold or a [limit]). If set to 'no', the AI drops this job and tries to continue with less important ones.
-* '''pattern'''=no: (boolean) If set to 'yes', the unit to recruit is not chosen by the AI, but randomly according to the frequency in the type attribute. For example, when <code>type=Orcish Grunt, Orcish Grunt, scout</code> and <code>number=6</code>, the AI recruits 6 units, with the probability that one unit is a grunt being twice as high as that of a scout. If the ''type'' attribute is empty, the AI recruits randomly. (See also [[#Other_aspects|''recruitment_pattern'']])
+* '''pattern'''=no: (boolean) If set to 'yes', the unit to recruit is not chosen by the AI, but randomly according to the frequency in the type attribute. For example, when <code>type=Orcish Grunt, Orcish Grunt, scout</code> and <code>number=6</code>, the AI recruits 6 units, with the probability that one unit is a grunt being twice as high as that of a scout. If the ''type'' attribute is empty, the AI recruits randomly. (See also [[#Other_Recruitment_Related_Aspects|''recruitment_pattern'']])
 Attributes inside '''[limit]''':

@@ Line 21: / Line 21: @@
   Elvish Archer:		  50	 25
   Elvish Ranger:		  50	 25
-* The aspects ''recruitment_more'', ''recruitment_diversity'' and ''recruitment_randomness'' are handled ([[#Other_aspects|see below]]).
+* The aspects ''recruitment_more'', ''recruitment_diversity'' and ''recruitment_randomness'' are handled ([[#Other_Recruitment_Related_Aspects|see below]]).
 ==Combat Analysis==