-Minetest Lua Modding API Reference 0.4.13
+Minetest Lua Modding API Reference 0.4.14
=========================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
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
is missing, that does not prevent this mod from being loaded.
### `screenshot.png`
-A screenshot shown in modmanager within mainmenu.
+A screenshot shown in the mod manager within the main menu. It should
+have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
### `description.txt`
A File containing description to be shown within mainmenu.
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.
### Texture grouping
Textures can be grouped together by enclosing them in `(` and `)`.
[combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
+#### `[resize:<w>x<h>`
+Resizes the texture to the given dimensions.
+
+Example:
+
+ default_sandstone.png^[resize:16x16
+
#### `[brighten`
Brightens the texture.
#### `[colorize:<color>:<ratio>`
Colorize the textures with the given color.
`<color>` is specified as a `ColorString`.
-`<ratio>` is an int ranging from 0 to 255, and specifies how much of the
-color to apply. If ommitted, the alpha will be used.
+`<ratio>` is an int ranging from 0 to 255 or the word "`alpha`". If
+it is an int, then it specifies how far to interpolate between the
+colors where 0 is only the texture color and 255 is only `<color>`. If
+omitted, the alpha of `<color>` will be used as the ratio. If it is
+the word "`alpha`", then each texture pixel will contain the RGB of
+`<color>` and the alpha of `<color>` multiplied by the alpha of the
+texture pixel.
Sounds
------
* 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
^ The rotation of the node is stored in param2. Furnaces and chests are
rotated this way. Can be made by using minetest.dir_to_facedir().
Values range 0 - 23
- facedir modulo 4 = axisdir
+ facedir / 4 = axis direction:
0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y-
- facedir's two less significant bits are rotation around the axis
+ facedir modulo 4 = rotation around that axis
paramtype2 == "leveled"
paramtype2 == "degrotate"
^ The rotation of this node is stored in param2. Plants are rotated this way.
wall_bottom = box,
wall_side = box
}
+ {
+ -- A node that has optional boxes depending on neighbouring nodes'
+ -- presence and type. See also `connects_to`.
+ type = "connected",
+ fixed = box OR {box1, box2, ...}
+ connect_top = box OR {box1, box2, ...}
+ connect_bottom = box OR {box1, box2, ...}
+ connect_front = box OR {box1, box2, ...}
+ connect_left = box OR {box1, box2, ...}
+ connect_back = box OR {box1, box2, ...}
+ connect_right = box OR {box1, box2, ...}
+ }
A `box` is defined as:
* `number`: Number of items in the inventory to be displayed.
* `item`: Position of item that is selected.
* `direction`
+* `offset`: offset in pixels from position.
### `waypoint`
Displays distance to selected world position.
#### `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`
* 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
* 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
* **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
* `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
* `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
+#### `checkbox[<X>,<Y>;<name>;<label>;<selected>]`
+* 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`
* 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`
or string form, a ColorString (defined above):
`colorspec = "green"`
-Spatial Vectors
---------------
-
-* `vector.new([x[, y, z]])`: returns a vector.
- * `x` is a table or the `x` position.
+Escape sequences
+----------------
+Most text can contain escape sequences, that can for example color the text.
+There are a few exceptions: tab headers, dropdowns and vertical labels can't.
+The following functions provide escape sequences:
+* `core.get_color_escape_sequence(color)`:
+ * `color` is a ColorString
+ * The escape sequence sets the text color to `color`
+* `core.colorize(color, message)`:
+ * Equivalent to:
+ `core.get_color_escape_sequence(color) ..
+ message ..
+ core.get_color_escape_sequence("#ffffff")`
+* `color.get_background_escape_sequence(color)`
+ * `color` is a ColorString
+ * The escape sequence sets the background of the whole text element to
+ `color`. Only defined for item descriptions and tooltips.
+Spatial Vectors
+---------------
+* `vector.new(a[, b, c])`: returns a vector:
+ * A copy of `a` if `a` is a vector.
+ * `{x = a, y = b, z = c}`, if all `a, b, c` are defined
* `vector.direction(p1, p2)`: returns a vector
* `vector.distance(p1, p2)`: returns a number
* `vector.length(v)`: returns a number
* `vector.normalize(v)`: returns a vector
-* `vector.round(v)`: returns a vector
+* `vector.round(v)`: returns a vector, each dimension rounded to floor
* `vector.apply(v, func)`: returns a vector
* `vector.equals(v1, v2)`: returns a boolean
* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
Helper functions
------------------
+----------------
* `dump2(obj, name="_", dumped={})`
* Return object serialized as a string, handles reference loops
* `dump(obj, dumped={})`
* `minetest.register_entity(name, prototype table)`
* `minetest.register_abm(abm definition)`
+* `minetest.register_lbm(lbm definition)`
* `minetest.register_node(name, node definition)`
* `minetest.register_tool(name, item definition)`
* `minetest.register_craftitem(name, item definition)`
* `minetest.register_alias(name, convert_to)`
* `minetest.register_craft(recipe)`
+ * Check recipe table syntax for different types below.
+* `minetest.clear_craft(recipe)`
+ * Will erase existing craft based either on output item or on input recipe.
+ * Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table
+ syntax as for `minetest.register_craft(recipe)`. For output specify only the item, without a quantity.
+ * If no erase candidate could be found, Lua exception will be thrown.
+ * Warning! The type field ("shaped","cooking" or any other) will be ignored if the recipe
+ contains output. Erasing is then done independently from the crafting method.
* `minetest.register_ore(ore definition)`
* `minetest.register_decoration(decoration definition)`
* `minetest.override_item(name, redefinition)`
* `modifier`: when true, the function should return the actual hp_change.
Note: modifiers only get a temporary hp_change that can be modified by later modifiers.
modifiers can return true as a second argument to stop the execution of further functions.
+ Non-modifiers receive the final hp change calculated by the modifiers.
* `minetest.register_on_respawnplayer(func(ObjectRef))`
* Called when player is to be respawned
* Called _before_ repositioning of player occurs
* If it returns a string, the player is disconnected with that string as reason
* `minetest.register_on_joinplayer(func(ObjectRef))`
* Called when a player joins the game
-* `minetest.register_on_leaveplayer(func(ObjectRef))`
+* `minetest.register_on_leaveplayer(func(ObjectRef, timed_out))`
* Called when a player leaves the game
+ * `timed_out`: True for timeout, false for other reasons.
* `minetest.register_on_cheat(func(ObjectRef, cheat))`
* Called when a player cheats
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
* `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
* `minetest.notify_authentication_modified(name)`
* Should be called by the authentication handler if privileges changes.
* To report everybody, set `name=nil`.
+* `minetest.check_password_entry(name, entry, password)`
+ * Returns true if the "db entry" for a player with name matches given
+ * password, false otherwise.
+ * The "db entry" is the usually player-individual value that is derived
+ * from the player's chosen password and stored on the server in order to allow
+ * authentication whenever the player desires to log in.
+ * Only use this function for making it possible to log in via the password from
+ * via protocols like IRC, other uses for inside the game are frowned upon.
* `minetest.get_password_hash(name, raw_password)`
* Convert a name-password pair to a password hash that Minetest can use.
* The returned value alone is not a good basis for password checks based
* on comparing the password hash in the database with the password hash
* from the function, with an externally provided password, as the hash
* in the db might use the new SRP verifier format.
+ * For this purpose, use minetest.check_password_entry instead.
* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
* Convert between two privilege representations
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
* `minetest.get_timeofday()`
* `minetest.get_gametime()`: returns the time, in seconds, since the world was created
+* `minetest.get_day_count()`: returns number days elapsed since world was created,
+ * accounting for time changes.
* `minetest.find_node_near(pos, radius, nodenames)`: returns pos or `nil`
* `radius`: using a maximum metric
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
given biome_name string.
* `minetest.get_mapgen_params()` Returns mapgen parameters, a table containing
`mgname`, `seed`, `chunksize`, `water_level`, and `flags`.
+ * Deprecated: use minetest.get_mapgen_setting(name) instead
* `minetest.set_mapgen_params(MapgenParams)`
+ * Deprecated: use minetest.set_mapgen_setting(name, value, override) instead
* Set map generation parameters
* Function cannot be called after the registration period; only initialization
and `on_mapgen_init`
* `flags` contains a comma-delimited string of flags to set,
or if the prefix `"no"` is attached, clears instead.
* `flags` is in the same format and has the same options as `mg_flags` in `minetest.conf`
+* `minetest.get_mapgen_setting(name)`
+ * Gets the *active* mapgen setting (or nil if none exists) in string format with the following
+ order of precedence:
+ 1) Settings loaded from map_meta.txt or overrides set during mod execution
+ 2) Settings set by mods without a metafile override
+ 3) Settings explicitly set in the user config file, minetest.conf
+ 4) Settings set as the user config default
+* `minetest.get_mapgen_setting_noiseparams(name)`
+ * Same as above, but returns the value as a NoiseParams table if the setting `name` exists
+ and is a valid NoiseParams
+* `minetest.set_mapgen_setting(name, value, [override_meta=false])`
+ * Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting
+ is not already present in map_meta.txt. If the optional boolean override_meta is set to true,
+ this setting will become the active setting regardless of the map metafile contents.
+ * Note: to set the seed, use "seed", not "fixed_map_seed"
+* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta=false])`
+ * Same as above, except value is a NoiseParams table
* `minetest.set_noiseparams(name, noiseparams, set_default)`
* Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`.
* `set_default` is an optional boolean (default: `true`) that specifies whether the setting
* `max_drop`: maximum height difference to consider droppable
* `algorithm`: One of `"A*_noprefetch"` (default), `"A*"`, `"Dijkstra"`
* `minetest.spawn_tree (pos, {treedef})`
- * spawns L-System tree at given `pos` with definition in `treedef` table
+ * spawns L-system tree at given `pos` with definition in `treedef` table
+ * Warning: L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
+ Often these bugs appear as subtle shadows in water.
* `minetest.transforming_liquid_add(pos)`
* add node to liquid update queue
* `minetest.get_node_max_level(pos)`
otherwise returns `nil`.
* The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get`
described below.
- * Only works at init time.
+ * Only works at init time and must be called from the mod's main scope (not from a function).
* Function only exists if minetest server was built with cURL support.
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
A LOCAL VARIABLE!**
* callback: `function(HTTPRequestResult res)`
* Use this HTTP function if you are unsure, the others are for advanced use.
* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
- * Performs given request asynchronously and returns handle for `minetest.http_fetch_async_get`
+ * 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
* See documentation on `minetest.compress()` for supported compression methods.
* currently supported.
* `...` indicates method-specific arguments. Currently, no methods use this.
+* `minetest.encode_base64(string)`: returns string encoded in base64
+ * Encodes a string in base64.
+* `minetest.decode_base64(string)`: returns string
+ * Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
* Returns true, if player `name` shouldn't be abled to dig at `pos` or do other
actions, defineable by mods, due to some mod-defined ownership-like concept.
* `get_inventory()`: returns `InvRef`
* `to_table()`: returns `nil` or `{fields = {...}, inventory = {list1 = {}, ...}}`
* `from_table(nil or {})`
+ * to clear metadata, use from_table(nil)
* See "Node Metadata"
### `NodeTimerRef`
##### 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)
-* `set_look_pitch(radians)`: sets look pitch
-* `set_look_yaw(radians)`: sets look yaw
+* `get_look_vertical()`: pitch in radians
+ * Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.
+* `get_look_horizontal()`: yaw in radians
+ * Angle is counter-clockwise from the +z direction.
+* `set_look_vertical(radians)`: sets look pitch
+ * radians - Angle from looking forward, where positive is downwards.
+* `set_look_horizontal(radians)`: sets look yaw
+ * radians - Angle from the +z direction, where positive is counter-clockwise.
+* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use get_look_vertical.
+ * Angle ranges between -pi/2 and pi/2, which are straight down and up respectively.
+* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use get_look_horizontal.
+ * Angle is counter-clockwise from the +x direction.
+* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use set_look_vertical.
+* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use set_look_horizontal.
* `get_breath()`: returns players breath
* `set_breath(value)`: sets players breath
* values:
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)`: inserts an area into the store. Returns the id if successful, nil otherwise. The (inclusive) positions `edge1` and `edge2` describe the area, `data`
-is a string stored with the area.
-* `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_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file.
### `ItemStack`
An `ItemStack` is a stack of items.
* `next()`: return next integer random number [`-2147483648`...`2147483647`]
* `next(min, max)`: return next integer random number [`min`...`max`]
* `rand_normal_dist(min, max, num_trials=6)`: return normally distributed random number [`min`...`max`]
- * This is only a rough approximation of a normal distribution with mean=(max-min)/2 and variance=1
+ * This is only a rough approximation of a normal distribution with:
+ * mean = (max - min) / 2, and
+ * variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)
* Increasing num_trials improves accuracy of the approximation
### `SecureRandom`
L-system trees
--------------
+**Warning**
+L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
+Often these bugs appear as subtle shadows in water.
### Tree definition
### ABM (ActiveBlockModifier) definition (`register_abm`)
{
+ label = "Lava cooling",
+ -- ^ Descriptive label for profiling purposes (optional).
+ -- Definitions with identical labels will be listed as one.
-- In the following two fields, also group:groupname will work.
nodenames = {"default:lava_source"},
neighbors = {"default:water_source", "default:water_flowing"}, -- Any of these --[[
action = func(pos, node, active_object_count, active_object_count_wider),
}
+### LBM (LoadingBlockModifier) definition (`register_lbm`)
+
+ {
+ label = "Upgrade legacy doors",
+ -- ^ Descriptive label for profiling purposes (optional).
+ -- Definitions with identical labels will be listed as one.
+ name = "modname:replace_legacy_door",
+ nodenames = {"default:lava_source"},
+ -- ^ List of node names to trigger the LBM on.
+ -- Also non-registered nodes will work.
+ -- Groups (as of group:groupname) will work as well.
+ run_at_every_load = false,
+ -- ^ Whether to run the LBM's action every time a block gets loaded,
+ -- and not just for blocks that were saved last time before LBMs were
+ -- introduced to the world.
+ action = func(pos, node),
+ }
+
### Item definition (`register_node`, `register_craftitem`, `register_tool`)
{
^ paramtype = "light" allows light to propagate from or through the node with light value
^ falling by 1 per node. This line is essential for a light source node to spread its light. ]]
paramtype2 = "none", -- See "Nodes"
+ place_param2 = nil, -- Force value for param2 when player places node
is_ground_content = true, -- If false, the cave generator will not carve through this
sunlight_propagates = false, -- If true, sunlight will go infinitely through this
walkable = true, -- If true, objects collide with node
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. ]]
light_source = 0, -- Amount of light emitted by node
damage_per_second = 0, -- If player is inside node, this damage is caused
node_box = {type="regular"}, -- See "Node boxes"
+ connects_to = nodenames, --[[
+ * Used for nodebox nodes with the type == "connected"
+ * Specifies to what neighboring nodes connections will be drawn
+ * e.g. `{"group:fence", "default:wood"}` or `"default:stone"` ]]
+ connect_sides = { "top", "bottom", "front", "left", "back", "right" }, --[[
+ ^ Tells connected nodebox nodes to connect only to these sides of this node. ]]
mesh = "model",
selection_box = {type="regular"}, -- See "Node boxes" --[[
^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
max_items = 1, -- Maximum number of items to drop.
items = { -- Choose max_items randomly from this list.
{
- items = {"foo:bar", "baz:frob"}, -- Choose one item randomly from this list.
- rarity = 1, -- Probability of getting is 1 / rarity.
+ items = {"foo:bar", "baz:frob"}, -- Items to drop.
+ rarity = 1, -- Probability of dropping is 1 / rarity.
},
},
},
### Biome definition (`register_biome`)
+**Note**
+The Biome API is still in an experimental phase and subject to change.
+
{
name = "tundra",
node_dust = "default:snow",
-- ^ Node that replaces all seawater nodes not in the defined surface layer.
node_river_water = "default:ice",
-- ^ Node that replaces river water in mapgens that use default:river_water.
+ node_riverbed = "default:gravel",
+ depth_riverbed = 2,
+ -- ^ Node placed under river water and thickness of this layer.
y_min = 1,
y_max = 31000,
-- ^ Lower and upper limits for biome.
-- ^ Minimum and maximum `y` positions these decorations can be generated at.
-- ^ This parameter refers to the `y` position of the decoration base, so
-- the actual maximum height would be `height_max + size.Y`.
- flags = "liquid_surface",
+ flags = "liquid_surface, force_placement",
-- ^ Flags for all decoration types.
-- ^ "liquid_surface": Instead of placement on the highest solid surface
-- ^ in a mapchunk column, placement is on the highest liquid surface.
-- ^ Placement is disabled if solid nodes are found above the liquid surface.
+ -- ^ "force_placement": Nodes other than "air" and "ignore" are replaced by the decoration.
----- Simple-type parameters
decoration = "default:grass",
},
-- ^ See 'Schematic specifier' for details.
replacements = {["oldname"] = "convert_to", ...},
- flags = "place_center_x, place_center_y, place_center_z, force_placement",
+ flags = "place_center_x, place_center_y, place_center_z",
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
rotation = "90" -- rotate schematic 90 degrees on placement
-- ^ Rotation can be "0", "90", "180", "270", or "random".
size = 1,
collisiondetection = false,
-- ^ collisiondetection: if true collides with physical objects
+ collision_removal = false,
+ -- ^ collision_removal: if true then particle is removed when it collides,
+ -- ^ requires collisiondetection = true to have any effect
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
collisiondetection = false,
-- ^ collisiondetection: if true uses collision detection
+ collision_removal = false,
+ -- ^ collision_removal: if true then particle is removed when it collides,
+ -- ^ requires collisiondetection = true to have any effect
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ Playername is optional, if specified spawns particle only on the player's client
}
-### `HTTPRequest` definition (`http_fetch`, `http_fetch_async`)
+### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`)
{
url = "http://example.org",
-- ^ Optional, if true performs a multipart HTTP request. Default is false.
}
-### `HTTPRequestResult` definition (`http_fetch` callback, `http_fetch_async_get`)
+### `HTTPRequestResult` definition (`HTTPApiTable.fetch` callback, `HTTPApiTable.fetch_async_get`)
{
completed = true,
projects / dragonfireclient.git / blobdiff