MTSR/minetest_modding_book
4
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

ItemStacks and Inventories: Merge into one chapter

Browse Source
This commit is contained in:
rubenwardy 2018-09-23 13:02:18 +01:00
parent 762fe6b8e3
commit c20f6d200c
No known key found for this signature in database
GPG Key ID: A1E29D52FF81513C
4 changed files with 302 additions and 411 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

271
_en/inventories/inventories.md
View File

@ -1,271 +0,0 @@
---
title: Inventories
layout: default
root: ../..
idx: 5.2
redirect_from: /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](itemstacks.html).
* [Basic Concepts](#basic-concepts)
* [Types of Inventories](#types-of-inventories)
* [Player Inventories](#player-inventories)
* [Node Inventories](#node-inventories)
* [Detached Inventories](#detached-inventories)
* [InvRef and Lists](#invref-and-lists)
* [Inventory Location](#inventory-location)
* [List Sizes](#list-sizes)
* [Empty Lists](#empty-lists)
* [Lua Tables](#lua-tables)
* [Lua Tables for Lists](#lua-tables-for-lists)
* [InvRef, Items and Stacks](#invref-items-and-stacks)
* [Adding to a List](#adding-to-a-list)
* [Checking for Room](#checking-for-room)
* [Taking Items](#taking-items)
* [Checking Inventory Contents](#checking-inventory-contents)
* [Manipulating Stacks](#manipulating-stacks)
## Basic Concepts
Components of an inventory:
* An **inventory** is a collection of **inventory list**s, which are simply called **list**s in the context of inventories.
* An **inventory list** is an array of **slot**s. (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.
<figure>
<img src="{{ page.root }}//static/inventories_lists.png" alt="The player inventory formspec, with annotated list names.">
<figcaption>
This image shows the two inventories visible when you press i.
The gray boxes are inventory lists.<br />
The creative inventory, left (in red) is detached and is made up of a
single list.<br />
The player inventory, right (in blue) is a player inventory
and is made up of three lists.<br />
Note that the trash can is a <a href="formspecs.html">formspec</a>
element, and is not part of the inventory.
</figcaption>
</figure>
### 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:
```lua
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](node_metadata.html).
Use its position to get a node inventory:
```lua
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:
```lua
local inv = minetest.get_inventory({type="detached", name="inventory_name"})
```
You can create your own detached inventories:
```lua
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:
```lua
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.
```lua
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
```
<!--The width and height of an inventory in a [formspec](formspecs.html) is
determined by the formspec element, not by the inventory. By that I mean
a list doesn't have a width or height, only the maximum number of stacks/slots.-->
### Empty Lists
You can use `list_is_empty` to check if a list is empty:
```lua
if inv:is_empty("main") then
print("The list is empty!")
end
```
### Lua Tables
You can convert an inventory to a Lua table:
```lua
local lists = inv:get_lists()
```
The table will be in this form:
```lua
{
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:
```lua
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:
```lua
local list = inv:get_list("list_one")
```
It will be in this form:
```lua
{
ItemStack,
ItemStack,
ItemStack,
ItemStack,
-- inv:get_size("list_one") elements
}
```
You can then set the list:
```lua
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"`:
```lua
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:
```lua
if not inv:room_for_item("main", stack) then
print("Not enough room!")
end
```
### Taking Items
To remove items from a list:
```lua
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:
```lua
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:
```lua
local stack = inv:get_stack(listname, 0)
inv:set_stack(listname, 0, stack)
```

139
_en/inventories/itemstacks.md
View File

@ -1,139 +0,0 @@
---
title: ItemStacks
layout: default
root: ../..
idx: 5.1
redirect_from: /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:
```lua
local items = ItemStack("default:dirt")
local items = ItemStack("default:stone 99")
```
You could alternatively create a blank ItemStack and fill it using methods:
```lua
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:
```lua
local items2 = ItemStack(items)
```
## Name and Count
```lua
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.
```lua
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.
```lua
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)`.
```lua
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
```lua
local data = items:to_table()
local items2 = ItemStack(data)
```
## Metadata
ItemStacks can have metadata, and use the same API as [Node Metadata](node_metadata.html).
```lua
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.

301
_en/items/inventories.md Normal file
View File

@ -0,0 +1,301 @@
---
title: ItemStacks and Inventories
layout: default
root: ../..
idx: 2.4
description: Manipulate InvRefs and ItemStacks
redirect_from:
- /en/chapters/inventories.html
- /en/chapters/itemstacks.html
- /en/inventories/inventories.html
- /en/inventories/itemstacks.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.
* [What are Item Stacks and Inventories?](#what-are-item-stacks-and-inventories)
* [ItemStacks](#itemstacks)
* [Inventory Locations](#inventory-locations)
* [Lists](#lists)
* [Size and Width](#size-and-width)
* [Checking Contents](#checking-contents)
* [Modifying Inventories and ItemStacks](#modifying-inventories-and-itemstacks)
* [Adding to a List](#adding-to-a-list)
* [Taking Items](#taking-items)
* [Manipulating Stacks](#manipulating-stacks)
* [Wear](#wear)
* [Lua Tables](#lua-tables)
## What are ItemStacks and Inventories?
An ItemStack is the data behind a single cell in an inventory.
An *inventory* is a collection of *inventory lists*, each of which
is a 2D grid of ItemStacks.
Inventory lists are simply called *lists* in the context
of inventories.
The point of an inventory is to allow multiple grids when Players
and Nodes only have at most one inventory in them.
## ItemStacks
ItemStacks have three components to them.
The item name may be the item name of a registered item, an alias, or an unknown
item name.
Unknown items are common when users uninstall mods, or when mods remove items without
any mitigation such as registering an alias.
```lua
print(stack:get_name())
stack:set_name("default:dirt")
if not stack:is_known() then
print("Is an unknown item!")
end
```
The count will always be 0 or greater.
Through normal gameplay, the count should be no more than the maximum stack size
of the item - `stack_max`.
However, admin commands and buggy mods may result in stacks exceeding the maximum
size.
```lua
print(stack:get_stack_max())
```
An ItemStack can be empty, in which case the count will be 0.
```lua
print(stack:get_count())
stack:set_count(10)
```
ItemStacks can be constructed in multiple ways using the ItemStack function.
```lua
ItemStack() -- name="", count=0
ItemStack("default:pick_stone") -- count=1
ItemStack("default:stone 30")
ItemStack({ name = "default:wood", count = 10 })
```
Item metadata is an unlimited key-value store for data about the item.
Key-value means that you use a name (called the key) to access the data (called the value).
Some keys have special meaning, such as `description` which is used to have a per-stack
item description.
This will be covered in more detail in the Metadata and Storage chapter.
## Inventory Locations
An Inventory Location is where and how the inventory is stored.
There are three types of inventory location: player, node, and detached.
An inventory is directly tied to one and only one location - updating the inventory
will cause it to update immediately.
Node inventories are related to the position of a specific node, such as a chest.
The node must be loaded, because it is stored in [node metadata](node_metadata.html).
```lua
local inv = minetest.get_inventory({ type="node", pos={x=1, y=2, z=3} })
```
The above obtains an *inventory reference*, commonly referred to as *InvRef*.
Inventory references are used to manipulate an inventory.
*Reference* means that the data isn't actually stored inside that object,
but the object instead directly updates the data in-place.
Player inventories can be obtained similarly or using a player reference.
The player must be online to access their inventory.
```lua
local inv = minetest.get_inventory({ type="player", name="player1" })
-- or
local inv = player:get_inventory()
```
A detached inventory is one which is independent of players or nodes.
Detached inventories also don't save over a restart.
Detached inventories need to be created before then can be retrieved -
this will be covered latter.
```lua
local inv = minetest.get_inventory({ type="detached", name="inventory_name" })
```
The location of an inventory reference can be found like so:
```lua
local location = inv:get_location()
```
## Lists
Inventory Lists are a concept used to allow multiple grids to be stored inside a single location.
This is especially useful for the player as there are a number of common lists
which all games have, such as the *main* inventory and *craft* slots.
### Size and Width
Lists have a size, which is the number of cells in the grid, and a width,
which is used when the engine.
The List width is not used when drawing the inventory in a window, as the
code behind the window determines the width to use.
```lua
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! Invalid itemname or size to set_size()")
end
```
`set_size` will fail and return false if the listname or size is invalid.
For example, the new size may be too small to fit all the current items
in the inventory.
### Checking Contents
`is_empty` can be used to see if a list contains any items:
```lua
if inv:is_empty("main") then
print("The list is empty!")
end
```
`contains_item` can be used to see if a list contains a specific item.
## Modifying Inventories and ItemStacks
### Adding to a List
To add items to a list named `"main"`, whilst respecting any maximum stack sizes:
```lua
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
```
### Taking Items
To remove items from a list:
```lua
local taken = inv:remove_item("main", stack)
print("Took " .. taken:get_count())
```
### Manipulating Stacks
You can modify individual stacks by first getting them:
```lua
local stack = inv:get_stack(listname, 0)
```
Then modifying them by setting properties or by using the methods which
respect `stack_size`:
```lua
local stack = ItemStack("default:stone 50")
local to_add = ItemStack("default:stone 100")
local leftover = stack:add_item(to_add)
local taken = stack:take_item(19)
print("Could not add" .. leftover:get_count() .. " of the items.")
-- ^ will be 51
print("Have " .. stack:get_count() .. " items")
-- ^ will be 80
-- min(50+100, stack_max) - 19 = 80
-- where stack_max = 99
```
`add_item` will add items to an ItemStack and return any that could not be added.
`take_item` will take up to the number of items but may take less, and returns the stack taken.
Finally, set the item stack:
```lua
inv:set_stack(listname, 0, stack)
```
## Wear
Tools can have wear; wear shows a progress bar and makes the tool break when completely worn.
Wear is a number out of 65535, the higher it is, the more worn the tool is.
Wear can be manipulated using `add_wear()`, `get_wear()` and `set_wear(wear)`.
```lua
local stack = ItemStack("default:pick_mese")
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.
stack: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
ItemStacks and Inventories can be converted to and from tables.
This is useful for copying and bulk operations.
```lua
-- Entire inventory
local data = inv1:get_lists()
inv2:set_lists(data)
-- One list
local listdata = inv1:get_list("main")
inv2:set_list("main", listdata)
```
The table of lists returned by `get_lists()` will be in this form:
```lua
{
list_one = {
ItemStack,
ItemStack,
ItemStack,
ItemStack,
-- inv:get_size("list_one") elements
},
list_two = {
ItemStack,
ItemStack,
ItemStack,
ItemStack,
-- inv:get_size("list_two") elements
}
}
```
`get_list()` will return a single list as just a list of ItemStacks.
One important thing to note is that the set methods above don't change the size
of the lists.
This means that you can clear a list by setting it to an empty table and it won't
decrease in size:
```lua
inv:set_list("main", {})
```

2
_layouts/default.html
View File

@ -12,6 +12,7 @@ layout: compress
<meta name="keywords" content="Minetest, modding, book, tutorial, guide, easy"> <meta name="keywords" content="Minetest, modding, book, tutorial, guide, easy">
<meta name="author" content="rubenwardy"> <meta name="author" content="rubenwardy">
<style>body,html,nav{background:#333}nav,nav li,nav li a{display:block}body,html,main,nav li{margin:0;padding:0}main,nav{position:absolute;top:0}body,html{font-size:17px;color:#000}#container{width:100%;max-width:1100px;margin:auto;position:relative}nav{left:0;width:280px;list-style:none;color:#fff}nav li a{padding:5px;color:#ccc;text-decoration:none}main{left:280px;right:0}article{background:#fff;padding:0 20px 20px}</style> <style>body,html,nav{background:#333}nav,nav li,nav li a{display:block}body,html,main,nav li{margin:0;padding:0}main,nav{position:absolute;top:0}body,html{font-size:17px;color:#000}#container{width:100%;max-width:1100px;margin:auto;position:relative}nav{left:0;width:280px;list-style:none;color:#fff}nav li a{padding:5px;color:#ccc;text-decoration:none}main{left:280px;right:0}article{background:#fff;padding:0 20px 20px}</style>
<link rel="stylesheet" href="{{ page.root }}/static/style.css">
</head> </head>
<body> <body>
{% assign pathsplit = page.dir | split: '/' %} {% assign pathsplit = page.dir | split: '/' %}
@ -79,7 +80,6 @@ layout: compress
</footer> </footer>
</article> </article>
</main> </main>
<link rel="stylesheet" href="{{ page.root }}/static/style.css">
<script async src="https://code.jquery.com/jquery-1.11.2.min.js"></script> <script async src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
<script async src="{{ page.root }}/static/script.js"></script> <script async src="{{ page.root }}/static/script.js"></script>
</body> </body>