LuaAPI/ai - Revision history

Celtic Minstrel: /* Move Maps */ Give a bit more explanation as to the format of the returned move maps.

2024-02-11T00:39:00Z

‎Move Maps: Give a bit more explanation as to the format of the returned move maps.

Celtic Minstrel: Add to AI category

2022-11-11T03:40:44Z

Add to AI category

Mattsc: /* ai.aspects */ add allow_ally_villages

2022-06-23T11:28:01Z

‎ai.aspects: add allow_ally_villages

Celtic Minstrel: /* AI Actions */ Add missing optional argument annotations

2022-06-23T04:40:47Z

‎AI Actions: Add missing optional argument annotations

Celtic Minstrel: Fix updated examples

2022-06-23T04:37:43Z

Fix updated examples

Celtic Minstrel: /* Move Maps */ Updated example

2022-06-23T04:37:07Z

‎Move Maps: Updated example

Celtic Minstrel: /* ai.aspects */ Updated example

2022-06-23T04:33:00Z

‎ai.aspects: Updated example

Celtic Minstrel: Those dev-tags should probably be 1.17 since they're describing a change that's only in master

2021-07-10T15:18:20Z

Those dev-tags should probably be 1.17 since they're describing a change that's only in master

Celtic Minstrel: Add dedicated headers for the first two entries; it looks a bit weird without them

2021-07-10T15:13:24Z

Add dedicated headers for the first two entries; it looks a bit weird without them

Mattsc: Various minor changes

2021-07-10T14:52:21Z

Various minor changes

@@ Line 119: / Line 119: @@
 * {{LuaGameOnly}} '''ai.get_enemy_src_dst'''() &rarr; ''move map''
-These functions return move maps – tables that relate the current positions of units with the hexes they can move to. A move map is a [[LuaAPI/location_set|location set]], similar to the advancements map, which can be converted to a standard location set with the following code:
+These functions return move maps – tables that relate the current positions of units with the hexes they can move to. A move map is a [[LuaAPI/location_set|location set]], similar to the advancements map. For the '''dst_src''' versions, the keys are empty hexes and the values are lists of locations containing units that can move there. For the '''src_dst''' versions, the keys are occupied hexes and the values are lists of locations that the unit on that hex can move to. The location set is returned in raw form, but it can be converted to a standard location set with the following code:
 <syntaxhighlight lang=lua>

← Older revision		Revision as of 03:40, 11 November 2022
Line 250:		Line 250:

	[[Category:Lua Reference]]		[[Category:Lua Reference]]
		+	[[Category:AI]]

@@ Line 26: / Line 26: @@
 The following aspects return scalar values (numbers, strings, or booleans):
 * '''aggression'''
 * '''caution'''
 * '''grouping'''

@@ Line 155: / Line 155: @@
 === ai.attack ===
-* {{LuaGameOnly}} (mutable) '''ai.attack'''(''attacker'', ''defender'', ''weapon'', ''aggression'') &rarr; ''result''
+* {{LuaGameOnly}} (mutable) '''ai.attack'''(''attacker'', ''defender'', ''weapon'', [''aggression'']) &rarr; ''result''
 Execute attack by ''attacker'' against ''defender''. If ''weapon'' is provided, it is the number of the weapon to be used (count starts at 1, not 0, as always in Lua), otherwise the choice of the weapon is left to the AI engine.  If ''aggression'' is provided, it is used to influence the choice of the best weapon.  Obviously, this only makes sense if this choice is left to the engine, that is, if ''weapon'' is set to either 'nil' or '-1'.
@@ Line 161: / Line 161: @@
 === ai.check_attack ===
-* {{LuaGameOnly}} '''ai.check_attack'''(''attacker'', ''defender'', ''weapon'', ''aggression'') &rarr; ''result''
+* {{LuaGameOnly}} '''ai.check_attack'''(''attacker'', ''defender'', ''weapon'', [''aggression'']) &rarr; ''result''
 Similar to '''ai.attack''', but does not execute the attack – it merely checks if it would succeed.
@@ Line 185: / Line 185: @@
 === ai.recall ===
-* {{LuaGameOnly}} (mutable) '''ai.recall'''(''unit_id'', ''location'') &rarr; ''result''
+* {{LuaGameOnly}} (mutable) '''ai.recall'''(''unit_id'', [''location'']) &rarr; ''result''
 Recall the unit with id ''unit_id''.  An optional recruit location can be given.  If the location is omitted, a suitable hex is automatically chosen by the AI engine.
@@ Line 193: / Line 193: @@
 === ai.check_recall ===
-* {{LuaGameOnly}} '''ai.check_recall'''(''unit_id'', ''location'') &rarr; ''result''
+* {{LuaGameOnly}} '''ai.check_recall'''(''unit_id'', [''location'']) &rarr; ''result''
 Similar to '''ai.recall''', but does not execute the recall – it merely checks if it would succeed.
@@ Line 199: / Line 199: @@
 === ai.recruit ===
-* {{LuaGameOnly}} (mutable) '''ai.recruit'''(''unit_type'', ''location'') &rarr; ''result''
+* {{LuaGameOnly}} (mutable) '''ai.recruit'''(''unit_type'', [''location'']) &rarr; ''result''
 Recruit a unit of type ''unit_type''. An optional recruit location can be given.  If the location is omitted, a suitable hex is automatically chosen by the AI engine.
@@ Line 207: / Line 207: @@
 === ai.check_recruit ===
-* {{LuaGameOnly}} '''ai.check_recruit'''(''unit_type'', ''location'') &rarr; ''result''
+* {{LuaGameOnly}} '''ai.check_recruit'''(''unit_type'', [''location'']) &rarr; ''result''
 Similar to '''ai.recruit''', but does not execute the recruit – it merely checks if it would succeed.

@@ Line 55: / Line 55: @@
 *:{{DevFeature1.17|?}} It's now even simpler to convert:<syntaxhighlight lang=lua>
 local location_set = wesnoth.require "location_set"
-local ls = ls.of_raw(ai.aspects.advancements)
+local ls = location_set.of_raw(ai.aspects.advancements)
 </syntaxhighlight>
 * '''attacks''' – a table with keys '''own''' containing all units that may attack and '''enemy''' containing all units that may be attacked.
@@ Line 129: / Line 129: @@
 {{DevFeature1.17|?}} It's now even simpler to convert:<syntaxhighlight lang=lua>
 local location_set = wesnoth.require "location_set"
-local ls = ls.of_raw(ai.get_dst_src())
+local ls = location_set.of_raw(ai.get_dst_src())
 </syntaxhighlight>

@@ Line 126: / Line 126: @@
 -- Now you can use it as a regular location set
 print(ls[{1,4}]) -- prints out something like {{5,4},{5,3}} or the like
 </syntaxhighlight>

@@ Line 181: / Line 181: @@
 Recall the unit with id ''unit_id''.  An optional recruit location can be given.  If the location is omitted, a suitable hex is automatically chosen by the AI engine.
-{{DevFeature1.15|14}} The location must be specified as separate ''x'' and ''y'' parameters.
+{{DevFeature1.17|0}} The location may be specified as an object (for example, <tt>{x,y}</tt> or a unit) rather than separate ''x'' and ''y'' parameters.
 === ai.check_recall ===
@@ Line 195: / Line 195: @@
 Recruit a unit of type ''unit_type''. An optional recruit location can be given.  If the location is omitted, a suitable hex is automatically chosen by the AI engine.
-{{DevFeature1.15|14}} The location must be specified as separate ''x'' and ''y'' parameters.
+{{DevFeature1.17|0}} The location may be specified as an object (for example, <tt>{x,y}</tt> or a unit) rather than separate ''x'' and ''y'' parameters.
 === ai.check_recruit ===

@@ Line 4: / Line 4: @@
 == Game State Queries ==
 * {{LuaGameOnly}} '''ai.read_only''' &rarr; ''boolean''
 The AI module operates in two modes: read-only, and read-write. Read-write mode is used in the execution function for stages and candidate actions, while read-only mode is used in goals and aspects and in the evaluation function for candidate actions. The '''read_only''' key allows you to distinguish these cases at runtime, if necessary. Functions that are only available in read-write mode will be tagged (mutable) in the descriptions on this page.
 * {{LuaGameOnly}} '''ai.side''' &rarr; ''number''

@@ Line 2: / Line 2: @@
 Code executed by [[Wesnoth AI]] components has access to the <tt>ai</tt> module, which contains functions for controlling the AI and querying AI information. Thus, all functions on this page are only available to AI code.
 * {{LuaGameOnly}} '''ai.read_only''' &rarr; ''boolean''
@@ Line 10: / Line 12: @@
 The side number that the AI module is bound to.
 === ai.aspects ===
@@ Line 18: / Line 18: @@
 Provides access to the aspects of the AI engine. This fetches the result of the aspect evaluation given the game state when it was last refreshed (see [[Wesnoth_AI_Framework#Some_more_on_the_invalidation_keys|aspect invalidation rules]]), not its definition. So, for example, '''ai.aspects.avoid''' returns the list of avoided hexes, not the
-[[StandardLocationFilter|Standard Location Filter]] that produced them, and a [[#Dynamic_Lua_Aspects|dynamic Lua aspect]] will return the result of calling the function, not the function itself.
+[[StandardLocationFilter|Standard Location Filter]] that produced them, and a [[#Dynamic_Lua_Aspects|dynamic Lua aspect]] will return the result of calling the function, not the function itself. For more details, see the definition of each aspect on [[AiWML]].
 The following aspects return scalar values (numbers, strings, or booleans):
@@ Line 38: / Line 38: @@
 * '''village_value'''
 * '''villages_per_scout'''
 The following aspects return tables:
-* '''advancements''' – a location set mapping locations to a list of possible advancements for the unit on that hex. To convert this to a location set:
+* '''advancements''' – the values of a [[LuaAPI/location_set|location set]] mapping locations to a list of possible advancements for the unit on that hex. To convert this to a fully functional standard  location set:
 *:<syntaxhighlight lang=lua>
 local location_set = wesnoth.require "location_set"
@@ Line 51: / Line 49: @@
 print(ls[{5,6}]) -- might print out {"Elvish Hero", "Elvish Captain"} for example
 </syntaxhighlight>
-* '''attacks''' – a table with keys '''own''' containing all units that can attack and '''enemy''' containing all units that can be attacked.
+* '''attacks''' – a table with keys '''own''' containing all units that may attack and '''enemy''' containing all units that may be attacked.
 * '''avoid''' – an array of locations.
 * '''leader_goal''' – the WML content of the leader_goal aspect
@@ Line 63: / Line 61: @@
 * {{LuaGameOnly}} '''ai.get_attacks'''() &rarr; ''array of attack analyses''
-Get all possible attacks the AI could perform, and an analysis of each. Each attack analysis table has the following keys:
+Get all possible attacks the AI is able to perform, and an analysis of each. If multiple AI units can attack the same enemy, all different combinations of AI units are listed. However, for a given combination of AI units, only one attack (the one the AI considers best) is listed. In other words, permutations of those units placed on different hexes are not included, as that would result in too long a list.
 * ''analysis''.'''rating'''() &rarr; ''numeric rating''
@@ Line 72: / Line 72: @@
 * ''analysis''.'''target_value''' &rarr; ''number''
 * ''analysis''.'''avg_losses''' &rarr; ''number''
-* ''analysis''.'''chance_to_kill''' &rarr; '''probability''
+* ''analysis''.'''chance_to_kill''' &rarr; ''probability''
 * ''analysis''.'''avg_damage_inflicted''' &rarr; ''number''
 * ''analysis''.'''target_starting_damage''' &rarr; ''integer''
@@ Line 110: / Line 110: @@
 * {{LuaGameOnly}} '''ai.get_enemy_src_dst'''() &rarr; ''move map''
-These functions return move maps – tables that relate the current positions of units with the hexes they can move to. A move map is a location set, similar to the advancements map, which can be converted to a standard location set with the following code:
+These functions return move maps – tables that relate the current positions of units with the hexes they can move to. A move map is a [[LuaAPI/location_set|location set]], similar to the advancements map, which can be converted to a standard location set with the following code:
 <syntaxhighlight lang=lua>
@@ Line 143: / Line 143: @@
 === ai.attack ===
-* {{LuaGameOnly}} (mutable) '''ai.check_attack'''(''attacker'', ''defender'', ''weapon'', ''aggression'') &rarr; ''result''
+* {{LuaGameOnly}} (mutable) '''ai.attack'''(''attacker'', ''defender'', ''weapon'', ''aggression'') &rarr; ''result''
 Execute attack by ''attacker'' against ''defender''. If ''weapon'' is provided, it is the number of the weapon to be used (count starts at 1, not 0, as always in Lua), otherwise the choice of the weapon is left to the AI engine.  If ''aggression'' is provided, it is used to influence the choice of the best weapon.  Obviously, this only makes sense if this choice is left to the engine, that is, if ''weapon'' is set to either 'nil' or '-1'.
@@ Line 177: / Line 177: @@
 Recall the unit with id ''unit_id''.  An optional recruit location can be given.  If the location is omitted, a suitable hex is automatically chosen by the AI engine.
-'''Note:''' The location must be specified as separate ''x'' and ''y'' parameters in 1.16.x.
+{{DevFeature1.15|14}} The location must be specified as separate ''x'' and ''y'' parameters.
 === ai.check_recall ===
@@ Line 191: / Line 191: @@
 Recruit a unit of type ''unit_type''. An optional recruit location can be given.  If the location is omitted, a suitable hex is automatically chosen by the AI engine.
-'''Note:''' The location must be specified as separate ''x'' and ''y'' parameters in 1.16.x.
+{{DevFeature1.15|14}} The location must be specified as separate ''x'' and ''y'' parameters.
 === ai.check_recruit ===