Difference between revisions of "LuaAPI/wesnoth/sides"

From The Battle for Wesnoth Wiki
(Document the sides module)
 
m (Increase level of all headers by one)
Line 5: Line 5:
 
All functions taking a side on this page (except '''get''') will accept either the integer index of the side or the side proxy userdata (as returned by '''get''' or '''find''').
 
All functions taking a side on this page (except '''get''') will accept either the integer index of the side or the side proxy userdata (as returned by '''get''' or '''find''').
  
==== wesnoth.sides.is_enemy ====
+
=== wesnoth.sides.is_enemy ===
  
 
* '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
 
* '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
Line 16: Line 16:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== wesnoth.sides.matches ====
+
=== wesnoth.sides.matches ===
  
 
* '''wesnoth.sides.match_side'''(''side'', ''filter'') &rarr; ''boolean''
 
* '''wesnoth.sides.match_side'''(''side'', ''filter'') &rarr; ''boolean''
Line 27: Line 27:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== wesnoth.sides.set_id ====
+
=== wesnoth.sides.set_id ===
  
 
* '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
 
* '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
Line 34: Line 34:
 
Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes. Both attributes can also be changed through the side proxy attributes, but changing both at the same time is slightly more efficient.
 
Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes. Both attributes can also be changed through the side proxy attributes, but changing both at the same time is slightly more efficient.
  
==== wesnoth.sides.switch_ai ====
+
=== wesnoth.sides.switch_ai ===
  
 
* '''wesnoth.sides.switch_ai'''(''side'', ''file'')
 
* '''wesnoth.sides.switch_ai'''(''side'', ''file'')
Line 41: Line 41:
 
Replaces a side's AI with the configuration from a specified file.
 
Replaces a side's AI with the configuration from a specified file.
  
==== wesnoth.sides.append_ai ====
+
=== wesnoth.sides.append_ai ===
  
 
* '''wesnoth.sides.append_ai'''(''side'', ''params'')
 
* '''wesnoth.sides.append_ai'''(''side'', ''params'')
Line 48: Line 48:
 
Appends AI parameters (aspects, stages, goals) to the side's AI. The syntax for the parameters to be appended is the same as that supported by '''[modify_side]'''.
 
Appends AI parameters (aspects, stages, goals) to the side's AI. The syntax for the parameters to be appended is the same as that supported by '''[modify_side]'''.
  
==== wesnoth.sides.add_ai_component ====
+
=== wesnoth.sides.add_ai_component ===
  
 
* '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
 
* '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
Line 55: Line 55:
 
Adds a component to the side's AI. The path syntax is the same as that used by '''[modify_ai]'''. The component is the content of the component - it should not contain eg a toplevel '''[facet]''' tag.
 
Adds a component to the side's AI. The path syntax is the same as that used by '''[modify_ai]'''. The component is the content of the component - it should not contain eg a toplevel '''[facet]''' tag.
  
==== wesnoth.sides.change_ai_component ====
+
=== wesnoth.sides.change_ai_component ===
  
 
* '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
 
* '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
Line 62: Line 62:
 
Like add_ai_component, but replaces an existing component instead of adding a new one.
 
Like add_ai_component, but replaces an existing component instead of adding a new one.
  
==== wesnoth.sides.delete_ai_component ====
+
=== wesnoth.sides.delete_ai_component ===
  
 
* '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
 
* '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
Line 69: Line 69:
 
Like add_ai_component, but removes a component instead of adding one.
 
Like add_ai_component, but removes a component instead of adding one.
  
==== wesnoth.sides.get ====
+
=== wesnoth.sides.get ===
  
 
* '''wesnoth.sides.get'''(''id'') &rarr; ''side proxy''
 
* '''wesnoth.sides.get'''(''id'') &rarr; ''side proxy''
Line 77: Line 77:
 
Returns the specified side, which must be a valid integer side ID.
 
Returns the specified side, which must be a valid integer side ID.
  
==== wesnoth.sides.find ====
+
=== wesnoth.sides.find ===
  
 
* '''wesnoth.sides.find'''(''filter'') &rarr; ''array of sides''
 
* '''wesnoth.sides.find'''(''filter'') &rarr; ''array of sides''

Revision as of 12:03, 6 December 2019

(Version 1.15.3 and later only)

The sides module is only available in the game. It is not available to plugins or map generators.

All functions taking a side on this page (except get) will accept either the integer index of the side or the side proxy userdata (as returned by get or find).

wesnoth.sides.is_enemy

  • wesnoth.sides.is_enemy(side1, side2) → boolean
  • side1:is_enemy(side2) → boolean

Returns true if side 1 is an enemy of side 2, false otherwise.

local enemy_flag = wesnoth.sides.is_enemy(1, 3)

wesnoth.sides.matches

  • wesnoth.sides.match_side(side, filter) → boolean
  • side:matches(filter) → boolean

Matches a side against a given StandardSideFilter.

wesnoth.message(tostring(wesnoth.sides[1]:matches{ wml.tag.has_unit { type = "Troll" } }))

wesnoth.sides.set_id

  • wesnoth.sides.set_id(side, flag, color)
  • side:set_id(flag, color)

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes. Both attributes can also be changed through the side proxy attributes, but changing both at the same time is slightly more efficient.

wesnoth.sides.switch_ai

  • wesnoth.sides.switch_ai(side, file)
  • side:switch_ai(file)

Replaces a side's AI with the configuration from a specified file.

wesnoth.sides.append_ai

  • wesnoth.sides.append_ai(side, params)
  • side:append_ai(params)

Appends AI parameters (aspects, stages, goals) to the side's AI. The syntax for the parameters to be appended is the same as that supported by [modify_side].

wesnoth.sides.add_ai_component

  • wesnoth.sides.add_ai_component(side, path, component)
  • side:add_ai_component(path, component)

Adds a component to the side's AI. The path syntax is the same as that used by [modify_ai]. The component is the content of the component - it should not contain eg a toplevel [facet] tag.

wesnoth.sides.change_ai_component

  • wesnoth.sides.change_ai_component(side, path, component)
  • side:change_ai_component(path, component)

Like add_ai_component, but replaces an existing component instead of adding a new one.

wesnoth.sides.delete_ai_component

  • wesnoth.sides.delete_ai_component(side, path)
  • side:delete_ai_component(path)

Like add_ai_component, but removes a component instead of adding one.

wesnoth.sides.get

  • wesnoth.sides.get(id) → side proxy
  • wesnoth.sides[id] → side proxy
  • #wesnoth.sidesnumber of sides

Returns the specified side, which must be a valid integer side ID.

wesnoth.sides.find

  • wesnoth.sides.find(filter) → array of sides

Returns a table array containing proxy tables for these sides matching the passed StandardSideFilter.

--set gold to 0 for all sides with a leader
local sides = wesnoth.sides.find{ wml.tag.has_unit { canrecruit = true } }
for i,v in ipairs(sides) do
    v.gold = 0
end