diff options
| -rw-r--r-- | doc/lua_api.txt | 129 |
1 files changed, 76 insertions, 53 deletions
diff --git a/doc/lua_api.txt b/doc/lua_api.txt index 30f4d87df..ea47d0044 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -65,15 +65,19 @@ e.g. The game directory can contain the file minetest.conf, which will be used to set default settings when running the particular game. It can also contain a settingtypes.txt in the same format as the one in builtin. -This settingtypes.txt will be parsed by the menu and the settings will be displayed in the "Games" category in the settings tab. +This settingtypes.txt will be parsed by the menu and the settings will be displayed +in the "Games" category in the settings tab. ### Menu images -Games can provide custom main menu images. They are put inside a `menu` directory inside the game directory. +Games can provide custom main menu images. They are put inside a `menu` directory +inside the game directory. -The images are named `$identifier.png`, where `$identifier` is one of `overlay,background,footer,header`. -If you want to specify multiple images for one identifier, add additional images named like `$identifier.$n.png`, with an ascending number $n starting with 1, -and a random image will be chosen from the provided ones. +The images are named `$identifier.png`, where `$identifier` is +one of `overlay,background,footer,header`. +If you want to specify multiple images for one identifier, add additional images named +like `$identifier.$n.png`, with an ascending number $n starting with 1, and a random +image will be chosen from the provided ones. Mod load path @@ -243,7 +247,8 @@ Example: default_dirt.png^default_grass_side.png `default_grass_side.png` is overlayed over `default_dirt.png`. -The texture with the lower resolution will be automatically upscaled to the higher resolution texture. +The texture with the lower resolution will be automatically upscaled to +the higher resolution texture. ### Texture grouping Textures can be grouped together by enclosing them in `(` and `)`. @@ -468,8 +473,8 @@ the global `minetest.registered_*` tables. * added to `minetest.registered_schematic` with the key of `schematic.name` * if `schematic.name` is nil, the key is the returned ID * if the schematic is loaded from a file, schematic.name is set to the filename - * if the function is called when loading the mod, and schematic.name is a relative path, - * then the current mod path will be prepended to the schematic filename + * if the function is called when loading the mod, and schematic.name is a relative + path, then the current mod path will be prepended to the schematic filename * `minetest.clear_registered_biomes()` * clears all biomes currently registered @@ -1416,13 +1421,13 @@ examples. #### `listring[<inventory location>;<list name>]` * Allows to create a ring of inventory lists * Shift-clicking on items in one element of the ring -* will send them to the next inventory list inside the ring + will send them to the next inventory list inside the ring * The first occurrence of an element inside the ring will -* determine the inventory where items will be sent to + determine the inventory where items will be sent to #### `listring[]` * Shorthand for doing `listring[<inventory location>;<list name>]` -* for the last two inventory lists added by list[...] + for the last two inventory lists added by list[...] #### `listcolors[<slot_bg_normal>;<slot_bg_hover>]` * Sets background color of slots as `ColorString` @@ -1475,7 +1480,7 @@ examples. * Textual password style field; will be sent to server when a button is clicked * `x` and `y` position the field relative to the top left of the menu * `w` and `h` are the size of the field -* fields are a set height, but will be vertically centred on `h` +* Fields are a set height, but will be vertically centred on `h` * Position and size units are inventory slots * `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 @@ -1484,7 +1489,7 @@ examples. * Textual field; will be sent to server when a button is clicked * `x` and `y` position the field relative to the top left of the menu * `w` and `h` are the size of the field -* fields are a set height, but will be vertically centred on `h` +* Fields are a set height, but will be vertically centred on `h` * Position and size units are inventory slots * `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 @@ -1494,13 +1499,13 @@ examples. * **Note**: no extra text or more than a single variable is supported ATM. #### `field[<name>;<label>;<default>]` -* as above, but without position/size units -* special field for creating simple forms, such as sign text input -* must be used without a `size[]` element -* a "Proceed" button will be added automatically +* As above, but without position/size units +* Special field for creating simple forms, such as sign text input +* Must be used without a `size[]` element +* A "Proceed" button will be added automatically #### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]` -* same as fields above, but with multi-line input +* Same as fields above, but with multi-line input #### `label[<X>,<Y>;<label>]` * `x` and `y` work as per field @@ -1561,12 +1566,12 @@ examples. * `name` fieldname sent to server on doubleclick value is current selected element * `listelements` can be prepended by #RRGGBB (only) in hexadecimal format * if you want a listelement to start with "#" write "##" -* index to be selected within textlist +* Index to be selected within textlist * `true`/`false`: draw transparent background -* see also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`) +* See also `minetest.explode_textlist_event` (main menu: `engine.explode_textlist_event`) #### `tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]` -* show a tab**header** at specific position (ignores formsize) +* Show a tab**header** at specific position (ignores formsize) * `x` and `y` position the itemlist relative to the top left of the menu * `name` fieldname data is transferred to Lua * `caption 1`...: name shown on top of tab @@ -1575,24 +1580,24 @@ examples. * `draw_border` (optional): draw border #### `box[<X>,<Y>;<W>,<H>;<color>]` -* simple colored semitransparent box +* Simple colored semitransparent box * `x` and `y` position the box relative to the top left of the menu * `w` and `h` are the size of box * `color` is color specified as a `ColorString` #### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]` -* show a dropdown field +* Show a dropdown field * **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 -* fieldname data is transferred to Lua -* items to be shown in dropdown -* index of currently selected dropdown item +* Width of dropdown +* Fieldname data is transferred to Lua +* Items to be shown in dropdown +* Index of currently selected dropdown item #### `checkbox[<X>,<Y>;<name>;<label>;<selected>;<tooltip>]` -* show a checkbox +* Show a checkbox * `x` and `y`: position of checkbox * `name` fieldname data is transferred to Lua * `label` to be shown left of checkbox @@ -1600,29 +1605,29 @@ examples. * `tooltip` (optional) #### `scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]` -* show a scrollbar -* there are two ways to use it: +* Show a scrollbar +* There are two ways to use it: 1. handle the changed event (only changed scrollbar is available) 2. read the value on pressing a button (all scrollbars are available) * `x` and `y`: position of trackbar * `w` and `h`: width and height * `orientation`: `vertical`/`horizontal` -* fieldname data is transferred to Lua -* value this trackbar is set to (`0`-`1000`) -* see also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`) +* Fieldname data is transferred to Lua +* Value this trackbar is set to (`0`-`1000`) +* See also `minetest.explode_scrollbar_event` (main menu: `engine.explode_scrollbar_event`) #### `table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]` -* show scrollable table using options defined by the previous `tableoptions[]` -* displays cells as defined by the previous `tablecolumns[]` +* Show scrollable table using options defined by the previous `tableoptions[]` +* Displays cells as defined by the previous `tablecolumns[]` * `x` and `y`: position the itemlist relative to the top left of the menu * `w` and `h` are the size of the itemlist * `name`: fieldname sent to server on row select or doubleclick * `cell 1`...`cell n`: cell contents given in row-major order * `selected idx`: index of row to be selected within table (first row = `1`) -* see also `minetest.explode_table_event` (main menu: `engine.explode_table_event`) +* See also `minetest.explode_table_event` (main menu: `engine.explode_table_event`) #### `tableoptions[<opt 1>;<opt 2>;...]` -* sets options for `table[]` +* Sets options for `table[]` * `color=#RRGGBB` * default text color (`ColorString`), defaults to `#FFFFFF` * `background=#RRGGBB` @@ -1638,14 +1643,14 @@ examples. * only useful when there is a column of type "tree" #### `tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]` -* sets columns for `table[]` -* types: `text`, `image`, `color`, `indent`, `tree` +* Sets columns for `table[]` +* Types: `text`, `image`, `color`, `indent`, `tree` * `text`: show cell contents as text * `image`: cell contents are an image index, use column options to define images * `color`: cell contents are a ColorString and define color of following cell * `indent`: cell contents are a number and define indentation of following cell * `tree`: same as indent, but user can open and close subtrees (treeview-like) -* column options: +* Column options: * `align=<value>` * for `text` and `image`: content alignment within cells. Available values: `left` (default), `center`, `right`, `inline` @@ -1948,7 +1953,8 @@ Call these functions only at load time! * `minetest.register_chatcommand(cmd, chatcommand definition)` * `minetest.register_privilege(name, definition)` * `definition`: `"description text"` - * `definition`: `{ description = "description text", give_to_singleplayer = boolean, -- default: true }` + * `definition`: `{ description = "description text", give_to_singleplayer = boolean}` + the default of `give_to_singleplayer` is true * To allow players with basic_privs to grant, see basic_privs minetest.conf setting. * `minetest.register_authentication_handler(handler)` * See `minetest.builtin_auth_handler` in `builtin.lua` for reference @@ -2669,7 +2675,8 @@ This is basically a reference to a C++ `ServerActiveObject` ##### 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 +* `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 * `get_look_dir()`: get camera direction as a unit vector * `get_look_pitch()`: pitch in radians * `get_look_yaw()`: yaw in radians (wraps around pretty randomly as of now) @@ -2783,25 +2790,40 @@ An `InvRef` is a reference to an inventory. 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)`. -If you chose the parameter-less constructor, a fast implementation will be automatically chosen for you. +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. -* `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. -* `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. -* `reserve(count)`: reserves resources for at most `count` many contained areas. Only needed for efficiency, and only some implementations profit. +* `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. +* `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. +* `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. +* `reserve(count)`: reserves resources for at most `count` many contained areas. + Only needed for efficiency, and only some implementations profit. * `remove_area(id)`: removes the area with the given id from the store, returns success. -* `set_cache_params(params)`: sets params for the included prefiltering cache. Calling invalidates the cache, so that its elements have to be newly generated. +* `set_cache_params(params)`: sets params for the included prefiltering cache. + Calling invalidates the cache, so that its elements have to be newly generated. * `params`: { enabled = boolean, -- whether to enable, default true - block_radius = number, -- the radius (in nodes) of the areas the cache generates prefiltered lists for, minimum 16, default 64 + block_radius = number, -- the radius (in nodes) of the areas the cache generates + prefiltered lists for, minimum 16, default 64 limit = number, -- the cache's size, minimum 20, default 1000 } * `to_string()`: Experimental. Returns area store serialized as a (binary) string. * `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to a file. -* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore. Returns success and, optionally, an error message. +* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore. + Returns success and, optionally, an error message. * `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file. ### `ItemStack` @@ -3517,7 +3539,8 @@ Definition tables liquid_alternative_flowing = "", -- Flowing version of source liquid liquid_alternative_source = "", -- Source version of flowing liquid liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7) - liquid_renewable = true, -- Can new liquid source be created by placing two or more sources nearby? + liquid_renewable = true, --[[ + ^ If true, a new liquid source can be created by placing two or more sources nearby ]] leveled = 0, --[[ ^ Block contains level in param2. Value is default level, used for snow. ^ Don't forget to use "leveled" type nodebox. ]] @@ -3724,7 +3747,7 @@ Definition tables ### Biome definition (`register_biome`) **Note** -The biome API is still in an experimental phase and subject to change. +The Biome API is still in an experimental phase and subject to change. { name = "tundra", |