* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
+* (Unofficial) Minetest Modding Book by rubenwardy: <https://rubenwardy.com/minetest_modding_book/>
Introduction
------------
### mod.conf
-A key-value store of mod details.
+A `Settings` file that provides meta information about the mod.
* `name`: The mod name. Allows Minetest to determine the mod name even if the
folder is wrongly named.
### `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.
+The format is documented in `builtin/settingtypes.txt`.
+It is parsed by the main menu settings dialogue to list mod-specific
+settings in the "Mods" category.
### `init.lua`
* e.g. `{name = "default_place_node", gain = 1.0, pitch = 1.0}`
+Special sound files
+-------------------
+
+These sound files are played back by the engine if provided.
+
+ * `main_menu`: Looped sound in the main menu (gain = 1.0)
+ * `player_damage`: Played when the local player takes damage (gain = 0.5)
+ * `player_falling_damage`: Played when the local player takes
+ damage by falling (gain = 0.5)
Registered definitions
**Note**: `offset` _will_ adapt to screen DPI as well as user defined scaling
factor!
+The `z_index` field specifies the order of HUD elements from back to front.
+Lower z-index elements are displayed behind higher z-index elements. Elements
+with same z-index are displayed in an arbitrary order. Default 0.
+Supports negative values.
+
Below are the specific uses for fields in each type; fields not listed for that
type are ignored.
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
+ * Indicates a pointed node selection box.
+ * `under` refers to the node position behind the pointed face.
+ * `above` refers to the node position in front of the pointed face.
* `{type="object", ref=ObjectRef}`
Exact pointing location (currently only `Raycast` supports these fields):
Special groups
--------------
-* `immortal`: Skips all damage and breath handling for an object. This group
- will also hide the integrated HUD status bars for players, and is
- automatically set to all players when damage is disabled on the server.
-* `punch_operable`: For entities; disables the regular damage mechanism for
- players punching it by hand or a non-tool item, so that it can do something
- else than take damage.
-* `level`: Can be used to give an additional sense of progression in the game.
- * A larger level will cause e.g. a weapon of a lower level make much less
- damage, and get worn out much faster, or not be able to get drops
- from destroyed nodes.
- * `0` is something that is directly accessible at the start of gameplay
- * There is no upper limit
+The asterisk `(*)` after a group name describes that there is no engine
+functionality bound to it, and implementation is left up as a suggestion
+to games.
+
+### Node, item and tool groups
+
+* `not_in_creative_inventory`: (*) Special group for inventory mods to indicate
+ that the item should be hidden in item lists.
+
+
+### Node-only groups
+
+* `attached_node`: if the node under it is not a walkable block the node will be
+ dropped as an item. If the node is wallmounted the wallmounted direction is
+ checked.
+* `bouncy`: value is bounce speed in percent
+* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
+ connect to each other
* `dig_immediate`: Player can always pick up node without reducing tool wear
* `2`: the node always gets the digging time 0.5 seconds (rail, sign)
* `3`: the node always gets the digging time 0 seconds (torch)
* `disable_jump`: Player (and possibly other things) cannot jump from node
* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
-* `bouncy`: value is bounce speed in percent
* `falling_node`: if there is no walkable block under the node it will fall
* `float`: the node will not fall through liquids
-* `attached_node`: if the node under it is not a walkable block the node will be
- dropped as an item. If the node is wallmounted the wallmounted direction is
- checked.
-* `connect_to_raillike`: makes nodes of raillike drawtype with same group value
- connect to each other
+* `level`: Can be used to give an additional sense of progression in the game.
+ * A larger level will cause e.g. a weapon of a lower level make much less
+ damage, and get worn out much faster, or not be able to get drops
+ from destroyed nodes.
+ * `0` is something that is directly accessible at the start of gameplay
+ * There is no upper limit
+ * See also: `leveldiff` in [Tools]
* `slippery`: Players and items will slide on the node.
Slipperiness rises steadily with `slippery` value, starting at 1.
+
+
+### Tool-only groups
+
* `disable_repair`: If set to 1 for a tool, it cannot be repaired using the
`"toolrepair"` crafting recipe
+
+### `ObjectRef` groups
+
+* `immortal`: Skips all damage and breath handling for an object. This group
+ will also hide the integrated HUD status bars for players, and is
+ automatically set to all players when damage is disabled on the server.
+* `punch_operable`: For entities; disables the regular damage mechanism for
+ players punching it by hand or a non-tool item, so that it can do something
+ else than take damage.
+
+
+
Known damage and digging time defining groups
---------------------------------------------
Determines how many uses the tool has when it is used for digging a node,
of this group, of the maximum level. For lower leveled nodes, the use count
is multiplied by `3^leveldiff`.
+`leveldiff` is the difference of the tool's `maxlevel` `groupcaps` and the
+node's `level` group. The node cannot be dug if `leveldiff` is less than zero.
* `uses=10, leveldiff=0`: actual uses: 10
* `uses=10, leveldiff=1`: actual uses: 30
use `minetest.formspec_escape`.
For coloured text you can use `minetest.colorize`.
-WARNING: Minetest allows you to add elements to every single formspec instance
+Since formspec version 3, elements drawn in the order they are defined. All
+background elements are drawn before all other elements.
+`list` elements are an exception here. They are drawn last. This, however, might
+be changed at any time.
+
+**WARNING**: do _not_ use a element name starting with `key_`; those names are
+reserved to pass key press events to formspec!
+
+**WARNING**: Minetest allows you to add elements to every single formspec instance
using `player:set_formspec_prepend()`, which may be the reason backgrounds are
-appearing when you don't expect them to. See [`no_prepend[]`].
+appearing when you don't expect them to, or why things are styled differently
+to normal. See [`no_prepend[]`] and [Styling Formspecs].
Examples
--------
Elements
--------
+### `formspec_version[<version>]`
+
+* Set the formspec version to a certain number. If not specified,
+ version 1 is assumed.
+* Must be specified before `size` element.
+* Clients older than this version can neither show newer elements nor display
+ elements with new arguments correctly.
+* Available since feature `formspec_version_element`.
+
### `size[<W>,<H>,<fixed_size>]`
* Define the size of the menu in inventory slots
### `real_coordinates[<bool>]`
+* INFORMATION: Enable it automatically using `formspec_version` version 2 or newer.
* When set to true, all following formspec elements will use the new coordinate system.
* If used immediately after `size`, `position`, `anchor`, and `no_prepend` elements
(if present), the form size will use the new coordinate system.
be shown if the inventory list is of size 0.
* **Note**: With the new coordinate system, the spacing between inventory
slots is one-fourth the size of an inventory slot.
+* **Note**: Lists are drawn after every other element. This might change at any time.
### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
be shown if the inventory list is of size 0.
* **Note**: With the new coordinate system, the spacing between inventory
slots is one-fourth the size of an inventory slot.
+* **Note**: Lists are drawn after every other element. This might change at any time.
### `listring[<inventory location>;<list name>]`
### `bgcolor[<color>;<fullscreen>]`
* Sets background color of formspec as `ColorString`
-* If `true`, the background color is drawn fullscreen (does not affect the size
- of the formspec).
+* If `true`, a fullscreen background is drawn and the color is ignored
+ (does not affect the size of the formspec)
### `background[<X>,<Y>;<W>,<H>;<texture name>]`
* If `auto_clip` is `true`, the background is clipped to the formspec size
(`x` and `y` are used as offset values, `w` and `h` are ignored)
-### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>;<middle>]`
+### `background
9[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>;<middle>]`
* 9-sliced background. See https://en.wikipedia.org/wiki/9-slice_scaling
* Middle is a rect which defines the middle of the 9-slice.
image shall be sized 8 times 16px times 4 times 16px
* If `auto_clip` is `true`, the background is clipped to the formspec size
(`x` and `y` are used as offset values, `w` and `h` are ignored)
+* Available since formspec version 2
### `pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]`
half a coordinate. With the old system, newlines are spaced 2/5 of
an inventory slot.
-### `vertlabel[<X>,<Y>;<label>]`
+### `hypertext[<X>,<Y>;<W>,<H>;<name>;<text>]`
+* Displays a static formated text with hyperlinks.
+* `x`, `y`, `w` and `h` work as per field
+* `name` is the name of the field as returned in fields to `on_receive_fields` in case of action in text.
+* `text` is the formatted text using `markup language` described below.
+### `vertlabel[<X>,<Y>;<label>]`
* Textual label drawn vertically
* `label` is the text on the label
* **Note**: If the new coordinate system is enabled, vertlabels are
### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]`
-* Show a scrollbar
+* Show a scrollbar using options defined by the previous `scrollbaroptions[]`
* There are two ways to use it:
1. handle the changed event (only changed scrollbar is available)
2. read the value on pressing a button (all scrollbars are available)
* `orientation`: `vertical`/`horizontal`
* Fieldname data is transferred to Lua
-* Value this trackbar is set to (`0`-`1000`)
+* Value of this trackbar is set to (`0`-`1000`) by default
* See also `minetest.explode_scrollbar_event`
(main menu: `core.explode_scrollbar_event`).
+### `scrollbaroptions[opt1;opt2;...]`
+* Sets options for all following `scrollbar[]` elements
+* `min=<int>`
+ * Sets scrollbar minimum value, defaults to `0`.
+* `max=<int>`
+ * Sets scrollbar maximum value, defaults to `1000`.
+ If the max is equal to the min, the scrollbar will be disabled.
+* `smallstep=<int>`
+ * Sets scrollbar step value when the arrows are clicked or the mouse wheel is
+ scrolled.
+ * If this is set to a negative number, the value will be reset to `10`.
+* `largestep=<int>`
+ * Sets scrollbar step value used by page up and page down.
+ * If this is set to a negative number, the value will be reset to `100`.
+* `thumbsize=<int>`
+ * Sets size of the thumb on the scrollbar. Size is calculated in the number of
+ units the thumb spans out of the range of the scrollbar values.
+ * Example: If a scrollbar has a `min` of 1 and a `max` of 100, a thumbsize of 10
+ would span a tenth of the scrollbar space.
+ * If this is set to zero or less, the value will be reset to `1`.
+* `arrows=<show/hide/default>`
+ * Whether to show the arrow buttons on the scrollbar. `default` hides the arrows
+ when the scrollbar gets too small, but shows them otherwise.
+
### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]`
* Show scrollable table using options defined by the previous `tableoptions[]`
* `span=<value>`: number of following columns to affect
(default: infinite).
-**Note**: do _not_ use a element name starting with `key_`; those names are
-reserved to pass key press events to formspec!
+### `style[<name>;<prop1>;<prop2>;...]`
+
+* Set the style for the named element `name`.
+* Note: this **must** be before the element is defined.
+* See [Styling Formspecs].
+
+
+### `style_type[<type>;<prop1>;<prop2>;...]`
+
+* Sets the style for all elements of type `type` which appear after this element.
+* See [Styling Formspecs].
Migrating to Real Coordinates
-----------------------------
| list | | | Spacing is now 0.25 for both directions, meaning lists will be taller in height
| label | 0, +0.3 | | The first line of text is now positioned centered exactly at the position specified
+Styling Formspecs
+-----------------
+
+Formspec elements can be themed using the style elements:
+
+ style[<name>;<prop1>;<prop2>;...]
+ style_type[<type>;<prop1>;<prop2>;...]
+
+Where a prop is:
+
+ property_name=property_value
+
+For example:
+
+ style_type[button;bgcolor=#006699]
+ style[world_delete;bgcolor=red;textcolor=yellow]
+ button[4,3.95;2.6,1;world_delete;Delete]
+
+Setting a property to nothing will reset it to the default value. For example:
+
+ style_type[button;bgimg=button.png;bgimg_pressed=button_pressed.png;border=false]
+ style[btn_exit;bgimg=;bgimg_pressed=;border=;bgcolor=red]
+
+
+### Supported Element Types
+
+Some types may inherit styles from parent types.
+
+* button
+* button_exit, inherits from button
+* checkbox
+* scrollbar
+* table
+* textlist
+* dropdown
+* field
+* pwdfield, inherits from field
+* textarea
+* label
+* vertlabel, inherits from field
+* image_button
+* item_image_button, inherits from image_button
+* tabheader
+
+
+### Valid Properties
+
+* button, button_exit
+ * alpha - boolean, whether to draw alpha in bgimg. Default true.
+ * bgcolor - color, sets button tint.
+ * bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided.
+ * bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided.
+ * bgimg - standard image. Defaults to none.
+ * bgimg_hovered - image when hovered. Defaults to bgimg when not provided.
+ * bgimg_pressed - image when pressed. Defaults to bgimg when not provided.
+ * border - boolean, draw border. Set to false to hide the bevelled button pane. Default true.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * textcolor - color, default white.
+* checkbox
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* scrollbar
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* table, textlist
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* dropdown
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* field, pwdfield, textarea
+ * border - set to false to hide the textbox background and border. Default true.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * textcolor - color. Default white.
+* label, vertlabel
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* image_button
+ * alpha - boolean, whether to draw alpha in bgimg. Default true.
+ * border - boolean, draw border. Set to false to hide the bevelled button pane. Default false.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* item_image_button
+ * border - boolean, draw border. Set to false to hide the bevelled button pane. Default false.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* tabheader
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * textcolor - color. Default white.
+
+Markup language
+---------------
+
+Markup language used in `hypertext[]` elements uses tag that look like HTML tags. Some
+tags can enclose text, they open with `<tagname>` and close with `</tagname>`.
+Tags can have attributes, in that case, attributes are in the opening tag in
+form of a key/value separated with equal signs. Attribute values should not be quoted.
+
+These are the technically basic tags but see below for usual tags. Base tags are:
+
+`<style color=... font=... size=...>...</style>`
+
+Changes the style of the text.
+
+* `color`: Text color. Given color is a `colorspec`.
+* `size`: Text size.
+* `font`: Text font (`mono` or `normal`).
+
+`<global background=... margin=... valign=... color=... hovercolor=... size=... font=... halign=... >`
+
+Sets global style.
+
+Global only styles:
+* `background`: Text background, a `colorspec` or `none`.
+* `margin`: Page margins in pixel.
+* `valign`: Text vertical alignment (`top`, `middle`, `bottom`).
+
+Inheriting styles (affects child elements):
+* `color`: Default text color. Given color is a `colorspec`.
+* `hovercolor`: Color of <action> tags when mouse is over.
+* `size`: Default text size.
+* `font`: Default text font (`mono` or `normal`).
+* `halign`: Default text horizontal alignment (`left`, `right`, `center`, `justify`).
+
+This tag needs to be placed only once as it changes the global settings of the
+text. Anyway, if several tags are placed, each changed will be made in the order
+tags appear.
+
+`<tag name=... color=... hovercolor=... font=... size=...>`
+
+Defines or redefines tag style. This can be used to define new tags.
+* `name`: Name of the tag to define or change.
+* `color`: Text color. Given color is a `colorspec`.
+* `hovercolor`: Text color when element hovered (only for `action` tags). Given color is a `colorspec`.
+* `size`: Text size.
+* `font`: Text font (`mono` or `normal`).
+
+Following tags are the usual tags for text layout. They are defined by default.
+Other tags can be added using `<tag ...>` tag.
+
+`<normal>...</normal>`: Normal size text
+
+`<big>...</big>`: Big text
+
+`<bigger>...</bigger>`: Bigger text
+
+`<center>...</center>`: Centered text
+
+`<left>...</left>`: Left-aligned text
+
+`<right>...</right>`: Right-aligned text
+
+`<justify>...</justify>`: Justified text
+
+`<mono>...</mono>`: Monospaced font
+
+`<b>...</b>`, `<i>...</i>`, `<u>...</u>`: Bold, italic, underline styles.
+
+`<action name=...>...</action>`
+
+Make that text a clickable text triggering an action.
+* `name`: Name of the action (mandatory).
+When clicked, the formspec is send to the server. The value of the text field
+sent to `on_player_receive_fields` will be "action:" concatenated to the action
+name.
+
+`<img name=... float=... width=... height=...>`
+
+Draws an image which is present in the client media cache.
+
+* `name`: Name of the texture (mandatory).
+* `float`: If present, makes the image floating (`left` or `right`).
+* `width`: Force image width instead of taking texture width.
+* `height`: Force image height instead of taking texture height.
+
+If only width or height given, texture aspect is kept.
+
+`<item name=... float=... width=... height=... rotate=...>`
+
+Draws an item image.
+
+* `name`: Item string of the item to draw (mandatory).
+* `float`: If present, makes the image floating (`left` or `right`).
+* `width`: Item image width.
+* `height`: Item image height.
+* `rotate`: Rotate item image if set to `yes` or `X,Y,Z`. X, Y and Z being
+rotation speeds in percent of standard speed (-1000 to 1000). Works only if
+`inventory_items_animations` is set to true.
+* `angle`: Angle in which the item image is shown. Value has `X,Y,Z` form.
+X, Y and Z being angles around each three axes. Works only if
+`inventory_items_animations` is set to true.
Inventory
=========
* `craftresult`: list containing the crafted output
* `hand`: list containing an override for the empty hand
* Is not created automatically, use `InvRef:set_size`
-
-
-
+ * Is only used to enhance the empty hand's tool capabilities
Colors
======
-- Specifies whether binary data can be uploaded or downloaded using
-- the HTTP API (5.1.0)
httpfetch_binary_data = true,
+ -- Whether formspec_version[<version>] may be used (5.1.0)
+ formspec_version_element = true,
+ -- Whether AreaStore's IDs are kept on save/load (5.1.0)
+ area_store_persistent_ids = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
avg_jitter = 0.03, -- average packet time jitter
connection_uptime = 200, -- seconds since client connected
protocol_version = 32, -- protocol version used by client
+ formspec_version = 2, -- supported formspec version
-- following information is available on debug build only!!!
-- DO NOT USE IN MODS
--ser_vers = 26, -- serialization version used by client
allow for multiple protection mods.
* `minetest.register_on_item_eat(function(hp_change, replace_with_item, itemstack, user, pointed_thing))`
* Called when an item is eaten, by `minetest.item_eat`
- * Return `true` or `itemstack` to cancel the default item eat response
- (i.e.: hp increase).
+ * Return `itemstack` to cancel the default item eat response (i.e.: hp increase).
* `minetest.register_on_priv_grant(function(name, granter, priv))`
* Called when `granter` grants the priv `priv` to `name`.
* Note that the callback will be called twice if it's done by a player,
* `minetest.chat_send_all(text)`
* `minetest.chat_send_player(name, text)`
+* `minetest.format_chat_message(name, message)`
+ * Used by the server to format a chat message, based on the setting `chat_message_format`.
+ Refer to the documentation of the setting for a list of valid placeholders.
+ * Takes player name and message, and returns the formatted string to be sent to players.
+ * Can be redefined by mods if required, for things like colored names or messages.
+ * **Only** the first occurrence of each placeholder will be replaced.
Environment access
------------------
* `minetest.inventorycube(img1, img2, img3)`
* Returns a string for making an image of a cube (useful as an item image)
* `minetest.get_pointed_thing_position(pointed_thing, above)`
- * Get position of a `pointed_thing` (that you can get from somewhere)
+ * Returns the position of a `pointed_thing` or `nil` if the `pointed_thing`
+ does not refer to a node or entity.
+ * If the optional `above` parameter is true and the `pointed_thing` refers
+ to a node, then it will return the `above` position of the `pointed_thing`.
* `minetest.dir_to_facedir(dir, is6d)`
* Convert a vector to a facedir value, used in `param2` for
`paramtype2="facedir"`.
`{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}`
* `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack`
* `output.time` = a number, if unsuccessful: `0`
- * `output.replacements` = list of `ItemStack`s that couldn't be placed in
- `decremented_input.items`
+ * `output.replacements` = List of replacement `ItemStack`s that couldn't be
+ placed in `decremented_input.items`. Replacements can be placed in
+ `decremented_input` if the stack of the replaced item has a count of 1.
* `decremented_input` = like `input`
* `minetest.get_craft_recipe(output)`: returns input
* returns last registered recipe for output item (node)
Bans
----
-* `minetest.get_ban_list()`: returns the ban list
- (same as `minetest.get_ban_description("")`).
-* `minetest.get_ban_description(ip_or_name)`: returns ban description (string)
-* `minetest.ban_player(name)`: ban a player
-* `minetest.unban_player_or_ip(name)`: unban player or IP address
-* `minetest.kick_player(name, [reason])`: disconnect a player with a optional
+* `minetest.get_ban_list()`: returns a list of all bans formatted as string
+* `minetest.get_ban_description(ip_or_name)`: returns list of bans matching
+ IP address or name formatted as string
+* `minetest.ban_player(name)`: ban the IP of a currently connected player
+ * Returns boolean indicating success
+* `minetest.unban_player_or_ip(ip_or_name)`: remove ban record matching
+ IP address or name
+* `minetest.kick_player(name, [reason])`: disconnect a player with an optional
reason.
+ * Returns boolean indicating success (false if player nonexistant)
Particles
---------
the Lua code generated will use that number of spaces as indentation
instead of a tab character.
+* `minetest.read_schematic(schematic, options)`
+ * Returns a Lua table representing the schematic (see: [Schematic specifier])
+ * `schematic` is the schematic to read (see: [Schematic specifier])
+ * `options` is a table containing the following optional parameters:
+ * `write_yslice_prob`: string value:
+ * `none`: no `write_yslice_prob` table is inserted,
+ * `low`: only probabilities that are not 254 or 255 are written in
+ the `write_ylisce_prob` table,
+ * `all`: write all probabilities to the `write_yslice_prob` table.
+ * The default for this option is `all`.
+ * Any invalid value will be interpreted as `all`.
+
HTTP Requests
-------------
of the creative mode setting, checks for "sneak" to set the `invert_wall`
parameter and `prevent_after_place` set to `true`.
+* `minetest.calculate_knockback(player, hitter, time_from_last_punch,
+ tool_capabilities, dir, distance, damage)`
+ * Returns the amount of knockback applied on the punched player.
+ * Arguments are equivalent to `register_on_punchplayer`, except the following:
+ * `distance`: distance between puncher and punched player
+ * This function can be overriden by mods that wish to modify this behaviour.
+ * You may want to cache and call the old function to allow multiple mods to
+ change knockback behaviour.
+
* `minetest.forceload_block(pos[, transient])`
* forceloads the position `pos`.
* returns `true` if area could be forceloaded
position or area.
Every area has a `data` string attribute to store additional information.
You can create an empty `AreaStore` by calling `AreaStore()`, or
-`AreaStore(type_name)`.
+`AreaStore(type_name)`. The mod decides where to save and load AreaStore.
If you chose the parameter-less constructor, a fast implementation will be
automatically chosen for you.
### Methods
-* `get_area(id, include_borders, include_data)`: returns the area with the id
- `id`.
- (optional) Boolean values `include_borders` and `include_data` control what's
- copied.
- Returns nil if specified area id does not exist.
-* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas
- that contain the position `pos`.
- (optional) Boolean values `include_borders` and `include_data` control what's
- copied.
-* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`:
- returns all areas that contain all nodes inside the area specified by `edge1`
- and `edge2` (inclusive).
- If `accept_overlap` is true, also areas are returned that have nodes in
- common with the specified area.
- (optional) Boolean values `include_borders` and `include_data` control what's
- copied.
+* `get_area(id, include_borders, include_data)`
+ * Returns the area information about the specified ID.
+ * Returned values are either of these:
+
+ nil -- Area not found
+ true -- Without `include_borders` and `include_data`
+ {
+ min = pos, max = pos -- `include_borders == true`
+ data = string -- `include_data == true`
+ }
+
+* `get_areas_for_pos(pos, include_borders, include_data)`
+ * Returns all areas as table, indexed by the area ID.
+ * Table values: see `get_area`.
+* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`
+ * Returns all areas that contain all nodes inside the area specified by `edge1`
+ and `edge2` (inclusive).
+ * `accept_overlap`: if `true`, areas are returned that have nodes in
+ common (intersect) with the specified area.
+ * Returns the same values as `get_areas_for_pos`.
* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store.
- Returns the new area's ID, or nil if the insertion failed.
- The (inclusive) positions `edge1` and `edge2` describe the area.
- `data` is a string stored with the area. If passed, `id` will be used as the
- internal area ID, it must be a unique number between 0 and 2^32-2. If you use
- the `id` parameter you must always use it, or insertions are likely to fail
- due to conflicts.
+ * Returns the new area's ID, or nil if the insertion failed.
+ * The (inclusive) positions `edge1` and `edge2` describe the area.
+ * `data` is a string stored with the area.
+ * `id` (optional): will be used as the internal area ID if it is an unique
+ number between 0 and 2^32-2.
* `reserve(count)`: reserves resources for at most `count` many contained
areas.
Only needed for efficiency, and only some implementations profit.
* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item
stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true.
+* `get_description()`: returns the description shown in inventory list tooltips.
* `clear()`: removes all items from the stack, making it empty.
* `replace(item)`: replace the contents of this stack.
* `item` can also be an itemstring or table.
`MetaDataRef`
-------------
-See [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], and [`PlayerMetaRef`].
+Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`],
+and [`PlayerMetaRef`].
### Methods
* `get_pos()`: returns `{x=num, y=num, z=num}`
* `set_pos(pos)`: `pos`=`{x=num, y=num, z=num}`
-* `move_to(pos, continuous=false)`: interpolated move
+* `move_to(pos, continuous=false)`
+ * Does an interpolated move for Lua entities for visually smooth transitions.
+ * If `continuous` is true, the Lua entity will not be moved to the current
+ position before starting the interpolated move.
+ * For players this does the same as `set_pos`,`continuous` is ignored.
* `punch(puncher, time_from_last_punch, tool_capabilities, direction)`
* `puncher` = another `ObjectRef`,
* `time_from_last_punch` = time since last punch action of the puncher
* `get_hp()`: returns number of hitpoints (2 * number of hearts)
* `set_hp(hp, reason)`: set number of hitpoints (2 * number of hearts).
* See reason in register_on_player_hpchange
-* `get_inventory()`: returns an `InvRef`
+* `get_inventory()`: returns an `InvRef` for players, otherwise returns `nil`
* `get_wield_list()`: returns the name of the inventory list the wielded item
is in.
* `get_wield_index()`: returns the index of the wielded item
* `get_player_name()`: returns `""` if is not a player
* `get_player_velocity()`: returns `nil` if is not a player, otherwise a
table {x, y, z} representing the player's instantaneous velocity in nodes/s
+* `add_player_velocity(vel)`
+ * Adds to player velocity, this happens client-side and only once.
+ * Does not apply during free_move.
+ * Note that since the player speed is normalized at each move step,
+ increasing e.g. Y velocity beyond what would usually be achieved
+ (see: physics overrides) will cause existing X/Z velocity to be reduced.
+ * Example: `add_player_velocity({x=0, y=6.5, z=0})` is equivalent to
+ pressing the jump key (assuming default settings)
* `get_look_dir()`: get camera direction as a unit vector
* `get_look_vertical()`: pitch in radians
* Angle ranges between -pi/2 and pi/2, which are straight up and down
`set_look_vertical`.
* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use
`set_look_horizontal`.
-* `get_breath()`: returns players breath
-* `set_breath(value)`: sets players breath
+* `get_breath()`: returns player's breath
+* `set_breath(value)`: sets player's breath
* values:
* `0`: player is drowning
* max: bubbles bar is not shown
* See [Object properties] for more information
+* `set_fov(fov, is_multiplier)`: Sets player's FOV
+ * `fov`: FOV value.
+ * `is_multiplier`: Set to `true` if the FOV value is a multiplier.
+ Defaults to `false`.
+ * Set to 0 to clear FOV override.
+* `get_fov()`:
+ * Returns player's FOV override in degrees, and a boolean depending on whether
+ the value is a multiplier.
+ * Returns 0 as first value if player's FOV hasn't been overridden.
* `set_attribute(attribute, value)`: DEPRECATED, use get_meta() instead
* Sets an extra attribute with value on player.
* `value` must be a string, or a number which will be converted to a
* Writes changes to file.
* `to_table()`: returns `{[key1]=value1,...}`
+### Format
+
+The settings have the format `key = value`. Example:
+
+ foo = example text
+ bar = """
+ Multiline
+ value
+ """
+
+
`StorageRef`
------------
Mod metadata: per mod metadata, saved automatically.
Can be obtained via `minetest.get_mod_storage()` during load time.
+WARNING: This storage backend is incaptable to save raw binary data due
+to restrictions of JSON.
+
### Methods
* All methods in MetaDataRef
-----------------
Used by `ObjectRef` methods. Part of an Entity definition.
+These properties are not persistent, but are applied automatically to the
+corresponding Lua entity using the given registration fields.
+Player properties need to be saved manually.
{
hp_max = 1,
Used by `minetest.register_lbm`.
+A loading block modifier (LBM) is used to define a function that is called for
+specific nodes (defined by `nodenames`) when a mapblock which contains such nodes
+gets loaded.
+
{
label = "Upgrade legacy doors",
-- Descriptive label for profiling purposes (optional).
run_at_every_load = false,
-- Whether to run the LBM's action every time a block gets loaded,
- -- and not just for blocks that were saved last time before LBMs were
- -- introduced to the world.
+ -- and not only the first time the block gets loaded after the LBM
+ -- was introduced.
action = function(pos, node),
}
liquids_pointable = false,
- -- See "Tools" section
+ -- See "Tools" section for an example including explanation
tool_capabilities = {
full_punch_interval = 1.0,
max_drop_level = 0,
uses = 20, maxlevel = 2},
},
damage_groups = {groupname = damage},
+
+ punch_attack_uses = nil,
+ -- Amount of uses this tool has for attacking players and entities
+ -- by punching them (0 = infinite uses).
+ -- For compatibility, this is automatically set from the first
+ -- suitable groupcap using the forumla "uses * 3^(maxlevel - 1)".
+ -- It is recommend to set this explicitly instead of relying on the
+ -- fallback behavior.
},
node_placement_prediction = nil,
-- default: minetest.item_place
on_secondary_use = function(itemstack, user, pointed_thing),
- -- Same as on_place but called when pointing at nothing.
+ -- Same as on_place but called when not pointing at a node.
-- The user may be any ObjectRef or nil.
- -- pointed_thing: always { type = "nothing" }
+ -- default: nil
on_drop = function(itemstack, dropper, pos),
-- Shall drop item and return the leftover itemstack.
drop = "",
-- Name of dropped item when dug.
-- Default dropped item is the node itself.
- -- Using a table allows multiple items, drop chances and tool filtering:
+ -- Using a table allows multiple items, drop chances and tool filtering.
+ -- Tool filtering was undocumented until recently, tool filtering by string
+ -- matching is deprecated.
drop = {
max_items = 1,
-- Maximum number of item lists to drop.
},
{
-- Only drop if using a tool whose name contains
- -- "default:shovel_".
+ -- "default:shovel_" (this tool filtering by string matching
+ -- is deprecated).
tools = {"~default:shovel_"},
rarity = 2,
-- The item list dropped.
-- default: nil
can_dig = function(pos, [player]),
-
- on_punch = function(pos, node, puncher, pointed_thing),
-- Returns true if node can be dug, or false if not.
-- default: nil
+
+ on_punch = function(pos, node, puncher, pointed_thing),
-- default: minetest.node_punch
-- By default calls minetest.register_on_punchnode callbacks.
Used by `minetest.register_privilege`.
{
- description = "Can teleport", -- Privilege description
+ description = "",
+ -- Privilege description
- give_to_singleplayer = false,
- -- Whether to grant the privilege to singleplayer (default true).
+ give_to_singleplayer = true,
+ -- Whether to grant the privilege to singleplayer.
give_to_admin = true,
-- Whether to grant the privilege to the server admin.
size = { x=100, y=100 },
-- Size of element in pixels
+
+ z_index = 0,
+ -- Z index : lower z-index HUDs are displayed behind higher z-index HUDs
}
Particle definition
projects / minetest.git / blobdiff