diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md index ced1a40a4..f7a1094f0 100644 --- a/doc/client_lua_api.md +++ b/doc/client_lua_api.md @@ -8,14 +8,13 @@ Introduction **WARNING: The client API is currently unstable, and may break/change without warning.** -Content and functionality can be added to Minetest 0.4 by using Lua +Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua scripting in run-time loaded mods. A mod is a self-contained bunch of scripts, textures and other related things that is loaded by and interfaces with Minetest. -Mods are contained and ran solely on the server side. Definitions and media -files are automatically transferred to the client. +Transfering client-sided mods form the server to the client is planned, but not implemented yet. If you see a deficiency in the API, feel free to attempt to add the functionality in the engine and API. You can send such improvements as @@ -66,6 +65,8 @@ On an installed version on Linux: Modpack support ---------------- +**NOTE: Not implemented yet.** + Mods can be put in a subdirectory, if the parent directory, which otherwise should be a mod, contains a file named `modpack.txt`. This file shall be empty, except for lines starting with `#`, which are comments. @@ -73,28 +74,16 @@ empty, except for lines starting with `#`, which are comments. Mod directory structure ------------------------ - mods - |-- modname - | |-- depends.txt - | |-- screenshot.png - | |-- description.txt - | |-- settingtypes.txt - | |-- init.lua - | |-- models - | |-- textures - | | |-- modname_stuff.png - | | `-- modname_something_else.png - | |-- sounds - | |-- media - | `-- - `-- another - + clientmods + ├── modname + | ├── depends.txt + | ├── init.lua + └── another ### modname -The location of this directory can be fetched by using -`minetest.get_modpath(modname)`. +The location of this directory. -### `depends.txt` +### depends.txt List of mods that have to be loaded before loading this mod. A single line contains a single modname. @@ -103,18 +92,7 @@ Optional dependencies can be defined by appending a question mark to a single modname. Their meaning is that if the specified mod is missing, that does not prevent this mod from being loaded. -### `screenshot.png` -A screenshot shown in the mod manager within the main menu. It should -have an aspect ratio of 3:2 and a minimum size of 300×200 pixels. - -### `description.txt` -A File containing description to be shown within mainmenu. - -### `settingtypes.txt` -A file in the same format as the one in builtin. It will be parsed by the -settings menu and the settings will be displayed in the "Mods" category. - -### `init.lua` +### init.lua The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on minetest calling the registered callbacks. @@ -151,29 +129,10 @@ when registering it. The `:` prefix can also be used for maintaining backwards compatibility. -### Aliases -Aliases can be added by using `minetest.register_alias(name, convert_to)` or -`minetest.register_alias_force(name, convert_to). - -This will make Minetest to convert things called name to things called -`convert_to`. - -The only difference between `minetest.register_alias` and -`minetest.register_alias_force` is that if an item called `name` exists, -`minetest.register_alias` will do nothing while -`minetest.register_alias_force` will unregister it. - -This can be used for maintaining backwards compatibility. - -This can be also used for setting quick access names for things, e.g. if -you have an item called `epiclylongmodname:stuff`, you could do - - minetest.register_alias("stuff", "epiclylongmodname:stuff") - -and be able to use `/giveme stuff`. - Sounds ------ +**NOTE: Not fully implemented yet.** + Only Ogg Vorbis files are supported. For positional playing of sounds, only single-channel (mono) files are @@ -231,7 +190,7 @@ Examples of sound parameter tables: Looped sounds must either be connected to an object or played locationless to one player using `to_player = name,` -### `SimpleSoundSpec` +### SimpleSoundSpec * e.g. `""` * e.g. `"default_place_node"` * e.g. `{}` @@ -247,7 +206,7 @@ Representations of simple things For helper functions see "Vector helpers". -### `pointed_thing` +### pointed_thing * `{type="nothing"}` * `{type="node", under=pos, above=pos}` * `{type="object", ref=ObjectRef}` @@ -287,8 +246,7 @@ since, by default, no schematic attributes are set. Formspec -------- -Formspec defines a menu. Currently not much else than inventories are -supported. It is a string, with a somewhat strange format. +Formspec defines a menu. It is a string, with a somewhat strange format. Spaces and newlines can be inserted between the blocks, as is used in the examples. @@ -653,7 +611,7 @@ Helper functions * `table.copy(table)`: returns a table * returns a deep copy of `table` -`minetest` namespace reference +Minetest namespace reference ------------------------------ ### Utilities @@ -669,7 +627,7 @@ Helper functions reliable or verifyable. Compatible forks will have a different name and version entirely. To check for the presence of engine features, test whether the functions exported by the wanted features exist. For example: - `if core.nodeupdate then ... end`. + `if minetest.nodeupdate then ... end`. ### Logging * `minetest.debug(...)` @@ -784,24 +742,26 @@ Call these functions only at load time! * Encodes a string in base64. * `minetest.decode_base64(string)`: returns string * Decodes a string encoded in base64. -* `core.gettext(string) : returns string +* `minetest.gettext(string) : returns string * look up the translation of a string in the gettext message catalog * `fgettext_ne(string, ...)` - * call core.gettext(string), replace "$1"..."$9" with the given + * call minetest.gettext(string), replace "$1"..."$9" with the given extra arguments and return the result * `fgettext(string, ...)` : returns string - * same as fgettext_ne(), but calls core.formspec_escape before returning result + * same as fgettext_ne(), but calls minetest.formspec_escape before returning result ### UI * `minetest.ui.minimap` * Reference to the minimap object. See `Minimap` class reference for methods. -* `show_formspec(formname, formspec)` : returns true on success +* `minetest.show_formspec(formname, formspec)` : returns true on success * Shows a formspec to the player +* `minetest.display_chat_message(message)` returns true on success + * Shows a chat message to the current player. Class reference --------------- -### `Minimap` +### Minimap An interface to manipulate minimap on client UI * `show()`: shows the minimap (if not disabled by server) @@ -814,7 +774,7 @@ An interface to manipulate minimap on client UI * `get_mode()`: returns the current minimap mode * `toggle_shape()`: toggles minimap shape to round or square. -### `Settings` +### Settings An interface to read config files in the format of `minetest.conf`. It can be created via `Settings(filename)`. @@ -837,8 +797,7 @@ Definition tables { params = " ", -- Short parameter description description = "Remove privilege from player", -- Full description - privs = {privs=true}, -- Require the "privs" privilege to run - func = function(name, param), -- Called when command is run. + func = function(param), -- Called when command is run. -- Returns boolean success and text output. } @@ -847,14 +806,14 @@ Escape sequences Most text can contain escape sequences, that can for example color the text. There are a few exceptions: tab headers, dropdowns and vertical labels can't. The following functions provide escape sequences: -* `core.get_color_escape_sequence(color)`: +* `minetest.get_color_escape_sequence(color)`: * `color` is a ColorString * The escape sequence sets the text color to `color` -* `core.colorize(color, message)`: +* `minetest.colorize(color, message)`: * Equivalent to: - `core.get_color_escape_sequence(color) .. + `minetest.get_color_escape_sequence(color) .. message .. - core.get_color_escape_sequence("#ffffff")` + minetest.get_color_escape_sequence("#ffffff")` * `color.get_background_escape_sequence(color)` * `color` is a ColorString * The escape sequence sets the background of the whole text element to @@ -874,4 +833,4 @@ Named colors are also supported and are equivalent to [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors). To specify the value of the alpha channel, append `#AA` to the end of the color name (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha -value must (always) be two hexadecima +value must (always) be two hexadecimal digits.