Difference between revisions of "LuaWML"

From The Battle for Wesnoth Wiki
m (Interface to the engine and helper functions)
(WML table: Clean up so that all examples use recommended format, leaving only a brief note on the old, deprecated format)
 
(20 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
== The '''[lua]''' tag ==
 
== The '''[lua]''' tag ==
  
This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.3] language.
+
This tag is a part of [[ActionWML]], thus can be used inside [event] and at other places where [[ActionWML]] can be used. It makes it possible to write actions with the [http://www.lua.org Lua 5.4] language.
  
It is also possible to put this tag inside a [scenario] [[ScenarioWML]], those tags will be executed immediately when the lua engine loads which is even before the scenario preload event is fired.
+
{{DevFeature1.13|?}} In addition to ActionWML, the '''[lua]''' tag may now be used in several other places. It can be placed at toplevel (outside of any tag) to make code that loads no matter what. ('''Note''': This should usually be avoided, unless you're making a [[CoreWML|custom core]].) It can be placed in any [[AddonsWML|addon module tag]], such as '''[scenario]''', '''[era]''', or '''[resource]''', to load code when the scenario boots up. Lua code placed in either of these places is executed even earlier than a '''preload''' event. And finally, it can now be used as [[ConditionalActionsWML#.5Blua.5D|ConditionalWML]]. In this case, the code must return either '''true''' or '''false''' to determine the outcome of the condition.
  
[lua] is now also allowed in [era], [modification] and [resource], those [lua] tags are then copied into the [scenario]/[multiplayer] when it is played just like [event]s inside [era] or [modification]
+
The '''[lua]''' tag can contain the following contents:
  
The tag supports only the '''code''' key, which is a string containing the Lua scripts. Since Lua makes usage of the quotes and the { and } symbols, it is certainly wise to enclose the script between stronger quotes, as they prevent the preprocessor from performing macro expansion and tokenization.
+
* '''code''': A string containing the Lua script.
 +
* '''name''': An arbitrary string used to identify this tag in error messages.
 +
* '''[args]''': Arbitrary data that will be passed to the Lua script as its only argument. It can be accessed in the Lua code via the special variadic variable <code>...</code>.
 +
 
 +
Since Lua makes usage of double quotes and curly braces, it is recommended to enclose the script between [[SyntaxWML#macro-protected-string|stronger quotes]] (as shown in the below example), as they prevent the preprocessor from performing macro expansion and tokenization. This is not strictly required, however. Example:
  
 
<syntaxhighlight lang='wml'>
 
<syntaxhighlight lang='wml'>
 
  [lua]
 
  [lua]
     code = << wesnoth.message "Hello World!" >>
+
     code = << wesnoth.interface.add_chat_message "Hello World!" >>
 
  [/lua]
 
  [/lua]
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The Lua kernel can also be accessed from the [[CommandMode|command mode]]:
+
The '''[args]''' tag is useful if you need to pass WML variables or macro expansions into the code.
 
 
:lua local u = wesnoth.get_units({ id = "Konrad" })[1]; u.moves = 5
 
 
 
The '''[args]''' sub-tag can be used to pass a WML object to the script via its variadic local variable "'''...'''".
 
  
 
<syntaxhighlight lang='wml'>
 
<syntaxhighlight lang='wml'>
 
  [lua]
 
  [lua]
     code = << local t = ...; wesnoth.message(tostring(t.text)) >>
+
     code = << local t = ...; wesnoth.interface.add_chat_message(tostring(t.text)) >>
 
     [args]
 
     [args]
         text = _ "Hello world!"
+
         text = _ "Hello $unit.name!"
 
     [/args]
 
     [/args]
 
  [/lua]
 
  [/lua]
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
When code in a '''[lua]''' tag has errors, it's often hard to find the location of the error because the line numbers are not within the code string and not the entire file. To help with this, you can set the '''name''' key. When an error is reported, the value of '''name''' will be shown as if it were the filename, allowing you to more easily locate the tag that raised it.
 +
 +
== Testing out Lua in-game ==
 +
 +
The Lua kernel can also be accessed from [[CommandMode|command mode]]:
 +
 +
:lua local u = wesnoth.units.find_on_map{ id = "Konrad" }[1]; u.moves = 5
 +
 +
In addition, if you enable debug mode, you can access a <acronym title="Read, evaluate, print loop">REPL</acronym> console by pressing the Lua Console hotkey, which is bound to ~ by default. You can enable debug mode by using the <tt>:debug</tt> command, or by running Wesnoth with the <tt>--debug</tt> command-line argument. In the latter case, the Lua Console can even be summoned from the main menu screen.
 +
 +
You can use the Lua console to examine anything about the Lua environment and execute any Lua code you wish. It is recommended to use command mode to execute Lua that affects the map however, for example moving a unit. In the Lua Console you can use a special [[LuaAPI/wesnoth#wesnoth.print_attributes|dir()]] function to examine the contents of objects and modules. You can also access a special <tt>_</tt> variable which contains the result of the previous command executed in the console. Global variables assigned in the Lua console are not visible to scenario code, but remain between invocations of the console within a single game, as long as you don't reload. If you need to assign a global variable that is visible outside of the console, you can do so via the special variable <tt>_G</tt>.
  
 
== Global environment ==
 
== Global environment ==
  
All the Lua scripts of a scenario share the same global environment (aka Lua state). Unlike other parts of the configurable gamestate the Lua state is not stored in savefiles, thus [lua] tags in [scenario] are executed not only before the scenario starts but also each time the game is loaded. Funtions defined in [lua] tags in [scenario] can be used in all [lua] tags in [event]s.
+
All the Lua scripts of a scenario share the same global environment (aka Lua state). Unlike other parts of the configurable gamestate the Lua state is not stored in savefiles, thus [lua] tags in [scenario] are executed not only before the scenario starts but also each time the game is loaded. Functions defined in [lua] tags in [scenario] can be used in all [lua] tags in [event]s.
  
 
<syntaxhighlight lang='wml'>
 
<syntaxhighlight lang='wml'>
Line 42: Line 54:
 
             function narrator(t)
 
             function narrator(t)
 
                 -- Behave like the [message] tag.
 
                 -- Behave like the [message] tag.
                 wesnoth.fire("message",
+
                 wml.fire("message",
 
                   { speaker = "narrator", message = t.sentence })
 
                   { speaker = "narrator", message = t.sentence })
 
             end
 
             end
Line 77: Line 89:
 
             function wesnoth.wml_actions.narrator(t)
 
             function wesnoth.wml_actions.narrator(t)
 
                 -- Behave like the [message] tag.
 
                 -- Behave like the [message] tag.
                 wesnoth.fire("message",
+
                 wml.fire("message",
 
                   { speaker = "narrator", message = t.sentence })
 
                   { speaker = "narrator", message = t.sentence })
 
             end
 
             end
Line 97: Line 109:
 
The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea. The only time assigning global variables (including function definitions) makes sense is in a [lua] block directly in [scenario] or during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.
 
The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea. The only time assigning global variables (including function definitions) makes sense is in a [lua] block directly in [scenario] or during a [[EventWML#Predefined 'name' Key Values|preload]] event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.
  
The global environment initially contains the following modules: [http://www.lua.org/manual/5.3/manual.html#6.1 basic] (no name), [http://www.lua.org/manual/5.3/manual.html#6.4 string], [http://www.lua.org/manual/5.3/manual.html#6.6 table], and [http://www.lua.org/manual/5.3/manual.html#6.7 math]. A '''wesnoth''' module is also available, it provides access to the [[#Interface to the C++ engine|C++ engine]]. Additionally, the functions clock, date, time and difftime from the [http://www.lua.org/manual/5.3/manual.html#6.9 os] library (keep in mind that they aren't multiplayer- and replay-safe), as well as traceback from the [http://www.lua.org/manual/5.3/manual.html#6.10 debug] library are also available.
+
The global environment initially contains the following built-in modules: '''string''', '''table''', and '''math'''. A '''wesnoth''' module is also available, which provides access to the C++ game engine. Additionally, the functions '''clock''', '''date''', '''time''' and '''difftime''' from the '''os''' module are also available (but keep in mind that they aren't multiplayer- and replay-safe), as well as '''traceback''' from the '''debug''' module. There are also a few other built-in modules specific to Wesnoth – for full details, see [[LuaAPI]].
  
 
At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.
 
At the start of a script, the variadic local variable '''...''' (three dots) is a proxy table representing [[#Encoding WML objects into Lua tables|WML data]]. This table is the content of the '''[args]''' sub-tag of the '''[lua]''' tag, if any.
Line 190: Line 202:
  
 
whether the variable ''wml.variables["target_hex"]'' matches the event parameters. Since ''wml.variables'' is not a local variable, it is taken from the global environment. Usually, variables from the global environment are not persistent but the wesnoth engine maps the variable wml.variables to the storage of WML variables.
 
whether the variable ''wml.variables["target_hex"]'' matches the event parameters. Since ''wml.variables'' is not a local variable, it is taken from the global environment. Usually, variables from the global environment are not persistent but the wesnoth engine maps the variable wml.variables to the storage of WML variables.
 
Without using wml.variables, the conditional would have been written
 
 
<syntaxhighlight lang='lua'>
 
if wesnoth.get_variable("target_hex.is_set") and
 
    (event_data.x1 ~= wesnoth.get_variable("target_hex.x") or event_data.y1 ~= wesnoth.get_variable("target_hex.y")
 
</syntaxhighlight>
 
  
 
The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.
 
The body of the conditional then performs the [[InterfaceActionsWML#Other interface tags|[redraw]]] action.
Line 210: Line 215:
 
     [lua]
 
     [lua]
 
         code = <<
 
         code = <<
             H = wesnoth.require "lua/helper.lua"
+
             H = wesnoth.require "helper"
 
             W = H.set_wml_action_metatable {}
 
             W = H.set_wml_action_metatable {}
 
         >>
 
         >>
Line 221: Line 226:
  
 
<syntaxhighlight lang='lua'>
 
<syntaxhighlight lang='lua'>
wesnoth.fire("redraw")
+
wml.fire("redraw")
 
</syntaxhighlight>
 
</syntaxhighlight>
 
or
 
or
Line 249: Line 254:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483].
+
<!-- A longer translation of the tutorial is available at [https://gna.org/patch/download.php?file_id=5483]. -->
 
 
== Interface to the engine and helper functions ==
 
 
 
{{Template:LuaMove}}
 
 
 
Functionalities of the game engine are available through the functions contained in the '''wesnoth''' global table. Some of these functions return proxy tables. Writes to fields marked "read-only" are ignored. The '''__cfg''' fields return plain tables; in particular, writes do not modify the original object, and reads return the values from the time the dump was performed.
 
 
 
Some helper functions are provided by the '''lua/helper.lua''' library. They are stored inside a table that is returned when loading the library with [[LuaWML:Files#wesnoth.require|wesnoth.require]].
 
 
 
<syntaxhighlight lang='lua'>
 
helper = wesnoth.require "lua/helper.lua"
 
</syntaxhighlight>
 
 
 
=== WML variables ===
 
 
 
* [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]]
 
* [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]]
 
* [[LuaWML:Variables#wesnoth.get_all_vars|wesnoth.get_all_vars]] {{DevFeature1.13|0}}
 
* [[LuaWML:Variables#wesnoth.wml_matches_filter|wesnoth.wml_matches_filter]] {{DevFeature1.13|8}}
 
* [[LuaWML:Variables#helper.set_wml_var_metatable|helper.set_wml_var_metatable]]
 
* [[LuaWML:Variables#helper.get_child|helper.get_child]]
 
* [[LuaWML:Variables#helper.get_nth_child|helper.get_nth_child]] {{DevFeature1.13|2}}
 
* [[LuaWML:Variables#helper.child_count|helper.child_count]] {{DevFeature1.13|2}}
 
* [[LuaWML:Variables#helper.child_range|helper.child_range]]
 
* [[LuaWML:Variables#helper.child_array|helper.child_array]] {{DevFeature1.13|2}}
 
* [[LuaWML:Variables#helper.get_variable_array|helper.get_variable_array]]
 
* [[LuaWML:Variables#helper.get_variable_proxy_array|helper.get_variable_proxy_array]]
 
* [[LuaWML:Variables#helper.set_variable_array|helper.set_variable_array]]
 
 
 
=== Events and WML actions ===
 
 
 
* [[LuaWML:Events#wesnoth.fire|wesnoth.fire]]
 
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]]
 
* [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_conditionals]] {{DevFeature1.13|0}}
 
* [[LuaWML:Events#wesnoth.game_events|wesnoth.game_events]]
 
* [[LuaWML:Events#wesnoth.persistent_tags|wesnoth.persistent_tags]] {{DevFeature1.13|12}}
 
* [[LuaWML:Events#wesnoth.fire_event|wesnoth.fire_event]]
 
* [[LuaWML:Events#wesnoth.fire_event_by_id|wesnoth.fire_event_by_id]] {{DevFeature1.13|6}}
 
* [[LuaWML:Events#wesnoth.add_event_handler|wesnoth.add_event_handler]] {{DevFeature1.13|0}}
 
* [[LuaWML:Events#wesnoth.remove_event_handler|wesnoth.remove_event_handler]] {{DevFeature1.13|0}}
 
* [[LuaWML:Events#wesnoth.eval_conditional|wesnoth.eval_conditional]]
 
* [[LuaWML:Events#wesnoth.tovconfig|wesnoth.tovconfig]]
 
* [[LuaWML:Events#helper.set_wml_action_metatable|helper.set_wml_action_metatable]]
 
* [[LuaWML:Events#helper.wml_error|helper.wml_error]]
 
* [[LuaWML:Events#helper.literal|helper.literal]]
 
* [[LuaWML:Events#helper.parsed|helper.parsed]]
 
* [[LuaWML:Events#helper.shallow_literal|helper.shallow_literal]]
 
* [[LuaWML:Events#helper.shallow_parsed|helper.shallow_parsed]]
 
* [[LuaWML:Events#on_event.lua|on_event.on_event]] {{DevFeature1.13|6}}
 
 
 
=== User interface ===
 
* [[LuaWML:Display#wesnoth.get_viewing_side|wesnoth.get_viewing_side]] {{DevFeature1.13|?}}
 
* [[LuaWML:Display#wesnoth.message|wesnoth.message]]
 
* [[LuaWML:Display#wesnoth.clear_messages|wesnoth.clear_messages]]
 
* [[LuaWML:Display#wesnoth.textdomain|wesnoth.textdomain]]
 
* [[LuaWML:Display#wesnoth.delay|wesnoth.delay]]
 
* [[LuaWML:Display#wesnoth.float_label|wesnoth.float_label]]
 
* [[LuaWML:Display#wesnoth.select_unit|wesnoth.select_hex]]
 
* [[LuaWML:Display#wesnoth.select_unit|wesnoth.select_unit]]
 
* [[LuaWML:Display#wesnoth.highlight_hex|wesnoth.highlight_hex]]
 
* [[LuaWML:Display#wesnoth.deselect_hex|wesnoth.deselect_hex]] {{DevFeature1.13|2}}
 
* [[LuaWML:Display#wesnoth.scroll_to_tile|wesnoth.scroll_to_tile]]
 
* [[LuaWML:Display#wesnoth.lock_view|wesnoth.lock_view]]
 
* [[LuaWML:Display#wesnoth.view_locked|wesnoth.view_locked]]
 
* [[LuaWML:Display#wesnoth.play_sound|wesnoth.play_sound]]
 
* [[LuaWML:Display#wesnoth.set_music|wesnoth.set_music]]
 
* [[LuaWML:Display#wesnoth.music_list|wesnoth.music_list]] {{DevFeature1.13|8}}
 
* [[LuaWML:Display#wesnoth.sound_volume|wesnoth.sound_volume]] {{DevFeature1.13|8}}
 
* [[LuaWML:Display#wesnoth.show_message_dialog|wesnoth.show_message_dialog]] {{DevFeature1.13|2}}
 
* [[LuaWML:Display#wesnoth.show_popup_dialog|wesnoth.show_popup_dialog]] {{DevFeature1.13|2}}
 
* [[LuaWML:Display#wesnoth.show_story|wesnoth.show_story]] {{DevFeature1.13|8}}
 
* [[LuaWML:Display#wesnoth.show_message_box|wesnoth.show_message_box]] {{DevFeature1.13|8}}
 
* [[LuaWML:Display#wesnoth.show_menu|wesnoth.show_menu]] {{DevFeature1.13|8}}
 
* [[LuaWML:Display#wesnoth.show_message_box|wesnoth.alert]] {{DevFeature1.13|8}}
 
* [[LuaWML:Display#wesnoth.show_message_box|wesnoth.confirm]] {{DevFeature1.13|8}}
 
* [[LuaWML:Display#wesnoth.show_dialog|wesnoth.show_dialog]]
 
* [[LuaWML:Display#wesnoth.set_dialog_value|wesnoth.set_dialog_value]]
 
* [[LuaWML:Display#wesnoth.get_dialog_value|wesnoth.get_dialog_value]]
 
* [[LuaWML:Display#wesnoth.set_dialog_active|wesnoth.set_dialog_active]]
 
* [[LuaWML:Display#wesnoth.set_dialog_callback|wesnoth.set_dialog_callback]]
 
* [[LuaWML:Display#wesnoth.set_dialog_markup|wesnoth.set_dialog_markup]]
 
* [[LuaWML:Display#wesnoth.set_dialog_focus|wesnoth.set_dialog_focus]] {{DevFeature1.13|2}}
 
* [[LuaWML:Display#wesnoth.set_dialog_visible|wesnoth.set_dialog_visible]] {{DevFeature1.13|2}}
 
* [[LuaWML:Display#wesnoth.set_dialog_canvas|wesnoth.set_dialog_canvas]]
 
* [[LuaWML:Display#wesnoth.add_dialog_tree_node|wesnoth.add_dialog_tree_node]] {{DevFeature1.13|0}}
 
* [[LuaWML:Display#wesnoth.remove_dialog_item|wesnoth.remove_dialog_item]] {{DevFeature1.13|1}}
 
* [[LuaWML:Display#wesnoth.get_displayed_unit|wesnoth.get_displayed_unit]]
 
* [[LuaWML:Display#wesnoth.theme_items|wesnoth.theme_items]]
 
* [[LuaWML:Display#helper.get_user_choice|helper.get_user_choice]]
 
* [[LuaWML:Display#wesnoth.is_skipping_messages|wesnoth.is_skipping_messages]] {{DevFeature1.13|2}}
 
* [[LuaWML:Display#wesnoth.skip_messages|wesnoth.skip_messages]] {{DevFeature1.13|2}}
 
* [[LuaWML:Display#wesnoth.log|wesnoth.log]] {{DevFeature1.13|5}}
 
* [[LuaWML:Display#wesnoth.zoom|wesnoth.zoom]] {{DevFeature1.13|8}}
 
 
 
=== Map and terrains ===
 
 
 
* [[LuaWML:Tiles#wesnoth.get_map_size|wesnoth.get_map_size]]
 
* [[LuaWML:Tiles#wesnoth.get_terrain|wesnoth.get_terrain]]
 
* [[LuaWML:Tiles#wesnoth.set_terrain|wesnoth.set_terrain]]
 
* [[LuaWML:Tiles#wesnoth.get_terrain_info|wesnoth.get_terrain_info]]
 
* [[LuaWML:Tiles#wesnoth.get_selected_tile|wesnoth.get_selected_tile]]
 
* [[LuaWML:Tiles#wesnoth.get_locations|wesnoth.get_locations]]
 
* [[LuaWML:Tiles#wesnoth.get_villages|wesnoth.get_villages]]
 
* [[LuaWML:Tiles#wesnoth.match_location|wesnoth.match_location]]
 
* [[LuaWML:Tiles#wesnoth.add_tile_overlay|wesnoth.add_tile_overlay]]
 
* [[LuaWML:Tiles#wesnoth.remove_tile_overlay|wesnoth.remove_tile_overlay]]
 
* [[LuaWML:Tiles#wesnoth.add_fog|wesnoth.add_fog]] {{DevFeature1.13|5}}
 
* [[LuaWML:Tiles#wesnoth.remove_fog|wesnoth.remove_fog]] {{DevFeature1.13|5}}
 
* [[LuaWML:Tiles#wesnoth.add_sound_source|wesnoth.add_sound_source]] {{DevFeature1.13|5}}
 
* [[LuaWML:Tiles#wesnoth.remove_sound_source|wesnoth.remove_sound_source]] {{DevFeature1.13|5}}
 
* [[LuaWML:Tiles#wesnoth.get_sound_source|wesnoth.get_sound_source]] {{DevFeature1.13|5}}
 
* [[LuaWML:Tiles#wesnoth.map.get_direction|wesnoth.map.get_direction]] {{DevFeature1.13|8}}
 
* [[LuaWML:Tiles#wesnoth.map.get_relative_dir|wesnoth.map.get_relative_dir]] {{DevFeature1.13|8}}
 
* [[LuaWML:Tiles#wesnoth.map.rotate_right_around_center|wesnoth.map.rotate_right_around_center]] {{DevFeature1.13|8}}
 
* [[LuaWML:Tiles#wesnoth.map.get_adjacent_tiles|wesnoth.map.get_adjacent_tiles]] {{DevFeature1.13|8}}
 
* [[LuaWML:Tiles#wesnoth.map.tiles_adjacent|wesnoth.map.tiles_adjacent]] {{DevFeature1.13|8}}
 
* [[LuaWML:Tiles#wesnoth.map.distance_between|wesnoth.map.distance_between]] {{DevFeature1.13|8}}
 
* [[LuaWML:Tiles#wesnoth.label|wesnoth.label]] {{DevFeature1.13|0}}
 
* [[LuaWML:Tiles#wesnoth.special_locations|wesnoth.special_locations]] {{DevFeature1.13|12}}
 
* [[LuaWML:Tiles#items.place_image|items.place_image]]
 
* [[LuaWML:Tiles#items.place_halo|items.place_halo]]
 
* [[LuaWML:Tiles#items.remove|items.remove]]
 
 
 
=== Time of day schedule ===
 
 
 
* [[LuaWML:Time#wesnoth.get_time_of_day|wesnoth.get_time_of_day]]
 
* [[LuaWML:Time#wesnoth.add_time_area|wesnoth.add_time_area]] {{DevFeature1.13|0}}
 
* [[LuaWML:Time#wesnoth.remove_time_area|wesnoth.remove_time_area]] {{DevFeature1.13|0}}
 
* [[LuaWML:Time#wesnoth.get_max_liminal_bonus|wesnoth.get_max_liminal_bonus]] {{DevFeature1.15|4}}
 
 
 
=== Units ===
 
 
 
* [[LuaWML:Units#wesnoth.get_units|wesnoth.get_units]]
 
* [[LuaWML:Units#wesnoth.get_unit|wesnoth.get_unit]]
 
* [[LuaWML:Units#wesnoth.match_unit|wesnoth.match_unit]]
 
* [[LuaWML:Units#wesnoth.put_unit|wesnoth.put_unit]]
 
* [[LuaWML:Units#wesnoth.erase_unit|wesnoth.erase_unit]] {{DevFeature1.13|2}}
 
* [[LuaWML:Units#wesnoth.get_recall_units|wesnoth.get_recall_units]]
 
* [[LuaWML:Units#wesnoth.put_recall_unit|wesnoth.put_recall_unit]]
 
* [[LuaWML:Units#wesnoth.create_unit|wesnoth.create_unit]]
 
* [[LuaWML:Units#wesnoth.copy_unit|wesnoth.copy_unit]]
 
* [[LuaWML:Units#wesnoth.extract_unit|wesnoth.extract_unit]]
 
* [[LuaWML:Units#wesnoth.add_modification|wesnoth.add_modification]]
 
* [[LuaWML:Units#wesnoth.remove_modifications|wesnoth.remove_modifications]] {{DevFeature1.13|?}}
 
* [[LuaWML:Units#wesnoth.unit_resistance|wesnoth.unit_resistance]]
 
* [[LuaWML:Units#wesnoth.unit_defense|wesnoth.unit_defense]]
 
* [[LuaWML:Units#wesnoth.unit_movement_cost|wesnoth.unit_movement_cost]]
 
* [[LuaWML:Units#wesnoth.unit_vision_cost|wesnoth.unit_vision_cost]]
 
* [[LuaWML:Units#wesnoth.unit_jamming_cost|wesnoth.unit_jamming_cost]]
 
* [[LuaWML:Units#wesnoth.unit_ability|wesnoth.unit_ability]]
 
* [[LuaWML:Units#wesnoth.unit_types|wesnoth.unit_types]]
 
* [[LuaWML:Units#wesnoth.races|wesnoth.races]]
 
* [[LuaWML:Units#wesnoth.get_traits|wesnoth.get_traits]]
 
* [[LuaWML:Units#wesnoth.advance_unit|wesnoth.advance_unit]] {{DevFeature1.13|?}}
 
* [[LuaWML:Units#wesnoth.add_known_unit|wesnoth.add_known_unit]] {{DevFeature1.13|?}}
 
* [[LuaWML:Units#wesnoth.simulate_combat|wesnoth.simulate_combat]]
 
* [[LuaWML:Units#wesnoth.transform_unit|wesnoth.transform_unit]]
 
* [[LuaWML:Units#wesnoth.create_animator|wesnoth.create_animator]] {{DevFeature1.13|7}}
 
* [[LuaWML:Units#wesnoth.effects|wesnoth.effects]] {{DevFeature1.13|2}}
 
 
 
=== Sides ===
 
 
 
* [[LuaWML:Sides#wesnoth.sides|wesnoth.sides]]
 
* [[LuaWML:Sides#wesnoth.get_sides|wesnoth.get_sides]]
 
* [[LuaWML:Sides#wesnoth.get_village_owner|wesnoth.get_village_owner]]
 
* [[LuaWML:Sides#wesnoth.set_village_owner|wesnoth.set_village_owner]]
 
* [[LuaWML:Sides#wesnoth.is_enemy|wesnoth.is_enemy]]
 
* [[LuaWML:Sides#wesnoth.match_side|wesnoth.match_side]]
 
* [[LuaWML:Sides#wesnoth.get_starting_location|wesnoth.get_starting_location]]
 
* [[LuaWML:Sides#wesnoth.set_side_id|wesnoth.set_side_id]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.place_shroud|wesnoth.place_shroud]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.remove_shroud|wesnoth.remove_shroud]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.is_fogged|wesnoth.is_fogged]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.is_shrouded|wesnoth.is_shrouded]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.switch_ai|wesnoth.switch_ai]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.append_ai|wesnoth.append_ai]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.add_ai_component|wesnoth.add_ai_component]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.change_ai_component|wesnoth.change_ai_component]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#wesnoth.delete_ai_component|wesnoth.delete_ai_component]] {{DevFeature1.13|7}}
 
* [[LuaWML:Sides#helper.all_teams|helper.all_teams]]
 
* [[LuaWML:Sides#helper.get_side_variable|helper.get_side_variable]] {{DevFeature1.13|?}}
 
* [[LuaWML:Sides#helper.set_side_variable|helper.set_side_variable]] {{DevFeature1.13|?}}
 
 
 
=== Pathfinder ===
 
 
 
* [[LuaWML:Pathfinder#wesnoth.find_path|wesnoth.find_path]]
 
* [[LuaWML:Pathfinder#wesnoth.find_vacant_tile|wesnoth.find_vacant_tile]]
 
* [[LuaWML:Pathfinder#wesnoth.find_reach|wesnoth.find_reach]]
 
* [[LuaWML:Pathfinder#wesnoth.find_cost_map|wesnoth.find_cost_map]]
 
* [[LuaWML:Pathfinder#helper.distance_between|helper.distance_between]]
 
* [[LuaWML:Pathfinder#helper.adjacent_tiles|helper.adjacent_tiles]]
 
 
 
=== Lua files ===
 
 
 
* [[LuaWML:Files#wesnoth.dofile|wesnoth.dofile]]
 
* [[LuaWML:Files#wesnoth.require|wesnoth.require]]
 
* [[LuaWML:Files#wesnoth.have_file|wesnoth.have_file]] {{DevFeature1.13|5}}
 
* [[LuaWML:Files#wesnoth.read_file|wesnoth.read_file]] {{DevFeature1.13|5}}
 
 
 
=== Location sets ===
 
 
 
* [[LuaWML:Location_set#location_set.create|location_set.create]]
 
* [[LuaWML:Location_set#location_set.of_pairs|location_set.of_pairs]]
 
* [[LuaWML:Location_set#location_set.of_wml_var|location_set.of_wml_var]]
 
* [[LuaWML:Location_set#location_set:empty|location_set:empty]]
 
* [[LuaWML:Location_set#location_set:size|location_set:size]]
 
* [[LuaWML:Location_set#location_set:clear|location_set:clear]]
 
* [[LuaWML:Location_set#location_set:get|location_set:get]]
 
* [[LuaWML:Location_set#location_set:insert|location_set:insert]]
 
* [[LuaWML:Location_set#location_set:remove|location_set:remove]]
 
* [[LuaWML:Location_set#location_set:of_pairs|location_set:of_pairs]]
 
* [[LuaWML:Location_set#location_set:of_wml_var|location_set:of_wml_var]]
 
* [[LuaWML:Location_set#location_set:to_pairs|location_set:to_pairs]]
 
* [[LuaWML:Location_set#location_set:to_stable_pairs|location_set:to_stable_pairs]]
 
* [[LuaWML:Location_set#location_set:to_wml_var|location_set:to_wml_var]]
 
* [[LuaWML:Location_set#location_set:union|location_set:union]]
 
* [[LuaWML:Location_set#location_set:inter|location_set:inter]]
 
* [[LuaWML:Location_set#location_set:iter|location_set:iter]]
 
* [[LuaWML:Location_set#location_set:stable_iter|location_set:stable_iter]]
 
* [[LuaWML:Location_set#location_set:filter|location_set:filter]]
 
* [[LuaWML:Location_set#location_set:union_merge|location_set:union_merge]]
 
* [[LuaWML:Location_set#location_set:inter_merge|location_set:inter_merge]]
 
 
 
=== Miscellaneous ===
 
 
 
* [[LuaWML:Misc#wesnoth.game_config|wesnoth.game_config]]
 
* [[LuaWML:Misc#wesnoth.get_era|wesnoth.get_era]]
 
* [[LuaWML:Misc#wesnoth.current|wesnoth.current]]
 
* [[LuaWML:Misc#wesnoth.synchronize_choice|wesnoth.synchronize_choice]]
 
* [[LuaWML:Misc#wesnoth.synchronize_choices|wesnoth.synchronize_choices]] {{DevFeature1.13|?}}
 
* [[LuaWML:Misc#wesnoth.unsynced|wesnoth.unsynced]] {{DevFeature1.13|?}}
 
* [[LuaWML:Misc#wesnoth.get_image_size|wesnoth.get_image_size]]
 
* [[LuaWML:Misc#wesnoth.compare_versions|wesnoth.compare_versions]]
 
* [[LuaWML:Misc#wesnoth.have_file|wesnoth.have_file]]
 
* [[LuaWML:Misc#wesnoth.debug|wesnoth.debug]]
 
* [[LuaWML:Misc#wesnoth.get_time_stamp|wesnoth.get_time_stamp]]
 
* [[LuaWML:Misc#wesnoth.random|wesnoth.random]]  {{DevFeature1.13|2}}
 
* [[LuaWML:Misc#wesnoth.eval_formula|wesnoth.eval_formula]] {{DevFeature1.13|5}}
 
* [[LuaWML:Misc#wesnoth.compile_formula|wesnoth.compile_formula]] {{DevFeature1.13|5}}
 
* [[LuaWML:Misc#wesnoth.name_generator|wesnoth.name_generator]] {{DevFeature1.13|5}}
 
* [[LuaWML:Misc#wesnoth.set_next_scenario|wesnoth.set_next_scenario]] {{DevFeature1.13|5}}
 
* [[LuaWML:Misc#wesnoth.format|wesnoth.format]] {{DevFeature1.13|8}}
 
* [[LuaWML:Misc#wesnoth.format_conjunct_list|wesnoth.format_conjunct_list]] {{DevFeature1.13|8}}
 
* [[LuaWML:Misc#wesnoth.format_disjunct_list|wesnoth.format_disjunct_list]] {{DevFeature1.13|8}}
 
* [[LuaWML:Misc#wesnoth.wesnoth.end_turn|wesnoth.end_turn]] {{DevFeature1.13|?}}
 
* [[LuaWML:Misc#wml.tag|wml.tag]]
 
* [[LuaWML:Misc#helper.modify_unit|helper.modify_unit]]
 
* [[LuaWML:Misc#helper.move_unit_fake|helper.move_unit_fake]]
 
* [[LuaWML:Misc#helper.rand|helper.rand]]
 
* [[LuaWML:Misc#helper.round|helper.round]]
 
* [[LuaWML:Misc#helper.shuffle|helper.shuffle]]
 
 
 
=== Functions that should not be used ===
 
 
 
If you take a look at Wesnoth's own lua files, you might find some undocumented functions use in the implementations of WML tags. Where possible, you should avoid using them, as they might be changed or removed with no compatibility for further releases. Instead, use the corresponding wml tags (in lua you can use <tt>wesnoth.wml_actions.tag_name(cfg)</tt>, though keep in mind that this won't substitute variables in the config).
 
 
 
If uncertain whether an undocumented feature is safe to use, ask on the forums, Discord, or IRC. It may turn out that someone simply forgot to add it to the wiki.
 
 
 
* wesnoth.redraw
 
* wesnoth.set_menu_item
 
* wesnoth.clear_menu_item
 
* wesnoth.modify_ai
 
* wesnoth.print
 
* wesnoth.end_level
 
  
 
== Encoding WML objects into Lua tables ==
 
== Encoding WML objects into Lua tables ==
  
Function [[LuaWML:Events#wesnoth.fire|wesnoth.fire]] expects a table representing a WML object as its second argument (if needed). Function [[LuaWML:Variables#wesnoth.set_variable|wesnoth.set_variable]] allows to modify whole WML objects, again by passing it a table. Function [[LuaWML:Variables#wesnoth.get_variable|wesnoth.get_variable]] transforms a WML object into a table, if its second argument is not set to ''true''. All these tables have the same format.
+
=== WML table ===
 +
Many functions in the Wesnoth Lua API expect a table representing a WML object (that is, the contents of a WML tag) to be passed as a parameter, for example [[LuaAPI/wml#wml.fire|wml.fire]]. Other functions return WML data converted to a Lua table. All these tables have the same format. The Lua API documentation refers to a table using this specific format convention as a "WML table".
  
 
Scalar fields are transformed into WML attributes. For instance, the following Lua table
 
Scalar fields are transformed into WML attributes. For instance, the following Lua table
Line 543: Line 285:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys. So child objects are stored as pairs string + table in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form <code>{[1] = "tag_name", [2] = {}}</code> which is equivalent to <code>{"tag_name", {}}</code>. [1] etc are the unnamed fields (as opposed to wml attributes). The table under [2] in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. For instance, the following Lua table
+
WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys (it is possible to have a tag and an attribute with the same name). So child objects are stored as (string, table) pairs in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form <syntaxhighlight inline lang=lua>{tag = "tag_name", contents = {}}</syntaxhighlight>. The table under <tt>contents</tt> in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. In code, this format is constructed using [[LuaAPI/wml#wml.tag|wml.tag]] to improve readability. For example <syntaxhighlight inline lang=lua>wml.tag_name{}</syntaxhighlight> is equivalent to the prior example.
 +
 
 +
'''Note''': As of 1.17, the structure changed slightly. Previously the additional table "layer" for each tag looked like <syntaxhighlight inline lang=lua>{[1] = "tag_name", [2] = {}}</syntaxhighlight>. For backwards compatibility, accessing [1] and [2] still return or set tag and contents respectively (in fact, it is a structure created by [[LuaAPI/wesnoth#wesnoth.named_tuple|wesnoth.named_tuple]]). However, in older versions, only [1] and [2] work.
 +
 
 +
For instance, the following Lua table
  
 
<syntaxhighlight lang='lua'>
 
<syntaxhighlight lang='lua'>
 
{
 
{
 
     foo = 42,
 
     foo = 42,
     { "bar", { v = 1, w = 2 } },
+
     wml.tag.bar { v = 1, w = 2 } },
     { "foo", { x = false } },
+
     wml.tag.foo { x = false } },
     { "bar", { y = "foo" } },
+
     wml.tag.bar { y = "foo" } },
     { "foobar", { z = 5, { "barfoo", {} } } }
+
     wml.tag.foobar { z = 5, { wml.tag.barfoo {} } } }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 576: Line 322:
 
     [/foobar]
 
     [/foobar]
 
[/dummy]
 
[/dummy]
</syntaxhighlight>
 
 
Both tables above are also equivalent to this WML table, where all unnamed fields are displayed:
 
 
<syntaxhighlight lang='lua'>
 
{
 
    foo = 42,
 
    [1] = { [1] = "bar", [2] = { v = 1, w = 2 } },
 
    [2] = { [1] = "foo", [2] = { x = false } },
 
    [3] = { [1] = "bar", [2] = { y = "foo" } },
 
    [4] = { [1] = "foobar", [2] = { z = 5, [1] = { [1] = "barfoo", [2] = {} } } }
 
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 594: Line 328:
 
<syntaxhighlight lang=lua>
 
<syntaxhighlight lang=lua>
 
a_int = cfg.foo        -- "dummy.foo", 42
 
a_int = cfg.foo        -- "dummy.foo", 42
a_string = cfg[3][2].y -- "dummy.bar[1].y", "foo"
+
a_string = cfg[3].contents.y -- "dummy.bar[1].y", "foo"
a_table = cfg[4][2]   -- "dummy.foobar", { z = 5, { "barfoo", {} } }
+
a_table = cfg[4].contents   -- "dummy.foobar", { z = 5, { "barfoo", {} } }
</syntaxhighlight>
 
 
 
For creating valid wml table in lua it is usully easier to use ''wml.tag''. Using that, you can create the above wml document with:
 
 
 
<syntaxhighlight lang=lua>
 
{
 
    foo = 42,
 
    wml.tag.bar {
 
        v = 1,
 
        w = 1,
 
    },
 
    wml.tag.foo {
 
        x = false,
 
    },
 
    wml.tag.bar {
 
        y = "foo",
 
    },
 
    wml.tag.foobar {
 
        z = 5,
 
        wml.tag.barfoo {
 
        },
 
    },
 
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 641: Line 352:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Functions registered in [[LuaWML:Events#wesnoth.wml_actions|wesnoth.wml_actions]] and other similar tables that provide hooks that the engine calls will receive their data either in lua tables encoding a WML object or as a [[LuaAPI/wml#wml.tovconfig|WML vconfig userdata]], which has the same structure but is read-only. Accessing fields or children on a vconfig performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain, writable tables. '''__literal''' returns the original text of the data (including dollar symbols in attributes and '''[insert_tag]''' children), while '''__parsed''' performs a full variable substitution.
+
=== vconfig userdata ===
 +
Functions registered in [[LuaAPI/wesnoth#wesnoth.wml_actions|wesnoth.wml_actions]] and other similar tables that provide hooks that the engine calls will receive their data either in lua tables encoding a WML object or as a [[LuaAPI/wml#wml.tovconfig|WML vconfig userdata]], which has the same structure but is read-only. Accessing fields or children on a vconfig performs variable substitution on the fly. Its '''__parsed''' and '''__literal''' fields provide translations to plain, writable tables. '''__literal''' returns the original text of the data (including dollar symbols in attributes and '''[insert_tag]''' children), while '''__parsed''' performs a full variable substitution.
  
 
For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.
 
For instance, if you cannot stand any longer the fact that '''first_time_only''' is set to yes by default for the '''[event]''' tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.
Line 649: Line 361:
 
function wesnoth.wml_actions.event(cfg)
 
function wesnoth.wml_actions.event(cfg)
 
     -- Get the plain text from the user.
 
     -- Get the plain text from the user.
     local new_cfg = helper.literal(cfg)
+
     local new_cfg = wml.literal(cfg)
 
     -- The expression below is equivalent to cfg.__parsed.first_time_only,
 
     -- The expression below is equivalent to cfg.__parsed.first_time_only,
 
     -- only faster. It is needed, since the first_time_only attribute may
 
     -- only faster. It is needed, since the first_time_only attribute may
Line 658: Line 370:
 
     new_cfg.first_time_only = first
 
     new_cfg.first_time_only = first
 
     -- Call the engine handler.
 
     -- Call the engine handler.
     old_event_handler(new_cfg)
+
     old_event_handler(wml.tovconfig(new_cfg))
 
end
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 666: Line 378:
 
<!-- This should probably be replaced with a better example. -->
 
<!-- This should probably be replaced with a better example. -->
  
'''pairs''' and '''ipairs''' also work on vconfig objects (contrary to the above statement). However, '''pairs''' works a little differently than on plain configs (tables) - it returns only string keys (attributes in WML terms) and not integer keys (tags in WML terms).
+
'''pairs''' and '''ipairs''' also work on vconfig objects. However, '''pairs''' works a little differently than on plain configs (tables) - it returns only string keys (attributes in WML terms) and not integer keys (tags in WML terms).
  
 
Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand. The [[LuaAPI/wml#wml.parsed|wml.parsed]] and [[LuaAPI/wml#wml.literal|wml.literal]] helpers take care of this for you.
 
Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand. The [[LuaAPI/wml#wml.parsed|wml.parsed]] and [[LuaAPI/wml#wml.literal|wml.literal]] helpers take care of this for you.
Line 712: Line 424:
 
== Remarks on Random Numbers ==
 
== Remarks on Random Numbers ==
  
The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should use the [[LuaWML:Misc#wesnoth.random|wesnoth.random]] function to synchronize random values. It has the same interface as math.random but is multiplayer-safe.
+
The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should use the [[LuaAPI/mathx#mathx.random|mathx.random]] function to synchronize random values. It has the same interface as math.random but is multiplayer-safe.
  
Also available is [[LuaWML:Misc#helper.rand|helper.rand()]], which takes the same argument in the same format as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] rand=.
+
Also available is [[LuaAPI/mathx#mathx.random_choice|mathx.random_choice]], which takes the same argument in the same format as [[InternalActionsWML#.5Bset_variable.5D|[set_variable]]] rand=.
  
 
<syntaxhighlight lang='lua'>
 
<syntaxhighlight lang='lua'>
  local random_variable = helper.rand("1,2,3")
+
  local random_variable = mathx.random_choice("1,2,3")
 
</syntaxhighlight>
 
</syntaxhighlight>
  

Latest revision as of 23:38, 1 November 2024

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, core, credits_group, criteria;

D:

damage, damage_type, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, fonts, for, foreach, found_item, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resolution, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit (action, scenario), unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

The [lua] tag

This tag is a part of ActionWML, thus can be used inside [event] and at other places where ActionWML can be used. It makes it possible to write actions with the Lua 5.4 language.

(Version 1.13.? and later only) In addition to ActionWML, the [lua] tag may now be used in several other places. It can be placed at toplevel (outside of any tag) to make code that loads no matter what. (Note: This should usually be avoided, unless you're making a custom core.) It can be placed in any addon module tag, such as [scenario], [era], or [resource], to load code when the scenario boots up. Lua code placed in either of these places is executed even earlier than a preload event. And finally, it can now be used as ConditionalWML. In this case, the code must return either true or false to determine the outcome of the condition.

The [lua] tag can contain the following contents:

  • code: A string containing the Lua script.
  • name: An arbitrary string used to identify this tag in error messages.
  • [args]: Arbitrary data that will be passed to the Lua script as its only argument. It can be accessed in the Lua code via the special variadic variable ....

Since Lua makes usage of double quotes and curly braces, it is recommended to enclose the script between stronger quotes (as shown in the below example), as they prevent the preprocessor from performing macro expansion and tokenization. This is not strictly required, however. Example:

 [lua]
     code = << wesnoth.interface.add_chat_message "Hello World!" >>
 [/lua]

The [args] tag is useful if you need to pass WML variables or macro expansions into the code.

 [lua]
     code = << local t = ...; wesnoth.interface.add_chat_message(tostring(t.text)) >>
     [args]
         text = _ "Hello $unit.name!"
     [/args]
 [/lua]

When code in a [lua] tag has errors, it's often hard to find the location of the error because the line numbers are not within the code string and not the entire file. To help with this, you can set the name key. When an error is reported, the value of name will be shown as if it were the filename, allowing you to more easily locate the tag that raised it.

Testing out Lua in-game

The Lua kernel can also be accessed from command mode:

:lua local u = wesnoth.units.find_on_map{ id = "Konrad" }[1]; u.moves = 5

In addition, if you enable debug mode, you can access a <acronym title="Read, evaluate, print loop">REPL</acronym> console by pressing the Lua Console hotkey, which is bound to ~ by default. You can enable debug mode by using the :debug command, or by running Wesnoth with the --debug command-line argument. In the latter case, the Lua Console can even be summoned from the main menu screen.

You can use the Lua console to examine anything about the Lua environment and execute any Lua code you wish. It is recommended to use command mode to execute Lua that affects the map however, for example moving a unit. In the Lua Console you can use a special dir() function to examine the contents of objects and modules. You can also access a special _ variable which contains the result of the previous command executed in the console. Global variables assigned in the Lua console are not visible to scenario code, but remain between invocations of the console within a single game, as long as you don't reload. If you need to assign a global variable that is visible outside of the console, you can do so via the special variable _G.

Global environment

All the Lua scripts of a scenario share the same global environment (aka Lua state). Unlike other parts of the configurable gamestate the Lua state is not stored in savefiles, thus [lua] tags in [scenario] are executed not only before the scenario starts but also each time the game is loaded. Functions defined in [lua] tags in [scenario] can be used in all [lua] tags in [event]s.

 [scenario]
     [lua]
         code = <<
             function narrator(t)
                 -- Behave like the [message] tag.
                 wml.fire("message",
                   { speaker = "narrator", message = t.sentence })
             end
         >>
     [/lua]
     [event]
         name = turn 1
         [lua]
             code = << narrator(...) >>
             [args]
                 sentence = _ "Hello world!"
             [/args]
         [/lua]
         [lua]
             code = << narrator(...) >>
             [args]
                 sentence = _ "How are you today?"
             [/args]
         [/lua]
     [/event]
     ...
 [/scenario]

In the example above, the redundant structure could be hidden behind macros. But it may be better to simply define a new WML tag.

 [scenario]
     [lua]
         code = <<
             -- The function is now placed in the wesnoth.wml_actions table
             -- The tag is [narrator], same as the function name
             function wesnoth.wml_actions.narrator(t)
                 -- Behave like the [message] tag.
                 wml.fire("message",
                   { speaker = "narrator", message = t.sentence })
             end
         >>
     [/lua]
 
     [event]
         name = turn 1
         [narrator]
             sentence = _ "Hello world!"
         [/narrator]
         [narrator]
             sentence = _ "How are you today?"
         [/narrator]
     [/event]
 [/scenario]

The global environment is not preserved over save/load cycles. Therefore, storing values in the global environment is generally a bad idea. The only time assigning global variables (including function definitions) makes sense is in a [lua] block directly in [scenario] or during a preload event, as this event is always run. Therefore, helper functions defined at that time will be available to all the later scripts.

The global environment initially contains the following built-in modules: string, table, and math. A wesnoth module is also available, which provides access to the C++ game engine. Additionally, the functions clock, date, time and difftime from the os module are also available (but keep in mind that they aren't multiplayer- and replay-safe), as well as traceback from the debug module. There are also a few other built-in modules specific to Wesnoth – for full details, see LuaAPI.

At the start of a script, the variadic local variable ... (three dots) is a proxy table representing WML data. This table is the content of the [args] sub-tag of the [lua] tag, if any.

Examples

The following WML event is taken from Wesnoth' tutorial. It will serve as an example to present how Lua scripts are embedded into Wesnoth. The event is fired whenever a unit from side 1 (that is, the hero controlled by the user) moves to a tile that is not the one set in the WML variable target_hex.

 # General catch for them moving to the wrong place.
 [event]
     name=moveto
     first_time_only=no
     [allow_undo][/allow_undo]
     [filter]
         side=1
     [/filter]
 
     [if]
         [variable]
             name=target_hex.is_set
             equals=yes
         [/variable]
         [then]
             [if]
                 [variable]
                     name=x1
                     equals=$target_hex.x
                 [/variable]
                 [variable]
                     name=y1
                     equals=$target_hex.y
                 [/variable]
                 [then]
                 [/then]
                 [else]
                     [redraw][/redraw]
                     [message]
                         speaker=narrator
                         message=_ "*Oops!
 You moved to the wrong place! After this message, you can press 'u' to undo, then try again." +
                         _ "
 *Left click or press spacebar to continue..."
                     [/message]
                 [/else]
             [/if]
         [/then]
     [/if]
 [/event]

A Lua script that performs the same action is presented below.

 [event]
     name=moveto
     first_time_only=no
     [allow_undo][/allow_undo]
     [filter]
         side=1
     [/filter]
 
     [lua]
         code = <<

             local event_data = wesnoth.current.event_context
             if wml.variables["target_hex.is_set"] and
                (event_data.x1 ~= wml.variables["target_hex.x"] or event_data.y1 ~= wml.variables["target_hex.y"])
             then
                 W.redraw()
                 narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")
             end
         >>
     [/lua]
 [/event]

Here is a more detailed explanation of the Lua code. Its first line

local event_data = wesnoth.current.event_context

puts the event data into the event_data local variable. Since it is a moveto event, the event_data table contains the destination of the unit in the x1 and y1 fields.

The next two lines then test

if wml.variables["target_hex.is_set"] and
    (event_data.x1 ~= wml.variables["target_hex.x"] or event_data.y1 ~= wml.variables["target_hex.y"])

whether the variable wml.variables["target_hex"] matches the event parameters. Since wml.variables is not a local variable, it is taken from the global environment. Usually, variables from the global environment are not persistent but the wesnoth engine maps the variable wml.variables to the storage of WML variables.

The body of the conditional then performs the [redraw] action.

W.redraw()

This short syntax is made possible by a line of the prelude that makes W a proxy for performing WML actions.

 [scenario]
     [lua]
         code = <<
             H = wesnoth.require "helper"
             W = H.set_wml_action_metatable {}
         >>
     [/lua]
     ...
 [/scenario]

Without this shortcut, the first statement would have been written

wml.fire("redraw")

or

wesnoth.wml_actions.redraw {}

Finally the script displays a message by

narrator_says(_ "*Oops!\nYou moved to the wrong place! After this message, you can press 'u' to undo, then try again.")

The narrator_says function is defined in the prelude too, since the construct behind it occurs several times in the tutorial. In plain WML, macros would have been used instead. The definition of the function is

function narrator_says(m)
    W.message { speaker="narrator",
                message = m .. _ "\n*Left click or press spacebar to continue..." }
end

The function fires a [message] action and passes a WML object containing the usual two fields to it. The second field is initialized by concatenating the function argument with another string. Both strings are prefixed by the _ symbol to mark them as translatable. (Note that _ is just a unary function, not a keyword.) Again, this is made possible by a specific line of the prelude:

_ = wesnoth.textdomain "wesnoth-tutorial"


Encoding WML objects into Lua tables

WML table

Many functions in the Wesnoth Lua API expect a table representing a WML object (that is, the contents of a WML tag) to be passed as a parameter, for example wml.fire. Other functions return WML data converted to a Lua table. All these tables have the same format. The Lua API documentation refers to a table using this specific format convention as a "WML table".

Scalar fields are transformed into WML attributes. For instance, the following Lua table

{
    a_bool = true,
    an_int = 42,
    a_float = 1.25,
    a_string = "scout",
    a_translation = _ "Hello World!"
}

is equivalent to the content of the following WML object

[dummy]
    a_bool = "yes"
    an_int = 42
    a_float = 1.25
    a_string = "scout"
    a_translation = _ "Hello World!"
[/dummy]

WML child objects are not stored as Lua named fields, since several of them can have the same tag. Moreover, their tags can conflict with the attribute keys (it is possible to have a tag and an attribute with the same name). So child objects are stored as (string, table) pairs in the unnamed fields in definition order. This means that for every subtag appearing in the wml code there is an additional table "layer" in the corresponding WML table of the form {tag = "tag_name", contents = {}}. The table under contents in this subtable then holds the wml attributes from inside the wml subtag. So every subtag other than the toplevel tag corresponds to two nested tables each. In code, this format is constructed using wml.tag to improve readability. For example wml.tag_name{} is equivalent to the prior example.

Note: As of 1.17, the structure changed slightly. Previously the additional table "layer" for each tag looked like {[1] = "tag_name", [2] = {}}. For backwards compatibility, accessing [1] and [2] still return or set tag and contents respectively (in fact, it is a structure created by wesnoth.named_tuple). However, in older versions, only [1] and [2] work.

For instance, the following Lua table

{
    foo = 42,
    wml.tag.bar { v = 1, w = 2 } },
    wml.tag.foo { x = false } },
    wml.tag.bar { y = "foo" } },
    wml.tag.foobar { z = 5, { wml.tag.barfoo {} } } }
}

is equivalent to the content of the following WML object

[dummy]
    foo = 42
    [bar]
        v = 1
        w = 2
    [/bar]
    [foo]
        x = no
    [/foo]
    [bar]
        y = foo
    [bar]
    [foobar]
        z = 5
        [barfoo]
        [/barfoo]
    [/foobar]
[/dummy]

So assuming cfg contains the above WML object, the following accesses are possible:

a_int = cfg.foo        -- "dummy.foo", 42
a_string = cfg[3].contents.y -- "dummy.bar[1].y", "foo"
a_table = cfg[4].contents    -- "dummy.foobar", { z = 5, { "barfoo", {} } }

Consider using the wml.get_child and wml.child_range helper functions to ease the access to subtags.

(Version 1.13.5 and later only) As a convenience, attributes with array values (tables with only integer keys) are concatenated into a string when converting a Lua table into WML. For example, the following Lua code:

{
    x = {1, 2, 3, 4},
    y = {7, 8, 9, 10}
}

produces the following WML table:

[dummy]
    x=1,2,3,4
    y=7,8,9,10
[/dummy]

vconfig userdata

Functions registered in wesnoth.wml_actions and other similar tables that provide hooks that the engine calls will receive their data either in lua tables encoding a WML object or as a WML vconfig userdata, which has the same structure but is read-only. Accessing fields or children on a vconfig performs variable substitution on the fly. Its __parsed and __literal fields provide translations to plain, writable tables. __literal returns the original text of the data (including dollar symbols in attributes and [insert_tag] children), while __parsed performs a full variable substitution.

For instance, if you cannot stand any longer the fact that first_time_only is set to yes by default for the [event] tag, you can redefine it. But we have to be careful not to cause variable substitution, since the engine would perform a second variable substitution afterwards.

local old_event_handler = wesnoth.wml_actions.event
function wesnoth.wml_actions.event(cfg)
    -- Get the plain text from the user.
    local new_cfg = wml.literal(cfg)
    -- The expression below is equivalent to cfg.__parsed.first_time_only,
    -- only faster. It is needed, since the first_time_only attribute may
    -- reference variables.
    local first = cfg.first_time_only
    -- Modify the default behavior of first_time_only.
    if first == nil then first = false end
    new_cfg.first_time_only = first
    -- Call the engine handler.
    old_event_handler(wml.tovconfig(new_cfg))
end

(Note: The above example will only affect nested events. Toplevel events will still default to first_time_only=yes.) (Note2: You should not do that since it will break other addons that rely on the first_time_only=no default value.)

pairs and ipairs also work on vconfig objects. However, pairs works a little differently than on plain configs (tables) - it returns only string keys (attributes in WML terms) and not integer keys (tags in WML terms).

Another approach for handling userdata and tables in the same way, would be to convert the former into the latter beforehand. The wml.parsed and wml.literal helpers take care of this for you.

The vconfig userdata provides two other special fields: __shallow_parsed and __shallow_literal. They return a table corresponding to the WML userdata with variable substitution performed on the attributes (or not). [insert_tag] tags have also been parsed, so the number of children is faithful. But contrarily to __parsed and __literal, the process is not recursive: all the children are still WML userdata and variable substitution can still happen for them. These shallow translators are meant as optimized versions of the deep ones, when only the toplevel attributes need to be writable.

Skeleton of a lua tag

The following [lua] tag is a skeleton for a prelude enabling Lua in your WML events. It creates a table H containing the functions from helper.lua . It sets up a table T so be used for easier creation of valid WML tables. It also sets up a table V so that any access to it is redirected to the persistent WML storage. Finally, it loads a textdomain to be accessed through the _ variable.

[scenario]
    [lua]
        code = <<
            H = wesnoth.require "lua/helper.lua"
            T = wml.tag
            V = wml.variables
            local _ = wesnoth.textdomain "my-campaign"

            -- Define your global constants here.
            -- ...


            -- Define your global functions here.
            -- ...
        >>
    [/lua]
    ... 
[/scenario]

It may be worth putting the whole Lua script above inside a separate file and having the [lua] tag load it:

[scenario]
    [lua]
        code = << wesnoth.dofile "~add-ons/Whatever/file.lua" >>
    [/lua]
    ...
[/scenario]

Note: When a multiplayer scenario is hosted on the multiplayer server, separate Lua files are not transmitted over the network from the host to the peers. Therefore, it may happen that the Lua code from the separate files is executed on the host but not on the peers. This may result in out of-sync type errors. Only the Lua code that is embedded in the scenario WML, that is without wesnoth.dofile, will be transmitted and executed. To prevent these issues, the Lua files that are to be loaded with wesnoth.dofile must be distributed to the end-user explicitly.

Remarks on Random Numbers

The math.random function is not safe for replays and multiplayer games, since the random values will be different each time and on all the clients. Instead, the Lua code should use the mathx.random function to synchronize random values. It has the same interface as math.random but is multiplayer-safe.

Also available is mathx.random_choice, which takes the same argument in the same format as [set_variable] rand=.

 local random_variable = mathx.random_choice("1,2,3")

Random Lua table iteration

Table iteration order (pairs) is not strictly defined in Lua. If your code depends on the order of iteration, different clients may have different data in a multiplayer game. For example:

  local table = { ["Mage"] = true, ["Wose"] = true }
  local concat = ""
  local bad_usage = next(table) -- wrong, leads to OOS
  for k, _ in pairs(table) do -- wrong, leads to OOS
    concat = concat .. k
  end

To avoid the problem, sort the table keys before iterating. Or alternatively, use Lua "arrays" and the ipairs function, which have a strictly defined order and never lead to OOS. Example of correct code:

  local array = { "Mage", "Wose" }
  local good_usage = table[1] -- correct
  local concat = ""
  for _, v in ipairs(array) do -- correct
    concat = concat .. v
  end
This page was last edited on 1 November 2024, at 23:38.