X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Fclient_lua_api.txt;h=098596481f82b310631dc825caf019ca163eaac4;hb=65047e41921f541b3ee26209040a53025fc1b021;hp=8ce487bf8c8a92b635a60fe2fd191c684fa8507e;hpb=2c19d51409ca903021e0b508e5bc15299c4e51dc;p=minetest.git diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index 8ce487bf8..098596481 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -1,18 +1,20 @@ -Minetest Lua Modding API Reference 0.4.15 -========================================= +Minetest Lua Client Modding API Reference 5.4.0 +================================================ * More information at * Developer Wiki: Introduction ------------ -Content and functionality can be added to Minetest 0.4 by using Lua + +** WARNING: The client API is currently unstable, and may break/change without warning. ** + +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. +Transferring client-sided mods from 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 @@ -28,17 +30,23 @@ 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` + +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 +be loaded or have limited functionality. See setting `csm_restriction_flags` for reference. + Paths ----- * `RUN_IN_PLACE=1` (Windows release, local build) - * `$path_user`: - * Linux: `` - * Windows: `` - * `$path_share` - * Linux: `` - * Windows: `` + * `$path_user`: `` + * `$path_share`: `` * `RUN_IN_PLACE=0`: (Linux release) - * `$path_share` + * `$path_share`: * Linux: `/usr/share/minetest` * Windows: `/minetest-0.4.x` * `$path_user`: @@ -63,65 +71,50 @@ On an installed version on Linux: Modpack support ---------------- + 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. +should be a mod, contains a file named `modpack.conf`. +The file is a key-value store of modpack details. + +* `name`: The modpack name. +* `description`: Description of mod to be shown in the Mods tab of the main + menu. 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 + │   ├── mod.conf + │   ├── init.lua + └── another ### modname -The location of this directory can be fetched by using -`minetest.get_modpath(modname)`. - -### `depends.txt` -List of mods that have to be loaded before loading this mod. - -A single line contains a single modname. -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. +The location of this directory. -### `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. +### mod.conf -### `description.txt` -A File containing description to be shown within mainmenu. +An (optional) settings file that provides meta information about the mod. -### `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. +* `name`: The mod name. Allows Minetest to determine the mod name even if the + folder is wrongly named. +* `description`: Description of mod to be shown in the Mods tab of the main + menu. +* `depends`: A comma separated list of dependencies. These are mods that must be + loaded before this mod. +* `optional_depends`: A comma separated list of optional dependencies. + Like a dependency, but no error if the mod doesn't exist. ### `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. -`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used -to read custom or existing settings at load time, if necessary. - -### `sounds` -Media files (sounds) that will be transferred to the -client and will be available for use by the mod. +**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 ---------------------------------------------- @@ -148,29 +141,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: Connecting sounds to objects is not implemented.** + Only Ogg Vorbis files are supported. For positional playing of sounds, only single-channel (mono) files are @@ -196,18 +170,12 @@ from the available ones of the following files: Examples of sound parameter tables: - -- Play locationless on all clients + -- Play locationless { gain = 1.0, -- default } - -- Play locationless to one player + -- Play locationless, looped { - to_player = name, - gain = 1.0, -- default - } - -- Play locationless to one player, looped - { - to_player = name, gain = 1.0, -- default loop = true, } @@ -215,20 +183,17 @@ Examples of sound parameter tables: { pos = {x = 1, y = 2, z = 3}, gain = 1.0, -- default - max_hear_distance = 32, -- default, uses an euclidean metric } -- Play connected to an object, looped { object = , gain = 1.0, -- default - max_hear_distance = 32, -- default, uses an euclidean metric loop = true, } -Looped sounds must either be connected to an object or played locationless to -one player using `to_player = name,` +Looped sounds must either be connected to an object or played locationless. -### `SimpleSoundSpec` +### SimpleSoundSpec * e.g. `""` * e.g. `"default_place_node"` * e.g. `{}` @@ -244,10 +209,10 @@ 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}` +* `{type="object", id=ObjectID}` Flag Specifier Format --------------------- @@ -284,8 +249,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. @@ -454,6 +418,7 @@ examples. * Clickable button. When clicked, fields will be sent. * `x`, `y` and `name` work as per field * `w` and `h` are the size of the button +* Fixed button height. It will be vertically centred on `h` * `label` is the text on the button * Position and size units are inventory slots @@ -636,26 +601,42 @@ Helper functions * `math.sign(x, tolerance)` * Get the sign of a number. Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`) -* `string.split(str, separator=",", include_empty=false, max_splits=-1, -* sep_is_pattern=false)` +* `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)` * If `max_splits` is negative, do not limit splits. * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex). * e.g. `string:split("a,b", ",") == {"a","b"}` * `string:trim()` * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"` +* `minetest.wrap_text(str, limit)`: returns a string + * Adds new lines to the string to keep it within the specified character limit + * limit: Maximal amount of characters in one line +* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"` + * Convert position to a printable string + Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place. +* `minetest.string_to_pos(string)`: returns a position + * Same but in reverse. Returns `nil` if the string can't be parsed to a position. +* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions + * Converts a string representing an area box into two positions * `minetest.is_yes(arg)` * returns whether `arg` can be interpreted as yes -* `minetest.get_us_time()` - * returns time with microsecond precision. May not return wall time. +* `minetest.is_nan(arg)` + * returns true when the passed number represents NaN. * `table.copy(table)`: returns a table * returns a deep copy of `table` -`minetest` namespace reference +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 + the trailing separator. This is useful to load additional Lua files + contained in your mod: + e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")` +* `minetest.get_language()`: returns two strings + * 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: * `project`: Name of the project, eg, "Minetest" @@ -663,10 +644,18 @@ Helper functions * `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty" Use this for informational purposes only. The information in the returned table does not represent the capabilities of the engine, nor is it - reliable or verifyable. Compatible forks will have a different name and + reliable or verifiable. 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.check_for_falling then ... end`. +* `minetest.sha1(data, [raw])`: returns the sha1 hash of data + * `data`: string of data to hash + * `raw`: return raw bytes instead of hex digits, default: false +* `minetest.get_csm_restrictions()`: returns a table of `Flags` indicating the + restrictions applied to the current mod. + * If a flag in this table is set to true, the feature is RESTRICTED. + * Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`, + `read_nodedefs`, `lookup_nodes`, `read_playerinfo` ### Logging * `minetest.debug(...)` @@ -678,38 +667,200 @@ Helper functions ### Global callback registration functions Call these functions only at load time! -* `minetest.register_globalstep(func(dtime))` +* `minetest.register_globalstep(function(dtime))` * Called every client environment step, usually interval of 0.1s -* `minetest.register_on_shutdown(func())` +* `minetest.register_on_mods_loaded(function())` + * 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 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(func(name, message))` +* `minetest.register_on_receiving_chat_message(function(message))` * Called always when a client receive a message * Return `true` to mark the message as handled, which means that it will not be shown to chat -* `minetest.register_on_sending_chat_message(func(name, message))` +* `minetest.register_on_sending_chat_message(function(message))` * Called always when a client send a message from chat * Return `true` to mark the message as handled, which means that it will not be sent to server * `minetest.register_chatcommand(cmd, chatcommand definition)` * Adds definition to minetest.registered_chatcommands -* `minetest.register_on_death(func())` - * Called when player die -* `minetest.register_on_hp_modification(func(hp))` +* `minetest.unregister_chatcommand(name)` + * Unregisters a chatcommands registered with register_chatcommand. +* `minetest.register_on_chatcommand(function(command, params))` + * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands` + is checked to see if that the command exists, but after the input is parsed. + * Return `true` to mark the command as handled, which means that the default + handlers will be prevented. +* `minetest.register_on_death(function())` + * Called when the local player dies +* `minetest.register_on_hp_modification(function(hp))` * Called when server modified player's HP -* `minetest.register_on_damage_taken(func(hp))` - * Called when player take damages - +* `minetest.register_on_damage_taken(function(hp))` + * Called when the local player take damages +* `minetest.register_on_formspec_input(function(formname, fields))` + * Called when a button is pressed in the local player's inventory form + * Newest functions are called first + * If function returns `true`, remaining functions are not called +* `minetest.register_on_dignode(function(pos, node))` + * Called when the local player digs a node + * Newest functions are called first + * If any function returns true, the node isn't dug +* `minetest.register_on_punchnode(function(pos, node))` + * Called when the local player punches a node + * Newest functions are called first + * If any function returns true, the punch is ignored +* `minetest.register_on_placenode(function(pointed_thing, node))` + * Called when a node has been placed +* `minetest.register_on_item_use(function(item, pointed_thing))` + * Called when the local player uses an item. + * Newest functions are called first. + * If any function returns true, the item use is not sent to server. +* `minetest.register_on_modchannel_message(function(channel_name, sender, message))` + * Called when an incoming mod channel message is received + * You must have joined some channels before, and server must acknowledge the + join request. + * 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 + * Possible values are: + 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 * `minetest.sound_play(spec, parameters)`: returns a handle * `spec` is a `SimpleSoundSpec` * `parameters` is a sound parameter table * `minetest.sound_stop(handle)` + * `handle` is a handle returned by `minetest.sound_play` +* `minetest.sound_fade(handle, step, gain)` + * `handle` is a handle returned by `minetest.sound_play` + * `step` determines how fast a sound will fade. + Negative step will lower the sound volume, positive step will increase + the sound volume. + * `gain` the target gain for the fade. ### 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` +* `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 +* `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` + for unloaded areas or flavor limited areas. +* `minetest.get_node_light(pos, timeofday)` + * Gets the light value at the given position. Note that the light value + "inside" the node at the given position is returned, so you usually want + to get the light value of a neighbor. + * `pos`: The position where to measure the light. + * `timeofday`: `nil` for current time, `0` for night, `0.5` for day + * Returns a number between `0` and `15` or `nil` +* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil` + * `radius`: using a maximum metric + * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` + * `search_center` is an optional boolean (default: `false`) + If true `pos` is also checked for the nodes +* `minetest.find_nodes_in_area(pos1, pos2, nodenames, [grouped])` + * `pos1` and `pos2` are the min and max positions of the area to search. + * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` + * If `grouped` is true the return value is a table indexed by node name + which contains lists of positions. + * If `grouped` is false or absent the return values are as follows: + first value: Table with all node positions + second value: Table with the count of each node with the node name + as index + * Area volume is limited to 4,096,000 nodes +* `minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)`: returns a + list of positions. + * `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"` + * Return value: Table with all node positions with a node air above + * Area volume is limited to 4,096,000 nodes +* `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos` + * Checks if there is anything other than air between pos1 and pos2. + * Returns false if something is blocking the sight. + * Returns the position of the blocking node when `false` + * `pos1`: First position + * `pos2`: Second position +* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast` + * Creates a `Raycast` object. + * `pos1`: start of the ray + * `pos2`: end of the ray + * `objects`: if false, only nodes will be returned. Default is `true`. + * `liquids`: if false, liquid nodes won't be returned. Default is `false`. + +* `minetest.find_nodes_with_meta(pos1, pos2)` + * Get a table of positions of nodes that have metadata within a region + {pos1, pos2}. +* `minetest.get_meta(pos)` + * Get a `NodeMetaRef` at that position +* `minetest.get_node_level(pos)` + * get level of leveled node (water, snow) +* `minetest.get_node_max_level(pos)` + * get max available level for leveled node + +### Player +* `minetest.send_chat_message(message)` + * Act as if `message` was typed by the player into the terminal. +* `minetest.run_server_chatcommand(cmd, param)` + * Alias for `minetest.send_chat_message("/" .. cmd .. " " .. param)` +* `minetest.clear_out_chat_queue()` + * Clears the out chat queue +* `minetest.localplayer` + * Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods. + +### 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 +* `minetest.get_player_names()` + * Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server) +* `minetest.disconnect()` + * Disconnect from the server and exit to main menu. + * Returns `false` if the client is already disconnecting otherwise returns `true`. +* `minetest.get_server_info()` + * Returns [server info](#server-info). +* `minetest.send_respawn()` + * Sends a respawn request to the server. + +### Storage API +* `minetest.get_mod_storage()`: + * returns reference to mod private `StorageRef` + * must be called during mod load time + +### 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. + +### Particles +* `minetest.add_particle(particle definition)` + +* `minetest.add_particlespawner(particlespawner definition)` + * Add a `ParticleSpawner`, an object that spawns an amount of particles over `time` seconds + * Returns an `id`, and -1 if adding didn't succeed + +* `minetest.delete_particlespawner(id)` + * Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`) ### Misc. * `minetest.parse_json(string[, nullvalue])`: returns something @@ -750,15 +901,231 @@ Call these functions only at load time! * See documentation on `minetest.compress()` for supported compression methods. * currently supported. * `...` indicates method-specific arguments. Currently, no methods use this. +* `minetest.rgba(red, green, blue[, alpha])`: returns a string + * Each argument is a 8 Bit unsigned integer + * Returns the ColorString from rgb or rgba values + * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"` * `minetest.encode_base64(string)`: returns string encoded in base64 * Encodes a string in base64. * `minetest.decode_base64(string)`: returns string * Decodes a string encoded in base64. +* `minetest.gettext(string)` : returns string + * look up the translation of a string in the gettext message catalog +* `fgettext_ne(string, ...)` + * 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 minetest.formspec_escape before returning result +* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position + * returns the exact position on the surface of a pointed node +* `minetest.global_exists(name)` + * Checks if a global variable has been set, without triggering a warning. + +### 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 +* `minetest.display_chat_message(message)` returns true on success + * Shows a chat message to the current player. Class reference --------------- -### `Settings` +### ModChannel + +An interface to use mod channels on client and server + +#### 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. + * This invalidate all future object usage + * Ensure your set mod_channel to nil after that to free Lua resources +* `is_writeable()`: returns true if channel is writable and mod can send over it. +* `send_all(message)`: Send `message` though the mod channel. + * If mod channel is not writable or invalid, message will be dropped. + * Message size is limited to 65535 characters by protocol. + +### Minimap +An interface to manipulate minimap on client UI + +#### Methods +* `show()`: shows the minimap (if not disabled by server) +* `hide()`: hides the minimap +* `set_pos(pos)`: sets the minimap position on screen +* `get_pos()`: returns the minimap current position +* `set_angle(deg)`: sets the minimap angle in degrees +* `get_angle()`: returns the current minimap angle in degrees +* `set_mode(mode)`: sets the minimap mode (0 to 6) +* `get_mode()`: returns the current minimap mode +* `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round) +* `get_shape()`: Gets the minimap shape. (0 = square, 1 = round) + +### 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 +* `set_camera_mode(mode)` + * Pass `0` for first-person, `1` for third person, and `2` for third person front +* `get_camera_mode()` + * Returns 0, 1, or 2 as described above +* `get_fov()` + * Returns a table with X, Y, maximum and actual FOV in degrees: + +```lua + { + x = number, + y = number, + max = number, + actual = number + } +``` + +* `get_pos()` + * Returns position of camera with view bobbing +* `get_offset()` + * Returns eye offset vector +* `get_look_dir()` + * Returns eye direction unit vector +* `get_look_vertical()` + * Returns pitch in radians +* `get_look_horizontal()` + * Returns yaw in radians +* `get_aspect_ratio()` + * Returns aspect ratio of screen + +### 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. + +Methods: + +* `get_pos()` + * returns current player current position +* `get_velocity()` + * returns player speed vector +* `get_hp()` + * returns player HP +* `get_name()` + * returns player name +* `get_wield_index()` + * returns the index of the wielded item +* `get_wielded_item()` + * returns the itemstack the player is holding +* `is_attached()` + * returns true if player is attached +* `is_touching_ground()` + * returns true if player touching ground +* `is_in_liquid()` + * returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface) +* `is_in_liquid_stable()` + * returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player) +* `get_liquid_viscosity()` + * returns liquid viscosity (Gets the viscosity of liquid to calculate friction) +* `is_climbing()` + * returns true if player is climbing +* `swimming_vertical()` + * returns true if player is swimming in vertical +* `get_physics_override()` + * returns: + +```lua + { + speed = float, + jump = float, + gravity = float, + sneak = boolean, + sneak_glitch = boolean, + new_move = boolean, + } +``` + +* `get_override_pos()` + * returns override position +* `get_last_pos()` + * returns last player position before the current client step +* `get_last_velocity()` + * returns last player speed +* `get_breath()` + * returns the player's breath +* `get_movement_acceleration()` + * returns acceleration of the player in different environments: + +```lua + { + fast = float, + air = float, + default = float, + } +``` + +* `get_movement_speed()` + * returns player's speed in different environments: + +```lua + { + walk = float, + jump = float, + crouch = float, + fast = float, + climb = float, + } +``` + +* `get_movement()` + * returns player's movement in different environments: + +```lua + { + liquid_fluidity = float, + liquid_sink = float, + liquid_fluidity_smooth = float, + 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, + down = boolean, + left = boolean, + right = boolean, + jump = boolean, + aux1 = boolean, + sneak = boolean, + zoom = boolean, + dig = boolean, + place = boolean, + } +``` + +* `get_armor_groups()` + * returns a table with the armor group ratings +* `hud_add(definition)` + * add a HUD element described by HUD def, returns ID number on success and `nil` on failure. + * 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_remove(id)` + * 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 An interface to read config files in the format of `minetest.conf`. It can be created via `Settings(filename)`. @@ -773,7 +1140,134 @@ It can be created via `Settings(filename)`. * write changes to file * `to_table()`: returns `{[key1]=value1,...}` -Definition tables +### NodeMetaRef +Node metadata: reference extra data and functionality stored in a node. +Can be obtained via `minetest.get_meta(pos)`. + +#### Methods +* `get_string(name)` +* `get_int(name)` +* `get_float(name)` +* `to_table()`: returns `nil` or a table with keys: + * `fields`: key-value storage + * `inventory`: `{list1 = {}, ...}}` + +### `Raycast` + +A raycast on the map. It works with selection boxes. +Can be used as an iterator in a for loop as: + + local ray = Raycast(...) + for pointed_thing in ray do + ... + end + +The map is loaded as the ray advances. If the map is modified after the +`Raycast` is created, the changes may or may not have an effect on the object. + +It can be created via `Raycast(pos1, pos2, objects, liquids)` or +`minetest.raycast(pos1, pos2, objects, liquids)` where: + +* `pos1`: start of the ray +* `pos2`: end of the ray +* `objects`: if false, only nodes will be returned. Default is true. +* `liquids`: if false, liquid nodes won't be returned. Default is false. + +#### 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` + +#### Node Definition + +```lua + { + has_on_construct = bool, -- Whether the node has the on_construct callback defined + has_on_destruct = bool, -- Whether the node has the on_destruct callback defined + has_after_destruct = bool, -- Whether the node has the after_destruct callback defined + name = string, -- The name of the node e.g. "air", "default:dirt" + groups = table, -- The groups of the node + paramtype = string, -- Paramtype of the node + paramtype2 = string, -- ParamType2 of the node + drawtype = string, -- Drawtype of the node + mesh = , -- Mesh name if existant + minimap_color = , -- Color of node on minimap *May not exist* + visual_scale = number, -- Visual scale of node + alpha = number, -- Alpha of the node. Only used for liquids + color = , -- Color of node *May not exist* + palette_name = , -- Filename of palette *May not exist* + palette = <{ -- List of colors + Color, + Color + }>, + waving = number, -- 0 of not waving, 1 if waving + connect_sides = number, -- Used for connected nodes + connects_to = { -- List of nodes to connect to + "node1", + "node2" + }, + post_effect_color = Color, -- Color overlayed on the screen when the player is in the node + leveled = number, -- Max level for node + sunlight_propogates = bool, -- Whether light passes through the block + light_source = number, -- Light emitted by the block + is_ground_content = bool, -- Whether caves should cut through the node + walkable = bool, -- Whether the player collides with the node + pointable = bool, -- Whether the player can select the node + diggable = bool, -- Whether the player can dig the node + climbable = bool, -- Whether the player can climb up the node + buildable_to = bool, -- Whether the player can replace the node by placing a node on it + rightclickable = bool, -- Whether the player can place nodes pointing at this node + damage_per_second = number, -- HP of damage per second when the player is in the node + liquid_type = , -- A string containing "none", "flowing", or "source" *May not exist* + liquid_alternative_flowing = , -- Alternative node for liquid *May not exist* + liquid_alternative_source = , -- Alternative node for liquid *May not exist* + liquid_viscosity = , -- How fast the liquid flows *May not exist* + liquid_renewable = , -- Whether the liquid makes an infinite source *May not exist* + liquid_range = , -- How far the liquid flows *May not exist* + drowning = bool, -- Whether the player will drown in the node + floodable = bool, -- Whether nodes will be replaced by liquids (flooded) + node_box = table, -- Nodebox to draw the node with + collision_box = table, -- Nodebox to set the collision area + selection_box = table, -- Nodebox to set the area selected by the player + sounds = { -- Table of sounds that the block makes + sound_footstep = SimpleSoundSpec, + sound_dig = SimpleSoundSpec, + sound_dug = SimpleSoundSpec + }, + legacy_facedir_simple = bool, -- Whether to use old facedir + legacy_wallmounted = bool -- Whether to use old wallmounted + } +``` + +#### Item Definition + +```lua + { + name = string, -- Name of the item e.g. "default:stone" + description = string, -- Description of the item e.g. "Stone" + type = string, -- Item type: "none", "node", "craftitem", "tool" + inventory_image = string, -- Image in the inventory + wield_image = string, -- Image in wieldmesh + palette_image = string, -- Image for palette + color = Color, -- Color for item + wield_scale = Vector, -- Wieldmesh scale + stack_max = number, -- Number of items stackable together + usable = bool, -- Has on_use callback defined + liquids_pointable = bool, -- Whether you can point at liquids with the item + tool_capabilities = , -- If the item is a tool, tool capabilities of the item + groups = table, -- Groups of the item + sound_place = SimpleSoundSpec, -- Sound played when placed + sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed + node_placement_prediction = string -- Node placed in client until server catches up + } +``` ----------------- ### Chat command definition (`register_chatcommand`) @@ -781,7 +1275,237 @@ 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. - -- Returns boolean success and text output. + func = function(param), -- Called when command is run. + -- Returns boolean success and text output. + } +### Server info +```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. +} +``` + +### HUD Definition (`hud_add`, `hud_get`) +```lua + { + hud_elem_type = "image", -- see HUD element types, default "text" + -- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory" + position = {x=0.5, y=0.5}, + -- ^ Left corner position of element, default `{x=0,y=0}`. + name = "", -- default "" + scale = {x=2, y=2}, -- default {x=0,y=0} + text = "", -- default "" + number = 2, -- default 0 + item = 3, -- default 0 + -- ^ Selected item in inventory. 0 for no item selected. + direction = 0, -- default 0 + -- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top + alignment = {x=0, y=0}, -- default {x=0, y=0} + -- ^ See "HUD Element Types" + offset = {x=0, y=0}, -- default {x=0, y=0} + -- ^ See "HUD Element Types" + size = { x=100, y=100 }, -- default {x=0, y=0} + -- ^ Size of element in pixels + } +``` + +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: +* `minetest.get_color_escape_sequence(color)`: + * `color` is a [ColorString](#colorstring) + * The escape sequence sets the text color to `color` +* `minetest.colorize(color, message)`: + * Equivalent to: + `minetest.get_color_escape_sequence(color) .. + message .. + minetest.get_color_escape_sequence("#ffffff")` +* `minetest.get_background_escape_sequence(color)` + * `color` is a [ColorString](#colorstring) + * The escape sequence sets the background of the whole text element to + `color`. Only defined for item descriptions and tooltips. +* `minetest.strip_foreground_colors(str)` + * Removes foreground colors added by `get_color_escape_sequence`. +* `minetest.strip_background_colors(str)` + * Removes background colors added by `get_background_escape_sequence`. +* `minetest.strip_colors(str)` + * Removes all color escape sequences. + +`ColorString` +------------- +`#RGB` defines a color in hexadecimal format. + +`#RGBA` defines a color in hexadecimal format and alpha channel. + +`#RRGGBB` defines a color in hexadecimal format. + +`#RRGGBBAA` defines a color in hexadecimal format and alpha channel. + +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 hexadecimal digits. + +`Color` +------------- +`{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color. + +HUD element types +----------------- +The position field is used for all element types. + +To account for differing resolutions, the position coordinates are the percentage +of the screen, ranging in value from `0` to `1`. + +The name field is not yet used, but should contain a description of what the +HUD element represents. The direction field is the direction in which something +is drawn. + +`0` draws from left to right, `1` draws from right to left, `2` draws from +top to bottom, and `3` draws from bottom to top. + +The `alignment` field specifies how the item will be aligned. It ranges from `-1` to `1`, +with `0` being the center, `-1` is moved to the left/up, and `1` is to the right/down. +Fractional values can be used. + +The `offset` field specifies a pixel offset from the position. Contrary to position, +the offset is not scaled to screen size. This allows for some precisely-positioned +items in the HUD. + +**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling factor! + +Below are the specific uses for fields in each type; fields not listed for that type are ignored. + +**Note**: Future revisions to the HUD API may be incompatible; the HUD API is still +in the experimental stages. + +### `image` +Displays an image on the HUD. + +* `scale`: The scale of the image, with 1 being the original texture size. + Only the X coordinate scale is used (positive values). + Negative values represent that percentage of the screen it + should take; e.g. `x=-100` means 100% (width). +* `text`: The name of the texture that is displayed. +* `alignment`: The alignment of the image. +* `offset`: offset in pixels from position. + +### `text` +Displays text on the HUD. + +* `scale`: Defines the bounding rectangle of the text. + A value such as `{x=100, y=100}` should work. +* `text`: The text to be displayed in the HUD element. +* `number`: An integer containing the RGB value of the color used to draw the text. + Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. +* `alignment`: The alignment of the text. +* `offset`: offset in pixels from position. + +### `statbar` +Displays a horizontal bar made up of half-images. + +* `text`: The name of the texture that is used. +* `number`: The number of half-textures that are displayed. + If odd, will end with a vertically center-split texture. +* `direction` +* `offset`: offset in pixels from position. +* `size`: If used, will force full-image size to this value (override texture pack image size) + +### `inventory` +* `text`: The name of the inventory list to be displayed. +* `number`: Number of items in the inventory to be displayed. +* `item`: Position of item that is selected. +* `direction` +* `offset`: offset in pixels from position. + +### `waypoint` + +Displays distance to selected world position. + +* `name`: The name of the waypoint. +* `text`: Distance suffix. Can be blank. +* `precision`: Waypoint precision, integer >= 0. Defaults to 10. + If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`. + When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point. + `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`). + `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on: + `precision = n` will show multiples of `1/n` +* `number:` An integer containing the RGB value of the color used to draw the + text. +* `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. +* `alignment`: The alignment of the waypoint. + +### `image_waypoint` + +Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint. + +* `scale`: The scale of the image, with 1 being the original texture size. + Only the X coordinate scale is used (positive values). + Negative values represent that percentage of the screen it + should take; e.g. `x=-100` means 100% (width). +* `text`: The name of the texture that is displayed. +* `alignment`: The alignment of the image. +* `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. + +### Particle definition (`add_particle`) + + { + pos = {x=0, y=0, z=0}, + velocity = {x=0, y=0, z=0}, + acceleration = {x=0, y=0, z=0}, + -- ^ Spawn particle at pos with velocity and acceleration + expirationtime = 1, + -- ^ Disappears after expirationtime seconds + size = 1, + collisiondetection = false, + -- ^ collisiondetection: if true collides with physical objects + collision_removal = false, + -- ^ collision_removal: if true then particle is removed when it collides, + -- ^ requires collisiondetection = true to have any effect + vertical = false, + -- ^ vertical: if true faces player using y axis only + texture = "image.png", + -- ^ Uses texture (string) + animation = {Tile Animation definition}, + -- ^ optional, specifies how to animate the particle texture + glow = 0 + -- ^ optional, specify particle self-luminescence in darkness + } + +### `ParticleSpawner` definition (`add_particlespawner`) + + { + amount = 1, + time = 1, + -- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base + minpos = {x=0, y=0, z=0}, + maxpos = {x=0, y=0, z=0}, + minvel = {x=0, y=0, z=0}, + maxvel = {x=0, y=0, z=0}, + minacc = {x=0, y=0, z=0}, + maxacc = {x=0, y=0, z=0}, + minexptime = 1, + maxexptime = 1, + minsize = 1, + maxsize = 1, + -- ^ The particle's properties are random values in between the bounds: + -- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration), + -- ^ minsize/maxsize, minexptime/maxexptime (expirationtime) + collisiondetection = false, + -- ^ collisiondetection: if true uses collision detection + collision_removal = false, + -- ^ collision_removal: if true then particle is removed when it collides, + -- ^ requires collisiondetection = true to have any effect + vertical = false, + -- ^ vertical: if true faces player using y axis only + texture = "image.png", + -- ^ Uses texture (string) }