LuaAI - Revision history

Celtic Minstrel: /* The advancements Aspect */ Fix reference to deprecated API

2024-04-09T23:27:36Z

‎The advancements Aspect: Fix reference to deprecated API

Celtic Minstrel: /* Dynamic Lua Aspects */ typo

2024-04-09T23:26:07Z

‎Dynamic Lua Aspects: typo

Celtic Minstrel: /* Lua Goals and Targets */ Terminology

2022-11-16T04:35:41Z

‎Lua Goals and Targets: Terminology

Celtic Minstrel: /* Lua Goals and Targets */ An explanation of each type of target

2022-11-16T04:35:04Z

‎Lua Goals and Targets: An explanation of each type of target

Celtic Minstrel: /* Lua Goals and Targets */ Use string types in the example

2022-11-11T03:38:19Z

‎Lua Goals and Targets: Use string types in the example

Celtic Minstrel: /* ai Table Functions for Executing AI Moves */ Remove check_synced_command too

2021-07-04T23:58:11Z

‎ai Table Functions for Executing AI Moves: Remove check_synced_command too

Celtic Minstrel: /* Lua AI Functions */ Remove synced_command since that doesn't even exist in 1.14

2021-07-04T23:57:38Z

‎Lua AI Functions: Remove synced_command since that doesn't even exist in 1.14

Celtic Minstrel: /* Lua AI Functions */ Add the moving notebox

2021-06-30T18:28:48Z

‎Lua AI Functions: Add the moving notebox

Holius: fix errors (title levels)

2017-11-30T14:59:46Z

fix errors (title levels)

Celtic Minstrel: /* Retrieving Aspect Values */ Note the deprecation of the old functions

2016-11-05T23:02:14Z

‎Retrieving Aspect Values: Note the deprecation of the old functions

@@ Line 159: / Line 159: @@
 ==== The ''advancements'' Aspect ====
-A slightly more elaborate example, using the ''advancements'' aspect, is given below.  This aspect is different from others in that it can be used with a function ''advance(x, y)'', where ''(x, y)'' is the current location of the unit about to advance. You can then use ''wesnoth.get_unit(x, y)'' to retrieve the unit object itself.  For example, the following code advances the unit with id 'Bob' to a swordsman (assuming here that this unit is a spearman), while all other spearmen are advanced to javelineers.
+A slightly more elaborate example, using the ''advancements'' aspect, is given below.  This aspect is different from others in that it can be used with a function ''advance(x, y)'', where ''(x, y)'' is the current location of the unit about to advance. You can then use ''wesnoth.units.get(x, y)'' to retrieve the unit object itself.  For example, the following code advances the unit with id 'Bob' to a swordsman (assuming here that this unit is a spearman), while all other spearmen are advanced to javelineers.
 <syntaxhighlight lang='wml'>
 [ai]
@@ Line 168: / Line 168: @@
          code=<<
              function advance(x, y)
-                 local unit = wesnoth.get_unit(x, y)
+                 local unit = wesnoth.units.get(x, y)
                  if (unit.id == 'Bob') then
                      return 'Swordsman'

@@ Line 133: / Line 133: @@
 It is possible to define aspects using Lua.  These can be either static or dynamic, that is, their value can change depending on the game state. We demonstrate this here with a few examples.
-First, as simple example of defining the ''aggression'' aspect statically in Lua:
+First, a simple example of defining the ''aggression'' aspect statically in Lua:
 <syntaxhighlight lang='wml'>
 [aspect]

@@ Line 213: / Line 213: @@
 ** '''village''': A village, or something equivalent to a village. By default, all enemy or unowned villages are considered to be village targets. There is usually no reason to add additional ones. Scout units are more likely than other units to approach village targets.
 ** '''leader''': An enemy leader.
-** '''explicit''': Usually a unit of particular importance (for example, a hero), or an important location. The '''[goal]''' tag with the ''target'' or ''target_location'' type creates an '''explicit''' goal.
+** '''explicit''': Usually a unit of particular importance (for example, a hero), or an important location. The '''[goal]''' tag with the ''target'' or ''target_location'' type creates an '''explicit''' target.
-** '''threat''': A location that needs to be defended. The '''[goal]''' tag with the ''protect'' or ''protect_location'' type creates a '''threat''' goal.
+** '''threat''': A location that needs to be defended. The '''[goal]''' tag with the ''protect'' or ''protect_location'' type creates a '''threat''' target.
 ** '''battle aid''': An ally in need of reinforcement.
 ** '''mass''': An enemy that is considered to be a particularly high threat.

@@ Line 210: / Line 210: @@
 * '''value''': The value of the target, equivalent to that defined for WML goals
 * '''loc''': A table with attributes ''x'' and ''y'' defining the target's location.  This is one of the disadvantages with respect to the WML syntax.  Each goal needs to be defined individually by its coordinates.  The use of SUFs and SLFs is not possible.
-* '''type''': A number defining the type of the target.  File [https://github.com/wesnoth/wesnoth/blob/master/src/ai/default/contexts.hpp src/ai/default/contexts.hpp] defines the available types as
+* '''type''': A string defining the type of the target. The default move-to-target candidate action does not take the type of the target into account for the most part, with the exception of village targets, but a custom movement candidate action could favour some types over others. The possible types are:
-<syntaxhighlight lang='cpp'>
+** '''village''': A village, or something equivalent to a village. By default, all enemy or unowned villages are considered to be village targets. There is usually no reason to add additional ones. Scout units are more likely than other units to approach village targets.
-enum TYPE { VILLAGE, LEADER, EXPLICIT, THREAT, BATTLE_AID, MASS, SUPPORT };
+** '''leader''': An enemy leader.
-</syntaxhighlight>
+** '''explicit''': Usually a unit of particular importance (for example, a hero), or an important location. The '''[goal]''' tag with the ''target'' or ''target_location'' type creates an '''explicit''' goal.
-User-defined targets should usually be given <code>type = 'explicit'</code> for ''target'' and ''target_location'' type targets, and <code>type = 'threat'</code> for ''protect_*'' type targets.
+** '''threat''': A location that needs to be defended. The '''[goal]''' tag with the ''protect'' or ''protect_location'' type creates a '''threat''' goal.
-{{DevFeature1.13|5}} Target types can now be specified as strings instead of integers. The possible values are <syntaxhighlight lang='lua' inline>'village', 'leader', 'explicit', 'threat', 'battle aid', 'mass', 'support'</syntaxhighlight>. (Integer types still work, for now.)
+** '''battle aid''': An ally in need of reinforcement.
 '''Notes:'''

@@ Line 200: / Line 200: @@
          local turn = wesnoth.current.turn
          local targets = {}
-         targets[1] = { value = 2, type = 2, loc = { x = 5, y = 6 } }
+         targets[1] = { value = 2, type = 'explicit', loc = { x = 5, y = 6 } }
-         targets[2] = { value = turn * 2 , type = 2, loc = { x = 4, y = 9 } }
+         targets[2] = { value = turn * 2 , type = 'explicit', loc = { x = 4, y = 9 } }
          return targets
      >>
@@ Line 214: / Line 214: @@
 enum TYPE { VILLAGE, LEADER, EXPLICIT, THREAT, BATTLE_AID, MASS, SUPPORT };
 </syntaxhighlight>
-User-defined targets should usually be given <code>type = 2</code> for ''target'' and ''target_location'' type targets, and <code>type = 3</code> for ''protect_*'' type targets.  This corresponds to ''EXPLICIT'' and ''THREAT'' targets (the third and fourth in the enum list, with counting starting at 0).
+User-defined targets should usually be given <code>type = 'explicit'</code> for ''target'' and ''target_location'' type targets, and <code>type = 'threat'</code> for ''protect_*'' type targets.
 {{DevFeature1.13|5}} Target types can now be specified as strings instead of integers. The possible values are <syntaxhighlight lang='lua' inline>'village', 'leader', 'explicit', 'threat', 'battle aid', 'mass', 'support'</syntaxhighlight>. (Integer types still work, for now.)

@@ Line 101: / Line 101: @@
 * '''ai.check_recruit()
 * '''ai.check_stopunit()
 These check functions take the same arguments as the respective AI action functions.  They return a Lua table which looks something like the following for a successful check

@@ Line 92: / Line 92: @@
 * '''ai.stopunit_moves(''unit'')''': Remove remaining movement points from ''unit''.  This is equivalent to setting <code>moves=0</code>.
 * '''ai.stopunit_all(''unit'')''': Remove both remaining attacks and remaining movement points from ''unit''.
 {{DevFeature1.13|5}} The above functions change the gamestate and thus are not always available. To be more specific, they are only available if '''ai.read_only''' is false. If it is true, the functions do not exist. This is the case everywhere except stage and candidate evaluation functions.

← Older revision		Revision as of 18:28, 30 June 2021
Line 2:		Line 2:

	== Lua AI Functions ==		== Lua AI Functions ==
		+
		+	{{LuaMove}}

	The code of [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|custom Lua candidate actions]] (CAs) has access to the ''ai'' table. This is a Lua table containing functions for getting information about the game state and for executing AI moves. Together with the other [[LuaWML\|Wesnoth Lua functions]] they can be used in the CA [[Creating_Custom_AIs#Evaluation_Function\|evaluation]] and [[Creating_Custom_AIs#Execution_Function\|execution]] functions to code the desired AI behavior.		The code of [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions\|custom Lua candidate actions]] (CAs) has access to the ''ai'' table. This is a Lua table containing functions for getting information about the game state and for executing AI moves. Together with the other [[LuaWML\|Wesnoth Lua functions]] they can be used in the CA [[Creating_Custom_AIs#Evaluation_Function\|evaluation]] and [[Creating_Custom_AIs#Execution_Function\|execution]] functions to code the desired AI behavior.

@@ Line 1: / Line 1: @@
 Wesnoth provides the functionality to both access and define all types of [[Wesnoth_AI_Framework#Types_of_AI_Components|AI components]] using [[LuaWML|Lua]].  Instructions for using these components to customize the default AI and to create custom AIs are explained on other pages.  See [[Wesnoth AI]] for a summary of the available documentation.  This page is a reference guide to the Lua AI functions, variables and component syntax.
-= Lua AI Functions =
+== Lua AI Functions ==
 The code of [[Creating_Custom_AIs#Creating_Custom_Candidate_Actions|custom Lua candidate actions]] (CAs) has access to the ''ai'' table.  This is a Lua table containing functions for getting information about the game state and for executing AI moves.  Together with the other [[LuaWML|Wesnoth Lua functions]] they can be used in the CA [[Creating_Custom_AIs#Evaluation_Function|evaluation]] and [[Creating_Custom_AIs#Execution_Function|execution]] functions to code the desired AI behavior.
-== ''ai'' Table Functions Returning Game State Information ==
+=== ''ai'' Table Functions Returning Game State Information ===
 The ''ai'' table contains a large number of functions returning game state information.  Some of those are simple scalar values which are self-explanatory, while others can be tables with many elements and complex structure.  We will not show the structure of all these tables here.  If you need to know the exact structure of such a table, use the method described below for [[#Debug_access_to_the_AI_tree|accessing the AI tree]].
-=== Retrieving Aspect Values ===
+==== Retrieving Aspect Values ====
 The contents of many of the [[AiWML#List_of_AI_Aspects|AI aspects]] can be read using ''ai'' table commands of the form
@@ Line 47: / Line 47: @@
 These functions are now deprecated. The new standard way of accessing aspect values is through the <code>ai.aspects</code> table, for example <code>ai.aspects.aggression</code>. All aspects can be accessed this way, including some that don't have function forms, such as the advancements aspect. {{DevFeature1.13|6}} The corresponding get_aspect_name functions are now deprecated, with the exception of <code>ai.get_attacks()</code> which returns an analysis of all possible attacks; this differs from <code>ai.aspects.attacks</code> which only returns the allowed units for use in attacks (in "own" and "enemy" subtables).
-=== Functions Returning Other Game State Information ===
+==== Functions Returning Other Game State Information ====
 * '''ai.get_targets()''': Get the AI targets.  See [[#Lua_Goals_and_Targets|below]] for details.
@@ Line 78: / Line 78: @@
 </syntaxhighlight>
-== ''ai'' Table Functions for Executing AI Moves ==
+=== ''ai'' Table Functions for Executing AI Moves ===
 For all functions below, units (''unit'', ''attacker'', ''defender'') can be passed either as a unit object in a single variable, or as two parameters specifying the unit's ''x'' and ''y'' coordinates.  For functions taking more than one unit as arguments, it can also be a mix of the two.
@@ Line 121: / Line 121: @@
 * The move execution functions return the same table, with the only difference being that ''gamestate_changed'' is 'true' in case the execution resulted in a change of the game state (even if the move was only partially successful).
-= Lua AI Variables — Persistence =
+== Lua AI Variables — Persistence ==
 When [[Creating Custom AIs]] in Lua, it is sometimes necessary to transfer information between the evaluation and execution functions of the same candidate action (CA) or between CAs.  It might also be necessary to have this information persist from turn to turn and across save/load cycles.  This could, in principle, be done using WML variables, but depending on the type and amount of information, that could be awkward and/or inconvenient to do in practice.
@@ Line 129: / Line 129: @@
 When saving a game, the save routine finds this field, converts it to a config and stores its content in readable format in the save file.  When the scenario gets loaded back, the engine code injects the data back into the AI context.  Note that, in order for this to work, all content of ''data'' needs to be in [[LuaWML#Encoding_WML_objects_into_Lua_tables|WML table format]].  Other format content can also be used during an AI turn, for example to pass it between the evaluation and execution functions of the same CA, but it is lost when saving the game.
-= Dynamic Lua Aspects =
+== Dynamic Lua Aspects ==
 It is possible to define aspects using Lua.  These can be either static or dynamic, that is, their value can change depending on the game state. We demonstrate this here with a few examples.
@@ Line 188: / Line 188: @@
 The attacks aspect may also be defined using the Lua engine; this is a little more complicated than most aspects, though. The aspect must return a table containing two keys, '''own''' and '''enemy'''. The value of each of these keys can be either a table defining a valid WML unit filter or a function which, when called with a unit proxy as its argument, returns true if the unit may be attacked and false otherwise.
-= Lua Goals and Targets =
+== Lua Goals and Targets ==
 It is also possible to define AI [[RCA_AI#Use_of_Goals_and_Targets_in_the_RCA_AI|goals and targets]] in Lua.  This is, however, somewhat inconvenient and we generally recommend using the [[AiWML#The_.5Bgoal.5D_Tag|[goal] tag]] with WML [[StandardUnitFilter|Standard Unit Filter]]s (SUFs) or [[StandardLocationFilter|Standard Location Filter]]s (SLFs) instead.  That is much more versatile and it makes no difference to the AI behavior whether the goals are defined using WML or Lua.
@@ Line 225: / Line 225: @@
 * {{DevFeature1.13|5}} A Lua goal may also include an [args] subtag, which is passed to the goal evaluation function in the same way as for candidate actions.
-= Lua Candidate Actions =
+== Lua Candidate Actions ==
 Lua candidate actions are the recommended method for creating custom AIs.  They are described on a [[Creating_Custom_AIs#Setting_Up_a_Custom_AI|separate page]].
-= Lua AI — Legacy Methods =
+== Lua AI — Legacy Methods ==
 The recommended method of using custom Lua AI functionality is described at [[Creating Custom AIs]].  A variety of alternative older methods also still exist.  There should be few, if any, situations in which using these methods is advantageous, but for completeness they are described on a [[Lua_AI_Legacy_Methods_Howto|separate page]].
@@ Line 241: / Line 241: @@
 * '''Behavior (sticky) candidate actions''': These are Lua CAs which attach directly to specific units.  They could, in principle, still be useful.  However, using the new syntax for Lua CAs with a condition to filter for specific units is usually done just as easily.  Several of the [[Micro AIs]] demonstrate how to do so.
-= Debug access to the AI tree =
+== Debug access to the AI tree ==
 It is now possible to access candidate actions (and some other AI components)  and have them updated automatically without requiring reloading. Only external candidate actions work in this way though. Candidate actions defined in the engine inside the config file of the scenario will not be updated if their code is directly in the [engine] tag, and they will only be updated on reloading if they are set up by including a file.