From 5cb6f85799359125c99e09a6f9da83a9de382b0e Mon Sep 17 00:00:00 2001 From: rubenwardy Date: Sun, 28 Dec 2014 19:26:49 +0000 Subject: [PATCH] Add lua_api.html --- _includes/header.html | 1 + lua_api.html | 4117 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 4118 insertions(+) create mode 100644 lua_api.html diff --git a/_includes/header.html b/_includes/header.html index 4e2428f..4bc1222 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -15,6 +15,7 @@
  • 4 - Formspecs
  • Index
    • +
  • Webpage version of lua_api.txt

    • {{ page.title }}

    diff --git a/lua_api.html b/lua_api.html new file mode 100644 index 0000000..b395640 --- /dev/null +++ b/lua_api.html @@ -0,0 +1,4117 @@ +--- +title: Minetest Lua Modding API Reference 0.4.11 +layout: default +--- + +

    Introduction

    + + + +

    Content and functionality can be added to Minetest 0.4 by using Lua +scripting in run-time loaded mods.

    + +

    A mod is a self-contained bunch of scripts, textures and other related +things that is loaded by and interfaces with Minetest.

    + +

    Mods are contained and ran solely on the server side. Definitions and media +files are automatically transferred to the client.

    + +

    If you see a deficiency in the API, feel free to attempt to add the +functionality in the engine and API. You can send such improvements as +source code patches to celeron55@gmail.com.

    + +

    This may not be the most up to date version. See lua_api.txt

    + + + +

    Programming in Lua

    + +

    If you have any difficulty in understanding this, please read Programming in Lua.

    + +

    Startup

    + +

    Mods are loaded during server startup from the mod load paths by running +the init.lua scripts in a shared environment.

    + +

    Paths

    + + + +

    Games

    + +

    Games are looked up from:

    + + + +

    where gameid is unique to each game.

    + +

    The game directory contains the file game.conf, which contains these fields:

    + +
    name = <Human-readable full name of the game>
+
    + +

    e.g.

    + +
    name = Minetest
+
    + +

    The game directory can contain the file minetest.conf, which will be used +to set default settings when running the particular game.

    + +

    Mod load path

    + +

    Generic:

    + + + +

    In a run-in-place version (e.g. the distributed windows version):

    + + + +

    On an installed version on Linux:

    + + + +

    Mod load path for world-specific games

    + +

    It is possible to include a game in a world; in this case, no mods or +games are loaded or checked from anywhere else.

    + +

    This is useful for e.g. adventure worlds.

    + +

    This happens if the following directory exists:

    + +
    $world/game/
+
    + +

    Mods should be then be placed in:

    + +
    $world/game/mods/
+
    + +

    Modpack support

    + +

    Mods can be put in a subdirectory, if the parent directory, which otherwise +should be a mod, contains a file named modpack.txt. This file shall be +empty, except for lines starting with #, which are comments.

    + +

    Mod directory structure

    + +
    mods
+|-- modname
+|   |-- depends.txt
+|   |-- screenshot.png
+|   |-- description.txt
+|   |-- init.lua
+|   |-- models
+|   |-- textures
+|   |   |-- modname_stuff.png
+|   |   `-- modname_something_else.png
+|   |-- sounds
+|   |-- media
+|   `-- <custom data>
+`-- another
+
    + +

    modname

    + +

    The location of this directory can be fetched by using +minetest.get_modpath(modname).

    + +

    depends.txt

    + +

    List of mods that have to be loaded before loading this mod.

    + +

    A single line contains a single modname.

    + +

    Optional dependencies can be defined by appending a question mark +to a single modname. Their meaning is that if the specified mod +is missing, that does not prevent this mod from being loaded.

    + +

    screenshot.png

    + +

    A screenshot shown in modmanager within mainmenu.

    + +

    description.txt

    + +

    A File containing description to be shown within mainmenu.

    + +

    init.lua

    + +

    The main Lua script. Running this script should register everything it +wants to register. Subsequent execution depends on minetest calling the +registered callbacks.

    + +

    minetest.setting_get(name) and minetest.setting_getbool(name) can be used +to read custom or existing settings at load time, if necessary.

    + +

    models

    + +

    Models for entities or meshnodes.

    + +

    textures, sounds, media

    + +

    Media files (textures, sounds, whatever) that will be transferred to the +client and will be available for use by the mod.

    + +

    Naming convention for registered textual names

    + +

    Registered names should generally be in this format:

    + +
    "modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
+
    + +

    This is to prevent conflicting names from corrupting maps and is +enforced by the mod loader.

    + +

    Example

    + +

    In the mod experimental, there is the ideal item/node/entity name tnt. +So the name should be experimental:tnt.

    + +

    Enforcement can be overridden by prefixing the name with :. This can +be used for overriding the registrations of some other mod.

    + +

    Example: Any mod can redefine experimental:tnt by using the name

    + +
    :experimental:tnt
+
    + +

    when registering it. +(also that mod is required to have experimental as a dependency)

    + +

    The : prefix can also be used for maintaining backwards compatibility.

    + +

    Aliases

    + +

    Aliases can be added by using minetest.register_alias(name, convert_to).

    + +

    This will make Minetest to convert things called name to things called +convert_to.

    + +

    This can be used for maintaining backwards compatibility.

    + +

    This can be also used for setting quick access names for things, e.g. if +you have an item called epiclylongmodname:stuff, you could do

    + +
    minetest.register_alias("stuff", "epiclylongmodname:stuff")
+
    + +

    and be able to use /giveme stuff.

    + +

    Textures

    + +

    Mods should generally prefix their textures with modname_, e.g. given +the mod name foomod, a texture could be called:

    + +
    foomod_foothing.png
+
    + +

    Textures are referred to by their complete name, or alternatively by +stripping out the file extension:

    + + + +

    Texture modifiers

    + +

    There are various texture modifiers that can be used +to generate textures on-the-fly.

    + +

    Texture overlaying

    + +

    Textures can be overlaid by putting a ^ between them.

    + +

    Example:

    + +
    default_dirt.png^default_grass_side.png
+
    + +

    default_grass_side.png is overlayed over default_dirt.png.

    + +

    Texture grouping

    + +

    Textures can be grouped together by enclosing them in ( and ).

    + +

    Example: cobble.png^(thing1.png^thing2.png)

    + +

    A texture for thing1.png^thing2.png is created and the resulting +texture is overlaid over cobble.png.

    + +

    Advanced texture modifiers

    + +

    [crack:<n>:<p>

    + + + +

    Draw a step of the crack animation on the texture.

    + +

    Example:

    + +
    default_cobble.png^[crack:10:1
+
    + +

    [combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>

    + + + +

    Create a texture of size <w> times <h> and blit <file1> to (<x1>,<y1>) +and blit <file2> to (<x2>,<y2>).

    + +

    Example:

    + +
    [combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
+
    + +

    [brighten

    + +

    Brightens the texture.

    + +

    Example:

    + +
    tnt_tnt_side.png^[brighten
+
    + +

    [noalpha

    + +

    Makes the texture completely opaque.

    + +

    Example:

    + +
    default_leaves.png^[noalpha
+
    + +

    [makealpha:<r>,<g>,<b>

    + +

    Convert one color to transparency.

    + +

    Example:

    + +
    default_cobble.png^[makealpha:128,128,128
+
    + +

    [transform<t>

    + + + +

    Rotates and/or flips the image.

    + +

    <t> can be a number (between 0 and 7) or a transform name. +Rotations are counter-clockwise.

    + +
    0  I      identity
+1  R90    rotate by 90 degrees
+2  R180   rotate by 180 degrees
+3  R270   rotate by 270 degrees
+4  FX     flip X
+5  FXR90  flip X then rotate by 90 degrees
+6  FY     flip Y
+7  FYR90  flip Y then rotate by 90 degrees
+
    + +

    Example:

    + +
    default_stone.png^[transformFXR90
+
    + +

    [inventorycube{<top>{<left>{<right>

    + +

    ^ is replaced by & in texture names.

    + +

    Create an inventory cube texture using the side textures.

    + +

    Example:

    + +
    [inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png
+
    + +

    Creates an inventorycube with grass.png, dirt.png^grass_side.png and +dirt.png^grass_side.png textures

    + +

    [lowpart:<percent>:<file>

    + +

    Blit the lower <percent>% part of <file> on the texture.

    + +

    Example:

    + +
    base.png^[lowpart:25:overlay.png
+
    + +

    [verticalframe:<t>:<n>

    + + + +

    Crops the texture to a frame of a vertical animation.

    + +

    Example:

    + +
    default_torch_animated.png^[verticalframe:16:8
+
    + +

    [mask:<file>

    + +

    Apply a mask to the base image.

    + +

    The mask is applied using binary AND.

    + +

    [colorize:<color>

    + +

    Colorize the textures with the given color. +<color> is specified as a ColorString.

    + +

    Sounds

    + +

    Only Ogg Vorbis files are supported.

    + +

    For positional playing of sounds, only single-channel (mono) files are +supported. Otherwise OpenAL will play them non-positionally.

    + +

    Mods should generally prefix their sounds with modname_, e.g. given +the mod name "foomod", a sound could be called:

    + +
    foomod_foosound.ogg
+
    + +

    Sounds are referred to by their name with a dot, a single digit and the +file extension stripped out. When a sound is played, the actual sound file +is chosen randomly from the matching sounds.

    + +

    When playing the sound foomod_foosound, the sound is chosen randomly +from the available ones of the following files:

    + + + +

    Examples of sound parameter tables:

    + +
    -- Play location-less on all clients
+{
+    gain = 1.0, -- default
+}
+-- Play location-less to a player
+{
+    to_player = name,
+    gain = 1.0, -- default
+}
+-- Play in a location
+{
+    pos = {x=1,y=2,z=3},
+    gain = 1.0, -- default
+    max_hear_distance = 32, -- default
+}
+-- Play connected to an object, looped
+{
+    object = <an ObjectRef>,
+    gain = 1.0, -- default
+    max_hear_distance = 32, -- default
+    loop = true, -- only sounds connected to objects can be looped
+}
+
    + +

    SimpleSoundSpec

    + + + +

    Registered definitions of stuff

    + +

    Anything added using certain minetest.register_* functions get added to +the global minetest.registered_* tables.

    + + + +

    Note that in some cases you will stumble upon things that are not contained +in these tables (e.g. when a mod has been removed). Always check for +existence before trying to access the fields.

    + +

    Example: If you want to check the drawtype of a node, you could do:

    + +
    local function get_nodedef_field(nodename, fieldname)
+    if not minetest.registered_nodes[nodename] then
+        return nil
+    end
+    return minetest.registered_nodes[nodename][fieldname]
+end
+local drawtype = get_nodedef_field(nodename, "drawtype")
+
    + +

    Example: minetest.get_item_group(name, group) has been implemented as:

    + +
    function minetest.get_item_group(name, group)
+    if not minetest.registered_items[name] or not
+            minetest.registered_items[name].groups[group] then
+        return 0
+    end
+    return minetest.registered_items[name].groups[group]
+end
+
    + +

    Nodes

    + +

    Nodes are the bulk data of the world: cubes and other things that take the +space of a cube. Huge amounts of them are handled efficiently, but they +are quite static.

    + +

    The definition of a node is stored and can be accessed by name in

    + +
    minetest.registered_nodes[node.name]
+
    + +

    See "Registered definitions of stuff".

    + +

    Nodes are passed by value between Lua and the engine. +They are represented by a table:

    + +
    {name="name", param1=num, param2=num}
+
    + +

    param1 and param2 are 8-bit integers. The engine uses them for certain +automated functions. If you don't use these functions, you can use them to +store arbitrary values.

    + +

    The functions of param1 and param2 are determined by certain fields in the +node definition:

    + +

    param1 is reserved for the engine when paramtype != "none":

    + +
    paramtype = "light"
+^ The value stores light with and without sun in it's
+  upper and lower 4 bits.
+
    + +

    param2 is reserved for the engine when any of these are used:

    + +
    liquidtype == "flowing"
+^ The level and some flags of the liquid is stored in param2
+drawtype == "flowingliquid"
+^ The drawn liquid level is read from param2
+drawtype == "torchlike"
+drawtype == "signlike"
+paramtype2 == "wallmounted"
+^ The rotation of the node is stored in param2. You can make this value
+  by using minetest.dir_to_wallmounted().
+paramtype2 == "facedir"
+^ The rotation of the node is stored in param2. Furnaces and chests are
+  rotated this way. Can be made by using minetest.dir_to_facedir().
+  Values range 0 - 23
+  facedir modulo 4 = axisdir
+  0 = y+    1 = z+    2 = z-    3 = x+    4 = x-    5 = y-
+  facedir's two less significant bits are rotation around the axis
+paramtype2 == "leveled"
+collision_box = {
+  type = "fixed",
+  fixed = {
+            {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
+  },
+},
+^ defines list of collision boxes for the node. If empty, collision boxes
+  will be the same as nodeboxes, in case of any other nodes will be full cube
+  as in the example above.
+
    + +

    Nodes can also contain extra data. See "Node Metadata".

    + +

    Node drawtypes

    + +

    There are a bunch of different looking node types.

    + +

    Look for examples in games/minimal or games/minetest_game.

    + + + +

    *_optional drawtypes need less rendering time if deactivated (always client side).

    + +

    Node boxes

    + +

    Node selection boxes are defined using "node boxes"

    + +

    The nodebox node drawtype allows defining visual of nodes consisting of +arbitrary number of boxes. It allows defining stuff like stairs. Only the +fixed and leveled box type is supported for these.

    + +

    Please note that this is still experimental, and may be incompatibly +changed in the future.

    + +

    A nodebox is defined as any of:

    + +
    {
+    -- A normal cube; the default in most things
+    type = "regular"
+}
+{
+    -- A fixed box (facedir param2 is used, if applicable)
+    type = "fixed",
+    fixed = box OR {box1, box2, ...}
+}
+{
+    -- A box like the selection box for torches
+    -- (wallmounted param2 is used, if applicable)
+    type = "wallmounted",
+    wall_top = box,
+    wall_bottom = box,
+    wall_side = box
+}
+
    + +

    A box is defined as:

    + +
    {x1, y1, z1, x2, y2, z2}
+
    + +

    A box of a regular node would look like:

    + +
    {-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
+
    + +

    type = "leveled" is same as type = "fixed", but y2 will be automatically +set to level from param2.

    + +

    Meshes

    + +

    If drawtype mesh is used, tiles should hold model materials textures. +Only static meshes are implemented. +For supported model formats see Irrlicht engine documentation.

    + +

    Noise Parameters

    + +

    Noise Parameters, or commonly called "NoiseParams", define the properties of perlin noise.

    + +

    offset

    + +

    Offset that the noise is translated by (i.e. added) after calculation.

    + +

    scale

    + +

    Factor that the noise is scaled by (i.e. multiplied) after calculation.

    + +

    spread

    + +

    Vector containing values by which each coordinate is divided by before calculation. +Higher spread values result in larger noise features.

    + +

    A value of {x=250, y=250, z=250} is common.

    + +

    seed

    + +

    Random seed for the noise. Add the world seed to a seed offset for world-unique noise. +In the case of minetest.get_perlin(), this value has the world seed automatically added.

    + +

    octaves

    + +

    Number of times the noise gradient is accumulated into the noise.

    + +

    Increase this number to increase the amount of detail in the resulting noise.

    + +

    A value of 6 is common.

    + +

    persistence

    + +

    Factor by which the effect of the noise gradient function changes with each successive octave.

    + +

    Values less than 1 make the details of successive octaves' noise diminish, while values +greater than 1 make successive octaves stronger.

    + +

    A value of 0.6 is common.

    + +

    lacunarity

    + +

    Factor by which the noise feature sizes change with each successive octave.

    + +

    A value of 2.0 is common.

    + +

    flags

    + +

    Leave this field unset for no special handling.

    + +

    Currently supported are defaults, eased and absvalue.

    + +

    defaults

    + +

    Specify this if you would like to keep auto-selection of eased/not-eased while specifying +some other flags.

    + +

    eased

    + +

    Maps noise gradient values onto a quintic S-curve before performing interpolation. +This results in smooth, rolling noise. Disable this (noeased) for sharp-looking noise. +If no flags are specified (or defaults is), 2D noise is eased and 3D noise is not eased.

    + +

    absvalue

    + +

    Accumulates the absolute value of each noise gradient result.

    + +

    Noise parameters format example for 2D or 3D perlin noise or perlin noise maps: + np_terrain = { + offset = 0, + scale = 1, + spread = {x=500, y=500, z=500}, + seed = 571347, + octaves = 5, + persist = 0.63, + lacunarity = 2.0, + flags = "defaults, absvalue" + } + ^ A single noise parameter table can be used to get 2D or 3D noise, + when getting 2D noise spread.z is ignored.

    + +

    Ore types

    + +

    These tell in what manner the ore is generated.

    + +

    All default ores are of the uniformly-distributed scatter type.

    + +

    scatter

    + +

    Randomly chooses a location and generates a cluster of ore.

    + +

    If noise_params is specified, the ore will be placed if the 3D perlin noise at +that point is greater than the noise_threshold, giving the ability to create a non-equal +distribution of ore.

    + +

    sheet

    + +

    Creates a sheet of ore in a blob shape according to the 2D perlin noise described by noise_params. +The relative height of the sheet can be controlled by the same perlin noise as well, by specifying +a non-zero scale parameter in noise_params.

    + +

    IMPORTANT: The noise is not transformed by offset or scale when comparing against the noise +threshold, but scale is used to determine relative height. +The height of the blob is randomly scattered, with a maximum height of clust_size.

    + +

    clust_scarcity and clust_num_ores are ignored.

    + +

    This is essentially an improved version of the so-called "stratus" ore seen in some unofficial mods.

    + +

    claylike -- not yet implemented

    + +

    Places ore if there are no more than clust_scarcity number of specified nodes within a Von Neumann +neighborhood of clust_size radius.

    + +

    Ore attributes

    + +

    See section "Flag Specifier Format".

    + +

    Currently supported flags: absheight

    + +

    absheight

    + +

    Also produce this same ore between the height range of -height_max and -height_min.

    + +

    Useful for having ore in sky realms without having to duplicate ore entries.

    + +

    Decoration types

    + +

    The varying types of decorations that can be placed.

    + +

    The default value is simple, and is currently the only type supported.

    + +

    simple

    + +

    Creates a 1 times H times 1 column of a specified node (or a random node from a list, if a +decoration list is specified). Can specify a certain node it must spawn next to, such as water or +lava, for example. Can also generate a decoration of random height between a specified lower and +upper bound. This type of decoration is intended for placement of grass, flowers, cacti, papyri, +and so on.

    + +

    schematic

    + +

    Copies a box of MapNodes from a specified schematic file (or raw description). Can specify a +probability of a node randomly appearing when placed. This decoration type is intended to be used +for multi-node sized discrete structures, such as trees, cave spikes, rocks, and so on.

    + +

    Schematic specifier

    + +

    A schematic specifier identifies a schematic by either a filename to a Minetest Schematic file (.mts) +or through raw data supplied through Lua, in the form of a table. This table must specify two fields:

    + + + +

    Important: The default value for param1 in MapNodes here is 255, which represents "always place".

    + +

    In the bulk MapNode data, param1, instead of the typical light values, instead represents the +probability of that node appearing in the structure.

    + +

    When passed to minetest.create_schematic, probability is an integer value ranging from 0 to 255:

    + + + +

    Important note: Node aliases cannot be used for a raw schematic provided when registering as a decoration.

    + +

    Schematic attributes

    + +

    See section "Flag Specifier Format".

    + +

    Currently supported flags: place_center_x, place_center_y, place_center_z.

    + + + +

    HUD element types

    + +

    The position field is used for all element types.

    + +

    To account for differing resolutions, the position coordinates are the percentage of the screen, +ranging in value from 0 to 1.

    + +

    The name field is not yet used, but should contain a description of what the HUD element represents. +The direction field is the direction in which something is drawn.

    + +

    0 draws from left to right, 1 draws from right to left, 2 draws from top to bottom, +and 3 draws from bottom to top.

    + +

    The alignment field specifies how the item will be aligned. It ranges from -1 to 1, +with 0 being the center, -1 is moved to the left/up, and 1 is to the right/down. +Fractional values can be used.

    + +

    The offset field specifies a pixel offset from the position. Contrary to position, +the offset is not scaled to screen size. This allows for some precisely-positioned +items in the HUD.

    + +

    Note: offset will adapt to screen DPI as well as user defined scaling factor!

    + +

    Below are the specific uses for fields in each type; fields not listed for that type are ignored.

    + +

    Note: Future revisions to the HUD API may be incompatible; the HUD API is still in the experimental stages.

    + +

    image

    + +

    Displays an image on the HUD.

    + + + +

    text

    + +

    Displays text on the HUD.

    + + + +

    statbar

    + +

    Displays a horizontal bar made up of half-images.

    + + + +

    inventory

    + + + +

    waypoint

    + +

    Displays distance to selected world position.

    + + + +

    Representations of simple things

    + +

    Position/vector

    + +
    {x=num, y=num, z=num}
+
    + +

    For helper functions see "Vector helpers".

    + +

    pointed_thing

    + + + +

    Flag Specifier Format

    + +

    Flags using the standardized flag specifier format can be specified in either of two ways, by string or table.

    + +

    The string format is a comma-delimited set of flag names; whitespace and unrecognized flag fields are ignored. +Specifying a flag in the string sets the flag, and specifying a flag prefixed by the string "no" explicitly +clears the flag from whatever the default may be.

    + +

    In addition to the standard string flag format, the schematic flags field can also be a table of flag names +to boolean values representing whether or not the flag is set. Additionally, if a field with the flag name +prefixed with "no" is present, mapped to a boolean of any value, the specified flag is unset.

    + +

    E.g. A flag field of value

    + +
    {place_center_x = true, place_center_y=false, place_center_z=true}
+
    + +

    is equivalent to

    + +
    {place_center_x = true, noplace_center_y=true, place_center_z=true}
+
    + +

    which is equivalent to

    + +
    "place_center_x, noplace_center_y, place_center_z"
+
    + +

    or even

    + +
    "place_center_x, place_center_z"
+
    + +

    since, by default, no schematic attributes are set.

    + +

    Items

    + +

    Item types

    + +

    There are three kinds of items: nodes, tools and craftitems.

    + + + +

    Item formats

    + +

    Items and item stacks can exist in three formats: Serializes, table format +and ItemStack.

    + +

    Serialized

    + +

    This is called "stackstring" or "itemstring":

    + + + +

    Table format

    + +

    Examples:

    + +

    5 dirt nodes:

    + +
    {name="default:dirt", count=5, wear=0, metadata=""}
+
    + +

    A wooden pick about 1/3 worn out:

    + +
    {name="default:pick_wood", count=1, wear=21323, metadata=""}
+
    + +

    An apple:

    + +
    {name="default:apple", count=1, wear=0, metadata=""}
+
    + +

    ItemStack

    + +

    A native C++ format with many helper methods. Useful for converting +between formats. See the Class reference section for details.

    + +

    When an item must be passed to a function, it can usually be in any of +these formats.

    + +

    Groups

    + +

    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 +the thing without actually knowing what the thing is.

    + +

    Usage

    + +

    Groups are stored in a table, having the group names with keys and the +group ratings as values. For example:

    + +
    groups = {crumbly=3, soil=1}
+-- ^ Default dirt
+
+groups = {crumbly=2, soil=1, level=2, outerspace=1}
+-- ^ A more special dirt-kind of thing
+
    + +

    Groups always have a rating associated with them. If there is no +useful meaning for a rating for an enabled group, it shall be 1.

    + +

    When not defined, the rating of a group defaults to 0. Thus when you +read groups, you must interpret nil and 0 as the same value, 0.

    + +

    You can read the rating of a group for an item or a node by using

    + +
    minetest.get_item_group(itemname, groupname)
+
    + +

    Groups of items

    + +

    Groups of items can define what kind of an item it is (e.g. wool).

    + +

    Groups of nodes

    + +

    In addition to the general item things, groups are used to define whether +a node is destroyable and how long it takes to destroy by a tool.

    + +

    Groups of entities

    + +

    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. +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 in tools define which groups of nodes and entities they are +effective towards.

    + +

    Groups in crafting recipes

    + +

    An example: Make meat soup from any meat, any water and any bowl:

    + +
    {
+    output = 'food:meat_soup_raw',
+    recipe = {
+        {'group:meat'},
+        {'group:water'},
+        {'group:bowl'},
+    },
+    -- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
+}
+
    + +

    Another example: Make red wool from white wool and red dye:

    + +
    {
+    type = 'shapeless',
+    output = 'wool:red',
+    recipe = {'wool:white', 'group:dye,basecolor_red'},
+}
+
    + +

    Special groups

    + + + +

    Known damage and digging time defining groups

    + + + +

    Examples of custom groups

    + +

    Item groups are often used for defining, well, groups of items. +* meat: any meat-kind of a thing (rating might define the size or healing + ability or be irrelevant -- it is not defined as of yet) +* eatable: anything that can be eaten. Rating might define HP gain in half + hearts. +* flammable: can be set on fire. Rating might define the intensity of the + fire, affecting e.g. the speed of the spreading of an open fire. +* wool: any wool (any origin, any color) +* metal: any metal +* weapon: any weapon +* heavy: anything considerably heavy

    + +

    Digging time calculation specifics

    + +

    Groups such as crumbly, cracky and snappy are used for this +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.

    + +

    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 +cannot dig other groups; thus it is important to use a standard bunch of +groups to enable interaction with tools.

    + +

    Tools definition

    + +

    Tools define:

    + + + +

    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 +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).

    + +

    This is not automated; it is the responsibility of the node definition +to implement this.

    + +

    Uses

    + +

    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 +is multiplied by 3^leveldiff.

    + + + +

    Maximum level

    + +

    Tells what is the maximum level of a node of this group that the tool will +be able to dig.

    + +

    Digging times

    + +

    List of digging times for different ratings of the group, for nodes of the +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 +for this group, and unable to dig the rating 1, which is the toughest. +Unless there is a matching group that enables digging otherwise.

    + +

    Damage groups

    + +

    List of damage for groups of entities. See "Entity damage mechanism".

    + +

    Example definition of the capabilities of a tool

    + +
    tool_capabilities = {
+    full_punch_interval=1.5,
+    max_drop_level=1,
+    groupcaps={
+        crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
+    }
+    damage_groups = {fleshy=2},
+}
+
    + +

    This makes the tool be able to dig nodes that fulfil both of these:

    + + + +

    Table of resulting digging times:

    + +
    crumbly        0     1     2     3     4  <- level
+     ->  0     -     -     -     -     -
+         1  0.80  1.60  1.60     -     -
+         2  0.60  1.20  1.20     -     -
+         3  0.40  0.80  0.80     -     -
+
+level diff:    2     1     0    -1    -2
+
    + +

    Table of resulting tool uses:

    + +
    ->  0     -     -     -     -     -
+    1   180    60    20     -     -
+    2   180    60    20     -     -
+    3   180    60    20     -     -
+
    + +

    Notes:

    + + + +

    Entity damage mechanism

    + +

    Damage calculation:

    + +
    damage = 0
+foreach group in cap.damage_groups:
+    damage += cap.damage_groups[group] * limit(actual_interval / cap.full_punch_interval, 0.0, 1.0)
+        * (object.armor_groups[group] / 100.0)
+        -- Where object.armor_groups[group] is 0 for inexistent values
+return damage
+
    + +

    Client predicts damage based on damage groups. Because of this, it is able to +give an immediate response when an entity is damaged or dies; the response is +pre-defined somehow (e.g. by defining a sprite animation) (not implemented; +TODO). +Currently a smoke puff will appear when an entity dies.

    + +

    The group immortal completely disables normal damage.

    + +

    Entities can define a special armor group, which is punch_operable. This +group 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.

    + +

    On the Lua side, every punch calls:

    + +
    entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction)
+
    + +

    This should never be called directly, because damage is usually not handled by the entity +itself.

    + + + +

    To punch an entity/object in Lua, call:

    + +
    object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
+
    + + + +

    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".

    + +

    Metadata contains two things: +* A key-value store +* An inventory

    + +

    Some of the values in the key-value store are handled specially: +* formspec: Defines a right-click inventory menu. See "Formspec". +* infotext: Text shown on the screen when the node is pointed at

    + +

    Example stuff:

    + +
    local meta = minetest.get_meta(pos)
+meta:set_string("formspec",
+        "size[8,9]"..
+        "list[context;main;0,0;8,4;]"..
+        "list[current_player;main;0,5;8,4;]")
+meta:set_string("infotext", "Chest");
+local inv = meta:get_inventory()
+inv:set_size("main", 8*4)
+print(dump(meta:to_table()))
+meta:from_table({
+    inventory = {
+        main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", [5] = "", [6] = "",
+                [7] = "", [8] = "", [9] = "", [10] = "", [11] = "", [12] = "", [13] = "",
+                [14] = "default:cobble", [15] = "", [16] = "", [17] = "", [18] = "",
+                [19] = "", [20] = "default:cobble", [21] = "", [22] = "", [23] = "",
+                [24] = "", [25] = "", [26] = "", [27] = "", [28] = "", [29] = "", [30] = "",
+                [31] = "", [32] = ""}
+    },
+    fields = {
+        formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
+        infotext = "Chest"
+    }
+})
+
    + +

    Formspec

    + +

    Formspec defines a menu. Currently not much else than inventories are +supported. It is a string, with a somewhat strange format.

    + +

    Spaces and newlines can be inserted between the blocks, as is used in the +examples.

    + +

    Examples

    + +

    Chest

    + +
    size[8,9]
+list[context;main;0,0;8,4;]
+list[current_player;main;0,5;8,4;]
+
    + +

    Furnace

    + +
    size[8,9]
+list[context;fuel;2,3;1,1;]
+list[context;src;2,1;1,1;]
+list[context;dst;5,1;2,2;]
+list[current_player;main;0,5;8,4;]
+
    + +

    Minecraft-like player inventory

    + +
    size[8,7.5]
+image[1,0.6;1,2;player.png]
+list[current_player;main;0,3.5;8,4;]
+list[current_player;craft;3,0;3,3;]
+list[current_player;craftpreview;7,1;1,1;]
+
    + +

    Elements

    + +

    size[<W>,<H>,<fixed_size>]

    + + + +

    list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]

    + + + +

    list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]

    + + + +

    listcolors[<slot_bg_normal>;<slot_bg_hover>]

    + + + +

    listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]

    + + + +

    listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]

    + + + +

    tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>,<fontcolor>]

    + + + +

    image[<X>,<Y>;<W>,<H>;<texture name>]

    + + + +

    item_image[<X>,<Y>;<W>,<H>;<item name>]

    + + + +

    bgcolor[<color>;<fullscreen>]

    + + + +

    background[<X>,<Y>;<W>,<H>;<texture name>]

    + + + +

    background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]

    + + + +

    pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]

    + + + +

    field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]

    + + + +

    field[<name>;<label>;<default>]

    + + + +

    textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]

    + + + +

    label[<X>,<Y>;<label>]

    + + + +

    vertlabel[<X>,<Y>;<label>]

    + + + +

    button[<X>,<Y>;<W>,<H>;<name>;<label>]

    + + + +

    image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]

    + + + +

    image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]

    + + + +

    item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]

    + + + +

    button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]

    + + + +

    image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]

    + + + +

    textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]

    + + + +

    textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]

    + + + +

    tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]

    + + + +

    box[<X>,<Y>;<W>,<H>;<color>]

    + + + +

    dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]

    + + + +

    checkbox[<X>,<Y>;<name>;<label>;<selected>;<tooltip>]

    + + + +

    scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]

    + + + +

    table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]

    + + + +

    tableoptions[<opt 1>;<opt 2>;...]

    + + + +

    tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]

    + + + +

    Note: do not use a element name starting with key_; those names are reserved to +pass key press events to formspec!

    + +

    Inventory locations

    + + + +

    ColorString

    + +

    #RGB defines a color in hexadecimal format.

    + +

    #RGBA defines a color in hexadecimal format and alpha channel.

    + +

    #RRGGBB defines a color in hexadecimal format.

    + +

    #RRGGBBAA defines a color in hexadecimal format and alpha channel.

    + +

    Named colors are also supported and are equivalent to +CSS Color Module Level 4. +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.

    + +

    Vector helpers

    + + + +

    For the following functions x can be either a vector or a number:

    + + + +

    Helper functions

    + + + +

    minetest namespace reference

    + +

    Utilities

    + + + +

    Example of minetest.get_player_information return value:

    + +
    {
+    address = "127.0.0.1",     -- IP address of client
+    ip_version = 4,            -- IPv4 / IPv6
+    min_rtt = 0.01,            -- minimum round trip time
+    max_rtt = 0.2,             -- maximum round trip time
+    avg_rtt = 0.02,            -- average round trip time
+    min_jitter = 0.01,         -- minimum packet time jitter
+    max_jitter = 0.5,          -- maximum packet time jitter
+    avg_jitter = 0.03,         -- average packet time jitter
+    connection_uptime = 200,   -- seconds since client connected
+
+    -- 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
+    --vers_string = "0.4.9-git", -- full version string
+    --state = "Active"           -- current client state
+}
+
    + +

    Logging

    + + + +

    Registration functions

    + +

    Call these functions only at load time!

    + + + +

    Global callback registration functions

    + +

    Call these functions only at load time!

    + + + +

    Other registration functions

    + + + +

    Setting-related

    + + + +

    Authentication

    + + + +

    minetest.set_player_password, minetest_set_player_privs, minetest_get_player_privs +and minetest.auth_reload call the authetification handler.

    + +

    Chat

    + + + +

    Environment access

    + + + +

    Inventory

    + +

    minetest.get_inventory(location): returns an InvRef

    + + + +

    Formspec

    + + + +

    Item handling

    + + + +

    Rollback

    + + + +

    Defaults for the on_* item definition functions

    + +

    These functions return the leftover itemstack.

    + + + +

    Defaults for the on_punch and on_dig node definition callbacks

    + + + +

    Sounds

    + + + +

    Timing

    + + + +

    Server

    + + + +

    Bans

    + + + +

    Particles

    + + + +

    Schematics

    + + + +

    Misc.

    + + + +

    Please note that forceloaded areas are saved when the server restarts.

    + +

    Global objects

    + + + +

    Global tables

    + + + +

    Class reference

    + +

    NodeMetaRef

    + +

    Node metadata: reference extra data and functionality stored in a node. +Can be gotten via minetest.get_meta(pos).

    + +

    Methods

    + + + +

    NoteTimerRef

    + +

    Node Timers: a high resolution persistent per-node timer. +Can be gotten via minetest.get_node_timer(pos).

    + +

    Methods

    + + + +

    ObjectRef

    + +

    Moving things in the game are generally these.

    + +

    This is basically a reference to a C++ ServerActiveObject

    + +

    Methods

    + + + +
    LuaEntitySAO-only (no-op for other objects)
    + + + +
    Player-only (no-op for other objects)
    + + + +

    InvRef

    + +

    An InvRef is a reference to an inventory.

    + +

    Methods

    + + + +

    ItemStack

    + +

    An ItemStack is a stack of items.

    + +

    It can be created via ItemStack(x), where x is an ItemStack, +an itemstring, a table or nil.

    + +

    Methods

    + + + +

    PseudoRandom

    + +

    A pseudorandom number generator.

    + +

    It can be created via PseudoRandom(seed).

    + +

    Methods

    + + + +

    PerlinNoise

    + +

    A perlin noise generator. +It can be created via PerlinNoise(seed, octaves, persistence, scale) +or PerlinNoise(noiseparams). +Alternatively with minetest.get_perlin(seeddiff, octaves, persistence, scale) +or minetest.get_perlin(noiseparams).

    + +

    Methods

    + + + +

    PerlinNoiseMap

    + +

    A fast, bulk perlin noise generator.

    + +

    It can be created via PerlinNoiseMap(noiseparams, size) or +minetest.get_perlin_map(noiseparams, size).

    + +

    Format of size is {x=dimx, y=dimy, z=dimz}. The z conponent is ommitted +for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise +nil is returned).

    + +

    Methods

    + + + +

    VoxelManip

    + +

    An interface to the MapVoxelManipulator for Lua.

    + +

    It can be created via VoxelManip() or minetest.get_voxel_manip().

    + +

    Methods

    + + + +

    VoxelArea

    + +

    A helper class for voxel areas. +It can be created via VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}. +The coordinates are inclusive, like most other things in Minetest.

    + +

    Methods

    + + + +

    Settings

    + +

    An interface to read config files in the format of minetest.conf.

    + +

    It can be created via Settings(filename).

    + +

    Methods

    + + + +

    Mapgen objects

    + +

    A mapgen object is a construct used in map generation. Mapgen objects can be used by an on_generate +callback to speed up operations by avoiding unnecessary recalculations; these can be retrieved using the +minetest.get_mapgen_object() function. If the requested Mapgen object is unavailable, or +get_mapgen_object() was called outside of an on_generate() callback, nil is returned.

    + +

    The following Mapgen objects are currently available:

    + +

    voxelmanip

    + +

    This returns three values; the VoxelManip object to be used, minimum and maximum emerged position, in that +order. All mapgens support this object.

    + +

    heightmap

    + +

    Returns an array containing the y coordinates of the ground levels of nodes in the most recently +generated chunk by the current mapgen.

    + +

    biomemap

    + +

    Returns an array containing the biome IDs of nodes in the most recently generated chunk by the +current mapgen.

    + +

    heatmap

    + +

    Returns an array containing the temperature values of nodes in the most recently generated chunk by +the current mapgen.

    + +

    humiditymap

    + +

    Returns an array containing the humidity values of nodes in the most recently generated chunk by the +current mapgen.

    + +

    gennotify

    + +

    Returns a table mapping requested generation notification types to arrays of positions at which the +corresponding generated structures are located at within the current chunk. To set the capture of positions +of interest to be recorded on generate, use minetest.set_gen_notify().

    + +

    Possible fields of the table returned are:

    + + + +

    Decorations have a key in the format of "decoration#id", where id is the numeric unique decoration ID.

    + +

    Registered entities

    + + + +

    L-system trees

    + +

    Tree definition

    + +
    treedef={
+    axiom,         --string  initial tree axiom
+    rules_a,       --string  rules set A
+    rules_b,       --string  rules set B
+    rules_c,       --string  rules set C
+    rules_d,       --string  rules set D
+    trunk,         --string  trunk node name
+    leaves,        --string  leaves node name
+    leaves2,       --string  secondary leaves node name
+    leaves2_chance,--num     chance (0-100) to replace leaves with leaves2
+    angle,         --num     angle in deg
+    iterations,    --num     max # of iterations, usually 2 -5
+    random_level,  --num     factor to lower nr of iterations, usually 0 - 3
+    trunk_type,    --string  single/double/crossed) type of trunk: 1 node, 2x2 nodes or 3x3 in cross shape
+    thin_branches, --boolean true -> use thin (1 node) branches
+    fruit,         --string  fruit node name
+    fruit_chance,  --num     chance (0-100) to replace leaves with fruit node
+    seed,          --num     random seed; if no seed is provided, the engine will create one
+}
+
    + +

    Key for Special L-System Symbols used in Axioms

    + + + +

    Example

    + +

    Spawn a small apple tree:

    + +
    pos = {x=230,y=20,z=4}
+apple_tree={
+    axiom="FFFFFAFFBF",
+    rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
+    rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
+    trunk="default:tree",
+    leaves="default:leaves",
+    angle=30,
+    iterations=2,
+    random_level=0,
+    trunk_type="single",
+    thin_branches=true,
+    fruit_chance=10,
+    fruit="default:apple"
+}
+minetest.spawn_tree(pos,apple_tree)
+
    + +

    Definition tables

    + +

    Object Properties

    + +
    {
+    hp_max = 1,
+    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},
+    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},
+    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
+}
+
    + +

    Entity definition (register_entity)

    + +
    {
+--  Deprecated: Everything in object properties is read directly from here
+
+    initial_properties = --[[<initial object properties>]],
+
+    on_activate = function(self, staticdata, dtime_s),
+    on_step = function(self, dtime),
+    on_punch = function(self, hitter),
+    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,
+}
+
    + +

    ABM (ActiveBlockModifier) definition (register_abm)

    + +
    {
+--  In the following two fields, also group:groupname will work.
+    nodenames = {"default:lava_source"},
+    neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
+--  ^ If left out or empty, any neighbor will do
+    interval = 1.0, -- (operation interval)
+    chance = 1, -- (chance of trigger is 1.0/this)
+    action = func(pos, node, active_object_count, active_object_count_wider),
+}
+
    + +

    Item definition (register_node, register_craftitem, register_tool)

    + +
    {
+    description = "Steel Axe",
+    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}
+    inventory_image = "default_tool_steelaxe.png",
+    wield_image = "",
+    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={
+            -- 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}
+        },
+        damage_groups = {groupname=damage},
+    },
+    node_placement_prediction = nil,
+    --[[
+    ^ If nil and item is node, prediction is made automatically
+    ^ If nil and item is not a node, no prediction is made
+    ^ If "" and item is anything, no prediction is made
+    ^ Otherwise should be name of node which the client immediately places
+      on ground when the player places the item. Server will always update
+      actual result to client in a short moment.
+    ]]
+    sound = {
+        place = --[[<SimpleSoundSpec>]],
+    },
+
+    on_place = func(itemstack, placer, pointed_thing),
+    --[[
+    ^ Shall place item and return the leftover itemstack
+    ^ default: minetest.item_place ]]
+    on_drop = func(itemstack, dropper, pos),
+    --[[
+    ^ Shall drop item and return the leftover itemstack
+    ^ default: minetest.item_drop ]]
+    on_use = func(itemstack, user, pointed_thing),
+    --[[
+    ^  default: nil
+    ^ Function must return either nil if no item shall be removed from
+      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 default functions handle regular use cases.
+    ]]
+    after_use = func(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.
+      If after_use doesn't exist, it is the same as:
+        function(itemstack, user, node, digparams)
+          itemstack:add_wear(digparams.wear)
+          return itemstack
+        end
+    ]]
+}
+
    + +

    Tile definition

    + + + +

    Tile animation definition

    + + + +

    Node definition (register_node)

    + +
    {
+    -- <all fields allowed in item definitions>,
+
+    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.
+    ^ 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 ]]
+    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,
+    use_texture_alpha = false, -- Use texture's alpha channel
+    post_effect_color = {a=0, r=0, g=0, b=0}, -- If player is inside node
+    paramtype = "none", -- See "Nodes"
+    paramtype2 = "none", -- See "Nodes"
+    is_ground_content = true, -- If false, the cave generator will not carve through this
+    sunlight_propagates = false, -- If true, sunlight will go infinitely through this
+    walkable = true, -- If true, objects collide with node
+    pointable = true, -- If true, can be pointed at
+    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
+    liquidtype = "none", -- "none"/"source"/"flowing"
+    liquid_alternative_flowing = "", -- Flowing version of source liquid
+    liquid_alternative_source = "", -- Source version of flowing liquid
+    liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
+    liquid_renewable = true, -- Can new liquid source be created by placing two or more sources nearby?
+    freezemelt = "", -- water for snow/ice, ice/snow for water
+    leveled = 0, -- Block contain level in param2. value - default level, used for snow. Don't forget 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
+    damage_per_second = 0, -- If player is inside node, this damage is caused
+    node_box = {type="regular"}, -- See "Node boxes"
+    mesh = "model",
+    selection_box = {type="regular"}, -- See "Node boxes"
+    ^ 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
+    sounds = {
+        footstep = <SimpleSoundSpec>,
+        dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
+        dug = <SimpleSoundSpec>,
+        place = <SimpleSoundSpec>,
+    },
+    drop = "",  -- Name of dropped node when dug. Default is the node itself.
+    -- Alternatively:
+    drop = {
+        max_items = 1,  -- Maximum number of items to drop.
+        items = { -- Choose max_items randomly from this list.
+            {
+                items = {"foo:bar", "baz:frob"},  -- Choose one item randomly from this list.
+                rarity = 1,  -- Probability of getting is 1 / rarity.
+            },
+        },
+    },
+
+    on_construct = func(pos), --[[
+    ^ Node constructor; always called after adding node
+    ^ Can set up metadata and stuff like that
+    ^ default: nil ]]
+    on_destruct = func(pos), --[[
+    ^ Node destructor; always called before removing node
+    ^ default: nil ]]
+    after_destruct = func(pos, oldnode), --[[
+    ^ Node destructor; always called after removing node
+    ^ default: nil ]]
+
+    after_place_node = func(pos, placer, itemstack, pointed_thing) --[[
+    ^ Called after constructing node when node was placed using
+      minetest.item_place_node / minetest.place_node
+    ^ If return true no item is taken from itemstack
+    ^ default: nil ]]
+    after_dig_node = func(pos, oldnode, oldmetadata, digger), --[[
+    ^ oldmetadata is in table format
+    ^ Called after destructing node when node was dug using
+      minetest.node_dig / minetest.dig_node
+    ^ default: nil ]]
+    can_dig = function(pos,player) --[[
+    ^ returns true if node can be dug, or false if not
+    ^ default: nil ]]
+
+    on_punch = func(pos, node, puncher, pointed_thing), --[[
+    ^ default: minetest.node_punch
+    ^ By default: Calls minetest.register_on_punchnode callbacks ]]
+    on_rightclick = func(pos, node, clicker, itemstack, pointed_thing), --[[
+    ^ default: nil
+    ^ if defined, itemstack will hold clicker's wielded item
+    ^ Shall return the leftover itemstack
+    ^ Note: pointed_thing can be nil, if a mod calls this function ]]
+
+    on_dig = func(pos, node, digger), --[[
+    ^ default: minetest.node_dig
+    ^ By default: checks privileges, wears out tool and removes node ]]
+
+    on_timer = function(pos,elapsed), --[[
+    ^ default: nil
+    ^ called by NodeTimers, see minetest.get_node_timer and NodeTimerRef
+    ^ elapsed is the total time passed since the timer was started
+    ^ return true to run the timer for another cycle with the same timeout value ]]
+
+    on_receive_fields = func(pos, formname, fields, sender), --[[
+    ^ fields = {name1 = value1, name2 = value2, ...}
+    ^ Called when an UI form (e.g. sign text input) returns data
+    ^ default: nil ]]
+
+    allow_metadata_inventory_move = func(pos, from_list, from_index,
+            to_list, to_index, count, player), --[[
+    ^ Called when a player wants to move items inside the inventory
+    ^ Return value: number of items allowed to move ]]
+
+    allow_metadata_inventory_put = func(pos, listname, index, stack, player), --[[
+    ^ Called when a player wants to put something into the inventory
+    ^ Return value: number of items allowed to put
+    ^ Return value: -1: Allow and don't modify item count in inventory ]]
+
+    allow_metadata_inventory_take = func(pos, listname, index, stack, player), --[[
+    ^ Called when a player wants to take something out of the inventory
+    ^ Return value: number of items allowed to take
+    ^ Return value: -1: Allow and don't modify item count in inventory ]]
+
+    on_metadata_inventory_move = func(pos, from_list, from_index,
+            to_list, to_index, count, player),
+    on_metadata_inventory_put = func(pos, listname, index, stack, player),
+    on_metadata_inventory_take = func(pos, listname, index, stack, player), --[[
+    ^ Called after the actual action has happened, according to what was allowed.
+    ^ No return value ]]
+
+    on_blast = func(pos, intensity), --[[
+    ^ intensity: 1.0 = mid range of regular TNT
+    ^ If defined, called when an explosion touches the node, instead of
+      removing the node ]]
+}
+
    + +

    Recipe for register_craft (shaped)

    + +
    {
+    output = 'default:pick_stone',
+    recipe = {
+        {'default:cobble', 'default:cobble', 'default:cobble'},
+        {'', 'default:stick', ''},
+        {'', 'default:stick', ''}, -- Also groups; e.g. 'group:crumbly'
+    },
+    replacements = --[[<optional list of item pairs,
+                    replace one input item with another item on crafting>]]
+}
+
    + +

    Recipe for register_craft (shapeless)

    + +
    {
+   type = "shapeless",
+   output = 'mushrooms:mushroom_stew',
+   recipe = {
+       "mushrooms:bowl",
+       "mushrooms:mushroom_brown",
+       "mushrooms:mushroom_red",
+   },
+   replacements = --[[<optional list of item pairs,
+                   replace one input item with another item on crafting>]]
+
    + +

    }

    + +

    Recipe for register_craft (tool repair)

    + +
    {
+    type = "toolrepair",
+    additional_wear = -0.02,
+}
+
    + +

    Recipe for register_craft (cooking)

    + +
    {
+    type = "cooking",
+    output = "default:glass",
+    recipe = "default:sand",
+    cooktime = 3,
+}
+
    + +

    Recipe for register_craft (furnace fuel)

    + +
    {
+    type = "fuel",
+    recipe = "default:leaves",
+    burntime = 1,
+}
+
    + +

    Ore definition (register_ore)

    + +
    {
+    ore_type = "scatter", -- See "Ore types"
+    ore = "default:stone_with_coal",
+    wherein = "default:stone",
+--  ^ a list of nodenames is supported too
+    clust_scarcity = 8*8*8,
+--  ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
+--  ^ This value should be *MUCH* higher than your intuition might tell you!
+    clust_num_ores = 8,
+--  ^ Number of ores in a cluster
+    clust_size = 3,
+--  ^ Size of the bounding box of the cluster
+--  ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore
+    height_min = -31000,
+    height_max = 64,
+    flags = "",
+--  ^ Attributes for this ore generation
+    noise_threshhold = 0.5,
+--  ^ If noise is above this threshold, ore is placed.  Not needed for a uniform distribution
+    noise_params = {offset=0, scale=1, spread={x=100, y=100, z=100}, seed=23, octaves=3, persist=0.70}
+--  ^ NoiseParams structure describing the perlin noise used for ore distribution.
+--  ^ Needed for sheet ore_type.  Omit from scatter ore_type for a uniform ore distribution
+}
+
    + +

    Decoration definition (register_decoration)

    + +
    {
+    deco_type = "simple", -- See "Decoration types"
+    place_on = "default:dirt_with_grass",
+--  ^ Node that 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.
+    fill_ratio = 0.02,
+--  ^ Ratio of the area to be uniformly filled by the decoration.
+--  ^ Used only if noise_params is not specified.
+    noise_params = {offset=0, scale=.45, spread={x=100, y=100, z=100}, seed=354, octaves=3, persist=0.7},
+--  ^ NoiseParams structure describing the perlin noise used for decoration distribution.
+--  ^ The result of this is multiplied by the 2d area of the division being decorated.
+    biomes = {"Oceanside", "Hills", "Plains"},
+--  ^ List of biomes in which this decoration occurs.  Occurs in all biomes if this is omitted,
+--  ^ and ignored if the Mapgen being used does not support biomes.
+
+    ----- Simple-type parameters
+    decoration = "default:grass",
+--  ^ The node name used as the decoration.
+--  ^ If instead a list of strings, a randomly selected node from the list is placed as the decoration.
+    height = 1,
+--      ^ Number of nodes high the decoration is made.
+--  ^ If height_max is not 0, this is the lower bound of the randomly selected height.
+    height_max = 0,
+--      ^ 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, in a 1-node square radius.
+    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.
+
+    ----- Schematic-type parameters
+    schematic = "foobar.mts",
+--  ^ If schematic is a string, it is the filepath relative to the current working directory of the
+--  ^ specified Minetest schematic file.
+--  ^  - OR -, could instead be a table containing two mandatory fields, size and data,
+--  ^ and an optional table yslice_prob:
+    schematic = {
+        size = {x=4, y=6, z=4},
+        data = {
+            {name="cobble", param1=255, param2=0},
+            {name="dirt_with_grass", param1=255, param2=0},
+             ...
+        },
+        yslice_prob = {
+            {ypos=2, prob=128},
+            {ypos=5, prob=64},
+             ...
+        },
+    },
+--  ^ See 'Schematic specifier' for details.
+    replacements = {["oldname"] = "convert_to", ...},
+    flags = "place_center_x, place_center_z",
+--  ^ Flags for schematic decorations.  See 'Schematic attributes'.
+    rotation = "90" -- rotate schematic 90 degrees on placement
+--  ^ Rotation can be "0", "90", "180", "270", or "random".
+}
+
    + +

    Chat command definition (register_chatcommand)

    + +
    {
+    params = "<name> <privilege>", -- Short parameter description
+    description = "Remove privilege from player", -- Full description
+    privs = {privs=true}, -- Require the "privs" privilege to run
+    func = function(name, param), -- Called when command is run.
+                                  -- Returns boolean success and text output.
+}
+
    + +

    Detached inventory callbacks

    + +
    {
+    allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
+--  ^ Called when a player wants to move items inside the inventory
+--  ^ Return value: number of items allowed to move
+
+    allow_put = func(inv, listname, index, stack, player),
+--  ^ Called when a player wants to put something into the inventory
+--  ^ Return value: number of items allowed to put
+--  ^ Return value: -1: Allow and don't modify item count in inventory
+
+    allow_take = func(inv, listname, index, stack, player),
+--  ^ Called when a player wants to take something out of the inventory
+--  ^ Return value: number of items allowed to take
+--  ^ Return value: -1: Allow and don't modify item count in inventory
+
+    on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
+    on_put = func(inv, listname, index, stack, player),
+    on_take = func(inv, listname, index, stack, player),
+--  ^ Called after the actual action has happened, according to what was allowed.
+--  ^ No return value
+}
+
    + +

    HUD Definition (hud_add, hud_get)

    + +
    {
+    hud_elem_type = "image", -- see HUD element types
+--  ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
+    position = {x=0.5, y=0.5},
+--  ^ Left corner position of element
+    name = "<name>",
+    scale = {x=2, y=2},
+    text = "<text>",
+    number = 2,
+    item = 3,
+--  ^ Selected item in inventory.  0 for no item selected.
+    direction = 0,
+--  ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
+    alignment = {x=0, y=0},
+--  ^ See "HUD Element Types"
+    offset = {x=0, y=0},
+--  ^ See "HUD Element Types"
+    size = { x=100, y=100 },
+--  ^ Size of element in pixels
+}
+
    + +

    Particle definition (add_particle)

    + +
    {
+    pos = {x=0, y=0, z=0},
+    velocity = {x=0, y=0, z=0},
+    acceleration = {x=0, y=0, z=0},
+--  ^ Spawn particle at pos with velocity and acceleration
+    expirationtime = 1,
+--  ^ Disappears after expirationtime seconds
+    size = 1,
+    collisiondetection = false,
+--  ^ collisiondetection: if true collides with physical objects
+    vertical = false,
+--  ^ vertical: if true faces player using y axis only
+    texture = "image.png",
+--  ^ Uses texture (string)
+    playername = "singleplayer"
+--  ^ optional, if specified spawns particle only on the player's client
+}
+
    + +

    ParticleSpawner definition (add_particlespawner)

    + +
    {
+    amount = 1,
+    time = 1,
+--  ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
+    minpos = {x=0, y=0, z=0},
+    maxpos = {x=0, y=0, z=0},
+    minvel = {x=0, y=0, z=0},
+    maxvel = {x=0, y=0, z=0},
+    minacc = {x=0, y=0, z=0},
+    maxacc = {x=0, y=0, z=0},
+    minexptime = 1,
+    maxexptime = 1,
+    minsize = 1,
+    maxsize = 1,
+--  ^ The particle's properties are random values in between the bounds:
+--  ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
+--  ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
+    collisiondetection = false,
+--  ^ collisiondetection: if true uses collision detection
+    vertical = false,
+--  ^ vertical: if true faces player using y axis only
+    texture = "image.png",
+--  ^ Uses texture (string)
+    playername = "singleplayer"
+--  ^ Playername is optional, if specified spawns particle only on the player's client
+}
+