Difference between revisions of "LuaWML/Sides"

From The Battle for Wesnoth Wiki
(wesnoth.sides)
(Remove DevFeature1.11)
Line 1: Line 1:
 
This page describes the [[LuaWML]] functions and helpers for handling sides and villages.
 
This page describes the [[LuaWML]] functions and helpers for handling sides and villages.
 
==== wesnoth.get_side ====
 
 
{{DevFeature1.11}}: This function is deprecated, use wesnoth.sides[i] instead of wesnoth.get_side(i).
 
  
 
==== wesnoth.sides ====
 
==== wesnoth.sides ====
Line 16: Line 12:
 
* '''controller''': string (read/write) :
 
* '''controller''': string (read/write) :
 
:''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''
 
:''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''
:{{DevFeature1.11|11}} The controller attribute has 6 possible values: human, network, ai, network_ai, null, idle.  
+
: The controller attribute has 6 possible values: human, network, ai, network_ai, null, idle.  
  
:In 1.11.11+, 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.  
+
: 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".
+
: 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.
+
: These values may be checked using lua, or the :controller command in game.
  
 
* '''fog''': boolean (read)
 
* '''fog''': boolean (read)
 
* '''shroud''': boolean (read)
 
* '''shroud''': boolean (read)
* '''hidden''': boolean (read)
+
* '''hidden''': boolean (read/write)
** {{DevFeature1.11}} 1.11.8 and later implement read/write support for this field
 
 
* '''name''': string (read)
 
* '''name''': string (read)
* '''color''': string (read) {{DevFeature1.11}}: also write
+
* '''color''': string (read/write)
 
* '''recruit''': table of strings
 
* '''recruit''': table of strings
* {{DevFeature1.11}} '''scroll_to_leader''': boolean (read/write)
+
* '''scroll_to_leader''': boolean (read/write)
* {{DevFeature1.11}} '''village_support''': string (read/write)
+
* '''village_support''': string (read/write)
* {{DevFeature1.11}} '''flag''': string (read)
+
* '''flag''': string (read)
* {{DevFeature1.11}} '''flag_icon''': string (read)
+
* '''flag_icon''': string (read)
* {{DevFeature1.11|15}} '''defeat_condition''': string (read/write) See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
+
* '''defeat_condition''': string (read/write) See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
* {{DevFeature1.11|15}} '''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.
+
* '''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)
 
* '''__cfg''': WML table (dump)
  

Revision as of 07:38, 17 April 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
  • 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

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

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

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

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

local enemy_flag = wesnoth.is_enemy(1, 3)

wesnoth.match_side

Matches a side against a given StandardSideFilter.

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

wesnoth.get_starting_location

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

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