minetest.register_node

From Minetest Developer Wiki
(Redirected from on construct)
Jump to: navigation, search

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.

Contents

Syntax

minetest.register_node("name", {node definition})

Node definition

The node definition is a regular Lua table:

minetest.registered_nodes["<node name>"].<field>

Valid fields include:

  • drawtype — Specifies how the game engine is to draw the node. See Node Drawtypes for more information.
  • visual_scale — 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.
  • tiles — 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.
  • special_tiles — Specifies certain textures used in things like texture animations. [This text needs further expansion]


  • use_texture_alpha — Set this to true for the texture's alpha channel to be used.
  • alpha — 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.
  • post_effect_color — 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: { r=255, g=0, b=0, a=128 }.
  • inventory_image — 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.
  • wield_image — The texture to display in place of the hand texture when the node is wielded. If undefined (nil), the inventory image will be used.
  • paramtype — Specifies what the node's param1 should hold. Possible values are:
    • none — The engine does not use the param1 field, and it is free to be used for other purposes.
    • light — The value stored in param1 is the light level with and without sun in it's upper and lower 4 bits respectively.
  • paramtype2 — Specifies what the node's param2 should hold. Possible values are:
    • wallmountedparam2 field contains the wall to which this node is "mounted". See minetest.dir_to_wallmounted(dir).
    • facedirparam2 field contains the node's facing direction. Required to be able to orient nodes depending on the direction the player is facing. minetest.dir_to_facedir(dir).
  • is_ground_content — If true, caves will carve through this
  • sunlight_propagates — If true, sunlight will go infinitely through this
  • walkable — If true, objects collide with node
  • pointable — If true, can be pointed at
  • diggable — If false, can never be dug
  • climbable — If true, can be climbed on (ladder)
  • buildable_to — If true, placed nodes can replace this node
  • drop — alternatively drop = { max_items = ..., items = { ... } }
  • liquidtype — "none"/"source"/"flowing"
  • liquid_alternative_flowing — Flowing version of source liquid
  • liquid_alternative_source — Source version of flowing liquid
  • liquid_viscosity — Higher viscosity means slower flow (max. 7)
  • liquid_renewable — If true, when placing two or more sources so that there's air between them, a new liquid source will be created.
  • light_source — Amount of light emitted by node, where 0 is no light, and 14 is sunlight-like light.
  • damage_per_second — If player is inside node, this damage is caused. This is used for example, by lava.
  • node_boxSee Node boxes
  • selection_boxSee Node boxes
  • collision_box
  • legacy_facedir_simple — Support maps made in and before January 2012
  • legacy_wallmounted — Support maps made in and before January 2012
  • sounds — A table that specifies which sound to play when some events occur. See SimpleSoundSpec for details. The following events are defined for nodes:
    • footstep — Played when a player walks on the node.
    • dig — Played while the player is digging the node. If it is "__group" is specified as value, it uses the group-based sound. [This text needs further expansion]


    • dug — 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.

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

on_construct = function(pos)

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

on_destruct

on_destruct = function(pos)

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

  • pos Position of the node being destroyed.

after_destruct

after_destruct = function(pos, oldnode)

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

on_place = function(itemstack, placer, pointed_thing)

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 minetest.item_place which:

  1. Checks whether the destination can be built to (contains no node or one with the buildable_to flag turned on).
  2. Sets param2 for "facedir" or "wallmounted" type nodes.
  3. Adds the node to the environment using minetest.add_node(...).
  4. Calls the after_place_node(...) and game-wide on_placement (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

on_drop = function(itemstack, dropper, pos)

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 minetest.add_item(...), and gives it a small "push" away from the camera using LuaEntitySAO.setvelocity(...).

  • 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

on_use = function(itemstack, player, pointed_thing)

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

on_punch = function(pos, node, player, pointed_thing)

Called when node is punched by player or using minetest.punch_node(...).

Default: Reference to minetest.node_punch(pos, node, player, pointed_thing), which calls minetest.register_on_punchnode() 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

on_dig = function(pos, node, player)

Called when node is dug by player or using minetest.dig_node(...).

Default: Reference to minetest.node_dig(pos, node, player), which:

  1. Checks node.diggable and calls can_dig(pos, player) (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 minetest.remove_node(pos).
  5. Calls after_dig_node (if defined) and game-wide on_dignodes (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

on_timer = function(pos, elapsed)

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

on_receive_fields = function(pos, formname, fields, sender)

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 minetest.show_formspec(playername, formname, formspec) and minetest.register_on_player_receive_fields(func(player, formname, fields)))
  • 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

allow_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player)

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

allow_metadata_inventory_put = function(pos, listname, index, stack, player)

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

allow_metadata_inventory_take = function(pos, listname, index, stack, player)

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

on_metadata_inventory_move = function(pos, from_list, from_index, to_list, to_index, count, player)

Callback called after a player has moved an item or items from one inventory slot to another within the node's inventory. Called after allow_metadata_inventory_move(pos, from_list, from_index, to_list, to_index, count, player) 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

on_metadata_inventory_put = function(pos, listname, index, stack, player)

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 allow_metadata_inventory_put(pos, listname, index, stack, player) 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

on_metadata_inventory_take = function(pos, listname, index, stack, player)

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 allow_metadata_inventory_take(pos, listname, index, stack, player) 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 on_place with a custom event handler callback, then after_place_node will not be called unless you explicitly call it, since it is the default on_place callback (minetest.item_place) that calls after_place_node. 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

after_place_node = function(pos, placer, itemstack, pointed_thing)

Called after constructing node when node was placed using minetest.item_place_node(...) / minetest.place_node(...) (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, false, or nil) 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).

can_dig

can_dig = function(pos, player)

Called by minetest.node_dig(...) / minetest.node_dig(...) to determine if player can dig the node in its current state. Returns a boolean (true 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

after_dig_node = function(pos, oldnode, oldmetadata, digger)

Called after node is destroyed as a result of minetest.node_dig(...) / minetest.node_dig(...).

  • 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

on_rightclick = function(pos, node, player, itemstack, pointed_thing)

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). (New in 0.4.5)

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

  • posPosition 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 (only in 0.4.10+).

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

on_blast = function(pos, intensity)

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

on_rotate

on_rotate = function(pos, node, player, mode, new_param2)

If defined, called when the node is rotated using the screwdriver (from minetest_game / screwdriver mod). Screwdriver only rotates facedir nodes.

Returns false to avoid screwdriver actually perform the rotation (if rotation is rejected/disallowed or if on_rotate performs the rotation itself). Returns true to let screwdriver perform the rotation.

  • posPosition of the node that is being rotated.
  • node — Node definition of the node that is being rotated.
  • player — Reference to the Player who is using the screwdriver.
  • mode — Screwdriver mode (1=Rotate face, 2=Rotate axis)
  • new_param2 — New node param2 proposed by the screwdriver mod.

Example

minetest.register_node("default:stone", {
	description = "Stone",
	tiles = {"default_stone.png"},
	is_ground_content = true,
	groups = {cracky=3, stone=1},
	drop = 'default:cobble',
	legacy_mineral = true,
	sounds = default.node_sound_stone_defaults(),
})



This article is incomplete.


Personal tools
Namespaces

Variants
Actions
Navigation
API
Toolbox