Difference between revisions of "LuaWML/Sides"

From The Battle for Wesnoth Wiki
m (link to extant docs of this attributes)
(Add move notice)
 
(30 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 +
{{Template:LuaMove}}
 +
 
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 14: Line 12:
 
* '''objectives_changed''': boolean (read/write)
 
* '''objectives_changed''': boolean (read/write)
 
* '''team_name''': string (read/write)
 
* '''team_name''': string (read/write)
* '''controller''': string (read/write) :
+
* '''is_local''' {{DevFeature1.13|8}}: boolean (read). Whether the side is local. Careless use will cause OOS errors.
:''note: In networked multiplayer, the controller attribute is ambiguous. Be very careful or you have OOS errors.''
+
* '''controller''': string (read/write):
:{{DevFeature1.11|11}} The controller attribute has 6 possible values: human, network, ai, network_ai, null, idle.
+
:''note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you'll have OOS errors.''
 
 
: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.
 
 
 
: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.
+
: The only possible values are 'human', 'ai' or 'null'.
  
* '''fog''': boolean (read)
+
{{DevFeature1.13|8}} 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.
* '''shroud''': boolean (read)
+
* '''fog''': boolean (read {{DevFeature1.13|7}}/write)
* '''hidden''': boolean (read)
+
* '''shroud''': boolean (read {{DevFeature1.13|7}}/write)
** {{DevFeature1.11}} 1.11.8 and later implement read/write support for this field
+
* '''hidden''': boolean (read/write)
 
* '''name''': string (read)
 
* '''name''': string (read)
* '''color''': string (read) {{DevFeature1.11}}: also write
+
* '''faction''': {{DevFeature1.13|5}} id of the selected faction, string (multiplayer-only, read)
* '''recruit''': table of strings
+
* '''faction_name''': {{DevFeature1.13|5}} name of the selected faction, string (multiplayer-only, read)
* {{DevFeature1.11}} '''scroll_to_leader''': boolean (read/write)
+
* '''color''': string (read/write)
* {{DevFeature1.11}} '''village_support''': string (read/write)
+
* '''recruit''': table of strings (read/write)
* {{DevFeature1.11}} '''flag''': string (read)
+
* '''scroll_to_leader''': boolean (read/write)
* {{DevFeature1.11}} '''flag_icon''': string (read)
+
* '''village_support''': string (read/write)
* {{DevFeature1.11|15}} '''defeat_condition''': string (read/write) See description at [[SideWML]], [[ScenarioWML#Scenario_End_Conditions]]
+
* '''flag''': string (read {{DevFeature1.13|7}}/write) As of 1.14.0 this is not writable.
* {{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
+
* '''flag_icon''': string (read {{DevFeature1.13|7}}/write)
a side by setting it to false in a victory event.
+
* '''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''' {{DevFeature1.13|5}}: boolean (read/write)
 +
* '''suppress_end_turn_confirmation''' {{DevFeature1.13|7}}: boolean (read/write)
 +
* '''share_vision''' {{DevFeature1.13|7}}: string (read/write)
 +
* '''share_maps''' {{DevFeature1.13|7}}: boolean (read)
 +
* '''share_view''' {{DevFeature1.13|7}}: boolean (read)
 +
* '''num_units''' {{DevFeature1.13|7}}: integer (read)
 +
* '''num_villages''' {{DevFeature1.13|7}}: integer (read)
 +
* '''total_upkeep''' {{DevFeature1.13|7}}: integer (read)
 +
* '''expenses''' {{DevFeature1.13|7}}: integer (read)
 +
* '''net_income''' {{DevFeature1.13|7}}: integer (read)
 
* '''__cfg''': WML table (dump)
 
* '''__cfg''': WML table (dump)
  
 
The metatable of these proxy tables appears as '''"side"'''.
 
The metatable of these proxy tables appears as '''"side"'''.
  
  local team = wesnoth.sides[1]
+
  local side = wesnoth.sides[1]
  team.gold = team.gold + 50
+
  side.gold = side.gold + 50
 
  wesnoth.message(string.format("%d sides", #wesnoth.sides))
 
  wesnoth.message(string.format("%d sides", #wesnoth.sides))
  
 
==== wesnoth.get_sides ====
 
==== wesnoth.get_sides ====
  
Returns a table array containing proxy tables for these sides matching the passed [[StandardSideFilter]].
+
* '''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
 
  --set gold to 0 for all sides with a leader
 
  local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })
 
  local sides = wesnoth.get_sides({ {"has_unit", { canrecruit = true }} })
Line 56: Line 63:
  
 
==== wesnoth.get_village_owner ====
 
==== wesnoth.get_village_owner ====
 +
 +
* '''wesnoth.get_village_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 62: Line 71:
  
 
==== wesnoth.set_village_owner ====
 
==== 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.
 
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 69: Line 80:
  
 
==== 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 75: Line 88:
  
 
==== 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 81: Line 96:
  
 
==== 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)
 
  wesnoth.message(string.format("side 1 starts at (%u, %u)", loc[1], loc[2]))
 
  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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''wesnoth.switch_ai(''side'', ''file'')'''
 +
 +
Replaces a side's AI with the configuration from a specified file.
 +
 +
==== wesnoth.append_ai ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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 ====
 +
 +
{{DevFeature1.13|7}}
 +
 +
* '''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.
+
* '''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 team in helper.all_teams() do team.gold = 200 end
+
  for side in helper.all_teams() do side.gold = 200 end
  
 
[[Category: Lua Reference]]
 
[[Category: Lua Reference]]

Latest revision as of 13:31, 12 February 2021



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 may not be the same on all clients. Be very careful or you'll have OOS errors.
The only possible values are '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.

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
This page was last edited on 12 February 2021, at 13:31.