diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md index 99f341de9..9da417c25 100644 --- a/doc/client_lua_api.md +++ b/doc/client_lua_api.md @@ -1,12 +1,11 @@ -Minetest Lua Client Modding API Reference 5.9.0 -================================================ -* More information at -* Developer Wiki: +# Minetest Lua Client Modding API Reference 5.9.0 -Introduction ------------- +* More information at +* Developer Wiki: -** WARNING: The client API is currently unstable, and may break/change without warning. ** +## Introduction + +> **Warning**: The client API is currently unstable, and may break/change without warning. Content and functionality can be added to Minetest by using Lua scripting in run-time loaded mods. @@ -20,28 +19,29 @@ 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 source code patches on GitHub (https://github.com/minetest/minetest). -Programming in Lua ------------------- +## Programming in Lua + If you have any difficulty in understanding this, please read [Programming in Lua](http://www.lua.org/pil/). -Startup -------- +## Startup + Mods are loaded during client startup from the mod load paths by running the `init.lua` scripts in a shared environment. In order to load client-side mods, the following conditions need to be satisfied: -1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true` +1. `$path_user/minetest.conf` contains the setting `enable_client_modding = true` +2. The client-side mod located in `$path_user/clientmods/` is added to + `$path_user/clientmods/mods.conf` as `load_mod_ = true`. -2) The client-side mod located in `$path_user/clientmods/` is added to - `$path_user/clientmods/mods.conf` as `load_mod_ = true`. - -Note: Depending on the remote server's settings, client-side mods might not +> **Note**: Depending on the remote server's settings, client-side mods might not be loaded or have limited functionality. See setting `csm_restriction_flags` for reference. -Paths ------ + + +# Paths + * `RUN_IN_PLACE=1` (Windows release, local build) * `$path_user`: `` * `$path_share`: `` @@ -53,24 +53,23 @@ Paths * Linux: `$HOME/.minetest` * Windows: `C:/users//AppData/minetest` (maybe) -Mod load path -------------- -Generic: +## Mod Load Path +Generic: +aa * `$path_share/clientmods/` * `$path_user/clientmods/` (User-installed mods) In a run-in-place version (e.g. the distributed windows version): -* `minetest/clientmods/` (User-installed mods) +* `minetest-0.4.x/clientmods/` (User-installed mods) On an installed version on Linux: * `/usr/share/minetest/clientmods/` * `$HOME/.minetest/clientmods/` (User-installed mods) -Modpack support ----------------- +## Modpack Support Mods can be put in a subdirectory, if the parent directory, which otherwise should be a mod, contains a file named `modpack.conf`. @@ -85,15 +84,15 @@ Mod directory structure clientmods ├── modname - │   ├── mod.conf - │   ├── init.lua + │ ├── mod.conf + │ ├── init.lua └── another -### modname +### `modname` The location of this directory. -### mod.conf +### `mod.conf` An (optional) settings file that provides meta information about the mod. @@ -112,12 +111,14 @@ The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on minetest calling the registered callbacks. -**NOTE**: Client mods currently can't provide textures, sounds, or models by -themselves. Any media referenced in function calls must already be loaded -(provided by mods that exist on the server). +> **Note**: Client mods currently can't provide textures, sounds, or models by + themselves. Any media referenced in function calls must already be loaded + (provided by mods that exist on the server). + + + +# Naming Convention For Registered Textual Names -Naming convention for registered textual names ----------------------------------------------- Registered names should generally be in this format: "modname:" ( can have characters a-zA-Z0-9_) @@ -125,7 +126,8 @@ Registered names should generally be in this format: This is to prevent conflicting names from corrupting maps and is enforced by the mod loader. -### Example +## Example + In the mod `experimental`, there is the ideal item/node/entity name `tnt`. So the name should be `experimental:tnt`. @@ -141,9 +143,11 @@ when registering it. The `:` prefix can also be used for maintaining backwards compatibility. -Sounds ------- -**NOTE: Connecting sounds to objects is not implemented.** + + +# Sounds + +> **Note**: Connecting sounds to objects is not implemented. Only Ogg Vorbis files are supported. @@ -185,21 +189,29 @@ Examples of sound parameter tables: pos = {x = 1, y = 2, z = 3}, gain = 1.0, -- default } +-- Play connected to an object, looped +{ + object = , + gain = 1.0, -- default + loop = true, +} ``` Looped sounds must be played locationless. -### SimpleSoundSpec +## `SimpleSoundSpec` + * e.g. `""` * e.g. `"default_place_node"` * e.g. `{}` * e.g. `{name = "default_place_node"}` * e.g. `{name = "default_place_node", gain = 1.0}` -Representations of simple things --------------------------------- -### Position/vector + +# Representations of Simple Things + +## Position/Vector ```lua {x=num, y=num, z=num} @@ -207,30 +219,36 @@ Representations of simple things For helper functions see "Vector helpers". -### pointed_thing +## `pointed_thing` + * `{type="nothing"}` * `{type="node", under=pos, above=pos}` * `{type="object", id=ObjectID}` -Flag Specifier Format ---------------------- + + +# Flag Specifier Format Refer to `lua_api.md`. -Formspec --------- + + +# Formspec Formspec defines a menu. It is a string, with a somewhat strange format. For details, refer to `lua_api.md`. -Spatial Vectors ---------------- + + +# Spatial Vectors Refer to `lua_api.md`. -Helper functions ----------------- + + +# Helper Functions + * `dump2(obj, name="_", dumped={})` * Return object serialized as a string, handles reference loops * `dump(obj, dumped={})` @@ -264,10 +282,11 @@ Helper functions * `table.copy(table)`: returns a table * returns a deep copy of `table` -Minetest namespace reference ------------------------------- -### Utilities + +# Minetest Namespace Reference + +## Utilities * `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod * `minetest.get_modpath(modname)`: returns virtual path of given mod including @@ -278,7 +297,7 @@ Minetest namespace reference * the current gettext locale * the current language code (the same as used for client-side translations) * `minetest.get_version()`: returns a table containing components of the - engine version. Components: + engine version. Components: * `project`: Name of the project, eg, "Minetest" * `string`: Simple version, eg, "1.2.3-dev" * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty" @@ -303,14 +322,16 @@ Minetest namespace reference percent sign followed by two hex digits. See [RFC 3986, section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3). -### Logging +## Logging + * `minetest.debug(...)` * Equivalent to `minetest.log(table.concat({...}, "\t"))` * `minetest.log([level,] text)` * `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`, - `"info"`, or `"verbose"`. Default is `"none"`. + `"info"`, or `"verbose"`. Default is `"none"`. + +## Global Callback Registration Functions -### Global callback registration functions Call these functions only at load time! * `minetest.register_globalstep(function(dtime))` @@ -319,7 +340,7 @@ Call these functions only at load time! * Called just after mods have finished loading. * `minetest.register_on_shutdown(function())` * Called before client shutdown - * **Warning**: If the client terminates abnormally (i.e. crashes), the registered + > **Warning**: If the client terminates abnormally (i.e. crashes), the registered callbacks **will likely not be run**. Data should be saved at semi-frequent intervals as well as on server shutdown. * `minetest.register_on_receiving_chat_message(function(message))` @@ -368,19 +389,21 @@ Call these functions only at load time! * If message comes from a server mod, `sender` field is an empty string. * `minetest.register_on_modchannel_signal(function(channel_name, signal))` * Called when a valid incoming mod channel signal is received - * Signal id permit to react to server mod channel events + * Signal ID permit to react to server mod channel events * Possible values are: - 0: join_ok - 1: join_failed - 2: leave_ok - 3: leave_failed - 4: event_on_not_joined_channel - 5: state_changed + 0: `join_ok` + 1: `join_failed` + 2: `leave_ok` + 3: `leave_failed` + 4: `event_on_not_joined_channel` + 5: `state_changed` * `minetest.register_on_inventory_open(function(inventory))` * Called when the local player open inventory * Newest functions are called first * If any function returns true, inventory doesn't open -### Sounds + +## Sounds + * `minetest.sound_play(spec, parameters)`: returns a handle * `spec` is a `SimpleSoundSpec` * `parameters` is a sound parameter table @@ -393,20 +416,18 @@ Call these functions only at load time! the sound volume. * `gain` the target gain for the fade. -### Timing +## Timing + * `minetest.after(time, func, ...)` * Call the function `func` after `time` seconds, may be fractional * Optional: Variable number of arguments that are passed to `func` - * Jobs set for earlier times are executed earlier. If multiple jobs expire - at exactly the same time, then they expire in the order in which they were - registered. This basically just applies to jobs registered on the same - step with the exact same delay. * `minetest.get_us_time()` * Returns time with microsecond precision. May not return wall time. * `minetest.get_timeofday()` * Returns the time of day: `0` for midnight, `0.5` for midday -### Map +## Map + * `minetest.get_node_or_nil(pos)` * Returns the node at the given position as table in the format `{name="node_name", param1=0, param2=0}`, returns `nil` @@ -461,7 +482,8 @@ Call these functions only at load time! * `minetest.get_node_max_level(pos)` * get max available level for leveled node -### Player +## Player + * `minetest.send_chat_message(message)` * Act as if `message` was typed by the player into the terminal. * `minetest.run_server_chatcommand(cmd, param)` @@ -471,14 +493,16 @@ Call these functions only at load time! * `minetest.localplayer` * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods. -### Privileges +## Privileges + * `minetest.get_privilege_list()` * Returns a list of privileges the current player has in the format `{priv1=true,...}` * `minetest.string_to_privs(str)`: returns `{priv1=true,...}` * `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."` * Convert between two privilege representations -### Client Environment +## Client Environment + * `minetest.get_player_names()` * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server) * `minetest.disconnect()` @@ -489,20 +513,24 @@ Call these functions only at load time! * `minetest.send_respawn()` * Sends a respawn request to the server. -### Storage API +## Storage API + * `minetest.get_mod_storage()`: * returns reference to mod private `StorageRef` * must be called during mod load time -### Mod channels +## Mod Channels + ![Mod channels communication scheme](docs/mod channels.png) * `minetest.mod_channel_join(channel_name)` * Client joins channel `channel_name`, and creates it, if necessary. You should listen from incoming messages with `minetest.register_on_modchannel_message` - call to receive incoming messages. Warning, this function is asynchronous. + call to receive incoming messages. + > **Warning**: This function is asynchronous. + +## Particles -### Particles * `minetest.add_particle(particle definition)` * `minetest.add_particlespawner(particlespawner definition)` @@ -512,7 +540,8 @@ Call these functions only at load time! * `minetest.delete_particlespawner(id)` * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`) -### Misc. +## Misc. + * `minetest.parse_json(string[, nullvalue])`: returns something * Convert a string containing JSON data into the Lua equivalent * `nullvalue`: returned in place of the JSON null; defaults to `nil` @@ -523,10 +552,10 @@ Call these functions only at load time! * Convert a Lua table into a JSON string * styled: Outputs in a human-readable format if this is set, defaults to false * Unserializable things like functions and userdata are saved as null. - * **Warning**: JSON is more strict than the Lua table format. - 1. You can only use strings and positive integers of at least one as keys. - 2. You cannot mix string and integer keys. - This is due to the fact that JSON has two distinct array and object values. + > **Warning**: JSON is more strict than the Lua table format. + > 1. You can only use strings and positive integers of at least one as keys. + > 2. You cannot mix string and integer keys. This is due to the fact that JSON has + > two distinct array and object values. * Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"` * `minetest.serialize(table)`: returns a string * Convert a table containing tables, strings, numbers, booleans and `nil`s @@ -578,33 +607,37 @@ Call these functions only at load time! * `minetest.global_exists(name)` * Checks if a global variable has been set, without triggering a warning. -### UI +## UI + * `minetest.ui.minimap` * Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods. * If client disabled minimap (using enable_minimap setting) this reference will be nil. * `minetest.camera` * Reference to the camera object. See [`Camera`](#camera) class reference for methods. * `minetest.show_formspec(formname, formspec)` : returns true on success - * Shows a formspec to the player + * Shows a formspec to the player * `minetest.display_chat_message(message)` returns true on success - * Shows a chat message to the current player. + * Shows a chat message to the current player. -Setting-related ---------------- + + +# Setting-Related * `minetest.settings`: Settings object containing all of the settings from the - main config file (`minetest.conf`). Check lua_api.md for class reference. + main config file (`minetest.conf`). Check `lua_api.md` for class reference. * `minetest.setting_get_pos(name)`: Loads a setting from the main settings and parses it as a position (in the format `(1,2,3)`). Returns a position or nil. -Class reference ---------------- -### ModChannel + +# Class Reference + +## `ModChannel` An interface to use mod channels on client and server -#### Methods +### Methods + * `leave()`: leave the mod channel. * Client leaves channel `channel_name`. * No more incoming or outgoing messages can be sent to this channel from client mods. @@ -615,10 +648,12 @@ An interface to use mod channels on client and server * If mod channel is not writable or invalid, message will be dropped. * Message size is limited to 65535 characters by protocol. -### Minimap +## Minimap + An interface to manipulate minimap on client UI -#### Methods +### Methods + * `show()`: shows the minimap (if not disabled by server) * `hide()`: hides the minimap * `set_pos(pos)`: sets the minimap position on screen @@ -630,11 +665,13 @@ An interface to manipulate minimap on client UI * `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round) * `get_shape()`: Gets the minimap shape. (0 = square, 1 = round) -### Camera +## Camera + An interface to get or set information about the camera and camera-node. Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil. -#### Methods +### Methods + * `set_camera_mode(mode)` * Pass `0` for first-person, `1` for third person, and `2` for third person front * `get_camera_mode()` @@ -664,7 +701,7 @@ Please do not try to access the reference until the camera is initialized, other * `get_aspect_ratio()` * Returns aspect ratio of screen -### LocalPlayer +## `LocalPlayer` An interface to retrieve information about the player. This object will only be available after the client is initialized. Earlier accesses will yield a `nil` value. @@ -698,7 +735,6 @@ Methods: * returns true if player is swimming in vertical * `get_physics_override()` * returns: - ```lua { speed = float, @@ -709,7 +745,6 @@ Methods: new_move = boolean, } ``` - * `get_override_pos()` * returns override position * `get_last_pos()` @@ -720,7 +755,6 @@ Methods: * returns the player's breath * `get_movement_acceleration()` * returns acceleration of the player in different environments: - ```lua { fast = float, @@ -728,10 +762,8 @@ Methods: default = float, } ``` - * `get_movement_speed()` * returns player's speed in different environments: - ```lua { walk = float, @@ -741,10 +773,8 @@ Methods: climb = float, } ``` - * `get_movement()` * returns player's movement in different environments: - ```lua { liquid_fluidity = float, @@ -753,14 +783,12 @@ Methods: gravity = float, } ``` - * `get_last_look_horizontal()`: * returns last look horizontal angle * `get_last_look_vertical()`: * returns last look vertical angle * `get_control()`: * returns pressed player controls - ```lua { up = boolean, @@ -775,7 +803,6 @@ Methods: place = boolean, } ``` - * `get_armor_groups()` * returns a table with the armor group ratings * `hud_add(definition)` @@ -783,23 +810,20 @@ Methods: * See [`HUD definition`](#hud-definition-hud_add-hud_get) * `hud_get(id)` * returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent. -* `hud_get_all()`: - * Returns a table in the form `{ [id] = HUD definition, [id] = ... }`. - * A mod should keep track of its introduced IDs and only use this to access foreign elements. - * It is discouraged to change foreign HUD elements. * `hud_remove(id)` - * remove the HUD element of the specified id, returns `true` on success + * remove the HUD element of the specified ID, returns `true` on success * `hud_change(id, stat, value)` * change a value of a previously added HUD element * element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir` * Returns `true` on success, otherwise returns `nil` -### Settings +## `Settings` An interface to read config files in the format of `minetest.conf`. It can be created via `Settings(filename)`. -#### Methods +### Methods + * `get(key)`: returns a value * `get_bool(key)`: returns a boolean * `set(key, value)` @@ -809,11 +833,12 @@ It can be created via `Settings(filename)`. * write changes to file * `to_table()`: returns `{[key1]=value1,...}` -### NodeMetaRef +## `NodeMetaRef` Node metadata: reference extra data and functionality stored in a node. Can be obtained via `minetest.get_meta(pos)`. -#### Methods +### Methods + * `get_string(name)` * `get_int(name)` * `get_float(name)` @@ -821,7 +846,7 @@ Can be obtained via `minetest.get_meta(pos)`. * `fields`: key-value storage * `inventory`: `{list1 = {}, ...}}` -### `Raycast` +## `Raycast` A raycast on the map. It works with selection boxes. Can be used as an iterator in a for loop as: @@ -844,19 +869,19 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or * `objects`: if false, only nodes will be returned. Default is true. * `liquids`: if false, liquid nodes won't be returned. Default is false. -#### Methods +### Methods * `next()`: returns a `pointed_thing` with exact pointing location * Returns the next thing pointed by the ray or nil. ------------------ -### Definitions -* `minetest.get_node_def(nodename)` - * Returns [node definition](#node-definition) table of `nodename` -* `minetest.get_item_def(itemstring)` - * Returns item definition table of `itemstring` +# Definitions -#### Node Definition +* `minetest.get_node_def(nodename)` + * Returns [node definition](#node-definition) table of `nodename` +* `minetest.get_item_def(itemstring)` + * Returns item definition table of `itemstring` + +## Node Definition ```lua { @@ -918,7 +943,7 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or } ``` -#### Item Definition +## Item Definition ```lua { @@ -940,9 +965,8 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or node_placement_prediction = string -- Node placed in client until server catches up } ``` ------------------ -### Chat command definition (`register_chatcommand`) +## Chat Command Definition (`register_chatcommand`) ```lua { @@ -953,23 +977,25 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or } ``` -### Server info +## Server Information ```lua { - address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server. - ip = "203.0.113.156", -- The IP address of the server. - port = 30000, -- The port the client is connected to. - protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0. + address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server. + ip = "203.0.113.156", -- The IP address of the server. + port = 30000, -- The port the client is connected to. + protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0. } ``` -### HUD Definition (`hud_add`, `hud_get`) +## HUD Definition (`hud_add`, `hud_get`) Refer to `lua_api.md`. -Escape sequences ----------------- + + +# 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: @@ -992,19 +1018,25 @@ The following functions provide escape sequences: * `minetest.strip_colors(str)` * Removes all color escape sequences. -`ColorString` -------------- + + +# `ColorString` Refer to `lua_api.md`. -`Color` -------------- + + +# `Color` + `{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color. + + + ### Particle definition (`add_particle`) -As documented in `lua_api.md`, except for obvious reasons, the `playername` field is not supported. +As documented in `lua_api.md`, except the `playername` field is not supported. ### `ParticleSpawner` definition (`add_particlespawner`) -As documented in `lua_api.md`, except for obvious reasons, the `playername` field is not supported. +As documented in `lua_api.md`, except the `playername` field is not supported. \ No newline at end of file