LuaAPI/wesnoth

The wesnoth module contains most of the core Wesnoth API. It is always loaded and available.

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.require returns nil on failure, for example if it could not locate the module. If it did locate the module, but the module did not return anything (or returned nil), then wesnoth.require returns an empty table with a metatable that raises an error on any attempt to access it.

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.textdomain

wesnoth.textdomain(domain) → textdomain_constructor

Returns a callable userdata that can be used to construct translatable strings. A typical use is:

local _ = wesnoth.textdomain "example"
wesnoth.alert(_ "This is an example translated string!")

The full syntax for using the result of this function is:

textdomain_constructor(string [, string_plural, number]) → translatable_string

By passing the optional arguments, you can vary the string based on a number that will be substituted into it. As with all Lua functions, the parentheses are optional when passing a single string argument, as in the above example.

The returned translatable string can be treated in many ways like a regular string. Translatable strings can be compared with other translatable strings or concatenated with each other or with regular strings or integers. The length operator also works, though it should be noted that its value may change if the language is changed. If you need to pass a translatable string to a function that doesn't understand them, it can be converted to a regular string with tostring.

wesnoth.wml_actions

(game only) wesnoth.wml_actions.action(wml parameters)
(game only) wesnoth.wml_actions.action ↔ function

This is a hook table that exposes and defines WML actions. Each function in this table corresponds to a single ActionWML tag, allowing you to invoke tags, define custom tags, and even modify the behavior of built-in tags. The single argument to these functions is a WML table, the content of the tag.

function wesnoth.wml_actions.freeze_unit(cfg)
    local unit_id = cfg.id or wml.error "[freeze_unit] expects an id= attribute."
    local unit = wesnoth.units.get(unit_id)
    if unit then unit.moves = 0 end
    wesnoth.units.modify({ id = unit_id }, { moves = 0 })
end

The new tag can now be used in plain WML code.

[freeze_unit]
    id=Delfador
[/freeze_unit]

You can override functions already assigned to the table. This is useful if you need to extend functionality of core tags. For instance, the following script overrides the [print] tag so that messages are displayed with a bigger font.

function wesnoth.wml_actions.print(cfg)
    local modified_cfg = setmetatable({}, {__index = cfg})
    modified_cfg.size = (cfg.size or 12) + 10
    wesnoth.wml_actions.print(modified_cfg)
end

An action handler should be able to handle being called with either a WML table or a WML vconfig userdata. It is recommended to pass the argument through wml.tovconfig before doing anything with it, both in the action's definition and when calling it directly (in case its definition did not do that). The engine always passes a vconfig when calling a WML action.

wesnoth.wml_conditionals

(game only) wesnoth.wml_conditionals.action(wml parameters) → boolean result
(game only) wesnoth.wml_conditionals.action ↔ function

This is a hook table like wesnoth.wml_actions. You can use it to define new ConditionalWML tags that will be recognized in WML when using [if], [show_if], [while], etc., or more generally when wesnoth.eval_conditional is run.

Use it like this:

function wesnoth.wml_conditionals.foo(cfg)
    local bar = cfg.bar or wml.error("[foo] tag did not have 'bar' attribute")

    return (bar == "baz")
end

If this lua code is executed, it would make the following syntax be valid WML in your add-on:

[if]
   [foo]
      bar = $X
   [/foo]
   [then]
      [message]
         # ...
      [/message]
   [/then]
[/if]

wesnoth.interface

(Version 1.15.0 and later only)

A submodule containing functions pertaining to the in-game UI.

wesnoth.units