Sounds
------
-**NOTE: Not fully implemented yet.**
+**NOTE: max_hear_distance and connecting to objects is not implemented.**
Only Ogg Vorbis files are supported.
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,
}
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. `""`
* **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
* 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`
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`](#localplayer) class reference for methods.
### Client Environment
* `minetest.get_player_names()`
* Returns list of player names on server
+* `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
* 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
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
### 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.
+* `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
* `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`.
* 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`)
{
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
----------------
* `color` is a 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)`
+ * Removes foreground colors added by `get_color_escape_sequence`.
+* `color.strip_background_colors(str)`
+ * Removes background colors added by `get_background_escape_sequence`.
+* `color.strip_colors(str)`
+ * Removes all color escape sequences.
+
`ColorString`
-------------
`#RGB` defines a color in hexadecimal format.