zmv7
/
MultiCraft
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Lua_api.txt: Split long lines part 4

master
paramat 2018-03-14 04:12:18 +00:00 committed by paramat
parent 92ca9dda54
commit 06f67646d8
1 changed files with 277 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

462
doc/lua_api.txt
View File

@ -3448,86 +3448,103 @@ These functions return the leftover itemstack.
### Schematics ### Schematics
* `minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)` * `minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)`
* Create a schematic from the volume of map specified by the box formed by p1 and p2. * Create a schematic from the volume of map specified by the box formed by
* Apply the specified probability and per-node force-place to the specified nodes p1 and p2.
according to the `probability_list`. * Apply the specified probability and per-node force-place to the specified
* `probability_list` is an array of tables containing two fields, `pos` and `prob`. nodes according to the `probability_list`.
* `probability_list` is an array of tables containing two fields, `pos`
and `prob`.
* `pos` is the 3D vector specifying the absolute coordinates of the * `pos` is the 3D vector specifying the absolute coordinates of the
node being modified, node being modified,
* `prob` is an integer value from `0` to `255` that encodes probability and * `prob` is an integer value from `0` to `255` that encodes
per-node force-place. Probability has levels 0-127, then 128 is added to probability and per-node force-place. Probability has levels
encode per-node force-place. 0-127, then 128 may be added to encode per-node force-place.
For probability stated as 0-255, divide by 2 and round down to get values For probability stated as 0-255, divide by 2 and round down to
0-127, then add 128 to apply per-node force-place. get values 0-127, then add 128 to apply per-node force-place.
* If there are two or more entries with the same pos value, the * If there are two or more entries with the same pos value, the
last entry is used. last entry is used.
* If `pos` is not inside the box formed by `p1` and `p2`, it is ignored. * If `pos` is not inside the box formed by `p1` and `p2`, it is
ignored.
* If `probability_list` equals `nil`, no probabilities are applied. * If `probability_list` equals `nil`, no probabilities are applied.
* Apply the specified probability to the specified horizontal slices according to the * Apply the specified probability to the specified horizontal slices
`slice_prob_list`. according to the `slice_prob_list`.
* `slice_prob_list` is an array of tables containing two fields, `ypos` and `prob`. * `slice_prob_list` is an array of tables containing two fields, `ypos`
* `ypos` indicates the y position of the slice with a probability applied, and `prob`.
the lowest slice being `ypos = 0`. * `ypos` indicates the y position of the slice with a probability
* If slice probability list equals `nil`, no slice probabilities are applied. applied, the lowest slice being `ypos = 0`.
* If slice probability list equals `nil`, no slice probabilities
are applied.
* Saves schematic in the Minetest Schematic format to filename. * Saves schematic in the Minetest Schematic format to filename.
* `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement, flags)` * `minetest.place_schematic(pos, schematic, rotation, replacements, force_placement, flags)`
* Place the schematic specified by schematic (see: Schematic specifier) at `pos`. * Place the schematic specified by schematic (see: Schematic specifier) at
`pos`.
* `rotation` can equal `"0"`, `"90"`, `"180"`, `"270"`, or `"random"`. * `rotation` can equal `"0"`, `"90"`, `"180"`, `"270"`, or `"random"`.
* If the `rotation` parameter is omitted, the schematic is not rotated. * If the `rotation` parameter is omitted, the schematic is not rotated.
* `replacements` = `{["old_name"] = "convert_to", ...}` * `replacements` = `{["old_name"] = "convert_to", ...}`
* `force_placement` is a boolean indicating whether nodes other than `air` and * `force_placement` is a boolean indicating whether nodes other than `air`
`ignore` are replaced by the schematic and `ignore` are replaced by the schematic.
* Returns nil if the schematic could not be loaded. * Returns nil if the schematic could not be loaded.
* **Warning**: Once you have loaded a schematic from a file, it will be cached. Future calls * **Warning**: Once you have loaded a schematic from a file, it will be
will always use the cached version and the replacement list defined for it, cached. Future calls will always use the cached version and the
regardless of whether the file or the replacement list parameter have changed. replacement list defined for it, regardless of whether the file or the
The only way to load the file anew is to restart the server. replacement list parameter have changed. The only way to load the file
anew is to restart the server.
* `flags` is a flag field with the available flags: * `flags` is a flag field with the available flags:
* place_center_x * place_center_x
* place_center_y * place_center_y
* place_center_z * place_center_z
* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement, flags)`: * `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement, flags)`:
* This function is analogous to minetest.place_schematic, but places a schematic onto the * This function is analogous to minetest.place_schematic, but places a
specified VoxelManip object `vmanip` instead of the whole map. schematic onto the specified VoxelManip object `vmanip` instead of the
* Returns false if any part of the schematic was cut-off due to the VoxelManip not map.
containing the full area required, and true if the whole schematic was able to fit. * Returns false if any part of the schematic was cut-off due to the
VoxelManip not containing the full area required, and true if the whole
schematic was able to fit.
* Returns nil if the schematic could not be loaded. * Returns nil if the schematic could not be loaded.
* After execution, any external copies of the VoxelManip contents are invalidated. * After execution, any external copies of the VoxelManip contents are
invalidated.
* `flags` is a flag field with the available flags: * `flags` is a flag field with the available flags:
* place_center_x * place_center_x
* place_center_y * place_center_y
* place_center_z * place_center_z
* `minetest.serialize_schematic(schematic, format, options)` * `minetest.serialize_schematic(schematic, format, options)`
* Return the serialized schematic specified by schematic (see: Schematic specifier) * Return the serialized schematic specified by schematic
(see: Schematic specifier)
* in the `format` of either "mts" or "lua". * in the `format` of either "mts" or "lua".
* "mts" - a string containing the binary MTS data used in the MTS file format * "mts" - a string containing the binary MTS data used in the MTS file
* "lua" - a string containing Lua code representing the schematic in table format format.
* "lua" - a string containing Lua code representing the schematic in table
format.
* `options` is a table containing the following optional parameters: * `options` is a table containing the following optional parameters:
* If `lua_use_comments` is true and `format` is "lua", the Lua code generated will have (X, Z) * If `lua_use_comments` is true and `format` is "lua", the Lua code
* position comments for every X row generated in the schematic data for easier reading. generated will have (X, Z) position comments for every X row
* If `lua_num_indent_spaces` is a nonzero number and `format` is "lua", the Lua code generated generated in the schematic data for easier reading.
* will use that number of spaces as indentation instead of a tab character. * If `lua_num_indent_spaces` is a nonzero number and `format` is "lua",
the Lua code generated will use that number of spaces as indentation
instead of a tab character.
### HTTP Requests: ### HTTP Requests:
* `minetest.request_http_api()`: * `minetest.request_http_api()`:
* returns `HTTPApiTable` containing http functions if the calling mod has been granted * returns `HTTPApiTable` containing http functions if the calling mod has
access by being listed in the `secure.http_mods` or `secure.trusted_mods` setting, been granted access by being listed in the `secure.http_mods` or
otherwise returns `nil`. `secure.trusted_mods` setting, otherwise returns `nil`.
* The returned table contains the functions `fetch`, `fetch_async` and `fetch_async_get` * The returned table contains the functions `fetch`, `fetch_async` and
described below. `fetch_async_get` described below.
* 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
(not from a function).
* Function only exists if minetest server was built with cURL support. * 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 * **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
A LOCAL VARIABLE!** A LOCAL VARIABLE!**
* `HTTPApiTable.fetch(HTTPRequest req, callback)` * `HTTPApiTable.fetch(HTTPRequest req, callback)`
* Performs given request asynchronously and calls callback upon completion * Performs given request asynchronously and calls callback upon completion
* callback: `function(HTTPRequestResult res)` * callback: `function(HTTPRequestResult res)`
* Use this HTTP function if you are unsure, the others are for advanced use. * Use this HTTP function if you are unsure, the others are for advanced use
* `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle * `HTTPApiTable.fetch_async(HTTPRequest req)`: returns handle
* Performs given request asynchronously and returns handle for `HTTPApiTable.fetch_async_get` * Performs given request asynchronously and returns handle for
`HTTPApiTable.fetch_async_get`
* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult * `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
* Return response data for given asynchronous HTTP request * Return response data for given asynchronous HTTP request
@ -3539,7 +3556,8 @@ These functions return the leftover itemstack.
### Misc. ### Misc.
* `minetest.get_connected_players()`: returns list of `ObjectRefs` * `minetest.get_connected_players()`: returns list of `ObjectRefs`
* `minetest.is_player(o)`: boolean, whether `o` is a player * `minetest.is_player(o)`: boolean, whether `o` is a player
* `minetest.player_exists(name)`: boolean, whether player exists (regardless of online status) * `minetest.player_exists(name)`: boolean, whether player exists
(regardless of online status)
* `minetest.hud_replace_builtin(name, hud_definition)` * `minetest.hud_replace_builtin(name, hud_definition)`
* Replaces definition of a builtin hud element * Replaces definition of a builtin hud element
* `name`: `"breath"` or `"health"` * `name`: `"breath"` or `"health"`
@ -3559,8 +3577,8 @@ These functions return the leftover itemstack.
* Deprecated: An alias for the former. * Deprecated: An alias for the former.
* `minetest.raillike_group(name)`: returns a rating * `minetest.raillike_group(name)`: returns a rating
* Returns rating of the connect_to_raillike group corresponding to name * Returns rating of the connect_to_raillike group corresponding to name
* If name is not yet the name of a connect_to_raillike group, a new group id * If name is not yet the name of a connect_to_raillike group, a new group
* is created, with that name id is created, with that name.
* `minetest.get_content_id(name)`: returns an integer * `minetest.get_content_id(name)`: returns an integer
* Gets the internal content ID of `name` * Gets the internal content ID of `name`
* `minetest.get_name_from_content_id(content_id)`: returns a string * `minetest.get_name_from_content_id(content_id)`: returns a string
@ -3571,15 +3589,20 @@ These functions return the leftover itemstack.
* On success returns a table, a string, a number, a boolean or `nullvalue` * On success returns a table, a string, a number, a boolean or `nullvalue`
* On failure outputs an error message and returns `nil` * On failure outputs an error message and returns `nil`
* Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}` * Example: `parse_json("[10, {\"a\":false}]")`, returns `{10, {a = false}}`
* `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message * `minetest.write_json(data[, styled])`: returns a string or `nil` and an error
message.
* Convert a Lua table into a JSON string * Convert a Lua table into a JSON string
* styled: Outputs in a human-readable format if this is set, defaults to false * styled: Outputs in a human-readable format if this is set, defaults to
false.
* Unserializable things like functions and userdata will cause an error. * Unserializable things like functions and userdata will cause an error.
* **Warning**: JSON is more strict than the Lua table format. * **Warning**: JSON is more strict than the Lua table format.
1. You can only use strings and positive integers of at least one as keys. 1. You can only use strings and positive integers of at least one as
keys.
2. You can not mix string and integer keys. 2. You can not mix string and integer keys.
This is due to the fact that JSON has two distinct array and object values. This is due to the fact that JSON has two distinct array and object
* Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"` values.
* Example: `write_json({10, {a = false}})`,
returns `"[10, {\"a\": false}]"`
* `minetest.serialize(table)`: returns a string * `minetest.serialize(table)`: returns a string
* Convert a table containing tables, strings, numbers, booleans and `nil`s * Convert a table containing tables, strings, numbers, booleans and `nil`s
into string form readable by `minetest.deserialize` into string form readable by `minetest.deserialize`
@ -3588,21 +3611,24 @@ These functions return the leftover itemstack.
* Convert a string returned by `minetest.deserialize` into a table * Convert a string returned by `minetest.deserialize` into a table
* `string` is loaded in an empty sandbox environment. * `string` is loaded in an empty sandbox environment.
* Will load functions, but they cannot access the global environment. * Will load functions, but they cannot access the global environment.
* Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}` * Example: `deserialize('return { ["foo"] = "bar" }')`,
* Example: `deserialize('print("foo")')`, returns `nil` (function call fails) returns `{foo='bar'}`
* `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)` * Example: `deserialize('print("foo")')`, returns `nil`
(function call fails), returns
`error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
* `minetest.compress(data, method, ...)`: returns `compressed_data` * `minetest.compress(data, method, ...)`: returns `compressed_data`
* Compress a string of data. * Compress a string of data.
* `method` is a string identifying the compression method to be used. * `method` is a string identifying the compression method to be used.
* Supported compression methods: * Supported compression methods:
* Deflate (zlib): `"deflate"` * Deflate (zlib): `"deflate"`
* `...` indicates method-specific arguments. Currently defined arguments are: * `...` indicates method-specific arguments. Currently defined arguments
are:
* Deflate: `level` - Compression level, `0`-`9` or `nil`. * Deflate: `level` - Compression level, `0`-`9` or `nil`.
* `minetest.decompress(compressed_data, method, ...)`: returns data * `minetest.decompress(compressed_data, method, ...)`: returns data
* Decompress a string of data (using ZLib). * Decompress a string of data (using ZLib).
* See documentation on `minetest.compress()` for supported compression methods. * See documentation on `minetest.compress()` for supported compression
* currently supported. methods.
* `...` indicates method-specific arguments. Currently, no methods use this. * `...` indicates method-specific arguments. Currently, no methods use this
* `minetest.rgba(red, green, blue[, alpha])`: returns a string * `minetest.rgba(red, green, blue[, alpha])`: returns a string
* Each argument is a 8 Bit unsigned integer * Each argument is a 8 Bit unsigned integer
* Returns the ColorString from rgb or rgba values * Returns the ColorString from rgb or rgba values
@ -3612,14 +3638,15 @@ These functions return the leftover itemstack.
* `minetest.decode_base64(string)`: returns string * `minetest.decode_base64(string)`: returns string
* Decodes a string encoded in base64. * Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean * `minetest.is_protected(pos, name)`: returns boolean
* Returns true, if player `name` shouldn't be able to dig at `pos` or do other * Returns true, if player `name` shouldn't be able to dig at `pos` or do
actions, definable by mods, due to some mod-defined ownership-like concept. other actions, definable by mods, due to some mod-defined ownership-like
Returns false or nil, if the player is allowed to do such actions. concept.
* Returns false or nil, if the player is allowed to do such actions.
* `name` will be "" for non-players or unknown players. * `name` will be "" for non-players or unknown players.
* This function should be overridden by protection mods and should be used to * This function should be overridden by protection mods and should be used
check if a player can interact at a position. to check if a player can interact at a position.
* This function should call the old version of itself if the position is not * This function should call the old version of itself if the position is
protected by the mod. not protected by the mod.
* Example: * Example:
local old_is_protected = minetest.is_protected local old_is_protected = minetest.is_protected
@ -3633,8 +3660,8 @@ These functions return the leftover itemstack.
* This function calls functions registered with * This function calls functions registered with
`minetest.register_on_protection_violation`. `minetest.register_on_protection_violation`.
* `minetest.is_area_protected(pos1, pos2, player_name, interval) * `minetest.is_area_protected(pos1, pos2, player_name, interval)
* Returns the position of the first node that `player_name` may not modify in * Returns the position of the first node that `player_name` may not modify
the specified cuboid between `pos1` and `pos2`. in the specified cuboid between `pos1` and `pos2`.
* Returns `false` if no protections were found. * Returns `false` if no protections were found.
* Applies `is_protected()` to a 3D lattice of points in the defined volume. * Applies `is_protected()` to a 3D lattice of points in the defined volume.
The points are spaced evenly throughout the volume and have a spacing The points are spaced evenly throughout the volume and have a spacing
@ -3643,27 +3670,29 @@ These functions return the leftover itemstack.
* `interval` defaults to 4. * `interval` defaults to 4.
* `interval` should be carefully chosen and maximised to avoid an excessive * `interval` should be carefully chosen and maximised to avoid an excessive
number of points being checked. number of points being checked.
* Like `minetest.is_protected`, this function may be extended or overwritten by * Like `minetest.is_protected`, this function may be extended or
mods to provide a faster implementation to check the cuboid for intersections. overwritten by mods to provide a faster implementation to check the
cuboid for intersections.
* `minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)` * `minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)`
* Attempt to predict the desired orientation of the facedir-capable node * Attempt to predict the desired orientation of the facedir-capable node
defined by `itemstack`, and place it accordingly (on-wall, on the floor, or defined by `itemstack`, and place it accordingly (on-wall, on the floor,
hanging from the ceiling). Stacks are handled normally if the `infinitestacks` or hanging from the ceiling). Stacks are handled normally if the
field is false or omitted (else, the itemstack is not changed). `orient_flags` `infinitestacks` field is false or omitted (else, the itemstack is not
is an optional table containing extra tweaks to the placement code: changed). `orient_flags` is an optional table containing extra tweaks to
* `invert_wall`: if `true`, place wall-orientation on the ground and ground- the placement code:
orientation on the wall. * `invert_wall`: if `true`, place wall-orientation on the ground and
ground-orientation on the wall.
* `force_wall` : if `true`, always place the node in wall orientation. * `force_wall` : if `true`, always place the node in wall orientation.
* `force_ceiling`: if `true`, always place on the ceiling. * `force_ceiling`: if `true`, always place on the ceiling.
* `force_floor`: if `true`, always place the node on the floor. * `force_floor`: if `true`, always place the node on the floor.
* `force_facedir`: if `true`, forcefully reset the facedir to north when placing on * `force_facedir`: if `true`, forcefully reset the facedir to north
the floor or ceiling when placing on the floor or ceiling.
* The first four options are mutually-exclusive; the last in the list takes * The first four options are mutually-exclusive; the last in the list
precedence over the first. takes precedence over the first.
* `minetest.rotate_node(itemstack, placer, pointed_thing)` * `minetest.rotate_node(itemstack, placer, pointed_thing)`
* calls `rotate_and_place()` with infinitestacks set according to the state of * calls `rotate_and_place()` with infinitestacks set according to the state
the creative mode setting, and checks for "sneak" to set the `invert_wall` of the creative mode setting, and checks for "sneak" to set the
parameter. `invert_wall` parameter.
* `minetest.forceload_block(pos[, transient])` * `minetest.forceload_block(pos[, transient])`
* forceloads the position `pos`. * forceloads the position `pos`.
@ -3679,10 +3708,12 @@ These functions return the leftover itemstack.
* `minetest.request_insecure_environment()`: returns an environment containing * `minetest.request_insecure_environment()`: returns an environment containing
insecure functions if the calling mod has been listed as trusted in the insecure functions if the calling mod has been listed as trusted in the
`secure.trusted_mods` setting or security is disabled, otherwise returns `nil`. `secure.trusted_mods` setting or security is disabled, otherwise returns
* Only works at init time and must be called from the mod's main scope (not from a function). `nil`.
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN * Only works at init time and must be called from the mod's main scope (not
A LOCAL VARIABLE!** from a function).
* **DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE
IT IN A LOCAL VARIABLE!**
* `minetest.global_exists(name)` * `minetest.global_exists(name)`
* Checks if a global variable has been set, without triggering a warning. * Checks if a global variable has been set, without triggering a warning.
@ -3728,10 +3759,12 @@ An interface to use mod channels on client and server
#### Methods #### Methods
* `leave()`: leave the mod channel. * `leave()`: leave the mod channel.
* Server leaves channel `channel_name`. * Server leaves channel `channel_name`.
* No more incoming or outgoing messages can be sent to this channel from server mods. * No more incoming or outgoing messages can be sent to this channel from
* This invalidate all future object usage server mods.
* Ensure your set mod_channel to nil after that to free Lua resources * This invalidate all future object usage.
* `is_writeable()`: returns true if channel is writeable and mod can send over it. * Ensure your set mod_channel to nil after that to free Lua resources.
* `is_writeable()`: returns true if channel is writeable and mod can send over
it.
* `send_all(message)`: Send `message` though the mod channel. * `send_all(message)`: Send `message` though the mod channel.
* If mod channel is not writeable or invalid, message will be dropped. * If mod channel is not writeable or invalid, message will be dropped.
* Message size is limited to 65535 characters by protocol. * Message size is limited to 65535 characters by protocol.
@ -3765,8 +3798,9 @@ Can be obtained via `minetest.get_meta(pos)`.
* `get_inventory()`: returns `InvRef` * `get_inventory()`: returns `InvRef`
* `mark_as_private(name or {name1, name2, ...})`: Mark specific vars as private * `mark_as_private(name or {name1, name2, ...})`: Mark specific vars as private
This will prevent them from being sent to the client. Note that the "private" This will prevent them from being sent to the client. Note that the "private"
status will only be remembered if an associated key-value pair exists, meaning status will only be remembered if an associated key-value pair exists,
it's best to call this when initializing all other meta (e.g. `on_construct`). meaning it's best to call this when initializing all other meta (e.g.
`on_construct`).
### `ItemStackMetaRef` ### `ItemStackMetaRef`
ItemStack metadata: reference extra data and functionality stored in a stack. ItemStack metadata: reference extra data and functionality stored in a stack.
@ -3775,8 +3809,9 @@ Can be obtained via `item:get_meta()`.
#### Methods #### Methods
* All methods in MetaDataRef * All methods in MetaDataRef
* `set_tool_capabilities([tool_capabilities])` * `set_tool_capabilities([tool_capabilities])`
* overrides the item's tool capabilities * Overrides the item's tool capabilities
* a nil value will clear the override data and restore the original behavior * A nil value will clear the override data and restore the original
behavior.
### `StorageRef` ### `StorageRef`
Mod metadata: per mod metadata, saved automatically. Mod metadata: per mod metadata, saved automatically.
@ -3794,7 +3829,8 @@ Can be gotten via `minetest.get_node_timer(pos)`.
* set a timer's state * set a timer's state
* `timeout` is in seconds, and supports fractional values (0.1 etc) * `timeout` is in seconds, and supports fractional values (0.1 etc)
* `elapsed` is in seconds, and supports fractional values (0.1 etc) * `elapsed` is in seconds, and supports fractional values (0.1 etc)
* will trigger the node's `on_timer` function after `(timeout - elapsed)` seconds * will trigger the node's `on_timer` function after `(timeout - elapsed)`
seconds.
* `start(timeout)` * `start(timeout)`
* start a timer * start a timer
* equivalent to `set(timeout,0)` * equivalent to `set(timeout,0)`
@ -3803,7 +3839,8 @@ Can be gotten via `minetest.get_node_timer(pos)`.
* `get_timeout()`: returns current timeout in seconds * `get_timeout()`: returns current timeout in seconds
* if `timeout` equals `0`, timer is inactive * if `timeout` equals `0`, timer is inactive
* `get_elapsed()`: returns current elapsed time in seconds * `get_elapsed()`: returns current elapsed time in seconds
* the node's `on_timer` function will be called after `(timeout - elapsed)` seconds * the node's `on_timer` function will be called after `(timeout - elapsed)`
seconds.
* `is_started()`: returns boolean state of timer * `is_started()`: returns boolean state of timer
* returns `true` if timer is started, otherwise `false` * returns `true` if timer is started, otherwise `false`
@ -3826,10 +3863,12 @@ This is basically a reference to a C++ `ServerActiveObject`
* `get_hp()`: returns number of hitpoints (2 * number of hearts) * `get_hp()`: returns number of hitpoints (2 * number of hearts)
* `set_hp(hp)`: set number of hitpoints (2 * number of hearts) * `set_hp(hp)`: set number of hitpoints (2 * number of hearts)
* `get_inventory()`: returns an `InvRef` * `get_inventory()`: returns an `InvRef`
* `get_wield_list()`: returns the name of the inventory list the wielded item is in * `get_wield_list()`: returns the name of the inventory list the wielded item
is in.
* `get_wield_index()`: returns the index of the wielded item * `get_wield_index()`: returns the index of the wielded item
* `get_wielded_item()`: returns an `ItemStack` * `get_wielded_item()`: returns an `ItemStack`
* `set_wielded_item(item)`: replaces the wielded item, returns `true` if successful * `set_wielded_item(item)`: replaces the wielded item, returns `true` if
successful.
* `set_armor_groups({group1=rating, group2=rating, ...})` * `set_armor_groups({group1=rating, group2=rating, ...})`
* `get_armor_groups()`: returns a table with the armor group ratings * `get_armor_groups()`: returns a table with the armor group ratings
* `set_animation(frame_range, frame_speed, frame_blend, frame_loop)` * `set_animation(frame_range, frame_speed, frame_blend, frame_loop)`
@ -3837,14 +3876,16 @@ This is basically a reference to a C++ `ServerActiveObject`
* `frame_speed`: number, default: `15.0` * `frame_speed`: number, default: `15.0`
* `frame_blend`: number, default: `0.0` * `frame_blend`: number, default: `0.0`
* `frame_loop`: boolean, default: `true` * `frame_loop`: boolean, default: `true`
* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and `frame_loop` * `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and
`frame_loop`.
* `set_animation_frame_speed(frame_speed)` * `set_animation_frame_speed(frame_speed)`
* `frame_speed`: number, default: `15.0` * `frame_speed`: number, default: `15.0`
* `set_attach(parent, bone, position, rotation)` * `set_attach(parent, bone, position, rotation)`
* `bone`: string * `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative) * `position`: `{x=num, y=num, z=num}` (relative)
* `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees
* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't attached * `get_attach()`: returns parent, bone, position, rotation or nil if it isn't
attached.
* `set_detach()` * `set_detach()`
* `set_bone_position(bone, position, rotation)` * `set_bone_position(bone, position, rotation)`
* `bone`: string * `bone`: string
@ -3897,19 +3938,26 @@ This is basically a reference to a C++ `ServerActiveObject`
table {x, y, z} representing the player's instantaneous velocity in nodes/s 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_dir()`: get camera direction as a unit vector
* `get_look_vertical()`: pitch in radians * `get_look_vertical()`: pitch in radians
* Angle ranges between -pi/2 and pi/2, which are straight up and down respectively. * Angle ranges between -pi/2 and pi/2, which are straight up and down
respectively.
* `get_look_horizontal()`: yaw in radians * `get_look_horizontal()`: yaw in radians
* Angle is counter-clockwise from the +z direction. * Angle is counter-clockwise from the +z direction.
* `set_look_vertical(radians)`: sets look pitch * `set_look_vertical(radians)`: sets look pitch
* radians - Angle from looking forward, where positive is downwards. * radians - Angle from looking forward, where positive is downwards.
* `set_look_horizontal(radians)`: sets look yaw * `set_look_horizontal(radians)`: sets look yaw
* radians - Angle from the +z direction, where positive is counter-clockwise. * radians - Angle from the +z direction, where positive is
* `get_look_pitch()`: pitch in radians - Deprecated as broken. Use `get_look_vertical`. counter-clockwise.
* Angle ranges between -pi/2 and pi/2, which are straight down and up respectively. * `get_look_pitch()`: pitch in radians - Deprecated as broken. Use
* `get_look_yaw()`: yaw in radians - Deprecated as broken. Use `get_look_horizontal`. `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. * Angle is counter-clockwise from the +x direction.
* `set_look_pitch(radians)`: sets look pitch - Deprecated. Use `set_look_vertical`. * `set_look_pitch(radians)`: sets look pitch - Deprecated. Use
* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use `set_look_horizontal`. `set_look_vertical`.
* `set_look_yaw(radians)`: sets look yaw - Deprecated. Use
`set_look_horizontal`.
* `get_breath()`: returns players breath * `get_breath()`: returns players breath
* `set_breath(value)`: sets players breath * `set_breath(value)`: sets players breath
* values: * values:
@ -3918,7 +3966,8 @@ This is basically a reference to a C++ `ServerActiveObject`
* See Object Properties for more information * See Object Properties for more information
* `set_attribute(attribute, value)`: * `set_attribute(attribute, value)`:
* Sets an extra attribute with value on player. * Sets an extra attribute with value on player.
* `value` must be a string, or a number which will be converted to a string. * `value` must be a string, or a number which will be converted to a
string.
* If `value` is `nil`, remove attribute from player. * If `value` is `nil`, remove attribute from player.
* `get_attribute(attribute)`: * `get_attribute(attribute)`:
* Returns value (a string) for extra attribute. * Returns value (a string) for extra attribute.
@ -3929,10 +3978,11 @@ This is basically a reference to a C++ `ServerActiveObject`
* `get_inventory_formspec()`: returns a formspec string * `get_inventory_formspec()`: returns a formspec string
* `get_player_control()`: returns table with player pressed keys * `get_player_control()`: returns table with player pressed keys
* The table consists of fields with boolean value representing the pressed * The table consists of fields with boolean value representing the pressed
keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down and up keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up.
* example: `{jump=false, right=true, left=false, LMB=false, RMB=false, * 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}`
* `get_player_control_bits()`: returns integer with bit packed player pressed keys * `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, * 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
* `set_physics_override(override_table)` * `set_physics_override(override_table)`
@ -3950,16 +4000,19 @@ This is basically a reference to a C++ `ServerActiveObject`
* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID * `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID
number on success number on success
* `hud_remove(id)`: remove the HUD element of the specified id * `hud_remove(id)`: remove the HUD element of the specified id
* `hud_change(id, stat, value)`: change a value of a previously added HUD element * `hud_change(id, stat, value)`: change a value of a previously added HUD
* element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir` element.
* element `stat` values:
`position`, `name`, `scale`, `text`, `number`, `item`, `dir`
* `hud_get(id)`: gets the HUD element definition structure of the specified ID * `hud_get(id)`: gets the HUD element definition structure of the specified ID
* `hud_set_flags(flags)`: sets specified HUD flags to `true`/`false` * `hud_set_flags(flags)`: sets specified HUD flags to `true`/`false`
* `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`, `breathbar`, * `flags`: (is visible) `hotbar`, `healthbar`, `crosshair`, `wielditem`,
`minimap`, `minimap_radar` `breathbar`, `minimap`, `minimap_radar`
* pass a table containing a `true`/`false` value of each flag to be set or unset * pass a table containing a `true`/`false` value of each flag to be set or
unset.
* if a flag equals `nil`, the flag is not modified * if a flag equals `nil`, the flag is not modified
* note that setting `minimap` modifies the client's permission to view the minimap - * note that setting `minimap` modifies the client's permission to view the
* the client may locally elect to not view the minimap minimap - the client may locally elect to not view the minimap.
* minimap `radar` is only usable when `minimap` is true * minimap `radar` is only usable when `minimap` is true
* `hud_get_flags()`: returns a table containing status of hud flags * `hud_get_flags()`: returns a table containing status of hud flags
* returns `{hotbar=true, healthbar=true, crosshair=true, wielditem=true, * returns `{hotbar=true, healthbar=true, crosshair=true, wielditem=true,
@ -3985,15 +4038,20 @@ This is basically a reference to a C++ `ServerActiveObject`
* `set_clouds(parameters)`: set cloud parameters * `set_clouds(parameters)`: set cloud parameters
* `parameters` is a table with the following optional fields: * `parameters` is a table with the following optional fields:
* `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`) * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
* `color`: basic cloud color with alpha channel, ColorSpec (default `#fff0f0e5`) * `color`: basic cloud color with alpha channel, ColorSpec
(default `#fff0f0e5`).
* `ambient`: cloud color lower bound, use for a "glow at night" effect. * `ambient`: cloud color lower bound, use for a "glow at night" effect.
ColorSpec (alpha ignored, default `#000000`) ColorSpec (alpha ignored, default `#000000`)
* `height`: cloud height, i.e. y of cloud base (default per conf, usually `120`) * `height`: cloud height, i.e. y of cloud base (default per conf,
usually `120`)
* `thickness`: cloud thickness in nodes (default `16`) * `thickness`: cloud thickness in nodes (default `16`)
* `speed`: 2D cloud speed + direction in nodes per second (default `{x=0, z=-2}`) * `speed`: 2D cloud speed + direction in nodes per second
* `get_clouds()`: returns a table with the current cloud parameters as in `set_clouds` (default `{x=0, z=-2}`).
* `get_clouds()`: returns a table with the current cloud parameters as in
`set_clouds`.
* `override_day_night_ratio(ratio or nil)` * `override_day_night_ratio(ratio or nil)`
* `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific amount * `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific
amount.
* `nil`: Disables override, defaulting to sunlight based on day-night cycle * `nil`: Disables override, defaulting to sunlight based on day-night cycle
* `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden * `get_day_night_ratio()`: returns the ratio or nil if it isn't overridden
* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`: * `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`:
@ -4004,8 +4062,10 @@ This is basically a reference to a C++ `ServerActiveObject`
{x=189, y=198}, -- < dig animation key frames {x=189, y=198}, -- < dig animation key frames
{x=200, y=219}, -- < walk+dig animation key frames {x=200, y=219}, -- < walk+dig animation key frames
frame_speed=30): -- < animation frame speed frame_speed=30): -- < animation frame speed
* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and `frame_speed` * `get_local_animation()`: returns stand, walk, dig, dig+walk tables and
* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for camera per player `frame_speed`.
* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for
camera per player.
* in first person view * in first person view
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`) * in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
* `get_eye_offset()`: returns `offset_first` and `offset_third` * `get_eye_offset()`: returns `offset_first` and `offset_third`
@ -4026,60 +4086,81 @@ An `InvRef` is a reference to an inventory.
* `set_list(listname, list)`: set full list (size will not change) * `set_list(listname, list)`: set full list (size will not change)
* `get_lists()`: returns list of inventory lists * `get_lists()`: returns list of inventory lists
* `set_lists(lists)`: sets inventory lists (size will not change) * `set_lists(lists)`: sets inventory lists (size will not change)
* `add_item(listname, stack)`: add item somewhere in list, returns leftover `ItemStack` * `add_item(listname, stack)`: add item somewhere in list, returns leftover
`ItemStack`.
* `room_for_item(listname, stack):` returns `true` if the stack of items * `room_for_item(listname, stack):` returns `true` if the stack of items
can be fully added to the list can be fully added to the list
* `contains_item(listname, stack, [match_meta])`: returns `true` if * `contains_item(listname, stack, [match_meta])`: returns `true` if
the stack of items can be fully taken from the list. the stack of items can be fully taken from the list.
If `match_meta` is false, only the items' names are compared (default: `false`). If `match_meta` is false, only the items' names are compared
* `remove_item(listname, stack)`: take as many items as specified from the list, (default: `false`).
returns the items that were actually removed (as an `ItemStack`) -- note that * `remove_item(listname, stack)`: take as many items as specified from the
any item metadata is ignored, so attempting to remove a specific unique list, returns the items that were actually removed (as an `ItemStack`)
item this way will likely remove the wrong one -- to do that use `set_stack` -- note that any item metadata is ignored, so attempting to remove a specific
with an empty `ItemStack` unique item this way will likely remove the wrong one -- to do that use
* `get_location()`: returns a location compatible to `minetest.get_inventory(location)` `set_stack` with an empty `ItemStack`.
* `get_location()`: returns a location compatible to
`minetest.get_inventory(location)`.
* returns `{type="undefined"}` in case location is not known * returns `{type="undefined"}` in case location is not known
### `AreaStore` ### `AreaStore`
A fast access data structure to store areas, and find areas near a given position or area. 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. Every area has a `data` string attribute to store additional information.
You can create an empty `AreaStore` by calling `AreaStore()`, or `AreaStore(type_name)`. You can create an empty `AreaStore` by calling `AreaStore()`, or
If you chose the parameter-less constructor, a fast implementation will be automatically `AreaStore(type_name)`.
chosen for you. If you chose the parameter-less constructor, a fast implementation will be
automatically chosen for you.
#### Methods #### Methods
* `get_area(id, include_borders, include_data)`: returns the area with the id `id`. * `get_area(id, include_borders, include_data)`: returns the area with the id
(optional) Boolean values `include_borders` and `include_data` control what's copied. `id`.
(optional) Boolean values `include_borders` and `include_data` control what's
copied.
Returns nil if specified area id does not exist. Returns nil if specified area id does not exist.
* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain * `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas
the position `pos`. (optional) Boolean values `include_borders` and `include_data` control that contain the position `pos`.
what's copied. (optional) Boolean values `include_borders` and `include_data` control what's
copied.
* `get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)`: * `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). returns all areas that contain all nodes inside the area specified by `edge1`
If `accept_overlap` is true, also areas are returned that have nodes in common with the specified area. and `edge2` (inclusive).
(optional) Boolean values `include_borders` and `include_data` control what's copied. If `accept_overlap` is true, also areas are returned that have nodes in
* `insert_area(edge1, edge2, data, [id])`: inserts an area into the store. Returns the new area's ID, common with the specified area.
or nil if the insertion failed. The (inclusive) positions `edge1` and `edge2` describe the area. (optional) Boolean values `include_borders` and `include_data` control what's
`data` is a string stored with the area. If passed, `id` will be used as the internal area ID, copied.
it must be a unique number between 0 and 2^32-2. If you use the `id` parameter you must always use it, * `insert_area(edge1, edge2, data, [id])`: inserts an area into the store.
or insertions are likely to fail due to conflicts. Returns the new area's ID, or nil if the insertion failed.
* `reserve(count)`: reserves resources for at most `count` many contained areas. 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. Only needed for efficiency, and only some implementations profit.
* `remove_area(id)`: removes the area with the given id from the store, returns success. * `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. * `set_cache_params(params)`: sets params for the included prefiltering cache.
Calling invalidates the cache, so that its elements have to be newly generated. Calling invalidates the cache, so that its elements have to be newly
generated.
* `params`: * `params`:
{ {
enabled = boolean, -- whether to enable, default true enabled = boolean, -- whether to enable, default true
block_radius = number, -- the radius (in nodes) of the areas the cache generates block_radius = number, -- the radius (in nodes) of the areas the cache
prefiltered lists for, minimum 16, default 64 generates prefiltered lists for, minimum 16,
limit = number, -- the cache's size, minimum 20, default 1000 default 64.
limit = number, -- the cache's size, minimum 20, default 1000
} }
* `to_string()`: Experimental. Returns area store serialized as a (binary) string. * `to_string()`: Experimental. Returns area store serialized as a (binary)
* `to_file(filename)`: Experimental. Like `to_string()`, but writes the data to a file. string.
* `from_string(str)`: Experimental. Deserializes string and loads it into the AreaStore. * `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. Returns success and, optionally, an error message.
* `from_file(filename)`: Experimental. Like `from_string()`, but reads the data from a file. * `from_file(filename)`: Experimental. Like `from_string()`, but reads the data
from a file.
### `ItemStack` ### `ItemStack`
An `ItemStack` is a stack of items. An `ItemStack` is a stack of items.
@ -4090,7 +4171,8 @@ an itemstring, a table or `nil`.
#### Methods #### Methods
* `is_empty()`: returns `true` if stack is empty. * `is_empty()`: returns `true` if stack is empty.
* `get_name()`: returns item name (e.g. `"default:stone"`). * `get_name()`: returns item name (e.g. `"default:stone"`).
* `set_name(item_name)`: returns a boolean indicating whether the item was cleared * `set_name(item_name)`: returns a boolean indicating whether the item was
cleared.
* `get_count()`: Returns number of items on the stack. * `get_count()`: Returns number of items on the stack.
* `set_count(count)`: returns a boolean indicating whether the item was cleared * `set_count(count)`: returns a boolean indicating whether the item was cleared
* `count`: number, unsigned 16 bit integer * `count`: number, unsigned 16 bit integer
@ -4098,14 +4180,16 @@ an itemstring, a table or `nil`.
* `set_wear(wear)`: returns boolean indicating whether item was cleared * `set_wear(wear)`: returns boolean indicating whether item was cleared
* `wear`: number, unsigned 16 bit integer * `wear`: number, unsigned 16 bit integer
* `get_meta()`: returns ItemStackMetaRef. See section for more details * `get_meta()`: returns ItemStackMetaRef. See section for more details
* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item stack). * `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item
stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true. * `set_metadata(metadata)`: (DEPRECATED) Returns true.
* `clear()`: removes all items from the stack, making it empty. * `clear()`: removes all items from the stack, making it empty.
* `replace(item)`: replace the contents of this stack. * `replace(item)`: replace the contents of this stack.
* `item` can also be an itemstring or table. * `item` can also be an itemstring or table.
* `to_string()`: returns the stack in itemstring form. * `to_string()`: returns the stack in itemstring form.
* `to_table()`: returns the stack in Lua table form. * `to_table()`: returns the stack in Lua table form.
* `get_stack_max()`: returns the maximum size of the stack (depends on the item). * `get_stack_max()`: returns the maximum size of the stack (depends on the
item).
* `get_free_space()`: returns `get_stack_max() - get_count()`. * `get_free_space()`: returns `get_stack_max() - get_count()`.
* `is_known()`: returns `true` if the item name refers to a defined item type. * `is_known()`: returns `true` if the item name refers to a defined item type.
* `get_definition()`: returns the item definition table. * `get_definition()`: returns the item definition table.
@ -4139,14 +4223,16 @@ It can be created via `PseudoRandom(seed)`.
### `PcgRandom` ### `PcgRandom`
A 32-bit pseudorandom number generator. A 32-bit pseudorandom number generator.
Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness. Uses PCG32, an algorithm of the permuted congruential generator family,
offering very strong randomness.
It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`. It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`.
#### Methods #### Methods
* `next()`: return next integer random number [`-2147483648`...`2147483647`] * `next()`: return next integer random number [`-2147483648`...`2147483647`]
* `next(min, max)`: return next integer random number [`min`...`max`] * `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`] * `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: * This is only a rough approximation of a normal distribution with:
* `mean = (max - min) / 2`, and * `mean = (max - min) / 2`, and
* `variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)` * `variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)`
@ -4155,11 +4241,12 @@ It can be created via `PcgRandom(seed)` or `PcgRandom(seed, sequence)`.
### `SecureRandom` ### `SecureRandom`
Interface for the operating system's crypto-secure PRNG. Interface for the operating system's crypto-secure PRNG.
It can be created via `SecureRandom()`. The constructor returns nil if a secure random device cannot be It can be created via `SecureRandom()`. The constructor returns nil if a
be found on the system. secure random device cannot be found on the system.
#### Methods #### Methods
* `next_bytes([count])`: return next `count` (default 1, capped at 2048) many random bytes, as a string. * `next_bytes([count])`: return next `count` (default 1, capped at 2048) many
random bytes, as a string.
### `PerlinNoise` ### `PerlinNoise`
A perlin noise generator. A perlin noise generator.
@ -4178,32 +4265,37 @@ A fast, bulk perlin noise generator.
It can be created via `PerlinNoiseMap(noiseparams, size)` or It can be created via `PerlinNoiseMap(noiseparams, size)` or
`minetest.get_perlin_map(noiseparams, size)`. `minetest.get_perlin_map(noiseparams, size)`.
Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` component is omitted 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 for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
`nil` is returned). `nil` is returned).
For each of the functions with an optional `buffer` parameter: If `buffer` is not For each of the functions with an optional `buffer` parameter: If `buffer` is
nil, this table will be used to store the result instead of creating a new table. not nil, this table will be used to store the result instead of creating a new
table.
#### Methods #### Methods
* `get_2d_map(pos)`: returns a `<size.x>` times `<size.y>` 2D array of 2D noise * `get_2d_map(pos)`: returns a `<size.x>` times `<size.y>` 2D array of 2D noise
with values starting at `pos={x=,y=}` with values starting at `pos={x=,y=}`
* `get_3d_map(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>` 3D array * `get_3d_map(pos)`: returns a `<size.x>` times `<size.y>` times `<size.z>`
of 3D noise with values starting at `pos={x=,y=,z=}` 3D array of 3D noise with values starting at `pos={x=,y=,z=}`.
* `get_2d_map_flat(pos, buffer)`: returns a flat `<size.x * size.y>` element array of 2D noise * `get_2d_map_flat(pos, buffer)`: returns a flat `<size.x * size.y>` element
with values starting at `pos={x=,y=}` array of 2D noise with values starting at `pos={x=,y=}`
* `get_3d_map_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise * `get_3d_map_flat(pos, buffer)`: Same as `get2dMap_flat`, but 3D noise
* `calc_2d_map(pos)`: Calculates the 2d noise map starting at `pos`. The result is stored internally. * `calc_2d_map(pos)`: Calculates the 2d noise map starting at `pos`. The result
* `calc_3d_map(pos)`: Calculates the 3d noise map starting at `pos`. The result is stored internally. is stored internally.
* `get_map_slice(slice_offset, slice_size, buffer)`: In the form of an array, returns a slice of the * `calc_3d_map(pos)`: Calculates the 3d noise map starting at `pos`. The result
most recently computed noise results. The result slice begins at coordinates `slice_offset` and is stored internally.
takes a chunk of `slice_size`. * `get_map_slice(slice_offset, slice_size, buffer)`: In the form of an array,
E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20: returns a slice of the most recently computed noise results. The result slice
begins at coordinates `slice_offset` and takes a chunk of `slice_size`.
E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer
offset y = 20:
`noisevals = noise:get_map_slice({y=20}, {y=2})` `noisevals = noise:get_map_slice({y=20}, {y=2})`
It is important to note that `slice_offset` offset coordinates begin at 1, and are relative to It is important to note that `slice_offset` offset coordinates begin at 1,
the starting position of the most recently calculated noise. and are relative to the starting position of the most recently calculated
To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000: noise.
To grab a single vertical column of noise starting at map coordinates
x = 1023, y=1000, z = 1000:
`noise:calc_3d_map({x=1000, y=1000, z=1000})` `noise:calc_3d_map({x=1000, y=1000, z=1000})`
`noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1})` `noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1})`