minetest_modding_book/_en/inventories/inventories.md

title	layout	root	idx	redirect_from
Inventories	default	../..	5.2	/en/chapters/inventories.html

Introduction

In this chapter you will learn how to use and 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
• Types of Inventories
  • Player Inventories
  • Node Inventories
  • Detached Inventories
• InvRef and Lists
  • Inventory Location
  • List Sizes
  • Empty Lists
  • Lua Tables
  • Lua Tables for Lists
• InvRef, Items and Stacks
  • Adding to a List
  • Checking for Room
  • Taking Items
  • Checking Inventory Contents
  • Manipulating Stacks

Basic Concepts

Components of an inventory:

• An inventory is a collection of inventory lists, which are simply called lists in the context of inventories.
• An inventory list is an array of slots. (An array is a table indexed by numbers).
• A slot contains a stack which may or may not be empty.
• An InvRef is an object that represents an inventory, and has functions to manipulate it.

Types of Inventories

There are three types of inventory:

• Player Inventories: An inventory attached to a player.
• Node Inventories: An inventory attached to a node.
• Detached Inventories: An inventory which is not attached to a node or player.

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 is 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.

Player Inventories

A player inventory usually has two grids, one for the main inventory and one for crafting. Press i in game to see your player inventory.

Use a player's name to get their inventory:

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

Node Inventories

A node inventory is related to the position of a specific node, such as a chest. The node must be loaded, because it is stored in node metadata.

Use its position to get a node inventory:

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. It is detached from any specific player because all players see the same creative inventory. A detached inventory would also allow multiple chests to share the same inventory.

Use the inventory name to get a detached inventory:

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

You can create your own detached inventories:

minetest.create_detached_inventory("inventory_name", callbacks)

This creates a detached inventory or, if the inventory already exists, it is cleared. You can also supply a [table of callbacks]({{ page.root }}/lua_api.html#detached-inventory-callbacks).

InvRef and Lists

Inventory Location

You can check where an inventory is located:

local location = inv:get_location()

This 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"))
else
    print("Error!")
end

Empty Lists

You can use list_is_empty to check if a list is empty:

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

Lua Tables

You can convert an inventory to a Lua table:

local lists = inv:get_lists()

The table will be in this form:

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

You can then set the inventory:

inv:set_lists(lists)

Please note that the sizes of lists will not change.

Lua Tables for Lists

You can do the above for individual lists:

local list = inv:get_list("list_one")

It will be in this form:

{
    ItemStack,
    ItemStack,
    ItemStack,
    ItemStack,
    -- inv:get_size("list_one") elements
}

You can then set the list:

inv:set_list("list_one", list)

Please note that the sizes of lists will not change.

InvRef, Items and Stacks

Adding to a List

To add items to a list named "main":

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")
end

Checking for Room

To check whether a list has room for items:

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

Taking Items

To remove items from a list:

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

Checking Inventory Contents

To check whether an inventory contains a specific quantity of an item:

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

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

Manipulating Stacks

You can manipulate individual stacks:

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