LuaWML/Sides

This page describes the LuaWML functions and helpers for handling sides and villages.

wesnoth.sides

This is not a function but a table indexed by side numbers. Its elements are proxy tables with these fields:

• side: the side number
• gold, village_gold, base_income: integers (read/write)
• total_income: integer (read only)
• objectives, user_team_name: translatable strings (read/write)
• objectives_changed: boolean (read/write)
• team_name: string (read/write)
• is_local (Version 1.13.8 and later only): boolean (read). Whether the side is local. Careless use will cause OOS errors.
• controller: string (read/write) :

note: In networked multiplayer, the controller attribute is ambiguous (won't be the same on all clients). Be very careful or you'll have OOS errors.

The controller attribute has 6 possible values: human, network, ai, network_ai, null, idle. (Or less, see below.)

A local human should always be "human", a local ai should always be "ai", a remote human should always be "network". and a remote ai should always be "network_ai". An empty side should be null on all clients.

An idle side should appear similarly as a "human" side for all sides that don't own the idle side, i.e. as "network".

These values may be checked using lua, or the :controller command in game.

This value can only be set to 'human', 'ai' or 'null'.

(Version 1.13.8 and later only) Remote and local are no longer differentiated by this field. For example, remote humans will be shown as "human". Use 'is_local' field if you need to differentiate.

• fog: boolean (read (Version 1.13.7 and later only)/write)
• shroud: boolean (read (Version 1.13.7 and later only)/write)
• hidden: boolean (read/write)
• name: string (read)
• faction: (Version 1.13.5 and later only) id of the selected faction, string (multiplayer-only, read)
• faction_name: (Version 1.13.5 and later only) name of the selected faction, string (multiplayer-only, read)
• color: string (read/write)
• recruit: table of strings (read/write)
• scroll_to_leader: boolean (read/write)
• village_support: string (read/write)
• flag: string (read (Version 1.13.7 and later only)/write) As of 1.14.0 this is not writable.
• flag_icon: string (read (Version 1.13.7 and later only)/write)
• defeat_condition: string (read/write) See description at SideWML, ScenarioWML#Scenario_End_Conditions
• lost: bool (read/write) If lost=true this side will be removed from the persitent list at the end of the scenario. This key can also be used to stop the engine from removing a side by setting it to false. Writing this key only works in a victory/defeat event.
• persistent (Version 1.13.5 and later only): boolean (read/write)
• suppress_end_turn_confirmation (Version 1.13.7 and later only): boolean (read/write)
• share_vision (Version 1.13.7 and later only): string (read/write)
• share_maps (Version 1.13.7 and later only): boolean (read)
• share_view (Version 1.13.7 and later only): boolean (read)
• num_units (Version 1.13.7 and later only): integer (read)
• num_villages (Version 1.13.7 and later only): integer (read)
• total_upkeep (Version 1.13.7 and later only): integer (read)
• expenses (Version 1.13.7 and later only): integer (read)
• net_income (Version 1.13.7 and later only): integer (read)
• __cfg: WML table (dump)

The metatable of these proxy tables appears as "side".

local side = wesnoth.sides[1]
side.gold = side.gold + 50
wesnoth.message(string.format("%d sides", #wesnoth.sides))

wesnoth.get_sides

• wesnoth.get_sides(filter)

Returns a table array containing proxy tables for these sides matching the passed StandardSideFilter. The output is the same format as the wesnoth.sides table, above.

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

wesnoth.get_village_owner

• wesnoth.get_village_owner(x, y)

Returns the side that owns the village at the given location.

local owned_by_side_1 = wesnoth.get_village_owner(12, 15) == 1

wesnoth.set_village_owner

• wesnoth.set_village_owner(x, y, side, [fire_events])

Gives ownership of the village at the given location to the given side (or remove ownership if none). Ownership is also removed if nil or 0 is passed for the third parameter, but no capture events are fired in this case. An optional 4th parameter (boolean true|false, default: false) can be passed determining whether to fire any capture events.

wesnoth.set_village_owner(12, 15, 1)

wesnoth.is_enemy

• wesnoth.is_enemy(side1, side2)

Returns true if side A is enemy of side B, false otherwise.

local enemy_flag = wesnoth.is_enemy(1, 3)

wesnoth.match_side

• wesnoth.match_side(side, filter)

Matches a side against a given StandardSideFilter.

wesnoth.message(tostring(wesnoth.match_side(1, {{"has_unit", { type = "Troll" }}})))

wesnoth.get_starting_location

• wesnoth.get_starting_location(side)

Returns the starting location of the given side.

local loc = wesnoth.get_starting_location(1)
wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))

wesnoth.get_side_variable

• wesnoth.get_side_variable(side, name)

Returns a variable stored in the side

local loc = wesnoth.get_side_variable(1, "a.c[7].d")

wesnoth.set_side_variable

• wesnoth.set_side_variable(side, name, content)

Sets a variable stored in the side

local loc = wesnoth.set_side_variable(1, "a.c[7].d", 5)

wesnoth.set_side_id

(Version 1.13.7 and later only)

• wesnoth.set_side_id(side, flag, color)

Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes.

wesnoth.place_shroud

(Version 1.13.7 and later only)

• wesnoth.place_shroud(side, shroud)

Shrouds the specified hexes. You can pass a shroud_data string (which will be merged with existing shroud), a list of specific locations (where each location is a two-element list of x and y coordinates), or the special string "all" to shroud all hexes.

wesnoth.remove_shroud

(Version 1.13.7 and later only)

• wesnoth.remove_shroud(side, shroud)

Unshrouds the specified hexes. Hexes are specified as with place_shroud, except that a shroud_data string will not work.

wesnoth.is_fogged

(Version 1.13.7 and later only)

• wesnoth.is_fogged(side, location)

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

wesnoth.is_shrouded

(Version 1.13.7 and later only)

• wesnoth.is_shrouded(side, location)

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

wesnoth.switch_ai

(Version 1.13.7 and later only)

• wesnoth.switch_ai(side, file)

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

wesnoth.append_ai

(Version 1.13.7 and later only)

• wesnoth.append_ai(side, 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.add_ai_component

(Version 1.13.7 and later only)

• wesnoth.add_ai_component(side, 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.change_ai_component

(Version 1.13.7 and later only)

• wesnoth.change_ai_component(side, path, component)

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

wesnoth.delete_ai_component

(Version 1.13.7 and later only)

• wesnoth.delete_ai_component(side, path)

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

helper.all_teams

• helper.all_teams()

Returns an iterator over sides that can be used in a for-in loop.

Note that the method name "teams" is a historical mistake, currently left out for backwards compatibility. It has no relation to [team] tag.

for side in helper.all_teams() do side.gold = 200 end