X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Fclient_lua_api.md;h=b76a406eaf594568c32bb74581dca072f5ce3330;hb=ae0d8f74d747fab2fbe5b4553818e0f938e3289d;hp=c9ccbeefacca7309976f877f797d6865ca53e923;hpb=26f4a5c2d1e3d825816188fcd63f6d1f6758ae60;p=minetest.git diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md index c9ccbeefa..b76a406ea 100644 --- a/doc/client_lua_api.md +++ b/doc/client_lua_api.md @@ -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. `""` @@ -646,6 +639,8 @@ 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_connect(func())` + * Called at the end of client connection (when player is loaded onto map) * `minetest.register_on_receiving_chat_message(func(name, 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 @@ -672,6 +667,8 @@ 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 ### Sounds * `minetest.sound_play(spec, parameters)`: returns a handle * `spec` is a `SimpleSoundSpec` @@ -690,10 +687,14 @@ Call these functions only at load time! for unloaded areas. * `minetest.get_node_or_nil(pos)` * Same as `get_node` but returns `nil` for unloaded areas. +* `minetest.get_meta(pos)` + * Get a `NodeMetaRef` at that position ### Player * `minetest.get_wielded_item()` * Returns the itemstack the local player is holding +* `minetest.localplayer` + * Reference to the LocalPlayer object. See `LocalPlayer` class reference for methods. ### Client Environment * `minetest.get_player_names()` @@ -701,6 +702,10 @@ 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). ### Misc. * `minetest.parse_json(string[, nullvalue])`: returns something @@ -777,7 +782,120 @@ 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) + +### 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_look_dir()` + * returns look direction vector +* `get_look_horizontal()` + * returns look horizontal angle +* `get_look_vertical()` + * returns look vertical angle +* `get_eye_pos()` + * returns the player's eye position +* `get_eye_offset()` + * returns the player's eye shift vector +* `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 +912,18 @@ 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 = {}, ...}}` + ----------------- ### Chat command definition (`register_chatcommand`) @@ -802,9 +931,18 @@ Definition tables { params = " ", -- 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 ----------------