diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile.in | 12 | ||||
| -rw-r--r-- | doc/README.android | 75 | ||||
| -rw-r--r-- | doc/client_lua_api.txt | 69 | ||||
| -rw-r--r-- | doc/fst_api.txt | 7 | ||||
| -rw-r--r-- | doc/lua_api.txt | 422 | ||||
| -rw-r--r-- | doc/menu_lua_api.txt | 271 | ||||
| -rw-r--r-- | doc/minetest.6 | 6 | ||||
| -rw-r--r-- | doc/mkdocs/lua_highlight.patch | 12 | ||||
| -rw-r--r-- | doc/texture_packs.txt | 49 |
9 files changed, 654 insertions, 269 deletions
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 3618b852d..d7816f0e4 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -20,18 +20,10 @@ PREDEFINED = "USE_SPATIAL=1" \ "USE_GETTEXT=1" # Input -RECURSIVE = NO +RECURSIVE = YES STRIP_FROM_PATH = @CMAKE_CURRENT_SOURCE_DIR@/src INPUT = @CMAKE_CURRENT_SOURCE_DIR@/doc/main_page.dox \ - @CMAKE_CURRENT_SOURCE_DIR@/src/ \ - @CMAKE_CURRENT_SOURCE_DIR@/src/client \ - @CMAKE_CURRENT_SOURCE_DIR@/src/network \ - @CMAKE_CURRENT_SOURCE_DIR@/src/util \ - @CMAKE_CURRENT_SOURCE_DIR@/src/script \ - @CMAKE_CURRENT_SOURCE_DIR@/src/script/common \ - @CMAKE_CURRENT_SOURCE_DIR@/src/script/cpp_api \ - @CMAKE_CURRENT_SOURCE_DIR@/src/script/lua_api \ - @CMAKE_CURRENT_SOURCE_DIR@/src/threading + @CMAKE_CURRENT_SOURCE_DIR@/src/ # Dot graphs HAVE_DOT = @DOXYGEN_DOT_FOUND@ diff --git a/doc/README.android b/doc/README.android index c21279583..f6b67978f 100644 --- a/doc/README.android +++ b/doc/README.android @@ -1,6 +1,5 @@ -Minetest Android port -===================== -Date: 2014 06 28 +Minetest: Android version +========================= Controls -------- @@ -40,25 +39,6 @@ file can usually be found at /mnt/sdcard/Minetest. main menu is too big or small on your device, try changing this value. -Known issues ------------- -Not all issues are fixed by now: - -* Unable to exit from volume menu -- don't use the volume menu, use Android's - volume controls instead. -* 512 MB RAM seems to be inadequate -- this depends on the server you join. - Try to play on more lightweight servers. - -Versioning ----------- -Android version numbers are 4 digits instead of Minetest's 3 digits. The last -number of Android's version represents the Android internal version code. This -version code is strictly incremental. It's incremented for each official -Minetest Android build. - -E.g. prerelease Minetest Android builds have been 0.4.9.3, while the first -official version most likely will be 0.4.10.4 - Requirements ------------ @@ -69,9 +49,9 @@ following software packages. The version number in parenthesis denotes the version that was tested at the time this README was drafted; newer/older versions may or may not work. -* android SDK (api-26) -* android NDK (r17c) -* wget (1.13.4) +* Android SDK 29 +* Android NDK r21 +* Android Studio 3 [optional] Additionally, you'll need to have an Internet connection available on the build system, as the Android build will download some source packages. @@ -79,16 +59,15 @@ build system, as the Android build will download some source packages. Build ----- -Debug build: -* Enter "build/android" subdirectory -* Execute "make" -* Answer the questions about where SDK and NDK are located on your filesystem -* Wait for build to finish - -After the build is finished, the resulting apk can be fond in -build/android/bin/. It will be called Minetest-debug.apk +The new build system Minetest Android is fully functional and is designed to +speed up and simplify the work, as well as adding the possibility of +cross-platform build. +You can use `./gradlew assemblerelease` or `./gradlew assembledebug` from the +command line or use Android Studio and click the build button. -Release build: +When using gradlew, the newest NDK will be downloaded and installed +automatically. Or you can create a `local.properties` file and specify +`sdk.dir` and `ndk.dir` yourself. * In order to make a release build you'll have to have a keystore setup to sign the resulting apk package. How this is done is not part of this README. There @@ -97,32 +76,6 @@ Release build: * Once your keystore is setup, enter build/android subdirectory and create a new file "ant.properties" there. Add following lines to that file: - + > key.store=<path to your keystore> > key.alias=Minetest - -* Execute "make release" -* Enter your keystore as well as your Mintest key password once asked. Be - careful it's shown on console in clear text! -* The result can be found at "bin/Minetest-release.apk" - -Other things that may be nice to know ------------- -* The environment for Android development tools is saved within Android build - build folder. If you want direct access to it do: - - > make envpaths - > . and_env - - After you've done this you'll have your path and path variables set correct - to use adb and all other Android development tools - -* You can build a single dependency by calling make and the dependency's name, - e.g.: - - > make irrlicht - -* You can completely cleanup a dependency by calling make and the "clean" target, - e.g.: - - > make clean_irrlicht diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt index c24de8d85..c9cd8ac93 100644 --- a/doc/client_lua_api.txt +++ b/doc/client_lua_api.txt @@ -1,4 +1,4 @@ -Minetest Lua Client Modding API Reference 5.2.0 +Minetest Lua Client Modding API Reference 5.3.0 ================================================ * More information at <http://www.minetest.net/> * Developer Wiki: <http://dev.minetest.net/> @@ -112,7 +112,7 @@ The main Lua script. Running this script should register everything it wants to register. Subsequent execution depends on minetest calling the registered callbacks. -**NOTE**: Client mods currently can't provide and textures, sounds or models by +**NOTE**: Client mods currently can't provide textures, sounds, or models by themselves. Any media referenced in function calls must already be loaded (provided by mods that exist on the server). @@ -734,6 +734,13 @@ Call these functions only at load time! * `spec` is a `SimpleSoundSpec` * `parameters` is a sound parameter table * `minetest.sound_stop(handle)` + * `handle` is a handle returned by `minetest.sound_play` +* `minetest.sound_fade(handle, step, gain)` + * `handle` is a handle returned by `minetest.sound_play` + * `step` determines how fast a sound will fade. + Negative step will lower the sound volume, positive step will increase + the sound volume. + * `gain` the target gain for the fade. ### Timing * `minetest.after(time, func, ...)` @@ -797,8 +804,6 @@ Call these functions only at load time! * get max available level for leveled node ### Player -* `minetest.get_wielded_item()` - * Returns the itemstack the local player is holding * `minetest.send_chat_message(message)` * Act as if `message` was typed by the player into the terminal. * `minetest.run_server_chatcommand(cmd, param)` @@ -962,7 +967,7 @@ Please do not try to access the reference until the camera is initialized, other * `get_camera_mode()` * Returns 0, 1, or 2 as described above * `get_fov()` - * Returns: + * Returns a table with X, Y, maximum and actual FOV in degrees: ```lua { @@ -999,6 +1004,10 @@ Methods: * returns player HP * `get_name()` * returns player name +* `get_wield_index()` + * returns the index of the wielded item +* `get_wielded_item()` + * returns the itemstack the player is holding * `is_attached()` * returns true if player is attached * `is_touching_ground()` @@ -1022,7 +1031,8 @@ Methods: jump = float, gravity = float, sneak = boolean, - sneak_glitch = boolean + sneak_glitch = boolean, + new_move = boolean, } ``` @@ -1074,8 +1084,26 @@ Methods: * returns last look horizontal angle * `get_last_look_vertical()`: * returns last look vertical angle -* `get_key_pressed()`: - * returns last key typed by the player +* `get_control()`: + * returns pressed player controls + +```lua + { + up = boolean, + down = boolean, + left = boolean, + right = boolean, + jump = boolean, + aux1 = boolean, + sneak = boolean, + zoom = boolean, + LMB = boolean, + RMB = boolean, + } +``` + +* `get_armor_groups()` + * returns a table with the armor group ratings * `hud_add(definition)` * add a HUD element described by HUD def, returns ID number on success and `nil` on failure. * See [`HUD definition`](#hud-definition-hud_add-hud_get) @@ -1388,12 +1416,35 @@ Displays a horizontal bar made up of half-images. * `offset`: offset in pixels from position. ### `waypoint` + Displays distance to selected world position. * `name`: The name of the waypoint. * `text`: Distance suffix. Can be blank. -* `number:` An integer containing the RGB value of the color used to draw the text. +* `precision`: Waypoint precision, integer >= 0. Defaults to 10. + If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`. + When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point. + `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`). + `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on: + `precision = n` will show multiples of `1/n` +* `number:` An integer containing the RGB value of the color used to draw the + text. * `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. +* `alignment`: The alignment of the waypoint. + +### `image_waypoint` + +Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint. + +* `scale`: The scale of the image, with 1 being the original texture size. + Only the X coordinate scale is used (positive values). + Negative values represent that percentage of the screen it + should take; e.g. `x=-100` means 100% (width). +* `text`: The name of the texture that is displayed. +* `alignment`: The alignment of the image. +* `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. ### Particle definition (`add_particle`) diff --git a/doc/fst_api.txt b/doc/fst_api.txt index c8bcb1e91..6f9aa14b3 100644 --- a/doc/fst_api.txt +++ b/doc/fst_api.txt @@ -101,6 +101,9 @@ dialog_create(name, cbf_formspec, cbf_button_handler, cbf_events) ^ cbf_events: function to handle events function(dialog, event) +messagebox(name, message) +^ creates a message dialog + Class reference dialog: methods: @@ -113,13 +116,13 @@ methods: ^ hide dialog - delete() ^ delete dialog from ui - + members: - data ^ variable data attached to this dialog - parent ^ parent component to return to on exit - + File: fst/buttonbar.lua ----------------------- diff --git a/doc/lua_api.txt b/doc/lua_api.txt index bd95062a5..f2a83eca5 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -64,9 +64,21 @@ The game directory can contain the following files: * `game.conf`, with the following keys: * `name`: Required, human readable name e.g. `name = Minetest` * `description`: Short description to be shown in the content tab + * `allowed_mapgens = <comma-separated mapgens>` + e.g. `allowed_mapgens = v5,v6,flat` + Mapgens not in this list are removed from the list of mapgens for + the game. + If not specified, all mapgens are allowed. * `disallowed_mapgens = <comma-separated mapgens>` e.g. `disallowed_mapgens = v5,v6,flat` These mapgens are removed from the list of mapgens for the game. + When both `allowed_mapgens` and `disallowed_mapgens` are + specified, `allowed_mapgens` is applied before + `disallowed_mapgens`. + * `disallowed_mapgen_settings= <comma-separated mapgen settings>` + e.g. `disallowed_mapgen_settings = mgv5_spflags` + These settings are hidden for this game in the world creation + dialog and game start menu. * `minetest.conf`: Used to set default settings when running this game. * `settingtypes.txt`: @@ -889,6 +901,7 @@ These sound files are played back by the engine if provided. * `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) + * `player_jump`: Played when the local player jumps * `default_dig_<groupname>`: Default node digging sound (see node sound definition for details) @@ -1010,22 +1023,24 @@ The function of `param2` is determined by `paramtype2` in node definition. * Values range 0 - 179. The value stored in `param2` is multiplied by two to get the actual rotation in degrees of the node. * `paramtype2 = "meshoptions"` - * Only valid for "plantlike" drawtype. The value of `param2` becomes a - bitfield which can be used to change how the client draws plantlike nodes. - * Bits 0, 1 and 2 form a mesh selector. - Currently the following meshes are choosable: + * Only valid for "plantlike" drawtype. `param2` encodes the shape and + optional modifiers of the "plant". `param2` is a bitfield. + * Bits 0 to 2 select the shape. + Use only one of the values below: * 0 = a "x" shaped plant (ordinary plant) * 1 = a "+" shaped plant (just rotated 45 degrees) * 2 = a "*" shaped plant with 3 faces instead of 2 * 3 = a "#" shaped plant with 4 faces instead of 2 * 4 = a "#" shaped plant with 4 faces that lean outwards * 5-7 are unused and reserved for future meshes. - * Bits 3 through 7 are optional flags that can be combined and give these - effects: - * bit 3 (0x08) - Makes the plant slightly vary placement horizontally - * bit 4 (0x10) - Makes the plant mesh 1.4x larger - * bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max) - * bits 6-7 are reserved for future use. + * Bits 3 to 7 are used to enable any number of optional modifiers. + Just add the corresponding value(s) below to `param2`: + * 8 - Makes the plant slightly vary placement horizontally + * 16 - Makes the plant mesh 1.4x larger + * 32 - Moves each face randomly a small bit down (1/8 max) + * values 64 and 128 (bits 6-7) are reserved for future use. + * Example: `param2 = 0` selects a normal "x" shaped plant + * Example: `param2 = 17` selects a "+" shaped plant, 1.4x larger (1+16) * `paramtype2 = "color"` * `param2` tells which color is picked from the palette. The palette should have 256 pixels. @@ -1054,7 +1069,7 @@ Node drawtypes There are a bunch of different looking node types. -Look for examples in `games/minimal` or `games/minetest_game`. +Look for examples in `games/devtest` or `games/minetest_game`. * `normal` * A node-sized cube. @@ -1278,9 +1293,9 @@ To account for differing resolutions, the position coordinates are the percentage of the screen, ranging in value from `0` to `1`. The name field is not yet used, but should contain a description of what the -HUD element represents. The direction field is the direction in which something -is drawn. +HUD element represents. +The `direction` field is the direction in which something is drawn. `0` draws from left to right, `1` draws from right to left, `2` draws from top to bottom, and `3` draws from bottom to top. @@ -1299,7 +1314,21 @@ factor! The `z_index` field specifies the order of HUD elements from back to front. Lower z-index elements are displayed behind higher z-index elements. Elements with same z-index are displayed in an arbitrary order. Default 0. -Supports negative values. +Supports negative values. By convention, the following values are recommended: + +* -400: Graphical effects, such as vignette +* -300: Name tags, waypoints +* -200: Wieldhand +* -100: Things that block the player's view, e.g. masks +* 0: Default. For standard in-game HUD elements like crosshair, hotbar, + minimap, builtin statbars, etc. +* 100: Temporary text messages or notification icons +* 1000: Full-screen effects such as full-black screen or credits. + This includes effects that cover the entire screen +* Other: If your HUD element doesn't fit into any category, pick a number + between the suggested values + + Below are the specific uses for fields in each type; fields not listed for that type are ignored. @@ -1327,15 +1356,21 @@ Displays text on the HUD. text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. * `alignment`: The alignment of the text. * `offset`: offset in pixels from position. +* `size`: size of the text. + The player-set font size is multiplied by size.x (y value isn't used). ### `statbar` -Displays a horizontal bar made up of half-images. +Displays a horizontal bar made up of half-images with an optional background. -* `text`: The name of the texture that is used. +* `text`: The name of the texture to use. +* `text2`: Optional texture name to enable a background / "off state" + texture (useful to visualize the maximal value). Both textures + must have the same size. * `number`: The number of half-textures that are displayed. If odd, will end with a vertically center-split texture. -* `direction` +* `item`: Same as `number` but for the "off state" texture +* `direction`: To which direction the images will extend to * `offset`: offset in pixels from position. * `size`: If used, will force full-image size to this value (override texture pack image size) @@ -1354,10 +1389,30 @@ Displays distance to selected world position. * `name`: The name of the waypoint. * `text`: Distance suffix. Can be blank. +* `precision`: Waypoint precision, integer >= 0. Defaults to 10. + If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`. + When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point. + `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`). + `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on: + `precision = n` will show multiples of `1/n` * `number:` An integer containing the RGB value of the color used to draw the text. * `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. +* `alignment`: The alignment of the waypoint. +### `image_waypoint` + +Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint. + +* `scale`: The scale of the image, with 1 being the original texture size. + Only the X coordinate scale is used (positive values). + Negative values represent that percentage of the screen it + should take; e.g. `x=-100` means 100% (width). +* `text`: The name of the texture that is displayed. +* `alignment`: The alignment of the image. +* `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. @@ -1611,6 +1666,7 @@ to games. * `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 + or if their feet are in the node. Note: not supported for `new_move = false` * `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)` * `falling_node`: if there is no walkable block under the node it will fall * `float`: the node will not fall through liquids @@ -2071,6 +2127,26 @@ Elements * End of a container, following elements are no longer relative to this container. +### `scroll_container[<X>,<Y>;<W>,<H>;<scrollbar name>;<orientation>;<scroll factor>]` + +* Start of a scroll_container block. All contained elements will ... + * take the scroll_container coordinate as position origin, + * be additionally moved by the current value of the scrollbar with the name + `scrollbar name` times `scroll factor` along the orientation `orientation` and + * be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. +* `orientation`: possible values are `vertical` and `horizontal`. +* `scroll factor`: optional, defaults to `0.1`. +* Nesting is possible. +* Some elements might work a little different if they are in a scroll_container. +* Note: If you want the scroll_container to actually work, you also need to add a + scrollbar element with the specified name. Furthermore, it is highly recommended + to use a scrollbaroptions element on this scrollbar. + +### `scroll_container_end[]` + +* End of a scroll_container, following elements are no longer bound to this + container. + ### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]` * Show an inventory list if it has been sent to the client. Nothing will @@ -2178,12 +2254,12 @@ Elements * 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. + * `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 @@ -2332,8 +2408,8 @@ Elements * `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 +* `transparent` (optional): if true, tabs are semi-transparent +* `draw_border` (optional): if true, draw a thin line at tab base ### `tabheader[<X>,<Y>;<H>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` @@ -2498,16 +2574,28 @@ Elements * `span=<value>`: number of following columns to affect (default: infinite). -### `style[<name 1>,<name 2>,...;<prop1>;<prop2>;...]` +### `style[<selector 1>,<selector 2>;<prop1>;<prop2>;...]` -* Set the style for the named element(s) `name`. +* Set the style for the element(s) matching `selector` by name. +* `selector` can be one of: + * `<name>` - An element name. Includes `*`, which represents every element. + * `<name>:<state>` - An element name, a colon, and one or more states. +* `state` is a list of states separated by the `+` character. + * If a state is provided, the style will only take effect when the element is in that state. + * All provided states must be active for the style to apply. * Note: this **must** be before the element is defined. * See [Styling Formspecs]. -### `style_type[<type 1>,<type 2>,...;<prop1>;<prop2>;...]` +### `style_type[<selector 1>,<selector 2>;<prop1>;<prop2>;...]` -* Sets the style for all elements of type(s) `type` which appear after this element. +* Set the style for the element(s) matching `selector` by type. +* `selector` can be one of: + * `<type>` - An element type. Includes `*`, which represents every element. + * `<type>:<state>` - An element type, a colon, and one or more states. +* `state` is a list of states separated by the `+` character. + * If a state is provided, the style will only take effect when the element is in that state. + * All provided states must be active for the style to apply. * See [Styling Formspecs]. Migrating to Real Coordinates @@ -2550,23 +2638,34 @@ Styling Formspecs Formspec elements can be themed using the style elements: - style[<name 1>,<name 2>,...;<prop1>;<prop2>;...] - style_type[<type 1>,<type 2>,...;<prop1>;<prop2>;...] + style[<name 1>,<name 2>;<prop1>;<prop2>;...] + style[<name 1>:<state>,<name 2>:<state>;<prop1>;<prop2>;...] + style_type[<type 1>,<type 2>;<prop1>;<prop2>;...] + style_type[<type 1>:<state>,<type 2>:<state>;<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] + A name/type can optionally be a comma separated list of names/types, like so: world_delete,world_create,world_configure button,image_button -For example: +A `*` type can be used to select every element in the formspec. - style_type[button;bgcolor=#006699] - style[world_delete;bgcolor=red;textcolor=yellow] - button[4,3.95;2.6,1;world_delete;Delete] +Any name/type in the list can also be accompanied by a `+`-separated list of states, like so: + + world_delete:hovered+pressed + button:pressed + +States allow you to apply styles in response to changes in the element, instead of applying at all times. Setting a property to nothing will reset it to the default value. For example: @@ -2607,14 +2706,22 @@ Some types may inherit styles from parent types. * alpha - boolean, whether to draw alpha in bgimg. Default true. * bgcolor - color, sets button tint. * bgcolor_hovered - color when hovered. Defaults to a lighter bgcolor when not provided. + * This is deprecated, use states instead. * bgcolor_pressed - color when pressed. Defaults to a darker bgcolor when not provided. + * This is deprecated, use states instead. * bgimg - standard background image. Defaults to none. * bgimg_hovered - background image when hovered. Defaults to bgimg when not provided. + * This is deprecated, use states instead. * bgimg_middle - Makes the bgimg textures render in 9-sliced mode and defines the middle rect. - See background9[] documentation for more details + See background9[] documentation for more details. This property also pads the + button's content when set. * bgimg_pressed - background image when pressed. Defaults to bgimg when not provided. + * This is deprecated, use states instead. * border - boolean, draw border. Set to false to hide the bevelled button pane. Default true. + * content_offset - 2d vector, shifts the position of the button's content without resizing it. * noclip - boolean, set to true to allow the element to exceed formspec bounds. + * padding - rect, adds space between the edges of the button and the content. This value is + relative to bgimg_middle. * textcolor - color, default white. * checkbox * noclip - boolean, set to true to allow the element to exceed formspec bounds. @@ -2638,12 +2745,22 @@ Some types may inherit styles from parent types. * image_button (additional properties) * fgimg - standard image. Defaults to none. * fgimg_hovered - image when hovered. Defaults to fgimg when not provided. + * This is deprecated, use states instead. * fgimg_pressed - image when pressed. Defaults to fgimg when not provided. + * This is deprecated, use states instead. * NOTE: The parameters of any given image_button will take precedence over fgimg/fgimg_pressed * tabheader * noclip - boolean, set to true to allow the element to exceed formspec bounds. * textcolor - color. Default white. +### Valid States + +* *all elements* + * default - Equivalent to providing no states +* button, button_exit, image_button, item_image_button + * hovered - Active when the mouse is hovering over the element + * pressed - Active when the button is pressed + Markup Language --------------- @@ -2896,6 +3013,24 @@ For the following functions `x` can be either a vector or a number: * `vector.divide(v, x)`: * Returns a scaled vector or Schur quotient. +For the following functions `a` is an angle in radians and `r` is a rotation +vector ({x = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are +angles in radians. + +* `vector.rotate(v, r)`: + * Applies the rotation `r` to `v` and returns the result. + * `vector.rotate({x = 0, y = 0, z = 1}, r)` and + `vector.rotate({x = 0, y = 1, z = 0}, r)` return vectors pointing + forward and up relative to an entity's rotation `r`. +* `vector.rotate_around_axis(v1, v2, a)`: + * Returns `v1` rotated around axis `v2` by `a` radians according to + the right hand rule. +* `vector.dir_to_rotation(direction[, up])`: + * Returns a rotation vector for `direction` pointing forward using `up` + as the up vector. + * 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. + @@ -3096,8 +3231,22 @@ Strings that need to be translated can contain several escapes, preceded by `@`. `minetest.translate`, but is in translation files. * `@n` acts as a literal newline as well. +Server side translations +------------------------ + +On some specific cases, server translation could be useful. For example, filter +a list on labels and send results to client. A method is supplied to achieve +that: +`minetest.get_translated_string(lang_code, string)`: Translates `string` using +translations for `lang_code` language. It gives the same result as if the string +was translated by the client. +The `lang_code` to use for a given player can be retrieved from +the table returned by `minetest.get_player_information(name)`. + +IMPORTANT: This functionality should only be used for sorting, filtering or similar purposes. +You do not need to use this to get translated strings to show up on the client. Perlin noise ============ @@ -3170,9 +3319,9 @@ For this parameter you can randomly choose any whole number. Usually it is preferable for this to be different from other seeds, but sometimes it is useful to be able to create identical noise patterns. -When used in mapgen this is actually a 'seed offset', it is added to the -'world seed' to create the seed used by the noise, to ensure the noise has a -different pattern in different worlds. +In some noise APIs the world seed is added to the seed specified in noise +parameters. This is done to make the resulting noise pattern vary in different +worlds, and be 'world-specific'. ### `octaves` @@ -4053,6 +4202,8 @@ Utilities area_store_persistent_ids = true, -- Whether minetest.find_path is functional (5.2.0) pathfinder_works = true, + -- Whether Collision info is available to an objects' on_step (5.3.0) + object_step_has_moveresult = true, } * `minetest.has_feature(arg)`: returns `boolean, missing_features` @@ -4064,16 +4215,18 @@ Utilities { address = "127.0.0.1", -- IP address of client ip_version = 4, -- IPv4 / IPv6 + connection_uptime = 200, -- seconds since client connected + protocol_version = 32, -- protocol version used by client + formspec_version = 2, -- supported formspec version + lang_code = "fr" -- Language code used for translation + -- the following keys can be missing if no stats have been collected yet min_rtt = 0.01, -- minimum round trip time max_rtt = 0.2, -- maximum round trip time avg_rtt = 0.02, -- average round trip time min_jitter = 0.01, -- minimum packet time jitter max_jitter = 0.5, -- maximum packet time jitter 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!!! + -- the following information is available in a debug build only!!! -- DO NOT USE IN MODS --ser_vers = 26, -- serialization version used by client --major = 0, -- major version number @@ -4246,7 +4399,7 @@ Call these functions only at load time! * Called after generating a piece of world. Modifying nodes inside the area is a bit faster than usually. * `minetest.register_on_newplayer(function(ObjectRef))` - * Called after a new player has been created + * Called when a new player enters the world for the first time * `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. @@ -4287,19 +4440,23 @@ Call these functions only at load time! * Called _before_ repositioning of player occurs * return true in func to disable regular player placement * `minetest.register_on_prejoinplayer(function(name, ip))` - * Called before a player joins the game - * If it returns a string, the player is disconnected with that string as + * Called when a client connects to the server, prior to authentication + * If it returns a string, the client is disconnected with that string as reason. -* `minetest.register_on_joinplayer(function(ObjectRef))` +* `minetest.register_on_joinplayer(function(ObjectRef, last_login))` * Called when a player joins the game + * `last_login`: The timestamp of the previous login, or nil if player is new * `minetest.register_on_leaveplayer(function(ObjectRef, timed_out))` * Called when a player leaves the game * `timed_out`: True for timeout, false for other reasons. +* `minetest.register_on_authplayer(function(name, ip, is_success))` + * Called when a client attempts to log into an account. + * `name`: The name of the account being authenticated. + * `ip`: The IP address of the client + * `is_success`: Whether the client was successfully authenticated + * For newly registered accounts, `is_success` will always be true * `minetest.register_on_auth_fail(function(name, ip))` - * Called when a client attempts to log into an account but supplies the - wrong password. - * `ip`: The IP address of the client. - * `name`: The account the client attempted to log into. + * Deprecated: use `minetest.register_on_authplayer(name, ip, is_success)` instead. * `minetest.register_on_cheat(function(ObjectRef, cheat))` * Called when a player cheats * `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of: @@ -4362,7 +4519,7 @@ Call these functions only at load time! * The same as before, except that it is called before the player crafts, to make craft prediction, and it should not change anything. * `minetest.register_allow_player_inventory_action(function(player, action, inventory, inventory_info))` - * Determinates how much of a stack may be taken, put or moved to a + * Determines how much of a stack may be taken, put or moved to a player inventory. * `player` (type `ObjectRef`) is the player who modified the inventory `inventory` (type `InvRef`). @@ -4569,8 +4726,11 @@ Environment access * Return value: Table with all node positions with a node air above * Area volume is limited to 4,096,000 nodes * `minetest.get_perlin(noiseparams)` + * Return world-specific perlin noise. + * The actual seed used is the noiseparams seed plus the world seed. * `minetest.get_perlin(seeddiff, octaves, persistence, spread)` - * Return world-specific perlin noise (`int(worldseed)+seeddiff`) + * Deprecated: use `minetest.get_perlin(noiseparams)` instead. + * Return world-specific perlin noise. * `minetest.get_voxel_manip([pos1, pos2])` * Return voxel manipulator object. * Loads the manipulator from the map if positions are passed. @@ -4751,7 +4911,7 @@ Environment access * `minetest.add_node_level(pos, level)` * increase level of leveled node by level, default `level` equals `1` * if `totallevel > maxlevel`, returns rest (`total-max`) - * can be negative for decreasing + * `level` must be between -127 and 127 * `minetest.fix_light(pos1, pos2)`: returns `true`/`false` * resets the light in a cuboid-shaped part of the map and removes lighting bugs. @@ -5063,6 +5223,20 @@ Server * Returns a code (0: successful, 1: no such player, 2: player is connected) * `minetest.remove_player_auth(name)`: remove player authentication data * Returns boolean indicating success (false if player nonexistant) +* `minetest.dynamic_add_media(filepath)` + * Adds the file at the given path to the media sent to clients by the server + on startup and also pushes this file to already connected clients. + The file must be a supported image, sound or model format. It must not be + modified, deleted, moved or renamed after calling this function. + The list of dynamically added media is not persisted. + * Returns boolean indicating success (duplicate files count as error) + * The media will be ready to use (in e.g. entity textures, sound_play) + immediately after calling this function. + Old clients that lack support for this feature will not see the media + unless they reconnect to the server. + * Since media transferred this way does not use client caching or HTTP + transfers, dynamic media should not be used with big files or performance + will suffer. Bans ---- @@ -5318,7 +5492,7 @@ Misc. * Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"` * `minetest.encode_base64(string)`: returns string encoded in base64 * Encodes a string in base64. -* `minetest.decode_base64(string)`: returns string +* `minetest.decode_base64(string)`: returns string or nil for invalid base64 * Decodes a string encoded in base64. * `minetest.is_protected(pos, name)`: returns boolean * Returning `true` restricts the player `name` from modifying (i.e. digging, @@ -5340,6 +5514,13 @@ Misc. * `minetest.record_protection_violation(pos, name)` * This function calls functions registered with `minetest.register_on_protection_violation`. +* `minetest.is_creative_enabled(name)`: returns boolean + * Returning `true` means that Creative Mode is enabled for player `name`. + * `name` will be `""` for non-players or if the player is unknown. + * This function should be overridden by Creative Mode-related mods to + implement a per-player Creative Mode. + * By default, this function returns `true` if the setting + `creative_mode` is `true` and `false` otherwise. * `minetest.is_area_protected(pos1, pos2, player_name, interval)` * Returns the position of the first node that `player_name` may not modify in the specified cuboid between `pos1` and `pos2`. @@ -5403,8 +5584,8 @@ Misc. insecure functions if the calling mod has been listed as trusted in the `secure.trusted_mods` setting or security is disabled, otherwise returns `nil`. - * Only works at init time and must be called from the mod's main scope (not - from a function). + * Only works at init time and must be called from the mod's main scope + (ie: the init.lua of the mod, not from another Lua file or within a function). * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN A LOCAL VARIABLE!** @@ -5897,15 +6078,18 @@ object you are working with still exists. * max: bubbles bar is not shown * See [Object properties] for more information * Is limited to range 0 ... 65535 (2^16 - 1) -* `set_fov(fov, is_multiplier)`: Sets player's FOV +* `set_fov(fov, is_multiplier, transition_time)`: 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. + * `transition_time`: If defined, enables smooth FOV transition. + Interpreted as the time (in seconds) to reach target FOV. + If set to 0, FOV change is instantaneous. Defaults to 0. + * Set `fov` to 0 to clear FOV override. +* `get_fov()`: Returns the following: + * Server-sent FOV value. Returns 0 if an FOV override doesn't exist. + * Boolean indicating whether the FOV value is a multiplier. + * Time (in seconds) taken for the FOV transition. Set by `set_fov`. * `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 @@ -5928,13 +6112,14 @@ object you are working with still exists. * `get_formspec_prepend(formspec)`: returns a formspec string. * `get_player_control()`: returns table with player pressed keys * The table consists of fields with boolean value representing the pressed - keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up. + keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up, zoom. * example: `{jump=false, right=true, left=false, LMB=false, RMB=false, - sneak=true, aux1=false, down=false, up=false}` + sneak=true, aux1=false, down=false, up=false, zoom=false}` + * The `zoom` field is available since 5.3 * `get_player_control_bits()`: returns integer with bit packed player pressed keys. * bit nr/meaning: 0/up, 1/down, 2/left, 3/right, 4/jump, 5/aux1, 6/sneak, - 7/LMB, 8/RMB + 7/LMB, 8/RMB, 9/zoom (zoom available since 5.3) * `set_physics_override(override_table)` * `override_table` is a table with the following fields: * `speed`: multiplier to default walking speed value (default: `1`) @@ -5992,7 +6177,7 @@ object you are working with still exists. * `sky_color`: A table containing the following values, alpha is ignored: * `day_sky`: ColorSpec, for the top half of the `"regular"` sky during the day. (default: `#8cbafa`) - * `day_horizon`: ColorSpec, for the bottom half of the + * `day_horizon`: ColorSpec, for the bottom half of the `"regular"` sky during the day. (default: `#9bc1f0`) * `dawn_sky`: ColorSpec, for the top half of the `"regular"` sky during dawn/sunset. (default: `#b4bafa`) @@ -6010,7 +6195,7 @@ object you are working with still exists. sky during the night. (default: `#4090ff`) The resulting sky color will be a dark version of the ColorSpec. Warning: The darkening of the ColorSpec is subject to change. - * `indoors`: ColorSpec, for when you're either indoors or + * `indoors`: ColorSpec, for when you're either indoors or underground. Only applies to the `"regular"` sky. (default: `#646464`) * `fog_sun_tint`: ColorSpec, changes the fog tinting for the sun @@ -6054,7 +6239,7 @@ object you are working with still exists. * `parameters` is a table with the following optional fields: * `visible`: Boolean for whether the stars are visible. (default: `true`) - * `count`: Integer number to set the number of stars in + * `count`: Integer number to set the number of stars in the skybox. Only applies to `"skybox"` and `"regular"` sky types. (default: `1000`) * `star_color`: ColorSpec, sets the colors of the stars, @@ -6127,10 +6312,15 @@ It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`. ------------- A perlin noise generator. -It can be created via `PerlinNoise(seed, octaves, persistence, spread)` -or `PerlinNoise(noiseparams)`. -Alternatively with `minetest.get_perlin(seeddiff, octaves, persistence, spread)` -or `minetest.get_perlin(noiseparams)`. +It can be created via `PerlinNoise()` or `minetest.get_perlin()`. +For `minetest.get_perlin()`, the actual seed used is the noiseparams seed +plus the world seed, to create world-specific noise. + +`PerlinNoise(noiseparams)` +`PerlinNoise(seed, octaves, persistence, spread)` (Deprecated). + +`minetest.get_perlin(noiseparams)` +`minetest.get_perlin(seeddiff, octaves, persistence, spread)` (Deprecated). ### Methods @@ -6144,6 +6334,8 @@ A fast, bulk perlin noise generator. It can be created via `PerlinNoiseMap(noiseparams, size)` or `minetest.get_perlin_map(noiseparams, size)`. +For `minetest.get_perlin_map()`, the actual seed used is the noiseparams seed +plus the world seed, to create world-specific noise. Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise @@ -6416,6 +6608,7 @@ Player properties need to be saved manually. automatic_rotate = 0, -- Set constant rotation in radians per second, positive or negative. + -- Object rotates along the local Y-axis, and works with set_rotation. -- Set to 0 to disable constant rotation. stepheight = 0, @@ -6454,6 +6647,12 @@ Player properties need to be saved manually. -- deleted when the block gets unloaded. -- The get_staticdata() callback is never called then. -- Defaults to 'true'. + + damage_texture_modifier = "^[brighten", + -- Texture modifier to be applied for a short duration when object is hit + + shaded = true, + -- Setting this to 'false' disables diffuse lighting of entity } Entity definition @@ -6474,7 +6673,10 @@ Used by `minetest.register_entity`. on_activate = function(self, staticdata, dtime_s), - on_step = function(self, dtime), + on_step = function(self, dtime, moveresult), + -- Called every server step + -- dtime: Elapsed time + -- moveresult: Table with collision info (only available if physical=true) on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir), @@ -6489,6 +6691,25 @@ Used by `minetest.register_entity`. -- for more info) by using a '_' prefix } +Collision info passed to `on_step`: + + { + touching_ground = boolean, + collides = boolean, + standing_on_object = boolean, + collisions = { + { + type = string, -- "node" or "object", + axis = string, -- "x", "y" or "z" + node_pos = vector, -- if type is "node" + object = ObjectRef, -- if type is "object" + old_velocity = vector, + new_velocity = vector, + }, + ... + } + } + ABM (ActiveBlockModifier) definition ------------------------------------ @@ -6655,6 +6876,8 @@ Used by `minetest.register_node`, `minetest.register_craftitem`, and wield_scale = {x = 1, y = 1, z = 1}, + -- The default value of 99 may be configured by + -- users using the setting "default_stack_max" stack_max = 99, range = 4.0, @@ -6760,7 +6983,7 @@ Used by `minetest.register_node`. visual_scale = 1.0, -- Supported for drawtypes "plantlike", "signlike", "torchlike", - -- "firelike", "mesh". + -- "firelike", "mesh", "nodebox", "allfaces". -- For plantlike and firelike, the image will start at the bottom of the -- node. For torchlike, the image will start at the surface to which the -- node "attaches". For the other drawtypes the image will be centered @@ -6843,11 +7066,15 @@ Used by `minetest.register_node`. -- If true, a new liquid source can be created by placing two or more -- sources nearby - leveled = 16, + leveled = 0, -- Only valid for "nodebox" drawtype with 'type = "leveled"'. -- Allows defining the nodebox height without using param2. -- The nodebox height is 'leveled' / 64 nodes. - -- The maximum value of 'leveled' is 127. + -- The maximum value of 'leveled' is `leveled_max`. + + leveled_max = 127, + -- Maximum value for `leveled` (0-127), enforced in + -- `minetest.set_node_level` and `minetest.add_node_level`. liquid_range = 8, -- Number of flowing nodes around source (max. 8) @@ -7020,6 +7247,7 @@ Used by `minetest.register_node`. -- node is deleted from the world or the drops are added. This is -- generally the result of either the node being dug or an attached node -- becoming detached. + -- oldmeta is the NodeMetaRef of the oldnode before deletion. -- drops is a table of ItemStacks, so any metadata to be preserved can -- be added directly to one or more of the dropped items. See -- "ItemStackMetaRef". @@ -7044,10 +7272,14 @@ Used by `minetest.register_node`. on_punch = function(pos, node, puncher, pointed_thing), -- default: minetest.node_punch + -- Called when puncher (an ObjectRef) punches the node at pos. -- By default calls minetest.register_on_punchnode callbacks. on_rightclick = function(pos, node, clicker, itemstack, pointed_thing), -- default: nil + -- Called when clicker (an ObjectRef) "rightclicks" + -- ("rightclick" here stands for the placement key) while pointing at + -- the node at pos with 'node' being the node table. -- itemstack will hold clicker's wielded item. -- Shall return the leftover itemstack. -- Note: pointed_thing can be nil, if a mod calls this function. @@ -7265,6 +7497,10 @@ Biome definition Used by `minetest.register_biome`. +The maximum number of biomes that can be used is 65535. However, using an +excessive number of biomes will slow down map generation. Depending on desired +performance and computing power the practical limit is much lower. + { name = "tundra", @@ -7612,6 +7848,8 @@ Used by `Player:hud_add`. Returned by `Player:hud_get`. text = "<text>", + text2 = "<text>", + number = 2, item = 3, @@ -7647,6 +7885,8 @@ Used by `minetest.add_particle`. size = 1, -- Scales the visual size of the particle texture. + -- If `node` is set, size can be set to 0 to spawn a randomly-sized + -- particle (just like actual node dig particles). collisiondetection = false, -- If true collides with `walkable` nodes and, depending on the @@ -7665,6 +7905,7 @@ Used by `minetest.add_particle`. -- If true faces player using y axis only texture = "image.png", + -- The texture of the particle playername = "singleplayer", -- Optional, if specified spawns particle only on the player's client @@ -7675,6 +7916,17 @@ Used by `minetest.add_particle`. glow = 0 -- Optional, specify particle self-luminescence in darkness. -- Values 0-14. + + node = {name = "ignore", param2 = 0}, + -- Optional, if specified the particle will have the same appearance as + -- node dig particles for the given node. + -- `texture` and `animation` will be ignored if this is set. + + node_tile = 0, + -- Optional, only valid in combination with `node` + -- If set to a valid number 1-6, specifies the tile from which the + -- particle texture is picked. + -- Otherwise, the default behavior is used. (currently: any random tile) } @@ -7704,7 +7956,9 @@ Used by `minetest.add_particlespawner`. maxsize = 1, -- The particles' properties are random values between the min and max -- values. - -- pos, velocity, acceleration, expirationtime, size + -- applies to: pos, velocity, acceleration, expirationtime, size + -- If `node` is set, min and maxsize can be set to 0 to spawn + -- randomly-sized particles (just like actual node dig particles). collisiondetection = false, -- If true collide with `walkable` nodes and, depending on the @@ -7727,6 +7981,7 @@ Used by `minetest.add_particlespawner`. -- If true face player using y axis only texture = "image.png", + -- The texture of the particle playername = "singleplayer", -- Optional, if specified spawns particles only on the player's client @@ -7737,6 +7992,17 @@ Used by `minetest.add_particlespawner`. glow = 0 -- Optional, specify particle self-luminescence in darkness. -- Values 0-14. + + node = {name = "ignore", param2 = 0}, + -- Optional, if specified the particles will have the same appearance as + -- node dig particles for the given node. + -- `texture` and `animation` will be ignored if this is set. + + node_tile = 0, + -- Optional, only valid in combination with `node` + -- If set to a valid number 1-6, specifies the tile from which the + -- particle texture is picked. + -- Otherwise, the default behavior is used. (currently: any random tile) } `HTTPRequest` definition diff --git a/doc/menu_lua_api.txt b/doc/menu_lua_api.txt index 4861ed0d9..724e37855 100644 --- a/doc/menu_lua_api.txt +++ b/doc/menu_lua_api.txt @@ -1,36 +1,55 @@ -Minetest Lua Mainmenu API Reference 5.2.0 +Minetest Lua Mainmenu API Reference 5.3.0 ========================================= Introduction ------------- + The main menu is defined as a formspec by Lua in builtin/mainmenu/ Description of formspec language to show your menu is in lua_api.txt + Callbacks --------- -core.buttonhandler(fields): called when a button is pressed. + +core.button_handler(fields): called when a button is pressed. ^ fields = {name1 = value1, name2 = value2, ...} core.event_handler(event) ^ event: "MenuQuit", "KeyEnter", "ExitButton" or "EditBoxEnter" + Gamedata -------- + The "gamedata" table is read when calling core.start(). It should contain: { - playername = <name>, - password = <password>, - address = <IP/adress>, - port = <port>, - selected_world = <index>, -- 0 for client mode - singleplayer = <true/false>, + playername = <name>, + password = <password>, + address = <IP/adress>, + port = <port>, + selected_world = <index>, -- 0 for client mode + singleplayer = <true/false>, } + Functions --------- + core.start() core.close() +core.get_min_supp_proto() +^ returns the minimum supported network protocol version +core.get_max_supp_proto() +^ returns the maximum supported network protocol version +core.open_url(url) +^ opens the URL in a web browser, returns false on failure. +^ Must begin with http:// or https:// +core.get_version() (possible in async calls) +^ returns current core version + + +Filesystem +---------- -Filesystem: core.get_builtin_path() ^ returns path to builtin root core.create_dir(absolute_path) (possible in async calls) @@ -48,12 +67,6 @@ core.extract_zip(zipfile,destination) [unzip within path required] ^ zipfile to extract ^ destination folder to extract to ^ returns true/false -core.download_file(url,target) (possible in async calls) -^ url to download -^ target to store to -^ returns true/false -core.get_version() (possible in async calls) -^ returns current core version core.sound_play(spec, looped) -> handle ^ spec = SimpleSoundSpec (see lua-api.txt) ^ looped = bool @@ -67,7 +80,82 @@ core.get_mapgen_names([include_hidden=false]) -> table of map generator algorith registered in the core (possible in async calls) core.get_cache_path() -> path of cache -Formspec: + +HTTP Requests +------------- + +* core.download_file(url, target) (possible in async calls) + * url to download, and target to store to + * returns true/false +* `minetest.get_http_api()` (possible in async calls) + * returns `HTTPApiTable` containing http functions. + * The returned table contains the functions `fetch_sync`, `fetch_async` and + `fetch_async_get` described below. + * Function only exists if minetest server was built with cURL support. +* `HTTPApiTable.fetch_sync(HTTPRequest req)`: returns HTTPRequestResult + * Performs given request synchronously +* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle + * Performs given request asynchronously and returns handle for + `HTTPApiTable.fetch_async_get` +* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult + * Return response data for given asynchronous HTTP request + +### `HTTPRequest` definition + +Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`. + + { + url = "http://example.org", + + timeout = 10, + -- Timeout for connection in seconds. Default is 3 seconds. + + post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"}, + -- Optional, if specified a POST request with post_data is performed. + -- Accepts both a string and a table. If a table is specified, encodes + -- table as x-www-form-urlencoded key-value pairs. + -- If post_data is not specified, a GET request is performed instead. + + user_agent = "ExampleUserAgent", + -- Optional, if specified replaces the default minetest user agent with + -- given string + + extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" }, + -- Optional, if specified adds additional headers to the HTTP request. + -- You must make sure that the header strings follow HTTP specification + -- ("Key: Value"). + + multipart = boolean + -- Optional, if true performs a multipart HTTP request. + -- Default is false. + } + +### `HTTPRequestResult` definition + +Passed to `HTTPApiTable.fetch` callback. Returned by +`HTTPApiTable.fetch_async_get`. + + { + completed = true, + -- If true, the request has finished (either succeeded, failed or timed + -- out) + + succeeded = true, + -- If true, the request was successful + + timeout = false, + -- If true, the request timed out + + code = 200, + -- HTTP status code + + data = "response" + } + + +Formspec +-------- + core.update_formspec(formspec) core.get_table_index(tablename) -> index ^ can also handle textlists @@ -82,7 +170,10 @@ core.explode_textlist_event(string) -> table core.set_formspec_prepend(formspec) ^ string to be added to every mainmenu formspec, to be used for theming. -GUI: + +GUI +--- + core.set_background(type, texturepath,[tile],[minsize]) ^ type: "background", "overlay", "header" or "footer" ^ tile: tile the image instead of scaling (background only) @@ -102,83 +193,96 @@ core.show_path_select_dialog(formname, caption, is_file_select) ^ returns nil or selected file/folder core.get_screen_info() ^ returns { - density = <screen density 0.75,1.0,2.0,3.0 ... (dpi)>, - display_width = <width of display>, - display_height = <height of display>, - window_width = <current window width>, - window_height = <current window height> - } + density = <screen density 0.75,1.0,2.0,3.0 ... (dpi)>, + display_width = <width of display>, + display_height = <height of display>, + window_width = <current window width>, + window_height = <current window height> + } + -### Content and Packages +Content and Packages +-------------------- Content - an installed mod, modpack, game, or texture pack (txt) Package - content which is downloadable from the content db, may or may not be installed. * core.get_modpath() (possible in async calls) - * returns path to global modpath + * returns path to global modpath * core.get_clientmodpath() (possible in async calls) - * returns path to global client-side modpath + * returns path to global client-side modpath * core.get_gamepath() (possible in async calls) - * returns path to global gamepath + * returns path to global gamepath * core.get_texturepath() (possible in async calls) - * returns path to default textures + * returns path to default textures * core.get_game(index) - * returns: - - { - id = <id>, - path = <full path to game>, - gamemods_path = <path>, - name = <name of game>, - menuicon_path = <full path to menuicon>, - author = "author", - DEPRECATED: - addon_mods_paths = {[1] = <path>,}, - } + * returns: + + { + id = <id>, + path = <full path to game>, + gamemods_path = <path>, + name = <name of game>, + menuicon_path = <full path to menuicon>, + author = "author", + DEPRECATED: + addon_mods_paths = {[1] = <path>,}, + } * core.get_games() -> table of all games in upper format (possible in async calls) * core.get_content_info(path) - * returns + * returns + + { + name = "name of content", + type = "mod" or "modpack" or "game" or "txp", + description = "description", + author = "author", + path = "path/to/content", + depends = {"mod", "names"}, -- mods only + optional_depends = {"mod", "names"}, -- mods only + } - { - name = "name of content", - type = "mod" or "modpack" or "game" or "txp", - description = "description", - author = "author", - path = "path/to/content", - depends = {"mod", "names"}, -- mods only - optional_depends = {"mod", "names"}, -- mods only - } +Favorites +--------- -Favorites: core.get_favorites(location) -> list of favorites (possible in async calls) ^ location: "local" or "online" ^ returns { - [1] = { - clients = <number of clients/nil>, - clients_max = <maximum number of clients/nil>, - version = <server version/nil>, - password = <true/nil>, - creative = <true/nil>, - damage = <true/nil>, - pvp = <true/nil>, - description = <server description/nil>, - name = <server name/nil>, - address = <address of server/nil>, - port = <port> - }, + [1] = { + clients = <number of clients/nil>, + clients_max = <maximum number of clients/nil>, + version = <server version/nil>, + password = <true/nil>, + creative = <true/nil>, + damage = <true/nil>, + pvp = <true/nil>, + description = <server description/nil>, + name = <server name/nil>, + address = <address of server/nil>, + port = <port> + clients_list = <array of clients/nil> + mods = <array of mods/nil> + }, + ... } core.delete_favorite(id, location) -> success -Logging: + +Logging +------- + core.debug(line) (possible in async calls) ^ Always printed to stderr and logfile (print() is redirected here) core.log(line) (possible in async calls) core.log(loglevel, line) (possible in async calls) ^ loglevel one of "error", "action", "info", "verbose" -Settings: + +Settings +-------- + core.settings:set(name, value) core.settings:get(name) -> string or nil (possible in async calls) core.settings:set_bool(name, value) @@ -188,19 +292,25 @@ core.settings:save() -> nil, save all settings to config file For a complete list of methods of the Settings object see [lua_api.txt](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt) -Worlds: + +Worlds +------ + core.get_worlds() -> list of worlds (possible in async calls) ^ returns { - [1] = { - path = <full path to world>, - name = <name of world>, - gameid = <gameid of world>, - }, + [1] = { + path = <full path to world>, + name = <name of world>, + gameid = <gameid of world>, + }, } core.create_world(worldname, gameid) core.delete_world(index) -Helpers: + +Helpers +------- + core.get_us_time() ^ returns time with microsecond precision core.gettext(string) -> string @@ -225,13 +335,10 @@ minetest.encode_base64(string) (possible in async calls) minetest.decode_base64(string) (possible in async calls) ^ Decodes a string encoded in base64. -Version compat: -core.get_min_supp_proto() -^ returns the minimum supported network protocol version -core.get_max_supp_proto() -^ returns the maximum supported network protocol version -Async: +Async +----- + core.handle_async(async_job,parameters,finished) ^ execute a function asynchronously ^ async_job is a function receiving one parameter and returning one parameter @@ -242,11 +349,13 @@ core.handle_async(async_job,parameters,finished) 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.show_path_select_dialog + e.g. No access to functions modifying menu like core.start,core.close, + core.show_path_select_dialog + Background music ---------------- + The main menu supports background music. It looks for a `main_menu` sound in `$USER_PATH/sounds`. The same naming conventions as for normal sounds apply. diff --git a/doc/minetest.6 b/doc/minetest.6 index cb5ed57ef..bac70fe1a 100644 --- a/doc/minetest.6 +++ b/doc/minetest.6 @@ -105,12 +105,12 @@ Migrate from current map backend to another. Possible values are sqlite3, leveldb, redis, postgresql, and dummy. .TP .B \-\-migrate-auth <value> -Migrate from current auth backend to another. Possible values are sqlite3 and -files. +Migrate from current auth backend to another. Possible values are sqlite3, +leveldb, and files. .TP .B \-\-migrate-players <value> Migrate from current players backend to another. Possible values are sqlite3, -postgresql, dummy, and files. +leveldb, postgresql, dummy, and files. .TP .B \-\-terminal Display an interactive terminal over ncurses during execution. diff --git a/doc/mkdocs/lua_highlight.patch b/doc/mkdocs/lua_highlight.patch index 034a63a33..e231081d6 100644 --- a/doc/mkdocs/lua_highlight.patch +++ b/doc/mkdocs/lua_highlight.patch @@ -1,4 +1,4 @@ -@@ -77,7 +77,7 @@ +@@ -75,7 +75,7 @@ css_class="codehilite", lang=None, style='default', noclasses=False, tab_length=4, hl_lines=None, use_pygments=True): self.src = src @@ -7,13 +7,3 @@ 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/texture_packs.txt b/doc/texture_packs.txt index 7ab0aca94..94151f1a4 100644 --- a/doc/texture_packs.txt +++ b/doc/texture_packs.txt @@ -64,6 +64,8 @@ by texture packs. All existing fallback textures can be found in the directory * `bubble.png`: the bubble texture when the player is drowning (default size: 12×12) +* `bubble_gone.png`: like `bubble.png`, but denotes lack of breath + (transparent by default, same size as bubble.png) * `crack_anylength.png`: node overlay texture when digging @@ -76,6 +78,8 @@ by texture packs. All existing fallback textures can be found in the directory * `heart.png`: used to display the health points of the player (default size: 12×12) +* `heart_gone.png`: like `heart.png`, but denotes lack of health points + (transparent by default, same size as heart.png) * `minimap_mask_round.png`: round minimap mask, white gets replaced by the map * `minimap_mask_square.png`: mask used for the square minimap @@ -145,34 +149,51 @@ are placeholders intended to be overwritten by the game. Texture Overrides ----------------- -You can override the textures of a node from a texture pack using -texture overrides. To do this, create a file in a texture pack -called override.txt +You can override the textures of nodes and items from a +texture pack using texture overrides. To do this, create one or +more files in a texture pack called override.txt Each line in an override.txt file is a rule. It consists of - nodename face-selector texture + itemname target texture For example, default:dirt_with_grass sides default_stone.png -You can use ^ operators as usual: +or + + default:sword_steel inventory my_steel_sword.png + +You can list multiple targets on one line as a comma-separated list: + + default:tree top,bottom my_special_tree.png + +You can use texture modifiers, as usual: default:dirt_with_grass sides default_stone.png^[brighten -Here are face selectors you can choose from: +Finally, if a line is empty or starts with '#' it will be considered +a comment and not read as a rule. You can use this to better organize +your override.txt files. + +Here are targets you can choose from: -| face-selector | behavior | +| target | behavior | |---------------|---------------------------------------------------| -| left | x- | -| right | x+ | -| front | z- | -| back | z+ | -| top | y+ | -| bottom | y- | -| sides | x-, x+, z-, z+ | +| left | x- face | +| right | x+ face | +| front | z- face | +| back | z+ face | +| top | y+ face | +| bottom | y- face | +| sides | x-, x+, z-, z+ faces | | all | All faces. You can also use '*' instead of 'all'. | +| inventory | The inventory texture | +| wield | The texture used when held by the player | + +Nodes support all targets, but other items only support 'inventory' +and 'wield' Designing leaves textures for the leaves rendering options ---------------------------------------------------------- |