LuaAPI/wesnoth/sides

(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])
• side:add_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.sides → number 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