In this chapter you will learn how to use manipulate inventories, whether that is a player inventory, a node inventory, or a detached inventory. This chapter assumes that you already know how to create and manipulate ItemStacks.

Basic Concepts

Components of an inventory:

There are three ways you can get inventories:

The player inventory formspec, with annotated list names.
This image shows the two inventories visible when you press i. The gray boxes are inventory lists.
The creative inventory, left (in red) is detached and it made up of a single list.
The player inventory, right (in blue) is a player inventory and is made up of three lists.
Note that the trash can is a formspec element, and is not part of the inventory.

Types of Inventories

There are three types of Inventories.

Player Inventories.

This is what you see when you press i. A player inventory usually has two grids, one for the main inventory, one for crafting.

local inv = minetest.get_inventory({type="player", name="celeron55"})

Node Inventories.

An inventory related to a position, such as a chest. The node must be loaded, as it’s stored in Node Metadata.

local inv = minetest.get_inventory({type="node", pos={x=, y=, z=}})

Detached Inventories

A detached inventory is independent of players and nodes. One example of a detached inventory is the creative inventory is detached, as all players see the same inventory. You may also use this if you want multiple chests to share the same inventory.

This is how you get a detached inventory:

local inv = minetest.get_inventory({type="detached", name="inventory_name"})

And this is how you can create one:

minetest.create_detached_inventory("inventory_name", callbacks)

Creates a detached inventory. If it already exists, it is cleared. You can supply a table of callbacks.

InvRef and Lists

Type of Inventory

You can check where the inventory is from by doing:

local location = inv:get_location()

It will return a table like the one passed to minetest.get_inventory().

If the location is unknown, {type="undefined"} is returned.

List sizes

Inventory lists have a size, for example main has size of 32 slots by default. They also have a width, which is used to divide them into a grid.

if inv:set_size("main", 32) then
	inv:set_width("main", 8)
	print("size:  " .. inv.get_size("main"))
	print("width: " .. inv:get_width("main"))

List is empty

if inv:is_empty("main") then
	print("The list is empty!")

Lua Tables

You can convert an inventory to a Lua table using:

local lists = inv:get_lists()

It will be in this form:

	list_one = {
		-- inv:get_size("list_one") elements
	list_two = {
		-- inv:get_size("list_two") elements

You can then set an inventory like this:


Please note that the sizes of lists will not change.

Lua Tables for Lists

You can do the same as above, but for individual lists

local list = inv:get_list("list_one")

It will be in this form:

	-- inv:get_size("list_one") elements

You can then set the list like this:

inv:set_list("list_one", list)

Please note that the sizes of lists will not change.

InvRef, Items and Items

Adding to a list

local stack = ItemStack("default:stone 99")
local leftover = inv:add_item("main", stack)
if leftover:get_count() > 0 then
	print("Inventory is full! " .. leftover:get_count() .. " items weren't added")

"main" is the name of the list you’re adding to.

Checking for room

if not inv:room_for_item("main", stack) then
	print("Not enough room!")

Taking items

local taken = inv:remove_item("main", stack)
print("Took " .. taken:get_count())


This works if the item count is split up over multiple stacks, for example looking for “default:stone 200” will work if there are stacks of 99 + 95 + 6.

if not inv:contains_item(listname, stack) then
	print("Item not in inventory!")

Manipulating Stacks

Finally, you can manipulate individual stacks like so:

local stack = inv:get_stack(listname, 0)
inv:set_stack(listname, 0, stack)