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

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

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

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

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

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

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

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

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 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]].
-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.

@@ Line 238: / Line 238: @@
 === 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.
 <syntaxhighlight lang='wml'>
 [ai]

@@ 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.
 *'''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.
+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.

@@ 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 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'''.
 *'''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.
@@ 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.
-{{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====
 *'''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.

@@ Line 246: / Line 246: @@
          {AI_CA_MOVE_LEADER_TO_GOALS}
          {AI_CA_MOVE_LEADER_TO_KEEP}
          {AI_CA_COMBAT}
          {AI_CA_HEALING}

@@ 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 '''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.
 As an example, the following code adds the CA described above to a modification.

@@ Line 147: / Line 147: @@
              max_score=100010
              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
          [/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.
 ** 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.
 The example above requires

← 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====

@@ 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 ==