Difference between revisions of "ItemStack"

From Minetest Developer Wiki
Jump to navigation Jump to search
(correct get_metadata(), add get_meta())
(Add UnofficialLua warning)
Line 1: Line 1:
 +
{{UnofficialLua}}
 
A stack of items. Can be created via <source enclose="none">ItemStack(itemstack or itemstring or table or nil)</source>.  
 
A stack of items. Can be created via <source enclose="none">ItemStack(itemstack or itemstring or table or nil)</source>.  
  

Revision as of 22:57, 23 December 2019

Mbox warning.png This page contains unofficial, low-quality Lua API documentation and is likely to be outdated or wrong. Do not rely on it!
For the official and up-to-date documentation, see Lua API Documentation.
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.

Definitions

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.

Methods

Method Description
[ItemStack]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
[ItemStack]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
[ItemStack]to_table() returns the stack in Lua table form

Example

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
		itemstack:take_item()
		return itemstack
	end
	
})