Difference between revisions of "LuaWML/Sides"

From The Battle for Wesnoth Wiki
(wesnoth.get_side)
(43 intermediate revisions by 15 users not shown)
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 ====
+
==== wesnoth.sides ====
  
Returns the team with given number.
+
This is not a function but a table indexed by side numbers. Its elements are proxy tables with these fields:
 
+
* '''side''': the side number
local team = wesnoth.get_side(1)
 
team.gold = team.gold + 50
 
 
 
Teams are proxy tables with the following fields:
 
* '''side''': the side number {{DevFeature1.9}}
 
 
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
 
* '''gold''', '''village_gold''', '''base_income''': integers (read/write)
 
* '''total_income''': integer (read only)
 
* '''total_income''': integer (read only)
Line 15: Line 10:
 
* '''objectives_changed''': boolean (read/write)
 
* '''objectives_changed''': boolean (read/write)
 
* '''team_name''': string (read/write)
 
* '''team_name''': string (read/write)
* '''controller''': string (read/write) {{DevFeature1.9}}
+
* '''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):
* '''fog''': boolean (read) {{DevFeature1.9}}
+
:''note: In networked multiplayer, the controller attribute may not be the same on all clients. Be very careful or you'll have OOS errors.''
* '''shroud''': boolean (read) {{DevFeature1.9}}
+
 
* '''hidden''': boolean (read) {{DevFeature1.9}}
+
: The only possible values are 'human', 'ai' or 'null'.
* '''name''': string (read) {{DevFeature1.9}}
+
 
* '''color''': string (read) {{DevFeature1.9}}
+
{{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.
 +
* '''fog''': boolean (read {{DevFeature1.13|7}}/write)
 +
* '''shroud''': boolean (read {{DevFeature1.13|7}}/write)
 +
* '''hidden''': boolean (read/write)
 +
* '''name''': string (read)
 +
* '''faction''': {{DevFeature1.13|5}} id of the selected faction, string (multiplayer-only, read)
 +
* '''faction_name''': {{DevFeature1.13|5}} 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  {{DevFeature1.13|7}}/write) As of 1.14.0 this is not writable.
 +
* '''flag_icon''': string (read {{DevFeature1.13|7}}/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''' {{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"'''.
  
==== wesnoth.sides ====
+
  local side = wesnoth.sides[1]
 
+
  side.gold = side.gold + 50
{{DevFeature1.9}}
 
 
 
This is not a function but a table indexed by side numbers. Its elements are the proxy tables returned by [[#wesnoth.get_side]].
 
 
 
  local team = wesnoth.sides[1]
 
  team.gold = team.gold + 50
 
 
  wesnoth.message(string.format("%d sides", #wesnoth.sides))
 
  wesnoth.message(string.format("%d sides", #wesnoth.sides))
  
 
==== wesnoth.get_sides ====
 
==== wesnoth.get_sides ====
  
{{DevFeature1.9}}
+
* '''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]]. 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 48: Line 61:
  
 
==== 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 55: Line 70:
 
==== wesnoth.set_village_owner ====
 
==== wesnoth.set_village_owner ====
  
Gives ownership of the village at the given location to the given side (or remove ownership if none).
+
* '''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.set_village_owner(12, 15, 1)
Line 61: Line 79:
 
==== wesnoth.is_enemy ====
 
==== wesnoth.is_enemy ====
  
{{DevFeature1.9}}
+
* '''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 68: Line 86:
  
 
==== wesnoth.match_side ====
 
==== wesnoth.match_side ====
{{DevFeature1.9}}
+
 
 +
* '''wesnoth.match_side(''side'', ''filter'')'''
  
 
Matches a side against a given [[StandardSideFilter]].
 
Matches a side against a given [[StandardSideFilter]].
Line 75: Line 94:
  
 
==== wesnoth.get_starting_location ====
 
==== wesnoth.get_starting_location ====
{{DevFeature1.9}}
+
 
 +
* '''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]]

Revision as of 19:15, 23 June 2018

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