RCA AI - Revision history

Egallager: /* RCA AI Summary */ minor wikification (tags will probably still need to get their own links, too)

2022-11-28T00:47:41Z

‎RCA AI Summary: minor wikification (tags will probably still need to get their own links, too)

Celtic Minstrel: /* RCA AI Summary */ Add a bit more info. This should probably be linkified but I can't be bothered right now.

2022-11-27T06:58:41Z

‎RCA AI Summary: Add a bit more info. This should probably be linkified but I can't be bothered right now.

Mattsc: /* The Candidate Actions (CAs) of the main_loop Stage in the RCA AI */ castle switch was removed from mainline

2020-03-04T16:26:37Z

‎The Candidate Actions (CAs) of the main_loop Stage in the RCA AI: castle switch was removed from mainline

Mattsc: /* The Candidate Actions (CAs) of the main_loop Stage in the RCA AI */ remove an outdated sentence

2019-12-22T19:53:53Z

‎The Candidate Actions (CAs) of the main_loop Stage in the RCA AI: remove an outdated sentence

Mattsc: /* The Candidate Actions (CAs) of the main_loop Stage in the RCA AI */ Add former Experimental AI CAs

2019-12-12T03:44:07Z

‎The Candidate Actions (CAs) of the main_loop Stage in the RCA AI: Add former Experimental AI CAs

Mattsc: /* RCA AI Stage Configuration */ Add note on new CAs from ExpAI

2019-12-12T01:48:45Z

‎RCA AI Stage Configuration: Add note on new CAs from ExpAI

Mattsc: /* The Candidate Actions (CAs) of the main_loop Stage in the RCA AI */ add high_xp_attack CA

2016-09-04T15:28:43Z

‎The Candidate Actions (CAs) of the main_loop Stage in the RCA AI: add high_xp_attack CA

Mattsc: /* RCA AI Stage Configuration */ add high_xp_attack CA

2016-09-04T15:25:18Z

‎RCA AI Stage Configuration: add high_xp_attack CA

Celtic Minstrel: /* RCA AI Stage Configuration */ Update stage name

2016-08-07T16:38:54Z

‎RCA AI Stage Configuration: Update stage name

Celtic Minstrel: /* RCA AI Configuration */ Apply syntax highlighting and remove version keys

2016-07-14T15:25:18Z

‎RCA AI Configuration: Apply syntax highlighting and remove version keys

@@ Line 12: / Line 12: @@
 * Initial configuration – the '''[ai]''' tag which may be placed in '''[side]''', '''[multiplayer_side]''', or '''[unit]'''.
-* Dynamic modification – ActionWML that modifies AI on the fly. This covers the '''[modify_ai]''' and '''[micro_ai]''' tags (although those can also be placed in the initial configuration) as well as the old '''[add_ai_behaviour]''' tag and some elements of the '''[modify_side]''' tag.
+* Dynamic modification – [[ActionWML]] that modifies AI on the fly. This covers the '''[modify_ai]''' and '''[micro_ai]''' tags (although those can also be placed in the initial configuration) as well as the old '''[add_ai_behaviour]''' tag and some elements of the '''[modify_side]''' tag.
 == RCA AI components  ==

@@ Line 8: / Line 8: @@
 * [[Creating Custom AIs]] and [[Modifying AI Components]]: Adding additional functionality to the RCA AI, or replacing parts or all of it.
 * [[Wesnoth AI]]: Links to all Wesnoth AI resources on this wiki.
 == RCA AI components  ==

← Older revision		Revision as of 16:26, 4 March 2020
Line 34:		Line 34:

	*'''Goto''' CA (score 200,000; C++ CA): Move units toward the coordinates set by [[SingleUnitWML\|goto_x, goto_y]] in their unit WML.		*'''Goto''' CA (score 200,000; C++ CA): Move units toward the coordinates set by [[SingleUnitWML\|goto_x, goto_y]] in their unit WML.
−
−	*{{DevFeature1.15\|3}} '''Castle switching''' CA (scores 195,000 and 15,000; Lua CA): move the leader to a different castle, generally one that is closer to the enemy leader(s).

	*{{DevFeature1.15\|3}} '''Retreat injured''' CA (scores 192,000 and 95,000; Lua CA): retreat injured units that are threatened by enemies to healing locations and away from these enemies.		*{{DevFeature1.15\|3}} '''Retreat injured''' CA (scores 192,000 and 95,000; Lua CA): retreat injured units that are threatened by enemies to healing locations and away from these enemies.

@@ Line 47: / Line 47: @@
 *'''Move leader to keep''' CA (score 120,000; C++ CA): Move the leader toward the closest available keep.
-*'''High XP attack''' CA (score 100,010; Lua CA): An addition to the default AI as of '''Wesnoth 1.13.6''', this CA performs attacks on enemy units so close to leveling that the combat CA (below) does not attack them. Unlike all the other RCA AI candidate actions, this CA is written in Lua.
+*'''High XP attack''' CA (score 100,010; Lua CA): An addition to the default AI as of '''Wesnoth 1.13.6''', this CA performs attacks on enemy units so close to leveling that the combat CA (below) does not attack them.
 *'''Combat''' CA (score 100,000; C++ CA): Attack enemy units that are in range.  Note that this CA includes the move to a hex adjacent to the enemy unit as well as the attack itself.

@@ Line 27: / Line 27: @@
 For each move of its turn, the AI evaluates a number of potential actions, called ''candidate actions'' (CAs). The CA with the highest evaluation score is executed and the process is repeated, until no more valid moves are found.  This ends the AI turn.  (Note: This is the general process of the [[Wesnoth_AI_Framework#Stages|''main_loop'' stage]], it is not specific to the RCA AI.)
-The scores of the RCA AI CAs have fixed values.  These values can be modified, but only to other fixed values.  For example, the recruitment CA by default has a score of 180,000.  The default score for attacks is 100,000.  Thus, if recruiting is possible, it will always be done before attacks.  However, that does not mean that all recruiting always happens before all attacks.
+Most of the RCA AI CAs have a single fixed scores, with a few of the Lua CAs have two distinct (but otherwise also fixed) scores, as indicated below.  These values can, in principle, be modified, but generally only to other fixed values.  For example, the recruitment CA by default has a score of 180,000.  The default score for attacks is 100,000.  Thus, if recruiting is possible, it will always be done before attacks.  If the score of the recruitment CA were lowered to below 100,000, then attacks would always be evaluated (and executed, if possible) before recruiting.
-Consider the case that all castle hexes are occupied by AI units which were recruited on the previous turn and have not been used yet this turn.  No recruiting is possible, so the AI moves on to other CAs.  Once it gets to attacks, one of the units (or a group of units) might be selected to move off the castle and attack a close-by enemy.  Now a castle hex is available for recruiting, which now has the highest evaluation score and is executed.  This cycle might be repeated several times.
+It is important to realize though that the default score settings do not mean that all recruiting always happens before all attacks.  The "if possible" clauses in the previous paragraph become important here.  Consider the case that all castle hexes are occupied by AI units which were recruited on the previous turn and have not been used yet this turn.  No recruiting is possible (in which case the CA returns 0), so the AI moves on to other CAs.  Once it gets to attacks, one of the units (or a group of units) might be selected to move off the castle and attack a close-by enemy.  Now a castle hex is available for recruiting, which now has the highest evaluation score and is executed.  This cycle might be repeated several times.
 In its default configuration, the RCA AI evaluates the following CAs, sorted here in order of their evaluation score:
-*'''Goto''' CA (score 200,000): Move units toward the coordinates set by [[SingleUnitWML|goto_x, goto_y]] in their unit WML.
+*'''Goto''' CA (score 200,000; C++ CA): Move units toward the coordinates set by [[SingleUnitWML|goto_x, goto_y]] in their unit WML.
-*'''Recruitment''' CA (score 180,000): Recruit or recall units.
+*{{DevFeature1.15|3}} '''Castle switching''' CA (scores 195,000 and 15,000; Lua CA): move the leader to a different castle, generally one that is closer to the enemy leader(s).
-*'''Move leader to goals''' CA (score 140,000): Move the leader toward goals set by [[AiWML#List_of_AI_Aspects|[leader_goal]]].
+*{{DevFeature1.15|3}} '''Retreat injured''' CA (scores 192,000 and 95,000; Lua CA): retreat injured units that are threatened by enemies to healing locations and away from these enemies.
-*'''Move leader to keep''' CA (score 120,000): Move the leader toward the closest available keep.
+*{{DevFeature1.15|3}} '''Spread poison''' CA (score 190,000; Lua CA): spread poison to enemies, while taking care not to try to poison unpoisonable or already poisoned units.
-*'''High XP attack''' CA (score 100,010): An addition to the default AI as of '''Wesnoth 1.13.6''', this CA performs attacks on enemy units so close to leveling that the combat CA (below) does not attack them. Unlike all the other RCA AI candidate actions, this CA is written in Lua.
+*'''Recruitment''' CA (score 180,000; C++ CA): Recruit or recall units.
-*'''Combat''' CA (score 100,000): Attack enemy units that are in range.  Note that this CA includes the move to a hex adjacent to the enemy unit as well as the attack itself.
+*'''Move leader to goals''' CA (score 140,000; C++ CA): Move the leader toward goals set by [[AiWML#List_of_AI_Aspects|[leader_goal]]].
-*'''Healing''' CA (score 80,000): Move units onto healing locations (generally villages).
+*'''Move leader to keep''' CA (score 120,000; C++ CA): Move the leader toward the closest available keep.
-*'''Villages''' CA (score 60,000): Move units onto villages that are unowned or owned by an enemy.
+*'''High XP attack''' CA (score 100,010; Lua CA): An addition to the default AI as of '''Wesnoth 1.13.6''', this CA performs attacks on enemy units so close to leveling that the combat CA (below) does not attack them. Unlike all the other RCA AI candidate actions, this CA is written in Lua.
-*'''Retreat''' CA (score 40,000): Evaluate if any units are in grave danger or hopelessly outnumbered, and if so, retreat them.
+*'''Combat''' CA (score 100,000; C++ CA): Attack enemy units that are in range.  Note that this CA includes the move to a hex adjacent to the enemy unit as well as the attack itself.
-*'''Move to targets''' CA (score 20,000): Evaluate potential [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|targets]] and move units toward them.  The evaluation takes into account how valuable the targets are (this is configurable by setting [[AiWML#AI_Targets_and_Goals|goals]]), how easily the AI's units can get there, how exposed to attacks they will be, etc.  Targets are enemy leaders, enemy units that pose a threat to the AI leader and villages, as well as anything defined in a [[AiWML#The_.5Bgoal.5D_Tag|[goal] tag]].  It is important to understand that targets only apply to the ''move-to-targets'' CA.  If a target is within range of the AI's unit(s) on the current turn, other CAs, such as ''combat'', ''healing'' or ''villages'' have a higher evaluation score and are (usually) executed first.  Thus, a target is specifically <u>not</u> an attack target, but a move target.
+*{{DevFeature1.15|3}} '''Place healers''' CA (score 96,000; Lua CA): Place healers adjacent to injured units that have already moved.
-*'''Leader shares keep''' CA (score 10,000): Move the leader off the keep to let an allied leader recruit, if an allied leader can get to the keep in one move.  Note: This CA used to be called ''passive_leader_shares_keep''.  That name still works for the time being but will be deprecated at some point.
+*'''Healing''' CA (score 80,000; C++ CA): Move units onto healing locations (generally villages, but also next to healers that were placed previously).
 As already mentioned, the CAs are always evaluated (and executed, if a possible move is found) in the order given above.  For example, the ''goto'' CA is always the first move that is done (if ''goto_x'' and ''goto_y'' are defined and a move toward that location is possible).  Equivalently, if a valid attack is found in the ''combat'' CA, it is <u>always</u> executed before any healing, village grabbing or move-to-target moves.  One of the effects this has is that attacks always have priority over any goals/targets of the move-to-target phase.  It is '''very important''' to understand this, as it is a frequent source of confusion for scenario creators.
-Note that nothing in Wesnoth's [[Wesnoth_AI_Framework|general AI mechanism]] limits CAs to have fixed evaluations scores.  For examples, some of the [[Micro AIs]] as well as some custom AI CAs return variable scores.
+Note that nothing in Wesnoth's [[Wesnoth_AI_Framework|general AI mechanism]] limits CAs to having fixed evaluation scores.  For example, some of the [[Micro AIs]] as well as some of the new Lua AI CAs return variable scores.
 === Use of Aspects in the RCA AI ===

@@ Line 81: / Line 81: @@
 === RCA AI Stage Configuration ===
-The RCA AI uses only the ''main_loop'' stage.  It is defined in file [https://github.com/wesnoth/wesnoth/blob/master/data/ai/ais/ai_default_rca.cfg ai/ais/ai_default_rca.cfg] in the Wesnoth data directory:
+The RCA AI uses only the ''main_loop'' stage.  It is defined in file [https://github.com/wesnoth/wesnoth/blob/master/data/ai/ais/ai_default_rca.cfg ai/ais/ai_default_rca.cfg] in the Wesnoth data directory.  {{DevFeature1.15|3}} Note that the example below is from a previous Wesnoth version as new candidate actions have since been added to the default AI. The linked file always contains the most up-to-date configuration though and can be used as reference.
 <syntaxhighlight lang='wml'>
 [ai]

← Older revision		Revision as of 15:28, 4 September 2016
Line 40:		Line 40:

	*'''Move leader to keep''' CA (score 120,000): Move the leader toward the closest available keep.		*'''Move leader to keep''' CA (score 120,000): Move the leader toward the closest available keep.
		+
		+	*'''High XP attack''' CA (score 100,010): An addition to the default AI as of '''Wesnoth 1.13.6''', this CA performs attacks on enemy units so close to leveling that the combat CA (below) does not attack them. Unlike all the other RCA AI candidate actions, this CA is written in Lua.

	*'''Combat''' CA (score 100,000): Attack enemy units that are in range. Note that this CA includes the move to a hex adjacent to the enemy unit as well as the attack itself.		*'''Combat''' CA (score 100,000): Attack enemy units that are in range. Note that this CA includes the move to a hex adjacent to the enemy unit as well as the attack itself.

@@ Line 91: / Line 91: @@
          {AI_CA_MOVE_LEADER_TO_GOALS}         # id="move_leader_to_goals"
          {AI_CA_MOVE_LEADER_TO_KEEP}          # id="move_leader_to_keep"
          {AI_CA_COMBAT}                       # id="combat"
          {AI_CA_HEALING}                      # id="healing"

@@ Line 86: / Line 86: @@
      [stage]
          id=main_loop
-         name=testing_ai_default::candidate_action_evaluation_loop
+         name=ai_default_rca::candidate_action_evaluation_loop
          {AI_CA_GOTO}                         # id="goto"
          {AI_CA_RECRUITMENT}                  # id="recruitment"

@@ Line 80: / Line 80: @@
 The RCA AI uses only the ''main_loop'' stage.  It is defined in file [https://github.com/wesnoth/wesnoth/blob/master/data/ai/ais/ai_default_rca.cfg ai/ais/ai_default_rca.cfg] in the Wesnoth data directory:
- [ai]
+<syntaxhighlight lang='wml'>
-     id=ai_default_rca
+[ai]
-     description=_"Multiplayer_AI^Default AI (RCA)" # wmllint: no spellcheck
+    id=ai_default_rca
-     version=10710
+    description=_"Multiplayer_AI^Default AI (RCA)" # wmllint: no spellcheck
-     [stage]
+    [stage]
-         id=main_loop
+        id=main_loop
-         name=testing_ai_default::candidate_action_evaluation_loop
+        name=testing_ai_default::candidate_action_evaluation_loop
-         {AI_CA_GOTO}                         # id="goto"
+        {AI_CA_GOTO}                         # id="goto"
-         {AI_CA_RECRUITMENT}                  # id="recruitment"
+        {AI_CA_RECRUITMENT}                  # id="recruitment"
-         {AI_CA_MOVE_LEADER_TO_GOALS}         # id="move_leader_to_goals"
+        {AI_CA_MOVE_LEADER_TO_GOALS}         # id="move_leader_to_goals"
-         {AI_CA_MOVE_LEADER_TO_KEEP}          # id="move_leader_to_keep"
+        {AI_CA_MOVE_LEADER_TO_KEEP}          # id="move_leader_to_keep"
-         {AI_CA_COMBAT}                       # id="combat"
+        {AI_CA_COMBAT}                       # id="combat"
-         {AI_CA_HEALING}                      # id="healing"
+        {AI_CA_HEALING}                      # id="healing"
-         {AI_CA_VILLAGES}                     # id="villages"
+        {AI_CA_VILLAGES}                     # id="villages"
-         {AI_CA_RETREAT}                      # id="retreat"
+        {AI_CA_RETREAT}                      # id="retreat"
-         {AI_CA_MOVE_TO_TARGETS}              # id="move_to_targets"
+        {AI_CA_MOVE_TO_TARGETS}              # id="move_to_targets"
-         {AI_CA_PASSIVE_LEADER_SHARES_KEEP}   # id="passive_leader_shares_keep"
+        {AI_CA_PASSIVE_LEADER_SHARES_KEEP}   # id="passive_leader_shares_keep"
-      [/stage]
+     [/stage]
- [/ai]
+[/ai]
 '''Note''': Before the RCA AI became the default, it was necessary to include this file (or one of its aliases) in the side definition.  That is not required any more – it is automatically included for all computer controlled sides, except when a stage is defined explicitly using the [stage] tag in the side definition.
@@ Line 105: / Line 106: @@
 In the configuration of the ''main_loop'' stage shown above, each candidate action is included as a macro.  Expanding the macros results in the following syntax (''combat'' CA example):
- [candidate_action]
+<syntaxhighlight lang='wml'>
-     id=combat
+[candidate_action]
-     engine=cpp
+    id=combat
-     name=ai_default_rca::combat_phase
+    engine=cpp
-     max_score=100000
+    name=ai_default_rca::combat_phase
-     score=100000
+    max_score=100000
- [/candidate_action]
+    score=100000
 ==== Available Candidate Actions ====
@@ Line 119: / Line 122: @@
 === RCA AI Aspect and Goal Configuration ===
-When a game is created, '''aspects''' are initialized with the default values given at [[AiWML#List_of_AI_Aspects|AiWML]].  In the [https://github.com/wesnoth/wesnoth/blob/master/data/ai/utils/default_config.cfg configuration file], they are in ''composite'' aspect format (which is why [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Top-level_Elements|<code>version=10703</code>]] is set in the definition of the stage shown above) such as
+When a game is created, '''aspects''' are initialized with the default values given at [[AiWML#List_of_AI_Aspects|AiWML]].  In the [https://github.com/wesnoth/wesnoth/blob/master/data/ai/utils/default_config.cfg configuration file], they are in ''composite'' aspect format such as
- [aspect]
+<syntaxhighlight lang='wml'>
-     id=aggression
+[aspect]
-     engine=cpp
+    id=aggression
-     name=composite_aspect
+    engine=cpp
-     [default]
+    name=composite_aspect
-         engine=cpp
+    [default]
-         name=standard_aspect
+        engine=cpp
-         value=0.4
+        name=standard_aspect
-     [/default]
+        value=0.4
- [/aspect]
+    [/default]
 for ''aggression'', or
- [aspect]
+<syntaxhighlight lang='wml'>
-     id=avoid
+[aspect]
-     engine=cpp
+    id=avoid
-     name=composite_aspect
+    engine=cpp
-     [default]
+    name=composite_aspect
-         engine=cpp
+    [default]
-         name=standard_aspect
+        engine=cpp
-         [value]
+        name=standard_aspect
-             [not]
+        [value]
-             [/not]
+            [not]
-         [/value]
+            [/not]
-     [/default]
+        [/value]
- [/aspect]
+    [/default]
 for ''[avoid]''.