Skip to content

Commit

Permalink
Lua_api.txt: Split long lines. Capitalise 'Biome API'. Minor edits
Browse files Browse the repository at this point in the history
  • Loading branch information
paramat committed Jun 7, 2016
1 parent d4457ef commit c7297e5
Showing 1 changed file with 76 additions and 53 deletions.
129 changes: 76 additions & 53 deletions doc/lua_api.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 `)`.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -1575,54 +1580,54 @@ 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
* `selected` (optional): `true`/`false`
* `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`
Expand All @@ -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`
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -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. ]]
Expand Down Expand Up @@ -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",
Expand Down

0 comments on commit c7297e5

Please sign in to comment.