X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=4e2ec00c30d9827d5e0acad6dd3df4717a7b9d21;hb=0d4d35ab930ecb5b313f74ae430edddd0ee79d4d;hp=182f5c821c2b84e4d9e915b8dc1586650ea45db9;hpb=f21dae63390aa872062bcfc96fc6817b0fcfe601;p=dragonfireclient.git
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 182f5c821..4e2ec00c3 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1,4 +1,4 @@
-Minetest Lua Modding API Reference 0.4.14
+Minetest Lua Modding API Reference 0.4.15
=========================================
* More information at `
+Inverts the given channels of the base image.
+Mode may contain the characters "r", "g", "b", "a".
+Only the channels that are mentioned in the mode string will be inverted.
+
+Example:
+
+ default_apple.png^[invert:rgb
+
#### `[brighten`
Brightens the texture.
@@ -345,7 +370,7 @@ Example:
default_stone.png^[transformFXR90
#### `[inventorycube{{{`
-`^` is replaced by `&` in texture names.
+Escaping does not apply here and `^` is replaced by `&` in texture names instead.
Create an inventory cube texture using the side textures.
@@ -378,6 +403,11 @@ Apply a mask to the base image.
The mask is applied using binary AND.
+#### `[sheet:x:,`
+Retrieves a tile at position x,y from the base image
+which it assumes to be a tilesheet with dimensions w,h.
+
+
#### `[colorize::`
Colorize the textures with the given color.
`` is specified as a `ColorString`.
@@ -389,6 +419,13 @@ the word "`alpha`", then each texture pixel will contain the RGB of
`` and the alpha of `` multiplied by the alpha of the
texture pixel.
+#### `[multiply:`
+Multiplies texture colors with the given color.
+`` is specified as a `ColorString`.
+Result is more like what you'd expect if you put a color on top of another
+color. Meaning white surfaces get a lot of your new color while black parts don't
+change very much.
+
Sounds
------
Only Ogg Vorbis files are supported.
@@ -416,18 +453,26 @@ from the available ones of the following files:
Examples of sound parameter tables:
- -- Play location-less on all clients
+ -- Play locationless on all clients
{
gain = 1.0, -- default
+ fade = 0.0, -- default, change to a value > 0 to fade the sound in
+ }
+ -- Play locationless to one player
+ {
+ to_player = name,
+ gain = 1.0, -- default
+ fade = 0.0, -- default, change to a value > 0 to fade the sound in
}
- -- Play location-less to a player
+ -- Play locationless to one player, looped
{
to_player = name,
gain = 1.0, -- default
+ loop = true,
}
-- Play in a location
{
- pos = {x=1,y=2,z=3},
+ pos = {x = 1, y = 2, z = 3},
gain = 1.0, -- default
max_hear_distance = 32, -- default, uses an euclidean metric
}
@@ -436,15 +481,18 @@ Examples of sound parameter tables:
object = ,
gain = 1.0, -- default
max_hear_distance = 32, -- default, uses an euclidean metric
- loop = true, -- only sounds connected to objects can be looped
+ loop = true,
}
+Looped sounds must either be connected to an object or played locationless to
+one player using `to_player = name,`
+
### `SimpleSoundSpec`
* e.g. `""`
* e.g. `"default_place_node"`
* e.g. `{}`
-* e.g. `{name="default_place_node"}`
-* e.g. `{name="default_place_node", gain=1.0}`
+* e.g. `{name = "default_place_node"}`
+* e.g. `{name = "default_place_node", gain = 1.0}`
Registered definitions of stuff
-------------------------------
@@ -464,6 +512,11 @@ the global `minetest.registered_*` tables.
* `minetest.register_craftitem(name, item definition)`
* added to `minetest.registered_items[name]`
+* `minetest.unregister_item(name)`
+ * Unregisters the item name from engine, and deletes the entry with key
+ * `name` from `minetest.registered_items` and from the associated item
+ * table according to its nature: minetest.registered_nodes[] etc
+
* `minetest.register_biome(biome definition)`
* returns an integer uniquely identifying the registered biome
* added to `minetest.registered_biome` with the key of `biome.name`
@@ -578,6 +631,39 @@ node definition:
^ The rotation of this node is stored in param2. Plants are rotated this way.
Values range 0 - 179. The value stored in param2 is multiplied by two to
get the actual rotation of the node.
+ paramtype2 == "meshoptions"
+ ^ Only valid for "plantlike". The value of param2 becomes a bitfield which can
+ be used to change how the client draws plantlike nodes. Bits 0, 1 and 2 form
+ a mesh selector. Currently the following meshes are choosable:
+ 0 = a "x" shaped plant (ordinary plant)
+ 1 = a "+" shaped plant (just rotated 45 degrees)
+ 2 = a "*" shaped plant with 3 faces instead of 2
+ 3 = a "#" shaped plant with 4 faces instead of 2
+ 4 = a "#" shaped plant with 4 faces that lean outwards
+ 5-7 are unused and reserved for future meshes.
+ Bits 3 through 7 are optional flags that can be combined and give these
+ effects:
+ bit 3 (0x08) - Makes the plant slightly vary placement horizontally
+ bit 4 (0x10) - Makes the plant mesh 1.4x larger
+ bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
+ bits 6-7 are reserved for future use.
+ paramtype2 == "color"
+ ^ `param2` tells which color is picked from the palette.
+ The palette should have 256 pixels.
+ paramtype2 == "colorfacedir"
+ ^ Same as `facedir`, but with colors.
+ The first three bits of `param2` tells which color
+ is picked from the palette.
+ The palette should have 8 pixels.
+ paramtype2 == "colorwallmounted"
+ ^ Same as `wallmounted`, but with colors.
+ The first five bits of `param2` tells which color
+ is picked from the palette.
+ The palette should have 32 pixels.
+ paramtype2 == "glasslikeliquidlevel"
+ ^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes.
+ param2 defines 64 levels of internal liquid.
+ Liquid texture is defined using `special_tiles = {"modname_tilename.png"},`
collision_box = {
type = "fixed",
fixed = {
@@ -1146,10 +1232,9 @@ Another example: Make red wool from white wool and red dye:
from destroyed nodes.
* `0` is something that is directly accessible at the start of gameplay
* There is no upper limit
-* `dig_immediate`: (player can always pick up node without tool wear)
- * `2`: node is removed without tool wear after 0.5 seconds or so
- (rail, sign)
- * `3`: node is removed without tool wear immediately (torch)
+* `dig_immediate`: (player can always pick up node without reducing tool wear)
+ * `2`: the node always gets the digging time 0.5 seconds (rail, sign)
+ * `3`: the node always gets the digging time 0 seconds (torch)
* `disable_jump`: Player (and possibly other things) cannot jump from node
* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
* `bouncy`: value is bounce speed in percent
@@ -1250,6 +1335,10 @@ result in the tool to be able to dig nodes that have a rating of `2` or `3`
for this group, and unable to dig the rating `1`, which is the toughest.
Unless there is a matching group that enables digging otherwise.
+If the result digging time is 0, a delay of 0.15 seconds is added between
+digging nodes; If the player releases LMB after digging, this delay is set to 0,
+i.e. players can more quickly click the nodes away instead of holding LMB.
+
#### Damage groups
List of damage for groups of entities. See "Entity damage mechanism".
@@ -1319,7 +1408,7 @@ a non-tool item, so that it can do something else than take damage.
On the Lua side, every punch calls:
- entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction)
+ entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage)
This should never be called directly, because damage is usually not handled by
the entity itself.
@@ -1330,6 +1419,9 @@ the entity itself.
* `tool_capabilities` can be `nil`.
* `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
+(retval true) or shall be done by engine (retval false)
To punch an entity/object in Lua, call:
@@ -1344,9 +1436,9 @@ Node Metadata
-------------
The instance of a node in the world normally only contains the three values
mentioned in "Nodes". However, it is possible to insert extra data into a
-node. It is called "node metadata"; See "`NodeMetaRef`".
+node. It is called "node metadata"; See `NodeMetaRef`.
-Metadata contains two things:
+Node metadata contains two things:
* A key-value store
* An inventory
@@ -1384,6 +1476,25 @@ Example stuff:
}
})
+Item Metadata
+-------------
+Item stacks can store metadata too. See `ItemStackMetaRef`.
+
+Item metadata only contains a key-value store.
+
+Some of the values in the key-value store are handled specially:
+
+* `description`: Set the itemstack's description. Defaults to idef.description
+* `color`: A `ColorString`, which sets the stack's color.
+* `palette_index`: If the item has a palette, this is used to get the
+ current color from the palette.
+
+Example stuff:
+
+ local meta = stack:get_meta()
+ meta:set_string("key", "value")
+ print(dump(meta:to_table()))
+
Formspec
--------
Formspec defines a menu. Currently not much else than inventories are
@@ -1423,6 +1534,25 @@ examples.
* `fixed_size`: `true`/`false` (optional)
* deprecated: `invsize[,;]`
+#### `position[,]`
+* Define the position of the formspec
+* A value between 0.0 and 1.0 represents a position inside the screen
+* The default value is the center of the screen (0.5, 0.5)
+
+#### `anchor[,]`
+* Define the anchor of the formspec
+* A value between 0.0 and 1.0 represents an anchor inside the formspec
+* The default value is the center of the formspec (0.5, 0.5)
+
+#### `container[,]`
+* Start of a container block, moves all physical elements in the container by (X, Y)
+* Must have matching container_end
+* Containers can be nested, in which case the offsets are added
+ (child containers are relative to parent containers)
+
+#### `container_end[]`
+* End of a container, following elements are no longer relative to this container
+
#### `list[;;,;,;]`
* Show an inventory list
@@ -1456,7 +1586,7 @@ examples.
* Sets default background color of tooltips
* Sets default font color of tooltips
-#### `tooltip[;;,]`
+#### `tooltip[;;;]`
* Adds tooltip for an element
* `` tooltip background color as `ColorString` (optional)
* `` tooltip font color as `ColorString` (optional)
@@ -1489,15 +1619,20 @@ examples.
#### `pwdfield[,;,;;]`
* Textual password style field; will be sent to server when a button is clicked
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+ of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
* Fields are a set height, but will be vertically centred on `h`
* Position and size units are inventory slots
* `name` is the name of the field as returned in fields to `on_receive_fields`
* `label`, if not blank, will be text printed on the top left above the field
+* See field_close_on_enter to stop enter closing the formspec
#### `field[,;,;;;]`
* Textual field; will be sent to server when a button is clicked
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+ of this field.
* `x` and `y` position the field relative to the top left of the menu
* `w` and `h` are the size of the field
* Fields are a set height, but will be vertically centred on `h`
@@ -1508,12 +1643,21 @@ examples.
* `default` may contain variable references such as `${text}'` which
will fill the value from the metadata value `text`
* **Note**: no extra text or more than a single variable is supported ATM.
+* See field_close_on_enter to stop enter closing the formspec
#### `field[;;]`
* As above, but without position/size units
+* When enter is pressed in field, fields.key_enter_field will be sent with the name
+ of this field.
* Special field for creating simple forms, such as sign text input
* Must be used without a `size[]` element
* A "Proceed" button will be added automatically
+* See field_close_on_enter to stop enter closing the formspec
+
+#### `field_close_on_enter[;]`
+* is the name of the field
+* if is false, pressing enter in the field will submit the form but not close it
+* defaults to true when not specified (ie: no tag for a field)
#### `textarea[,;,;;;]`
* Same as fields above, but with multi-line input
@@ -1690,6 +1834,13 @@ Inventory locations
* `"nodemeta:,,"`: Any node metadata
* `"detached:"`: A detached inventory
+Player Inventory lists
+----------------------
+* `main`: list containing the default inventory
+* `craft`: list containing the craft input
+* `craftpreview`: list containing the craft output
+* `hand`: list containing an override for the empty hand
+
`ColorString`
-------------
`#RGB` defines a color in hexadecimal format.
@@ -1721,18 +1872,24 @@ Escape sequences
Most text can contain escape sequences, that can for example color the text.
There are a few exceptions: tab headers, dropdowns and vertical labels can't.
The following functions provide escape sequences:
-* `core.get_color_escape_sequence(color)`:
+* `minetest.get_color_escape_sequence(color)`:
* `color` is a ColorString
* The escape sequence sets the text color to `color`
-* `core.colorize(color, message)`:
+* `minetest.colorize(color, message)`:
* Equivalent to:
- `core.get_color_escape_sequence(color) ..
+ `minetest.get_color_escape_sequence(color) ..
message ..
- core.get_color_escape_sequence("#ffffff")`
+ minetest.get_color_escape_sequence("#ffffff")`
* `color.get_background_escape_sequence(color)`
* `color` is a ColorString
* The escape sequence sets the background of the whole text element to
`color`. Only defined for item descriptions and tooltips.
+* `color.strip_foreground_colors(str)`
+ * Removes foreground colors added by `get_color_escape_sequence`.
+* `color.strip_background_colors(str)`
+ * Removes background colors added by `get_background_escape_sequence`.
+* `color.strip_colors(str)`
+ * Removes all color escape sequences.
Spatial Vectors
---------------
@@ -1743,9 +1900,11 @@ Spatial Vectors
* `vector.distance(p1, p2)`: returns a number
* `vector.length(v)`: returns a number
* `vector.normalize(v)`: returns a vector
-* `vector.round(v)`: returns a vector, each dimension rounded to floor
+* `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
For the following functions `x` can be either a vector or a number:
@@ -1766,8 +1925,7 @@ Helper functions
* `math.sign(x, tolerance)`
* 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)`
+* `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"}`
@@ -1783,11 +1941,13 @@ Helper functions
* `minetest.formspec_escape(string)`: returns a string
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
* `minetest.is_yes(arg)`
- * returns whether `arg` can be interpreted as yes
+ * returns true if passed 'y', 'yes', 'true' or a number that isn't zero.
* `minetest.get_us_time()`
* returns time with microsecond precision. May not return wall time.
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
+* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a position
+ * returns the exact position on the surface of a pointed node
`minetest` namespace reference
------------------------------
@@ -1802,13 +1962,31 @@ Helper functions
* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
* Useful for storing custom data
* `minetest.is_singleplayer()`
-* `minetest.features`
- * Table containing API feature flags: `{foo=true, bar=true}`
+* `minetest.features`: Table containing API feature flags
+ {
+ glasslike_framed = true,
+ nodebox_as_selectionbox = true,
+ chat_send_player_param3 = true,
+ get_all_craft_recipes_works = true,
+ use_texture_alpha = true,
+ -- ^ The transparency channel of textures can be used optionally
+ no_legacy_abms = true,
+ -- ^ Tree and grass ABMs are no longer done from C++
+ texture_names_parens = true,
+ -- ^ Texture grouping is possible using parentheses
+ area_store_custom_ids = true,
+ -- ^ Unique Area ID for AreaStore:insert_area
+ add_entity_with_staticdata = true,
+ -- ^ add_entity supports passing initial staticdata to on_activate
+ no_chat_message_prediction = true,
+ -- ^ Chat messages are no longer predicted
+ }
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
* `arg`: string or table in format `{foo=true, bar=true}`
* `missing_features`: `{foo=true, bar=true}`
-* `minetest.get_player_information(player_name)`: returns a table containing
- information about player. Example return value:
+* `minetest.get_player_information(player_name)`:
+ * Returns a table containing information about a player
+ Example return value:
{
address = "127.0.0.1", -- IP address of client
ip_version = 4, -- IPv4 / IPv6
@@ -1819,11 +1997,11 @@ Helper functions
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
-- following information is available on debug build only!!!
-- DO NOT USE IN MODS
--ser_vers = 26, -- serialization version used by client
- --prot_vers = 23, -- protocol version used by client
--major = 0, -- major version number
--minor = 4, -- minor version number
--patch = 10, -- patch version number
@@ -1838,6 +2016,17 @@ Helper functions
* nil: return all entries,
* true: return only subdirectory names, or
* false: return only file names.
+* `minetest.get_version()`: returns a table containing components of the
+ engine version. Components:
+ * `project`: Name of the project, eg, "Minetest"
+ * `string`: Simple version, eg, "1.2.3-dev"
+ * `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
+ version entirely. To check for the presence of engine features, test
+ whether the functions exported by the wanted features exist. For example:
+ `if minetest.nodeupdate then ... end`.
### Logging
* `minetest.debug(...)`
@@ -1855,7 +2044,9 @@ Call these functions only at load time!
* `minetest.register_node(name, node definition)`
* `minetest.register_tool(name, item definition)`
* `minetest.register_craftitem(name, item definition)`
+* `minetest.unregister_item(name)`
* `minetest.register_alias(name, convert_to)`
+* `minetest.register_alias_force(name, convert_to)`
* `minetest.register_craft(recipe)`
* Check recipe table syntax for different types below.
* `minetest.clear_craft(recipe)`
@@ -1866,13 +2057,14 @@ Call these functions only at load time!
* Warning! The type field ("shaped","cooking" or any other) will be ignored if the recipe
contains output. Erasing is then done independently from the crafting method.
* `minetest.register_ore(ore definition)`
+* `minetest.register_biome(biome definition)`
* `minetest.register_decoration(decoration definition)`
* `minetest.override_item(name, redefinition)`
* Overrides fields of an item registered with register_node/tool/craftitem.
* Note: Item must already be defined, (opt)depend on the mod defining it.
* Example: `minetest.override_item("default:mese", {light_source=LIGHT_MAX})`
-
* `minetest.clear_registered_ores()`
+* `minetest.clear_registered_biomes()`
* `minetest.clear_registered_decorations()`
### Global callback registration functions
@@ -1936,9 +2128,10 @@ Call these functions only at load time!
* `minetest.register_on_cheat(func(ObjectRef, cheat))`
* Called when a player cheats
* `cheat`: `{type=}`, where `` is one of:
- * `"moved_too_fast"`
- * `"interacted_too_far"`
- * `"finished_unknown_dig"`
+ * `moved_too_fast`
+ * `interacted_too_far`
+ * `interacted_while_dead`
+ * `finished_unknown_dig`
* `dug_unbreakable`
* `dug_too_fast`
* `minetest.register_on_chat_message(func(name, message))`
@@ -1970,6 +2163,11 @@ Call these functions only at load time!
### Other registration functions
* `minetest.register_chatcommand(cmd, chatcommand definition)`
+ * Adds definition to minetest.registered_chatcommands
+* `minetest.override_chatcommand(name, redefinition)`
+ * Overrides fields of a chatcommand registered with register_chatcommand.
+* `minetest.unregister_chatcommand(name)`
+ * Unregisters a chatcommands registered with register_chatcommand.
* `minetest.register_privilege(name, definition)`
* `definition`: `"description text"`
* `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
@@ -1979,16 +2177,10 @@ Call these functions only at load time!
* See `minetest.builtin_auth_handler` in `builtin.lua` for reference
### Setting-related
-* `minetest.setting_set(name, 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.
-* `minetest.setting_get(name)`: returns string or `nil`
-* `minetest.setting_setbool(name, value)`
- * See documentation on `setting_set` for restrictions.
-* `minetest.setting_getbool(name)`: returns boolean or `nil`
-* `minetest.setting_get_pos(name)`: returns position or nil
-* `minetest.setting_save()`, returns `nil`, save all settings to config file
+* `minetest.settings`: Settings object containing all of the settings from the
+ main config file (`minetest.conf`).
+* `minetest.setting_get_pos(name)`: Loads a setting from the main settings and
+ parses it as a position (in the format `(1,2,3)`). Returns a position or nil.
### Authentication
* `minetest.notify_authentication_modified(name)`
@@ -2034,7 +2226,7 @@ and `minetest.auth_reload` call the authetification handler.
* `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.swap_node(pos, node`
+* `minetest.swap_node(pos, node)`
* Set node at position, but don't remove metadata
* `minetest.remove_node(pos)`
* Equivalent to `set_node(pos, "air")`
@@ -2058,6 +2250,9 @@ and `minetest.auth_reload` call the authetification handler.
* Returns `true` if successful, `false` on failure (e.g. protected location)
* `minetest.punch_node(pos)`
* Punch node with the same effects that a player would cause
+* `minetest.spawn_falling_node(pos)`
+ * Change node into falling node
+ * Returns `true` if successful, `false` on failure
* `minetest.find_nodes_with_meta(pos1, pos2)`
* Get a table of positions of nodes that have metadata within a region {pos1, pos2}
@@ -2066,7 +2261,7 @@ and `minetest.auth_reload` call the authetification handler.
* `minetest.get_node_timer(pos)`
* Get `NodeTimerRef`
-* `minetest.add_entity(pos, name)`: Spawn Lua-defined entity at position
+* `minetest.add_entity(pos, name, [staticdata])`: Spawn Lua-defined entity at position
* Returns `ObjectRef`, or `nil` if failed
* `minetest.add_item(pos, item)`: Spawn item
* Returns `ObjectRef`, or `nil` if failed
@@ -2079,9 +2274,11 @@ and `minetest.auth_reload` call the authetification handler.
* `minetest.get_gametime()`: returns the time, in seconds, since the world was created
* `minetest.get_day_count()`: returns number days elapsed since world was created,
* accounting for time changes.
-* `minetest.find_node_near(pos, radius, nodenames)`: returns pos or `nil`
+* `minetest.find_node_near(pos, radius, nodenames, [search_center])`: returns pos or `nil`
* `radius`: using a maximum metric
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
+ * `search_center` is an optional boolean (default: `false`)
+ If true `pos` is also checked for the nodes
* `minetest.find_nodes_in_area(minp, maxp, nodenames)`: returns a list of positions
* returns as second value a table with the count of the individual nodes found
* `nodenames`: e.g. `{"ignore", "group:tree"}` or `"default:dirt"`
@@ -2129,13 +2326,14 @@ and `minetest.auth_reload` call the authetification handler.
* `minetest.get_mapgen_setting_noiseparams(name)`
* Same as above, but returns the value as a NoiseParams table if the setting `name` exists
and is a valid NoiseParams
-* `minetest.set_mapgen_setting(name, value, [override_meta=false])`
+* `minetest.set_mapgen_setting(name, value, [override_meta])`
* Sets a mapgen param to `value`, and will take effect if the corresponding mapgen setting
- is not already present in map_meta.txt. If the optional boolean override_meta is set to true,
- this setting will become the active setting regardless of the map metafile contents.
+ is not already present in map_meta.txt.
+ * `override_meta` is an optional boolean (default: `false`). If this is set to true,
+ the setting will become the active setting regardless of the map metafile contents.
* Note: to set the seed, use "seed", not "fixed_map_seed"
-* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta=false])`
- * Same as above, except value is a NoiseParams table
+* `minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])`
+ * Same as above, except value is a NoiseParams table.
* `minetest.set_noiseparams(name, noiseparams, set_default)`
* Sets the noiseparams setting of `name` to the noiseparams table specified in `noiseparams`.
* `set_default` is an optional boolean (default: `true`) that specifies whether the setting
@@ -2161,8 +2359,8 @@ and `minetest.auth_reload` call the authetification handler.
* `function EmergeAreaCallback(blockpos, action, calls_remaining, param)`
* - `blockpos` is the *block* coordinates of the block that had been emerged
* - `action` could be one of the following constant values:
- * `core.EMERGE_CANCELLED`, `core.EMERGE_ERRORED`, `core.EMERGE_FROM_MEMORY`,
- * `core.EMERGE_FROM_DISK`, `core.EMERGE_GENERATED`
+ * `minetest.EMERGE_CANCELLED`, `minetest.EMERGE_ERRORED`, `minetest.EMERGE_FROM_MEMORY`,
+ * `minetest.EMERGE_FROM_DISK`, `minetest.EMERGE_GENERATED`
* - `calls_remaining` is the number of callbacks to be expected after this one
* - `param` is the user-defined parameter passed to emerge_area (or nil if the
* parameter was absent)
@@ -2201,6 +2399,31 @@ and `minetest.auth_reload` call the authetification handler.
* increase level of leveled node by level, default `level` equals `1`
* if `totallevel > maxlevel`, returns rest (`total-max`)
* can be negative for decreasing
+* `minetest.fix_light(pos1, pos2)`: returns `true`/`false`
+ * resets the light in a cuboid-shaped part of
+ the map and removes lighting bugs.
+ * Loads the area if it is not loaded.
+ * `pos1` is the corner of the cuboid with the least coordinates
+ (in node coordinates), inclusive.
+ * `pos2` is the opposite corner of the cuboid, inclusive.
+ * The actual updated cuboid might be larger than the specified one,
+ because only whole map blocks can be updated.
+ The actual updated area consists of those map blocks that intersect
+ with the given cuboid.
+ * However, the neighborhood of the updated area might change
+ as well, as light can spread out of the cuboid, also light
+ might be removed.
+ * returns `false` if the area is not fully generated,
+ `true` otherwise
+* `minetest.check_single_for_falling(pos)`
+ * causes an unsupported `group:falling_node` node to fall and causes an
+ unattached `group:attached_node` node to fall.
+ * does not spread these updates to neighbours.
+* `minetest.check_for_falling(pos)`
+ * causes an unsupported `group:falling_node` node to fall and causes an
+ unattached `group:attached_node` node to fall.
+ * spread these updates to neighbours and can cause a cascade
+ of nodes to fall.
### Inventory
`minetest.get_inventory(location)`: returns an `InvRef`
@@ -2209,8 +2432,11 @@ and `minetest.auth_reload` call the authetification handler.
* `{type="player", name="celeron55"}`
* `{type="node", pos={x=, y=, z=}}`
* `{type="detached", name="creative"}`
-* `minetest.create_detached_inventory(name, callbacks)`: returns an `InvRef`
+* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef`
* callbacks: See "Detached inventory callbacks"
+ * player_name: Make detached inventory available to one player exclusively,
+ by default they will be sent to every player (even if not used).
+ Note that this parameter is mostly just a workaround and will be removed in future releases.
* Creates a detached inventory. If it already exists, it is cleared.
* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
returns left over ItemStack
@@ -2222,6 +2448,13 @@ and `minetest.auth_reload` call the authetification handler.
* `formname`: name passed to `on_player_receive_fields` callbacks.
It should follow the `"modname:"` naming convention
* `formspec`: formspec to display
+* `minetest.close_formspec(playername, formname)`
+ * `playername`: name of player to close formspec
+ * `formname`: has to exactly match the one given in show_formspec, or the formspec will
+ not close.
+ * calling show_formspec(playername, formname, "") is equal to this expression
+ * to close a formspec regardless of the formname, call
+ minetest.close_formspec(playername, ""). USE THIS ONLY WHEN ABSOLUTELY NECESSARY!
* `minetest.formspec_escape(string)`: returns a string
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
* `minetest.explode_table_event(string)`: returns a table
@@ -2258,6 +2491,10 @@ and `minetest.auth_reload` call the authetification handler.
* Convert a vector to a wallmounted value, used for `paramtype2="wallmounted"`
* `minetest.wallmounted_to_dir(wallmounted)`
* Convert a wallmounted value back into a vector aimed directly out the "back" of a node
+* `minetest.dir_to_yaw(dir)`
+ * Convert a vector into a yaw (angle)
+* `minetest.yaw_to_dir(yaw)`
+ * Convert yaw (angle) to a vector
* `minetest.get_node_drops(nodename, toolname)`
* Returns list of item names.
* **Note**: This will be removed or modified in a future version.
@@ -2348,6 +2585,11 @@ These functions return the leftover itemstack.
* `spec` is a `SimpleSoundSpec`
* `parameters` is a sound parameter table
* `minetest.sound_stop(handle)`
+* `minetest.sound_fade(handle, step, gain)`
+ * `handle` is a handle returned by minetest.sound_play
+ * `step` determines how fast a sound will fade.
+ Negative step will lower the sound volume, positive step will increase the sound volume
+ * `gain` the target gain for the fade.
### Timing
* `minetest.after(time, func, ...)`
@@ -2355,9 +2597,16 @@ These functions return the leftover itemstack.
* Optional: Variable number of arguments that are passed to `func`
### Server
-* `minetest.request_shutdown([message],[reconnect])`: request for server shutdown. Will display `message` to clients,
- and `reconnect` == true displays a reconnect button.
+* `minetest.request_shutdown([message],[reconnect],[delay])`: request for server shutdown. Will display `message` to clients,
+ `reconnect` == true displays a reconnect button,
+ `delay` adds an optional delay (in seconds) before shutdown
+ negative delay cancels the current active shutdown
+ zero delay triggers an immediate shutdown.
+* `minetest.cancel_shutdown_requests()`: cancel current delayed shutdown
* `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).
+ * Returns a code (0: successful, 1: no such player, 2: player is connected)
### Bans
* `minetest.get_ban_list()`: returns the ban list (same as `minetest.get_ban_description("")`)
@@ -2453,8 +2702,18 @@ These functions return the leftover itemstack.
* `HTTPApiTable.fetch_async_get(handle)`: returns HTTPRequestResult
* Return response data for given asynchronous HTTP request
+### Storage API:
+* `minetest.get_mod_storage()`:
+ * returns reference to mod private `StorageRef`
+ * must be called during mod load time
+
### Misc.
* `minetest.get_connected_players()`: returns list of `ObjectRefs`
+* `minetest.player_exists(name)`: boolean, whether player exists (regardless of online status)
+* `minetest.hud_replace_builtin(name, hud_definition)`
+ * Replaces definition of a builtin hud element
+ * `name`: `"breath"` or `"health"`
+ * `hud_definition`: definition to replace builtin definition
* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
* Gives a unique hash number for a node position (16+16+16=48bit)
* `minetest.get_position_from_hash(hash)`: returns a position
@@ -2480,7 +2739,7 @@ These functions return the leftover itemstack.
* `minetest.write_json(data[, styled])`: returns a string or `nil` and an error message
* Convert a Lua table into a JSON string
* styled: Outputs in a human-readable format if this is set, defaults to false
- * Unserializable things like functions and userdata are saved as null.
+ * Unserializable things like functions and userdata will cause an error.
* **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.
2. You can not mix string and integer keys.
@@ -2553,13 +2812,17 @@ These functions return the leftover itemstack.
the creative mode setting, and checks for "sneak" to set the `invert_wall`
parameter.
-* `minetest.forceload_block(pos)`
+* `minetest.forceload_block(pos[, transient])`
* forceloads the position `pos`.
* returns `true` if area could be forceloaded
- * Please note that forceloaded areas are saved when the server restarts.
+ * If `transient` is `false` or absent, the forceload will be persistent
+ (saved between server runs). If `true`, the forceload will be transient
+ (not saved between server runs).
-* `minetest.forceload_free_block(pos)`
+* `minetest.forceload_free_block(pos[, transient])`
* stops forceloading the position `pos`
+ * If `transient` is `false` or absent, frees a persistent forceload.
+ If `true`, frees a transient forceload.
* `minetest.request_insecure_environment()`: returns an environment containing
insecure functions if the calling mod has been listed as trusted in the
@@ -2593,6 +2856,8 @@ These functions return the leftover itemstack.
* Map of object references, indexed by active object id
* `minetest.luaentities`
* Map of Lua entities, indexed by active object id
+* `minetest.registered_chatcommands`
+ * Map of registered chat command definitions, indexed by name
* `minetest.registered_ores`
* List of registered ore definitions.
* `minetest.registered_biomes`
@@ -2603,9 +2868,8 @@ These functions return the leftover itemstack.
Class reference
---------------
-### `NodeMetaRef`
-Node metadata: reference extra data and functionality stored in a node.
-Can be gotten via `minetest.get_meta(pos)`.
+### `MetaDataRef`
+See `StorageRef`, `NodeMetaRef` and `ItemStackMetaRef`.
#### Methods
* `set_string(name, value)`
@@ -2614,11 +2878,41 @@ Can be gotten via `minetest.get_meta(pos)`.
* `get_int(name)`
* `set_float(name, value)`
* `get_float(name)`
-* `get_inventory()`: returns `InvRef`
-* `to_table()`: returns `nil` or `{fields = {...}, inventory = {list1 = {}, ...}}`
+* `to_table()`: returns `nil` or a table with keys:
+ * `fields`: key-value storage
+ * `inventory`: `{list1 = {}, ...}}` (NodeMetaRef only)
* `from_table(nil or {})`
- * to clear metadata, use from_table(nil)
- * See "Node Metadata"
+ * Any non-table value will clear the metadata
+ * See "Node Metadata" for an example
+ * returns `true` on success
+* `equals(other)`
+ * returns `true` if this metadata has the same key-value pairs as `other`
+
+### `NodeMetaRef`
+Node metadata: reference extra data and functionality stored in a node.
+Can be obtained via `minetest.get_meta(pos)`.
+
+#### Methods
+* All methods in MetaDataRef
+* `get_inventory()`: returns `InvRef`
+* `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"
+ status will only be remembered if an associated key-value pair exists, meaning
+ it's best to call this when initializing all other meta (e.g. on_construct).
+
+### `ItemStackMetaRef`
+ItemStack metadata: reference extra data and functionality stored in a stack.
+Can be obtained via `item:get_meta()`.
+
+#### Methods
+* All methods in MetaDataRef
+
+### `StorageRef`
+Mod metadata: per mod metadata, saved automatically.
+Can be obtained via `minetest.get_mod_storage()` during load time.
+
+#### Methods
+* All methods in MetaDataRef
### `NodeTimerRef`
Node Timers: a high resolution persistent per-node timer.
@@ -2650,9 +2944,9 @@ This is basically a reference to a C++ `ServerActiveObject`
#### Methods
* `remove()`: remove object (after returning from Lua)
* Note: Doesn't work on players, use minetest.kick_player instead
-* `getpos()`: returns `{x=num, y=num, z=num}`
-* `setpos(pos)`; `pos`=`{x=num, y=num, z=num}`
-* `moveto(pos, continuous=false)`: interpolated move
+* `get_pos()`: returns `{x=num, y=num, z=num}`
+* `set_pos(pos)`; `pos`=`{x=num, y=num, z=num}`
+* `move_to(pos, continuous=false)`: interpolated move
* `punch(puncher, time_from_last_punch, tool_capabilities, direction)`
* `puncher` = another `ObjectRef`,
* `time_from_last_punch` = time since last punch action of the puncher
@@ -2698,14 +2992,15 @@ This is basically a reference to a C++ `ServerActiveObject`
}
##### LuaEntitySAO-only (no-op for other objects)
-* `setvelocity({x=num, y=num, z=num})`
-* `getvelocity()`: returns `{x=num, y=num, z=num}`
-* `setacceleration({x=num, y=num, z=num})`
-* `getacceleration()`: returns `{x=num, y=num, z=num}`
-* `setyaw(radians)`
-* `getyaw()`: returns number in radians
-* `settexturemod(mod)`
-* `setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
+* `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_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
@@ -2737,6 +3032,10 @@ This is basically a reference to a C++ `ServerActiveObject`
* `0`: player is drowning,
* `1`-`10`: remaining number of bubbles
* `11`: bubbles bar is not shown
+* `set_attribute(attribute, value)`:
+ * Sets an extra attribute with value on player.
+ * If value is nil, remove attribute from player.
+* `get_attribute(attribute)`: returns value for extra attribute. Returns nil if no attribute found.
* `set_inventory_formspec(formspec)`
* Redefine player's inventory form
* Should usually be called in on_joinplayer
@@ -2751,7 +3050,11 @@ This is basically a reference to a C++ `ServerActiveObject`
* `jump`: multiplier to default jump value (default: `1`)
* `gravity`: multiplier to default gravity value (default: `1`)
* `sneak`: whether player can sneak (default: `true`)
- * `sneak_glitch`: whether player can use the sneak glitch (default: `true`)
+ * `sneak_glitch`: whether player can use the new move code replications
+ of the old sneak side-effects: sneak ladders and 2 node sneak jump
+ (default: `false`)
+ * `new_move`: use new move/sneak code. When `false` the exact old code
+ is used for the specific old sneak behaviour (default: `true`)
* `get_physics_override()`: returns the table given to set_physics_override
* `hud_add(hud definition)`: add a HUD element described by HUD def, returns ID
number on success
@@ -2776,17 +3079,24 @@ This is basically a reference to a C++ `ServerActiveObject`
* `hud_set_hotbar_selected_image(texturename)`
* sets image for selected item of hotbar
* `hud_get_hotbar_selected_image`: returns texturename
-* `hud_replace_builtin(name, hud_definition)`
- * replace definition of a builtin hud element
- * `name`: `"breath"` or `"health"`
- * `hud_definition`: definition to replace builtin definition
-* `set_sky(bgcolor, type, {texture names})`
+* `set_sky(bgcolor, type, {texture names}, clouds)`
* `bgcolor`: ColorSpec, defaults to white
- * Available types:
+ * `type`: Available types:
* `"regular"`: Uses 0 textures, `bgcolor` ignored
* `"skybox"`: Uses 6 textures, `bgcolor` used
* `"plain"`: Uses 0 textures, `bgcolor` used
-* `get_sky()`: returns bgcolor, type and a table with the textures
+ * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or
+ `"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 (default `#fff0f0e5`)
+ * `ambient`: cloud color lower bound, use for a "glow at night" effect (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, y=-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
@@ -2845,6 +3155,7 @@ chosen for you.
#### Methods
* `get_area(id, include_borders, include_data)`: returns the area with the id `id`.
(optional) Boolean values `include_borders` and `include_data` control what's copied.
+ Returns nil if specified area id does not exist.
* `get_areas_for_pos(pos, include_borders, include_data)`: returns all areas that contain
the position `pos`. (optional) Boolean values `include_borders` and `include_data` control
what's copied.
@@ -2884,15 +3195,14 @@ 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 success.
- Clears item on failure.
+* `set_name(item_name)`: Returns boolean whether item was cleared
* `get_count()`: Returns number of items on the stack.
-* `set_count(count)`
+* `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 success.
- Clears item on failure.
-* `get_metadata()`: Returns metadata (a string attached to an item stack).
-* `set_metadata(metadata)`: Returns true.
+* `set_wear(wear)`: Returns boolean whether item was cleared
+* `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.
@@ -3055,9 +3365,6 @@ format as produced by get_data() et al. and is *not required* to be a table retr
Once the internal VoxelManip state has been modified to your liking, the changes can be committed back
to the map by calling `VoxelManip:write_to_map()`.
-Finally, a call to `VoxelManip:update_map()` is required to re-calculate lighting and set the blocks
-as being modified so that connected clients are sent the updated parts of map.
-
##### Flat array format
Let
@@ -3101,9 +3408,9 @@ Note that the node being queried needs to have already been been registered.
The following builtin node types have their Content IDs defined as constants:
```
-core.CONTENT_UNKNOWN (ID for "unknown" nodes)
-core.CONTENT_AIR (ID for "air" nodes)
-core.CONTENT_IGNORE (ID for "ignore" nodes)
+minetest.CONTENT_UNKNOWN (ID for "unknown" nodes)
+minetest.CONTENT_AIR (ID for "air" nodes)
+minetest.CONTENT_IGNORE (ID for "ignore" nodes)
```
##### Mapgen VoxelManip objects
@@ -3122,8 +3429,6 @@ but with a few differences:
will also update the Mapgen VoxelManip object's internal state active on the current thread.
* After modifying the Mapgen VoxelManip object's internal buffer, it may be necessary to update lighting
information using either: `VoxelManip:calc_lighting()` or `VoxelManip:set_lighting()`.
-* `VoxelManip:update_map()` does not need to be called after `write_to_map()`. The map update is performed
- automatically after all on_generated callbacks have been run for that generated block.
##### Other API functions operating on a VoxelManip
If any VoxelManip contents were set to a liquid node, `VoxelManip:update_liquids()` must be called
@@ -3157,8 +3462,14 @@ will place the schematic inside of the VoxelManip.
* `read_from_map(p1, p2)`: Loads a chunk of map into the VoxelManip object containing
the region formed by `p1` and `p2`.
* returns actual emerged `pmin`, actual emerged `pmax`
-* `write_to_map()`: Writes the data loaded from the `VoxelManip` back to the map.
+* `write_to_map([light])`: Writes the data loaded from the `VoxelManip` back to the map.
* **important**: data must be set using `VoxelManip:set_data()` before calling this
+ * if `light` is true, then lighting is automatically recalculated.
+ The default value is true.
+ If `light` is false, no light calculations happen, and you should correct
+ all modified blocks with `minetest.fix_light()` as soon as possible.
+ Keep in mind that modifying the map where light is incorrect can cause
+ more lighting bugs.
* `get_node_at(pos)`: Returns a `MapNode` table of the node currently loaded in
the `VoxelManip` at that position
* `set_node_at(pos, node)`: Sets a specific `MapNode` in the `VoxelManip` at that position
@@ -3166,9 +3477,7 @@ will place the schematic inside of the VoxelManip.
* returns raw node data in the form of an array of node content IDs
* if the param `buffer` is present, this table will be used to store the result instead
* `set_data(data)`: Sets the data contents of the `VoxelManip` object
-* `update_map()`: Update map after writing chunk back to map.
- * To be used only by `VoxelManip` objects created by the mod itself;
- not a `VoxelManip` that was retrieved from `minetest.get_mapgen_object`
+* `update_map()`: Does nothing, kept for compatibility.
* `set_lighting(light, [p1, p2])`: Set the lighting within the `VoxelManip` to a uniform value
* `light` is a table, `{day=<0...15>, night=<0...15>}`
* To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
@@ -3181,7 +3490,9 @@ will place the schematic inside of the VoxelManip.
* `set_light_data(light_data)`: Sets the `param1` (light) contents of each node
in the `VoxelManip`
* expects lighting data in the same format that `get_light_data()` returns
-* `get_param2_data()`: Gets the raw `param2` data read into the `VoxelManip` object
+* `get_param2_data([buffer])`: Gets the raw `param2` data read into the `VoxelManip` object
+ * Returns an array (indices 1 to volume) of integers ranging from `0` to `255`
+ * If the param `buffer` is present, this table will be used to store the result instead
* `set_param2_data(param2_data)`: Sets the `param2` contents of each node in the `VoxelManip`
* `calc_lighting([p1, p2], [propagate_shadow])`: Calculate lighting within the `VoxelManip`
* To be used only by a `VoxelManip` object from `minetest.get_mapgen_object`
@@ -3225,10 +3536,15 @@ It can be created via `Settings(filename)`.
* `get(key)`: returns a value
* `get_bool(key)`: returns a boolean
* `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.
* `remove(key)`: returns a boolean (`true` for success)
* `get_names()`: returns `{key1,...}`
* `write()`: returns a boolean (`true` for success)
- * write changes to file
+ * Writes changes to file.
* `to_table()`: returns `{[key1]=value1,...}`
Mapgen objects
@@ -3287,13 +3603,15 @@ Registered entities
* It has the member `.object`, which is an `ObjectRef` pointing to the object
* The original prototype stuff is visible directly via a metatable
* Callbacks:
- * `on_activate(self, staticdata)`
+ * `on_activate(self, staticdata, dtime_s)`
* Called when the object is instantiated.
+ * `dtime_s` is the time passed since the object was unloaded, which can
+ be used for updating the entity state.
* `on_step(self, dtime)`
* Called on every server tick, after movement and collision processing.
`dtime` is usually 0.1 seconds, as per the `dedicated_server_step` setting
`in minetest.conf`.
- * `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir`
+ * `on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)`
* Called when somebody punches the object.
* Note that you probably want to handle most punches using the
automatic armor group system.
@@ -3388,24 +3706,26 @@ Definition tables
{
hp_max = 1,
physical = true,
- collide_with_objects = true, -- collide with other objects if physical=true
+ collide_with_objects = true, -- collide with other objects if physical = true
weight = 5,
- collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
- visual = "cube"/"sprite"/"upright_sprite"/"mesh"/"wielditem",
- visual_size = {x=1, y=1},
+ collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
+ visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem",
+ visual_size = {x = 1, y = 1},
mesh = "model",
textures = {}, -- number of required textures depends on visual
colors = {}, -- number of required colors depends on visual
- spritediv = {x=1, y=1},
- initial_sprite_basepos = {x=0, y=0},
+ spritediv = {x = 1, y = 1},
+ initial_sprite_basepos = {x = 0, y = 0},
is_visible = true,
makes_footstep_sound = false,
automatic_rotate = false,
stepheight = 0,
automatic_face_movement_dir = 0.0,
- -- ^ automatically set yaw to movement direction; offset in degrees; false to disable
+ -- ^ Automatically set yaw to movement direction, offset in degrees,
+ -- 'false' to disable.
automatic_face_movement_max_rotation_per_sec = -1,
- -- ^ limit automatic rotation to this value in degrees per second. values < 0 no limit
+ -- ^ Limit automatic rotation to this value in degrees per second,
+ -- value < 0 no limit.
backface_culling = true, -- false to disable backface_culling for model
nametag = "", -- by default empty, for players their name is shown if empty
nametag_color = , -- sets color of nametag as ColorSpec
@@ -3421,14 +3741,15 @@ Definition tables
on_activate = function(self, staticdata, dtime_s),
on_step = function(self, dtime),
- on_punch = function(self, hitter),
+ on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
on_rightclick = function(self, clicker),
get_staticdata = function(self),
-- ^ Called sometimes; the string returned is passed to on_activate when
-- the entity is re-activated from static state
- -- Also you can define arbitrary member variables here
- myvariable = whatever,
+ -- Also you can define arbitrary member variables here (see item definition for
+ -- more info)
+ _custom_field = whatever,
}
### ABM (ActiveBlockModifier) definition (`register_abm`)
@@ -3472,27 +3793,39 @@ Definition tables
{
description = "Steel Axe",
- groups = {}, -- key=name, value=rating; rating=1..3.
+ groups = {}, -- key = name, value = rating; rating = 1..3.
if rating not applicable, use 1.
- e.g. {wool=1, fluffy=3}
- {soil=2, outerspace=1, crumbly=1}
- {bendy=2, snappy=1},
- {hard=1, metal=1, spikes=1}
+ e.g. {wool = 1, fluffy = 3}
+ {soil = 2, outerspace = 1, crumbly = 1}
+ {bendy = 2, snappy = 1},
+ {hard = 1, metal = 1, spikes = 1}
inventory_image = "default_tool_steelaxe.png",
wield_image = "",
- wield_scale = {x=1,y=1,z=1},
+ palette = "",
+ --[[
+ ^ An image file containing the palette of a node.
+ ^ You can set the currently used color as the
+ ^ "palette_index" field of the item stack metadata.
+ ^ The palette is always stretched to fit indices
+ ^ between 0 and 255, to ensure compatibility with
+ ^ "colorfacedir" and "colorwallmounted" nodes.
+ ]]
+ color = "0xFFFFFFFF",
+ --[[
+ ^ The color of the item. The palette overrides this.
+ ]]
+ wield_scale = {x = 1, y = 1, z = 1},
stack_max = 99,
range = 4.0,
liquids_pointable = false,
tool_capabilities = {
full_punch_interval = 1.0,
- max_drop_level=0,
- groupcaps={
+ max_drop_level = 0,
+ groupcaps = {
-- For example:
- snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
- choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
+ choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, uses = 20, maxlevel = 2},
},
- damage_groups = {groupname=damage},
+ damage_groups = {groupname = damage},
},
node_placement_prediction = nil,
--[[
@@ -3504,21 +3837,25 @@ Definition tables
actual result to client in a short moment.
]]
sound = {
+ breaks = "default_tool_break", -- tools only
place = --[[]],
},
on_place = func(itemstack, placer, pointed_thing),
--[[
^ Shall place item and return the leftover itemstack
+ ^ The placer may be any ObjectRef or nil.
^ default: minetest.item_place ]]
on_secondary_use = func(itemstack, user, pointed_thing),
--[[
^ Same as on_place but called when pointing at nothing.
+ ^ The user may be any ObjectRef or nil.
^ pointed_thing : always { type = "nothing" }
]]
on_drop = func(itemstack, dropper, pos),
--[[
^ Shall drop item and return the leftover itemstack
+ ^ The dropper may be any ObjectRef or nil.
^ default: minetest.item_drop ]]
on_use = func(itemstack, user, pointed_thing),
--[[
@@ -3527,6 +3864,7 @@ Definition tables
inventory, or an itemstack to replace the original itemstack.
e.g. itemstack:take_item(); return itemstack
^ Otherwise, the function is free to do what it wants.
+ ^ The user may be any ObjectRef or nil.
^ The default functions handle regular use cases.
]]
after_use = func(itemstack, user, node, digparams),
@@ -3539,6 +3877,13 @@ Definition tables
itemstack:add_wear(digparams.wear)
return itemstack
end
+ ^ The user may be any ObjectRef or nil.
+ ]]
+ _custom_field = whatever,
+ --[[
+ ^ Add your own custom fields. By convention, all custom field names
+ should start with `_` to avoid naming collisions with future engine
+ usage.
]]
}
@@ -3552,11 +3897,33 @@ Definition tables
when displacement mapping is used
Directions are from the point of view of the tile texture,
not the node it's on
+* `{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.
* deprecated, yet still supported field names:
* `image` (name)
### Tile animation definition
-* `{type="vertical_frames", aspect_w=16, aspect_h=16, length=3.0}`
+
+ {
+ 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`)
@@ -3565,18 +3932,34 @@ Definition tables
drawtype = "normal", -- See "Node drawtypes"
visual_scale = 1.0, --[[
- ^ Supported for drawtypes "plantlike", "signlike", "torchlike", "mesh".
- ^ For plantlike, the image will start at the bottom of the node; for the
- ^ other drawtypes, the image will be centered on the node.
+ ^ Supported for drawtypes "plantlike", "signlike", "torchlike",
+ ^ "firelike", "mesh".
+ ^ For plantlike and firelike, the image will start at the bottom of the
+ ^ node, for the other drawtypes the image will be centered on the node.
^ Note that positioning for "torchlike" may still change. ]]
tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
^ List can be shortened to needed length ]]
+ overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
+ ^ Same as `tiles`, but these textures are drawn on top of the
+ ^ 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.
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 ]]
- alpha = 255,
+ color = ColorSpec, --[[
+ ^ The node's original color will be multiplied with this color.
+ ^ If the node has a palette, then this setting only has an effect
+ ^ in the inventory and on the wield item. ]]
use_texture_alpha = false, -- Use texture's alpha channel
+ palette = "palette.png", --[[
+ ^ The node's `param2` is used to select a pixel from the image
+ ^ (pixels are arranged from left to right and from top to bottom).
+ ^ The node's color will be multiplied with the selected pixel's
+ ^ color. Tiles can override this behavior.
+ ^ Only when `paramtype2` supports palettes. ]]
post_effect_color = "green#0F", -- If player is inside node, see "ColorSpec"
paramtype = "none", -- See "Nodes" --[[
^ paramtype = "light" allows light to propagate from or through the node with light value
@@ -3590,7 +3973,9 @@ Definition tables
diggable = true, -- If false, can never be dug
climbable = false, -- If true, can be climbed on (ladder)
buildable_to = false, -- If true, placed nodes can replace this node
- floodable = false, -- If true, liquids flow into and replace this node
+ floodable = false, --[[
+ ^ If true, liquids flow into and replace this node.
+ ^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]]
liquidtype = "none", -- "none"/"source"/"flowing"
liquid_alternative_flowing = "", -- Flowing version of source liquid
liquid_alternative_source = "", -- Source version of flowing liquid
@@ -3602,7 +3987,10 @@ Definition tables
^ Don't forget to use "leveled" type nodebox. ]]
liquid_range = 8, -- number of flowing nodes around source (max. 8)
drowning = 0, -- Player will take this amount of damage if no bubbles are left
- light_source = 0, -- Amount of light emitted by node
+ light_source = 0, --[[
+ ^ Amount of light emitted by node.
+ ^ To set the maximum (currently 14), use the value 'minetest.LIGHT_MAX'.
+ ^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.]]
damage_per_second = 0, -- If player is inside node, this damage is caused
node_box = {type="regular"}, -- See "Node boxes"
connects_to = nodenames, --[[
@@ -3616,6 +4004,12 @@ Definition tables
^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
legacy_facedir_simple = false, -- Support maps made in and before January 2012
legacy_wallmounted = false, -- Support maps made in and before January 2012
+ waving = 0, --[[ valid for mesh, nodebox, plantlike, allfaces_optional nodes
+ ^ 1 - wave node like plants (top of node moves, bottom is fixed)
+ ^ 2 - wave node like leaves (whole node moves side-to-side synchronously)
+ ^ caveats: not all models will properly wave
+ ^ plantlike drawtype nodes can only wave like plants
+ ^ allfaces_optional drawtype nodes can only wave like leaves --]]
sounds = {
footstep = ,
dig = , -- "__group" = group-based sound (default)
@@ -3648,6 +4042,14 @@ Definition tables
^ Node destructor; called after removing node
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
^ default: nil ]]
+ on_flood = func(pos, oldnode, newnode), --[[
+ ^ Called when a liquid (newnode) is about to flood oldnode, if
+ ^ it has `floodable = true` in the nodedef. Not called for bulk
+ ^ node placement (i.e. schematics and VoxelManip) or air nodes. If
+ ^ return true the node is not flooded, but on_flood callback will
+ ^ most likely be called over and over again every liquid update
+ ^ interval. Default: nil.
+ ^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]]
after_place_node = func(pos, placer, itemstack, pointed_thing) --[[
^ Called after constructing node when node was placed using
@@ -3856,7 +4258,7 @@ The Biome API is still in an experimental phase and subject to change.
{
deco_type = "simple", -- See "Decoration types"
place_on = "default:dirt_with_grass",
- -- ^ Node that decoration can be placed on
+ -- ^ Node (or list of nodes) that the decoration can be placed on
sidelen = 8,
-- ^ Size of divisions made in the chunk being generated.
-- ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size.
@@ -3875,6 +4277,13 @@ The Biome API is still in an experimental phase and subject to change.
-- ^ Minimum and maximum `y` positions these decorations can be generated at.
-- ^ This parameter refers to the `y` position of the decoration base, so
-- the actual maximum height would be `height_max + size.Y`.
+ 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.
+ 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 for all decoration types.
-- ^ "liquid_surface": Instead of placement on the highest solid surface
@@ -3890,15 +4299,10 @@ The Biome API is still in an experimental phase and subject to change.
-- ^ Number of nodes high the decoration is made.
-- ^ If height_max is not 0, this is the lower bound of the randomly selected height.
height_max = 0,
- -- ^ Number of nodes the decoration can be at maximum.
+ -- ^ Number of nodes the decoration can be at maximum.
-- ^ If absent, the parameter 'height' is used as a constant.
- spawn_by = "default:water",
- -- ^ Node that the decoration only spawns next to.
- -- ^ The neighbours checked are the 8 nodes horizontally surrounding the lowest node of the
- -- ^ decoration, and the 8 nodes horizontally surrounding the ground node below the decoration.
- 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.
+ param2 = 0,
+ -- ^ Param2 value of placed decoration node.
----- Schematic-type parameters
schematic = "foobar.mts",
@@ -4006,10 +4410,15 @@ The Biome API is still in an experimental phase and subject to change.
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ Uses texture (string)
- playername = "singleplayer"
+ playername = "singleplayer",
-- ^ optional, if specified spawns particle only on the player's client
+ animation = {Tile Animation definition},
+ -- ^ optional, specifies how to animate the particle texture
+ glow = 0
+ -- ^ optional, specify particle self-luminescence in darkness
}
+
### `ParticleSpawner` definition (`add_particlespawner`)
{
@@ -4034,6 +4443,9 @@ The Biome API is still in an experimental phase and subject to change.
collision_removal = false,
-- ^ collision_removal: if true then particle is removed when it collides,
-- ^ requires collisiondetection = true to have any effect
+ attached = ObjectRef,
+ -- ^ attached: if defined, particle positions, velocities and accelerations
+ -- ^ are relative to this object's position and yaw.
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",