Difference between revisions of "LuaWML/Sides"
(→wesnoth.sides) |
|||
Line 13: | Line 13: | ||
* '''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 is ambiguous (won't 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. | + | : The controller attribute has 6 possible values: human, network, ai, network_ai, null, idle. (Or less, see below.) |
: 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. | ||
Line 22: | Line 22: | ||
: This value can only be set to 'human', 'ai' or 'null'. | : This value can only be set to 'human', 'ai' or 'null'. | ||
+ | |||
+ | {{DevFeature1.13|8}} Both remote and local sides will appear as 'human'. Combine this value with 'is_local' to differentiate "network human" from "local human" if you need to. | ||
* '''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) |
Revision as of 16:06, 19 March 2018
This page describes the LuaWML functions and helpers for handling sides and villages.
Contents
- 1 wesnoth.sides
- 2 wesnoth.get_sides
- 3 wesnoth.get_village_owner
- 4 wesnoth.set_village_owner
- 5 wesnoth.is_enemy
- 6 wesnoth.match_side
- 7 wesnoth.get_starting_location
- 8 wesnoth.get_side_variable
- 9 wesnoth.set_side_variable
- 10 wesnoth.set_side_id
- 11 wesnoth.place_shroud
- 12 wesnoth.remove_shroud
- 13 wesnoth.is_fogged
- 14 wesnoth.is_shrouded
- 15 wesnoth.switch_ai
- 16 wesnoth.append_ai
- 17 wesnoth.add_ai_component
- 18 wesnoth.change_ai_component
- 19 wesnoth.delete_ai_component
- 20 helper.all_teams
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 is ambiguous (won't 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. (Or less, see below.)
- 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.
- This value can only be set to 'human', 'ai' or 'null'.
(Version 1.13.8 and later only) Both remote and local sides will appear as 'human'. Combine this value with 'is_local' to differentiate "network human" from "local human" if you need to.
- fog: boolean (read (Version 1.13.7 and later only)/write)
- shroud: boolean (read (Version 1.13.7 and later only)/write)
- hidden: boolean (read/write)
- name: string (read)
- faction: (Version 1.13.5 and later only) id of the selected faction, string (multiplayer-only, read)
- faction_name: (Version 1.13.5 and later only) 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 (Version 1.13.7 and later only)/write)
- flag_icon: string (read (Version 1.13.7 and later only)/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 (Version 1.13.5 and later only): boolean (read/write)
- suppress_end_turn_confirmation (Version 1.13.7 and later only): boolean (read/write)
- share_vision (Version 1.13.7 and later only): string (read/write)
- share_maps (Version 1.13.7 and later only): boolean (read)
- share_view (Version 1.13.7 and later only): boolean (read)
- num_units (Version 1.13.7 and later only): integer (read)
- num_villages (Version 1.13.7 and later only): integer (read)
- total_upkeep (Version 1.13.7 and later only): integer (read)
- expenses (Version 1.13.7 and later only): integer (read)
- net_income (Version 1.13.7 and later only): integer (read)
- __cfg: WML table (dump)
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, color, flag)
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