Various smaller lua_api documentation updates (#13240)

This fixes several smaller documentation issues at once because posting one PR for every tiny documentation fix is a nightmare.
This commit is contained in:
Wuzzy 2023-03-19 20:24:37 +01:00 committed by GitHub
parent 5fa63a0b0c
commit 0050f12b32
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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
-- * `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
-- 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]),