AIWML - Revision history

Egallager: /* Filtering Combat with the attacks Aspect */ make "See Also" its own section

2024-10-21T06:38:03Z

‎Filtering Combat with the attacks Aspect: make "See Also" its own section

Celtic Minstrel: /* List of AI Aspects */ fix template

2024-02-25T01:32:10Z

‎List of AI Aspects: fix template

Celtic Minstrel: /* List of AI Aspects */ Add anchors for other pages to link to

2024-02-25T01:31:16Z

‎List of AI Aspects: Add anchors for other pages to link to

Show changes

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

2022-06-22T23:20:03Z

‎List of AI Aspects: add allow_ally_villages aspect

Mattsc: /* The [goal] Tag */ add id=

2022-06-13T02:39:01Z

‎The [goal] Tag: add id=

Mattsc: /* Removed AI Aspects */ attack_depth is removed also

2021-06-30T14:00:13Z

‎Removed AI Aspects: attack_depth is removed also

Egallager: /* Customizing the Default AI Using WML */ more links to related pages

2021-04-25T01:58:21Z

‎Customizing the Default AI Using WML: more links to related pages

Mattsc: /* List of AI Aspects */ Minor wording update to retreat aspects

2021-02-27T16:41:04Z

‎List of AI Aspects: Minor wording update to retreat aspects

Mattsc: /* List of AI Aspects */ add retreat_factor and retreat_enemy_weight aspects

2021-02-27T16:35:27Z

‎List of AI Aspects: add retreat_factor and retreat_enemy_weight aspects

UnwiseOwl: Adding more detail in the notes

2020-03-01T00:37:16Z

Adding more detail in the notes

@@ Line 331: / Line 331: @@
 </syntaxhighlight>
 [[Category: WML Reference]]
 [[Category:AI]]

@@ Line 115: / Line 115: @@
 *{{anchor|retreat_factor|'''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.
-*{{anchor_retreat_enemy_weight|'''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:
+*{{anchor|retreat_enemy_weight|'''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

@@ Line 64: / Line 64: @@
 *** 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.

← Older revision		Revision as of 02:39, 13 June 2022
Line 163:		Line 163:

	* '''protect_radius'''=20: (int) The protection radius. Applies to ''protect_location'', ''protect_unit'' and ''protect_my_unit''.		* '''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===		===Examples of [goal] Tag Usage===

@@ Line 130: / Line 130: @@
 === 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.
+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)

@@ Line 9: / Line 9: @@
 * Instructions for setting them up at the beginning of the scenario in a [side] tag
-This page does not contain:
+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 ==

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

@@ Line 70: / Line 70: @@
 * '''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:
@@ Line 111: / Line 108: @@
 *'''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]].
 * '''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.

@@ Line 44: / Line 44: @@
 ==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 will be the only one that applies.
+'''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:'''
@@ Line 67: / Line 67: @@
 * '''[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 will be the only one that applies.
+**'''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]]):