SPIGOT-1526 / SPIGOT-1809: Expand Inventory API

By: md_5 <git@md-5.net>

paper-api/src/main/java/org/bukkit/inventory/Inventory.java

@@ -127,6 +127,28 @@ public interface Inventory extends Iterable<ItemStack> {
      */
     public void setContents(ItemStack[] items) throws IllegalArgumentException;
 
+    /**
+     * Return the contents from the section of the inventory where items can
+     * reasonably be expected to be stored. In most cases this will represent
+     * the entire inventory, but in some cases it may exclude armor or result
+     * slots.
+     * <br>
+     * It is these contents which will be used for add / contains / remove
+     * methods which look for a specific stack.
+     *
+     * @return inventory storage contents
+     */
+    public ItemStack[] getStorageContents();
+
+    /**
+     * Put the given ItemStacks into the storage slots
+     *
+     * @param items The ItemStacks to use as storage contents
+     * @throws IllegalArgumentException If the array has more items than the
+     * inventory.
+     */
+    public void setStorageContents(ItemStack[] items) throws IllegalArgumentException;
+
     /**
      * Checks if the inventory contains any ItemStacks with the given
      * materialId

paper-api/src/main/java/org/bukkit/inventory/PlayerInventory.java

@@ -3,7 +3,7 @@ package org.bukkit.inventory;
 import org.bukkit.entity.HumanEntity;
 
 /**
- * Interface to the inventory of a Player, including the four armor slots.
+ * Interface to the inventory of a Player, including the four armor slots and any extra slots.
  */
 public interface PlayerInventory extends Inventory {
 
@@ -14,6 +14,17 @@ public interface PlayerInventory extends Inventory {
      */
     public ItemStack[] getArmorContents();
 
+    /**
+     * Get all additional ItemStacks stored in this inventory.
+     * <br>
+     * NB: What defines an extra slot is up to the implementation, however it
+     * will not be contained within {@link #getStorageContents()} or
+     * {@link #getArmorContents()}
+     *
+     * @return All additional ItemStacks
+     */
+    public ItemStack[] getExtraContents();
+
     /**
      * Return the ItemStack from the helmet slot
      *
@@ -73,6 +84,15 @@ public interface PlayerInventory extends Inventory {
      */
     public void setArmorContents(ItemStack[] items);
 
+    /**
+     * Put the given ItemStacks into the extra slots
+     * <br>
+     * See {@link #getExtraContents()} for an explanation of extra slots.
+     *
+     * @param items The ItemStacks to use as extra
+     */
+    public void setExtraContents(ItemStack[] items);
+
     /**
      * Put the given ItemStack into the helmet slot. This does not check if
      * the ItemStack is a helmet