-Minetest Lua Modding API Reference 0.5.0
-=========================================
+Minetest Lua Modding API Reference
+==================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
Introduction
------------
-Content and functionality can be added to Minetest 0.4 by using Lua
-scripting in run-time loaded mods.
+Content and functionality can be added to Minetest using Lua scripting
+in run-time loaded mods.
A mod is a self-contained bunch of scripts, textures and other related
-things that is loaded by and interfaces with Minetest.
+things, which is loaded by and interfaces with Minetest.
Mods are contained and ran solely on the server side. Definitions and media
files are automatically transferred to the client.
If you see a deficiency in the API, feel free to attempt to add the
-functionality in the engine and API.
+functionality in the engine and API, and to document it here.
Programming in Lua
------------------
where `gameid` is unique to each game.
-The game directory contains the file `game.conf`, which contains these fields:
+The game directory contains the file `game.conf`, which contains:
name = <Human-readable full name of the game>
name = Minetest
+Optionally, game.conf can also contain:
+
+ disallowed_mapgens = <comma-separated mapgens>
+
+e.g.
+
+ disallowed_mapgens = v5,v6,flat
+
+These mapgens are removed from the list of mapgens for the game.
+
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.
A single line contains a single modname.
Optional dependencies can be defined by appending a question mark
-to a single modname. Their meaning is that if the specified mod
-is missing, that does not prevent this mod from being loaded.
+to a single modname. This means that if the specified mod
+is missing, it does not prevent this mod from being loaded.
### `screenshot.png`
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.
+A file containing a description to be shown in the Mods tab of the mainmenu.
### `settingtypes.txt`
A file in the same format as the one in builtin. It will be parsed by the
The `:` prefix can also be used for maintaining backwards compatibility.
-### Aliases
+Aliases
+-------
Aliases can be added by using `minetest.register_alias(name, convert_to)` or
`minetest.register_alias_force(name, convert_to)`.
-This will make Minetest to convert things called name to things called
-`convert_to`.
+This converts anything called `name` to `convert_to`.
The only difference between `minetest.register_alias` and
`minetest.register_alias_force` is that if an item called `name` exists,
This can be used for maintaining backwards compatibility.
-This can be also used for setting quick access names for things, e.g. if
+This can also set quick access names for things, e.g. if
you have an item called `epiclylongmodname:stuff`, you could do
minetest.register_alias("stuff", "epiclylongmodname:stuff")
and be able to use `/giveme stuff`.
+Mapgen aliases
+--------------
+In a game, a certain number of these must be set to tell core mapgens which
+of the game's nodes are to be used by the core mapgens. For example:
+
+ minetest.register_alias("mapgen_stone", "default:stone")
+
+### Aliases needed for all mapgens except Mapgen v6
+
+Base terrain:
+
+"mapgen_stone"
+"mapgen_water_source"
+"mapgen_river_water_source"
+
+Caves:
+
+"mapgen_lava_source"
+
+Dungeons:
+
+Only needed for registered biomes where 'node_stone' is stone:
+"mapgen_cobble"
+"mapgen_stair_cobble"
+"mapgen_mossycobble"
+Only needed for registered biomes where 'node_stone' is desert stone:
+"mapgen_desert_stone"
+"mapgen_stair_desert_stone"
+Only needed for registered biomes where 'node_stone' is sandstone:
+"mapgen_sandstone"
+"mapgen_sandstonebrick"
+"mapgen_stair_sandstone_block"
+
+### Aliases needed for Mapgen v6
+
+Terrain and biomes:
+
+"mapgen_stone"
+"mapgen_water_source"
+"mapgen_lava_source"
+"mapgen_dirt"
+"mapgen_dirt_with_grass"
+"mapgen_sand"
+"mapgen_gravel"
+"mapgen_desert_stone"
+"mapgen_desert_sand"
+"mapgen_dirt_with_snow"
+"mapgen_snowblock"
+"mapgen_snow"
+"mapgen_ice"
+
+Flora:
+
+"mapgen_tree"
+"mapgen_leaves"
+"mapgen_apple"
+"mapgen_jungletree"
+"mapgen_jungleleaves"
+"mapgen_junglegrass"
+"mapgen_pine_tree"
+"mapgen_pine_needles"
+
+Dungeons:
+
+"mapgen_cobble"
+"mapgen_stair_cobble"
+"mapgen_mossycobble"
+"mapgen_stair_desert_stone"
+
Textures
--------
Mods should generally prefix their textures with `modname_`, e.g. given
default_dirt.png^default_grass_side.png
-`default_grass_side.png` is overlayed over `default_dirt.png`.
+`default_grass_side.png` is overlaid over `default_dirt.png`.
The texture with the lower resolution will be automatically upscaled to
the higher resolution texture.
### Advanced texture modifiers
-#### `[crack:<n>:<p>`
+#### Crack
+* `[crack:<n>:<p>`
+* `[cracko:<n>:<p>`
+* `[crack:<t>:<n>:<p>`
+* `[cracko:<t>:<n>:<p>`
+
+Parameters:
+* `<t>` = tile count (in each direction)
* `<n>` = animation frame count
* `<p>` = current animation frame
Draw a step of the crack animation on the texture.
+`crack` draws it normally, while `cracko` lays it over, keeping transparent pixels intact.
Example:
Example:
- default_apple.png^[invert:rgb
+ default_apple.png^[invert:rgb
#### `[brighten`
Brightens the texture.
for reverse compatibility. New code should prefer `column_height_max`.
The `column_midpoint_factor` parameter controls the position of the column at which
-ore eminates from. If 1, columns grow upward. If 0, columns grow downward. If 0.5,
+ore emanates from. If 1, columns grow upward. If 0, columns grow downward. If 0.5,
columns grow equally starting from each direction. `column_midpoint_factor` is a
decimal number ranging in value from 0 to 1. If this parameter is not specified,
the default is 0.5.
### `vein`
Creates veins of ore varying in density by according to the intersection of two
-instances of 3d perlin noise with diffferent seeds, both described by
-`noise_params`. `random_factor` varies the influence random chance has on
-placement of an ore inside the vein, which is `1` by default. Note that
-modifying this parameter may require adjusting `noise_threshold`.
+instances of 3d perlin noise with different seeds, both described by
+`noise_params`.
+
+`random_factor` varies the influence random chance has on placement of an ore
+inside the vein, which is `1` by default. Note that modifying this parameter may
+require adjusting `noise_threshold`.
+
The parameters `clust_scarcity`, `clust_num_ores`, and `clust_size` are ignored
-by this ore type. This ore type is difficult to control since it is sensitive
-to small changes. The following is a decent set of parameters to work from:
-
- noise_params = {
- offset = 0,
- scale = 3,
- spread = {x=200, y=200, z=200},
- seed = 5390,
- octaves = 4,
- persist = 0.5,
- flags = "eased",
- },
- noise_threshold = 1.6
+by this ore type.
+
+This ore type is difficult to control since it is sensitive to small changes.
+The following is a decent set of parameters to work from:
+
+ noise_params = {
+ offset = 0,
+ scale = 3,
+ spread = {x=200, y=200, z=200},
+ seed = 5390,
+ octaves = 4,
+ persist = 0.5,
+ flags = "eased",
+ },
+ noise_threshold = 1.6
**WARNING**: Use this ore type *very* sparingly since it is ~200x more
computationally expensive than any other ore.
### `stratum`
Creates a single undulating ore stratum that is continuous across mapchunk
borders and horizontally spans the world.
-The 2D perlin noise described by `noise_params` varies the Y co-ordinate of the
+
+The 2D perlin noise described by `noise_params` defines the Y co-ordinate of the
stratum midpoint. The 2D perlin noise described by `np_stratum_thickness`
-varies the stratum's vertical thickness (in units of nodes). Due to being
+defines the stratum's vertical thickness (in units of nodes). Due to being
continuous across mapchunk borders the stratum's vertical thickness is
-unlimited.
+unlimited.
+
+If the noise parameter `noise_params` is omitted the ore will occur from y_min
+to y_max in a simple horizontal stratum.
+
+A parameter `stratum_thickness` can be provided instead of the noise parameter
+`np_stratum_thickness`, to create a constant thickness.
+
+Leaving out one or both noise parameters makes the ore generation less intensive,
+useful when adding multiple strata.
+
`y_min` and `y_max` define the limits of the ore generation and for performance
reasons should be set as close together as possible but without clipping the
stratum's Y variation.
+
Each node in the stratum has a 1-in-`clust_scarcity` chance of being ore, so a
solid-ore stratum would require a `clust_scarcity` of 1.
+
The parameters `clust_num_ores`, `clust_size`, `noise_threshold` and
`random_factor` are ignored by this ore type.
* The `size` field is a 3D vector containing the dimensions of the provided schematic. (required)
* The `yslice_prob` field is a table of {ypos, prob} which sets the `ypos`th vertical slice
- of the schematic to have a `prob / 256 * 100` chance of occuring. (default: 255)
+ of the schematic to have a `prob / 256 * 100` chance of occurring. (default: 255)
* The `data` field is a flat table of MapNode tables making up the schematic,
in the order of `[z [y [x]]]`. (required)
Each MapNode table contains:
* `direction` is a unit vector, pointing from the source of the punch to
the punched object.
* `damage` damage that will be done to entity
-Return value of this function will determin if damage is done by this function
+Return value of this function will determine if damage is done by this function
(retval true) or shall be done by engine (retval false)
To punch an entity/object in Lua, call:
#### `textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]`
* Same as fields above, but with multi-line input
+* if the text overflows a vertical scrollbar is added
+* if the name is empty the textarea is readonly. The label is not displayed then
#### `label[<X>,<Y>;<label>]`
* `x` and `y` work as per field
Spatial Vectors
---------------
-* `vector.new(a[, b, c])`: returns a vector:
+For the following functions, `v`, `v1`, `v2` are vectors, `p1`, `p2` are positions:
+
+* `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.floor(v)`: returns a vector, each dimension rounded down
-* `vector.round(v)`: returns a vector, each dimension rounded to nearest int
-* `vector.apply(v, func)`: returns a vector
-* `vector.equals(v1, v2)`: returns a boolean
-* `vector.sort(v1, v2)`: returns minp, maxp vectors of the cuboid defined by v1 and v2
+ * `{x = a, y = b, z = c}`, if all of `a`, `b`, `c` are defined numbers.
+* `vector.direction(p1, p2)`:
+ * Returns a vector of length 1 with direction `p1` to `p2`.
+ * If `p1` and `p2` are identical, returns `{x = 0, y = 0, z = 0}`.
+* `vector.distance(p1, p2)`:
+ * Returns zero or a positive number, the distance between `p1` and `p2`.
+* `vector.length(v)`:
+ * Returns zero or a positive number, the length of vector `v`.
+* `vector.normalize(v)`:
+ * Returns a vector of length 1 with direction of vector `v`.
+ * If `v` has zero length, returns `{x = 0, y = 0, z = 0}`.
+* `vector.floor(v)`:
+ * Returns a vector, each dimension rounded down.
+* `vector.round(v)`:
+ * Returns a vector, each dimension rounded to nearest integer.
+* `vector.apply(v, func)`:
+ * Returns a vector where the function `func` has been applied to each component.
+* `vector.equals(v1, v2)`:
+ * Returns a boolean, `true` if the vectors are identical.
+* `vector.sort(v1, v2)`:
+ * Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`.
For the following functions `x` can be either a vector or a number:
-* `vector.add(v, x)`: returns a vector
-* `vector.subtract(v, x)`: returns a vector
-* `vector.multiply(v, x)`: returns a scaled vector or Schur product
-* `vector.divide(v, x)`: returns a scaled vector or Schur quotient
+* `vector.add(v, x)`:
+ * Returns a vector.
+* `vector.subtract(v, x)`:
+ * Returns a vector.
+* `vector.multiply(v, x)`:
+ * Returns a scaled vector or Schur product.
+* `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={})`
- * Return object serialized as a string
+* `dump2(obj, name, dumped)`: returns a string which makes `obj` human readable,
+ handles reference loops
+ * `obj`: arbitrary variable
+ * `name`: string, default: `"_"`
+ * `dumped`: table, default: `{}`
+* `dump(obj, dumped)`: returns a string which makes `obj` human readable
+ * `obj`: arbitrary variable
+ * `dumped`: table, default: `{}`
* `math.hypot(x, y)`
* Get the hypotenuse of a triangle with legs x and y.
Useful for distance calculation.
-* `math.sign(x, tolerance)`
+* `math.sign(x, tolerance)`: returns `-1`, `0` or `1`
* Get the sign of a number.
- Optional: Also returns `0` when the absolute value is within the tolerance (default: `0`)
-* `string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)`
- * If `max_splits` is negative, do not limit splits.
- * `sep_is_pattern` specifies if separator is a plain string or a pattern (regex).
- * e.g. `string:split("a,b", ",") == {"a","b"}`
-* `string:trim()`
- * e.g. `string.trim("\n \t\tfoo bar\t ") == "foo bar"`
-* `minetest.wrap_text(str, limit, [as_table])`: returns a string or table
- * Adds newlines to the string to keep it within the specified character limit
- Note that returned lines may be longer than the limit since it only splits at word borders.
- * limit: Maximal amount of characters in one line
- * as_table: optional, if true return table of lines instead of string
-* `minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))`: returns string `"(X,Y,Z)"`
- * Convert position to a printable string
- Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.
-* `minetest.string_to_pos(string)`: returns a position
- * Same but in reverse. Returns `nil` if the string can't be parsed to a position.
+ * tolerance: number, default: `0.0`
+ * If the absolute value of `x` is within the `tolerance` or `x` is NaN,
+ `0` is returned.
+* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)`
+ * `separator`: string, default: `","`
+ * `include_empty`: boolean, default: `false`
+ * `max_splits`: number, if it's positive, splits aren't limited,
+ default: `-1`
+ * `sep_is_pattern`: boolean, it specifies whether separator is a plain
+ string or a pattern (regex), default: `false`
+ * e.g. `"a,b":split","` returns `{"a","b"}`
+* `string:trim()`: returns the string whithout whitespace pre- and suffixes
+ * e.g. `"\n \t\tfoo bar\t ":trim()` returns `"foo bar"`
+* `minetest.wrap_text(str, limit, as_table)`: returns a string or table
+ * Adds newlines to the string to keep it within the specified character
+ limit
+ * Note that the returned lines may be longer than the limit since it only
+ splits at word borders.
+ * `limit`: number, maximal amount of characters in one line
+ * `as_table`: boolean, if set to true, a table of lines instead of a string
+ is returned, default: `false`
+* `minetest.pos_to_string(pos, decimal_places)`: returns string `"(X,Y,Z)"`
+ * `pos`: table {x=X, y=Y, z=Z}
+ * Converts the position `pos` to a human-readable, printable string
+ * `decimal_places`: number, if specified, the x, y and z values of
+ the position are rounded to the given decimal place.
+* `minetest.string_to_pos(string)`: returns a position or `nil`
+ * Same but in reverse.
+ * If the string can't be parsed to a position, nothing is returned.
* `minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")`: returns two positions
* Converts a string representing an area box into two positions
* `minetest.formspec_escape(string)`: returns a string
when translation. Due to how translations are implemented, the original translation string **must** have
its arguments in increasing order, without gaps or repetitions, starting from 1.
* `@=` acts as a literal `=`. It is not required in strings given to `minetest.translate`, but is in translation
- files to avoid begin confused with the `=` separating the original from the translation.
+ files to avoid being confused with the `=` separating the original from the translation.
* `@\n` (where the `\n` is a literal newline) acts as a literal newline. As with `@=`, this escape is not required
in strings given to `minetest.translate`, but is in translation files.
* `@n` acts as a literal newline as well.
max_jitter = 0.5, -- maximum packet time jitter
avg_jitter = 0.03, -- average packet time jitter
connection_uptime = 200, -- seconds since client connected
- prot_vers = 31, -- protocol version used by client
+ protocol_version = 32, -- protocol version used by client
-- following information is available on debug build only!!!
-- DO NOT USE IN MODS
--ser_vers = 26, -- serialization version used by client
* nil: return all entries,
* true: return only subdirectory names, or
* false: return only file names.
+* `minetest.safe_file_write(path, content)`: returns boolean indicating success
+ * Replaces contents of file at path with new contents in a safe (atomic) way.
+ Use this instead of below code when writing e.g. database files:
+ `local f = io.open(path, "wb"); f:write(content); f:close()`
* `minetest.get_version()`: returns a table containing components of the
engine version. Components:
* `project`: Name of the project, eg, "Minetest"
* `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
Use this for informational purposes only. The information in the returned
table does not represent the capabilities of the engine, nor is it
- reliable or verifyable. Compatible forks will have a different name and
+ reliable or verifiable. Compatible forks will have a different name and
version entirely. To check for the presence of engine features, test
whether the functions exported by the wanted features exist. For example:
`if minetest.check_for_falling then ... end`.
+* `minetest.sha1(data, [raw])`: returns the sha1 hash of data
+ * `data`: string of data to hash
+ * `raw`: return raw bytes instead of hex digits, default: false
### Logging
* `minetest.debug(...)`
* `minetest.register_craftitem(name, item definition)`
* `minetest.unregister_item(name)`
* `minetest.register_alias(name, convert_to)`
+ * Also use this to set the 'mapgen aliases' needed in a game for the core
+ * mapgens. See 'Mapgen aliases' section above.
* `minetest.register_alias_force(name, convert_to)`
* `minetest.register_craft(recipe)`
* Check recipe table syntax for different types below.
* `minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack, pointed_thing))`
* Called when a node has been placed
* If return `true` no item is taken from `itemstack`
+ * `placer` may be any valid ObjectRef or nil.
* **Not recommended**; use `on_construct` or `after_place_node` in node definition
whenever possible
* `minetest.register_on_dignode(func(pos, oldnode, digger))`
* `minetest.register_can_bypass_userlimit(function(name, ip))`
* Called when `name` user connects with `ip`.
* Return `true` to by pass the player limit
+* `minetest.register_on_modchannel_message(func(channel_name, sender, message))`
+ * Called when an incoming mod channel message is received
+ * You should have joined some channels to receive events.
+ * If message comes from a server mod, `sender` field is an empty string.
### Other registration functions
* `minetest.register_chatcommand(cmd, chatcommand definition)`
* Note that the above two callbacks will be called twice if a player is responsible -
once with the player name, and then with a nil player name.
* Return true in the above callbacks to stop register_on_priv_grant or revoke being called.
-* `minetest.register_authentication_handler(handler)`
- * See `minetest.builtin_auth_handler` in `builtin.lua` for reference
+* `minetest.register_authentication_handler(authentication handler definition)`
+ * Registers an auth handler that overrides the builtin one
+ * This function can be called by a single mod once only.
### Setting-related
* `minetest.settings`: Settings object containing all of the settings from the
parses it as a position (in the format `(1,2,3)`). Returns a position or nil.
### Authentication
-* `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
-* `minetest.set_player_password(name, password_hash)`
-* `minetest.set_player_privs(name, {priv1=true,...})`
* `minetest.get_player_privs(name) -> {priv1=true,...}`
-* `minetest.auth_reload()`
* `minetest.check_player_privs(player_or_name, ...)`: returns `bool, missing_privs`
* A quickhand for checking privileges.
- * `player_or_name`: Either a Player object or the name of a player.
- * `...` is either a list of strings, e.g. `"priva", "privb"` or
- a table, e.g. `{ priva = true, privb = true }`.
-* `minetest.get_player_ip(name)`: returns an IP address string
+ * `player_or_name`: Either a Player object or the name of a player.
+ * `...` is either a list of strings, e.g. `"priva", "privb"` or
+ a table, e.g. `{ priva = true, privb = true }`.
+
+* `minetest.check_password_entry(name, entry, password)`
+ * Returns true if the "password entry" for a player with name matches given
+ password, false otherwise.
+ * The "password entry" is the password representation generated by the engine
+ as returned as part of a `get_auth()` call on the auth handler.
+ * Only use this function for making it possible to log in via password from
+ external protocols such as IRC, other uses 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.get_player_ip(name)`: returns an IP address string for the player `name`
+ * The player needs to be online for this to be successful.
+
+* `minetest.get_auth_handler()`: Return the currently active auth handler
+ * See the `Authentication handler definition`
+ * Use this to e.g. get the authentication data for a player:
+ `local auth_data = minetest.get_auth_handler().get_auth(playername)`
+* `minetest.notify_authentication_modified(name)`
+ * Must be called by the authentication handler for privilege changes.
+ * `name`: string; if omitted, all auth data should be considered modified
+* `minetest.set_player_password(name, password_hash)`: Set password hash of player `name`
+* `minetest.set_player_privs(name, {priv1=true,...})`: Set privileges of player `name`
+* `minetest.auth_reload()`
+ * See `reload()` in authentication handler definition
`minetest.set_player_password`, `minetest_set_player_privs`, `minetest_get_player_privs`
-and `minetest.auth_reload` call the authetification handler.
+and `minetest.auth_reload` call the authentication handler.
### Chat
* `minetest.chat_send_all(text)`
### Environment access
* `minetest.set_node(pos, node)`
-* `minetest.add_node(pos, node): alias set_node(pos, node)`
- * Set node at position (`node = {name="foo", param1=0, param2=0}`)
+* `minetest.add_node(pos, node): alias to `minetest.set_node`
+ * Set node at position `pos`
+ * `node`: table `{name=string, param1=number, param2=number}`
+ * If param1 or param2 is omitted, it's set to `0`.
+ * e.g. `minetest.set_node({x=0, y=10, z=0}, {name="default:wood"})`
* `minetest.swap_node(pos, node)`
* Set node at position, but don't remove metadata
* `minetest.remove_node(pos)`
- * Equivalent to `set_node(pos, "air")`
+ * By default it does the same as `minetest.set_node(pos, {name="air"})`
* `minetest.get_node(pos)`
* Returns the node at the given position as table in the format
`{name="node_name", param1=0, param2=0}`, returns `{name="ignore", param1=0, param2=0}`
* parameter was absent)
* `minetest.delete_area(pos1, pos2)`
* delete all mapblocks in the area from pos1 to pos2, inclusive
-* `minetest.line_of_sight(pos1, pos2, stepsize)`: returns `boolean, pos`
- * Check if there is a direct line of sight between `pos1` and `pos2`
+* `minetest.line_of_sight(pos1, pos2)`: returns `boolean, pos`
+ * Checks if there is anything other than air between pos1 and pos2.
+ * Returns false if something is blocking the sight.
* Returns the position of the blocking node when `false`
* `pos1`: First position
* `pos2`: Second position
- * `stepsize`: smaller gives more accurate results but requires more computing
- time. Default is `1`.
* `minetest.raycast(pos1, pos2, objects, liquids)`: returns `Raycast`
* Creates a `Raycast` object.
* `pos1`: start of the ray
* spread these updates to neighbours and can cause a cascade
of nodes to fall.
+### Mod channels
+You can find mod channels communication scheme in `docs/mod_channels.png`.
+
+* `minetest.mod_channel_join(channel_name)`
+ * Server joins channel `channel_name`, and creates it if necessary. You
+ should listen from incoming messages with `minetest.register_on_modchannel_message`
+ call to receive incoming messages
+
### Inventory
`minetest.get_inventory(location)`: returns an `InvRef`
* `minetest.get_server_status()`: returns server status string
* `minetest.get_server_uptime()`: returns the server uptime in seconds
* `minetest.remove_player(name)`: remove player from database (if he is not connected).
- * Does not remove player authentication data, minetest.player_exists will continue to return true.
+ * As auth data is not removed, minetest.player_exists will continue to return true.
+ Call the below method as well if you want to remove auth data too.
* Returns a code (0: successful, 1: no such player, 2: player is connected)
+* `minetest.remove_player_auth(name)`: remove player authentication data
+ * Returns boolean indicating success (false if player nonexistant)
### Bans
* `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`)
* Returns nil if the schematic could not be loaded.
* `minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)`:
- * This function is analagous to minetest.place_schematic, but places a schematic onto the
+ * This function is analogous to minetest.place_schematic, but places a schematic onto the
specified VoxelManip object `vmanip` instead of the whole map.
* 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.
* `name`: `"breath"` or `"health"`
* `hud_definition`: definition to replace builtin definition
* `minetest.send_join_message(player_name)`
- * Can be overridden by mods to change the join message
+ * This function can be overridden by mods to change the join message.
* `minetest.send_leave_message(player_name, timed_out)`
- * Can be overridden by mods to change the leave message
-* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
+ * This function can be overridden by mods to change the leave message.
+* `minetest.hash_node_position(pos)`: returns an 48-bit integer
+ * `pos`: table {x=number, y=number, z=number},
* Gives a unique hash number for a node position (16+16+16=48bit)
* `minetest.get_position_from_hash(hash)`: returns a position
* Inverse transform of `minetest.hash_node_position`
* 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.
+ actions, definable by mods, due to some mod-defined ownership-like concept.
Returns false or nil, if the player is allowed to do such actions.
+ * `name` will be "" for non-players or unknown players.
* This function should be overridden by protection mods and should be used to
check if a player can interact at a position.
* This function should call the old version of itself if the position is not
Class reference
---------------
+### ModChannel
+
+An interface to use mod channels on client and server
+
+#### Methods
+* `leave()`: leave the mod channel.
+ * Server leaves channel `channel_name`.
+ * No more incoming or outgoing messages can be sent to this channel from server mods.
+ * This invalidate all future object usage
+ * 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.
+ * If mod channel is not writeable or invalid, message will be dropped.
+ * Message size is limited to 65535 characters by protocol.
+
### `MetaDataRef`
See `StorageRef`, `NodeMetaRef` and `ItemStackMetaRef`.
#### Methods
* All methods in MetaDataRef
+* `set_tool_capabilities([tool_capabilities])`
+ * overrides the item's tool capabilities
+ * a nil value will clear the override data and restore the original behavior
### `StorageRef`
Mod metadata: per mod metadata, saved automatically.
* `set_wielded_item(item)`: replaces the wielded item, returns `true` if successful
* `set_armor_groups({group1=rating, group2=rating, ...})`
* `get_armor_groups()`: returns a table with the armor group ratings
-* `set_animation({x=1,y=1}, frame_speed=15.0, frame_blend=0, frame_loop=true)`
+* `set_animation(frame_range, frame_speed, frame_blend, frame_loop)`
+ * `frame_range`: table {x=num, y=num}, default: `{x=1, y=1}`
+ * `frame_speed`: number, default: `15.0`
+ * `frame_blend`: number, default: `0.0`
+ * `frame_loop`: boolean, default: `true`
* `get_animation()`: returns `range`, `frame_speed`, `frame_blend` and `frame_loop`
-* `set_animation_frame_speed(frame_speed=15.0)`
+* `set_animation_frame_speed(frame_speed)`
+ * `frame_speed`: number, default: `15.0`
* `set_attach(parent, bone, position, rotation)`
* `bone`: string
* `position`: `{x=num, y=num, z=num}` (relative)
- * `rotation`: `{x=num, y=num, z=num}`
+ * `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
* `set_detach()`
* `set_bone_position(bone, position, rotation)`
}
##### LuaEntitySAO-only (no-op for other objects)
-* `set_velocity({x=num, y=num, z=num})`
-* `get_velocity()`: returns `{x=num, y=num, z=num}`
-* `set_acceleration({x=num, y=num, z=num})`
-* `get_acceleration()`: returns `{x=num, y=num, z=num}`
+* `set_velocity(vel)`
+ * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
+* `get_velocity()`: returns the velocity, a vector
+* `set_acceleration(acc)`
+ * `acc` is a vector
+* `get_acceleration()`: returns the acceleration, a vector
* `set_yaw(radians)`
* `get_yaw()`: returns number in radians
* `set_texture_mod(mod)`
* `get_texture_mod()` returns current texture modifier
-* `set_sprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
- select_horiz_by_yawpitch=false)`
- * Select sprite from spritesheet with optional animation and DM-style
- texture selection based on yaw relative to camera
+* `set_sprite(p, num_frames, framelength, select_horiz_by_yawpitch)`
+ * Select sprite from spritesheet with optional animation and Dungeon Master
+ style texture selection based on yaw relative to camera
+ * `p`: {x=number, y=number}, the coordinate of the first frame
+ (x: column, y: row), default: `{x=0, y=0}`
+ * `num_frames`: number, default: `1`
+ * `framelength`: number, default: `0.2`
+ * `select_horiz_by_yawpitch`: boolean, this was once used for the Dungeon
+ Master mob, default: `false`
* `get_entity_name()` (**Deprecated**: Will be removed in a future version)
* `get_luaentity()`
* See Object Properties for more information
* `set_attribute(attribute, value)`:
* Sets an extra attribute with value on player.
- * `value` must be 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.
* `get_attribute(attribute)`:
* Returns value (a string) for extra attribute.
* Should usually be called in `on_joinplayer`
* `get_inventory_formspec()`: returns a formspec string
* `get_player_control()`: returns table with player pressed keys
- * `{jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}`
+ * 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
+ * example: `{jump=false, right=true, left=false, LMB=false, RMB=false,
+ sneak=true, aux1=false, down=false, up=false}`
* `get_player_control_bits()`: returns integer with bit packed player pressed keys
- * bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB
+ * bit nr/meaning: 0/up, 1/down, 2/left, 3/right, 4/jump, 5/aux1, 6/sneak,
+ 7/LMB, 8/RMB
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
`"plain"` custom skyboxes (default: `true`)
* `get_sky()`: returns bgcolor, type, table of textures, clouds
* `set_clouds(parameters)`: set cloud parameters
- * `parameters` is a table with the following optional fields:
- * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
- * `color`: basic cloud color with alpha channel, ColorSpec (default `#fff0f0e5`)
- * `ambient`: cloud color lower bound, use for a "glow at night" effect.
- ColorSpec (alpha ignored, default `#000000`)
- * `height`: cloud height, i.e. y of cloud base (default per conf, usually `120`)
- * `thickness`: cloud thickness in nodes (default `16`)
- * `speed`: 2D cloud speed + direction in nodes per second (default `{x=0, z=-2}`)
+ * `parameters` is a table with the following optional fields:
+ * `density`: from `0` (no clouds) to `1` (full clouds) (default `0.4`)
+ * `color`: basic cloud color with alpha channel, ColorSpec (default `#fff0f0e5`)
+ * `ambient`: cloud color lower bound, use for a "glow at night" effect.
+ ColorSpec (alpha ignored, default `#000000`)
+ * `height`: cloud height, i.e. y of cloud base (default per conf, usually `120`)
+ * `thickness`: cloud thickness in nodes (default `16`)
+ * `speed`: 2D cloud speed + direction in nodes per second (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)`
* `0`...`1`: Overrides day-night ratio, controlling sunlight to a specific amount
* `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
-* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`
-
- set animation for player model in third person view
+* `set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)`:
+ set animation for player model in third person view
set_local_animation({x=0, y=79}, -- < stand/idle animation key frames
{x=168, y=187}, -- < walk animation key frames
an itemstring, a table or `nil`.
#### Methods
-* `is_empty()`: Returns `true` if stack is empty.
-* `get_name()`: Returns item name (e.g. `"default:stone"`).
-* `set_name(item_name)`: Returns boolean whether item was cleared
+* `is_empty()`: returns `true` if stack is empty.
+* `get_name()`: returns item name (e.g. `"default:stone"`).
+* `set_name(item_name)`: returns a boolean indicating whether the item was cleared
* `get_count()`: Returns number of items on the stack.
-* `set_count(count)`: Returns boolean whether item was cleared
-* `get_wear()`: Returns tool wear (`0`-`65535`), `0` for non-tools.
-* `set_wear(wear)`: Returns boolean whether item was cleared
-* `get_meta()`: Returns ItemStackMetaRef. See section for more details
+* `set_count(count)`: returns a boolean indicating whether the item was cleared
+ * `count`: number, unsigned 16 bit integer
+* `get_wear()`: returns tool wear (`0`-`65535`), `0` for non-tools.
+* `set_wear(wear)`: returns boolean indicating whether item was cleared
+ * `wear`: number, unsigned 16 bit integer
+* `get_meta()`: returns ItemStackMetaRef. See section for more details
* `get_metadata()`: (DEPRECATED) Returns metadata (a string attached to an item stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true.
* `clear()`: removes all items from the stack, making it empty.
* `replace(item)`: replace the contents of this stack.
* `item` can also be an itemstring or table.
-* `to_string()`: Returns the stack in itemstring 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_free_space()`: Returns `get_stack_max() - get_count()`.
-* `is_known()`: Returns `true` if the item name refers to a defined item type.
-* `get_definition()`: Returns the item definition table.
-* `get_tool_capabilities()`: Returns the digging properties of the item,
- or those of the hand if none are defined for this item type
-* `add_wear(amount)`: Increases wear by `amount` if the item is a tool.
-* `add_item(item)`: Put some item or stack onto this stack.
- Returns leftover `ItemStack`.
-* `item_fits(item)`: Returns `true` if item or stack can be fully added to
- this one.
-* `take_item(n=1)`: Take (and remove) up to `n` items from this stack.
- Returns taken `ItemStack`.
-* `peek_item(n=1)`: copy (don't remove) up to `n` items from this stack.
- Returns taken `ItemStack`.
+* `to_string()`: returns the stack in itemstring 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_free_space()`: returns `get_stack_max() - get_count()`.
+* `is_known()`: returns `true` if the item name refers to a defined item type.
+* `get_definition()`: returns the item definition table.
+* `get_tool_capabilities()`: returns the digging properties of the item,
+ or those of the hand if none are defined for this item type
+* `add_wear(amount)`
+ * Increases wear by `amount` if the item is a tool
+ * `amount`: number, integer
+* `add_item(item)`: returns leftover `ItemStack`
+ * Put some item or stack onto this stack
+* `item_fits(item)`: returns `true` if item or stack can be fully added to
+ this one.
+* `take_item(n)`: returns taken `ItemStack`
+ * Take (and remove) up to `n` items from this stack
+ * `n`: number, default: `1`
+* `peek_item(n)`: returns taken `ItemStack`
+ * Copy (don't remove) up to `n` items from this stack
+ * `n`: number, default: `1`
### `PseudoRandom`
A 16-bit pseudorandom number generator.
It can be created via `PerlinNoiseMap(noiseparams, size)` or
`minetest.get_perlin_map(noiseparams, size)`.
-Format of `size` is `{x=dimx, y=dimy, z=dimz}`. The `z` conponent is ommitted
+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
`nil` is returned).
#### Methods
* `get(key)`: returns a value
-* `get_bool(key)`: returns a boolean
+* `get_bool(key, [default])`: returns a boolean
+ * `default` is the value returned if `key` is not found.
+ * Returns `nil` if `key` is not found and `default` not specified.
+* `get_np_group(key)`: returns a NoiseParams table
* `set(key, value)`
* Setting names can't contain whitespace or any of `="{}#`.
* Setting values can't contain the sequence `\n"""`.
* Setting names starting with "secure." can't be set on the main settings object (`minetest.settings`).
* `set_bool(key, value)`
* See documentation for set() above.
+* `set_np_group(key, value)`
+ * `value` is a NoiseParams table.
+ * Also, see documentation for set() above.
* `remove(key)`: returns a boolean (`true` for success)
* `get_names()`: returns `{key1,...}`
* `write()`: returns a boolean (`true` for success)
* `tool_capabilities`: capability table of used tool (can be `nil`)
* `dir`: unit vector of direction of punch. Always defined. Points from
the puncher to the punched.
- `on_death(self, killer)`
+ * `on_death(self, killer)`
* Called when the object dies.
* `killer`: an `ObjectRef` (can be `nil`)
* `on_rightclick(self, clicker)`
-- ^ For players: Defaults to `minetest.PLAYER_MAX_HP_DEFAULT`
breath_max = 0,
-- ^ For players only. Defaults to `minetest.PLAYER_MAX_BREATH_DEFAULT`
+ zoom_fov = 0.0,
+ -- ^ For players only. Zoom FOV in degrees.
+ -- Note that zoom loads and/or generates world beyond the server's maximum
+ -- send and generate distances, so acts like a telescope.
+ -- Smaller zoomFOV values increase the distance loaded and/or generated.
+ -- Defaults to 15 in creative mode, 0 in survival mode.
+ -- zoom_fov = 0 disables zooming for the player.
+ eye_height = 1.625,
+ -- ^ For players only. Camera height above feet position in nodes. Defaults to 1.625
physical = true,
collide_with_objects = true, -- collide with other objects if physical = true
weight = 5,
backface_culling = true, -- false to disable backface_culling for model
glow = 0,
-- ^ Add this much extra lighting when calculating texture color.
- value < 0 disables light's effect on texture color.
- For faking self-lighting, UI style entities, or programmatic coloring in mods.
+ -- Value < 0 disables light's effect on texture color.
+ -- For faking self-lighting, UI style entities, or programmatic coloring in mods.
nametag = "", -- by default empty, for players their name is shown if empty
nametag_color = <color>, -- sets color of nametag as ColorSpec
infotext = "", -- by default empty, text to be shown when pointed at object
+ static_save = true,
+ -- ^ If false, never save this object statically. It will simply be deleted when the
+ -- block gets unloaded.
+ -- The get_staticdata() callback is never called then.
+ -- Defaults to 'true'
}
### Entity definition (`register_entity`)
* `"image.png"`
* `{name="image.png", animation={Tile Animation definition}}`
* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
- tileable_horizontal=bool}`
+ tileable_horizontal=bool, align_style="node"/"world"/"user", scale=int}`
* backface culling enabled by default for most nodes
* tileable flags are info for shaders, how they should treat texture
- when displacement mapping is used
- Directions are from the point of view of the tile texture,
- not the node it's on
+ when displacement mapping is used
+ Directions are from the point of view of the tile texture,
+ not the node it's on
+ * align style determines whether the texture will be rotated with the node
+ or kept aligned with its surroundings. "user" means that client
+ setting will be used, similar to `glasslike_framed_optional`.
+ Note: supported by solid nodes and nodeboxes only.
+ * scale is used to make texture span several (exactly `scale`) nodes,
+ instead of just one, in each direction. Works for world-aligned
+ textures only.
+ Note that as the effect is applied on per-mapblock basis, `16` should
+ be equally divisible by `scale` or you may get wrong results.
* `{name="image.png", color=ColorSpec}`
* the texture's color will be multiplied with this color.
* the tile's color overrides the owning node's color in all cases.
### Tile animation definition
- {
- type = "vertical_frames",
- aspect_w = 16,
- -- ^ specify width of a frame in pixels
- aspect_h = 16,
- -- ^ specify height of a frame in pixels
- length = 3.0,
- -- ^ specify full loop length
- }
-
- {
- type = "sheet_2d",
- frames_w = 5,
- -- ^ specify width in number of frames
- frames_h = 3,
- -- ^ specify height in number of frames
- frame_length = 0.5,
- -- ^ specify length of a single frame
- }
+ {
+ type = "vertical_frames",
+ aspect_w = 16,
+ -- ^ specify width of a frame in pixels
+ aspect_h = 16,
+ -- ^ specify height of a frame in pixels
+ length = 3.0,
+ -- ^ specify full loop length
+ }
+
+ {
+ type = "sheet_2d",
+ frames_w = 5,
+ -- ^ specify width in number of frames
+ frames_h = 3,
+ -- ^ specify height in number of frames
+ frame_length = 0.5,
+ -- ^ specify length of a single frame
+ }
### Node definition (`register_node`)
^ base tiles. You can use this to colorize only specific parts of
^ your texture. If the texture name is an empty string, that
^ overlay is not drawn. Since such tiles are drawn twice, it
- ^ is not recommended to use overlays on very common nodes.
+ ^ is not recommended to use overlays on very common nodes. ]]
special_tiles = {tile definition 1, Tile definition 2}, --[[
^ Special textures of node; used rarely (old field name: special_materials)
^ List can be shortened to needed length ]]
^ interval. Default: nil.
^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]]
+ preserve_metadata = func(pos, oldnode, oldmeta, drops) --[[
+ ^ Called when oldnode is about be converted to an item, but before the
+ node is deleted from the world or the drops are added. This is generally
+ the result of either the node being dug or an attached node becoming detached.
+ ^ drops is a table of ItemStacks, so any metadata to be preserved can be
+ added directly to one or more of the dropped items. See "ItemStackMetaRef".
+ ^ default: nil ]]
after_place_node = func(pos, placer, itemstack, pointed_thing) --[[
^ Called after constructing node when node was placed using
minetest.item_place_node / minetest.place_node
^ If return true no item is taken from itemstack
+ ^ `placer` may be any valid ObjectRef or nil
^ default: nil ]]
after_dig_node = func(pos, oldnode, oldmetadata, digger), --[[
^ oldmetadata is in table format
### Ore definition (`register_ore`)
+ See 'Ore types' section above for essential information.
+
{
- ore_type = "scatter", -- See "Ore types"
+ ore_type = "scatter",
ore = "default:stone_with_coal",
ore_param2 = 3,
-- ^ Facedir rotation. Default is 0 (unchanged rotation)
wherein = "default:stone",
-- ^ a list of nodenames is supported too
- clust_scarcity = 8*8*8,
+ clust_scarcity = 8 * 8 * 8,
-- ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
- -- ^ This value should be *MUCH* higher than your intuition might tell you!
+ -- ^ If the desired average distance between ores is 'd', set this to d * d * d.
clust_num_ores = 8,
-- ^ Number of ores in a cluster
clust_size = 3,
-- ^ Size of the bounding box of the cluster
- -- ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore
+ -- ^ In this example, there is a 3 * 3 * 3 cluster where 8 out of the 27 nodes
+ -- ^ are coal ore.
y_min = -31000,
y_max = 64,
-- ^ Lower and upper limits for ore.
flags = "",
- -- ^ Attributes for this ore generation
+ -- ^ Attributes for this ore generation, see 'Ore attributes' section above.
noise_threshold = 0.5,
- -- ^ If noise is above this threshold, ore is placed. Not needed for a uniform distribution
- noise_params = {offset=0, scale=1, spread={x=100, y=100, z=100}, seed=23, octaves=3, persist=0.70}
- -- ^ NoiseParams structure describing the perlin noise used for ore distribution.
- -- ^ Needed for sheet ore_type. Omit from scatter ore_type for a uniform ore distribution
- random_factor = 1.0,
- -- ^ Multiplier of the randomness contribution to the noise value at any
- -- ^ given point to decide if ore should be placed. Set to 0 for solid veins.
- -- ^ This parameter is only valid for ore_type == "vein".
+ -- ^ If noise is above this threshold, ore is placed. Not needed for a
+ -- ^ uniform distribution.
+ noise_params = {
+ offset = 0,
+ scale = 1,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 23,
+ octaves = 3,
+ persist = 0.7
+ },
+ -- ^ NoiseParams structure describing one of the perlin noises used for ore
+ -- ^ distribution.
+ -- ^ Needed by "sheet", "puff", "blob" and "vein" ores.
+ -- ^ Omit from "scatter" ore for a uniform ore distribution.
+ -- ^ Omit from "stratum ore for a simple horizontal strata from y_min to y_max.
biomes = {"desert", "rainforest"}
- -- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted,
- -- ^ and ignored if the Mapgen being used does not support biomes.
+ -- ^ List of biomes in which this decoration occurs.
+ -- ^ Occurs in all biomes if this is omitted, and ignored if the Mapgen being
+ -- ^ used does not support biomes.
-- ^ Can be a list of (or a single) biome names, IDs, or definitions.
+ column_height_min = 1,
+ column_height_max = 16,
+ column_midpoint_factor = 0.5,
+ -- ^ See 'Ore types' section above.
+ -- ^ The above 3 parameters are only valid for "sheet" ore.
+ np_puff_top = {
+ offset = 4,
+ scale = 2,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 47,
+ octaves = 3,
+ persist = 0.7
+ },
+ np_puff_bottom = {
+ offset = 4,
+ scale = 2,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 11,
+ octaves = 3,
+ persist = 0.7
+ },
+ -- ^ See 'Ore types' section above.
+ -- ^ The above 2 parameters are only valid for "puff" ore.
+ random_factor = 1.0,
+ -- ^ See 'Ore types' section above.
+ -- ^ Only valid for "vein" ore.
+ np_stratum_thickness = {
+ offset = 8,
+ scale = 4,
+ spread = {x = 100, y = 100, z = 100},
+ seed = 17,
+ octaves = 3,
+ persist = 0.7
+ },
+ stratum_thickness = 8,
+ -- ^ See 'Ore types' section above.
+ -- ^ The above 2 parameters are only valid for "stratum" ore.
}
### Biome definition (`register_biome`)
-- ^ diagram to result in roughly equal size biomes.
-- ^ Heat and humidity have average values of 50, vary mostly between
-- ^ 0 and 100 but also often exceed these values.
- -- ^ Heat is not in degrees celcius, both values are abstract.
+ -- ^ Heat is not in degrees Celsius, both values are abstract.
}
### Decoration definition (`register_decoration`)
y_min = -31000
y_max = 31000
-- ^ Lower and upper limits for decoration.
- -- ^ This parameter refers to the `y` position of the decoration base, so
- -- the actual maximum height would be `height_max + size.Y`.
+ -- ^ These parameters refer to the Y co-ordinate of the 'place_on' node.
spawn_by = "default:water",
-- ^ Node (or list of nodes) that the decoration only spawns next to.
-- ^ Checks two horizontal planes of neighbouring nodes (including diagonal neighbours),
- -- ^ one plane at Y = surface and one plane at Y = surface = + 1.
+ -- ^ one plane level with the 'place_on' node and a plane one node above that.
num_spawn_by = 1,
-- ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
-- ^ If absent or -1, decorations occur next to any nodes.
- flags = "liquid_surface, force_placement",
+ flags = "liquid_surface, force_placement, all_floors, all_ceilings",
-- ^ 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.
+ -- ^ 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.
+ -- ^ "all_floors", "all_ceilings": Instead of placement on the highest
+ -- ^ surface in a mapchunk the decoration is placed on all floor and/or
+ -- ^ ceiling surfaces, for example in caves.
+ -- ^ Ceiling decorations act as an inversion of floor decorations so the
+ -- ^ effect of 'place_offset_y' is inverted.
+ -- ^ If a single decoration registration has both flags the floor and
+ -- ^ ceiling decorations will be aligned vertically and may sometimes
+ -- ^ meet to form a column.
----- Simple-type parameters
decoration = "default:grass",
-- ^ The node name used as the decoration.
-- ^ If instead a list of strings, a randomly selected node from the list is placed as the decoration.
height = 1,
- -- ^ Number of nodes high the decoration is made.
- -- ^ If height_max is not 0, this is the lower bound of the randomly selected height.
+ -- ^ Decoration height in nodes.
+ -- ^ If height_max is not 0, this is the lower limit of a randomly selected height.
height_max = 0,
- -- ^ Number of nodes the decoration can be at maximum.
+ -- ^ Upper limit of the randomly selected height.
-- ^ If absent, the parameter 'height' is used as a constant.
param2 = 0,
- -- ^ Param2 value of placed decoration node.
+ -- ^ Param2 value of decoration nodes.
+ -- ^ If param2_max is not 0, this is the lower limit of a randomly selected param2.
+ param2_max = 0,
+ -- ^ Upper limit of the randomly selected param2.
+ -- ^ If absent, the parameter 'param2' is used as a constant.
+ place_offset_y = 0,
+ -- ^ Y offset of the decoration base node relative to the standard base
+ -- ^ node position.
+ -- ^ Can be positive or negative. Default is 0.
+ -- ^ Effect is inverted for "all_ceilings" decorations.
+ -- ^ Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
+ -- ^ to the 'place_on' node.
----- Schematic-type parameters
schematic = "foobar.mts",
rotation = "90" -- rotate schematic 90 degrees on placement
-- ^ Rotation can be "0", "90", "180", "270", or "random".
place_offset_y = 0,
+ -- ^ If the flag 'place_center_y' is set this parameter is ignored.
-- ^ Y offset of the schematic base node layer relative to the 'place_on'
-- ^ node.
-- ^ Can be positive or negative. Default is 0.
- -- ^ If the flag 'place_center_y' is set this parameter is ignored.
- -- ^ If absent or 0 the schematic base node layer will be placed level
- -- ^ with the 'place_on' node.
+ -- ^ Effect is inverted for "all_ceilings" decorations.
+ -- ^ Ignored by 'y_min', 'y_max' and 'spawn_by' checks, which always refer
+ -- ^ to the 'place_on' node.
}
### Chat command definition (`register_chatcommand`)
completed = true,
-- ^ If true, the request has finished (either succeeded, failed or timed out)
succeeded = true,
- -- ^ If true, the request was succesful
+ -- ^ If true, the request was successful
timeout = false,
-- ^ If true, the request timed out
code = 200,
-- ^ HTTP status code
data = "response"
}
+
+### Authentication handler definition
+
+ {
+ get_auth = func(name),
+ -- ^ Get authentication data for existing player `name` (`nil` if player doesn't exist)
+ -- ^ returns following structure `{password=<string>, privileges=<table>, last_login=<number or nil>}`
+ create_auth = func(name, password),
+ -- ^ Create new auth data for player `name`
+ -- ^ Note that `password` is not plain-text but an arbitrary representation decided by the engine
+ delete_auth = func(name),
+ -- ^ Delete auth data of player `name`, returns boolean indicating success (false if player nonexistant)
+ set_password = func(name, password),
+ -- ^ Set password of player `name` to `password`
+ Auth data should be created if not present
+ set_privileges = func(name, privileges),
+ -- ^ Set privileges of player `name`
+ -- ^ `privileges` is in table form, auth data should be created if not present
+ reload = func(),
+ -- ^ Reload authentication data from the storage location
+ -- ^ Returns boolean indicating success
+ record_login = func(name),
+ -- ^ Called when player joins, used for keeping track of last_login
+ iterate = func(),
+ -- ^ Returns an iterator (use with `for` loops) for all player names currently in the auth database
+ }
+
projects / dragonfireclient.git / blobdiff