Difference between revisions of "LuaAPI"

From The Battle for Wesnoth Wiki
(Wesnoth Modules: Add sides module)
 
(48 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
__NOTOC__
 +
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. Wesnoth uses [http://www.lua.org/manual/5.4/manual.html Lua 5.4] which is documented in detail on the Lua website.
  
'''''Note: This page is is a work-in-progress and only reflects the current stable version. For more complete documentation for 1.14, see [[LuaWML#Interface_to_the_engine_and_helper_functions|here]].'''''
+
This page documents the modules, functions, and other APIs available for use when writing Lua for Wesnoth. For information on how to tell the engine about your Lua code, see [[LuaWML]].
  
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:
+
== Conventions used in this manual ==
  
* [http://www.lua.org/manual/5.3/manual.html#6.1 basic] — except <tt>dofile</tt>, <tt>require</tt>, and <tt>loadfile</tt>; also note that <tt>print</tt> redirects to the Lua console interface rather than standard output; you can use <tt>std_print</tt> if you need the default Lua behavior. Starting from 1.15, <tt>loadstring</tt> (deprecated in Lua in favor of <tt>load</tt>) isn't available either.
+
On this page and any page linked from it, variable values will be shown in italic type, while literal names will be shown in bold type. Variable values may be parameters, self values, indexes, or field names on a table. Return values will be indicated by a right arrow (&rarr;) followed by a list of names in italics. The arrow will be omitted for a function that returns nothing. Optional portions will be enclosed in square brackets. The commas for optional parameters will not be included in the brackets, even though they must be omitted if the optional parameter is omitted.
* [http://www.lua.org/manual/5.3/manual.html#6.2 coroutine]
 
* [http://www.lua.org/manual/5.3/manual.html#6.4 string]
 
* [http://www.lua.org/manual/5.3/manual.html#6.5 utf8]
 
* [http://www.lua.org/manual/5.3/manual.html#6.6 table]
 
* [http://www.lua.org/manual/5.3/manual.html#6.7 math] — note that <tt>math.random</tt> is unsafe for MP usage; wesnoth provides a separate MP-safe random function
 
* [http://www.lua.org/manual/5.3/manual.html#6.9 os] — only the <tt>clock</tt>, <tt>date</tt>, <tt>time</tt>, and <tt>difftime</tt> functions are available (but keep in mind that they are not MP safe)
 
* [http://www.lua.org/manual/5.3/manual.html#6.10 debug] — only the <tt>traceback</tt> 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.
+
===== Functions =====
  
=== Conventions used in this manual ===
+
For example, the following line would be seen in the documentation of a function that returns two values and has an optional parameter:
  
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 (&rarr;) followed by a list of names in italics. Optional portions will be enclosed in square brackets.
+
* '''wesnoth.some_function'''(''some_parameter'', [''some_optional_parameter'']) &rarr; ''first_return_value'', ''second_return_value''
  
For example, consider the following hypothetical definitions:
+
===== Methods =====
 +
 
 +
The following example documents a function that can be called as a method on a ''some_value'', taking one additional parameter and returning one value.
  
* '''wesnoth.some_function'''(''some_parameter'' [, ''some_optional_parameter'']) &rarr; ''first_return_value'', ''second_return_value''
 
This is a function that returns multiple values and has optional parameters
 
 
* ''some_value'':'''some_method'''(''some_parameter'') &rarr; ''some_new_value''
 
* ''some_value'':'''some_method'''(''some_parameter'') &rarr; ''some_new_value''
* ''some_value''.'''some_member''' &rarr; ''result''
 
  
For member variables, the right arrow may be replaced with a left arrow (&larr;) if it is write-only, or a double-ended arrow (&harr;) if it is read-write.
+
===== Variadic Functions =====
 +
 
 +
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'') &rarr; ...
 +
 
 +
The first of these takes a variable number of parameters, but requires at least one parameter. The second takes one parameter and returns a variable number of values.
 +
 
 +
===== Member Variables =====
 +
 
 +
Not all documented APIs are functions. When documenting userdata types, as well as some complex tables returned by API functions, the following syntax is used for member variables. The right arrow may be replaced with a left arrow (&larr;) if it is write-only, or a double-ended arrow (&harr;) if it is read-write. Read-only members may return multiple values. The following examples document a read-write member, a read-only member that returns two values, and a write-only member respectively.
 +
 
 +
* ''some_value''.'''some_member''' &harr; ''result''
 +
* ''some_value''.'''read_only_member''' &rarr; ''first_result'', ''second_result''
 +
* ''some_value''.'''write_only_member''' &larr; ''input''
 +
 
 +
===== Operators =====
 +
 
 +
Custom types in Lua can overload operators with new functionality. Some examples of how these would be documented:
 +
 
 +
* #'''wesnoth.list_like_object''' &rarr; ''number of somethings''
 +
* '''wesnoth.list_like_object'''[''index''] &harr; ''a something definition table''
 +
* ''comparable_value'' == ''comparable_value'' &rarr; ''whether they are equal''
 +
* ''operable_value'' + ''operable_value'' &rarr; ''result''
 +
 
 +
The first example documents that you can get the length of that object. The same format would be used for other unary operators as well.
 +
 
 +
The second example documents that you can index the object with arbitrary values. Whether the index needs to be a number would usually be mentioned in the detailed description, although the placeholder name may also make it clear. This example could also use a single-directional arrow to indicate that it is read-only or write-only.
 +
 
 +
The third example documents that you can compare two values of that type with the equality operator, and the fourth example documents that you can add two values of that type together with the addition operator.
 +
 
 +
===== Iterators =====
 +
 
 +
For functions that return an iterator, a double arrow indicates the values yielded when you use the iterator in a for loop. The following example documents a function returning an iterator that yields three values.
  
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:
+
* '''wesnoth.some_function'''() &rarr; ''iterator'' &rArr; ''a'', ''b'', ''c''
  
* (game only) '''wesnoth.game_exclusive_function'''(''parameter'') &rarr; ''result''
+
===== Hooks =====
  
<!-- TODO: Consider implementing image icons for these? -->
+
Some parts of the API are so-called ''hooks'', meaning that you define a function in a special location and it has some effect on the game. The following example documents a hook which takes one parameter and returns a value. Usually the double-ended arrow is used for hooks, but some may be write-only.
  
Functions that take a variable number of parameters or return a variable number of values will use the string "..." to indicate this. For example:
+
* '''wesnoth.some_table'''.''name'' &harr; '''function'''(''parameter'') &rarr; ''expected return value''
  
* '''wesnoth.variadic_function'''(''required_param'' [, ...])
+
===== Context Specifiers =====
* '''wesnoth.get_several_values'''(''param'') &rarr; ...
+
 
 +
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 with an icon at the beginning of the definition. For example:
 +
 
 +
* {{LuaGameOnly}} '''wesnoth.game_exclusive_function'''(''parameter'') &rarr; ''result''
 +
 
 +
The possible icons are:
 +
 
 +
* {{LuaGameOnly}} Available in the game context. Most Lua in Wesnoth runs in the game context, which is initialized when a game begins and destroyed upon victory or loss.
 +
* {{LuaMapOnly}} Available in the map generation context. This context is created at the game creation screen, generally to generate a map for a scenario.
 +
* {{LuaPluginOnly}} Available in the plugins context. There is only one plugins context, which is initialized when Wesnoth launches and remains valid until it shuts down. A plugin is a Lua script loaded via the command-line option <tt>--plugin</tt> that runs as a coroutine in parallel with the game UI. It can automatically connect to a server and host or join a game. This API is documented at [[LuaPluginAPI]].
 +
 
 +
== Built-in Modules ==
 +
 
 +
The following built-in Lua modules are available:
 +
 
 +
* [http://www.lua.org/manual/5.4/manual.html#6.1 basic] — except <tt>dofile</tt>, <tt>require</tt>, and <tt>loadfile</tt>; also note that <tt>print</tt> redirects to the Lua console interface rather than standard output; you can use <tt>std_print</tt> if you need the default Lua behavior.
 +
* [http://www.lua.org/manual/5.4/manual.html#6.2 coroutine]
 +
* [http://www.lua.org/manual/5.4/manual.html#6.4 string]
 +
* [http://www.lua.org/manual/5.4/manual.html#6.5 utf8]
 +
* [http://www.lua.org/manual/5.4/manual.html#6.6 table]
 +
* [http://www.lua.org/manual/5.4/manual.html#6.7 math] — note that <tt>math.random</tt> is unsafe for MP usage; wesnoth provides a separate MP-safe random function
 +
* [http://www.lua.org/manual/5.4/manual.html#6.9 os] — only the <tt>clock</tt>, <tt>date</tt>, <tt>time</tt>, and <tt>difftime</tt> functions are available (but keep in mind that they are not MP safe)
 +
* [http://www.lua.org/manual/5.4/manual.html#6.10 debug] — only the <tt>traceback</tt> function is available
 +
 
 +
== Wesnoth Modules ==
  
=== Wesnoth Modules ===
+
Wesnoth also provides several modules of its own, some of which are loaded by default while others require you to load them as needed. Note: APIs named '''wesnoth.something''', for example [[LuaAPI/wesnoth#wesnoth.scenario|wesnoth.scenario]], might be part of Core and not a separate module.
  
* [[LuaAPI/wesnoth|Core]] - The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.
+
* [[LuaAPI/wesnoth|wesnoth]] (Core) - The <tt>wesnoth</tt> module contains most of the core Wesnoth API. It is always loaded and available.
** [[LuaAPI/wesnoth/interface|Interface]] - {{DevFeature1.15|0}} The <tt>interface</tt> submodule contains functions for querying or manipulating the in-game UI.
+
** [[LuaAPI/wesnoth/interface|wesnoth.interface]] (Game 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/units|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/wesnoth/schedule|wesnoth.schedule]] (Schedule) - {{DevFeature1.15|14}} The <tt>schedule</tt> submodule contains functions for manipulating the time of day schedule 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/wesnoth/sides|wesnoth.sides]] (Sides) - {{DevFeature1.15|3}} The <tt>sides</tt> submodule contains functions for manipulating sides in the scenario.
* [[LuaAPI/wml|WML]] - The <tt>wml</tt> module contains functions for working with WML tables.
+
** [[LuaAPI/wesnoth/sync|wesnoth.sync]] (Synchronization) - {{DevFeature1.15|3}} The <tt>sync</tt> submodule contains functions for keeping multiplayer games synchronized.
 +
** [[LuaAPI/wesnoth/map|wesnoth.map]] (Game Map) - {{DevFeature1.15|11}} The <tt>map</tt> submodule contains functions for querying and manipulating the game map.
 +
** [[LuaAPI/wesnoth/audio|wesnoth.audio]] (Audio) - {{DevFeature1.15|13}} The <tt>audio</tt> submodule contains functions for playing music and sound effects.
 +
** [[LuaAPI/wesnoth/paths|wesnoth.paths]] (Pathfinding) - {{DevFeature1.15|14}} The <tt>paths</tt> submodule contains functions related to pathfinding.
 +
** [[LuaAPI/wesnoth/game_events|wesnoth.game_events]] (Event Handling) - The <tt>game_events</tt> submodule contains functions and hooks related to event handling.
 +
** [[LuaAPI/wesnoth/achievements|wesnoth.achievements]] (Achievements Support) - {{DevFeature1.17|13}} The <tt>achievements</tt> submodule contains functions for checking and setting achievements.
 +
* [[LuaAPI/gui|gui]] (User Interface) - {{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|gui.widget]] (GUI Widget Support) - {{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]] (WML Tables) - The <tt>wml</tt> module contains functions for working with WML tables.
 +
* [[LuaAPI/location_set|location_set]] (Location Sets) - 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.
 +
* [[LuaAPI/mathx|mathx]] - {{DevFeature1.15|13}} Additional math and randomization support functions, to augment the built-in math module.
 +
* [[LuaAPI/filesystem|filesystem]] - {{DevFeature1.15|13}} Functions that allow read-only access to arbitrary files in the data folder.
 +
* [[LuaAPI/ai|ai]] - Functions that instruct the AI on how to move.
 +
* [[LuaAPI/wml-utils|wml-utils]] - Useful functions for implementing custom WML tags.
 +
* [[LuaAPI/unit_test|unit_test]] - Functions that can be used to write unit tests; only available in [test] scenarios.
  
=== Wesnoth Types ===
+
== 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.
 
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.
Line 55: Line 123:
 
* [[LuaAPI/wml#wml.tovconfig|vconfig]] - a WML object that automatically substitutes variables on the fly.
 
* [[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/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#Weapon|weapon]] - represents a unit's weapon.
* [[LuaAPI/types#race|race]] - represents a unit's race.
+
* [[LuaAPI/types#Race|race]] - represents a unit's race.
* [[LuaAPI/types#unit_type|unit type]] - represents a unit's type.
+
* [[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/side|side]] - represents a single side (player) in the game.
 +
* [[LuaAPI/types/widget|widget]] - represents a GUI2 widget.
 +
* [[LuaAPI/types/map|map]] - represents the game map.
 +
* [[LuaAPI/types/hex|hex]] - represents a single hex on the map.
 +
 
 +
== See Also ==
 +
* [[LuaAPI/UpdatingFrom14]]
 +
* [[LuaAPI/old]] - The reference for the 1.14 Lua API, which may be useful if porting older add-ons
  
[[Category:Lua Reference]]
+
[[Category:Lua Reference|*]]

Latest revision as of 18:12, 1 July 2023

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. Wesnoth uses Lua 5.4 which is documented in detail on the Lua website.

This page documents the modules, functions, and other APIs available for use when writing Lua for Wesnoth. For information on how to tell the engine about your Lua code, see LuaWML.

Conventions used in this manual

On this page and any page linked from it, variable values will be shown in italic type, while literal names will be shown in bold type. Variable values may be parameters, self values, indexes, or field names on a table. Return values will be indicated by a right arrow (→) followed by a list of names in italics. The arrow will be omitted for a function that returns nothing. Optional portions will be enclosed in square brackets. The commas for optional parameters will not be included in the brackets, even though they must be omitted if the optional parameter is omitted.

Functions

For example, the following line would be seen in the documentation of a function that returns two values and has an optional parameter:

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

The following example documents a function that can be called as a method on a some_value, taking one additional parameter and returning one value.

  • some_value:some_method(some_parameter) → some_new_value
Variadic Functions

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) → ...

The first of these takes a variable number of parameters, but requires at least one parameter. The second takes one parameter and returns a variable number of values.

Member Variables

Not all documented APIs are functions. When documenting userdata types, as well as some complex tables returned by API functions, the following syntax is used 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. Read-only members may return multiple values. The following examples document a read-write member, a read-only member that returns two values, and a write-only member respectively.

  • some_value.some_memberresult
  • some_value.read_only_memberfirst_result, second_result
  • some_value.write_only_memberinput
Operators

Custom types in Lua can overload operators with new functionality. Some examples of how these would be documented:

  • #wesnoth.list_like_objectnumber of somethings
  • wesnoth.list_like_object[index] ↔ a something definition table
  • comparable_value == comparable_valuewhether they are equal
  • operable_value + operable_valueresult

The first example documents that you can get the length of that object. The same format would be used for other unary operators as well.

The second example documents that you can index the object with arbitrary values. Whether the index needs to be a number would usually be mentioned in the detailed description, although the placeholder name may also make it clear. This example could also use a single-directional arrow to indicate that it is read-only or write-only.

The third example documents that you can compare two values of that type with the equality operator, and the fourth example documents that you can add two values of that type together with the addition operator.

Iterators

For functions that return an iterator, a double arrow indicates the values yielded when you use the iterator in a for loop. The following example documents a function returning an iterator that yields three values.

  • wesnoth.some_function() → iteratora, b, c
Hooks

Some parts of the API are so-called hooks, meaning that you define a function in a special location and it has some effect on the game. The following example documents a hook which takes one parameter and returns a value. Usually the double-ended arrow is used for hooks, but some may be write-only.

  • wesnoth.some_table.namefunction(parameter) → expected return value
Context Specifiers

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 with an icon at the beginning of the definition. For example:

  • wesnoth.game_exclusive_function(parameter) → result

The possible icons are:

  • Available in the game context. Most Lua in Wesnoth runs in the game context, which is initialized when a game begins and destroyed upon victory or loss.
  • Available in the map generation context. This context is created at the game creation screen, generally to generate a map for a scenario.
  • 🔌 Available in the plugins context. There is only one plugins context, which is initialized when Wesnoth launches and remains valid until it shuts down. A plugin is a Lua script loaded via the command-line option --plugin that runs as a coroutine in parallel with the game UI. It can automatically connect to a server and host or join a game. This API is documented at LuaPluginAPI.

Built-in Modules

The following built-in Lua modules are available:

  • 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.
  • 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 Modules

Wesnoth also provides several modules of its own, some of which are loaded by default while others require you to load them as needed. Note: APIs named wesnoth.something, for example wesnoth.scenario, might be part of Core and not a separate 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.
  • map - represents the game map.
  • hex - represents a single hex on the map.

See Also

This page was last edited on 1 July 2023, at 18:12.