diff --git a/_en/inventories/inventories.md b/_en/inventories/inventories.md deleted file mode 100644 index 28c24a5..0000000 --- a/_en/inventories/inventories.md +++ /dev/null @@ -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. - -
- 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 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: - -```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 -``` - - - -### 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) -``` diff --git a/_en/inventories/itemstacks.md b/_en/inventories/itemstacks.md deleted file mode 100644 index 366930c..0000000 --- a/_en/inventories/itemstacks.md +++ /dev/null @@ -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. diff --git a/_en/items/inventories.md b/_en/items/inventories.md new file mode 100644 index 0000000..5bc293a --- /dev/null +++ b/_en/items/inventories.md @@ -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", {}) +``` diff --git a/_layouts/default.html b/_layouts/default.html index e7d8340..beb632b 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -12,6 +12,7 @@ layout: compress + {% assign pathsplit = page.dir | split: '/' %} @@ -79,7 +80,6 @@ layout: compress -