Difference between revisions of "LuaWML/Sides"

From The Battle for Wesnoth Wiki
(wesnoth.sides)
(Add move notice)
 
(9 intermediate revisions by 5 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.
  
Line 11: Line 13:
 
* '''team_name''': string (read/write)
 
* '''team_name''': string (read/write)
 
* '''is_local''' {{DevFeature1.13|8}}: boolean (read). Whether the side is local. Careless use will cause OOS errors.
 
* '''is_local''' {{DevFeature1.13|8}}: boolean (read). Whether the side is local. Careless use will cause OOS errors.
* '''controller''': string (read/write) :
+
* '''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.''
+
:''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 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.
+
: The only possible values are 'human', 'ai' or 'null'.
  
: This value can only be set to 'human', 'ai' or 'null'.
+
{{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)
 
* '''fog''': boolean (read {{DevFeature1.13|7}}/write)
 
* '''shroud''': boolean (read  {{DevFeature1.13|7}}/write)
 
* '''shroud''': boolean (read  {{DevFeature1.13|7}}/write)
Line 32: Line 29:
 
* '''scroll_to_leader''': boolean (read/write)
 
* '''scroll_to_leader''': boolean (read/write)
 
* '''village_support''': string (read/write)
 
* '''village_support''': string (read/write)
* '''flag''': string (read  {{DevFeature1.13|7}}/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)
 
* '''flag_icon''': string (read  {{DevFeature1.13|7}}/write)
 
* '''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]]
Line 106: Line 103:
 
  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 ====
 
==== wesnoth.set_side_id ====
Line 111: Line 125:
 
{{DevFeature1.13|7}}
 
{{DevFeature1.13|7}}
  
* '''wesnoth.set_side_id(''side'', ''color'', ''flag'')'''
+
* '''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.
 
Changes the visual identification of a side. Pass an empty string if you only want to change one of these two attributes.
Line 123: Line 137:
 
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.
 
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 ====
+
==== wesnoth.remove_shroud ====
  
 
{{DevFeature1.13|7}}
 
{{DevFeature1.13|7}}
  
* '''wesnoth.clear_shroud(''side'', ''shroud'')'''
+
* '''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.
 
Unshrouds the specified hexes. Hexes are specified as with place_shroud, except that a shroud_data string will not work.
Line 191: Line 205:
 
* '''helper.all_teams()'''
 
* '''helper.all_teams()'''
  
Returns an iterator over teams that can be used in a for-in loop.
+
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.