X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=8a80303947c25ac41820bc8ca6fed8d726cfe2bc;hb=6a6b579c5472065dd4ba8edcebe120b4b1c9198e;hp=81b05abb088da88e6faba4ac7113c3000e763db7;hpb=8910c7f8ae1862d3d81e6f635789e765ae2e80b9;p=dragonfireclient.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 81b05abb0..8a8030394 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -62,7 +62,8 @@ Where `` is unique to each game. The game directory can contain the following files: * `game.conf`, with the following keys: - * `name`: Required, a human readable title to address the game, e.g. `name = Minetest`. + * `title`: Required, a human-readable title to address the game, e.g. `title = Minetest Game`. + * `name`: (Deprecated) same as title. * `description`: Short description to be shown in the content tab * `allowed_mapgens = ` e.g. `allowed_mapgens = v5,v6,flat` @@ -78,7 +79,7 @@ The game directory can contain the following files: * `disallowed_mapgen_settings= ` e.g. `disallowed_mapgen_settings = mgv5_spflags` These mapgen settings are hidden for this game in the world creation - dialog and game start menu. + dialog and game start menu. Add `seed` to hide the seed input field. * `disabled_settings = ` e.g. `disabled_settings = enable_damage, creative_mode` These settings are hidden for this game in the "Start game" tab @@ -1026,7 +1027,7 @@ The function of `param1` is determined by `paramtype` in node definition. `param1` is reserved for the engine when `paramtype != "none"`. * `paramtype = "light"` - * The value stores light with and without sun in its upper and lower 4 bits + * The value stores light with and without sun in its lower and upper 4 bits respectively. * Required by a light source node to enable spreading its light. * Required by the following drawtypes as they determine their visual @@ -1544,15 +1545,12 @@ Displays a minimap on the HUD. Representations of simple things ================================ -Position/vector ---------------- - - {x=num, y=num, z=num} +Vector (ie. a position) +----------------------- - Note: it is highly recommended to construct a vector using the helper function: - vector.new(num, num, num) + vector.new(x, y, z) -For helper functions see [Spatial Vectors]. +See [Spatial Vectors] for details. `pointed_thing` --------------- @@ -1573,8 +1571,7 @@ Exact pointing location (currently only `Raycast` supports these fields): from 1). * `pointed_thing.intersection_normal`: Unit vector, points outwards of the selected selection box. This specifies which face is pointed at. - Is a null vector `{x = 0, y = 0, z = 0}` when the pointer is inside the - selection box. + Is a null vector `vector.zero()` when the pointer is inside the selection box. @@ -1683,10 +1680,10 @@ wear value. Syntax: Examples: -* `'default:apple'`: 1 apple -* `'default:dirt 5'`: 5 dirt -* `'default:pick_stone'`: a new stone pickaxe -* `'default:pick_wood 1 21323'`: a wooden pickaxe, ca. 1/3 worn out +* `"default:apple"`: 1 apple +* `"default:dirt 5"`: 5 dirt +* `"default:pick_stone"`: a new stone pickaxe +* `"default:pick_wood 1 21323"`: a wooden pickaxe, ca. 1/3 worn out ### Table format @@ -1776,21 +1773,20 @@ Groups in crafting recipes An example: Make meat soup from any meat, any water and any bowl: { - output = 'food:meat_soup_raw', + output = "food:meat_soup_raw", recipe = { - {'group:meat'}, - {'group:water'}, - {'group:bowl'}, + {"group:meat"}, + {"group:water"}, + {"group:bowl"}, }, - -- preserve = {'group:bowl'}, -- Not implemented yet (TODO) } Another example: Make red wool from white wool and red dye: { - type = 'shapeless', - output = 'wool:red', - recipe = {'wool:white', 'group:dye,basecolor_red'}, + type = "shapeless", + output = "wool:red", + recipe = {"wool:white", "group:dye,basecolor_red"}, } Special groups @@ -2015,7 +2011,7 @@ Example definition of the capabilities of an item max_drop_level=1, groupcaps={ crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}} - } + }, damage_groups = {fleshy=2}, } @@ -2174,6 +2170,13 @@ Some of the values in the key-value store are handled specially: * `color`: A `ColorString`, which sets the stack's color. * `palette_index`: If the item has a palette, this is used to get the current color from the palette. +* `count_meta`: Replace the displayed count with any string. +* `count_alignment`: Set the alignment of the displayed count value. This is an + int value. The lowest 2 bits specify the alignment in x-direction, the 3rd and + 4th bit specify the alignment in y-direction: + 0 = default, 1 = left / up, 2 = middle, 3 = right / down + The default currently is the same as right/down. + Example: 6 = 2 + 1*4 = middle,up Example: @@ -2271,18 +2274,20 @@ Examples Version History --------------- -* FORMSPEC VERSION 1: +* Formspec version 1 (pre-5.1.0): * (too much) -* FORMSPEC VERSION 2: +* Formspec version 2 (5.1.0): * Forced real coordinates * background9[]: 9-slice scaling parameters -* FORMSPEC VERSION 3: +* Formspec version 3 (5.2.0): * Formspec elements are drawn in the order of definition * bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor) * box[] and image[] elements enable clipping by default * new element: scroll_container[] -* FORMSPEC VERSION 4: +* Formspec version 4 (5.4.0): * Allow dropdown indexing events +* Formspec version 5 (5.5.0): + * Added padding[] element Elements -------- @@ -2386,21 +2391,23 @@ Elements * End of a scroll_container, following elements are no longer bound to this container. -### `list[;;,;,;]` +### `list[;;,;,;]` -* Show an inventory list if it has been sent to the client. Nothing will - be shown if the inventory list is of size 0. +* Show an inventory list if it has been sent to the client. +* If the inventory list changes (eg. it didn't exist before, it's resized, or its items + are moved) while the formspec is open, the formspec element may (but is not guaranteed + to) adapt to the new inventory list. +* Item slots are drawn in a grid from left to right, then up to down, ordered + according to the slot index. +* `W` and `H` are in inventory slots, not in coordinates. +* `starting item index` (Optional): The index of the first (upper-left) item to draw. + Indices start at `0`. Default is `0`. +* The number of shown slots is the minimum of `W*H` and the inventory list's size minus + `starting item index`. * **Note**: With the new coordinate system, the spacing between inventory slots is one-fourth the size of an inventory slot by default. Also see [Styling Formspecs] for changing the size of slots and spacing. -### `list[;;,;,;]` - -* Show an inventory list if it has been sent to the client. Nothing will - 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. - ### `listring[;]` * Allows to create a ring of inventory lists @@ -3241,7 +3248,7 @@ Colors `#RRGGBBAA` defines a color in hexadecimal format and alpha channel. Named colors are also supported and are equivalent to -[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors). +[CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/#named-color). To specify the value of the alpha channel, append `#A` or `#AA` to the end of the color name (e.g. `colorname#08`). @@ -3292,33 +3299,76 @@ The following functions provide escape sequences: Spatial Vectors =============== -A spatial vector is similar to a position, but instead using -absolute world coordinates, it uses *relative* coordinates, relative to -no particular point. - -Internally, it is implemented as a table with the 3 fields -`x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`. -However, one should *never* create a vector manually as above, such misbehavior -is deprecated. The vector helpers set a metatable for the created vectors which -allows indexing with numbers, calling functions directly on vectors and using -operators (like `+`). Furthermore, the internal implementation might change in + +Minetest stores 3-dimensional spatial vectors in Lua as tables of 3 coordinates, +and has a class to represent them (`vector.*`), which this chapter is about. +For details on what a spatial vectors is, please refer to Wikipedia: +https://en.wikipedia.org/wiki/Euclidean_vector. + +Spatial vectors are used for various things, including, but not limited to: + +* any 3D spatial vector (x/y/z-directions) +* Euler angles (pitch/yaw/roll in radians) (Spatial vectors have no real semantic + meaning here. Therefore, most vector operations make no sense in this use case.) + +Note that they are *not* used for: + +* n-dimensional vectors where n is not 3 (ie. n=2) +* arrays of the form `{num, num, num}` + +The API documentation may refer to spatial vectors, as produced by `vector.new`, +by any of the following notations: + +* `(x, y, z)` (Used rarely, and only if it's clear that it's a vector.) +* `vector.new(x, y, z)` +* `{x=num, y=num, z=num}` (Even here you are still supposed to use `vector.new`.) + +Compatibility notes +------------------- + +Vectors used to be defined as tables of the form `{x = num, y = num, z = num}`. +Since Minetest 5.5.0, vectors additionally have a metatable to enable easier use. +Note: Those old-style vectors can still be found in old mod code. Hence, mod and +engine APIs still need to be able to cope with them in many places. + +Manually constructed tables are deprecated and highly discouraged. This interface +should be used to ensure seamless compatibility between mods and the Minetest API. +This is especially important to callback function parameters and functions overwritten +by mods. +Also, though not likely, the internal implementation of a vector might change in the future. -Old code might still use vectors without metatables, be aware of this! +In your own code, or if you define your own API, you can, of course, still use +other representations of vectors. + +Vectors provided by API functions will provide an instance of this class if not +stated otherwise. Mods should adapt this for convenience reasons. + +Special properties of the class +------------------------------- + +Vectors can be indexed with numbers and allow method and operator syntax. All these forms of addressing a vector `v` are valid: `v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13` +Note: Prefer letter over number indexing for performance and compatibility reasons. Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does the same as `vector.foo(v, ...)`, apart from deprecated functionality. +`tostring` is defined for vectors, see `vector.to_string`. + The metatable that is used for vectors can be accessed via `vector.metatable`. Do not modify it! All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables. Returned vectors always have a metatable set. -For the following functions, `v`, `v1`, `v2` are vectors, -`p1`, `p2` are positions, +Common functions and methods +---------------------------- + +For the following functions (and subchapters), +`v`, `v1`, `v2` are vectors, +`p1`, `p2` are position vectors, `s` is a scalar (a number), vectors are written like this: `(x, y, z)`: @@ -3340,6 +3390,7 @@ vectors are written like this: `(x, y, z)`: * `init`: If given starts looking for the vector at this string index. * `vector.to_string(v)`: * Returns a string of the form `"(x, y, z)"`. + * `tostring(v)` does the same. * `vector.direction(p1, p2)`: * Returns a vector of length 1 with direction `p1` to `p2`. * If `p1` and `p2` are identical, returns `(0, 0, 0)`. @@ -3358,6 +3409,9 @@ vectors are written like this: `(x, y, z)`: * `vector.apply(v, func)`: * Returns a vector where the function `func` has been applied to each component. +* `vector.combine(v, w, func)`: + * Returns a vector where the function `func` has combined both components of `v` and `w` + for each component * `vector.equals(v1, v2)`: * Returns a boolean, `true` if the vectors are identical. * `vector.sort(v1, v2)`: @@ -3370,7 +3424,7 @@ vectors are written like this: `(x, y, z)`: * Returns the cross product of `v1` and `v2`. * `vector.offset(v, x, y, z)`: * Returns the sum of the vectors `v` and `(x, y, z)`. -* `vector.check()`: +* `vector.check(v)`: * Returns a boolean value indicating whether `v` is a real vector, eg. created by a `vector.*` function. * Returns `false` for anything else, including tables like `{x=3,y=1,z=4}`. @@ -3392,6 +3446,9 @@ For the following functions `x` can be either a vector or a number: * Returns a scaled vector. * Deprecated: If `s` is a vector: Returns the Schur quotient. +Operators +--------- + Operators can be used if all of the involved vectors have metatables: * `v1 == v2`: * Returns whether `v1` and `v2` are identical. @@ -3408,8 +3465,11 @@ Operators can be used if all of the involved vectors have metatables: * `v / s`: * Returns `v` scaled by `1 / s`. +Rotation-related functions +-------------------------- + For the following functions `a` is an angle in radians and `r` is a rotation -vector ({x = , y = , z = }) where pitch, yaw and roll are +vector (`{x = , y = , z = }`) where pitch, yaw and roll are angles in radians. * `vector.rotate(v, r)`: @@ -3426,6 +3486,18 @@ angles in radians. * If `up` is omitted, the roll of the returned vector defaults to zero. * Otherwise `direction` and `up` need to be vectors in a 90 degree angle to each other. +Further helpers +--------------- + +There are more helper functions involving vectors, but they are listed elsewhere +because they only work on specific sorts of vectors or involve things that are not +vectors. + +For example: + +* `minetest.hash_node_position` (Only works on node positions.) +* `minetest.dir_to_wallmounted` (Involves wallmounted param2 values.) + @@ -3477,8 +3549,16 @@ Helper functions * `minetest.string_to_pos(string)`: returns a position or `nil` * Same but in reverse. * If the string can't be parsed to a position, nothing is returned. -* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions +* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)", relative_to)`: + * returns two positions * Converts a string representing an area box into two positions + * X1, Y1, ... Z2 are coordinates + * `relative_to`: Optional. If set to a position, each coordinate + can use the tilde notation for relative positions + * Tilde notation: "~": Relative coordinate + "~": Relative coordinate plus + * Example: `minetest.string_to_area("(1,2,3) (~5,~-5,~)", {x=10,y=10,z=10})` + returns `{x=1,y=2,z=3}, {x=15,y=5,z=10}` * `minetest.formspec_escape(string)`: returns a string * escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs. @@ -3510,6 +3590,12 @@ Helper functions * `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position. * returns the exact position on the surface of a pointed node +* `minetest.get_tool_wear_after_use(uses [, initial_wear])` + * Simulates a tool being used once and returns the added wear, + such that, if only this function is used to calculate wear, + the tool will break exactly after `uses` times of uses + * `uses`: Number of times the tool can be used + * `initial_wear`: The initial wear the tool starts with (default: 0) * `minetest.get_dig_params(groups, tool_capabilities [, wear])`: Simulates an item that digs a node. Returns a table with the following fields: @@ -3524,7 +3610,7 @@ Helper functions * `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch [, wear]])`: Simulates an item that punches an object. Returns a table with the following fields: - * `hp`: How much damage the punch would cause. + * `hp`: How much damage the punch would cause (between -65535 and 65535). * `wear`: How much wear would be added to the tool (ignored for non-tools). Parameters: * `groups`: Damage groups of the object @@ -4623,6 +4709,8 @@ Utilities abm_min_max_y = true, -- dynamic_add_media supports passing a table with options (5.5.0) dynamic_add_media_table = true, + -- allows get_sky to return a table instead of separate values (5.6.0) + get_sky_as_table = true, } * `minetest.has_feature(arg)`: returns `boolean, missing_features` @@ -5696,6 +5784,68 @@ Timing * `job:cancel()` * Cancels the job function from being called +Async environment +----------------- + +The engine allows you to submit jobs to be ran in an isolated environment +concurrently with normal server operation. +A job consists of a function to be ran in the async environment, any amount of +arguments (will be serialized) and a callback that will be called with the return +value of the job function once it is finished. + +The async environment does *not* have access to the map, entities, players or any +globals defined in the 'usual' environment. Consequently, functions like +`minetest.get_node()` or `minetest.get_player_by_name()` simply do not exist in it. + +Arguments and return values passed through this can contain certain userdata +objects that will be seamlessly copied (not shared) to the async environment. +This allows you easy interoperability for delegating work to jobs. + +* `minetest.handle_async(func, callback, ...)`: + * Queue the function `func` to be ran in an async environment. + Note that there are multiple persistent workers and any of them may + end up running a given job. The engine will scale the amount of + worker threads automatically. + * When `func` returns the callback is called (in the normal environment) + with all of the return values as arguments. + * Optional: Variable number of arguments that are passed to `func` +* `minetest.register_async_dofile(path)`: + * Register a path to a Lua file to be imported when an async environment + is initialized. You can use this to preload code which you can then call + later using `minetest.handle_async()`. + +### List of APIs available in an async environment + +Classes: +* `ItemStack` +* `PerlinNoise` +* `PerlinNoiseMap` +* `PseudoRandom` +* `PcgRandom` +* `SecureRandom` +* `VoxelArea` +* `VoxelManip` + * only if transferred into environment; can't read/write to map +* `Settings` + +Class instances that can be transferred between environments: +* `ItemStack` +* `PerlinNoise` +* `PerlinNoiseMap` +* `VoxelManip` + +Functions: +* Standalone helpers such as logging, filesystem, encoding, + hashing or compression APIs +* `minetest.request_insecure_environment` (same restrictions apply) + +Variables: +* `minetest.settings` +* `minetest.registered_items`, `registered_nodes`, `registered_tools`, + `registered_craftitems` and `registered_aliases` + * with all functions and userdata values replaced by `true`, calling any + callbacks here is obviously not possible + Server ------ @@ -5971,11 +6121,11 @@ Misc. This is due to the fact that JSON has two distinct array and object values. * Example: `write_json({10, {a = false}})`, - returns `"[10, {\"a\": false}]"` + returns `'[10, {"a": false}]'` * `minetest.serialize(table)`: returns a string * Convert a table containing tables, strings, numbers, booleans and `nil`s into string form readable by `minetest.deserialize` - * Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'` + * Example: `serialize({foo="bar"})`, returns `'return { ["foo"] = "bar" }'` * `minetest.deserialize(string[, safe])`: returns a table * Convert a string returned by `minetest.serialize` into a table * `string` is loaded in an empty sandbox environment. @@ -5987,7 +6137,7 @@ Misc. value of `safe`. It is fine to serialize then deserialize user-provided data, but directly providing user input to deserialize is always unsafe. * Example: `deserialize('return { ["foo"] = "bar" }')`, - returns `{foo='bar'}` + returns `{foo="bar"}` * Example: `deserialize('print("foo")')`, returns `nil` (function call fails), returns `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)` @@ -6200,45 +6350,53 @@ Sorted alphabetically. `AreaStore` ----------- -A fast access data structure to store areas, and find areas near a given -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)`. 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. +AreaStore is a data structure to calculate intersections of 3D cuboid volumes +and points. The `data` field (string) may be used to store and retrieve any +mod-relevant information to the specified area. + +Despite its name, mods must take care of persisting AreaStore data. They may +use the provided load and write functions for this. + ### Methods -* `get_area(id, include_borders, include_data)` +* `AreaStore(type_name)` + * Returns a new AreaStore instance + * `type_name`: optional, forces the internally used API. + * Possible values: `"LibSpatial"` (default). + * When other values are specified, or SpatialIndex is not available, + the custom Minetest functions are used. +* `get_area(id, include_corners, 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` + true -- Without `include_corners` and `include_data` { - min = pos, max = pos -- `include_borders == true` + min = pos, max = pos -- `include_corners == true` data = string -- `include_data == true` } -* `get_areas_for_pos(pos, include_borders, include_data)` +* `get_areas_for_pos(pos, include_corners, 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). +* `get_areas_in_area(corner1, corner2, accept_overlap, include_corners, include_data)` + * Returns all areas that contain all nodes inside the area specified by` + `corner1 and `corner2` (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. +* `insert_area(corner1, corner2, 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. + * The (inclusive) positions `corner1` and `corner2` 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. +* `reserve(count)` + * Requires SpatialIndex, no-op function otherwise. + * Reserves resources for `count` many contained areas to improve + efficiency when working with many area entries. Additional areas can still + be inserted afterwards at the usual complexity. * `remove_area(id)`: removes the area with the given id from the store, returns success. * `set_cache_params(params)`: sets params for the included prefiltering cache. @@ -6276,9 +6434,9 @@ 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 +* `get_list(listname)`: return full list (list of `ItemStack`s) * `set_list(listname, list)`: set full list (size will not change) -* `get_lists()`: returns list of inventory lists +* `get_lists()`: returns table that maps listnames to inventory lists * `set_lists(lists)`: sets inventory lists (size will not change) * `add_item(listname, stack)`: add item somewhere in list, returns leftover `ItemStack`. @@ -6373,7 +6531,13 @@ an itemstring, a table or `nil`. or those of the hand if none are defined for this item type * `add_wear(amount)` * Increases wear by `amount` if the item is a tool, otherwise does nothing + * Valid `amount` range is [0,65536] * `amount`: number, integer +* `add_wear_by_uses(max_uses)` + * Increases wear in such a way that, if only this function is called, + the item breaks after `max_uses` times + * Valid `max_uses` range is [0,65536] + * Does nothing if item is not a tool or if `max_uses` is 0 * `add_item(item)`: returns leftover `ItemStack` * Put some item or stack onto this stack * `item_fits(item)`: returns `true` if item or stack can be fully added to @@ -6638,7 +6802,7 @@ object you are working with still exists. * Fourth column: subject looking to the right * Fifth column: subject viewed from above * Sixth column: subject viewed from below -* `get_entity_name()` (**Deprecated**: Will be removed in a future version) +* `get_entity_name()` (**Deprecated**: Will be removed in a future version, use the field `self.name` instead) * `get_luaentity()` #### Player only (no-op for other objects) @@ -6714,18 +6878,21 @@ object you are working with still exists. `aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`. * The fields `LMB` and `RMB` are equal to `dig` and `place` respectively, and exist only to preserve backwards compatibility. + * Returns an empty table `{}` if the object is not a player. * `get_player_control_bits()`: returns integer with bit packed player pressed - keys. Bits: - * 0 - up - * 1 - down - * 2 - left - * 3 - right - * 4 - jump - * 5 - aux1 - * 6 - sneak - * 7 - dig - * 8 - place - * 9 - zoom + keys. + * Bits: + * 0 - up + * 1 - down + * 2 - left + * 3 - right + * 4 - jump + * 5 - aux1 + * 6 - sneak + * 7 - dig + * 8 - place + * 9 - zoom + * Returns `0` (no bits set) if the object is not a player. * `set_physics_override(override_table)` * `override_table` is a table with the following fields: * `speed`: multiplier to default walking speed value (default: `1`) @@ -6748,17 +6915,18 @@ object you are working with still exists. * `hud_get(id)`: gets the HUD element definition structure of the specified ID * `hud_set_flags(flags)`: sets specified HUD flags of player. * `flags`: A table with the following fields set to boolean values - * hotbar - * healthbar - * crosshair - * wielditem - * breathbar - * minimap - * minimap_radar + * `hotbar` + * `healthbar` + * `crosshair` + * `wielditem` + * `breathbar` + * `minimap`: Modifies the client's permission to view the minimap. + The client may locally elect to not view the minimap. + * `minimap_radar`: is only usable when `minimap` is true + * `basic_debug`: Allow showing basic debug info that might give a gameplay advantage. + This includes map seed, player position, look direction, the pointed node and block bounds. + Does not affect players with the `debug` privilege. * If a flag equals `nil`, the flag is not modified - * `minimap`: Modifies the client's permission to view the minimap. - The client may locally elect to not view the minimap. - * `minimap_radar` is only usable when `minimap` is true * `hud_get_flags()`: returns a table of player HUD flags with boolean values. * 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 @@ -6794,12 +6962,15 @@ object you are working with still exists. * `set_sky(sky_parameters)` * The presence of the function `set_sun`, `set_moon` or `set_stars` indicates whether `set_sky` accepts this format. Check the legacy format otherwise. + * Passing no arguments resets the sky to its default values. * `sky_parameters` is a table with the following optional fields: * `base_color`: ColorSpec, changes fog in "skybox" and "plain". + (default: `#ffffff`) * `type`: Available types: * `"regular"`: Uses 0 textures, `base_color` ignored * `"skybox"`: Uses 6 textures, `base_color` used as fog. * `"plain"`: Uses 0 textures, `base_color` used as both fog and sky. + (default: `"regular"`) * `textures`: A table containing up to six textures in the following order: Y+ (top), Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south). * `clouds`: Boolean for whether clouds appear. (default: `true`) @@ -6828,9 +6999,9 @@ object you are working with still exists. * `indoors`: ColorSpec, for when you're either indoors or underground. (default: `#646464`) * `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun - at sunrise and sunset. + at sunrise and sunset. (default: `#f47d1d`) * `fog_moon_tint`: ColorSpec, changes the fog tinting for the moon - at sunrise and sunset. + at sunrise and sunset. (default: `#7f99cc`) * `fog_tint_type`: string, changes which mode the directional fog abides by, `"custom"` uses `sun_tint` and `moon_tint`, while `"default"` uses the classic Minetest sun and moon tinting. @@ -6844,15 +7015,22 @@ object you are working with still exists. * `"plain"`: Uses 0 textures, `bgcolor` used * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or `"plain"` custom skyboxes (default: `true`) -* `get_sky()`: returns base_color, type, table of textures, clouds. -* `get_sky_color()`: returns a table with the `sky_color` parameters as in - `set_sky`. +* `get_sky(as_table)`: + * `as_table`: boolean that determines whether the deprecated version of this + function is being used. + * `true` returns a table containing sky parameters as defined in `set_sky(sky_parameters)`. + * Deprecated: `false` or `nil` returns base_color, type, table of textures, + clouds. +* `get_sky_color()`: + * Deprecated: Use `get_sky(as_table)` instead. + * returns a table with the `sky_color` parameters as in `set_sky`. * `set_sun(sun_parameters)`: + * Passing no arguments resets the sun to its default values. * `sun_parameters` is a table with the following optional fields: * `visible`: Boolean for whether the sun is visible. (default: `true`) * `texture`: A regular texture for the sun. Setting to `""` - will re-enable the mesh sun. (default: `"sun.png"`) + will re-enable the mesh sun. (default: "sun.png", if it exists) * `tonemap`: A 512x1 texture containing the tonemap for the sun (default: `"sun_tonemap.png"`) * `sunrise`: A regular texture for the sunrise texture. @@ -6863,17 +7041,21 @@ object you are working with still exists. * `get_sun()`: returns a table with the current sun parameters as in `set_sun`. * `set_moon(moon_parameters)`: + * Passing no arguments resets the moon to its default values. * `moon_parameters` is a table with the following optional fields: * `visible`: Boolean for whether the moon is visible. (default: `true`) * `texture`: A regular texture for the moon. Setting to `""` - will re-enable the mesh moon. (default: `"moon.png"`) + will re-enable the mesh moon. (default: `"moon.png"`, if it exists) + Note: Relative to the sun, the moon texture is rotated by 180°. + You can use the `^[transformR180` texture modifier to achieve the same orientation. * `tonemap`: A 512x1 texture containing the tonemap for the moon (default: `"moon_tonemap.png"`) * `scale`: Float controlling the overall size of the moon (default: `1`) * `get_moon()`: returns a table with the current moon parameters as in `set_moon`. * `set_stars(star_parameters)`: + * Passing no arguments resets stars to their default values. * `star_parameters` is a table with the following optional fields: * `visible`: Boolean for whether the stars are visible. (default: `true`) @@ -6887,6 +7069,7 @@ object you are working with still exists. * `get_stars()`: returns a table with the current stars parameters as in `set_stars`. * `set_clouds(cloud_parameters)`: set cloud parameters + * Passing no arguments resets clouds to their default values. * `cloud_parameters` is a table with the following optional fields: * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`) * `color`: basic cloud color with alpha channel, ColorSpec @@ -6921,6 +7104,14 @@ object you are working with still exists. * Returns `false` if failed. * Resource intensive - use sparsely * To get blockpos, integer divide pos by 16 +* `set_lighting(light_definition)`: sets lighting for the player + * `light_definition` is a table with the following optional fields: + * `shadows` is a table that controls ambient shadows + * `intensity` sets the intensity of the shadows from 0 (no shadows, default) to 1 (blackness) +* `get_lighting()`: returns the current state of lighting for the player. + * Result is a table with the same fields as `light_definition` in `set_lighting`. +* `respawn()`: Respawns the player using the same mechanism as the death screen, + including calling on_respawnplayer callbacks. `PcgRandom` ----------- @@ -7339,7 +7530,7 @@ Used by `minetest.register_entity`. -- for more info) by using a '_' prefix } -Collision info passed to `on_step`: +Collision info passed to `on_step` (`moveresult` argument): { touching_ground = boolean, @@ -7356,6 +7547,8 @@ Collision info passed to `on_step`: }, ... } + -- `collisions` does not contain data of unloaded mapblock collisions + -- or when the velocity changes are negligibly small } ABM (ActiveBlockModifier) definition @@ -8068,11 +8261,11 @@ Used by `minetest.register_craft`. ### Shaped { - output = 'default:pick_stone', + output = "default:pick_stone", recipe = { - {'default:cobble', 'default:cobble', 'default:cobble'}, - {'', 'default:stick', ''}, - {'', 'default:stick', ''}, -- Also groups; e.g. 'group:crumbly' + {"default:cobble", "default:cobble", "default:cobble"}, + {"", "default:stick", ""}, + {"", "default:stick", ""}, -- Also groups; e.g. "group:crumbly" }, replacements = , -- replacements: replace one input item with another item on crafting @@ -8083,7 +8276,7 @@ Used by `minetest.register_craft`. { type = "shapeless", - output = 'mushrooms:mushroom_stew', + output = "mushrooms:mushroom_stew", recipe = { "mushrooms:bowl", "mushrooms:mushroom_brown", @@ -8380,9 +8573,8 @@ See [Decoration types]. Used by `minetest.register_decoration`. spawn_by = "default:water", -- Node (or list of nodes) that the decoration only spawns next to. - -- Checks two horizontal planes of 8 neighbouring nodes (including - -- diagonal neighbours), one plane level with the 'place_on' node and a - -- plane one node above that. + -- Checks the 8 neighbouring nodes on the same Y, and also the ones + -- at Y+1, excluding both center nodes. num_spawn_by = 1, -- Number of spawn_by nodes that must be surrounding the decoration