diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/client_lua_api.txt | 17 | ||||
| -rw-r--r-- | doc/lua_api.txt | 778 | ||||
| -rw-r--r-- | doc/menu_lua_api.txt | 13 | ||||
| -rwxr-xr-x | doc/mkdocs/build.sh | 41 | ||||
| -rw-r--r-- | doc/mkdocs/docs/css/code_styles.css | 68 | ||||
| -rw-r--r-- | doc/mkdocs/docs/css/extra.css | 15 | ||||
| l--------- | doc/mkdocs/docs/img/favicon.ico | 1 | ||||
| -rw-r--r-- | doc/mkdocs/lua_highlight.patch | 19 | ||||
| -rw-r--r-- | doc/world_format.txt | 30 |
9 files changed, 806 insertions, 176 deletions
diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index 9253b5568..4bb53f403 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -1,5 +1,5 @@ -Minetest Lua Client Modding API Reference 5.0.1 -=============================================== +Minetest Lua Client Modding API Reference 5.1.0 +================================================ * More information at <http://www.minetest.net/> * Developer Wiki: <http://dev.minetest.net/> @@ -30,6 +30,16 @@ Startup Mods are loaded during client startup from the mod load paths by running the `init.lua` scripts in a shared environment. +In order to load client-side mods in a world, the following conditions need to be satisfied: + +1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true` + +2) The client-side mod located in `$path_user/clientmods/<modname>` is added to + `$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`. + +Note: Depending on the remote server's settings, client-side mods might not +be loaded or have limited functionality. See setting `csm_restriction_flags` for reference. + Paths ----- * `RUN_IN_PLACE=1` (Windows release, local build) @@ -101,9 +111,6 @@ The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on minetest calling the registered callbacks. -`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used -to read custom or existing settings at load time, if necessary. - ### `sounds` Media files (sounds) that will be transferred to the client and will be available for use by the mod. diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 2edd0d9de..907f47e73 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -3,10 +3,10 @@ Minetest Lua Modding API Reference * 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 -============ +------------ Content and functionality can be added to Minetest using Lua scripting in run-time loaded mods. @@ -154,7 +154,7 @@ The location of this directory can be fetched by using ### 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. @@ -196,8 +196,9 @@ A file containing a description to be shown in the Mods tab of the main menu. ### `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` @@ -283,40 +284,35 @@ Mapgen aliases -------------- In a game, a certain number of these must be set to tell core mapgens which -of the game's nodes are to be used by the core mapgens. For example: +of the game's nodes are to be used for core mapgen generation. For example: minetest.register_alias("mapgen_stone", "default:stone") -### Aliases needed for all mapgens except Mapgen V6 +### Aliases for non-V6 mapgens -#### Base terrain +#### Essential aliases * mapgen_stone * mapgen_water_source * mapgen_river_water_source -#### Caves +`mapgen_river_water_source` is required for mapgens with sloping rivers where +it is necessary to have a river liquid node with a short `liquid_range` and +`liquid_renewable = false` to avoid flooding. -Not required if cave liquid nodes are set in biome definitions. +#### Optional aliases * mapgen_lava_source -#### Dungeons - -Not required if dungeon nodes are set in biome definitions. +Fallback lava node used if cave liquids are not defined in biome definitions. +Deprecated for non-V6 mapgens, define cave liquids in biome definitions instead. * mapgen_cobble -* mapgen_stair_cobble -* mapgen_mossycobble -* mapgen_desert_stone -* mapgen_stair_desert_stone -* mapgen_sandstone -* mapgen_sandstonebrick -* mapgen_stair_sandstone_block -### Aliases needed for Mapgen V6 +Fallback node used if dungeon nodes are not defined in biome definitions. +Deprecated for non-V6 mapgens, define dungeon nodes in biome definitions instead. -#### Terrain and biomes +### Aliases needed for Mapgen V6 * mapgen_stone * mapgen_water_source @@ -332,8 +328,6 @@ Not required if dungeon nodes are set in biome definitions. * mapgen_snow * mapgen_ice -#### Flora - * mapgen_tree * mapgen_leaves * mapgen_apple @@ -343,8 +337,6 @@ Not required if dungeon nodes are set in biome definitions. * mapgen_pine_tree * mapgen_pine_needles -#### Dungeons - * mapgen_cobble * mapgen_stair_cobble * mapgen_mossycobble @@ -865,6 +857,15 @@ A positional sound will only be heard by players that are within * 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 @@ -1171,6 +1172,64 @@ A box of a regular node would look like: +Map terminology and coordinates +=============================== + +Nodes, mapblocks, mapchunks +--------------------------- + +A 'node' is the fundamental cubic unit of a world and appears to a player as +roughly 1x1x1 meters in size. + +A 'mapblock' (often abbreviated to 'block') is 16x16x16 nodes and is the +fundamental region of a world that is stored in the world database, sent to +clients and handled by many parts of the engine. +'mapblock' is preferred terminology to 'block' to help avoid confusion with +'node', however 'block' often appears in the API. + +A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks +(80x80x80 nodes) and is the volume of world generated in one operation by +the map generator. +The size in mapblocks has been chosen to optimise map generation. + +Coordinates +----------- + +### Orientation of axes + +For node and mapblock coordinates, +X is East, +Y is up, +Z is North. + +### Node coordinates + +Almost all positions used in the API use node coordinates. + +### Mapblock coordinates + +Occasionally the API uses 'blockpos' which refers to mapblock coordinates that +specify a particular mapblock. +For example blockpos (0,0,0) specifies the mapblock that extends from +node position (0,0,0) to node position (15,15,15). + +#### Converting node position to the containing blockpos + +To calculate the blockpos of the mapblock that contains the node at 'nodepos', +for each axis: + +* blockpos = math.floor(nodepos / 16) + +#### Converting blockpos to min/max node positions + +To calculate the min/max node positions contained in the mapblock at 'blockpos', +for each axis: + +* Minimum: + nodepos = blockpos * 16 +* Maximum: + nodepos = blockpos * 16 + 15 + + + + HUD === @@ -1276,6 +1335,9 @@ For helper functions see [Spatial Vectors]. * `{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): @@ -1485,33 +1547,59 @@ Another example: Make red wool from white wool and red dye: Special groups -------------- -* `immortal`: Disables the group damage system for an entity -* `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 -* `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 +* `float`: the node will not fall through liquids +* `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 --------------------------------------------- @@ -1601,6 +1689,8 @@ to implement this. 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 @@ -1817,9 +1907,15 @@ is used when the server receives user input. You must not use the name Spaces and newlines can be inserted between the blocks, as is used in the examples. -Position and size units are inventory slots, `X` and `Y` position the formspec -element relative to the top left of the menu or container. `W` and `H` are its -width and height values. +Position and size units are inventory slots unless the new coordinate system +is enabled. `X` and `Y` position the formspec element relative to the top left +of the menu or container. `W` and `H` are its width and height values. + +If the new system is enabled, all elements have unified coordinates for all +elements with no padding or spacing in between. This is highly recommended +for new forms. See `real_coordinates[<bool>]` and `Migrating to Real +Coordinates`. + Inventories with a `player:<name>` inventory location are only sent to the player named `<name>`. @@ -1827,9 +1923,13 @@ When displaying text which can contain formspec code, e.g. text set by a player, use `minetest.formspec_escape`. For coloured text you can use `minetest.colorize`. -WARNING: Minetest allows you to add elements to every single formspec instance +**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 -------- @@ -1859,6 +1959,15 @@ 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 @@ -1893,6 +2002,17 @@ Elements * Must be used after the `size`, `position`, and `anchor` elements (if present). * Disables player:set_formspec_prepend() from applying to this formspec. +### `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. +* **Note**: Formspec prepends are not affected by the coordinates in the main form. + They must enable it explicitly. +* For information on converting forms to the new coordinate system, see `Migrating + to Real Coordinates`. + ### `container[<X>,<Y>]` * Start of a container block, moves all physical elements in the container by @@ -1910,11 +2030,15 @@ Elements * 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. ### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]` * 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[<inventory location>;<list name>]` @@ -1971,29 +2095,44 @@ Elements ### `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>]` -* Use a background. Inventory rectangles are not drawn then. * Example for formspec 8x4 in 16x resolution: image shall be sized 8 times 16px times 4 times 16px. ### `background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]` -* Use a background. Inventory rectangles are not drawn then. * Example for formspec 8x4 in 16x resolution: 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) +### `background9[<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. + * `x` - The middle will be x pixels from all sides. + * `x,y` - The middle will be x pixels from the horizontal and y from the vertical. + * `x,y,x2,y2` - The middle will start at x,y, and end at x2, y2. Negative x2 and y2 values + will be added to the width and height of the texture, allowing it to be used as the + distance from the far end. + * All numbers in middle are integers. +* Example for formspec 8x4 in 16x resolution: + 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>]` * Textual password style field; will be sent to server when a button is clicked * When enter is pressed in field, fields.key_enter_field will be sent with the name of this field. -* Fields are a set height, but will be vertically centred on `H` +* With the old coordinate system, fields are a set height, but will be vertically + centred on `H`. With the new coordinate system, `H` will modify the height. * `name` is the name of the field as returned in fields to `on_receive_fields` * `label`, if not blank, will be text printed on the top left above the field * See `field_close_on_enter` to stop enter closing the formspec @@ -2003,7 +2142,8 @@ Elements * Textual field; will be sent to server when a button is clicked * When enter is pressed in field, `fields.key_enter_field` will be sent with the name of this field. -* Fields are a set height, but will be vertically centred on `H` +* With the old coordinate system, fields are a set height, but will be vertically + centred on `H`. With the new coordinate system, `H` will modify the height. * `name` is the name of the field as returned in fields to `on_receive_fields` * `label`, if not blank, will be text printed on the top left above the field * `default` is the default value of the field @@ -2040,23 +2180,34 @@ Elements * The label formspec element displays the text set in `label` at the specified position. +* **Note**: If the new coordinate system is enabled, labels are + positioned from the center of the text, not the top. * The text is displayed directly without automatic line breaking, - so label should not be used for big text chunks. + so label should not be used for big text chunks. Newlines can be + used to make labels multiline. +* **Note**: With the new coordinate system, newlines are spaced with + half a coordinate. With the old system, newlines are spaced 2/5 of + an inventory slot. ### `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 + positioned from the center of the text, not the left. ### `button[<X>,<Y>;<W>,<H>;<name>;<label>]` * Clickable button. When clicked, fields will be sent. -* Fixed button height. It will be vertically centred on `H` +* With the old coordinate system, buttons are a set height, but will be vertically + centred on `H`. With the new coordinate system, `H` will modify the height. * `label` is the text on the button ### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]` * `texture name` is the filename of an image +* **Note**: Height is supported on both the old and new coordinate systems + for image_buttons. ### `image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]` @@ -2075,10 +2226,12 @@ Elements ### `button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]` * When clicked, fields will be sent and the form will quit. +* Same as `button` in all other respects. ### `image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]` * When clicked, fields will be sent and the form will quit. +* Same as `image_button` in all other respects. ### `textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]` @@ -2104,6 +2257,34 @@ Elements ### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` * Show a tab**header** at specific position (ignores formsize) +* `X` and `Y`: position of the tabheader +* *Note*: Width and height are automatically chosen with this syntax +* `name` fieldname data is transferred to Lua +* `caption 1`...: name shown on top of tab +* `current_tab`: index of selected tab 1... +* `transparent` (optional): show transparent +* `draw_border` (optional): draw border + +### `tabheader[<X>,<Y>;<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` + +* Show a tab**header** at specific position (ignores formsize) +* **Important note**: This syntax for tabheaders can only be used with the + new coordinate system. +* `X` and `Y`: position of the tabheader +* `H`: height of the tabheader. Width is automatically determined with this syntax. +* `name` fieldname data is transferred to Lua +* `caption 1`...: name shown on top of tab +* `current_tab`: index of selected tab 1... +* `transparent` (optional): show transparent +* `draw_border` (optional): draw border + +### `tabheader[<X>,<Y>;<W>,<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` + +* Show a tab**header** at specific position (ignores formsize) +* **Important note**: This syntax for tabheaders can only be used with the + new coordinate system. +* `X` and `Y`: position of the tabheader +* `W` and `H`: width and height of the tabheader * `name` fieldname data is transferred to Lua * `caption 1`...: name shown on top of tab * `current_tab`: index of selected tab 1... @@ -2122,8 +2303,22 @@ Elements * **Important note**: There are two different operation modes: 1. handle directly on change (only changed dropdown is submitted) 2. read the value on pressing a button (all dropdown values are available) -* `x` and `y` position of dropdown -* Width of dropdown +* `X` and `Y`: position of the dropdown +* `W`: width of the dropdown. Height is automatically chosen with this syntax. +* Fieldname data is transferred to Lua +* Items to be shown in dropdown +* Index of currently selected dropdown item + +### `dropdown[<X>,<Y>;<W>,<H>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]` + +* Show a dropdown field +* **Important note**: This syntax for dropdowns can only be used with the + new coordinate system. +* **Important note**: There are two different operation modes: + 1. handle directly on change (only changed dropdown is submitted) + 2. read the value on pressing a button (all dropdown values are available) +* `X` and `Y`: position of the dropdown +* `W` and `H`: width and height of the dropdown * Fieldname data is transferred to Lua * Items to be shown in dropdown * Index of currently selected dropdown item @@ -2134,6 +2329,8 @@ Elements * `name` fieldname data is transferred to Lua * `label` to be shown left of checkbox * `selected` (optional): `true`/`false` +* **Note**: If the new coordinate system is enabled, checkboxes are + positioned from the center of the checkbox, not the top. ### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]` @@ -2207,11 +2404,132 @@ Elements * `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 +----------------------------- + +In the old system, positions included padding and spacing. Padding is a gap between +the formspec window edges and content, and spacing is the gaps between items. For +example, two `1x1` elements at `0,0` and `1,1` would have a spacing of `5/4` between them, +and a padding of `3/8` from the formspec edge. It may be easiest to recreate old layouts +in the new coordinate system from scratch. + +To recreate an old layout with padding, you'll need to pass the positions and sizes +through the following formula to re-introduce padding: + +``` +pos = (oldpos + 1)*spacing + padding +where + padding = 3/8 + spacing = 5/4 +``` +You'll need to change the `size[]` tag like this: +``` +size = (oldsize-1)*spacing + padding*2 + 1 +``` +A few elements had random offsets in the old system. Here is a table which shows these +offsets when migrating: + +| Element | Position | Size | Notes +|---------|------------|---------|------- +| box | +0.3, +0.1 | 0, -0.4 | +| button | | | Buttons now support height, so set h = 2 * 15/13 * 0.35, and reposition if h ~= 15/13 * 0.35 before +| 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. + * bgimg - standard image. Defaults to none. + * 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. Inventory ========= @@ -2234,8 +2552,7 @@ Player Inventory lists * `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 @@ -2340,6 +2657,12 @@ For the following functions, `v`, `v1`, `v2` are vectors, * Returns a boolean, `true` if the vectors are identical. * `vector.sort(v1, v2)`: * Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`. +* `vector.angle(v1, v2)`: + * Returns the angle between `v1` and `v2` in radians. +* `vector.dot(v1, v2)` + * Returns the dot product of `v1` and `v2` +* `vector.cross(v1, v2)` + * Returns the cross product of `v1` and `v2` For the following functions `x` can be either a vector or a number: @@ -2378,6 +2701,7 @@ Helper functions * tolerance: number, default: `0.0` * If the absolute value of `x` is within the `tolerance` or `x` is NaN, `0` is returned. +* `math.factorial(x)`: returns the factorial of `x` * `string.split(str, separator, include_empty, max_splits, sep_is_pattern)` * `separator`: string, default: `","` * `include_empty`: boolean, default: `false` @@ -3191,10 +3515,8 @@ Methods * To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`. * (`p1`, `p2`) is the area in which lighting is set, defaults to the whole - area if left out or nil. - * Setting `p1`, `p2` to `emin`, `emax` of the mapgen object voxelmanip (the - entire volume of the voxelmanip: the mapchunk plus a 1 mapblock thick - shell around it) will cause an error. + area if left out or nil. For almost all uses these should be left out + or nil to use the default. * `propagate_shadow` is an optional boolean deciding whether shadows in a generated mapchunk above are propagated down into the mapchunk, defaults to `true` if left out. @@ -3300,7 +3622,7 @@ Possible fields of the table returned are: * `decoration` Decorations have a key in the format of `"decoration#id"`, where `id` is the -numeric unique decoration ID. +numeric unique decoration ID as returned by `minetest.get_decoration_id`. @@ -3468,11 +3790,18 @@ Utilities -- Chat messages are no longer predicted (0.4.16) no_chat_message_prediction = true, -- The transparency channel of textures can optionally be used on - -- objects (ie: players and lua entities) (5.0) + -- objects (ie: players and lua entities) (5.0.0) object_use_texture_alpha = true, -- Object selectionbox is settable independently from collisionbox - -- (5.0) + -- (5.0.0) object_independent_selectionbox = true, + -- 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` @@ -3492,6 +3821,7 @@ Utilities 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 @@ -3566,21 +3896,24 @@ Call these functions only at load time! mapgens. See [Mapgen aliases] section above. * `minetest.register_alias_force(alias, original_name)` * `minetest.register_ore(ore definition)` - * Returns an integer uniquely identifying the registered ore on success. + * Returns an integer object handle uniquely identifying the registered + ore on success. * The order of ore registrations determines the order of ore generation. * `minetest.register_biome(biome definition)` - * Returns an integer uniquely identifying the registered biome on success. + * Returns an integer object handle uniquely identifying the registered + biome on success. To get the biome ID, use `minetest.get_biome_id`. * `minetest.unregister_biome(name)` * Unregisters the biome from the engine, and deletes the entry with key `name` from `minetest.registered_biomes`. * `minetest.register_decoration(decoration definition)` - * Returns an integer uniquely identifying the registered decoration on - success. + * Returns an integer object handle uniquely identifying the registered + decoration on success. To get the decoration ID, use + `minetest.get_decoration_id`. * The order of decoration registrations determines the order of decoration generation. * `minetest.register_schematic(schematic definition)` - * Returns an integer uniquely identifying the registered schematic on - success. + * Returns an integer object handle uniquely identifying the registered + schematic on success. * If the schematic is loaded from a file, the `name` field is set to the filename. * If the function is called when loading the mod, and `name` is a relative @@ -3659,6 +3992,7 @@ Call these functions only at load time! * Called after a new player has been created * `minetest.register_on_punchplayer(function(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))` * Called when a player is punched + * Note: This callback is invoked even if the punched player is dead. * `player`: ObjectRef - Player that was punched * `hitter`: ObjectRef - Player that hit * `time_from_last_punch`: Meant for disallowing spamming of clicks @@ -3678,15 +4012,16 @@ Call these functions only at load time! giving a type - use this for custom damage types. * `punch`: Was punched. `reason.object` will hold the puncher, or nil if none. * `fall` - * `node_damage`: damage_per_second from a neighbouring node. + * `node_damage`: `damage_per_second` from a neighbouring node. + `reason.node` will hold the node name or nil. * `drown` * `respawn` * Any of the above types may have additional fields from mods. * `reason.from` will be `mod` or `engine`. * `modifier`: when true, the function should return the actual `hp_change`. - Note: modifiers only get a temporary hp_change that can be modified by later modifiers. - modifiers can return true as a second argument to stop the execution of further functions. - Non-modifiers receive the final hp change calculated by the modifiers. + Note: modifiers only get a temporary `hp_change` that can be modified by later modifiers. + Modifiers can return true as a second argument to stop the execution of further functions. + Non-modifiers receive the final HP change calculated by the modifiers. * `minetest.register_on_dieplayer(function(ObjectRef, reason))` * Called when a player dies * `reason`: a PlayerHPChangeReason table, see register_on_player_hpchange @@ -3794,8 +4129,7 @@ Call these functions only at load time! 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, @@ -3875,6 +4209,12 @@ Chat * `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 ------------------ @@ -4255,7 +4595,10 @@ Item handling * `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"`. @@ -4557,6 +4900,18 @@ Schematics 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 ------------- @@ -4675,15 +5030,13 @@ Misc. * `minetest.decode_base64(string)`: returns string * Decodes a string encoded in base64. * `minetest.is_protected(pos, name)`: returns boolean - * Returns true, if player `name` shouldn't be able to dig at `pos` or do - other actions, definable by mods, due to some mod-defined ownership-like - concept. - * Returns false or nil, if the player is allowed to do such actions. - * `name` will be "" for non-players or unknown players. - * This function should be overridden by protection mods and should be used - to check if a player can interact at a position. - * This function should call the old version of itself if the position is - not protected by the mod. + * Returning `true` restricts the player `name` from modifying (i.e. digging, + placing) the node at position `pos`. + * `name` will be `""` for non-players or unknown players. + * This function should be overridden by protection mods. It is highly + recommended to grant access to players with the `protection_bypass` privilege. + * Cache and call the old version of this function if the position is + not protected by the mod. This will allow using multiple protection mods. * Example: local old_is_protected = minetest.is_protected @@ -4734,6 +5087,15 @@ Misc. 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 @@ -4794,17 +5156,19 @@ Global tables * Map of registered aliases, indexed by name * `minetest.registered_ores` * Map of registered ore definitions, indexed by the `name` field. - * If `name` is nil, the key is the ID returned by `minetest.register_ore`. + * If `name` is nil, the key is the object handle returned by + `minetest.register_ore`. * `minetest.registered_biomes` * Map of registered biome definitions, indexed by the `name` field. - * If `name` is nil, the key is the ID returned by `minetest.register_biome`. + * If `name` is nil, the key is the object handle returned by + `minetest.register_biome`. * `minetest.registered_decorations` * Map of registered decoration definitions, indexed by the `name` field. - * If `name` is nil, the key is the ID returned by + * If `name` is nil, the key is the object handle returned by `minetest.register_decoration`. * `minetest.registered_schematics` * Map of registered schematic definitions, indexed by the `name` field. - * If `name` is nil, the key is the ID returned by + * If `name` is nil, the key is the object handle returned by `minetest.register_schematic`. * `minetest.registered_chatcommands` * Map of registered chat command definitions, indexed by name @@ -4831,35 +5195,38 @@ 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)`. +`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. @@ -4945,6 +5312,7 @@ an itemstring, a table or `nil`. * `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. @@ -4988,7 +5356,8 @@ Can be obtained via `item:get_meta()`. `MetaDataRef` ------------- -See [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], and [`PlayerMetaRef`]. +Base class used by [`StorageRef`], [`NodeMetaRef`], [`ItemStackMetaRef`], +and [`PlayerMetaRef`]. ### Methods @@ -5082,11 +5451,13 @@ This is basically a reference to a C++ `ServerActiveObject` ### Methods -* `remove()`: remove object (after returning from Lua) - * Note: Doesn't work on players, use `minetest.kick_player` instead * `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 @@ -5095,7 +5466,7 @@ This is basically a reference to a C++ `ServerActiveObject` * `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 @@ -5142,8 +5513,9 @@ This is basically a reference to a C++ `ServerActiveObject` text = "My Nametag", } -#### LuaEntitySAO-only (no-op for other objects) +#### Lua entity only (no-op for other objects) +* `remove()`: remove object (after returning from Lua) * `set_velocity(vel)` * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}` * `add_velocity(vel)` @@ -5174,11 +5546,19 @@ This is basically a reference to a C++ `ServerActiveObject` * `get_entity_name()` (**Deprecated**: Will be removed in a future version) * `get_luaentity()` -#### Player-only (no-op for other objects) +#### Player only (no-op for other objects) * `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 @@ -5200,12 +5580,21 @@ This is basically a reference to a C++ `ServerActiveObject` `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 @@ -5322,6 +5711,11 @@ This is basically a reference to a C++ `ServerActiveObject` * in first person view * in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`) * `get_eye_offset()`: returns `offset_first` and `offset_third` +* `send_mapblock(blockpos)`: + * Sends a server-side loaded mapblock to the player. + * Returns `false` if failed. + * Resource intensive - use sparsely + * To get blockpos, integer divide pos by 16 `PcgRandom` ----------- @@ -5497,12 +5891,26 @@ It can be created via `Settings(filename)`. * 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 @@ -5517,6 +5925,9 @@ Object properties ----------------- 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, @@ -5560,7 +5971,7 @@ Used by `ObjectRef` methods. Part of an Entity definition. -- "mesh" uses the defined mesh model. -- "wielditem" is used for dropped items. -- (see builtin/game/item_entity.lua). - -- For this use 'textures = {itemname}'. + -- For this use 'wield_item = itemname' (Deprecated: 'textures = {itemname}'). -- If the item has a 'wield_image' the object will be an extrusion of -- that, otherwise: -- If 'itemname' is a cubic node or nodebox the object will appear @@ -5569,6 +5980,8 @@ Used by `ObjectRef` methods. Part of an Entity definition. -- of its texture. -- Otherwise for non-node items, the object will be an extrusion of -- 'inventory_image'. + -- If 'itemname' contains a ColorString or palette index (e.g. from + -- `minetest.itemstring_with_palette()`), the entity will inherit the color. -- "item" is similar to "wielditem" but ignores the 'wield_image' parameter. visual_size = {x = 1, y = 1, z = 1}, @@ -5620,7 +6033,7 @@ Used by `ObjectRef` methods. Part of an Entity definition. automatic_face_movement_max_rotation_per_sec = -1, -- Limit automatic rotation to this value in degrees per second. - -- No limit if value < 0. + -- No limit if value <= 0. backface_culling = true, -- Set to false to disable backface_culling for model @@ -5728,6 +6141,10 @@ LBM (LoadingBlockModifier) definition 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). @@ -5742,8 +6159,8 @@ Used by `minetest.register_lbm`. 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), } @@ -5848,7 +6265,7 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and 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, @@ -5858,6 +6275,14 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and 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, @@ -5980,7 +6405,11 @@ Used by `minetest.register_node`. place_param2 = nil, -- Force value for param2 when player places node is_ground_content = true, - -- If false, the cave generator will not carve through this node + -- If false, the cave generator and dungeon generator will not carve + -- through this node. + -- Specifically, this stops mod-added nodes being removed by caves and + -- dungeons when those generate in a neighbor mapchunk and extend out + -- beyond the edge of that mapchunk. sunlight_propagates = false, -- If true, sunlight will go infinitely through this node @@ -6071,12 +6500,15 @@ Used by `minetest.register_node`. legacy_wallmounted = false, waving = 0, - -- Valid for mesh, nodebox, plantlike, allfaces_optional nodes. - -- 1 - wave node like plants (top of node moves, bottom is fixed) + -- Valid for drawtypes: + -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid. + -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed) -- 2 - wave node like leaves (whole node moves side-to-side) - -- caveats: not all models will properly wave. - -- plantlike drawtype nodes can only wave like plants. - -- allfaces_optional drawtype nodes can only wave like leaves. + -- 3 - wave node like liquids (whole node moves up and down) + -- Not all models will properly wave. + -- plantlike drawtype can only wave like plants. + -- allfaces_optional drawtype can only wave like leaves. + -- liquid, flowingliquid drawtypes can only wave like liquids. sounds = { footstep = <SimpleSoundSpec>, @@ -6084,20 +6516,51 @@ Used by `minetest.register_node`. dug = <SimpleSoundSpec>, place = <SimpleSoundSpec>, place_failed = <SimpleSoundSpec>, + fall = <SimpleSoundSpec>, }, drop = "", - -- Name of dropped node when dug. Default is the node itself. - -- Alternatively: + -- Name of dropped item when dug. + -- Default dropped item is the node itself. + -- 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 = { - -- Maximum number of items to drop max_items = 1, - -- Choose max_items randomly from this list + -- Maximum number of item lists to drop. + -- The entries in 'items' are processed in order. For each: + -- Tool filtering is applied, chance of drop is applied, if both are + -- successful the entire item list is dropped. + -- Entry processing continues until the number of dropped item lists + -- equals 'max_items'. + -- Therefore, entries should progress from low to high drop chance. items = { + -- Entry examples. + { + -- 1 in 1000 chance of dropping a diamond. + -- Default rarity is '1'. + rarity = 1000, + items = {"default:diamond"}, + }, + { + -- Only drop if using a tool whose name is identical to one + -- of these. + tools = {"default:shovel_mese", "default:shovel_diamond"}, + rarity = 5, + items = {"default:dirt"}, + -- Whether all items in the dropped item list inherit the + -- hardware coloring palette color from the dug node. + -- Default is 'false'. + inherit_color = true, + }, { - items = {"foo:bar", "baz:frob"}, -- Items to drop - rarity = 1, -- Probability of dropping is 1 / rarity - inherit_color = true, -- Inherit palette color from the node + -- Only drop if using a tool whose name contains + -- "default:shovel_" (this tool filtering by string matching + -- is deprecated). + tools = {"~default:shovel_"}, + rarity = 2, + -- The item list dropped. + items = {"default:sand", "default:desert_sand"}, }, }, }, @@ -6151,10 +6614,10 @@ Used by `minetest.register_node`. -- 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. @@ -6409,14 +6872,20 @@ Used by `minetest.register_biome`. depth_riverbed = 2, -- Node placed under river water and thickness of this layer - node_cave_liquid = "default:water_source", - -- Nodes placed as a blob of liquid in 50% of large caves. - -- If absent, cave liquids fall back to classic behaviour of lava or - -- water distributed according to a hardcoded 3D noise. + node_cave_liquid = "default:lava_source", + node_cave_liquid = {"default:water_source", "default:lava_source"}, + -- Nodes placed inside 50% of the medium size caves. + -- Multiple nodes can be specified, each cave will use a randomly + -- chosen node from the list. + -- If this field is left out or 'nil', cave liquids fall back to + -- classic behaviour of lava and water distributed using 3D noise. + -- For no cave liquid, specify "air". node_dungeon = "default:cobble", -- Node used for primary dungeon structure. - -- If absent, dungeon materials fall back to classic behaviour. + -- If absent, dungeon nodes fall back to the 'mapgen_cobble' mapgen + -- alias, if that is also absent, dungeon nodes fall back to the biome + -- 'node_stone'. -- If present, the following two nodes are also used. node_dungeon_alt = "default:mossycobble", @@ -6645,10 +7114,11 @@ Privilege definition 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. diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt index 2c76c6b8f..a2f9c3f5b 100644 --- a/doc/menu_lua_api.txt +++ b/doc/menu_lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Mainmenu API Reference 5.0.1 +Minetest Lua Mainmenu API Reference 5.1.0 ========================================= Introduction @@ -79,6 +79,8 @@ core.explode_table_event(string) -> table core.explode_textlist_event(string) -> table ^ returns e.g. {type="CHG", index=1} ^ type: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click) +core.set_formspec_prepend(formspec) +^ string to be added to every mainmenu formspec, to be used for theming. GUI: core.set_background(type, texturepath,[tile],[minsize]) @@ -89,13 +91,14 @@ core.set_background(type, texturepath,[tile],[minsize]) core.set_clouds(<true/false>) core.set_topleft_text(text) core.show_keys_menu() -core.file_open_dialog(formname,caption) -^ shows a file open dialog +core.show_path_select_dialog(formname, caption, is_file_select) +^ shows a path select dialog ^ formname is base name of dialog response returned in fields ^ -if dialog was accepted "_accepted" -^^ will be added to fieldname containing the path +^ will be added to fieldname containing the path ^ -if dialog was canceled "_cancelled" ^ will be added to fieldname value is set to formname itself +^ if `is_file_select` is `true`, a file and not a folder will be selected ^ returns nil or selected file/folder core.get_screen_info() ^ returns { @@ -240,4 +243,4 @@ Limitations of Async operations -No access to global lua variables, don't even try -Limited set of available functions e.g. No access to functions modifying menu like core.start,core.close, - core.file_open_dialog + core.show_path_select_dialog diff --git a/doc/mkdocs/build.sh b/doc/mkdocs/build.sh new file mode 100755 index 000000000..f4d946874 --- /dev/null +++ b/doc/mkdocs/build.sh @@ -0,0 +1,41 @@ +#!/bin/sh -e + +# Patch Python-Markdown +MARKDOWN_FILE=$(pip show markdown | awk '/Location/ { print $2 }')/markdown/extensions/codehilite.py +patch -N -r - $MARKDOWN_FILE lua_highlight.patch || true + +# Split lua_api.txt on top level headings +cat ../lua_api.txt | csplit -sz -f docs/section - '/^=/-1' '{*}' + +cat > mkdocs.yml << EOF +site_name: Minetest API Documentation +theme: + name: readthedocs + highlightjs: False +extra_css: + - css/code_styles.css + - css/extra.css +markdown_extensions: + - toc: + permalink: True + - codehilite +plugins: + - search: + separator: '[\s\-\.\(]+' +nav: +- "Home": index.md +EOF + +mv docs/section00 docs/index.md + +for f in docs/section* +do + title=$(head -1 $f) + fname=$(echo $title | tr '[:upper:]' '[:lower:]') + fname=$(echo $fname | sed 's/ /-/g') + fname=$(echo $fname | sed "s/'//g").md + mv $f docs/$fname + echo "- \"$title\": $fname" >> mkdocs.yml +done + +mkdocs build --site-dir ../../public diff --git a/doc/mkdocs/docs/css/code_styles.css b/doc/mkdocs/docs/css/code_styles.css new file mode 100644 index 000000000..c135acd94 --- /dev/null +++ b/doc/mkdocs/docs/css/code_styles.css @@ -0,0 +1,68 @@ +.codehilite .hll { background-color: #ffffcc } +.codehilite .c { color: #408080; font-style: italic } /* Comment */ +/* .codehilite .err { border: 1px solid #FF0000 } /* Error */ +.codehilite .k { color: #008000; font-weight: bold } /* Keyword */ +.codehilite .o { color: #666666 } /* Operator */ +.codehilite .ch { color: #408080; font-style: italic } /* Comment.Hashbang */ +.codehilite .cm { color: #408080; font-style: italic } /* Comment.Multiline */ +.codehilite .cp { color: #BC7A00 } /* Comment.Preproc */ +.codehilite .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */ +.codehilite .c1 { color: #408080; font-style: italic } /* Comment.Single */ +.codehilite .cs { color: #408080; font-style: italic } /* Comment.Special */ +.codehilite .gd { color: #A00000 } /* Generic.Deleted */ +.codehilite .ge { font-style: italic } /* Generic.Emph */ +.codehilite .gr { color: #FF0000 } /* Generic.Error */ +.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.codehilite .gi { color: #00A000 } /* Generic.Inserted */ +.codehilite .go { color: #888888 } /* Generic.Output */ +.codehilite .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ +.codehilite .gs { font-weight: bold } /* Generic.Strong */ +.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.codehilite .gt { color: #0044DD } /* Generic.Traceback */ +.codehilite .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ +.codehilite .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ +.codehilite .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ +.codehilite .kp { color: #008000 } /* Keyword.Pseudo */ +.codehilite .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ +.codehilite .kt { color: #B00040 } /* Keyword.Type */ +.codehilite .m { color: #666666 } /* Literal.Number */ +.codehilite .s { color: #BA2121 } /* Literal.String */ +.codehilite .na { color: #7D9029 } /* Name.Attribute */ +.codehilite .nb { color: #008000 } /* Name.Builtin */ +.codehilite .nc { color: #0000FF; font-weight: bold } /* Name.Class */ +.codehilite .no { color: #880000 } /* Name.Constant */ +.codehilite .nd { color: #AA22FF } /* Name.Decorator */ +.codehilite .ni { color: #999999; font-weight: bold } /* Name.Entity */ +.codehilite .ne { color: #D2413A; font-weight: bold } /* Name.Exception */ +.codehilite .nf { color: #0000FF } /* Name.Function */ +.codehilite .nl { color: #A0A000 } /* Name.Label */ +.codehilite .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ +.codehilite .nt { color: #008000; font-weight: bold } /* Name.Tag */ +.codehilite .nv { color: #19177C } /* Name.Variable */ +.codehilite .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ +.codehilite .w { color: #bbbbbb } /* Text.Whitespace */ +.codehilite .mb { color: #666666 } /* Literal.Number.Bin */ +.codehilite .mf { color: #666666 } /* Literal.Number.Float */ +.codehilite .mh { color: #666666 } /* Literal.Number.Hex */ +.codehilite .mi { color: #666666 } /* Literal.Number.Integer */ +.codehilite .mo { color: #666666 } /* Literal.Number.Oct */ +.codehilite .sa { color: #BA2121 } /* Literal.String.Affix */ +.codehilite .sb { color: #BA2121 } /* Literal.String.Backtick */ +.codehilite .sc { color: #BA2121 } /* Literal.String.Char */ +.codehilite .dl { color: #BA2121 } /* Literal.String.Delimiter */ +.codehilite .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ +.codehilite .s2 { color: #BA2121 } /* Literal.String.Double */ +.codehilite .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ +.codehilite .sh { color: #BA2121 } /* Literal.String.Heredoc */ +.codehilite .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ +.codehilite .sx { color: #008000 } /* Literal.String.Other */ +.codehilite .sr { color: #BB6688 } /* Literal.String.Regex */ +.codehilite .s1 { color: #BA2121 } /* Literal.String.Single */ +.codehilite .ss { color: #19177C } /* Literal.String.Symbol */ +.codehilite .bp { color: #008000 } /* Name.Builtin.Pseudo */ +.codehilite .fm { color: #0000FF } /* Name.Function.Magic */ +.codehilite .vc { color: #19177C } /* Name.Variable.Class */ +.codehilite .vg { color: #19177C } /* Name.Variable.Global */ +.codehilite .vi { color: #19177C } /* Name.Variable.Instance */ +.codehilite .vm { color: #19177C } /* Name.Variable.Magic */ +.codehilite .il { color: #666666 } /* Literal.Number.Integer.Long */ diff --git a/doc/mkdocs/docs/css/extra.css b/doc/mkdocs/docs/css/extra.css new file mode 100644 index 000000000..8fde9f893 --- /dev/null +++ b/doc/mkdocs/docs/css/extra.css @@ -0,0 +1,15 @@ +/* Fix partly obscured last TOC element */ +.wy-menu { + padding-bottom: 20px; +} + +/* Use Minetest green instead of blue */ +.wy-nav-content a { + color: hsl(100, 40%, 40%); +} +.wy-nav-content a:hover { + color: hsl(100, 30%, 30%); +} +.wy-side-nav-search, .wy-nav-top, .wy-menu-vertical a:active { + background: hsl(100, 40%, 40%); +} diff --git a/doc/mkdocs/docs/img/favicon.ico b/doc/mkdocs/docs/img/favicon.ico new file mode 120000 index 000000000..cac34a30c --- /dev/null +++ b/doc/mkdocs/docs/img/favicon.ico @@ -0,0 +1 @@ +../../../../misc/minetest-icon.ico
\ No newline at end of file diff --git a/doc/mkdocs/lua_highlight.patch b/doc/mkdocs/lua_highlight.patch new file mode 100644 index 000000000..034a63a33 --- /dev/null +++ b/doc/mkdocs/lua_highlight.patch @@ -0,0 +1,19 @@ +@@ -77,7 +77,7 @@ + css_class="codehilite", lang=None, style='default', + noclasses=False, tab_length=4, hl_lines=None, use_pygments=True): + self.src = src +- self.lang = lang ++ self.lang = "lua" + self.linenums = linenums + self.guess_lang = guess_lang + self.css_class = css_class +@@ -119,7 +119,8 @@ + cssclass=self.css_class, + style=self.style, + noclasses=self.noclasses, +- hl_lines=self.hl_lines) ++ hl_lines=self.hl_lines, ++ wrapcode=True) + return highlight(self.src, lexer, formatter) + else: + # just escape and build markup usable by JS highlighting libs diff --git a/doc/world_format.txt b/doc/world_format.txt index c5d1d1be1..7cbf13af6 100644 --- a/doc/world_format.txt +++ b/doc/world_format.txt @@ -365,7 +365,9 @@ if map format version <= 22: u16 content_size u8[content_size] content of metadata. Format depends on type_id, see below. if map format version >= 23: - u8 version (=1) -- Note the type is u8, while for map format version <= 22 it's u16 + u8 version -- Note: type was u16 for map format version <= 22 + -- = 1 for map format version < 28 + -- = 2 since map format version 28 u16 count of metadata foreach count: u16 position (p.Z*MAP_BLOCKSIZE*MAP_BLOCKSIZE + p.Y*MAP_BLOCKSIZE + p.X) @@ -375,6 +377,7 @@ if map format version >= 23: u8[key_len] key u32 val_len u8[val_len] value + u8 is_private -- only for version >= 2. 0 = not private, 1 = private serialized inventory - Node timers @@ -510,17 +513,20 @@ Object types: u8[len] itemstring 7: LuaEntity: - u8 version - version 1: - u16 len - u8[len] entity name - u32 len - u8[len] static data - s16 hp - s32 velocity.x * 10000 - s32 velocity.y * 10000 - s32 velocity.z * 10000 - s32 yaw * 1000 + u8 compatibility_byte (always 1) + u16 len + u8[len] entity name + u32 len + u8[len] static data + s16 hp + s32 velocity.x * 10000 + s32 velocity.y * 10000 + s32 velocity.z * 10000 + s32 yaw * 1000 + if PROTOCOL_VERSION >= 37: + u8 version2 (=1) + s32 pitch * 1000 + s32 roll * 1000 Itemstring format ------------------ |