Difference between revisions of "ItemStack"

From Minetest Developer Wiki
Jump to navigation Jump to search
(correct get_metadata(), add get_meta())
(Replaced content with "See the Lua API or https://rubenwardy.com/minetest_modding_book/en/items/inventories.html")
Tag: Replaced
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
A stack of items. Can be created via <source enclose="none">ItemStack(itemstack or itemstring or table or nil)</source>.
+
See the Lua API or https://rubenwardy.com/minetest_modding_book/en/items/inventories.html
 
 
'''Please note''' that all functions returning <code>ItemStack</code> return its copy which modifications won't affect original <code>ItemStack</code>.
 
 
 
== Definitions ==
 
Items and item stacks can exist in three formats:
 
 
 
* Serialized; This is called <code>stackstring</code> or <code>itemstring</code>:
 
:* <source enclose="none">'default:dirt 5'</source>
 
:* <source enclose="none">'default:pick_wood 21323'</source>
 
:* <source enclose="none">'default:apple'</source>
 
* Table format:
 
:* <source enclose="none">{name="default:dirt", count=5, wear=0, metadata=""}</source> — 5 dirt nodes
 
:* <source enclose="none">{name="default:pick_wood", count=1, wear=21323, metadata=""}</source> — wooden pick about 1/3 worn out
 
:* <source enclose="none">{name="default:apple", count=1, wear=0, metadata=""}</source> — an apple.
 
* ItemStack. C++ native format with many helper methods. Useful for converting between formats. See this article for details.
 
 
 
== Methods ==
 
{| class="wikitable collapsible sortable"
 
! Method
 
! Description
 
|-
 
| <source enclose="none">[ItemStack]add_item(item)</source>
 
| put some item or stack onto this stack, returns leftover <code>ItemStack</code>
 
|-
 
| <source enclose="none">add_wear(amount)</source>
 
| increases wear by <code>amount</code> if the item is a tool
 
|-
 
| <source enclose="none">clear()</source>
 
| removes all items from the stack, making it empty
 
|-
 
| <source enclose="none">get_count()</source>
 
| returns number of items on the stack
 
|-
 
| <source enclose="none">set_count(count)</source>
 
| returns <source enclose="none">true/false</source> (success), clears item on failure
 
|-
 
| <source enclose="none">get_definition()</source>
 
| returns the item definition table
 
|-
 
| <source enclose="none">get_free_space()</source>
 
| returns <source enclose="none">get_stack_max() - get_count()</source>
 
|-
 
| <source enclose="none">get_meta()</source>
 
| returns a [[MetaDataRef]]
 
|-
 
| <source enclose="none">get_metadata()</source>
 
| returns a <source enclose="none">string</source>, for compatibility reasons this is equal to <source enclose="none">get_meta():get_string("")</source>
 
|-
 
| <source enclose="none">get_name()</source>
 
| returns item name (e.g. <source enclose="none">"default:stone"</source>)
 
|-
 
| <source enclose="none">set_name("itemname")</source>
 
| returns <source enclose="none">true/false</source> (success), clears item on failure
 
|-
 
| <source enclose="none">get_stack_max()</source>
 
| returns the maximum size of the stack (depends on the item)
 
|-
 
| <source enclose="none">get_tool_capabilities()</source>
 
| returns the digging properties of the item, or those of the hand if none are defined for this item type
 
|-
 
| <source enclose="none">get_wear()</source>
 
| returns tool wear (<code>0-65535</code>), <code>0</code> for non-tools
 
|-
 
| <source enclose="none">set_wear(wear)</source>
 
| returns <source enclose="none">true/false</source> (success), clears item on failure
 
|-
 
| <source enclose="none">[ItemStack]is_empty()</source>
 
| return <source enclose="none">true</source> if stack is empty
 
|-
 
| <source enclose="none">is_known()</source>
 
| returns <source enclose="none">true</source> if the item name refers to a defined item type
 
|-
 
| <source enclose="none">item_fits(item)</source>
 
| returns <source enclose="none">true</source> if item or stack can be fully added to this one
 
|-
 
| <source enclose="none">peek_item(n)</source>
 
| copy (don't remove) up to <code>n</code> items from this stack; returns copied <code>ItemStack</code>; if <code>n</code> is omitted, <code>n=1</code> is used
 
|-
 
| <source enclose="none">replace(item)</source>
 
| replace the contents of this stack (<code>item</code> can also be an itemstring or table)
 
|-
 
| <source enclose="none">take_item(n)</source>
 
| take (and remove) up to <code>n</code> items from this stack; returns taken <code>ItemStack</code>; if <code>n</code> is omitted, <code>n=1</code> is used
 
|-
 
| <source enclose="none">to_string()</source>
 
| returns the stack in <code>itemstring</code> form
 
|-
 
| <source enclose="none">[ItemStack]to_table()</source>
 
| returns the stack in Lua table form
 
|}
 
 
 
== Example ==
 
<source>
 
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
 
 
})
 
</source>
 
 
 
[[Category:Objects]]
 

Latest revision as of 01:58, 16 August 2022