Creating Custom AIs - Revision history

Mattsc: /* Starting from Version 1.13.5 */ fix argument order for Lua CAs

2020-07-15T19:39:58Z

Starting from Version 1.13.5: fix argument order for Lua CAs

← Older revision		Revision as of 19:39, 15 July 2020
Line 103:		Line 103:
	*'''filter_own''': {{DevFeature1.15\|3}} The content of the <code>[candidate action][filter_own]</code> tag as described [[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag\|here]].		*'''filter_own''': {{DevFeature1.15\|3}} The content of the <code>[candidate action][filter_own]</code> tag as described [[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag\|here]].

	If the functions are defined using '''colon notation''' as in the above example, then the ''self'' parameter is implicitly defined and the arguments must be in order <code>(ai, ~~cfg~~, filter_own)</code> in the function calls. If you prefer to explicitly define it, use '''a dot instead of a colon''' when defining the function, in which case the arguments must be passed as <code>(self, ai, ~~cfg~~, filter_own)</code>. As always in Lua, you can omit any of the arguments if the function does not need to access the respective information.		If the functions are defined using '''colon notation''' as in the above example, then the ''self'' parameter is implicitly defined and the arguments must be in order <code>(cfg, data, filter_own)</code> in the function calls. If you prefer to explicitly define it, use '''a dot instead of a colon''' when defining the function, in which case the arguments must be passed as <code>(self, cfg, data, filter_own)</code>. As always in Lua, you can omit any of the arguments if the function does not need to access the respective information.

	Notice that the ''ai'' table is no longer included among the arguments passed to the table. This is because it's now available as a "scoped global variable" anywhere in AI code, so there is no need to pass it around.		Notice that the ''ai'' table is no longer included among the arguments passed to the table. This is because it's now available as a "scoped global variable" anywhere in AI code, so there is no need to pass it around.

Mattsc: /* Adding the main_loop Stage from Scratch */ add comment about new CAs added to default AI

2019-12-11T21:29:11Z

Adding the main_loop Stage from Scratch: add comment about new CAs added to default AI

← Older revision		Revision as of 21:29, 11 December 2019
Line 238:		Line 238:
	=== Adding the ''main_loop'' Stage from Scratch ===		=== Adding the ''main_loop'' Stage from Scratch ===

	Sometimes it might be useful or convenient to add the entire ''main_loop'' stage from scratch, rather than adding or deleting individual candidate actions. If that is desired, the syntax for the example of the default AI plus Guardian Bob from above looks ~~like this~~		Sometimes it might be useful or convenient to add the entire ''main_loop'' stage from scratch, rather than adding or deleting individual candidate actions. If that is desired, the syntax for the example of the default AI plus Guardian Bob from above looks as shown below.

			{{DevFeature1.15\|3}} The example below is from a previous Wesnoth version. New candidate actions have since been added to the default AI. The latest up-to-date version can always be found 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

	<syntaxhighlight lang='wml'>		<syntaxhighlight lang='wml'>
	[ai]		[ai]

Mattsc: /* Starting from Version 1.13.5 */ add filter_own and clean up description

2019-11-22T17:28:43Z

Starting from Version 1.13.5: add filter_own and clean up description

← Older revision		Revision as of 17:28, 22 November 2019
Line 101:		Line 101:
	*'''cfg''': The contents of the [args] subtag; parameters specific to this candidate action. With this, you can use the same code with different parameters to produce two different candidate actions.		*'''cfg''': The contents of the [args] subtag; parameters specific to this candidate action. With this, you can use the same code with different parameters to produce two different candidate actions.
	*'''data''': The persistent variable ''data''. This is the same as ''self.data'' in the old system. If an [engine] tag was explicitly defined for the Lua engine, this is initially equal to the value of the [data] subtag. However, unlike the other two parameters, this value is mutable.		*'''data''': The persistent variable ''data''. This is the same as ''self.data'' in the old system. If an [engine] tag was explicitly defined for the Lua engine, this is initially equal to the value of the [data] subtag. However, unlike the other two parameters, this value is mutable.
			*'''filter_own''': {{DevFeature1.15\|3}} The content of the <code>[candidate action][filter_own]</code> tag as described [[Wesnoth_AI_Framework#The_.5Bcandidate_action.5D_Tag\|here]].

	If the functions are defined using colon notation as in the above example, then the ''self'' parameter is implicitly defined and must ~~not~~ be ~~included~~. (If you prefer to explicitly define it, use a dot instead of a colon when defining the function~~.) Beyond that~~, ~~these~~ arguments must ~~always appear in the order listed - that is~~, ~~the ''~~cfg~~'' argument is always the first argument (or second if defined with dot notation) and the ''data'' argument, if used~~, ~~is always the second argument (or third if defined with dot notation~~). As always in Lua, you can omit the ~~''data'' argument~~ if the function does not need to access the ~~persistent data~~.		If the functions are defined using '''colon notation''' as in the above example, then the ''self'' parameter is implicitly defined and the arguments must be in order <code>(ai, cfg, filter_own)</code> in the function calls. If you prefer to explicitly define it, use '''a dot instead of a colon''' when defining the function, in which case the arguments must be passed as <code>(self, ai, cfg, filter_own)</code>. As always in Lua, you can omit any of the arguments if the function does not need to access the respective information.

	Notice that the ''ai'' table is no longer included among the arguments passed to the table. This is because it's now available as a "scoped global variable" anywhere in AI code, so there is no need to pass it around.		Notice that the ''ai'' table is no longer included among the arguments passed to the table. This is because it's now available as a "scoped global variable" anywhere in AI code, so there is no need to pass it around.

Mattsc: /* Creating Custom Candidate Actions */ Use subsections for different Wesnoth versions

2019-11-22T17:17:18Z

Creating Custom Candidate Actions: Use subsections for different Wesnoth versions

← Older revision		Revision as of 17:17, 22 November 2019
Line 87:		Line 87:
	The first 12 lines are not directly relevant to setting up the AI, they simply define some utility functions. The first important line is L.13 in combination with lines 15, 28 and 47. A Lua candidate action needs to return a table with an evaluation and an execution function. The mentioned lines set up that table and the two functions. Its name is chosen to be ''ca_return_guardian'', but that is really irrelevant as it is a variable local to the file.		The first 12 lines are not directly relevant to setting up the AI, they simply define some utility functions. The first important line is L.13 in combination with lines 15, 28 and 47. A Lua candidate action needs to return a table with an evaluation and an execution function. The mentioned lines set up that table and the two functions. Its name is chosen to be ''ca_return_guardian'', but that is really irrelevant as it is a variable local to the file.

	The execution and evaluation function can have ~~up to three~~ arguments:		The execution and evaluation function can have several arguments. The available arguments and the order in which they appear '''depend on the Wesnoth version and usage'''.

			====Before Version 1.13.5====
	*'''ai''': The [[LuaAI#Lua_AI_Functions\|Lua AI function table]]. The execution function always needs this argument to be passed, the evaluation function only in some situations. See below for details.		*'''ai''': The [[LuaAI#Lua_AI_Functions\|Lua AI function table]]. The execution function always needs this argument to be passed, the evaluation function only in some situations. See below for details.
	*'''cfg''': A comma-separated list of configuration parameters, which are passed from the [candidate_action] tag using the ''eval_parms'' and ''exec_parms'' keys. These need to be in [[LuaWML\|Lua table format]], but without the outer curly brackets <code>{ }</code>. See below for examples.		*'''cfg''': A comma-separated list of configuration parameters, which are passed from the [candidate_action] tag using the ''eval_parms'' and ''exec_parms'' keys. These need to be in [[LuaWML\|Lua table format]], but without the outer curly brackets <code>{ }</code>. See below for examples.
Line 94:		Line 96:
	These arguments <u>must</u> appear in order <code>(ai, cfg, self)</code> in the function calls, but as always in Lua, trailing unused arguments can be omitted.		These arguments <u>must</u> appear in order <code>(ai, cfg, self)</code> in the function calls, but as always in Lua, trailing unused arguments can be omitted.

	~~{{DevFeature1~~.13\|5}} The arguments passed to the functions are different for candidate actions using the recommended [args] subtag rather than eval_parms and exec_parms (these are explained in more detail below). The new arguments are as follows:		====Starting from Version 1.13.5====
			The arguments passed to the functions are different for candidate actions using the recommended [args] subtag rather than eval_parms and exec_parms (these are explained in more detail below). The new arguments are as follows:
	*'''self''': The engine data. By default, this replicates the ''self'' parameter from the old system for compatibility, meaning that ''self.data'' is the same as ''data''. If an [engine] tag was explicitly defined for Lua, however, this parameter is the value that the engine's code returned, which could be pretty much anything.		*'''self''': The engine data. By default, this replicates the ''self'' parameter from the old system for compatibility, meaning that ''self.data'' is the same as ''data''. If an [engine] tag was explicitly defined for Lua, however, this parameter is the value that the engine's code returned, which could be pretty much anything.
	*'''cfg''': The contents of the [args] subtag; parameters specific to this candidate action. With this, you can use the same code with different parameters to produce two different candidate actions.		*'''cfg''': The contents of the [args] subtag; parameters specific to this candidate action. With this, you can use the same code with different parameters to produce two different candidate actions.

Mattsc: /* Adding the main_loop Stage from Scratch */ added high_xp_attack CA

2016-09-04T14:42:07Z

Adding the main_loop Stage from Scratch: added high_xp_attack CA

← Older revision		Revision as of 14:42, 4 September 2016
Line 246:		Line 246:
	{AI_CA_MOVE_LEADER_TO_GOALS}		{AI_CA_MOVE_LEADER_TO_GOALS}
	{AI_CA_MOVE_LEADER_TO_KEEP}		{AI_CA_MOVE_LEADER_TO_KEEP}
			{AI_CA_HIGH_XP_ATTACK} # Wesnoth 1.13.6 and later only
	{AI_CA_COMBAT}		{AI_CA_COMBAT}
	{AI_CA_HEALING}		{AI_CA_HEALING}

Celtic Minstrel: /* Custom AIs in Eras and Modifications */ Update for new feature note

2016-07-15T18:05:58Z

Custom AIs in Eras and Modifications: Update for new feature note

← Older revision		Revision as of 18:05, 15 July 2016
Line 197:		Line 197:
	* The MODIFY_AI_ADD_CANDIDATE_ACTION macro needs to be placed inside [era][ai] or [modification][ai] instead of in [side][ai].		* The MODIFY_AI_ADD_CANDIDATE_ACTION macro needs to be placed inside [era][ai] or [modification][ai] instead of in [side][ai].
	* The '''description''' attribute needs to be set inside the [ai] tag. This is the text which will show up in the computer player selection menu during the MP game setup.		* The '''description''' attribute needs to be set inside the [ai] tag. This is the text which will show up in the computer player selection menu during the MP game setup.
			* {{DevFeature1.13\|5}} Scenarios wishing to use such AIs may reference them using the '''ai_algorithm''' key in [side][ai], and modify them further with additional AI component tags such as aspect values.

	As an example, the following code adds the CA described above to a modification.		As an example, the following code adds the CA described above to a modification.

Celtic Minstrel: /* Including Custom Candidate Actions in Scenarios */ Update for new syntax

2016-07-15T17:56:34Z

Including Custom Candidate Actions in Scenarios: Update for new syntax

← Older revision		Revision as of 17:56, 15 July 2016
Line 147:		Line 147:
	max_score=100010		max_score=100010
	location="~add-ons/my_addon/lua/return_guardian.lua"		location="~add-ons/my_addon/lua/return_guardian.lua"
	eval_parms="id = 'Bob', return_x = 10, return_y = 15"		[args]
	exec_parms="id = 'Bob', return_x = 10, return_y = 15"		id=Bob
			return_x=10
			return_y=15
			[/args]
			# In the older syntax, the above would have looked like this:
			# eval_parms="id = 'Bob', return_x = 10, return_y = 15"
			# exec_parms="id = 'Bob', return_x = 10, return_y = 15"
	[/candidate_action]		[/candidate_action]
	)}		)}
Line 162:		Line 168:
	*'''eval_parms''', '''exec_parms''': (string) The parameters to be passed to the evaluation and execution functions of the AI. These need to be strings in form of a Lua table, without the outer curly brackets. They are passed to the functions as the second argument, called ''cfg'' in the example above.		*'''eval_parms''', '''exec_parms''': (string) The parameters to be passed to the evaluation and execution functions of the AI. These need to be strings in form of a Lua table, without the outer curly brackets. They are passed to the functions as the second argument, called ''cfg'' in the example above.
	** The strings do not necessarily need to be in [[LuaWML#Encoding_WML_objects_into_Lua_tables\|WML object Lua table]] format. However, this is, of course, necessary if they are to be used in functions that require that format, as in the ''filter'' example shown below.		** The strings do not necessarily need to be in [[LuaWML#Encoding_WML_objects_into_Lua_tables\|WML object Lua table]] format. However, this is, of course, necessary if they are to be used in functions that require that format, as in the ''filter'' example shown below.
	** ~~Note: In~~ the next development cycle, ~~these string parameters may~~ be ~~replaced by WML tags~~.		** {{DevFeature1.13\|5}} These string parameters are now replaced by the [args] WML tag. For the time being, the string parameters will continue to work, but they will be removed entirely in the next development cycle.
			*'''[args]''': {{DevFeature1.13\|5}} WML data to be passed to both the evaluation and execution functions. A copy of the data is passed, so even if the functions modify it, it will always be the same on the next call. This replaces eval_parms and exec_parms.

	The example above requires		The example above requires

Celtic Minstrel: /* Creating Custom Candidate Actions */ Update for new argument list

2016-07-15T17:48:35Z

Creating Custom Candidate Actions: Update for new argument list

← Older revision		Revision as of 17:48, 15 July 2016
Line 93:		Line 93:

	These arguments <u>must</u> appear in order <code>(ai, cfg, self)</code> in the function calls, but as always in Lua, trailing unused arguments can be omitted.		These arguments <u>must</u> appear in order <code>(ai, cfg, self)</code> in the function calls, but as always in Lua, trailing unused arguments can be omitted.

			{{DevFeature1.13\|5}} The arguments passed to the functions are different for candidate actions using the recommended [args] subtag rather than eval_parms and exec_parms (these are explained in more detail below). The new arguments are as follows:
			*'''self''': The engine data. By default, this replicates the ''self'' parameter from the old system for compatibility, meaning that ''self.data'' is the same as ''data''. If an [engine] tag was explicitly defined for Lua, however, this parameter is the value that the engine's code returned, which could be pretty much anything.
			*'''cfg''': The contents of the [args] subtag; parameters specific to this candidate action. With this, you can use the same code with different parameters to produce two different candidate actions.
			*'''data''': The persistent variable ''data''. This is the same as ''self.data'' in the old system. If an [engine] tag was explicitly defined for the Lua engine, this is initially equal to the value of the [data] subtag. However, unlike the other two parameters, this value is mutable.

			If the functions are defined using colon notation as in the above example, then the ''self'' parameter is implicitly defined and must not be included. (If you prefer to explicitly define it, use a dot instead of a colon when defining the function.) Beyond that, these arguments must always appear in the order listed - that is, the ''cfg'' argument is always the first argument (or second if defined with dot notation) and the ''data'' argument, if used, is always the second argument (or third if defined with dot notation). As always in Lua, you can omit the ''data'' argument if the function does not need to access the persistent data.

			Notice that the ''ai'' table is no longer included among the arguments passed to the table. This is because it's now available as a "scoped global variable" anywhere in AI code, so there is no need to pass it around.

	====Evaluation Function====		====Evaluation Function====

Celtic Minstrel: Syntax highlighting for most of the code samples

2016-03-13T03:24:06Z

Syntax highlighting for most of the code samples

Show changes

Mattsc: /* On the Fly Candidate Action Testing */ add this section

2016-03-01T15:31:33Z

On the Fly Candidate Action Testing: add this section

@@ Line 283: / Line 283: @@
 == On the Fly Candidate Action Testing ==
-One of the advantages of using Lua for custom AIs is that there is no need for restarting Wesnoth after the code is changed.  In fact, it is even possible to set things up so that no reload is required.  You can simply change the code and click on a context menu option (or even just use a keyboard shortcut) to test the new version of the candidate action's evaluation and/or execution function.  This section describes how to set up this testing mechanism using the example of the Guardian Bob AI described above.
+One of the advantages of using Lua for custom AIs is that there is no need for restarting Wesnoth after the code is changed for the changes to take effect.  In fact, it is even possible to set things up so that not even a reload is required.  You can simply change the code and click on a context menu option (or even just use a keyboard shortcut) to test the new version of the candidate action's evaluation and/or execution function.  This section describes how to set up such a testing mechanism using the example of the Guardian Bob AI described above.
-[ to be written ]
+The context menu option, along with hotkey 'x', is set up by adding the following code to the WML of whatever scenario you want to test this in.
 == Legacy Methods for Creating Custom AIs ==