Difference between revisions of "LuaAPI"
(Initial draft) |
(Add return value annotations) |
||
| Line 48: | Line 48: | ||
=== wesnoth.dofile === | === wesnoth.dofile === | ||
| − | * '''wesnoth.dofile'''(''file_path'' [, ...]) | + | * '''wesnoth.dofile'''(''file_path'' [, ...]) → ... |
Loads and executes a file. The rules for locating the files are the same as for WML files, except that they require a ''.lua'' extension instead of ''.cfg.'' Any extra parameters to '''dofile''' are forwarded to the script (which can access them via the special <tt>...</tt> variable), and '''dofile''' returns all the values returned by the script. | Loads and executes a file. The rules for locating the files are the same as for WML files, except that they require a ''.lua'' extension instead of ''.cfg.'' Any extra parameters to '''dofile''' are forwarded to the script (which can access them via the special <tt>...</tt> variable), and '''dofile''' returns all the values returned by the script. | ||
| Line 54: | Line 54: | ||
=== wesnoth.require === | === wesnoth.require === | ||
| − | * '''wesnoth.require'''(''module'') | + | * '''wesnoth.require'''(''module'') → ''module_contents'' |
Returns the contents of the specified module, loading it if necessary. The module can either be a simple name or a file path similar to that used by '''wesnoth.dofile'''. In addition, the ''.lua'' extension will automatically be appended if necessary. The module script is invoked with no arguments, and '''wesnoth.require''' then passes back its first return value, discarding any additional ones. If the module is a directory, then all lua files are loaded, and a table containing the resulting modules is returned, with the keys being the filenames minus the ''.lua'' extension. | Returns the contents of the specified module, loading it if necessary. The module can either be a simple name or a file path similar to that used by '''wesnoth.dofile'''. In addition, the ''.lua'' extension will automatically be appended if necessary. The module script is invoked with no arguments, and '''wesnoth.require''' then passes back its first return value, discarding any additional ones. If the module is a directory, then all lua files are loaded, and a table containing the resulting modules is returned, with the keys being the filenames minus the ''.lua'' extension. | ||
| Line 60: | Line 60: | ||
=== wesnoth.read_file === | === wesnoth.read_file === | ||
| − | * '''wesnoth.read_file'''(''file_path'') | + | * '''wesnoth.read_file'''(''file_path'') → ''file_contents'' |
Loads a file into memory and returns it as a string. The rules for locating the files are the same as for WML files, but with no requirements on file extension. If the path points to a directory, it instead returns a table containing a list of directory entries, sorted alphabetically with directories grouped at the beginning. In this case, there is also an '''ndirs''' member which contains the number of entries that are directories, allowing you to easily skip the directories if you wish. | Loads a file into memory and returns it as a string. The rules for locating the files are the same as for WML files, but with no requirements on file extension. If the path points to a directory, it instead returns a table containing a list of directory entries, sorted alphabetically with directories grouped at the beginning. In this case, there is also an '''ndirs''' member which contains the number of entries that are directories, allowing you to easily skip the directories if you wish. | ||
| Line 66: | Line 66: | ||
=== wesnoth.have_file === | === wesnoth.have_file === | ||
| − | * '''wesnoth.have_file'''(''file_path''[, ''only_as_regular_file'']) | + | * '''wesnoth.have_file'''(''file_path''[, ''only_as_regular_file'']) → ''boolean'' |
Checks if a file exists. The rules for locating the files are the same as for WML files. Using the second parameter, you can distinguish regular files from directories. | Checks if a file exists. The rules for locating the files are the same as for WML files. Using the second parameter, you can distinguish regular files from directories. | ||
| Line 72: | Line 72: | ||
=== wesnoth.text_domain === | === wesnoth.text_domain === | ||
| − | * '''wesnoth.textdomain'''(''domain'') | + | * '''wesnoth.textdomain'''(''domain'') → ''textdomain_constructor'' |
Returns a callable userdata that can be used to construct translatable strings. A typical use is: | Returns a callable userdata that can be used to construct translatable strings. A typical use is: | ||
Revision as of 15:33, 3 June 2017
Note: This page is is a work-in-progress and only reflects the current development version. For the equivalent documentation for 1.12, or more complete documentation for 1.13, 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
- 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 paged 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 the 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_member → result
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 will use the string "..." to indicate this. For example:
- wesnoth.variadic_function(required_param [, ...])
Contents
Wesnoth Modules
wesnoth
The wesnoth module contains most of the core Wesnoth API. It is always loaded and available.
wesnoth.dofile
- wesnoth.dofile(file_path [, ...]) → ...
Loads and executes a file. The rules for locating the files are the same as for WML files, except that they require a .lua extension instead of .cfg. Any extra parameters to dofile are forwarded to the script (which can access them via the special ... variable), and dofile returns all the values returned by the script.
wesnoth.require
- wesnoth.require(module) → module_contents
Returns the contents of the specified module, loading it if necessary. The module can either be a simple name or a file path similar to that used by wesnoth.dofile. In addition, the .lua extension will automatically be appended if necessary. The module script is invoked with no arguments, and wesnoth.require then passes back its first return value, discarding any additional ones. If the module is a directory, then all lua files are loaded, and a table containing the resulting modules is returned, with the keys being the filenames minus the .lua extension.
wesnoth.read_file
- wesnoth.read_file(file_path) → file_contents
Loads a file into memory and returns it as a string. The rules for locating the files are the same as for WML files, but with no requirements on file extension. If the path points to a directory, it instead returns a table containing a list of directory entries, sorted alphabetically with directories grouped at the beginning. In this case, there is also an ndirs member which contains the number of entries that are directories, allowing you to easily skip the directories if you wish.
wesnoth.have_file
- wesnoth.have_file(file_path[, only_as_regular_file]) → boolean
Checks if a file exists. The rules for locating the files are the same as for WML files. Using the second parameter, you can distinguish regular files from directories.
wesnoth.text_domain
- wesnoth.textdomain(domain) → textdomain_constructor
Returns a callable userdata that can be used to construct translatable strings. A typical use is:
local _ = wesnoth.textdomain "wesnoth"
wml
The wml module contains functions for working with WML tables.