Difference between revisions of "LuaWML/Sides"
(Explicitly note how to call each function) |
(Add move notice) |
||
(25 intermediate revisions by 9 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 10: | 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 | + | * '''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'. |
− | * '''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) |
+ | * '''shroud''': boolean (read {{DevFeature1.13|7}}/write) | ||
* '''hidden''': boolean (read/write) | * '''hidden''': boolean (read/write) | ||
* '''name''': string (read) | * '''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) | * '''color''': string (read/write) | ||
* '''recruit''': table of strings (read/write) | * '''recruit''': table of strings (read/write) | ||
* '''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) | + | * '''flag''': string (read {{DevFeature1.13|7}}/write) As of 1.14.0 this is not writable. |
− | * '''flag_icon''': string (read) | + | * '''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]] | ||
* '''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. | ||
+ | * '''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 | + | local side = wesnoth.sides[1] |
− | + | side.gold = side.gold + 50 | |
wesnoth.message(string.format("%d sides", #wesnoth.sides)) | wesnoth.message(string.format("%d sides", #wesnoth.sides)) | ||
Line 44: | Line 55: | ||
* '''wesnoth.get_sides(''filter'')''' | * '''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 53: | Line 64: | ||
==== wesnoth.get_village_owner ==== | ==== wesnoth.get_village_owner ==== | ||
− | * '''wesnoth. | + | * '''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 61: | Line 72: | ||
==== wesnoth.set_village_owner ==== | ==== wesnoth.set_village_owner ==== | ||
− | * '''wesnoth. | + | * '''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 92: | 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 ==== | ||
+ | |||
+ | {{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 ==== | ||
Line 97: | Line 205: | ||
* '''helper.all_teams()''' | * '''helper.all_teams()''' | ||
− | Returns an iterator over | + | 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 | + | 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.
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 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.
- 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) As of 1.14.0 this is not writable.
- 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, 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