The game directory can contain the following files:
* `game.conf`, with the following keys:
- * `name`: Required, human readable name e.g. `name = Minetest`
+ * `name`: Required, a human readable title to address the game, e.g. `name = Minetest`.
* `description`: Short description to be shown in the content tab
* `allowed_mapgens = <comma-separated mapgens>`
e.g. `allowed_mapgens = v5,v6,flat`
- Mapgens not in this list are removed from the list of mapgens for
- the game.
+ Mapgens not in this list are removed from the list of mapgens for the
+ game.
If not specified, all mapgens are allowed.
* `disallowed_mapgens = <comma-separated mapgens>`
e.g. `disallowed_mapgens = v5,v6,flat`
e.g. `disallowed_mapgen_settings = mgv5_spflags`
These settings are hidden for this game in the world creation
dialog and game start menu.
+ * `author`: The author of the game. It only appears when downloaded from
+ ContentDB.
+ * `release`: Ignore this: Should only ever be set by ContentDB, as it is
+ an internal ID used to track versions.
* `minetest.conf`:
Used to set default settings when running this game.
* `settingtypes.txt`:
should be a mod, contains a file named `modpack.conf`.
The file is a key-value store of modpack details.
-* `name`: The modpack name.
+* `name`: The modpack name. Allows Minetest to determine the modpack name even
+ if the folder is wrongly named.
* `description`: Description of mod to be shown in the Mods tab of the main
menu.
+* `author`: The author of the modpack. It only appears when downloaded from
+ ContentDB.
+* `release`: Ignore this: Should only ever be set by ContentDB, as it is an
+ internal ID used to track versions.
+* `title`: A human-readable title to address the modpack.
Note: to support 0.4.x, please also create an empty modpack.txt file.
│ ├── models
│ ├── textures
│ │ ├── modname_stuff.png
- │ │ └── modname_something_else.png
+ │ │ ├── modname_stuff_normal.png
+ │ │ ├── modname_something_else.png
+ │ │ ├── subfolder_foo
+ │ │ │ ├── modname_more_stuff.png
+ │ │ │ └── another_subfolder
+ │ │ └── bar_subfolder
│ ├── sounds
│ ├── media
│ ├── locale
loaded before this mod.
* `optional_depends`: A comma separated list of optional dependencies.
Like a dependency, but no error if the mod doesn't exist.
+* `author`: The author of the mod. It only appears when downloaded from
+ ContentDB.
+* `release`: Ignore this: Should only ever be set by ContentDB, as it is an
+ internal ID used to track versions.
+* `title`: A human-readable title to address the mod.
Note: to support 0.4.x, please also provide depends.txt.
`minetest.settings` can be used to read custom or existing settings at load
time, if necessary. (See [`Settings`])
-### `models`
-
-Models for entities or meshnodes.
-
-### `textures`, `sounds`, `media`
+### `textures`, `sounds`, `media`, `models`, `locale`
Media files (textures, sounds, whatever) that will be transferred to the
-client and will be available for use by the mod.
+client and will be available for use by the mod and translation files for
+the clients (see [Translations]).
-### `locale`
+It is suggested to use the folders for the purpose they are thought for,
+eg. put textures into `textures`, translation files into `locale`,
+models for entities or meshnodes into `models` et cetera.
-Translation files for the clients. (See [Translations])
+These folders and subfolders can contain subfolders.
+Subfolders with names starting with `_` or `.` are ignored.
+If a subfolder contains a media file with the same name as a media file
+in one of its parents, the parent's file is used.
+
+Although it is discouraged, a mod can overwrite a media file of any mod that it
+depends on by supplying a file with an equal name.
Naming conventions
------------------
* e.g. `foomod_foothing.png`
* e.g. `foomod_foothing`
+
Texture modifiers
-----------------
There are various texture modifiers that can be used
-to generate textures on-the-fly.
+to let the client generate textures on-the-fly.
+The modifiers are applied directly in sRGB colorspace,
+i.e. without gamma-correction.
### Texture overlaying
-- Overlay tiles: define them in the same style
-- The top and bottom tile does not have overlay
overlay_tiles = {"", "",
- {name = "default_grass_side.png", tileable_vertical = false}},
+ {name = "default_grass_side.png"}},
-- Global color, used in inventory
color = "green",
-- Palette in the world
* `paramtype2 = "flowingliquid"`
* Used by `drawtype = "flowingliquid"` and `liquidtype = "flowing"`
* The liquid level and a flag of the liquid are stored in `param2`
- * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node
+ * Bits 0-2: Liquid level (0-7). The higher, the more liquid is in this node;
+ see `minetest.get_node_level`, `minetest.set_node_level` and `minetest.add_node_level`
+ to access/manipulate the content of this field
* Bit 3: If set, liquid is flowing downwards (no graphical effect)
* `paramtype2 = "wallmounted"`
- * Supported drawtypes: "torchlike", "signlike", "normal", "nodebox", "mesh"
+ * Supported drawtypes: "torchlike", "signlike", "plantlike",
+ "plantlike_rooted", "normal", "nodebox", "mesh"
* The rotation of the node is stored in `param2`
* You can make this value by using `minetest.dir_to_wallmounted()`
* Values range 0 - 5
* The height of the 'plantlike' section is stored in `param2`.
* The height is (`param2` / 16) nodes.
* `paramtype2 = "degrotate"`
- * Only valid for "plantlike" drawtype. The rotation of the node is stored in
- `param2`.
- * Values range 0 - 179. The value stored in `param2` is multiplied by two to
+ * Valid for `plantlike` and `mesh` drawtypes. The rotation of the node is
+ stored in `param2`.
+ * Values range 0–239. The value stored in `param2` is multiplied by 1.5 to
get the actual rotation in degrees of the node.
* `paramtype2 = "meshoptions"`
* Only valid for "plantlike" drawtype. `param2` encodes the shape and
palette. The palette should have 32 pixels.
* `paramtype2 = "glasslikeliquidlevel"`
* Only valid for "glasslike_framed" or "glasslike_framed_optional"
- drawtypes.
- * `param2` values 0-63 define 64 levels of internal liquid, 0 being empty
- and 63 being full.
+ drawtypes. "glasslike_framed_optional" nodes are only affected if the
+ "Connected Glass" setting is enabled.
+ * Bits 0-5 define 64 levels of internal liquid, 0 being empty and 63 being
+ full.
+ * Bits 6 and 7 modify the appearance of the frame and node faces. One or
+ both of these values may be added to `param2`:
+ * 64 - Makes the node not connect with neighbors above or below it.
+ * 128 - Makes the node not connect with neighbors to its sides.
* Liquid texture is defined using `special_tiles = {"modname_tilename.png"}`
+* `paramtype2 = "colordegrotate"`
+ * Same as `degrotate`, but with colors.
+ * The first (most-significant) three bits of `param2` tells which color
+ is picked from the palette. The palette should have 8 pixels.
+ * Remaining 5 bits store rotation in range 0–23 (i.e. in 15° steps)
* `paramtype2 = "none"`
* `param2` will not be used by the engine and can be used to store
an arbitrary value
* Invisible, uses no texture.
* `liquid`
* The cubic source node for a liquid.
+ * Faces bordering to the same node are never rendered.
+ * Connects to node specified in `liquid_alternative_flowing`.
+ * Use `backface_culling = false` for the tiles you want to make
+ visible when inside the node.
* `flowingliquid`
* The flowing version of a liquid, appears with various heights and slopes.
+ * Faces bordering to the same node are never rendered.
+ * Connects to node specified in `liquid_alternative_source`.
+ * Node textures are defined with `special_tiles` where the first tile
+ is for the top and bottom faces and the second tile is for the side
+ faces.
+ * `tiles` is used for the item/inventory/wield image rendering.
+ * Use `backface_culling = false` for the special tiles you want to make
+ visible when inside the node
* `glasslike`
* Often used for partially-transparent nodes.
* Only external sides of textures are visible.
used to compensate for how `glasslike` reduces visual thickness.
* `torchlike`
* A single vertical texture.
- * If placed on top of a node, uses the first texture specified in `tiles`.
- * If placed against the underside of a node, uses the second texture
- specified in `tiles`.
- * If placed on the side of a node, uses the third texture specified in
- `tiles` and is perpendicular to that node.
+ * If `paramtype2="[color]wallmounted":
+ * If placed on top of a node, uses the first texture specified in `tiles`.
+ * If placed against the underside of a node, uses the second texture
+ specified in `tiles`.
+ * If placed on the side of a node, uses the third texture specified in
+ `tiles` and is perpendicular to that node.
+ * If `paramtype2="none"`:
+ * Will be rendered as if placed on top of a node (see
+ above) and only the first texture is used.
* `signlike`
* A single texture parallel to, and mounted against, the top, underside or
side of a node.
+ * If `paramtype2="[color]wallmounted", it rotates according to `param2`
+ * If `paramtype2="none"`, it will always be on the floor.
* `plantlike`
* Two vertical and diagonal textures at right-angles to each other.
* See `paramtype2 = "meshoptions"` above for other options.
* `plantlike_rooted`
* Enables underwater `plantlike` without air bubbles around the nodes.
* Consists of a base cube at the co-ordinates of the node plus a
- `plantlike` extension above with a height of `param2 / 16` nodes.
+ `plantlike` extension above
+ * If `paramtype2="leveled", the `plantlike` extension has a height
+ of `param2 / 16` nodes, otherwise it's the height of 1 node
+ * If `paramtype2="wallmounted"`, the `plantlike` extension
+ will be at one of the corresponding 6 sides of the base cube.
+ Also, the base cube rotates like a `normal` cube would
* The `plantlike` extension visually passes through any nodes above the
base cube without affecting them.
* The base cube texture tiles are defined as normal, the `plantlike`
extension uses the defined special tile, for example:
- `special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},`
+ `special_tiles = {{name = "default_papyrus.png"}},`
`*_optional` drawtypes need less rendering time if deactivated
(always client-side).
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
+To avoid collision issues, keep each value within the range of +/- 1.45.
+This also applies to leveled nodeboxes, where the final height shall not
+exceed this soft limit.
* `world_pos`: World position of the waypoint.
* `offset`: offset in pixels from position.
+### `compass`
+
+Displays an image oriented or translated according to current heading direction.
+
+* `size`: The size of this element. Negative values represent percentage
+ of the screen; e.g. `x=-100` means 100% (width).
+* `scale`: Scale of the translated image (used only for dir = 2 or dir = 3).
+* `text`: The name of the texture to use.
+* `alignment`: The alignment of the image.
+* `offset`: Offset in pixels from position.
+* `dir`: How the image is rotated/translated:
+ * 0 - Rotate as heading direction
+ * 1 - Rotate in reverse direction
+ * 2 - Translate as landscape direction
+ * 3 - Translate in reverse direction
+
+If translation is chosen, texture is repeated horizontally to fill the whole element.
+
+### `minimap`
+Displays a minimap on the HUD.
+
+* `size`: Size of the minimap to display. Minimap should be a square to avoid
+ distortion.
+* `alignment`: The alignment of the minimap.
+* `offset`: offset in pixels from position.
Representations of simple things
================================
{x=num, y=num, z=num}
+ Note: it is highly recommended to construct a vector using the helper function:
+ vector.new(num, num, num)
+
For helper functions see [Spatial Vectors].
`pointed_thing`
Items
=====
+Items are things that can be held by players, dropped in the map and
+stored in inventories.
+Items come in the form of item stacks, which are collections of equal
+items that occupy a single inventory slot.
+
Item types
----------
There are three kinds of items: nodes, tools and craftitems.
-* Node: Can be placed in the world's voxel grid
-* Tool: Has a wear property but cannot be stacked. The default use action is to
- dig nodes or hit objects according to its tool capabilities.
-* Craftitem: Cannot dig nodes or be placed
+* Node: Placeable item form of a node in the world's voxel grid
+* Tool: Has a changable wear property but cannot be stacked
+* Craftitem: Has no special properties
+
+Every registered node (the voxel in the world) has a corresponding
+item form (the thing in your inventory) that comes along with it.
+This item form can be placed which will create a node in the
+world (by default).
+Both the 'actual' node and its item form share the same identifier.
+For all practical purposes, you can treat the node and its item form
+interchangeably. We usually just say 'node' to the item form of
+the node as well.
+
+Note the definition of tools is purely technical. The only really
+unique thing about tools is their wear, and that's basically it.
+Beyond that, you can't make any gameplay-relevant assumptions
+about tools or non-tools. It is perfectly valid to register something
+that acts as tool in a gameplay sense as a craftitem, and vice-versa.
+
+Craftitems can be used for items that neither need to be a node
+nor a tool.
Amount and wear
---------------
Tools use a wear (damage) value ranging from 0 to 65535. The
value 0 is the default and is used for unworn tools. The values
1 to 65535 are used for worn tools, where a higher value stands for
-a higher wear. Non-tools always have a wear value of 0.
+a higher wear. Non-tools technically also have a wear property,
+but it is always 0. There is also a special 'toolrepair' crafting
+recipe that is only available to tools.
Item formats
------------
======
In a number of places, there is a group table. Groups define the
-properties of a thing (item, node, armor of entity, capabilities of
-tool) in such a way that the engine and other mods can can interact with
+properties of a thing (item, node, armor of entity, tool capabilities)
+in such a way that the engine and other mods can can interact with
the thing without actually knowing what the thing is.
Usage
------------------
For entities, groups are, as of now, used only for calculating damage.
-The rating is the percentage of damage caused by tools with this damage group.
+The rating is the percentage of damage caused by items with this damage group.
See [Entity damage mechanism].
object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
object.set_armor_groups({fleshy=30, cracky=80})
-Groups of tools
----------------
+Groups of tool capabilities
+---------------------------
-Groups in tools define which groups of nodes and entities they are
-effective towards.
+Groups in tool capabilities define which groups of nodes and entities they
+are effective towards.
Groups in crafting recipes
--------------------------
functionality bound to it, and implementation is left up as a suggestion
to games.
-### Node, item and tool groups
+### Node and item groups
* `not_in_creative_inventory`: (*) Special group for inventory mods to indicate
that the item should be hidden in item lists.
* `3`: the node always gets the digging time 0 seconds (torch)
* `disable_jump`: Player (and possibly other things) cannot jump from node
or if their feet are in the node. Note: not supported for `new_move = false`
-* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
+* `fall_damage_add_percent`: modifies the fall damage suffered when hitting
+ the top of this node. There's also an armor group with the same name.
+ The final player damage is determined by the following formula:
+ damage =
+ collision speed
+ * ((node_fall_damage_add_percent + 100) / 100) -- node group
+ * ((player_fall_damage_add_percent + 100) / 100) -- player armor group
+ - (14) -- constant tolerance
+ Negative damage values are discarded as no damage.
* `falling_node`: if there is no walkable block under the node it will fall
* `float`: the node will not fall through liquids
* `level`: Can be used to give an additional sense of progression in the game.
from destroyed nodes.
* `0` is something that is directly accessible at the start of gameplay
* There is no upper limit
- * See also: `leveldiff` in [Tools]
+ * See also: `leveldiff` in [Tool Capabilities]
* `slippery`: Players and items will slide on the node.
Slipperiness rises steadily with `slippery` value, starting at 1.
`"toolrepair"` crafting recipe
-### `ObjectRef` groups
+### `ObjectRef` armor groups
* `immortal`: Skips all damage and breath handling for an object. This group
- will also hide the integrated HUD status bars for players, and is
- automatically set to all players when damage is disabled on the server.
+ will also hide the integrated HUD status bars for players. It is
+ automatically set to all players when damage is disabled on the server and
+ cannot be reset (subject to change).
+* `fall_damage_add_percent`: Modifies the fall damage suffered by players
+ when they hit the ground. It is analog to the node group with the same
+ name. See the node group above for the exact calculation.
* `punch_operable`: For entities; disables the regular damage mechanism for
players punching it by hand or a non-tool item, so that it can do something
else than take damage.
* `crumbly`: dirt, sand
* `cracky`: tough but crackable stuff like stone.
-* `snappy`: something that can be cut using fine tools; e.g. leaves, small
- plants, wire, sheets of metal
+* `snappy`: something that can be cut using things like scissors, shears,
+ bolt cutters and the like, e.g. leaves, small plants, wire, sheets of metal
* `choppy`: something that can be cut using force; e.g. trees, wooden planks
* `fleshy`: Living things like animals and the player. This could imply
some blood effects when hitting.
Can be added to nodes that shouldn't logically be breakable by the
hand but are. Somewhat similar to `dig_immediate`, but times are more
like `{[1]=3.50,[2]=2.00,[3]=0.70}` and this does not override the
- speed of a tool if the tool can dig at a faster speed than this
+ digging speed of an item if it can dig at a faster speed than this
suggests for the hand.
Examples of custom groups
purpose. Rating is `1`, `2` or `3`. A higher rating for such a group implies
faster digging time.
-The `level` group is used to limit the toughness of nodes a tool can dig
-and to scale the digging times / damage to a greater extent.
+The `level` group is used to limit the toughness of nodes an item capable
+of digging can dig and to scale the digging times / damage to a greater extent.
**Please do understand this**, otherwise you cannot use the system to it's
full potential.
-Tools define their properties by a list of parameters for groups. They
+Items define their properties by a list of parameters for groups. They
cannot dig other groups; thus it is important to use a standard bunch of
-groups to enable interaction with tools.
+groups to enable interaction with items.
-Tools
-=====
+Tool Capabilities
+=================
-Tools definition
-----------------
+'Tool capabilities' is a property of items that defines two things:
+
+1) Which nodes it can dig and how fast
+2) Which objects it can hurt by punching and by how much
+
+Tool capabilities are available for all items, not just tools.
+But only tools can receive wear from digging and punching.
-Tools define:
+Missing or incomplete tool capabilities will default to the
+player's hand.
+
+Tool capabilities definition
+----------------------------
+
+Tool capabilities define:
* Full punch interval
* Maximum drop level
-* For an arbitrary list of groups:
+* For an arbitrary list of node groups:
* Uses (until the tool breaks)
- * Maximum level (usually `0`, `1`, `2` or `3`)
- * Digging times
- * Damage groups
+ * Maximum level (usually `0`, `1`, `2` or `3`)
+ * Digging times
+* Damage groups
+* Punch attack uses (until the tool breaks)
### Full punch interval
-When used as a weapon, the tool will do full damage if this time is spent
-between punches. If e.g. half the time is spent, the tool will do half
+When used as a weapon, the item will do full damage if this time is spent
+between punches. If e.g. half the time is spent, the item will do half
damage.
### Maximum drop level
-Suggests the maximum level of node, when dug with the tool, that will drop
-it's useful item. (e.g. iron ore to drop a lump of iron).
+Suggests the maximum level of node, when dug with the item, that will drop
+its useful item. (e.g. iron ore to drop a lump of iron).
This is not automated; it is the responsibility of the node definition
to implement this.
-### Uses
+### Uses (tools only)
Determines how many uses the tool has when it is used for digging a node,
of this group, of the maximum level. For lower leveled nodes, the use count
* `uses=10, leveldiff=1`: actual uses: 30
* `uses=10, leveldiff=2`: actual uses: 90
+For non-tools, this has no effect.
+
### Maximum level
-Tells what is the maximum level of a node of this group that the tool will
+Tells what is the maximum level of a node of this group that the item will
be able to dig.
### Digging times
maximum level.
For example, as a Lua table, `times={2=2.00, 3=0.70}`. This would
-result in the tool to be able to dig nodes that have a rating of `2` or `3`
+result in the item 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.
List of damage for groups of entities. See [Entity damage mechanism].
-Example definition of the capabilities of a tool
-------------------------------------------------
+### Punch attack uses (tools only)
+
+Determines how many uses (before breaking) the tool has when dealing damage
+to an object, when the full punch interval (see above) was always
+waited out fully.
+
+Wear received by the tool is proportional to the time spent, scaled by
+the full punch interval.
+
+For non-tools, this has no effect.
+
+Example definition of the capabilities of an item
+-------------------------------------------------
tool_capabilities = {
full_punch_interval=1.5,
damage_groups = {fleshy=2},
}
-This makes the tool be able to dig nodes that fulfil both of these:
+This makes the item capable of digging nodes that fulfil both of these:
* Have the `crumbly` group
* Have a `level` group less or equal to `2`
Some of the values in the key-value store are handled specially:
-* `description`: Set the item stack's description. Defaults to
- `idef.description`.
+* `description`: Set the item stack's description.
+ See also: `get_description` in [`ItemStack`]
+* `short_description`: Set the item stack's short description.
+ See also: `get_short_description` in [`ItemStack`]
* `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.
list[current_player;craft;3,0;3,3;]
list[current_player;craftpreview;7,1;1,1;]
+Version History
+---------------
+
+* FORMSPEC VERSION 1:
+ * (too much)
+* FORMSPEC VERSION 2:
+ * Forced real coordinates
+ * background9[]: 9-slice scaling parameters
+* FORMSPEC VERSION 3:
+ * Formspec elements are drawn in the order of definition
+ * bgcolor[]: use 3 parameters (bgcolor, formspec (now an enum), fbgcolor)
+ * box[] and image[] elements enable clipping by default
+ * new element: scroll_container[]
+* FORMSPEC VERSION 4:
+ * Allow dropdown indexing events
+
Elements
--------
* Clients older than this version can neither show newer elements nor display
elements with new arguments correctly.
* Available since feature `formspec_version_element`.
+* See also: [Version History]
### `size[<W>,<H>,<fixed_size>]`
* Show an inventory list if it has been sent to the client. Nothing will
be shown if the inventory list is of size 0.
* **Note**: With the new coordinate system, the spacing between inventory
- slots is one-fourth the size of an inventory slot.
+ slots is one-fourth the size of an inventory slot by default. Also see
+ [Styling Formspecs] for changing the size of slots and spacing.
### `list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]`
* `frame duration`: Milliseconds between each frame. `0` means the frames don't advance.
* `frame start` (Optional): The index of the frame to start on. Default `1`.
+### `model[<X>,<Y>;<W>,<H>;<name>;<mesh>;<textures>;<rotation X,Y>;<continuous>;<mouse control>;<frame loop range>;<animation speed>]`
+
+* Show a mesh model.
+* `name`: Element name that can be used for styling
+* `mesh`: The mesh model to use.
+* `textures`: The mesh textures to use according to the mesh materials.
+ Texture names must be separated by commas.
+* `rotation {X,Y}` (Optional): Initial rotation of the camera.
+ The axes are euler angles in degrees.
+* `continuous` (Optional): Whether the rotation is continuous. Default `false`.
+* `mouse control` (Optional): Whether the model can be controlled with the mouse. Default `true`.
+* `frame loop range` (Optional): Range of the animation frames.
+ * Defaults to the full range of all available frames.
+ * Syntax: `<begin>,<end>`
+* `animation speed` (Optional): Sets the animation speed. Default 0 FPS.
+
### `item_image[<X>,<Y>;<W>,<H>;<item name>]`
* Show an inventory image of registered item/node
* Simple colored box
* `color` is color specified as a `ColorString`.
If the alpha component is left blank, the box will be semitransparent.
+ If the color is not specified, the box will use the options specified by
+ its style. If the color is specified, all styling options will be ignored.
### `dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>;<index event>]`
* `span=<value>`: number of following columns to affect
(default: infinite).
-### `style[<selector 1>,<selector 2>;<prop1>;<prop2>;...]`
+### `style[<selector 1>,<selector 2>
,...;<prop1>;<prop2>;...]`
* Set the style for the element(s) matching `selector` by name.
* `selector` can be one of:
* See [Styling Formspecs].
-### `style_type[<selector 1>,<selector 2>;<prop1>;<prop2>;...]`
+### `style_type[<selector 1>,<selector 2>
,...;<prop1>;<prop2>;...]`
* Set the style for the element(s) matching `selector` by type.
* `selector` can be one of:
Formspec elements can be themed using the style elements:
- style[<name 1>,<name 2>;<prop1>;<prop2>;...]
- style[<name 1>:<state>,<name 2>:<state>;<prop1>;<prop2>;...]
- style_type[<type 1>,<type 2>;<prop1>;<prop2>;...]
- style_type[<type 1>:<state>,<type 2>:<state>;<prop1>;<prop2>;...]
+ style[<name 1>,<name 2>
,...;<prop1>;<prop2>;...]
+ style[<name 1>:<state>,<name 2>:<state>
,...;<prop1>;<prop2>;...]
+ style_type[<type 1>,<type 2>
,...;<prop1>;<prop2>;...]
+ style_type[<type 1>:<state>,<type 2>:<state>
,...;<prop1>;<prop2>;...]
Where a prop is:
Some types may inherit styles from parent types.
* animated_image, inherits from image
+* box
* button
* button_exit, inherits from button
* checkbox
-* scrollbar
-* table
-* textlist
* dropdown
* field
-* pwdfield, inherits from field
-* textarea
-* label
-* vertlabel, inherits from field
+* image
* image_button
* item_image_button
+* label
+* list
+* model
+* pwdfield, inherits from field
+* scrollbar
* tabheader
+* table
+* textarea
+* textlist
+* vertlabel, inherits from label
### Valid Properties
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* box
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
- * Default to false in formspec_version version 3 or higher
+ * Defaults to false in formspec_version version 3 or higher
+ * **Note**: `colors`, `bordercolors`, and `borderwidths` accept multiple input types:
+ * Single value (e.g. `#FF0`): All corners/borders.
+ * Two values (e.g. `red,#FFAAFF`): top-left and bottom-right,top-right and bottom-left/
+ top and bottom,left and right.
+ * Four values (e.g. `blue,#A0F,green,#FFFA`): top-left/top and rotates clockwise.
+ * These work similarly to CSS borders.
+ * colors - `ColorString`. Sets the color(s) of the box corners. Default `black`.
+ * bordercolors - `ColorString`. Sets the color(s) of the borders. Default `black`.
+ * borderwidths - Integer. Sets the width(s) of the borders in pixels. If the width is
+ negative, the border will extend inside the box, whereas positive extends outside
+ the box. A width of zero results in no border; this is default.
* button, button_exit, image_button, item_image_button
* alpha - boolean, whether to draw alpha in bgimg. Default true.
* bgcolor - color, sets button tint.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* padding - rect, adds space between the edges of the button and the content. This value is
relative to bgimg_middle.
+ * sound - a sound to be played when triggered.
* textcolor - color, default white.
* checkbox
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
-* scrollbar
- * noclip - boolean, set to true to allow the element to exceed formspec bounds.
-* table, textlist
- * font - Sets font type. See button `font` property for more information.
- * font_size - Sets font size. See button `font_size` property for more information.
- * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * sound - a sound to be played when triggered.
* dropdown
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * sound - a sound to be played when the entry is changed.
* field, pwdfield, textarea
* border - set to false to hide the textbox background and border. Default true.
* font - Sets font type. See button `font` property for more information.
* font_size - Sets font size. See button `font_size` property for more information.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* textcolor - color. Default white.
+* model
+ * bgcolor - color, sets background color.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * Default to false in formspec_version version 3 or higher
* image
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
* Default to false in formspec_version version 3 or higher
* font - Sets font type. See button `font` property for more information.
* font_size - Sets font size. See button `font_size` property for more information.
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+* list
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * size - 2d vector, sets the size of inventory slots in coordinates.
+ * spacing - 2d vector, sets the space between inventory slots in coordinates.
* image_button (additional properties)
* fgimg - standard image. Defaults to none.
* fgimg_hovered - image when hovered. Defaults to fgimg when not provided.
* fgimg_pressed - image when pressed. Defaults to fgimg when not provided.
* This is deprecated, use states instead.
* NOTE: The parameters of any given image_button will take precedence over fgimg/fgimg_pressed
+ * sound - a sound to be played when triggered.
+* scrollbar
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
* tabheader
* noclip - boolean, set to true to allow the element to exceed formspec bounds.
+ * sound - a sound to be played when a different tab is selected.
* textcolor - color. Default white.
+* table, textlist
+ * font - Sets font type. See button `font` property for more information.
+ * font_size - Sets font size. See button `font_size` property for more information.
+ * noclip - boolean, set to true to allow the element to exceed formspec bounds.
### Valid States
Tags can have attributes, in that case, attributes are in the opening tag in
form of a key/value separated with equal signs. Attribute values should not be quoted.
+If you want to insert a literal greater-than sign or a backslash into the text,
+you must escape it by preceding it with a backslash.
+
These are the technically basic tags but see below for usual tags. Base tags are:
`<style color=... font=... size=...>...</style>`
Named colors are also supported and are equivalent to
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
-To specify the value of the alpha channel, append `#AA` to the end of the color
-name (e.g. `colorname#08`). For named colors the hexadecimal string
-representing the alpha value must (always) be two hexadecimal digits.
+To specify the value of the alpha channel, append `#A` or `#AA` to the end of
+the color name (e.g. `colorname#08`).
`ColorSpec`
-----------
Internally, it is implemented as a table with the 3 fields
`x`, `y` and `z`. Example: `{x = 0, y = 1, z = 0}`.
+However, one should *never* create a vector manually as above, such misbehavior
+is deprecated. The vector helpers set a metatable for the created vectors which
+allows indexing with numbers, calling functions directly on vectors and using
+operators (like `+`). Furthermore, the internal implementation might change in
+the future.
+Old code might still use vectors without metatables, be aware of this!
+
+All these forms of addressing a vector `v` are valid:
+`v[1]`, `v[3]`, `v.x`, `v[1] = 42`, `v.y = 13`
+
+Where `v` is a vector and `foo` stands for any function name, `v:foo(...)` does
+the same as `vector.foo(v, ...)`, apart from deprecated functionality.
+
+The metatable that is used for vectors can be accessed via `vector.metatable`.
+Do not modify it!
+
+All `vector.*` functions allow vectors `{x = X, y = Y, z = Z}` without metatables.
+Returned vectors always have a metatable set.
For the following functions, `v`, `v1`, `v2` are vectors,
-`p1`, `p2` are positions:
+`p1`, `p2` are positions,
+`s` is a scalar (a number),
+vectors are written like this: `(x, y, z)`:
-* `vector.new(a[, b, c])`:
+* `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 of `a`, `b`, `c` are defined numbers.
+ * `(a, b, c)`, if all of `a`, `b`, `c` are defined numbers.
+ * `(0, 0, 0)`, if no arguments are given.
+* `vector.from_string(s[, init])`:
+ * Returns `v, np`, where `v` is a vector read from the given string `s` and
+ `np` is the next position in the string after the vector.
+ * Returns `nil` on failure.
+ * `s`: Has to begin with a substring of the form `"(x, y, z)"`. Additional
+ spaces, leaving away commas and adding an additional comma to the end
+ is allowed.
+ * `init`: If given starts looking for the vector at this string index.
+* `vector.to_string(v)`:
+ * Returns a string of the form `"(x, y, z)"`.
* `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}`.
+ * If `p1` and `p2` are identical, returns `(0, 0, 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}`.
+ * If `v` has zero length, returns `(0, 0, 0)`.
* `vector.floor(v)`:
* Returns a vector, each dimension rounded down.
* `vector.round(v)`:
* Returns a vector, each dimension rounded to nearest integer.
+ * At a multiple of 0.5, rounds away from zero.
* `vector.apply(v, func)`:
* Returns a vector where the function `func` has been applied to each
component.
* Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`.
* `vector.angle(v1, v2)`:
* Returns the angle between `v1` and `v2` in radians.
-* `vector.dot(v1, v2)`
- * Returns the dot product of `v1` and `v2`
-* `vector.cross(v1, v2)`
- * Returns the cross product of `v1` and `v2`
+* `vector.dot(v1, v2)`:
+ * Returns the dot product of `v1` and `v2`.
+* `vector.cross(v1, v2)`:
+ * Returns the cross product of `v1` and `v2`.
+* `vector.offset(v, x, y, z)`:
+ * Returns the sum of the vectors `v` and `(x, y, z)`.
+* `vector.check()`:
+ * Returns a boolean value indicating whether `v` is a real vector, eg. created
+ by a `vector.*` function.
+ * Returns `false` for anything else, including tables like `{x=3,y=1,z=4}`.
For the following functions `x` can be either a vector or a number:
* Returns a vector.
* If `x` is a vector: Returns the difference of `v` subtracted by `x`.
* If `x` is a number: Subtracts `x` from each component of `v`.
-* `vector.multiply(v, x)`:
- * Returns a scaled vector or Schur product.
-* `vector.divide(v, x)`:
- * Returns a scaled vector or Schur quotient.
+* `vector.multiply(v, s)`:
+ * Returns a scaled vector.
+ * Deprecated: If `s` is a vector: Returns the Schur product.
+* `vector.divide(v, s)`:
+ * Returns a scaled vector.
+ * Deprecated: If `s` is a vector: Returns the Schur quotient.
+
+Operators can be used if all of the involved vectors have metatables:
+* `v1 == v2`:
+ * Returns whether `v1` and `v2` are identical.
+* `-v`:
+ * Returns the additive inverse of v.
+* `v1 + v2`:
+ * Returns the sum of both vectors.
+ * Note: `+` can not be used together with scalars.
+* `v1 - v2`:
+ * Returns the difference of `v1` subtracted by `v2`.
+ * Note: `-` can not be used together with scalars.
+* `v * s` or `s * v`:
+ * Returns `v` scaled by `s`.
+* `v / s`:
+ * Returns `v` scaled by `1 / s`.
For the following functions `a` is an angle in radians and `r` is a rotation
vector ({x = <pitch>, y = <yaw>, z = <roll>}) where pitch, yaw and roll are
* `vector.rotate(v, r)`:
* Applies the rotation `r` to `v` and returns the result.
- * `vector.rotate({x = 0, y = 0, z = 1}, r)` and
- `vector.rotate({x = 0, y = 1, z = 0}, r)` return vectors pointing
+ * `vector.rotate(vector.new(0, 0, 1), r)` and
+ `vector.rotate(vector.new(0, 1, 0), r)` return vectors pointing
forward and up relative to an entity's rotation `r`.
* `vector.rotate_around_axis(v1, v2, a)`:
* Returns `v1` rotated around axis `v2` by `a` radians according to
* If the absolute value of `x` is within the `tolerance` or `x` is NaN,
`0` is returned.
* `math.factorial(x)`: returns the factorial of `x`
+* `math.round(x)`: Returns `x` rounded to the nearest integer.
+ * At a multiple of 0.5, rounds away from zero.
* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)`
* `separator`: string, default: `","`
* `include_empty`: boolean, default: `false`
* Appends all values in `other_table` to `table` - uses `#table + 1` to
find new indices.
* `table.key_value_swap(t)`: returns a table with keys and values swapped
- * If multiple keys in `t` map to the same value, the result is undefined.
+ * If multiple keys in `t` map to the same value, it is unspecified which
+ value maps to that key.
* `table.shuffle(table, [from], [to], [random_func])`:
* Shuffles elements `from` to `to` in `table` in place
* `from` defaults to `1`
* `minetest.pointed_thing_to_face_pos(placer, pointed_thing)`: returns a
position.
* returns the exact position on the surface of a pointed node
-* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates a tool
+* `minetest.get_dig_params(groups, tool_capabilities)`: Simulates an item
that digs a node.
Returns a table with the following fields:
* `diggable`: `true` if node can be dug, `false` otherwise.
* `time`: Time it would take to dig the node.
- * `wear`: How much wear would be added to the tool.
+ * `wear`: How much wear would be added to the tool (ignored for non-tools).
`time` and `wear` are meaningless if node's not diggable
Parameters:
* `groups`: Table of the node groups of the node that would be dug
- * `tool_capabilities`: Tool capabilities table of the tool
+ * `tool_capabilities`: Tool capabilities table of the item
* `minetest.get_hit_params(groups, tool_capabilities [, time_from_last_punch])`:
Simulates an item that punches an object.
Returns a table with the following fields:
* `hp`: How much damage the punch would cause.
- * `wear`: How much wear would be added to the tool.
+ * `wear`: How much wear would be added to the tool (ignored for non-tools).
Parameters:
* `groups`: Damage groups of the object
* `tool_capabilities`: Tool capabilities table of the item
Each additional octave adds finer detail to the noise but also increases the
noise calculation load.
3 is a typical minimum for a high quality, complex and natural-looking noise
-variation. 1 octave has a slight 'gridlike' appearence.
+variation. 1 octave has a slight 'gridlike' appearance.
Choose the number of octaves according to the `spread` and `lacunarity`, and the
size of the finest detail you require. For example:
spread = {x = 500, y = 500, z = 500},
seed = 571347,
octaves = 5,
- persist = 0.63,
+ persistence = 0.63,
lacunarity = 2.0,
flags = "defaults, absvalue",
}
spread = {x=200, y=200, z=200},
seed = 5390,
octaves = 4,
- persist = 0.5,
+ persistence = 0.5,
lacunarity = 2.0,
flags = "eased",
},
* 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_deactivate(self)
+ * Called when the object is about to get removed or unloaded.
* `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
* `puncher`: an `ObjectRef` (can be `nil`)
* `time_from_last_punch`: Meant for disallowing spamming of clicks
(can be `nil`).
- * `tool_capabilities`: capability table of used tool (can be `nil`)
+ * `tool_capabilities`: capability table of used item (can be `nil`)
* `dir`: unit vector of direction of punch. Always defined. Points from the
puncher to the punched.
* `damage`: damage that will be done to entity.
* `minetest.get_current_modname()`: returns the currently loading mod's name,
when loading a mod.
-* `minetest.get_modpath(modname)`: returns e.g.
- `"/home/user/.minetest/usermods/modname"`.
- * Useful for loading additional `.lua` modules or static data from mod
-* `minetest.get_modnames()`: returns a list of installed mods
- * Return a list of installed mods, sorted alphabetically
+* `minetest.get_modpath(modname)`: returns the directory path for a mod,
+ e.g. `"/home/user/.minetest/usermods/modname"`.
+ * Returns nil if the mod is not enabled or does not exist (not installed).
+ * Works regardless of whether the mod has been loaded yet.
+ * Useful for loading additional `.lua` modules or static data from a mod,
+ or checking if a mod is enabled.
+* `minetest.get_modnames()`: returns a list of enabled mods, sorted alphabetically.
+ * Does not include disabled mods, even if they are installed.
* `minetest.get_worldpath()`: returns e.g. `"/home/user/.minetest/world"`
* Useful for storing custom data
* `minetest.is_singleplayer()`
pathfinder_works = true,
-- Whether Collision info is available to an objects' on_step (5.3.0)
object_step_has_moveresult = true,
+ -- Whether get_velocity() and add_velocity() can be used on players (5.4.0)
+ direct_velocity_on_players = true,
+ -- nodedef's use_texture_alpha accepts new string modes (5.4.0)
+ use_texture_alpha_string_modes = true,
+ -- degrotate param2 rotates in units of 1.5° instead of 2°
+ -- thus changing the range of values from 0-179 to 0-240 (5.5.0)
+ degrotate_240_steps = true,
+ -- ABM supports min_y and max_y fields in definition (5.5.0)
+ abm_min_max_y = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
* `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
+* `minetest.colorspec_to_colorstring(colorspec)`: Converts a ColorSpec to a
+ ColorString. If the ColorSpec is invalid, returns `nil`.
+ * `colorspec`: The ColorSpec to convert
Logging
-------
* `hitter`: ObjectRef - Player that hit
* `time_from_last_punch`: Meant for disallowing spamming of clicks
(can be nil).
- * `tool_capabilities`: Capability table of used tool (can be nil)
+ * `tool_capabilities`: Capability table of used item (can be nil)
* `dir`: Unit vector of direction of punch. Always defined. Points from
the puncher to the punched.
* `damage`: Number that represents the damage calculated by the engine
* should return `true` to prevent the default damage mechanism
+* `minetest.register_on_rightclickplayer(function(player, clicker))`
+ * Called when a player is right-clicked
+ * `player`: ObjectRef - Player that was right-clicked
+ * `clicker`: ObjectRef - Object that right-clicked, may or may not be a player
* `minetest.register_on_player_hpchange(function(player, hp_change, reason), modifier)`
* Called when the player gets damaged or healed
* `player`: ObjectRef of the player
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
* `moved_too_fast`
* `interacted_too_far`
+ * `interacted_with_self`
* `interacted_while_dead`
* `finished_unknown_dig`
* `dug_unbreakable`
* Called always when a player says something
* Return `true` to mark the message as handled, which means that it will
not be sent to other players.
+* `minetest.register_on_chatcommand(function(name, command, params))`
+ * Called always when a chatcommand is triggered, before `minetest.registered_chatcommands`
+ is checked to see if the command exists, but after the input is parsed.
+ * Return `true` to mark the command as handled, which means that the default
+ handlers will be prevented.
* `minetest.register_on_player_receive_fields(function(player, formname, fields))`
* Called when the server received input from `player` in a formspec with
the given `formname`. Specifically, this is called on any of the
* 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.
+* `minetest.register_on_liquid_transformed(function(pos_list, node_list))`
+ * Called after liquid nodes are modified by the engine's liquid transformation
+ process.
+ * `pos_list` is an array of all modified positions.
+ * `node_list` is an array of the old node that was previously at the position
+ with the corresponding index in pos_list.
Setting-related
---------------
* `pos`: The position where to measure the light.
* `timeofday`: `nil` for current time, `0` for night, `0.5` for day
* Returns a number between `0` and `15` or `nil`
+ * `nil` is returned e.g. when the map isn't loaded at `pos`
+* `minetest.get_natural_light(pos[, timeofday])`
+ * Figures out the sunlight (or moonlight) value at pos at the given time of
+ day.
+ * `pos`: The position of the node
+ * `timeofday`: `nil` for current time, `0` for night, `0.5` for day
+ * Returns a number between `0` and `15` or `nil`
+ * This function tests 203 nodes in the worst case, which happens very
+ unlikely
+* `minetest.get_artificial_light(param1)`
+ * Calculates the artificial light (light from e.g. torches) value from the
+ `param1` value.
+ * `param1`: The param1 value of a `paramtype = "light"` node.
+ * Returns a number between `0` and `15`
+ * Currently it's the same as `math.floor(param1 / 16)`, except that it
+ ensures compatibility.
* `minetest.place_node(pos, node)`
* Place node with the same effects that a player would cause
* `minetest.dig_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
+ * Returns `true` and the ObjectRef of the spawned entity 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
* `minetest.get_objects_inside_radius(pos, radius)`: returns a list of
ObjectRefs.
* `radius`: using an euclidean metric
+* `minetest.get_objects_in_area(pos1, pos2)`: returns a list of
+ ObjectRefs.
+ * `pos1` and `pos2` are the min and max positions of the area to search.
* `minetest.set_timeofday(val)`
* `val` is between `0` and `1`; `0` for midnight, `0.5` for midday
* `minetest.get_timeofday()`
information.
* `minetest.get_node_drops(node, toolname)`
* Returns list of itemstrings that are dropped by `node` when dug
- with `toolname`.
+ with the item `toolname` (not limited to tools).
* `node`: node as table or node name
- * `toolname`: name of the tool item (can be `nil`)
+ * `toolname`: name of the item used to dig (can be `nil`)
* `minetest.get_craft_result(input)`: returns `output, decremented_input`
* `input.method` = `"normal"` or `"cooking"` or `"fuel"`
* `input.width` = for example `3`
* `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.
+ The gain will change by this much per second,
+ until it reaches the target gain.
+ Note: Older versions used a signed step. This is deprecated, but old
+ code will still work. (the client uses abs(step) to correct it)
* `gain` the target gain for the fade.
+ Fading to zero will delete the sound.
Timing
------
-* `minetest.after(time, func, ...)`
+* `minetest.after(time, func, ...)` : returns job table to use as below.
* Call the function `func` after `time` seconds, may be fractional
* Optional: Variable number of arguments that are passed to `func`
+* `job:cancel()`
+ * Cancels the job function from being called
+
Server
------
* 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)
-* `minetest.dynamic_add_media(filepath)`
- * Adds the file at the given path to the media sent to clients by the server
- on startup and also pushes this file to already connected clients.
+* `minetest.dynamic_add_media(filepath, callback)`
+ * `filepath`: path to a media file on the filesystem
+ * `callback`: function with arguments `name`, where name is a player name
+ (previously there was no callback argument; omitting it is deprecated)
+ * Adds the file to the media sent to clients by the server on startup
+ and also pushes this file to already connected clients.
The file must be a supported image, sound or model format. It must not be
modified, deleted, moved or renamed after calling this function.
The list of dynamically added media is not persisted.
- * Returns boolean indicating success (duplicate files count as error)
- * The media will be ready to use (in e.g. entity textures, sound_play)
- immediately after calling this function.
+ * Returns false on error, true if the request was accepted
+ * The given callback will be called for every player as soon as the
+ media is available on the client.
Old clients that lack support for this feature will not see the media
- unless they reconnect to the server.
- * Since media transferred this way does not use client caching or HTTP
- transfers, dynamic media should not be used with big files or performance
- will suffer.
+ unless they reconnect to the server. (callback won't be called)
+ * Since media transferred this way currently does not use client caching
+ or HTTP transfers, dynamic media should not be used with big files.
Bans
----
* Example: `minetest.rgba(10, 20, 30, 40)`, returns `"#0A141E28"`
* `minetest.encode_base64(string)`: returns string encoded in base64
* Encodes a string in base64.
-* `minetest.decode_base64(string)`: returns string or nil for invalid base64
+* `minetest.decode_base64(string)`: returns string or nil on failure
+ * Padding characters are only supported starting at version 5.4.0, where
+ 5.5.0 and newer perform proper checks.
* Decodes a string encoded in base64.
* `minetest.is_protected(pos, name)`: returns boolean
* Returning `true` restricts the player `name` from modifying (i.e. digging,
* If `transient` is `false` or absent, frees a persistent forceload.
If `true`, frees a transient forceload.
+* `minetest.compare_block_status(pos, condition)`
+ * Checks whether the mapblock at positition `pos` is in the wanted condition.
+ * `condition` may be one of the following values:
+ * `"unknown"`: not in memory
+ * `"emerging"`: in the queue for loading from disk or generating
+ * `"loaded"`: in memory but inactive (no ABMs are executed)
+ * `"active"`: in memory and active
+ * Other values are reserved for future functionality extensions
+ * Return value, the comparison status:
+ * `false`: Mapblock does not fulfil the wanted condition
+ * `true`: Mapblock meets the requirement
+ * `nil`: Unsupported `condition` value
+
* `minetest.request_insecure_environment()`: returns an environment containing
insecure functions if the calling mod has been listed as trusted in the
`secure.trusted_mods` setting or security is disabled, otherwise returns
* Map of registered tool definitions, indexed by name
* `minetest.registered_entities`
* Map of registered entity prototypes, indexed by name
+ * Values in this table may be modified directly.
+ Note: changes to initial properties will only affect entities spawned afterwards,
+ as they are only read when spawning.
* `minetest.object_refs`
* Map of object references, indexed by active object id
* `minetest.luaentities`
* Map of registered chat command definitions, indexed by name
* `minetest.registered_privileges`
* Map of registered privilege definitions, indexed by name
+ * Registered privileges can be modified directly in this table.
### Registered callback tables
`minetest.get_inventory(location)`.
* returns `{type="undefined"}` in case location is not known
+### Callbacks
+
+Detached & nodemeta inventories provide the following callbacks for move actions:
+
+#### Before
+
+The `allow_*` callbacks return how many items can be moved.
+
+* `allow_move`/`allow_metadata_inventory_move`: Moving items in the inventory
+* `allow_take`/`allow_metadata_inventory_take`: Taking items from the inventory
+* `allow_put`/`allow_metadata_inventory_put`: Putting items to the inventory
+
+#### After
+
+The `on_*` callbacks are called after the items have been placed in the inventories.
+
+* `on_move`/`on_metadata_inventory_move`: Moving items in the inventory
+* `on_take`/`on_metadata_inventory_take`: Taking items from the inventory
+* `on_put`/`on_metadata_inventory_put`: Putting items to the inventory
+
+#### Swapping
+
+When a player tries to put an item to a place where another item is, the items are *swapped*.
+This means that all callbacks will be called twice (once for each action).
+
`ItemStack`
-----------
stack).
* `set_metadata(metadata)`: (DEPRECATED) Returns true.
* `get_description()`: returns the description shown in inventory list tooltips.
+ * The engine uses this when showing item descriptions in tooltips.
+ * Fields for finding the description, in order:
+ * `description` in item metadata (See [Item Metadata].)
+ * `description` in item definition
+ * item name
+* `get_short_description()`: returns the short description or nil.
+ * Unlike the description, this does not include new lines.
+ * Fields for finding the short description, in order:
+ * `short_description` in item metadata (See [Item Metadata].)
+ * `short_description` in item definition
+ * first line of the description (From item meta or def, see `get_description()`.)
+ * Returns nil if none of the above are set
* `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.
* `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
+ * Increases wear by `amount` if the item is a tool, otherwise does nothing
* `amount`: number, integer
* `add_item(item)`: returns leftover `ItemStack`
* Put some item or stack onto this stack
* `get_pos()`: returns `{x=num, y=num, z=num}`
* `set_pos(pos)`: `pos`=`{x=num, y=num, z=num}`
+* `get_velocity()`: returns the velocity, a vector.
+* `add_velocity(vel)`
+ * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
+ * In comparison to using get_velocity, adding the velocity and then using
+ set_velocity, add_velocity is supposed to avoid synchronization problems.
+ Additionally, players also do not support set_velocity.
+ * If a player:
+ * Does not apply during free_move.
+ * Note that since the player speed is normalized at each move step,
+ increasing e.g. Y velocity beyond what would usually be achieved
+ (see: physics overrides) will cause existing X/Z velocity to be reduced.
+ * Example: `add_velocity({x=0, y=6.5, z=0})` is equivalent to
+ pressing the jump key (assuming default settings)
* `move_to(pos, continuous=false)`
* Does an interpolated move for Lua entities for visually smooth transitions.
* If `continuous` is true, the Lua entity will not be moved to the current
* `time_from_last_punch` = time since last punch action of the puncher
* `direction`: can be `nil`
* `right_click(clicker)`; `clicker` is another `ObjectRef`
-* `get_hp()`: returns number of hitpoints (2 * number of hearts)
-* `set_hp(hp, reason)`: set number of hitpoints (2 * number of hearts).
+* `get_hp()`: returns number of health points
+* `set_hp(hp, reason)`: set number of health points
* See reason in register_on_player_hpchange
* Is limited to the range of 0 ... 65535 (2^16 - 1)
* For players: HP are also limited by `hp_max` specified in the player's
`frame_loop`.
* `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 on each axis, in degrees
-* `get_attach()`: returns parent, bone, position, rotation or nil if it isn't
- attached.
+* `set_attach(parent[, bone, position, rotation, forced_visible])`
+ * `bone`: string. Default is `""`, the root bone
+ * `position`: `{x=num, y=num, z=num}`, relative, default `{x=0, y=0, z=0}`
+ * `rotation`: `{x=num, y=num, z=num}` = Rotation on each axis, in degrees.
+ Default `{x=0, y=0, z=0}`
+ * `forced_visible`: Boolean to control whether the attached entity
+ should appear in first person. Default `false`.
+ * This command may fail silently (do nothing) when it would result
+ in circular attachments.
+* `get_attach()`: returns parent, bone, position, rotation, forced_visible,
+ or nil if it isn't attached.
+* `get_children()`: returns a list of ObjectRefs that are attached to the
+ object.
* `set_detach()`
-* `set_bone_position(bone, position, rotation)`
- * `bone`: string
- * `position`: `{x=num, y=num, z=num}` (relative)
- * `rotation`: `{x=num, y=num, z=num}`
+* `set_bone_position([bone, position, rotation])`
+ * `bone`: string. Default is `""`, the root bone
+ * `position`: `{x=num, y=num, z=num}`, relative, `default {x=0, y=0, z=0}`
+ * `rotation`: `{x=num, y=num, z=num}`, default `{x=0, y=0, z=0}`
* `get_bone_position(bone)`: returns position and rotation of the bone
* `set_properties(object property table)`
* `get_properties()`: returns object property table
* `get_nametag_attributes()`
* returns a table with the attributes of the nametag of an object
* {
- color = {a=0..255, r=0..255, g=0..255, b=0..255},
text = "",
+ color = {a=0..255, r=0..255, g=0..255, b=0..255},
+ bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255},
}
* `set_nametag_attributes(attributes)`
* sets the attributes of the nametag of an object
* `attributes`:
{
- color = ColorSpec,
text = "My Nametag",
+ color = ColorSpec,
+ -- ^ Text color
+ bgcolor = ColorSpec or false,
+ -- ^ Sets background color of nametag
+ -- `false` will cause the background to be set automatically based on user settings
+ -- Default: false
}
#### Lua entity only (no-op for other objects)
no effect and returning `nil`.
* `set_velocity(vel)`
* `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
-* `add_velocity(vel)`
- * `vel` is a vector, e.g. `{x=0.0, y=2.3, z=1.0}`
- * In comparison to using get_velocity, adding the velocity and then using
- set_velocity, add_velocity is supposed to avoid synchronization problems.
-* `get_velocity()`: returns the velocity, a vector
* `set_acceleration(acc)`
* `acc` is a vector
* `get_acceleration()`: returns the acceleration, a vector
* `rot` is a vector (radians). X is pitch (elevation), Y is yaw (heading)
and Z is roll (bank).
* `get_rotation()`: returns the rotation, a vector (radians)
-* `set_yaw(radians)`: sets the yaw (heading).
+* `set_yaw(yaw)`: sets the yaw in radians (heading).
* `get_yaw()`: returns number in radians
* `set_texture_mod(mod)`
+ * Set a texture modifier to the base texture, for sprites and meshes.
+ * When calling `set_texture_mod` again, the previous one is discarded.
+ * `mod` the texture modifier. See [Texture modifiers].
* `get_texture_mod()` returns current texture modifier
-* `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`
+* `set_sprite(start_frame, num_frames, framelength, select_x_by_camera)`
+ * Specifies and starts a sprite animation
+ * Animations iterate along the frame `y` position.
+ * `start_frame`: {x=column number, y=row number}, the coordinate of the
+ first frame, default: `{x=0, y=0}`
+ * `num_frames`: Total frames in the texture, default: `1`
+ * `framelength`: Time per animated frame in seconds, default: `0.2`
+ * `select_x_by_camera`: Only for visual = `sprite`. Changes the frame `x`
+ position according to the view direction. default: `false`.
+ * First column: subject facing the camera
+ * Second column: subject looking to the left
+ * Third column: subject backing the camera
+ * Fourth column: subject looking to the right
+ * Fifth column: subject viewed from above
+ * Sixth column: subject viewed from below
* `get_entity_name()` (**Deprecated**: Will be removed in a future version)
* `get_luaentity()`
#### Player only (no-op for other objects)
* `get_player_name()`: returns `""` if is not a player
-* `get_player_velocity()`: returns `nil` if is not a player, otherwise a
+* `get_player_velocity()`: **DEPRECATED**, use get_velocity() instead.
table {x, y, z} representing the player's instantaneous velocity in nodes/s
-* `add_player_velocity(vel)`
- * Adds to player velocity, this happens client-side and only once.
- * Does not apply during free_move.
- * Note that since the player speed is normalized at each move step,
- increasing e.g. Y velocity beyond what would usually be achieved
- (see: physics overrides) will cause existing X/Z velocity to be reduced.
- * Example: `add_player_velocity({x=0, y=6.5, z=0})` is equivalent to
- pressing the jump key (assuming default settings)
+* `add_player_velocity(vel)`: **DEPRECATED**, use add_velocity(vel) instead.
* `get_look_dir()`: get camera direction as a unit vector
* `get_look_vertical()`: pitch in radians
* Angle ranges between -pi/2 and pi/2, which are straight up and down
* Only affects formspecs shown after this is called.
* `get_formspec_prepend(formspec)`: returns a formspec string.
* `get_player_control()`: returns table with player pressed keys
- * The table consists of fields with boolean value representing the pressed
- keys, the fields are jump, right, left, LMB, RMB, sneak, aux1, down, up, zoom.
- * example: `{jump=false, right=true, left=false, LMB=false, RMB=false,
- sneak=true, aux1=false, down=false, up=false, zoom=false}`
- * The `zoom` field is available since 5.3
+ * The table consists of fields with the following boolean values
+ representing the pressed keys: `up`, `down`, `left`, `right`, `jump`,
+ `aux1`, `sneak`, `dig`, `place`, `LMB`, `RMB`, and `zoom`.
+ * The fields `LMB` and `RMB` are equal to `dig` and `place` respectively,
+ and exist only to preserve backwards compatibility.
* `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, 9/zoom (zoom available since 5.3)
+ keys. Bits:
+ * 0 - up
+ * 1 - down
+ * 2 - left
+ * 3 - right
+ * 4 - jump
+ * 5 - aux1
+ * 6 - sneak
+ * 7 - dig
+ * 8 - place
+ * 9 - zoom
* `set_physics_override(override_table)`
* `override_table` is a table with the following fields:
* `speed`: multiplier to default walking speed value (default: `1`)
* `hud_set_hotbar_selected_image(texturename)`
* sets image for selected item of hotbar
* `hud_get_hotbar_selected_image`: returns texturename
-* `set_sky(parameters)`
- * `parameters` is a table with the following optional fields:
+* `set_minimap_modes({mode, mode, ...}, selected_mode)`
+ * Overrides the available minimap modes (and toggle order), and changes the
+ selected mode.
+ * `mode` is a table consisting of up to four fields:
+ * `type`: Available type:
+ * `off`: Minimap off
+ * `surface`: Minimap in surface mode
+ * `radar`: Minimap in radar mode
+ * `texture`: Texture to be displayed instead of terrain map
+ (texture is centered around 0,0 and can be scaled).
+ Texture size is limited to 512 x 512 pixel.
+ * `label`: Optional label to display on minimap mode toggle
+ The translation must be handled within the mod.
+ * `size`: Sidelength or diameter, in number of nodes, of the terrain
+ displayed in minimap
+ * `texture`: Only for texture type, name of the texture to display
+ * `scale`: Only for texture type, scale of the texture map in nodes per
+ pixel (for example a `scale` of 2 means each pixel represents a 2x2
+ nodes square)
+ * `selected_mode` is the mode index to be selected after modes have been changed
+ (0 is the first mode).
+* `set_sky(sky_parameters)`
+ * The presence of the function `set_sun`, `set_moon` or `set_stars` indicates
+ whether `set_sky` accepts this format. Check the legacy format otherwise.
+ * `sky_parameters` is a table with the following optional fields:
* `base_color`: ColorSpec, changes fog in "skybox" and "plain".
* `type`: Available types:
* `"regular"`: Uses 0 textures, `base_color` ignored
* `clouds`: Boolean for whether clouds appear. (default: `true`)
* `sky_color`: A table containing the following values, alpha is ignored:
* `day_sky`: ColorSpec, for the top half of the `"regular"`
- sky during the day. (default: `#8cbafa`)
+ sky during the day. (default: `#61b5f5`)
* `day_horizon`: ColorSpec, for the bottom half of the
- `"regular"` sky during the day. (default: `#9bc1f0`)
+ `"regular"` sky during the day. (default: `#90d3f6`)
* `dawn_sky`: ColorSpec, for the top half of the `"regular"`
sky during dawn/sunset. (default: `#b4bafa`)
The resulting sky color will be a darkened version of the ColorSpec.
The resulting sky color will be a darkened version of the ColorSpec.
Warning: The darkening of the ColorSpec is subject to change.
* `night_sky`: ColorSpec, for the top half of the `"regular"`
- sky during the night. (default: `#006aff`)
+ sky during the night. (default: `#006bff`)
The resulting sky color will be a dark version of the ColorSpec.
Warning: The darkening of the ColorSpec is subject to change.
* `night_horizon`: ColorSpec, for the bottom half of the `"regular"`
abides by, `"custom"` uses `sun_tint` and `moon_tint`, while
`"default"` uses the classic Minetest sun and moon tinting.
Will use tonemaps, if set to `"default"`. (default: `"default"`)
+* `set_sky(base_color, type, {texture names}, clouds)`
+ * Deprecated. Use `set_sky(sky_parameters)`
+ * `base_color`: ColorSpec, defaults to white
+ * `type`: Available types:
+ * `"regular"`: Uses 0 textures, `bgcolor` ignored
+ * `"skybox"`: Uses 6 textures, `bgcolor` used
+ * `"plain"`: Uses 0 textures, `bgcolor` used
+ * `clouds`: Boolean for whether clouds appear in front of `"skybox"` or
+ `"plain"` custom skyboxes (default: `true`)
* `get_sky()`: returns base_color, type, table of textures, clouds.
* `get_sky_color()`: returns a table with the `sky_color` parameters as in
`set_sky`.
-* `set_sun(parameters)`:
- * `parameters` is a table with the following optional fields:
+* `set_sun(sun_parameters)`:
+ * `sun_parameters` is a table with the following optional fields:
* `visible`: Boolean for whether the sun is visible.
(default: `true`)
* `texture`: A regular texture for the sun. Setting to `""`
* `scale`: Float controlling the overall size of the sun. (default: `1`)
* `get_sun()`: returns a table with the current sun parameters as in
`set_sun`.
-* `set_moon(parameters)`:
- * `parameters` is a table with the following optional fields:
+* `set_moon(moon_parameters)`:
+ * `moon_parameters` is a table with the following optional fields:
* `visible`: Boolean for whether the moon is visible.
(default: `true`)
* `texture`: A regular texture for the moon. Setting to `""`
* `scale`: Float controlling the overall size of the moon (default: `1`)
* `get_moon()`: returns a table with the current moon parameters as in
`set_moon`.
-* `set_stars(parameters)`:
- * `parameters` is a table with the following optional fields:
+* `set_stars(star_parameters)`:
+ * `star_parameters` is a table with the following optional fields:
* `visible`: Boolean for whether the stars are visible.
(default: `true`)
* `count`: Integer number to set the number of stars in
* `scale`: Float controlling the overall size of the stars (default: `1`)
* `get_stars()`: returns a table with the current stars parameters as in
`set_stars`.
-* `set_clouds(parameters)`: set cloud parameters
- * `parameters` is a table with the following optional fields:
+* `set_clouds(cloud_parameters)`: set cloud parameters
+ * `cloud_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`).
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({x=0, y=79}, -- stand/idle animation key frames
- {x=168, y=187}, -- walk animation key frames
- {x=189, y=198}, -- dig animation key frames
- {x=200, y=219}, -- walk+dig animation key frames
- frame_speed=30) -- animation frame speed
-* `get_local_animation()`: returns stand, walk, dig, dig+walk tables and
+* `set_local_animation(idle, walk, dig, walk_while_dig, frame_speed)`:
+ set animation for player model in third person view.
+ * Every animation equals to a `{x=starting frame, y=ending frame}` table.
+ * `frame_speed` sets the animations frame speed. Default is 30.
+* `get_local_animation()`: returns idle, walk, dig, walk_while_dig tables and
`frame_speed`.
-* `set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})`: defines offset value for
- camera per player.
+* `set_eye_offset([firstperson, thirdperson])`: defines offset vectors for
+ camera per player. An argument defaults to `{x=0, y=0, z=0}` if unspecified.
* in first person view
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
-* `get_eye_offset()`: returns `offset_first` and `offset_third`
+* `get_eye_offset()`: returns first and third person offsets.
* `send_mapblock(blockpos)`:
* Sends a server-side loaded mapblock to the player.
* Returns `false` if failed.
-- in mods.
nametag = "",
- -- By default empty, for players their name is shown if empty
+ -- The name to display on the head of the object. By default empty.
+ -- If the object is a player, a nil or empty nametag is replaced by the player's name.
+ -- For all other objects, a nil or empty string removes the nametag.
+ -- To hide a nametag, set its color alpha to zero. That will disable it entirely.
nametag_color = <ColorSpec>,
- -- Sets color of nametag
+ -- Sets text color of nametag
+
+ nametag_bgcolor = <ColorSpec>,
+ -- Sets background color of nametag
+ -- `false` will cause the background to be set automatically based on user settings.
+ -- Default: false
infotext = "",
-- By default empty, text to be shown when pointed at object
shaded = true,
-- Setting this to 'false' disables diffuse lighting of entity
+
+ show_on_minimap = false,
+ -- Defaults to true for players, false for other entities.
+ -- If set to true the entity will show as a marker on the minimap.
}
Entity definition
-- Chance of triggering `action` per-node per-interval is 1.0 / this
-- value
+ min_y = -32768,
+ max_y = 32767,
+ -- min and max height levels where ABM will be processed
+ -- can be used to reduce CPU usage
+
catch_up = true,
-- If true, catch-up behaviour is enabled: The `chance` value is
-- temporarily reduced when returning to an area to simulate time lost
* `"image.png"`
* `{name="image.png", animation={Tile Animation definition}}`
-* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
- tileable_horizontal=bool, align_style="node"/"world"/"user", scale=int}`
+* `{name="image.png", backface_culling=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.
* 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`.
{
description = "Steel Axe",
+ -- Can contain new lines. "\n" has to be used as new line character.
+ -- See also: `get_description` in [`ItemStack`]
+
+ short_description = "Steel Axe",
+ -- Must not contain new lines.
+ -- Defaults to nil.
+ -- Use an [`ItemStack`] to get the short description, eg:
+ -- ItemStack(itemname):get_short_description()
groups = {},
-- key = name, value = rating; rating = 1..3.
liquids_pointable = false,
- -- See "Tools" section for an example including explanation
+ light_source = 0,
+ -- When used for nodes: Defines amount of light emitted by node.
+ -- Otherwise: Defines texture glow when viewed as a dropped item
+ -- To set the maximum (14), use the value 'minetest.LIGHT_MAX'.
+ -- A value outside the range 0 to minetest.LIGHT_MAX causes undefined
+ -- behavior.
+
+ -- See "Tool Capabilities" section for an example including explanation
tool_capabilities = {
full_punch_interval = 1.0,
max_drop_level = 0,
after_use = function(itemstack, user, node, digparams),
-- default: nil
-- If defined, should return an itemstack and will be called instead of
- -- wearing out the tool. If returns nil, does nothing.
+ -- wearing out the item (if tool). If returns nil, does nothing.
-- If after_use doesn't exist, it is the same as:
-- function(itemstack, user, node, digparams)
-- itemstack:add_wear(digparams.wear)
-- 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
+ use_texture_alpha = ...,
+ -- Specifies how the texture's alpha channel will be used for rendering.
+ -- possible values:
+ -- * "opaque": Node is rendered opaque regardless of alpha channel
+ -- * "clip": A given pixel is either fully see-through or opaque
+ -- depending on the alpha channel being below/above 50% in value
+ -- * "blend": The alpha channel specifies how transparent a given pixel
+ -- of the rendered node is
+ -- The default is "opaque" for drawtypes normal, liquid and flowingliquid;
+ -- "clip" otherwise.
+ -- If set to a boolean value (deprecated): true either sets it to blend
+ -- or clip, false sets it to clip or opaque mode depending on the drawtype.
palette = "palette.png",
-- The node's `param2` is used to select a pixel from the image.
-- If true, liquids flow into and replace this node.
-- Warning: making a liquid node 'floodable' will cause problems.
- liquidtype = "none", -- "none" / "source" / "flowing"
+ liquidtype = "none", -- specifies liquid physics
+ -- * "none": no liquid physics
+ -- * "source": spawns flowing liquid nodes at all 4 sides and below;
+ -- recommended drawtype: "liquid".
+ -- * "flowing": spawned from source, spawns more flowing liquid nodes
+ -- around it until `liquid_range` is reached;
+ -- will drain out without a source;
+ -- recommended drawtype: "flowingliquid".
+ -- If it's "source" or "flowing" and `liquid_range > 0`, then
+ -- both `liquid_alternative_*` fields must be specified
liquid_alternative_flowing = "", -- Flowing version of source liquid
leveled_max = 127,
-- Maximum value for `leveled` (0-127), enforced in
-- `minetest.set_node_level` and `minetest.add_node_level`.
+ -- Values above 124 might causes collision detection issues.
- liquid_range = 8, -- Number of flowing nodes around source (max. 8)
+ liquid_range = 8,
+ -- Maximum distance that flowing liquid nodes can spread around
+ -- source on flat land;
+ -- maximum = 8; set to 0 to disable liquid flow
drowning = 0,
-- Player will take this amount of damage if no bubbles are left
- light_source = 0,
- -- Amount of light emitted by node.
- -- To set the maximum (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
type = "fixed",
fixed = {
{-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16},
+ -- Node box format: see [Node boxes]
},
},
-- Custom selection box definition. Multiple boxes can be defined.
type = "fixed",
fixed = {
{-2 / 16, -0.5, -2 / 16, 2 / 16, 3 / 16, 2 / 16},
+ -- Node box format: see [Node boxes]
},
},
-- Custom collision box definition. Multiple boxes can be defined.
-- If "nodebox" drawtype is used and collision_box is nil, then node_box
-- definition is used for the collision box.
- -- Both of the boxes above are defined as:
- -- {xmin, ymin, zmin, xmax, ymax, zmax} in nodes from node center.
-- Support maps made in and before January 2012
legacy_facedir_simple = false,
-- While digging node.
-- If `"__group"`, then the sound will be
-- `default_dig_<groupname>`, where `<groupname>` is the
- -- name of the tool's digging group with the fastest digging time.
+ -- name of the item's digging group with the fastest digging time.
-- In case of a tie, one of the sounds will be played (but we
-- cannot predict which one)
-- Default value: `"__group"`
-- Node was placed. Also played after falling
place_failed = <SimpleSoundSpec>,
- -- When node placement failed
+ -- When node placement failed.
+ -- Note: This happens if the _built-in_ node placement failed.
+ -- This sound will still be played if the node is placed in the
+ -- `on_place` callback manually.
fall = <SimpleSoundSpec>,
- -- When node starts to fall
+ -- When node starts to fall or is detached
},
drop = "",
-- Name of dropped item when dug.
-- Default dropped item is the node itself.
- -- Using a table allows multiple items, drop chances and tool filtering.
- -- Tool filtering was undocumented until recently, tool filtering by string
- -- matching is deprecated.
+ -- Using a table allows multiple items, drop chances and item filtering.
+ -- Item filtering by string matching is deprecated.
drop = {
max_items = 1,
-- Maximum number of item lists to drop.
-- The entries in 'items' are processed in order. For each:
- -- Tool filtering is applied, chance of drop is applied, if both are
+ -- Item filtering is applied, chance of drop is applied, if both are
-- successful the entire item list is dropped.
-- Entry processing continues until the number of dropped item lists
-- equals 'max_items'.
items = {"default:diamond"},
},
{
- -- Only drop if using a tool whose name is identical to one
+ -- Only drop if using an item whose name is identical to one
-- of these.
tools = {"default:shovel_mese", "default:shovel_diamond"},
rarity = 5,
inherit_color = true,
},
{
- -- Only drop if using a tool whose name contains
- -- "default:shovel_" (this tool filtering by string matching
+ -- Only drop if using a item whose name contains
+ -- "default:shovel_" (this item filtering by string matching
-- is deprecated).
tools = {"~default:shovel_"},
rarity = 2,
on_dig = function(pos, node, digger),
-- default: minetest.node_dig
- -- By default checks privileges, wears out tool and removes node.
+ -- By default checks privileges, wears out item (if tool) and removes node.
+ -- return true if the node was dug successfully, false otherwise.
+ -- Deprecated: returning nil is the same as returning true.
on_timer = function(pos, elapsed),
-- default: nil
-- intensity: 1.0 = mid range of regular TNT.
-- If defined, called when an explosion touches the node, instead of
-- removing the node.
+
+ mod_origin = "modname",
+ -- stores which mod actually registered a node
+ -- if it can not find a source, returns "??"
+ -- useful for getting what mod truly registered something
+ -- example: if a node is registered as ":othermodname:nodename",
+ -- nodename will show "othermodname", but mod_orgin will say "modname"
}
Crafting recipes
{
type = "toolrepair",
- additional_wear = -0.02,
+ additional_wear = -0.02, -- multiplier of 65536
}
-Note: Tools with group `disable_repair=1` will not repairable by this recipe.
+Adds a shapeless recipe for *every* tool that doesn't have the `disable_repair=1`
+group. Player can put 2 equal tools in the craft grid to get one "repaired" tool
+back.
+The wear of the output is determined by the wear of both tools, plus a
+'repair bonus' given by `additional_wear`. To reduce the wear (i.e. 'repair'),
+you want `additional_wear` to be negative.
+
+The formula used to calculate the resulting wear is:
+
+ 65536 - ( (65536 - tool_1_wear) + (65536 - tool_2_wear) + 65536 * additional_wear )
+
+The result is rounded and can't be lower than 0. If the result is 65536 or higher,
+no crafting is possible.
### Cooking
spread = {x = 100, y = 100, z = 100},
seed = 23,
octaves = 3,
- persist = 0.7
+ persistence = 0.7
},
-- NoiseParams structure describing one of the perlin noises used for
-- ore distribution.
spread = {x = 100, y = 100, z = 100},
seed = 47,
octaves = 3,
- persist = 0.7
+ persistence = 0.7
},
np_puff_bottom = {
offset = 4,
spread = {x = 100, y = 100, z = 100},
seed = 11,
octaves = 3,
- persist = 0.7
+ persistence = 0.7
},
-- vein
spread = {x = 100, y = 100, z = 100},
seed = 17,
octaves = 3,
- persist = 0.7
+ persistence = 0.7
},
stratum_thickness = 8,
}
spread = {x = 100, y = 100, z = 100},
seed = 354,
octaves = 3,
- persist = 0.7,
+ persistence = 0.7,
lacunarity = 2.0,
flags = "absvalue"
},
func = function(name, param),
-- Called when command is run. Returns boolean success and text output.
+ -- Special case: The help message is shown to the player if `func`
+ -- returns false without a text output.
}
Note that in params, use of symbols is as follows:
{
hud_elem_type = "image", -- See HUD element types
- -- Type of element, can be "image", "text", "statbar", or "inventory"
+ -- Type of element, can be "image", "text", "statbar", "inventory",
+ -- "compass" or "minimap"
position = {x=0.5, y=0.5},
-- Left corner position of element
url = "http://example.org",
timeout = 10,
- -- Timeout for connection in seconds. Default is 3 seconds.
+ -- Timeout for request to be completed in seconds. Default depends on engine settings.
- post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
- -- Optional, if specified a POST request with post_data is performed.
+ method = "GET", "POST", "PUT" or "DELETE"
+ -- The http method to use. Defaults to "GET".
+
+ data = "Raw request data string" OR {field1 = "data1", field2 = "data2"},
+ -- Data for the POST, PUT or DELETE request.
-- Accepts both a string and a table. If a table is specified, encodes
-- table as x-www-form-urlencoded key-value pairs.
- -- If post_data is not specified, a GET request is performed instead.
user_agent = "ExampleUserAgent",
-- Optional, if specified replaces the default minetest user agent with
multipart = boolean
-- Optional, if true performs a multipart HTTP request.
-- Default is false.
+ -- Post only, data must be array
+
+ post_data = "Raw POST request data string" OR {field1 = "data1", field2 = "data2"},
+ -- Deprecated, use `data` instead. Forces `method = "POST"`.
}
`HTTPRequestResult` definition
projects / dragonfireclient.git / blobdiff