Modifying AI Components - Revision history

Celtic Minstrel: /* [modify_ai] Tag Syntax */ Be clearer about the basic format of the new configuration tag.

2026-02-01T07:36:45Z

‎[modify_ai] Tag Syntax: Be clearer about the basic format of the new configuration tag.

Celtic Minstrel: /* Possible values for [modify_ai]path */ Try to be more clear about what's possible

2026-02-01T07:31:47Z

‎Possible values for [modify_ai]path: Try to be more clear about what's possible

Soliton: /* The [modify_ai] Tag */

2023-07-13T15:59:26Z

‎The [modify_ai] Tag

Mattsc: /* Modifying Candidate Action of the main_loop Stage */ comment on other attack CAs

2019-12-11T21:34:19Z

‎Modifying Candidate Action of the main_loop Stage: comment on other attack CAs

Celtic Minstrel: /* A Few More Notes on Modifying Aspects */ Additional note on new feature

2016-07-15T18:51:36Z

‎A Few More Notes on Modifying Aspects: Additional note on new feature

Celtic Minstrel: /* Possible values for [modify_ai]path */ Additional example

2016-07-15T18:49:35Z

‎Possible values for [modify_ai]path: Additional example

Celtic Minstrel: /* Possible values for [modify_ai]path */ Rephrase list as examples rather than an exhaustive list of possibilities, and properly explain the path structure

2016-07-15T16:07:06Z

‎Possible values for [modify_ai]path: Rephrase list as examples rather than an exhaustive list of possibilities, and properly explain the path structure

Celtic Minstrel: /* Modifying AI Component Examples */ Apply syntax highlighting

2016-07-14T19:19:43Z

‎Modifying AI Component Examples: Apply syntax highlighting

Show changes

Celtic Minstrel: /* Possible values for [modify_ai]path */ Make note of new feature

2016-07-14T18:34:46Z

‎Possible values for [modify_ai]path: Make note of new feature

Celtic Minstrel: /* Using [modify_side] to Change Aspects Mid Scenario */ Apply syntax highlighting

2016-07-14T18:31:24Z

‎Using [modify_side] to Change Aspects Mid Scenario: Apply syntax highlighting

@@ Line 60: / Line 60: @@
 ** 'try_delete': Delete a component if it exists.  This does not produce a warning if [modify_ai] fails to change the AI.
 * '''path''': (string) Defines the component of the AI to be modified.  See below.
-* '''New configuration''' for the component: This depends on the type of component and is shown in the examples below.
+* '''New configuration''' for the component (only when adding or changing): This depends on the type of component and is shown in the examples below. It must always be a tag whose name matches the final component of the '''path'''.
 ====Possible values for [modify_ai]path ====

@@ Line 64: / Line 64: @@
 ====Possible values for [modify_ai]path ====
-Depending on the AI component one wants to modify, the '''path''' key can take on different values. The general form of a path is a series of elements separated by dots; each element consists of a component type followed by an ID in square brackets. In many cases, the path consists of only a single level (goals or stages) or two levels (aspect/facet and stage/CA), but {{DevFeature1.13|5}} three or even four levels is occasionally possible with aspects. Some examples:
+Depending on the AI component one wants to modify, the '''path''' key can take on different values. The general form of a path is a series of elements separated by dots; each element consists of a component type followed by an ID in square brackets. In many cases, the path consists of only a single level (goals or stages) or two levels (aspect/facet and stage/CA), but {{DevFeature1.13|5}} three or even four levels is occasionally possible with aspects.
 * Select facet 'quark' of the aggression (composite) aspect: <code>aspect[aggression].facet[quark]</code>
 * {{DevFeature1.13|5}} Select recruit job 'bobby' of the recruitment_instructions aspect defined as a standard aspect: <code>aspect[recruitment_instructions].recruit[bobby]</code>
 * {{DevFeature1.13|5}} Select the default facet of the (composite) village_value aspect: <code>aspect[village_value].facet[default_facet]</code>
 * Select goal 'lighthouse': <code>goal[lighthouse]</code>
 * Select the 'main_loop' stage: <code>stage[main_loop]</code>
 * Select candidate action 'healer_support' of the 'main_loop' stage: <code>stage[main_loop].candidate_action[healer_support]</code>
+* Select an unspecified facet in the composite 'aggression' aspect: <code>aspect[aggression].facet[]</code>
 If all this seemed a bit theoretical, don't worry.  Below, we provide many examples for how to do this in practice.

@@ Line 44: / Line 44: @@
 == The [modify_ai] Tag ==
-The [modify_ai] tag is a tool for modifying [[Wesnoth_AI_Framework#Stages|stages]], [[Wesnoth_AI_Framework#The_Candidate_Actions_of_the_main_loop_Stage|candidate actions]], [[Wesnoth_AI_Framework#Aspects_and_Goals|aspects and goals]] of the active AI on the fly at any time during a scenario.  Since all this functionality is packed into a single tag, its syntax is a bit more complex than that of other tags.  To facilitate this, Wesnoth also provides a large variety of [[#Modifying_AI_Components_Helper_Macros|helper macros]], but even for using those one still needs to understand how the general syntax of the [modify_ai] tag.
+The [modify_ai] tag is a tool for modifying [[Wesnoth_AI_Framework#Stages|stages]], [[Wesnoth_AI_Framework#The_Candidate_Actions_of_the_main_loop_Stage|candidate actions]], [[Wesnoth_AI_Framework#Aspects_and_Goals|aspects and goals]] of the active AI on the fly at any time during a scenario.  Since all this functionality is packed into a single tag, its syntax is a bit more complex than that of other tags.  To facilitate this, Wesnoth also provides a large variety of [[#Modifying_AI_Components_Helper_Macros|helper macros]], but even for using those one still needs to understand the general syntax of the [modify_ai] tag.
 Note that the [modify_ai] tag can be used both in [event] tags and in [side][ai], [era][ai] or [modification][ai] tags, meaning it can also be used to change the AI configuration at game setup time.

@@ Line 289: / Line 289: @@
 === Modifying Candidate Action of the ''main_loop'' Stage ===
-The syntax for modifying candidate actions is entirely equivalent to that for aspects and goals shown above. If one wants to, for example, set up an AI that does not fight, this can be done by removing the [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|''combat'' CA]].
+The syntax for modifying candidate actions is entirely equivalent to that for aspects and goals shown above. If one wants to, for example, set up an AI that does not fight, this can be done by removing the ''combat'' CA.  {{DevFeature1.15|3}} There are now additional CAs which also perform attacks. Check out [[RCA_AI#The_Candidate_Actions_.28CAs.29_of_the_main_loop_Stage_in_the_RCA_AI|the candidate actions of the default AI]] to see which CAs need to be remove in order to produce an AI that truly does not attack.
 <syntaxhighlight lang='wml'>
 [modify_ai]

@@ Line 237: / Line 237: @@
 === A Few More Notes on Modifying Aspects ===
-* The aspect itself and its [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|[default]]] facet cannot be deleted, only the custom facets.
+* The aspect itself and its [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|[default]]] facet cannot be deleted, only the custom facets. {{DevFeature1.13|5}} However, they can be changed, replacing them with a new definition. (The id attribute must match when changing an aspect.) This could change a standard aspect to a composite aspect or vice versa.
 * For standard aspects, it is generally not necessary to delete custom facets.  One can simply overwrite the current value with a new one.  The only times when one might have to remove a standard aspect is when it is defined for specific times of day or turns, or when it is defined so many times that it might bloat the AI configuration (and therefore the savefile).
 * We can also use <code>action=change</code> to delete an existing facet and overwrite it with a new definition.  If <code>*</code> is used as ''facet_id'', this deletes all existing facets of this aspect and replaces them with a single facet with the new definition.

@@ Line 66: / Line 66: @@
 Depending on the AI component one wants to modify, the '''path''' key can take on different values:
-* aspect[aspect_id].facet[facet_id]
+* aspect[aspect_id].facet[facet_id] ({{DevFeature1.13|5}} more complex paths for aspects are also possible)
 * goal[goal_id]
 * stage[stage_id]

@@ Line 13: / Line 13: @@
 The [modify_side] tag can contain an [ai] tag for modifying aspects while a game is in progress.  This works, however, <u>only</u> for [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|standard aspects]].  An example is
- [modify_side]
+<syntaxhighlight lang='wml'>
-     side=2
+[modify_side]
-     [ai]
+    side=2
-         aggression=0.765
+    [ai]
-     [/ai]
+        aggression=0.765
- [/modify_side]
+    [/ai]
 [[Wesnoth_AI_Framework#The_.5Bai.5D_Tag_.E2.80.94_Aspects|Composite aspects]] and all other [[Wesnoth_AI_Framework#Types_of_AI_Components|AI components]] cannot be modified in this way.  Use the [modify_ai] tag described below for these tasks.
@@ Line 25: / Line 27: @@
 Note that it is, in principle, also possible to define the aspect using this syntax
- [modify_side]
+<syntaxhighlight lang='wml'>
-     side=2
+[modify_side]
-     [ai]
+    side=2
-         [aspect]
+    [ai]
-             id=aggression
+        [aspect]
-             [facet]
+            id=aggression
-                 value=0.765
+            [facet]
-             [/facet]
+                value=0.765
-         [/aspect]
+            [/facet]
-     [/ai]
+        [/aspect]
- [/modify_side]
+   [/ai]
 However, as this <u>only</u> works for standard aspects which can also be set with the simpler syntax shown above, there is really no point in doing so.