LuaAPI/wesnoth/sides

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).

Functions

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)

Clears shroud on the specified hexes for the chosen side. This replaces any existing shroud data on the map – after calling `override_shroud`, the locations passed will be the only unshrouded 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

wesnoth.sides.iter

(Version 1.17.? and later only)

♟ wesnoth.sides.iter(filter?) → iterator ⇒ side

Iterate over all sides, or sides that match a filter.

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.