utilities/Inventory, Items and Item Transfer
This page covers the item to item, inventory to item, item to inventory and inventory to inventory transfer principles. It covers how item(s) go from one place to another, and the methods available to achieve this. It also covers several other item utilities, new base classes you can use and use cases.
An ItemParser is used to define the rules for a transfer operation. It can be created from user input using a certain format, but can also be created in-code. An item parser has the following 'fields':
- Has amount and amount: the maximum amount of items that is allowed to be transferred, and whether this is used
- Has type and type: the item type to be transferred, and whether an item type restriction is there
- Has data and data: the item data to be transferred, and whether an item data restriction is there All these settings will be used when transferring items.
There are rules defined to create an item parser from user input, these are:
- The : sign delimits type and data
- The x, X, *, <space>, <comma> and @ signs are used to delimit data/type and the amount
- Type can be the material ID, or the material name, or part of a material name (it uses ParseUtil.parseMaterial)
- Data can be a value from 0 to 15, or an identifier of data for the type (e.g. wood, stone, etc.)
|5xwood||5 pieces of wood|
|12@ironore||12 pieces of iron ore|
|5xwool:red||5 pieces of red wool|
|6xcoal:1||6 pieces of charcoal|
|22xlog:birch||22 pieces of birch logs|
Transfer and Item Utilities
All utilities can be found in ItemUtil. All methods called 'transfer' transfer items from one place to another. There are also methods to check whether a full transfer is possible at all, allowing you to check it before having a failing result.
This class also contains several other item-related utilities, such as those to clone items, clone inventory contents, transfer item metadata, constructing an empty item which has a handle, and much more. Whenever you run into something that has to do with items, check whether there is a method in ItemUtil that could make your life easier.
There are also several base classes you can use. All of them extend CraftInventory (or another type used by the implementation), so it is required to compile against CraftBukkit to get around 'class hierarchy' errors. They pose no real threat in this case. The base classes are:
- InventoryBase - a base class that has everything implemented except the getting and setting of items
- InventoryBaseImp - base implementation backed by an array of ItemStack
- MergedInventory - an inventory of inventories, merging multiple together as one
If you need a quick and dirty way to implement your own Inventory type, these base classes make this a lot easier. Since the base class extends CraftBukkit's inventory, you are automatically provided with the latest methods Bukkit has to offer.