From Minetest Developer Wiki
Jump to: navigation, search
Mbox warning.png This page contains unofficial Lua API documentation and is likely to be outdated or wrong.
For the official and up-to-date documentation, refer to lua_api.txt found in your Minetest installation directory under doc.
Mbox warning.png This page has been proposed for deletion for the following reason: "Contains unofficial and potentially outdated, redundant and inconsistent Lua API information"
If you don't think that this page should be deleted, please explain why on the talk page.

A stack of items. Can be created via ItemStack(itemstack or itemstring or table or nil).

Please note that all functions returning ItemStack return its copy which modifications won't affect original ItemStack.


Items and item stacks can exist in three formats:

  • Serialized; This is called stackstring or itemstring:
  • 'default:dirt 5'
  • 'default:pick_wood 21323'
  • 'default:apple'
  • Table format:
  • {name="default:dirt", count=5, wear=0, metadata=""} — 5 dirt nodes
  • {name="default:pick_wood", count=1, wear=21323, metadata=""} — wooden pick about 1/3 worn out
  • {name="default:apple", count=1, wear=0, metadata=""} — an apple.
  • ItemStack. C++ native format with many helper methods. Useful for converting between formats. See this article for details.


Method Description
add_item(item) put some item or stack onto this stack, returns leftover ItemStack
add_wear(amount) increases wear by amount if the item is a tool
clear() removes all items from the stack, making it empty
get_count() returns number of items on the stack
set_count(count) returns true/false (success), clears item on failure
get_definition() returns the item definition table
get_free_space() returns get_stack_max() - get_count()
get_meta() returns a MetaDataRef
get_metadata() returns a string, for compatibility reasons this is equal to get_meta():get_string("")
get_name() returns item name (e.g. "default:stone")
set_name("itemname") returns true/false (success), clears item on failure
get_stack_max() returns the maximum size of the stack (depends on the item)
get_tool_capabilities() returns the digging properties of the item, or those of the hand if none are defined for this item type
get_wear() returns tool wear (0-65535), 0 for non-tools
set_wear(wear) returns true/false (success), clears item on failure
is_empty() return true if stack is empty
is_known() returns true if the item name refers to a defined item type
item_fits(item) returns true if item or stack can be fully added to this one
peek_item(n) copy (don't remove) up to n items from this stack; returns copied ItemStack; if n is omitted, n=1 is used
replace(item) replace the contents of this stack (item can also be an itemstring or table)
take_item(n) take (and remove) up to n items from this stack; returns taken ItemStack; if n is omitted, n=1 is used
to_string() returns the stack in itemstring form
to_table() returns the stack in Lua table form


minetest.register_craftitem("modname:tool", {
	description = "Example Tool",
	inventory_image = "modname_test.png",
	on_use = function(itemstack, user, pointed_thing)
		-- Takes one item from the stack
		return itemstack
Personal tools