minetest.register node

Registers a new node named "name". The node properties are specified in the Node definition (see below).

Note that the node is not "created" immediately; it is stored in the minetest.registered_nodes list to be processed when all the mods have been loaded.

Node definition
The node definition is a regular Lua table:

Valid fields include:


 * — Specifies how the game engine is to draw the node. See Node Drawtypes for more information.
 * — Specifies the scale at which the item is drawn when it is wielded. Default is 1.0 (normal scale). 2.0 is double, 0.5 is half, and so on.
 * — Specifies the textures used for the node's faces. It's an array (table) of either one or six elements. If only one texture is needed, it can be specified directly as a string instead of a table. The textures are specified as strings as either "texturename.png" or "texturename". The order of the textures is +Y, -Y, +X, -X, +Z, -Z. In English: top, bottom, right, left, back, front.
 * — Specifies certain textures used in things like texture animations.
 * — Set this to true for the texture's alpha channel to be used.
 * — Alpha value (transparency) of the node, with 255 being fully opaque and 0 being fully transparent. Values in-between specify partial transparency. This only has an effect on liquid nodes.
 * — Whenever a player is "inside" the node, the screen is tinted using this color. It is specified as a table with fields 'r', 'g', 'b', and 'a', which represent the Red, Green, and Blue components, and the effect transparency (Alpha). For example:.
 * — This texture will be used for every state except when placed in the world (i.e. it will be used in inventory and when dropped). If undefined (nil) an image will be automatically constructed from tiles.
 * — The texture to display in place of the hand texture when the node is wielded. If undefined (nil), the inventory image will be used.
 * — Specifies what the node's  should hold. Possible values are:
 * — The engine does not use the  field, and it is free to be used for other purposes.
 * — The value stored in  is the light level with and without sun in it's upper and lower 4 bits respectively.
 * — Specifies what the node's  should hold. Possible values are:
 * —  field contains the wall to which this node is "mounted". See.
 * —  field contains the node's facing direction. Required to be able to orient nodes depending on the direction the player is facing..
 * — If true, caves will carve through this. Default it true.
 * — If true, sunlight will go infinitely through this. Default is false.
 * — If true, objects collide with node. Default is true.
 * — If true, can be pointed at. Default is true.
 * — If false, can never be dug. Default is true.
 * — If true, can be climbed on (ladder). Default is false.
 * — If true, placed nodes can replace this node. Default is false.
 * — A single ItemStack that is dropped when the node is dug, or a list of item sets to pick randomly from. Set it to {} to disable the drop. Default is the name of the node. See below for more details.
 * — Maximum number of this item (and not the dropped one) in a stack. Default is 99.
 * — "none"/"source"/"flowing"
 * — Flowing version of source liquid
 * — Source version of flowing liquid
 * — Higher viscosity means slower flow (max. 7)
 * — If true, when placing two or more sources so that there's air between them, a new liquid source will be created.
 * — Amount of light emitted by node, where 0 is no light, and 14 is sunlight-like light.
 * — If player is inside node, this damage is caused. This is used for example, by lava.
 * — See Node boxes
 * — See Node boxes
 * — Support maps made in and before January 2012
 * — Support maps made in and before January 2012
 * — A table that specifies which sound to play when some events occur. See SimpleSoundSpec for details. The following events are defined for nodes:
 * — Played when a player walks on the node.
 * — Played while the player is digging the node. If it is  is specified as value, it uses the group-based sound.
 * — Played when the player finishes digging the node.
 * — Played when the player finishes digging the node.

Wield Image Transparency
When an inventory image or explicit wield image is selected by the engine to display in first-person view on the client, some processing is done to actually display it on the screen. The game takes the rightmost pixels in the image that are not 100% transparent (alpha=0) and duplicates them several times to the right to give the image a "3D" appearance. This can cause artifacts if those right-most pixels are partially transparent, or if anti-aliasing results in some of the pixels being partially transparent.

However, you can use a trick to effectively turn this feature off: add some pixels of your own to the right of all "real" pixels in your image, and make them very close to fully transparent (alpha=1 when alpha ranges from 0 to 255, or alpha=0.005 when alpha ranges from 0.0 to 1.0, or alpha = 0.5% when alpha ranges from 0% to 100%; alpha and opacity are generally interchangeable terms in image editors, so setting the opacity of a layer in GIMP to 0.5% accomplishes this for all fully opaque pixels in the layer). This will cause these buffer pixels, which are generally invisible to the eye, to be duplicated instead of the "real" pixels of your image. This will allow you to have full control over the wielded item images and even use anti-aliasing for them.

Use Texture Alpha Channel
Must be used with a drawtype that does not perform backface culling.

There are currently two known, difficult-to-solve issues with this feature.

With shaders enabled, the faces of other transparent nodes are sometimes not drawn, depending on viewing angle. This is most noticable when a liquid is behind a node that uses the texture's alpha channel.

With shaders disabled, transparent objects farther away from the camera that should be occluded will be drawn over the node with this attribute. This is caused by the lack of transparency sorting, and is also the cause of water being drawn in front of clouds.

More on drop
The drop be picked randomly from a set. In that case, the maximum number of sets to drop is indicated in  and the items to picks are defined inside. Each item is defined by a list of ItemStack, an optional rarity which is the inverted chance this set will be picked and an optional list of tools to use or not to use (with the ~ prefix).

The above example with result if digging with a  to either 2 flints and one gravel (first item set, max_items is reached) or only one gravel (the second set). If max items was 2 or more it could be 2 flints and 2 gravels (both sets), or only one gravel (the first set wasn't picked by chance).

Primary Callbacks
When the following methods are defined in the node definition, the core engine will call them as callback methods as a result of direct events in the game such as a player punching the node or the node being added to the environment. Much of the default behavior of the game, such as adding a node to the environment when it is "placed", or adding an entity for an item when it is "dropped" can be replaced by overriding these callback methods. See src/scriptapi.cpp for more info.

on_construct
Node Constructor. This function is called after putting the node in the world. It can be used to set up the node's metadata.


 * pos — Position of the new node

on_destruct
Node destructor. This function is called before removing the node.


 * pos — Position of the node being destroyed.

after_destruct
Node destructor. This function is called after removing the node.


 * pos — Position the destroyed node occupied.
 * oldnode — A reference to the node that has been removed (TODO: verify this from C++ source; no documentation or examples are evident).

on_place
Called when a player places a node in-world. Returns itemstack modified according to the logic of the method (e.g. with one node removed from the count).

Default: Reference to  which:


 * 1) Checks whether the destination can be built to (contains no node or one with the   flag turned on).
 * 2) Sets   for "facedir" or "wallmounted" type nodes.
 * 3) Adds the node to the environment using.
 * 4) Calls the   and game-wide   (see minetest.register_on_placenode) callbacks.
 * 5) Returns itemstack with one node removed.

Parameters are:


 * itemstack — The ItemStack that contains the node being placed.
 * placer — The Player object for the player placing the node.
 * pointed_thing — The pointed_thing acting as a reference for where to place the node (i.e. what the player's crosshair is pointing at).

on_drop
Called when a player drops a node item (as in drops its stack on the ground—with the Q button by default—not placing it in-world as a node). Returns itemstack modified according to the logic of the method (e.g. emptied of all contents).

Default: Reference to minetest.item_drop which calculates a point 1m in front of the camera, places an item entity (type "__builtin:item") there using, and gives it a small "push" away from the camera using.


 * itemstack — The ItemStack that contains the node being dropped.
 * dropper — The Player object for the player dropping the node.
 * pos — The position of the player dropping the node item. Note that this is not the place where the item is dropped in-world; it is up to this method to calculate that based on factors like which way the player is looking.

on_use
Called when player wields and uses the node item. Returns itemstack modified according to the logic of the method, or nil if no item is to be removed from inventory.

Default: nil (not called)


 * itemstack — The ItemStack that contains the node being used.
 * player — The Player object for the player using the node item.
 * pointed_thing — The pointed_thing acting as a reference for where the player's crosshair is pointing.

on_punch
Called when node is punched by player or using.

Default: Reference to, which calls   callbacks.


 * pos — Position of the node being punched.
 * node — Copy of the node being punched.
 * player — Reference to an object indicating who or what is punching the node.
 * pointed_thing — Copy of pointed_thing (only in 0.4.10+).

on_dig
Called when node is dug by player or using.

Default: Reference to, which:
 * 1) Checks   and calls   (if defined).
 * 2) Adds wear to the player's wielded item, if any.
 * 3) Handles node drops.
 * 4) Removes the node from the environment with.
 * 5) Calls   (if defined) and game-wide   (see minetest.register_on_dignode) callbacks.

Parameters are:


 * pos — Position of the node being punched.
 * node — Reference to the node being dug.
 * player — Reference to an ObjectRef indicating who or what doing the digging.

on_timer
Called by node timers. Should return a boolean indicating whether to run the timer for another cycle using the same timeout value.


 * pos — Position of the node for which the timer has elapsed.
 * elapsed — Total time that has passed since the timer was started.

on_receive_fields
Called when a UI form on a node (e.g. sign text input) returns data. See formspec and NodeMetaRef.


 * pos — Position of the node whose form fields are submitted.
 * formname — (TODO: Check meaning and use, because its only used by  and  )
 * fields — The names and values of the form's fields, as a table: {name1 = value1, name2 = value2, ...}
 * sender — Reference to a Player object indicating who submitted the form.

allow_metadata_inventory_move
Called when a player attempts to move an item or items from one inventory slot to another within the node's inventory. Should return the actual number of items allowed to move from 0 (if the move is not allowed) to count (if all items may be moved), inclusive.

Example: Used by locked chests to ensure only the owner can modify them.


 * pos — The position of the node whose inventory is being modified.
 * from_list — The inventory list from which the item or items are being moved (e.g. "fuel", "dst", or "src" for a furnace in the default game).
 * from_index — The index of the slot from which the item or items are being moved within from_list.
 * to_list — The inventory list to which the item or items are being moved (e.g. "fuel", "dst", or "src" for a furnace in the default game).
 * to_index — The index of the slot to which the item or items are being moved within to_list.
 * count — The number of items the player is attempting to move.
 * player — The player attempting to modify the node inventory.

allow_metadata_inventory_put
Called when a player attempts to move an item or items into the node's inventory from another inventory (e.g. the player's own inventory). Should return either -1 to allow all items to be moved but leave the node inventory unchanged, or the actual number of items allowed to move from 0 (if the move is not allowed) to count (if all items may be moved), inclusive.

Example: Used by locked chests to ensure only the owner can modify them.


 * pos — The position of the node whose inventory is being modified.
 * listname — The inventory list to which the item or items are being moved (e.g. "fuel", "dst", or "src" for a furnace in the default game).
 * index — The index of the slot to which the item or items are being moved within listname.
 * stack — Reference to an ItemStack describing what player is attempting to move.
 * player — The player attempting to modify the node inventory.

allow_metadata_inventory_take
Called when a player attempts to move an item or items out of the node's inventory to another inventory (e.g. the player's own inventory). Should return either -1 to allow all items to be moved but leave the node inventory unchanged (copy items out), or the actual number of items allowed to move from 0 (if the move is not allowed) to count (if all items may be moved), inclusive.

Example: Used by locked chests to ensure only the owner can modify them.


 * pos — The position of the node whose inventory is being modified.
 * listname — The inventory list from which the item or items are being moved (e.g. "fuel", "dst", or "src" for a furnace in the default game).
 * index — The index of the slot from which the item or items are being moved within listname.
 * stack — Reference to an ItemStack describing what player is attempting to move.
 * player — The player attempting to modify the node inventory.

on_metadata_inventory_move
Callback called after a player has moved an item or items from one inventory slot to another within the node's inventory. Called after  if the inventory move is allowed, with identical arguments except for a count updated to reflect the actual allowed number of items.

on_metadata_inventory_put
Callback called after a player has moved an item or items into the node's inventory from another inventory (e.g. the player's own inventory). Called after  if the inventory move is allowed, with identical arguments except for a stack updated to reflect the actual allowed number of items.

on_metadata_inventory_take
Callback called after a player has moved an item or items out of the node's inventory to another inventory (e.g. the player's own inventory). Called after  if the inventory move is allowed, with identical arguments except for a stack updated to reflect the actual allowed number of items.

Secondary Callbacks
Rather than being used by the core game engine itself the following callbacks are called indirectly by the default implementations of the above primary callbacks, so installing a callback for the primary events may result in these methods not being called. For example, if you implement  with a custom event handler callback, then   will not be called unless you explicitly call it, since it is the default   callback  that calls. The default implementation of these secondary callbacks for a new node type does nothing (though several node types used by the default game mods do install behavior; e.g. chests). This means overriding them for your custom node simply adds new behavior instead of replacing existing default behavior. See builtin/item.lua for more info.

after_place_node
Called after constructing node when node was placed using  /   (for example, locked chests use this to determine the owner).

Return a true value to indicate modification of itemstack (if any) has been handled by the callback. Otherwise (return nothing,, or  ) the caller will remove one item from itemstack. Note that it is not generally possible for one global on_placenode callback to know what values were returned by others or by this callback (one should thus be careful to avoid double-removal of items).


 * pos — Position of the new node.
 * placer — Reference to an object.
 * itemstack — Reference to wielded ItemStack.
 * pointed_thing — Copy of the pointed_thing (only in 0.4.10+).

can_dig
Called by  /   to determine if player can dig the node in its current state. Returns a boolean ( if node can be dug).

Example: Chests and furnaces use this to allow digging only if they are empty.


 * pos — Position of the node to be dug.
 * player — Reference to an object indicating who or what is trying to dig the node.

after_dig_node
Called after node is destroyed as a result of  /.


 * pos — Position of node that was dug.
 * oldnode — Copy of old node
 * oldmetadata — Copy of old metadata in table format.
 * digger — Reference to an object.

on_rightclick
When defined (not nil), this method is called by minetest.on_place(...) instead of minetest.item_place_node(...). Returns itemstack modified according to the logic of the method (e.g. with one node removed from the count). This function does not get triggered by clients prior and including 0.4.16 if the "formspec" node metadata field is set.

Default: nil (not defined; try to place a node instead)


 * pos — Position of the node that was right-clicked on.
 * node — Node that was right-clicked on.
 * player — Reference to the Player who right-clicked on the node.
 * itemstack — The item (stack) wielded by the player when right-clicking.
 * pointed_thing pointed_thing. Can be nil if called by a mod

Unclassified Callbacks
These callbacks have been mentioned very briefly in the game documentation (e.g. in lua_api.txt), but few details are available other than a hint at their design and purpose, so it is unknown where they fit in the scheme of engine vs. mod code.

on_blast
If defined, called when an explosion touches the node, instead of removing the node. It should be used by mods.


 * pos — The position of the node being affected the the explosion.
 * intensity — Describes the intensity of the blast affecting the node. According the lua_api.txt: 1.0 = mid range of regular TNT

Examples
Fast way to define a block of desired color using no textures at all.

Fast way to define a block of desired color using a default textures. In this example the color is #802BB1 and color opacity is 119 (0x77, hexadecimal).