Difference between revisions of "LuaAPI"

From The Battle for Wesnoth Wiki
(Wesnoth Modules: Add gui module)
(Conventions used in this manual: Add a clarification; without this, one might wonder why you'd use ... instead of square brackets)
 
(17 intermediate revisions by the same user not shown)
Line 34: Line 34:
 
<!-- TODO: Consider implementing image icons for these? -->
 
<!-- TODO: Consider implementing image icons for these? -->
  
Functions that take a variable number of parameters will use the string "..." to indicate this. For example:
+
Functions that take a variable number of parameters or return a variable number of values where the specific meaning of the parameters is unspecified will use the string "..." to indicate this. For example:
  
 
* '''wesnoth.variadic_function'''(''required_param'' [, ...])
 
* '''wesnoth.variadic_function'''(''required_param'' [, ...])
 +
* '''wesnoth.get_several_values'''(''param'') &rarr; ...
  
 
=== Wesnoth Modules ===
 
=== Wesnoth Modules ===
  
 
* [[LuaAPI/wesnoth|Core]] - The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.
 
* [[LuaAPI/wesnoth|Core]] - The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.
* [[LuaAPI/gui|Gui]] - The <tt>gui</tt> module contains routines for showing dialogs on the screen. It does ''not'' contain anything for manipulating the in-game UI, however.
+
** [[LuaAPI/wesnoth/interface|Interface]] - {{DevFeature1.15|0}} The <tt>interface</tt> submodule contains functions for querying or manipulating the in-game UI.
 +
** [[LuaAPI/wesnoth/units|Units]] - {{DevFeature1.15|0}} The <tt>units</tt> submodule contains functions for manipulating units on the map or recall list.
 +
** [[LuaAPI/wesnoth/sides|Sides]] - {{DevFeature1.15|3}} The <tt>sides</tt> submodule contains functions for manipulating sides in the scenario.
 +
* [[LuaAPI/gui|GUI]] - {{DevFeature1.15|0}} The <tt>gui</tt> module contains routines for showing dialogs on the screen. It does ''not'' contain anything for manipulating the in-game UI, however.
 +
** [[LuaAPI/gui/widget|Widget]] - {{DevFeature1.15|6}} The <tt>widget</tt> submodule contains routines for operating on dialog widgets. Since they take a widget reference an argument, they can only be called while a dialog is onscreen.
 
* [[LuaAPI/wml|WML]] - The <tt>wml</tt> module contains functions for working with WML tables.
 
* [[LuaAPI/wml|WML]] - The <tt>wml</tt> module contains functions for working with WML tables.
 +
* [[LuaAPI/location_set|location_set]] - A module for working with sets of locations, optionally associating data to each location. Not loaded by default.
 +
* [[LuaAPI/functional|functional]] - Higher-order functions module. Not loaded by default.
 +
* [[LuaAPI/stringx|stringx]] - Additional string support functions, to augment the built-in string module.
 +
 +
=== Wesnoth Types ===
 +
 +
Wesnoth defines a large number of ''userdata'' types, some of which are quite common and complex. Most of them are documented alongside the function that creates them, but some of the most common or complex ones are listed below.
 +
 +
* [[LuaAPI/wesnoth#wesnoth.textdomain|translatable strings]] - a string that will be translated by the engine.
 +
* [[LuaAPI/wml#wml.tovconfig|vconfig]] - a WML object that automatically substitutes variables on the fly.
 +
* [[LuaAPI/types/unit|unit]] - represents a reference to Wesnoth unit on the map, on the recall list, or private to Lua.
 +
* [[LuaAPI/types#Weapon|weapon]] - represents a unit's weapon.
 +
* [[LuaAPI/types#Race|race]] - represents a unit's race.
 +
* [[LuaAPI/types#Unit_Type|unit type]] - represents a unit's type.
 +
* [[LuaAPI/types/side|side]] - represents a single side (player) in the game.
 +
* [[LuaAPI/types/widget|widget]] - represents a GUI2 widget.
 +
 +
[[Category:Lua Reference]]

Latest revision as of 02:15, 17 October 2020

Note: This page is is a work-in-progress and only reflects the current stable version. For more complete documentation for 1.14, see here.

All Lua API functionality is available in one of several global module tables, as well as some global functions which form the basic Lua API. The following core Lua modules are available and are documented on the Lua website:

  • basic — except dofile, require, and loadfile; also note that print redirects to the Lua console interface rather than standard output; you can use std_print if you need the default Lua behavior. Starting from 1.15, loadstring (deprecated in Lua in favor of load) isn't available either.
  • coroutine
  • string
  • utf8
  • table
  • math — note that math.random is unsafe for MP usage; wesnoth provides a separate MP-safe random function
  • os — only the clock, date, time, and difftime functions are available (but keep in mind that they are not MP safe)
  • debug — only the traceback function is available

Wesnoth also provides several modules of its own, some of which are loaded by default while others require you to load them as needed.

Conventions used in this manual

On this page and any page linked from it, parameters will be shown in italic type, while literal names will be shown in bold type. Return values will be indicated by a right arrow (→) followed by a list of names in italics. Optional portions will be enclosed in square brackets.

For example, consider the following hypothetical definitions:

  • wesnoth.some_function(some_parameter [, some_optional_parameter]) → first_return_value, second_return_value

This is a function that returns multiple values and has optional parameters

  • some_value:some_method(some_parameter) → some_new_value
  • some_value.some_memberresult

For member variables, the right arrow may be replaced with a left arrow (←) if it is write-only, or a double-ended arrow (↔) if it is read-write.

Many functions and variables are only available in certain contexts. Currently, there are three possible contexts - plugins, map generators, and the game. Most Lua will run in the game kernel. If a function is only available in certain contexts, that will be indicated in parentheses at the beginning of the definition. For example:

  • (game only) wesnoth.game_exclusive_function(parameter) → result


Functions that take a variable number of parameters or return a variable number of values where the specific meaning of the parameters is unspecified will use the string "..." to indicate this. For example:

  • wesnoth.variadic_function(required_param [, ...])
  • wesnoth.get_several_values(param) → ...

Wesnoth Modules

  • Core - The wesnoth module contains most of the core Wesnoth API. It is always loaded and available.
  • GUI - (Version 1.15.0 and later only) The gui module contains routines for showing dialogs on the screen. It does not contain anything for manipulating the in-game UI, however.
    • Widget - (Version 1.15.6 and later only) The widget submodule contains routines for operating on dialog widgets. Since they take a widget reference an argument, they can only be called while a dialog is onscreen.
  • WML - The wml module contains functions for working with WML tables.
  • location_set - A module for working with sets of locations, optionally associating data to each location. Not loaded by default.
  • functional - Higher-order functions module. Not loaded by default.
  • stringx - Additional string support functions, to augment the built-in string module.

Wesnoth Types

Wesnoth defines a large number of userdata types, some of which are quite common and complex. Most of them are documented alongside the function that creates them, but some of the most common or complex ones are listed below.

  • translatable strings - a string that will be translated by the engine.
  • vconfig - a WML object that automatically substitutes variables on the fly.
  • unit - represents a reference to Wesnoth unit on the map, on the recall list, or private to Lua.
  • weapon - represents a unit's weapon.
  • race - represents a unit's race.
  • unit type - represents a unit's type.
  • side - represents a single side (player) in the game.
  • widget - represents a GUI2 widget.
This page was last edited on 17 October 2020, at 02:15.