diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 0de5d8c7a..958e88284 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -460,9 +460,10 @@ texture is overlaid on top of `cobble.png`. Modifiers that accept texture names (e.g. `[combine`) accept escaping to allow passing complex texture names as arguments. Escaping is done with backslash and -is required for `^` and `:`. +is required for `^`, `:` and `\`. Example: `cobble.png^[lowpart:50:color.png\^[mask\:trans.png` +Or as a Lua string: `"cobble.png^[lowpart:50:color.png\\^[mask\\:trans.png"` The lower 50 percent of `color.png^[mask:trans.png` are overlaid on top of `cobble.png`. @@ -648,7 +649,8 @@ don't change very much. Embed a base64 encoded PNG image in the texture string. You can produce a valid string for this by calling `minetest.encode_base64(minetest.encode_png(tex))`, -refer to the documentation of these functions for details. +where `tex` is pixel data. Refer to the documentation of these +functions for details. You can use this to send disposable images such as captchas to individual clients, or render things that would be too expensive to compose with `[combine:`. @@ -2221,16 +2223,25 @@ Some of the values in the key-value store are handled specially: Example: local meta = minetest.get_meta(pos) + + -- Set node formspec and infotext meta:set_string("formspec", "size[8,9]".. "list[context;main;0,0;8,4;]".. "list[current_player;main;0,5;8,4;]") meta:set_string("infotext", "Chest"); + + -- Set inventory list size of `"main"` list to 32 local inv = meta:get_inventory() - inv:set_size("main", 8*4) + inv:set_size("main", 32) + + -- Dump node metadata print(dump(meta:to_table())) + + -- Set node metadata from a metadata table meta:from_table({ inventory = { + -- Set items of inventory in all 32 slots of the `"main"` list main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", [10] = "", [11] = "", [12] = "", [13] = "", @@ -2240,6 +2251,7 @@ Example: [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", [32] = ""} }, + -- metadata fields fields = { formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]", infotext = "Chest" @@ -4972,7 +4984,7 @@ Utilities connection_uptime = 200, -- seconds since client connected protocol_version = 32, -- protocol version used by client formspec_version = 2, -- supported formspec version - lang_code = "fr" -- Language code used for translation + lang_code = "fr", -- Language code used for translation -- the following keys can be missing if no stats have been collected yet min_rtt = 0.01, -- minimum round trip time @@ -5466,6 +5478,8 @@ Authentication * The player needs to be online for this to be successful. * `minetest.get_auth_handler()`: Return the currently active auth handler + * Must be called *after* load time, to ensure that any custom auth handler was + already registered. * See the [Authentication handler definition] * Use this to e.g. get the authentication data for a player: `local auth_data = minetest.get_auth_handler().get_auth(playername)` @@ -5524,7 +5538,7 @@ Environment access 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. -* `minetest.get_node_light(pos, timeofday)` +* `minetest.get_node_light(pos[, timeofday])` * Gets the light value at the given position. Note that the light value "inside" the node at the given position is returned, so you usually want to get the light value of a neighbor. @@ -6780,7 +6794,8 @@ An `InvRef` is a reference to an inventory. * `set_width(listname, width)`: set width of list; currently used for crafting * `get_stack(listname, i)`: get a copy of stack index `i` in list * `set_stack(listname, i, stack)`: copy `stack` to index `i` in list -* `get_list(listname)`: return full list (list of `ItemStack`s) +* `get_list(listname)`: returns full list (list of `ItemStack`s) + or `nil` if list doesn't exist (size 0) * `set_list(listname, list)`: set full list (size will not change) * `get_lists()`: returns table that maps listnames to inventory lists * `set_lists(lists)`: sets inventory lists (size will not change) @@ -6949,16 +6964,59 @@ of the `${k}` syntax in formspecs is not deprecated. * `set_float(key, value)` * `get_float(key)`: Returns `0` if key not present. * `get_keys()`: returns a list of all keys in the metadata. -* `to_table()`: returns `nil` or a table with keys: - * `fields`: key-value storage - * `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only) -* `from_table(nil or {})` - * Any non-table value will clear the metadata - * See [Node Metadata] for an example - * returns `true` on success +* `to_table()`: + * Returns a metadata table (see below) or `nil` on failure. +* `from_table(data)` + * Imports metadata from a metadata table + * If `data` is a metadata table (see below), the metadata it represents + will replace all metadata of this MetaDataRef object + * Any non-table value for `data` will clear all metadata + * Item table values the `inventory` field may also be itemstrings + * Returns `true` on success * `equals(other)` * returns `true` if this metadata has the same key-value pairs as `other` +### Metadata tables + +Metadata tables represent MetaDataRef in a Lua table form (see `from_table`/`to_table`). + +A metadata table is a table that has the following keys: + +* `fields`: key-value storage of metadata fields + * all values are stored as strings + * numbers must be converted to strings first +* `inventory` (for NodeMetaRef only): A node inventory in table form + * inventory table keys are inventory list names + * inventory table values are item tables + * item table keys are slot IDs (starting with 1) + * item table values are ItemStacks + +Example: + + metadata_table = { + -- metadata fields (key/value store) + fields = { + infotext = "Container", + anoter_key = "Another Value", + }, + + -- inventory data (for nodes) + inventory = { + -- inventory list "main" with 4 slots + main = { + -- list of all item slots + [1] = "example:dirt", + [2] = "example:stone 25", + [3] = "", -- empty slot + [4] = "example:pickaxe", + }, + -- inventory list "hidden" with 1 slot + hidden = { + [1] = "example:diamond", + }, + }, + } + `ModChannel` ------------ @@ -7257,7 +7315,7 @@ child will follow movement and rotation of that bone. * This should be used to set style elements such as background[] and bgcolor[], any non-style elements (eg: label) may result in weird behavior. * Only affects formspecs shown after this is called. -* `get_formspec_prepend(formspec)`: returns a formspec string. +* `get_formspec_prepend()`: returns a formspec string. * `get_player_control()`: returns table with player pressed keys * The table consists of fields with the following boolean values representing the pressed keys: `up`, `down`, `left`, `right`, `jump`, @@ -7319,13 +7377,13 @@ child will follow movement and rotation of that bone. * See `hud_set_flags` for a list of flags that can be toggled. * `hud_set_hotbar_itemcount(count)`: sets number of items in builtin hotbar * `count`: number of items, must be between `1` and `32` -* `hud_get_hotbar_itemcount`: returns number of visible items +* `hud_get_hotbar_itemcount()`: returns number of visible items * `hud_set_hotbar_image(texturename)` * sets background image for hotbar -* `hud_get_hotbar_image`: returns texturename +* `hud_get_hotbar_image()`: returns texturename * `hud_set_hotbar_selected_image(texturename)` * sets image for selected item of hotbar -* `hud_get_hotbar_selected_image`: returns texturename +* `hud_get_hotbar_selected_image()`: returns texturename * `set_minimap_modes({mode, mode, ...}, selected_mode)` * Overrides the available minimap modes (and toggle order), and changes the selected mode. @@ -7825,6 +7883,8 @@ Player properties need to be saved manually. -- 'inventory_image'. -- If 'itemname' contains a ColorString or palette index (e.g. from -- `minetest.itemstring_with_palette()`), the entity will inherit the color. + -- Wielditems are scaled a bit. If you want a wielditem to appear + -- to be as large as a node, use `0.667` in `visual_size` -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter. visual_size = {x = 1, y = 1, z = 1}, @@ -8609,15 +8669,17 @@ Used by `minetest.register_node`. -- Warning: making a liquid node 'floodable' will cause problems. preserve_metadata = function(pos, oldnode, oldmeta, drops), - -- Called when oldnode is about be converted to an item, but before the + -- Called when `oldnode` is about be converted to an item, but before the -- node is deleted from the world or the drops are added. This is -- generally the result of either the node being dug or an attached node -- becoming detached. - -- oldmeta are the metadata fields (table) of the node before deletion. - -- drops is a table of ItemStacks, so any metadata to be preserved can - -- be added directly to one or more of the dropped items. See - -- "ItemStackMetaRef". - -- default: nil + -- * `pos`: node position + -- * `oldnode`: node table of node before it was deleted + -- * `oldmeta`: metadata of node before it was deleted, as a metadata table + -- * `drops`: a table of `ItemStack`s, so any metadata to be preserved can + -- be added directly to one or more of the dropped items. See + -- "ItemStackMetaRef". + -- default: `nil` after_place_node = function(pos, placer, itemstack, pointed_thing), -- Called after constructing node when node was placed using @@ -8627,9 +8689,13 @@ Used by `minetest.register_node`. -- default: nil after_dig_node = function(pos, oldnode, oldmetadata, digger), - -- oldmetadata is in table format. - -- Called after destructing node when node was dug using - -- minetest.node_dig / minetest.dig_node. + -- Called after destructing the node when node was dug using + -- `minetest.node_dig` / `minetest.dig_node`. + -- * `pos`: node position + -- * `oldnode`: node table of node before it was dug + -- * `oldmetadata`: metadata of node before it was dug, + -- as a metadata table + -- * `digger`: ObjectRef of digger -- default: nil can_dig = function(pos, [player]),