Difference between revisions of "LuaAPI/wesnoth/sides"

From The Battle for Wesnoth Wiki
m (Increase level of all headers by one)
(Document the fog functions)
Line 33: Line 33:
  
 
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.add_fog ===
 +
 +
* '''wesnoth.sides.add_fog'''([''sides''], ''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. 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''])
 +
 +
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. 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.
 +
 +
<syntaxhighlight lang=lua>
 +
wesnoth.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
 +
wesnoth.remove_fog(wesnoth.sides[1].side, { {5, 5} }) -- removes fog for first side on 5,5
 +
wesnoth.remove_fog(1, wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5
 +
</syntaxhighlight>
 +
 +
=== wesnoth.sides.is_fogged ===
 +
 +
* '''wesnoth.sides.is_fogged(''side'', ''location'') &rarr; ''boolean''
 +
 +
Check if a specific location is under fog for the given side.
  
 
=== wesnoth.sides.switch_ai ===
 
=== wesnoth.sides.switch_ai ===

Revision as of 18:03, 24 June 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.add_fog

  • wesnoth.sides.add_fog([sides], 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. 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])

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. 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.remove_fog(1, { {5, 5}, {5, 6} }) --removes fog on 5,5 and 5,6 for side 1
wesnoth.remove_fog(wesnoth.sides[1].side, { {5, 5} }) -- removes fog for first side on 5,5
wesnoth.remove_fog(1, wesnoth.get_locations{ x = 5, y = 5 }) --removes fog on 5,5

wesnoth.sides.is_fogged

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

Check if a specific location is under fog for 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