Difference between revisions of "LuaAPI/ai"

From The Battle for Wesnoth Wiki
(Add context specifiers to each entry; it's redundant but it's useful redundancy)
m (Various minor changes)
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.
 
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.
 +
 +
== Game State Queries ==
  
 
* {{LuaGameOnly}} '''ai.read_only''' &rarr; ''boolean''
 
* {{LuaGameOnly}} '''ai.read_only''' &rarr; ''boolean''
Line 10: Line 12:
  
 
The side number that the AI module is bound to.
 
The side number that the AI module is bound to.
 
== Game State Queries ==
 
  
 
=== ai.aspects ===
 
=== 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  
 
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):
 
The following aspects return scalar values (numbers, strings, or booleans):
Line 38: Line 38:
 
* '''village_value'''
 
* '''village_value'''
 
* '''villages_per_scout'''
 
* '''villages_per_scout'''
 
For more details, see the definition of each aspect on [[AiWML]].
 
  
 
The following aspects return tables:
 
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>
 
*:<syntaxhighlight lang=lua>
 
local location_set = wesnoth.require "location_set"
 
local location_set = wesnoth.require "location_set"
Line 51: Line 49:
 
print(ls[{5,6}]) -- might print out {"Elvish Hero", "Elvish Captain"} for example
 
print(ls[{5,6}]) -- might print out {"Elvish Hero", "Elvish Captain"} for example
 
</syntaxhighlight>
 
</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.
 
* '''avoid''' – an array of locations.
 
* '''leader_goal''' – the WML content of the leader_goal aspect
 
* '''leader_goal''' – the WML content of the leader_goal aspect
Line 63: Line 61:
 
* {{LuaGameOnly}} '''ai.get_attacks'''() &rarr; ''array of attack analyses''
 
* {{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.
 +
 
 +
Each attack analysis table has the following keys:
  
 
* ''analysis''.'''rating'''() &rarr; ''numeric rating''
 
* ''analysis''.'''rating'''() &rarr; ''numeric rating''
Line 72: Line 72:
 
* ''analysis''.'''target_value''' &rarr; ''number''
 
* ''analysis''.'''target_value''' &rarr; ''number''
 
* ''analysis''.'''avg_losses''' &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''.'''avg_damage_inflicted''' &rarr; ''number''
 
* ''analysis''.'''target_starting_damage''' &rarr; ''integer''
 
* ''analysis''.'''target_starting_damage''' &rarr; ''integer''
Line 110: Line 110:
 
* {{LuaGameOnly}} '''ai.get_enemy_src_dst'''() &rarr; ''move map''
 
* {{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>
 
<syntaxhighlight lang=lua>
Line 143: Line 143:
 
=== ai.attack ===
 
=== 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'.
 
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.
 
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 ===
 
=== 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.
 
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 ===
 
=== ai.check_recruit ===

Revision as of 14:52, 10 July 2021

Code executed by Wesnoth AI components has access to the ai module, which contains functions for controlling the AI and querying AI information. Thus, all functions on this page are only available to AI code.

Game State Queries

  • ai.read_onlyboolean

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.

  • ai.sidenumber

The side number that the AI module is bound to.

ai.aspects

  • ai.aspects.aspectvalue

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 aspect invalidation rules), not its definition. So, for example, ai.aspects.avoid returns the list of avoided hexes, not the Standard Location Filter that produced them, and a 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):

  • aggression
  • caution
  • grouping
  • leader_aggression
  • leader_ignores_keep
  • leader_value
  • passive_leader
  • passive_leader_shares_keep
  • recruitment_diversity
  • recruitment_randomness
  • retreat_enemy_weight
  • retreat_factor
  • scout_village_targeting
  • simple_targeting
  • support_villages
  • village_value
  • villages_per_scout

The following aspects return tables:

  • advancements – the values of a 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:
    local location_set = wesnoth.require "location_set"
    local ls = location_set.create()
    ls.values = ai.aspects.advancements
    -- Now you can use it as a regular location set
    print(ls[{5,6}]) -- might print out {"Elvish Hero", "Elvish Captain"} for example
    
  • 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
  • recruitment_instructions – the WML content of the recruitment_instructions aspect
  • recruitment_more – an array of strings where each string is a usage, a unit type ID, or an integer
  • recruitment_pattern – an array of usage strings (see UnitTypeWML for an explanation of usage)
  • recruitment_save_gold – the WML content of the recruitment_save_gold aspect

ai.get_attacks

  • ai.get_attacks() → array of attack analyses

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.

Each attack analysis table has the following keys:

  • analysis.rating() → numeric rating
  • analysis.movementsarray of location pairs
    • move.srclocation
    • move.dstlocation
  • analysis.targetlocation
  • analysis.target_valuenumber
  • analysis.avg_lossesnumber
  • analysis.chance_to_killprobability
  • analysis.avg_damage_inflictednumber
  • analysis.target_starting_damageinteger
  • analysis.avg_damage_takennumber
  • analysis.resources_usednumber
  • analysis.terrain_qualitynumber
  • analysis.alternative_terrain_qualitynumber
  • analysis.vulnerabilitynumber
  • analysis.supportnumber
  • analysis.leader_threatboolean
  • analysis.uses_leaderboolean
  • analysis.is_surroundedboolean

ai.get_targets

  • ai.get_targets() → array of targets

Get a list of all the current AI targets. Each target has the following keys:

  • loc: The coordinates of the target, as a 2-element array.
  • type: The type of target, as a string.
  • value: The value of the target, as a real number.

The possible target types are 'village', 'leader', 'explicit', 'threat', 'battle aid', 'mass', 'support'. More information on the meaning of each type can be found in the LuaAI documentation.

ai.suitable_keep

  • ai.suitable_keep(unit) → x, y

This returns the location of the closest keep to the unit passed as argument.

Move Maps

  • ai.get_dst_src() → move map
  • ai.get_src_dst() → move map
  • ai.get_enemy_dst_src() → move map
  • ai.get_enemy_src_dst() → 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:

local location_set = wesnoth.require "location_set"
local ls = location_set.create()
ls.values = ai.get_dst_src()
-- 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

These functions are defined in ai/lua/stdlib.lua, which is loaded by default if you allow the game to implicitly define a Lua [engine] tag. However, if you require a custom Lua [engine] tag, it must load this file manually with the following code in order to use these functions:

local ai_stdlib = wesnoth.require('ai/lua/stdlib.lua')
ai_stdlib.init(ai)
  • ai.recalculate_move_maps()
  • ai.recalculate_enemy_move_maps()

Force the move maps to be recalculated. This might be necessary if you've moved units around using wesnoth.units.to_map.

AI Actions

All these functions instruct the AI to check or perform a specific action, and return a result table indicating the success of the action. The table has the following keys:

  • gamestate_changed: a boolean indicating whether anything actually changed as a result of the action
  • ok: a boolean indicating the success of the action
  • status: a numeric status code indicating why the action failed
  • result: a string error code indicating why the action failed

ai.attack

  • (mutable) ai.attack(attacker, defender, weapon, aggression) → 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'.

ai.check_attack

  • ai.check_attack(attacker, defender, weapon, aggression) → result

Similar to ai.attack, but does not execute the attack – it merely checks if it would succeed.

ai.move

  • (mutable) ai.move(unit, to) → result

Execute a "partial" move of unit to hex (to.x, to.y). A "partial" move means that the unit keeps whatever movement points it has left after the move.

ai.move_full

  • (mutable) ai.move_full(unit, to) → result

Execute a "full" move of unit to hex (to.x, to.y). A "full" move means that the unit's movement points are set to zero at the end of the move.

ai.check_move

  • ai.check_move(unit, to) → result

Similar to ai.move or ai.move_full, but does not execute the move – it merely checks if it would succeed.

ai.recall

  • (mutable) ai.recall(unit_id, location) → 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.

(Version 1.15.14 and later only) The location must be specified as separate x and y parameters.

ai.check_recall

  • ai.check_recall(unit_id, location) → result

Similar to ai.recall, but does not execute the recall – it merely checks if it would succeed.

ai.recruit

  • (mutable) ai.recruit(unit_type, location) → 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.

(Version 1.15.14 and later only) The location must be specified as separate x and y parameters.

ai.check_recruit

  • ai.check_recruit(unit_type, location) → result

Similar to ai.recruit, but does not execute the recruit – it merely checks if it would succeed.

ai.stopunit_attacks

  • (mutable) ai.stopunit_attacks(unit) → result

Remove remaining attacks from unit. This is equivalent to setting attacks_left=0.

ai.stopunit_moves

  • (mutable) ai.stopunit_moves(unit) → result

Remove remaining movement points from unit. This is equivalent to setting moves=0.

ai.stopunit_all

  • (mutable) ai.stopunit_all(unit) →

Remove both remaining attacks and remaining movement points from unit.

ai.check_stopunit

  • ai.check_stopunit(unit) → result

Similar to ai.stopunit_attacks, ai.stopunit_moves, or ai.stopunit_all, but does not execute the stop – it merely checks if it would succeed.

ai.fallback_human

  • (mutable) ai.fallback_human()

Hands over control of this side to the local human player until the end of the current turn. This action does not return a result; it always succeeds.

See Also

There are two other functions that are not in the AI module but are important for AI coding: