Wesnoth AI Framework - Revision history

Soliton: /* AI Configuration */

2026-10-28T08:03:08Z

AI Configuration

← Older revision		Revision as of 08:03, 28 October 2026
Line 45:		Line 45:
	The Wesnoth AIs are assembled from configurations provided in several different places:		The Wesnoth AIs are assembled from configurations provided in several different places:
	* The default AI parameters in a variety of configuration files in the 'data/ai/' directory		* The default AI parameters in a variety of configuration files in the 'data/ai/' directory
	* Optional [ai] or [modify_ai] tags in era configurations		* Optional [ai] or [modify_ai] tags in [[EraWML\|era configurations]]
	* Optional [ai] or [modify_ai] tags in modification configurations		* Optional [ai] or [modify_ai] tags in [[ModificationWML\|modification configurations]]
	* Optional [ai] or [modify_ai] tags in multiplayer faction configurations		* Optional [ai] or [modify_ai] tags in [[EraWML#Defining_Factions\|multiplayer faction configurations]]
	* Optional [ai] or [modify_ai] tags in scenario configurations		* Optional [ai] or [modify_ai] tags in [[ScenarioWML\|scenario configurations]]
	* Optional [ai] tags in individual unit definitions (ie in the [unit] tag) - note that this option may be removed or drastically changed in the future		* Optional [ai] tags in [[SingleUnitWML\|individual unit definitions]] (ie in the [unit] tag) - note that this option may be removed or drastically changed in the future

	When the game is created, all these config snippets are merged into a single configuration stored in form of an [ai] tag. Then, aspects with the same ids are merged. During the game, whenever a [modify_ai] tag is acted upon (for example in an event), it is added into the existing AI configuration in the same way.		When the game is created, all these config snippets are merged into a single configuration stored in form of an [ai] tag. Then, aspects with the same ids are merged. During the game, whenever a [modify_ai] tag is acted upon (for example in an event), it is added into the existing AI configuration in the same way.

Lexa04: /* The [ai] Tag — Aspects */

2026-08-18T19:30:51Z

The [ai] Tag — Aspects

← Older revision		Revision as of 19:30, 18 August 2026
Line 258:		Line 258:
	terrain=W*		terrain=W*
	[/avoid]		[/avoid]
	[ai]		[/ai]
	</syntaxhighlight>		</syntaxhighlight>
	For simple aspect syntax, several additional keys are available in addition to the aspect names themselves, '''time_of_day''' (as shown in the example above), '''turns''' and {{DevFeature1.13\|5}} '''engine'''. These are also explained at [[AiWML]], but these keys basically affect all aspects defined in this simple syntax. {{DevFeature1.13\|5}} Currently, every aspect except the attacks aspect can be defined in this way. Prior to 1.13.5, there were also a few other aspects that could not be defined in this way.		For simple aspect syntax, several additional keys are available in addition to the aspect names themselves, '''time_of_day''' (as shown in the example above), '''turns''' and {{DevFeature1.13\|5}} '''engine'''. These are also explained at [[AiWML]], but these keys basically affect all aspects defined in this simple syntax. {{DevFeature1.13\|5}} Currently, every aspect except the attacks aspect can be defined in this way. Prior to 1.13.5, there were also a few other aspects that could not be defined in this way.

Laela: /* AI Configuration */ seems [ai] works in [modification]

2024-08-08T19:15:56Z

AI Configuration: seems [ai] works in [modification]

← Older revision		Revision as of 19:15, 8 August 2024
Line 46:		Line 46:
	* The default AI parameters in a variety of configuration files in the 'data/ai/' directory		* The default AI parameters in a variety of configuration files in the 'data/ai/' directory
	* Optional [ai] or [modify_ai] tags in era configurations		* Optional [ai] or [modify_ai] tags in era configurations
			* Optional [ai] or [modify_ai] tags in modification configurations
	* Optional [ai] or [modify_ai] tags in multiplayer faction configurations		* Optional [ai] or [modify_ai] tags in multiplayer faction configurations
	* Optional [ai] or [modify_ai] tags in scenario configurations		* Optional [ai] or [modify_ai] tags in scenario configurations

Egallager: additional "See Also"

2024-07-29T08:50:29Z

additional "See Also"

← Older revision		Revision as of 08:50, 29 July 2024
Line 415:		Line 415:
	* '''code''': If <code>name=lua</code> only. The Lua code to add to the engine. See the [[Lua_AI_Legacy_Methods_Howto#Lua_AI_Setup\|old method for setting up custom Lua CAs]] for details. It should generally <code>return ...</code> or similar - if it doesn't, other components using the Lua engine may not be able to function correctly.		* '''code''': If <code>name=lua</code> only. The Lua code to add to the engine. See the [[Lua_AI_Legacy_Methods_Howto#Lua_AI_Setup\|old method for setting up custom Lua CAs]] for details. It should generally <code>return ...</code> or similar - if it doesn't, other components using the Lua engine may not be able to function correctly.

			== See also ==
			* [[Wesnoth AI]]
			* [[AiWML]]

	~~'''See also:''' [[Wesnoth AI]]~~
	[[Category:AI]]		[[Category:AI]]

Celtic Minstrel: /* Dynamic Lua Aspects */ Clarify that this can just as well go in [facet]

2024-04-09T23:25:17Z

Dynamic Lua Aspects: Clarify that this can just as well go in [facet]

← Older revision		Revision as of 23:25, 9 April 2024
Line 399:		Line 399:
	[/aspect]		[/aspect]
	</syntaxhighlight>		</syntaxhighlight>

			It's also possible to put all of that ''in'' a [facet] tag, rather than in an [aspect] tag – this would allow the Lua aspect to take effect only at certain times of day, for example.

	== The [ai] Tag — Goals ==		== The [ai] Tag — Goals ==

Celtic Minstrel: /* The [ai] Tag — Aspects */ Wow, how long has that type been there!?

2024-04-09T23:22:50Z

The [ai] Tag — Aspects: Wow, how long has that type been there!?

← Older revision		Revision as of 23:22, 9 April 2024
Line 322:		Line 322:
	invalidate_on_gamestate_change=no		invalidate_on_gamestate_change=no
	invalidate_on_minor_gamestate_change=no		invalidate_on_minor_gamestate_change=no
	~~invalidate_on_tod_change_change~~=yes		invalidate_on_tod_change=yes
	invalidate_on_turn_start=yes		invalidate_on_turn_start=yes
	name=composite_aspect		name=composite_aspect
Line 330:		Line 330:
	invalidate_on_gamestate_change=no		invalidate_on_gamestate_change=no
	invalidate_on_minor_gamestate_change=no		invalidate_on_minor_gamestate_change=no
	~~invalidate_on_tod_change_change~~=yes		invalidate_on_tod_change=yes
	invalidate_on_turn_start=yes		invalidate_on_turn_start=yes
	name=standard_aspect		name=standard_aspect
Line 342:		Line 342:
	invalidate_on_gamestate_change=no		invalidate_on_gamestate_change=no
	invalidate_on_minor_gamestate_change=no		invalidate_on_minor_gamestate_change=no
	~~invalidate_on_tod_change_change~~=yes		invalidate_on_tod_change=yes
	invalidate_on_turn_start=yes		invalidate_on_turn_start=yes
	name=standard_aspect		name=standard_aspect
Line 394:		Line 394:
	invalidate_on_gamestate_change=no		invalidate_on_gamestate_change=no
	invalidate_on_minor_gamestate_change=no		invalidate_on_minor_gamestate_change=no
	~~invalidate_on_tod_change_change~~=yes		invalidate_on_tod_change=yes
	invalidate_on_turn_start=yes		invalidate_on_turn_start=yes
	name=lua_aspect		name=lua_aspect

Celtic Minstrel: /* The [candidate_action] Tag */ typo

2024-02-25T00:57:46Z

The [candidate_action] Tag: typo

← Older revision		Revision as of 00:57, 25 February 2024
Line 191:		Line 191:
	*'''location''': File name, including path, of the AI code for the CA.		*'''location''': File name, including path, of the AI code for the CA.
	*'''eval_parms''', '''exec_parms''': (deprecated) The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a [[LuaWML#Encoding_WML_objects_into_Lua_tables\|Lua table]], without the outer curly brackets. They are [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|passed to these functions]] as the second argument, ''cfg''.		*'''eval_parms''', '''exec_parms''': (deprecated) The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a [[LuaWML#Encoding_WML_objects_into_Lua_tables\|Lua table]], without the outer curly brackets. They are [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|passed to these functions]] as the second argument, ''cfg''.
	*'''sticky''', '''unit_x''', '''~~unit_t~~''': Specifies that this is a [[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions\|behavioral candidate action]] that is automatically removed once the unit on the given location dies.		*'''sticky''', '''unit_x''', '''unit_y''': Specifies that this is a [[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions\|behavioral candidate action]] that is automatically removed once the unit on the given location dies.
	*'''[args]''': {{DevFeature1.13\|5}} This replaces eval_parms and exec_parms, which are now deprecated and will be removed in a later version. The content of this tag is available to both the evaluation and execution function as a WML table. Details at the link above.		*'''[args]''': {{DevFeature1.13\|5}} This replaces eval_parms and exec_parms, which are now deprecated and will be removed in a later version. The content of this tag is available to both the evaluation and execution function as a WML table. Details at the link above.

Celtic Minstrel: /* The [candidate_action] Tag */ Document sticky/unit_xy

2024-02-25T00:57:27Z

The [candidate_action] Tag: Document sticky/unit_xy

← Older revision		Revision as of 00:57, 25 February 2024
Line 190:		Line 190:
	In addition, [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|Lua CAs]] also contain the following keys:		In addition, [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|Lua CAs]] also contain the following keys:
	*'''location''': File name, including path, of the AI code for the CA.		*'''location''': File name, including path, of the AI code for the CA.
	*'''eval_parms''', '''exec_parms''': The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a [[LuaWML#Encoding_WML_objects_into_Lua_tables\|Lua table]], without the outer curly brackets. They are [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|passed to these functions]] as the second argument, ''cfg''.		*'''eval_parms''', '''exec_parms''': (deprecated) The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a [[LuaWML#Encoding_WML_objects_into_Lua_tables\|Lua table]], without the outer curly brackets. They are [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|passed to these functions]] as the second argument, ''cfg''.
			*'''sticky''', '''unit_x''', '''unit_t''': Specifies that this is a [[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions\|behavioral candidate action]] that is automatically removed once the unit on the given location dies.
	*'''[args]''': {{DevFeature1.13\|5}} This replaces eval_parms and exec_parms, which are now deprecated and will be removed in a later version. The content of this tag is available to both the evaluation and execution function as a WML table. Details at the link above.		*'''[args]''': {{DevFeature1.13\|5}} This replaces eval_parms and exec_parms, which are now deprecated and will be removed in a later version. The content of this tag is available to both the evaluation and execution function as a WML table. Details at the link above.

Celtic Minstrel: /* The [ai] Tag — Top-level Elements */ Document what happens when ai_algorithm is not specified

2023-03-07T06:02:24Z

The [ai] Tag — Top-level Elements: Document what happens when ai_algorithm is not specified

← Older revision		Revision as of 06:02, 7 March 2023
Line 73:		Line 73:
	*'''time_of_day''', '''turns''', '''engine''': {{DevFeature1.13\|5}} Specifies default values for aspects given as attributes or simple tags. (Simple tags are tags that do not contain either a value= attribute or a [value] subtag, with the exception that [attacks] is never a simple tag.) This is available prior to 1.13.5, but more limited; the engine attribute is probably more limited, and there might be problems mixing this syntax with fully-specified composite aspects in the same [ai] tag. (That can easily be worked around in a side configuration by splitting the [ai] tag in two.)		*'''time_of_day''', '''turns''', '''engine''': {{DevFeature1.13\|5}} Specifies default values for aspects given as attributes or simple tags. (Simple tags are tags that do not contain either a value= attribute or a [value] subtag, with the exception that [attacks] is never a simple tag.) This is available prior to 1.13.5, but more limited; the engine attribute is probably more limited, and there might be problems mixing this syntax with fully-specified composite aspects in the same [ai] tag. (That can easily be worked around in a side configuration by splitting the [ai] tag in two.)
	*'''Other tags and attributes''': {{DevFeature1.13\|5}} Any other tag or attribute found is assumed to be a simplified aspect. More details about this syntax is given in the section on aspects later on this page. Some of this syntax is available prior to 1.13.5, but it has been generalized in 1.13.5 to automatically work for any compatible aspect. See [[AIWML]] for a list of these tags and attributes.		*'''Other tags and attributes''': {{DevFeature1.13\|5}} Any other tag or attribute found is assumed to be a simplified aspect. More details about this syntax is given in the section on aspects later on this page. Some of this syntax is available prior to 1.13.5, but it has been generalized in 1.13.5 to automatically work for any compatible aspect. See [[AIWML]] for a list of these tags and attributes.

			If no '''ai_algorithm''' is specified, normally the game will automatically load in the default AI, as if you had specified '''ai_algorithm=ai_default_rca'''. However, if there is a '''[stage]''' tag, then this behaviour is disabled and the AI will be built from a blank slate. This special behaviour only comes into play if '''ai_algorithm''' is omitted entirely.

	== The [ai] Tag — Stages ==		== The [ai] Tag — Stages ==

Celtic Minstrel: /* The [ai] Tag — Top-level Elements */ Clarify the scope of id, description, and mp_rank

2023-02-18T16:58:01Z

The [ai] Tag — Top-level Elements: Clarify the scope of id, description, and mp_rank

← Older revision		Revision as of 16:58, 18 February 2023
Line 58:		Line 58:
	AI configurations are set up and stored using the [ai] tag. It has the following top-level elements, which are described in more detail in the remaining sections of this page.		AI configurations are set up and stored using the [ai] tag. It has the following top-level elements, which are described in more detail in the remaining sections of this page.

	*'''description'''="": (translatable string) This is the text displayed in the MP setup menu when choosing an AI for a computer player.		*'''description'''="": (translatable string) This is the text displayed in the MP setup menu when choosing an AI for a computer player. It is only relevant for reusable AI configurations, for example in [[EraWML]].
	*'''id'''="": (string) The id of the [ai] config snippet. This was originally meant to make it possible to remove [ai] configurations selectively during a game. However, due to the merging process described above, this information is lost. The id is therefore meaningless in the current implementation of the AI. {{DevFeature1.13\|5}} This id can now be referenced by ''ai_algorithm'' in order to set the base AI algorithm to build on.		*'''id'''="": (string) The id of the [ai] config snippet. This was originally meant to make it possible to remove [ai] configurations selectively during a game. However, due to the merging process described above, this information is lost. The id is therefore meaningless in the current implementation of the AI. {{DevFeature1.13\|5}} This id can now be referenced by ''ai_algorithm'' in order to set the base AI algorithm to build on. It is only relevant for reusable AI configurations, for example in [[EraWML]].
	*'''ai_algorithm''': (string) This used to instruct Wesnoth to load a different AI engine instead of the composite AI. {{DevFeature1.13\|5}} It now specifies a default AI configuration to load; any AI available at the multiplayer select screen can be chosen, or AIs defined in other addons. It must reference the id attribute of another [ai] tag. It defaults to ai_default_rca; other possible values include experimental_ai and idle_ai. Specifying the ID of an AI defined in ''data/ai/ais/'' or ''/data/ai/dev/'' is roughly equivalent to macro-including that file in your side configuration just above the opening [ai] tag, except that the AI configuration will be loaded on the fly (similar to using [modify_side]switch_ai) rather than included in the preprocessed WML. Additional aspects, stages, and so on can still be added to the [ai] tag as normal.		*'''ai_algorithm''': (string) This used to instruct Wesnoth to load a different AI engine instead of the composite AI. {{DevFeature1.13\|5}} It now specifies a default AI configuration to load; any AI available at the multiplayer select screen can be chosen, or AIs defined in other addons. It must reference the id attribute of another [ai] tag. It defaults to ai_default_rca; other possible values include experimental_ai and idle_ai. Specifying the ID of an AI defined in ''data/ai/ais/'' or ''/data/ai/dev/'' is roughly equivalent to macro-including that file in your side configuration just above the opening [ai] tag, except that the AI configuration will be loaded on the fly (similar to using [modify_side]switch_ai) rather than included in the preprocessed WML. Additional aspects, stages, and so on can still be added to the [ai] tag as normal.
	*'''mp_rank''': (integer) {{DevFeature1.15\|0}} A value that determines in which order available AIs are displayed in the multiplayer selection menu. AIs are listed in ascending order of mp_rank (smallest values first). The mainline default (RCA) AI and Experimental AI have values of 1000 and 1010, respectively, meaning that custom AIs with mp_rank less than 1000 will be listed before any of the default AIs. AIs that do not contain an mp_rank line are shown at the end of the list.		*'''mp_rank''': (integer) {{DevFeature1.15\|0}} A value that determines in which order available AIs are displayed in the multiplayer selection menu. AIs are listed in ascending order of mp_rank (smallest values first). The mainline default (RCA) AI and Experimental AI have values of 1000 and 1010, respectively, meaning that custom AIs with mp_rank less than 1000 will be listed before any of the default AIs. AIs that do not contain an mp_rank line are shown at the end of the list. It is only relevant for reusable AI configurations, for example in [[EraWML]].
	*'''version'''="": (string) This key is currently still needed to distinguish whether aspects are defined using ''standard'' or ''composite'' syntax in the [ai] tag. If it is omitted, standard syntax is used. If set to '10703' or '10710', the engine uses composite syntax. However, '''we are in the process of removing this distinction'''. When that is done, both types of syntax can be used without needing the ''version'' key, even mixed together inside the same [ai] tag. We will also deprecate this key when that happens. {{DevFeature1.13\|5}} The version key is no longer recognized and will be mistaken as an attempt to set a non-existent "version" aspect. The key should not normally be required even prior to 1.13.5, however.		*'''version'''="": (string) This key is currently still needed to distinguish whether aspects are defined using ''standard'' or ''composite'' syntax in the [ai] tag. If it is omitted, standard syntax is used. If set to '10703' or '10710', the engine uses composite syntax. However, '''we are in the process of removing this distinction'''. When that is done, both types of syntax can be used without needing the ''version'' key, even mixed together inside the same [ai] tag. We will also deprecate this key when that happens. {{DevFeature1.13\|5}} The version key is no longer recognized and will be mistaken as an attempt to set a non-existent "version" aspect. The key should not normally be required even prior to 1.13.5, however.
	*'''[stage]''': Configuration of the stage(s) used in the AI. Several [stage] tags can be used, even several stages of the same type. They are executed in the order in which they are put into the [ai] tag.		*'''[stage]''': Configuration of the stage(s) used in the AI. Several [stage] tags can be used, even several stages of the same type. They are executed in the order in which they are put into the [ai] tag.

← Older revision		Revision as of 00:57, 25 February 2024
Line 190:		Line 190:
	In addition, [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|Lua CAs]] also contain the following keys:		In addition, [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|Lua CAs]] also contain the following keys:
	*'''location''': File name, including path, of the AI code for the CA.		*'''location''': File name, including path, of the AI code for the CA.
	*'''eval_parms''', '''exec_parms''': The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a [[LuaWML#Encoding_WML_objects_into_Lua_tables\|Lua table]], without the outer curly brackets. They are [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|passed to these functions]] as the second argument, ''cfg''.		*'''eval_parms''', '''exec_parms''': (deprecated) The parameters to be passed to the evaluation and execution functions of the AI. These need to be in form of a [[LuaWML#Encoding_WML_objects_into_Lua_tables\|Lua table]], without the outer curly brackets. They are [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|passed to these functions]] as the second argument, ''cfg''.
			*'''sticky''', '''unit_x''', '''unit_t''': Specifies that this is a [[Lua_AI_Legacy_Methods_Howto#Behavior_.28Sticky.29_Candidate_Actions\|behavioral candidate action]] that is automatically removed once the unit on the given location dies.
	*'''[args]''': {{DevFeature1.13\|5}} This replaces eval_parms and exec_parms, which are now deprecated and will be removed in a later version. The content of this tag is available to both the evaluation and execution function as a WML table. Details at the link above.		*'''[args]''': {{DevFeature1.13\|5}} This replaces eval_parms and exec_parms, which are now deprecated and will be removed in a later version. The content of this tag is available to both the evaluation and execution function as a WML table. Details at the link above.