X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fclient_lua_api.md;h=1f7c6b0cce6eda69d92081d9b36d3ffbf2415e3b;hb=fd3afbced5410639325e730d5710b8b5039b320e;hp=c9ccbeefacca7309976f877f797d6865ca53e923;hpb=26f4a5c2d1e3d825816188fcd63f6d1f6758ae60;p=minetest.git

diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md
index c9ccbeefa..1f7c6b0cc 100644
--- a/doc/client_lua_api.md
+++ b/doc/client_lua_api.md
@@ -1,4 +1,4 @@
-Minetest Lua Client Modding API Reference 0.4.15
+Minetest Lua Client Modding API Reference 0.4.16
 ================================================
 * More information at <http://www.minetest.net/>
 * Developer Wiki: <http://dev.minetest.net/>
@@ -131,7 +131,7 @@ The `:` prefix can also be used for maintaining backwards compatibility.
 
 Sounds
 ------
-**NOTE: Not fully implemented yet.**
+**NOTE: max_hear_distance and connecting to objects is not implemented.**
 
 Only Ogg Vorbis files are supported.
 
@@ -158,18 +158,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,
     }
@@ -187,8 +181,7 @@ Examples of sound parameter tables:
         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
 * e.g. `""`
@@ -209,7 +202,7 @@ For helper functions see "Vector helpers".
 ### pointed_thing
 * `{type="nothing"}`
 * `{type="node", under=pos, above=pos}`
-* `{type="object", ref=ObjectRef}`
+* `{type="object", id=ObjectID}`
 
 Flag Specifier Format
 ---------------------
@@ -415,6 +408,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
 
@@ -597,17 +591,24 @@ 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.
 * `table.copy(table)`: returns a table
     * returns a deep copy of `table`
 
@@ -646,14 +647,18 @@ Call these functions only at load time!
     * **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_connect(func())`
+    * Called at the end of client connection (when player is loaded onto map)
+* `minetest.register_on_receiving_chat_message(func(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(func(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.unregister_chatcommand(name)`
+    * Unregisters a chatcommands registered with register_chatcommand.
 * `minetest.register_on_death(func())`
     * Called when the local player dies
 * `minetest.register_on_hp_modification(func(hp))`
@@ -672,6 +677,12 @@ Call these functions only at load time!
     * 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(func(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.
 ### Sounds
 * `minetest.sound_play(spec, parameters)`: returns a handle
     * `spec` is a `SimpleSoundSpec`
@@ -682,18 +693,48 @@ Call these functions only at load time!
 * `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_day_count()`
+    * Returns number days elapsed since world was created, accounting for time changes.
+* `minetest.get_timeofday()`
+    * Returns the time of day: `0` for midnight, `0.5` for midday
 
 ### Map
-* `minetest.get_node(pos)`
-    * Returns the node at the given position as table in the format
-      `{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
-      for unloaded areas.
 * `minetest.get_node_or_nil(pos)`
-    * Same as `get_node` but returns `nil` for unloaded areas.
+    * 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 flavour limited areas.
+* `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.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.get_wielded_item()`
     * Returns the itemstack the local player is holding
+* `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 currect 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()`
@@ -701,6 +742,17 @@ Call these functions only at load time!
 * `minetest.disconnect()`
     * Disconnect from the server and exit to main menu.
     * Returns `false` if the client is already disconnecting otherwise returns `true`.
+* `minetest.take_screenshot()`
+    * Take a screenshot.
+* `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
 
 ### Misc.
 * `minetest.parse_json(string[, nullvalue])`: returns something
@@ -741,11 +793,15 @@ 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
+* `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
@@ -754,10 +810,15 @@ Call these functions only at load time!
     * 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` class reference for methods.
+    * 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
@@ -777,7 +838,144 @@ An interface to manipulate minimap on client UI
 * `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
-* `toggle_shape()`: toggles minimap shape to round or square.
+* `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 cameranode.
+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 with same syntax as above
+* `get_fov()`
+    * Returns:
+
+```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. The player is
+not accessible until the client is fully done loading and therefore
+not at module init time.
+
+To get the localplayer handle correctly, use `on_connect()` as follows:
+
+```lua
+local localplayer
+minetest.register_on_connect(function()
+        localplayer = minetest.localplayer
+end)
+```
+
+Methods:
+
+* `get_pos()`
+    * returns current player current position
+* `get_velocity()`
+    * returns player speed vector
+* `get_hp()`
+    * returns player HP
+* `get_name()`
+    * returns player name
+* `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
+    }
+```
+
+* `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_key_pressed()`:
+    * returns last key typed by the player
 
 ### Settings
 An interface to read config files in the format of `minetest.conf`.
@@ -794,7 +992,108 @@ 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 = {}, ...}}`
+
+-----------------
+### 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 = <string>,                -- Mesh name if existant
+		minimap_color = <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>,                -- Color of node *May not exist*
+		palette_name = <string>,        -- 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 = <string>,         -- A string containing "none", "flowing", or "source" *May not exist*
+		liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
+		liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
+		liquid_viscosity = <number>,    -- How fast the liquid flows *May not exist*
+		liquid_renewable = <boolean>,   -- Whether the liquid makes an infinite source *May not exist*
+		liquid_range = <number>,        -- 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 = <table>,    -- If the item is a tool, tool capabiltites 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`)
@@ -802,9 +1101,18 @@ Definition tables
     {
         params = "<name> <privilege>", -- Short parameter description
         description = "Remove privilege from player", -- Full description
-        func = function(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.
+}
+```
 
 Escape sequences
 ----------------
@@ -812,22 +1120,22 @@ 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
+    * `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")`
-* `color.get_background_escape_sequence(color)`
-    * `color` is a ColorString
+* `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.
-* `color.strip_foreground_colors(str)`
+* `minetest.strip_foreground_colors(str)`
     * Removes foreground colors added by `get_color_escape_sequence`.
-* `color.strip_background_colors(str)`
+* `minetest.strip_background_colors(str)`
     * Removes background colors added by `get_background_escape_sequence`.
-* `color.strip_colors(str)`
+* `minetest.strip_colors(str)`
     * Removes all color escape sequences.
 
 `ColorString`
@@ -845,3 +1153,7 @@ Named colors are also supported and are equivalent to
 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.