LuaAPI

From The Battle for Wesnoth Wiki
Revision as of 21:43, 4 July 2021 by Celtic Minstrel (talk | contribs) (→‎Conventions used in this manual: Some reformatting and clarifications; split into subsections)

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. For information on what has changed since 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, 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_member ↔ result
  • some_value.read_only_member → first_result, second_result
  • some_value.write_only_member ← input
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() → iterator ⇒ a, 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.name ↔ function(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 in parentheses at the beginning of the definition. For example:

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


Wesnoth Modules

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.
Retrieved from "https://wiki.wesnoth.org/index.php?title=LuaAPI&oldid=68262"