Inventory#removeItemAnySlot

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

@@ -104,7 +104,37 @@ public interface Inventory extends Iterable<ItemStack> {
     public HashMap<Integer, ItemStack> addItem(@NotNull ItemStack... items) throws IllegalArgumentException;
 
     /**
-     * Removes the given ItemStacks from the inventory.
+     * Removes the given ItemStacks from the storage contents of the inventory.
+     * For removing ItemStacks from the inventories that have other content groups,
+     * like Player inventories, see {@link #removeItemAnySlot(ItemStack...)}.
+     * <p>
+     * It will try to remove 'as much as possible' from the types and amounts
+     * you give as arguments.
+     * <p>
+     * The returned HashMap contains what it couldn't remove, where the key is
+     * the index of the parameter, and the value is the ItemStack at that
+     * index of the varargs parameter. If all the given ItemStacks are
+     * removed, it will return an empty HashMap.
+     * <p>
+     * It is known that in some implementations this method will also set the
+     * inputted argument amount to the number of that item not removed from
+     * slots.
+     *
+     * @param items The ItemStacks to remove
+     * @return A HashMap containing items that couldn't be removed.
+     * @throws IllegalArgumentException if items is null
+     * @see #removeItemAnySlot(ItemStack...)
+     */
+    @NotNull
+    public HashMap<Integer, ItemStack> removeItem(@NotNull ItemStack... items) throws IllegalArgumentException;
+
+    // Paper start
+    /**
+     * Searches all possible inventory slots in order to remove the given ItemStacks.
+     * <p>
+     * Similar to {@link Inventory#removeItem(ItemStack...)} in behavior, except this
+     * method will check all possible slots in the inventory, rather than just the main
+     * storage contents.
      * <p>
      * It will try to remove 'as much as possible' from the types and amounts
      * you give as arguments.
@@ -123,7 +153,8 @@ public interface Inventory extends Iterable<ItemStack> {
      * @throws IllegalArgumentException if items is null
      */
     @NotNull
-    public HashMap<Integer, ItemStack> removeItem(@NotNull ItemStack... items) throws IllegalArgumentException;
+    public HashMap<Integer, ItemStack> removeItemAnySlot(@NotNull ItemStack... items) throws IllegalArgumentException;
+    // Paper end
 
     /**
      * Returns all ItemStacks from the inventory