LuaWML/Sides

From The Battle for Wesnoth Wiki
< LuaWML
Revision as of 00:40, 29 May 2017 by Celtic Minstrel (talk | contribs) (wesnoth.add_ai_component: Fixup)

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.3 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.
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'.

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

local team = wesnoth.sides[1]
team.gold = team.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.set_side_id

(Version 1.13.7 and later only)

  • wesnoth.set_side_id(side, color, flag)

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

(Version 1.13.7 and later only)

  • wesnoth.clear_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 teams that can be used in a for-in loop.

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