Difference between revisions of "LuaWML/Sides"

From The Battle for Wesnoth Wiki
(wesnoth.sides: side.recruit is a read/write table)
(Explicitly note how to call each function)
Line 41: Line 41:
  
 
==== wesnoth.get_sides ====
 
==== wesnoth.get_sides ====
 +
 +
* '''wesnoth.get_sides(''filter'')'''
  
 
Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].
 
Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].
Line 50: Line 52:
  
 
==== wesnoth.get_village_owner ====
 
==== wesnoth.get_village_owner ====
 +
 +
* '''wesnoth.get_villlag_owner(''x'', ''y'')'''
  
 
Returns the side that owns the village at the given location.
 
Returns the side that owns the village at the given location.
Line 56: Line 60:
  
 
==== wesnoth.set_village_owner ====
 
==== wesnoth.set_village_owner ====
 +
 +
* '''wesnoth.set_vilage_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.
 
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.
Line 63: Line 69:
  
 
==== wesnoth.is_enemy ====
 
==== wesnoth.is_enemy ====
 +
 +
* '''wesnoth.is_enemy(''side1'', ''side2'')'''
  
 
Returns true if side A is enemy of side B, false otherwise.
 
Returns true if side A is enemy of side B, false otherwise.
Line 69: Line 77:
  
 
==== wesnoth.match_side ====
 
==== wesnoth.match_side ====
 +
 +
* '''wesnoth.match_side(''side'', ''filter'')'''
  
 
Matches a side against a given [[StandardSideFilter]].
 
Matches a side against a given [[StandardSideFilter]].
Line 75: Line 85:
  
 
==== wesnoth.get_starting_location ====
 
==== wesnoth.get_starting_location ====
 +
 +
* '''wesnoth.get_starting_location(''side'')'''
 +
 +
Returns the starting location of the given side.
  
 
  local loc = wesnoth.get_starting_location(1)
 
  local loc = wesnoth.get_starting_location(1)
Line 80: Line 94:
  
 
==== helper.all_teams ====
 
==== helper.all_teams ====
 +
 +
* '''helper.all_teams()'''
  
 
Returns an iterator over teams that can be used in a for-in loop.
 
Returns an iterator over teams that can be used in a for-in loop.

Revision as of 18:27, 22 September 2015

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)
  • controller: string (read/write) :
note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you 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.
  • fog: boolean (read)
  • shroud: boolean (read)
  • hidden: boolean (read/write)
  • name: string (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)
  • flag_icon: string (read)
  • 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.
  • __cfg: WML table (dump)

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.

--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_villlag_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_vilage_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]))

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