Difference between revisions of "LuaAPI/wesnoth/sides"

From The Battle for Wesnoth Wiki
(Document wesnoth.sides.create)
(Add context specifiers to each entry; it's redundant but it's useful redundancy)
Line 7: Line 7:
 
=== wesnoth.sides.is_enemy ===
 
=== wesnoth.sides.is_enemy ===
  
* '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
+
* {{LuaGameOnly}} '''wesnoth.sides.is_enemy'''(''side1'', ''side2'') → ''boolean''
* ''side1'':'''is_enemy'''(''side2'') → ''boolean''
+
* {{LuaGameOnly}} ''side1'':'''is_enemy'''(''side2'') → ''boolean''
  
 
Returns true if side 1 is an enemy of side 2, false otherwise.
 
Returns true if side 1 is an enemy of side 2, false otherwise.
Line 18: Line 18:
 
=== wesnoth.sides.matches ===
 
=== wesnoth.sides.matches ===
  
* '''wesnoth.sides.match_side'''(''side'', ''filter'') → ''boolean''
+
* {{LuaGameOnly}} '''wesnoth.sides.match_side'''(''side'', ''filter'') → ''boolean''
* ''side'':'''matches'''(''filter'') → ''boolean''
+
* {{LuaGameOnly}} ''side'':'''matches'''(''filter'') → ''boolean''
  
 
Matches a side against a given [[StandardSideFilter]].
 
Matches a side against a given [[StandardSideFilter]].
Line 29: Line 29:
 
=== wesnoth.sides.set_id ===
 
=== wesnoth.sides.set_id ===
  
* '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
+
* {{LuaGameOnly}} '''wesnoth.sides.set_id'''(''side'', ''flag'', ''color'')
* ''side'':'''set_id('''''flag'', ''color'')
+
* {{LuaGameOnly}} ''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.
 
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.
Line 36: Line 36:
 
=== wesnoth.sides.place_fog ===
 
=== wesnoth.sides.place_fog ===
  
* '''wesnoth.sides.place_fog'''([''sides''], ''locations'', [''permanent''])
+
* {{LuaGameOnly}} '''wesnoth.sides.place_fog'''([''sides''], ''locations'', [''permanent''])
* ''side'':'''place_fog'''(''locations'', [''permanent''])
+
* {{LuaGameOnly}} ''side'':'''place_fog'''(''locations'', [''permanent''])
  
 
Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, but not a list of such. The ''permanent'' argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.
 
Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, but not a list of such. The ''permanent'' argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.
Line 43: Line 43:
 
=== wesnoth.sides.remove_fog ===
 
=== wesnoth.sides.remove_fog ===
  
* '''wesnoth.sides.remove_fog'''([''sides''], ''locations'', [''permanent''])
+
* {{LuaGameOnly}} '''wesnoth.sides.remove_fog'''([''sides''], ''locations'', [''permanent''])
* ''side'':'''remove_fog'''(''locations'', [''permanent''])
+
* {{LuaGameOnly}} ''side'':'''remove_fog'''(''locations'', [''permanent''])
  
 
Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, though not a list of such. The ''permanent'' argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.
 
Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, though not a list of such. The ''permanent'' argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.
Line 56: Line 56:
 
=== wesnoth.sides.is_fogged ===
 
=== wesnoth.sides.is_fogged ===
  
* '''wesnoth.sides.is_fogged(''side'', ''location'') → ''boolean''
+
* {{LuaGameOnly}} '''wesnoth.sides.is_fogged(''side'', ''location'') → ''boolean''
* ''side'':'''is_fogged'''(''side'') → ''boolean''
+
* {{LuaGameOnly}} ''side'':'''is_fogged'''(''side'') → ''boolean''
  
 
Check if a specific location is under fog for the given side.
 
Check if a specific location is under fog for the given side.
Line 63: Line 63:
 
=== wesnoth.sides.place_shroud ===
 
=== wesnoth.sides.place_shroud ===
  
* '''wesnoth.sides.place_shroud'''(''side'', ''locations'')
+
* {{LuaGameOnly}} '''wesnoth.sides.place_shroud'''(''side'', ''locations'')
* ''side'':'''place_shroud'''(''locations'')
+
* {{LuaGameOnly}} ''side'':'''place_shroud'''(''locations'')
  
 
Places shroud on the specified hexes for the chosen side. This merges the new shroud with any existing shroud on the map. The locations must be passed as an array of pairs, but if you want to merge in a shroud data string, you can parse it first with [[../map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]].
 
Places shroud on the specified hexes for the chosen side. This merges the new shroud with any existing shroud on the map. The locations must be passed as an array of pairs, but if you want to merge in a shroud data string, you can parse it first with [[../map#wesnoth.map.parse_bitmap|wesnoth.map.parse_bitmap]].
Line 70: Line 70:
 
=== wesnoth.sides.override_shroud ===
 
=== wesnoth.sides.override_shroud ===
  
* '''wesnoth.sides.override_shroud'''(''side'', ''locations'')
+
* {{LuaGameOnly}} '''wesnoth.sides.override_shroud'''(''side'', ''locations'')
* ''side'':'''override_shroud'''(''locations'')
+
* {{LuaGameOnly}} ''side'':'''override_shroud'''(''locations'')
  
 
Places shroud on the specified hexes for the chosen side. This replaces any existing shroud on the map – after calling `override_shroud`, the locations passed will be the ''only'' shrouded locations.
 
Places shroud on the specified hexes for the chosen side. This replaces any existing shroud on the map – after calling `override_shroud`, the locations passed will be the ''only'' shrouded locations.
Line 77: Line 77:
 
=== wesnoth.sides.remove_shroud ===
 
=== wesnoth.sides.remove_shroud ===
  
* '''wesnoth.sides.remove_shroud'''(''side'', ''locations'')
+
* {{LuaGameOnly}} '''wesnoth.sides.remove_shroud'''(''side'', ''locations'')
* ''side'':'''remove_shroud'''(''locations'')
+
* {{LuaGameOnly}} ''side'':'''remove_shroud'''(''locations'')
  
 
Unshrouds the specified hexes for the chosen side.
 
Unshrouds the specified hexes for the chosen side.
Line 84: Line 84:
 
=== wesnoth.sides.is_shrouded ===
 
=== wesnoth.sides.is_shrouded ===
  
* '''wesnoth.sides.is_shrouded'''(''side'', ''location'') → ''boolean''
+
* {{LuaGameOnly}} '''wesnoth.sides.is_shrouded'''(''side'', ''location'') → ''boolean''
* ''side'':'''is_shrouded'''(''location'') → ''boolean''
+
* {{LuaGameOnly}} ''side'':'''is_shrouded'''(''location'') → ''boolean''
  
 
Tests if the given location is under shroud from the point of view of the given side.
 
Tests if the given location is under shroud from the point of view of the given side.
Line 91: Line 91:
 
=== wesnoth.sides.switch_ai ===
 
=== wesnoth.sides.switch_ai ===
  
* '''wesnoth.sides.switch_ai'''(''side'', ''file'')
+
* {{LuaGameOnly}} '''wesnoth.sides.switch_ai'''(''side'', ''file'')
* ''side'':'''switch_ai'''(''file'')
+
* {{LuaGameOnly}} ''side'':'''switch_ai'''(''file'')
  
 
Replaces a side's AI with the configuration from a specified file.
 
Replaces a side's AI with the configuration from a specified file.
Line 98: Line 98:
 
=== wesnoth.sides.append_ai ===
 
=== wesnoth.sides.append_ai ===
  
* '''wesnoth.sides.append_ai'''(''side'', ''params'')
+
* {{LuaGameOnly}} '''wesnoth.sides.append_ai'''(''side'', ''params'')
* ''side'':'''append_ai'''(''params'')
+
* {{LuaGameOnly}} ''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]'''.
 
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]'''.
Line 105: Line 105:
 
=== wesnoth.sides.add_ai_component ===
 
=== wesnoth.sides.add_ai_component ===
  
* '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
+
* {{LuaGameOnly}} '''wesnoth.sides.add_ai_component'''(''side'', ''path'', ''component'')
* ''side'':'''add_ai_component'''(''path'', ''component'')
+
* {{LuaGameOnly}} ''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.
 
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.
Line 112: Line 112:
 
=== wesnoth.sides.change_ai_component ===
 
=== wesnoth.sides.change_ai_component ===
  
* '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
+
* {{LuaGameOnly}} '''wesnoth.sides.change_ai_component'''(''side'', ''path'', ''component'')
* ''side'':'''change_ai_component'''(''path'', ''component'')
+
* {{LuaGameOnly}} ''side'':'''change_ai_component'''(''path'', ''component'')
  
 
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.
Line 119: Line 119:
 
=== wesnoth.sides.delete_ai_component ===
 
=== wesnoth.sides.delete_ai_component ===
  
* '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
+
* {{LuaGameOnly}} '''wesnoth.sides.delete_ai_component'''(''side'', ''path'')
* ''side'':'''delete_ai_component'''(''path'')
+
* {{LuaGameOnly}} ''side'':'''delete_ai_component'''(''path'')
  
 
Like add_ai_component, but removes a component instead of adding one.
 
Like add_ai_component, but removes a component instead of adding one.
Line 126: Line 126:
 
=== wesnoth.sides.get ===
 
=== wesnoth.sides.get ===
  
* '''wesnoth.sides.get'''(''id'') → ''side proxy''
+
* {{LuaGameOnly}} '''wesnoth.sides.get'''(''id'') → ''side proxy''
* '''wesnoth.sides'''[''id''] → ''side proxy''
+
* {{LuaGameOnly}} '''wesnoth.sides'''[''id''] → ''side proxy''
* #'''wesnoth.sides''' → ''number of sides''
+
* {{LuaGameOnly}} #'''wesnoth.sides''' → ''number of sides''
  
 
Returns the specified side, which must be a valid integer side ID.
 
Returns the specified side, which must be a valid integer side ID.
Line 134: Line 134:
 
=== wesnoth.sides.find ===
 
=== wesnoth.sides.find ===
  
* '''wesnoth.sides.find'''(''filter'') → ''array of sides''
+
* {{LuaGameOnly}} '''wesnoth.sides.find'''(''filter'') → ''array of sides''
  
 
Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].  
 
Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].  
Line 148: Line 148:
 
=== wesnoth.sides.create ===
 
=== wesnoth.sides.create ===
  
* '''wesnoth.sides.create'''() → ''new side number''
+
* {{LuaGameOnly}} '''wesnoth.sides.create'''() → ''new side number''
  
 
Adds a new blank side to the end of the scenario sides list and returns its number.
 
Adds a new blank side to the end of the scenario sides list and returns its number.
Line 154: Line 154:
 
=== wesnoth.sides.debug_ai ===
 
=== wesnoth.sides.debug_ai ===
  
* '''wesnoth.sides.debug_ai'''(''side'') → ''ai context table''
+
* {{LuaGameOnly}} '''wesnoth.sides.debug_ai'''(''side'') → ''ai context table''
* ''side'':'''debug_ai'''() → ''ai context table''
+
* {{LuaGameOnly}} ''side'':'''debug_ai'''() → ''ai context table''
  
 
Returns the AI context table for the given side. This function only exists in debug mode, and only if Wesnoth is launched with the <tt>--debug-lua</tt> command-line argument. This allows you to inspect all the AI internals for that side, including the AI component tree and the AI module (which is instanced per side). You can also execute individual components by calling their execution or evaluation functions.
 
Returns the AI context table for the given side. This function only exists in debug mode, and only if Wesnoth is launched with the <tt>--debug-lua</tt> command-line argument. This allows you to inspect all the AI internals for that side, including the AI component tree and the AI module (which is instanced per side). You can also execute individual components by calling their execution or evaluation functions.

Revision as of 23:37, 4 July 2021

(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.place_fog

  • wesnoth.sides.place_fog([sides], locations, [permanent])
  • side:place_fog(locations, [permanent])

Fogs over the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, but not a list of such. The permanent argument defaults to false, causing temporary fog overrides to be cleared; if true, it affects the team's permanent fog as well.

wesnoth.sides.remove_fog

  • wesnoth.sides.remove_fog([sides], locations, [permanent])
  • side:remove_fog(locations, [permanent])

Unfogs the specified locations for the specified sides (or all sides, if no sides are specified). You can specify sides either as a single integer or a list of integers. A side userdata also works, though not a list of such. The permanent argument defaults to false, creating temporary fog overrides that disappear at the end of the turn; if true, it affects the team's permanent fog as well.

wesnoth.sides.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.sides.remove_fog(wesnoth.sides[1], { {5, 5} }) -- removes fog for first side on 5,5
wesnoth.sides[1]:remove_fog(wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5

wesnoth.sides.is_fogged

  • wesnoth.sides.is_fogged(side, location) → boolean
  • side:is_fogged(side) → boolean

Check if a specific location is under fog for the given side.

wesnoth.sides.place_shroud

  • wesnoth.sides.place_shroud(side, locations)
  • side:place_shroud(locations)

Places shroud on the specified hexes for the chosen side. This merges the new shroud with any existing shroud on the map. The locations must be passed as an array of pairs, but if you want to merge in a shroud data string, you can parse it first with wesnoth.map.parse_bitmap.

wesnoth.sides.override_shroud

  • wesnoth.sides.override_shroud(side, locations)
  • side:override_shroud(locations)

Places shroud on the specified hexes for the chosen side. This replaces any existing shroud on the map – after calling `override_shroud`, the locations passed will be the only shrouded locations.

wesnoth.sides.remove_shroud

  • wesnoth.sides.remove_shroud(side, locations)
  • side:remove_shroud(locations)

Unshrouds the specified hexes for the chosen side.

wesnoth.sides.is_shrouded

  • wesnoth.sides.is_shrouded(side, location) → boolean
  • side:is_shrouded(location) → boolean

Tests if the given location is under shroud from the point of view of the given side.

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

wesnoth.sides.create

  • wesnoth.sides.create() → new side number

Adds a new blank side to the end of the scenario sides list and returns its number.

wesnoth.sides.debug_ai

  • wesnoth.sides.debug_ai(side) → ai context table
  • side:debug_ai() → ai context table

Returns the AI context table for the given side. This function only exists in debug mode, and only if Wesnoth is launched with the --debug-lua command-line argument. This allows you to inspect all the AI internals for that side, including the AI component tree and the AI module (which is instanced per side). You can also execute individual components by calling their execution or evaluation functions.

The returned table contains the following keys:

  • ai: The ai module bound to this side. Each side has a separate instance of the AI module.
  • components: The AI components tree. Each component in this tree potentially has the following subkeys:
    • engine, id, name: The basic info about the component - its name and ID and the engine it runs on.
    • stage, candidate_action: An array of subcomponents of the specified type.
    • exec: For stages or candidate actions, a function which, when called, executes it immediately (and synchronously). Prefer calling this with the :lua command rather than from the Lua console.
  • engine: The complete contents of the Lua [engine] tag.
  • params: The contents of the [args] tag from the Lua [engine] tag.
  • data: A WML table containing persistent data used by the AI. This data is serialized as part of the Lua [engine] tag.
  • update_self: The function defined in the Lua [engine] tag. Called as update_self(params, data).

The above list covers only the most useful keys and is not exhaustive.

Some examples:

wesnoth.debug_ai(2).ai -- returns the AI module bound to side 2
wesnoth.debug_ai(2).stage[another_stage].exec() -- executes the "another_stage" stage for side 2
wesnoth.debug_ai(2).ai.aspects.aggression -- returns the current value of the aggression aspect of the AI on side 2

Note: Do not rely on the precise structure of the AI context table. It is documented here as an aid to debugging, but it is not public API and may change without warning or deprecation.