minetest_modding_book/_en/inventories/itemstacks.md

title	layout	root	idx	redirect_from
ItemStacks	default	../..	5.1	/en/chapters/itemstacks.html

Introduction

In this chapter you will learn how to use ItemStacks.

• Creating ItemStacks
• Name and Count
• Adding and Taking Items
• Wear
• Lua Tables
• Metadata
• More Methods

Creating ItemStacks

An item stack is a... stack of items. It's basically just an item type with a count of items in the stack.

You can create a stack like so:

local items = ItemStack("default:dirt")
local items = ItemStack("default:stone 99")

You could alternatively create a blank ItemStack and fill it using methods:

local items = ItemStack()
if items:set_name("default:dirt") then
    items:set_count(99)
else
    print("An error occured!")
end

And you can copy stacks like this:

local items2 = ItemStack(items)

Name and Count

local items = ItemStack("default:stone")
print(items:get_name()) -- default:stone
print(items:get_count()) -- 1

items:set_count(99)
print(items:get_name()) -- default:stone
print(items:get_count()) -- 99

if items:set_name("default:dirt") then
    print(items:get_name()) -- default:dirt
    print(items:get_count()) -- 99
else
    error("This shouldn't happen")
end

Adding and Taking Items

Adding

Use add_item to add items to an ItemStack. An ItemStack of the items that could not be added is returned.

local items = ItemStack("default:stone 50")
local to_add = ItemStack("default:stone 100")
local leftovers = items:add_item(to_add)

print("Could not add" .. leftovers:get_count() .. " of the items.")
-- ^ will be 51

Taking

The following code takes up to 100. If there aren't enough items in the stack, it will take as much as it can.

local taken = items:take_item(100)
-- taken is the ItemStack taken from the main ItemStack

print("Took " .. taken:get_count() .. " items")

Wear

ItemStacks also have wear on them. Wear is a number out of 65535, the higher it is, the more wear.

You use add_wear(), get_wear() and set_wear(wear).

local items = ItemStack("default:dirt")
local max_uses = 10

-- This is done automatically when you use a tool that digs things
-- It increases the wear of an item by one use.
items:add_wear(65535 / (max_uses - 1))

When digging a node, the amount of wear a tool gets may depends on the node being dug. So max_uses varies depending on what is being dug.

Lua Tables

local data = items:to_table()
local items2 = ItemStack(data)

Metadata

ItemStacks can have metadata, and use the same API as Node Metadata.

local meta = items:get_meta()
meta:set_string("foo", meta:get_string("foo") .. " ha!")

print(dump(meta:get_string("foo")))
-- if ran multiple times, would give " ha! ha! ha!"

More Methods

Have a look at the [list of methods for an ItemStack]({{ page.root }}/lua_api.html#methods_5). There are a lot more available than talked about here.