X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=aa58bd48e65897c1cba1998210f024dc69d4a838;hb=1d07a365528e3b947a03baba9ef986af2ecd23d1;hp=faaed55e14c502e14b6d7e94246073196c14498e;hpb=fe0b2d02bf07966ce4554578a1efd4b07bbb4734;p=dragonfireclient.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index faaed55e1..aa58bd48e 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -78,7 +78,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 @@ -1544,15 +1544,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 +1570,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 +1679,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 +1772,21 @@ 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) + -- 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 @@ -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: @@ -2388,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 @@ -3294,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)`: @@ -3342,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)`. @@ -3394,6 +3443,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. @@ -3410,8 +3462,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)`: @@ -3428,6 +3483,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.) + @@ -4625,6 +4692,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` @@ -5973,11 +6042,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. @@ -5989,7 +6058,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)` @@ -6202,45 +6271,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. @@ -6278,9 +6355,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`. @@ -6753,17 +6830,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 @@ -6852,9 +6930,15 @@ 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: @@ -6877,7 +6961,9 @@ object you are working with still exists. * `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", if it exists) + 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`) @@ -6933,6 +7019,12 @@ 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`. `PcgRandom` ----------- @@ -7351,7 +7443,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, @@ -7368,6 +7460,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 @@ -8080,11 +8174,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 @@ -8095,7 +8189,7 @@ Used by `minetest.register_craft`. { type = "shapeless", - output = 'mushrooms:mushroom_stew', + output = "mushrooms:mushroom_stew", recipe = { "mushrooms:bowl", "mushrooms:mushroom_brown",