-Minetest Lua Client Modding API Reference 0.4.15
+Minetest Lua Client Modding API Reference 0.5.0
================================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
### pointed_thing
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
-* `{type="object", ref=ObjectRef}`
+* `{type="object", id=ObjectID}`
Flag Specifier Format
---------------------
* 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
* `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`
reliable or verifyable. 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 minetest.nodeupdate then ... end`.
+ `if minetest.check_for_falling then ... end`.
### Logging
* `minetest.debug(...)`
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))`
+* `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))`
* 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.
+* `minetest.register_on_modchannel_message(func(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(func(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(func(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`
* `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`
- * returns LocalPlayer handle. See LocalPlayer below.
+ * 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()`
* `minetest.disconnect()`
* Disconnect from the server and exit to main menu.
* Returns `false` if the client is already disconnecting otherwise returns `true`.
-* `minetest.get_protocol_version()`
- * Returns the protocol version of the server.
- * Might not be accurate at start up as the client might not be connected to the server yet, in that case it will return 0.
+* `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
+
+### Mod channels
+
+
+* `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.
+ * You should use a minetest.register_on_connect(function() ... end) to perform
+ a successful channel join on client startup.
### Misc.
* `minetest.parse_json(string[, nullvalue])`: returns something
* 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
* 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
Class reference
---------------
+### 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 writeable and mod can send over it.
+* `send_all(message)`: Send `message` though the mod channel.
+ * If mod channel is not writeable 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_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
* returns player speed vector
* `get_hp()`
* returns player HP
-* `got_teleported()`
- * returns true if player was teleported
+* `get_name()`
+ * returns player name
* `is_attached()`
* returns true if player is attached
* `is_touching_ground()`
* 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:
* `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`)
{
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
----------------
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`
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.
projects / dragonfireclient.git / blobdiff