#712: Add API to get full result of crafting items

By: James Peters <email@jamesdpeters.com>

paper-api/src/main/java/org/bukkit/Bukkit.java

@@ -35,6 +35,7 @@ import org.bukkit.generator.ChunkGenerator;
 import org.bukkit.help.HelpMap;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
+import org.bukkit.inventory.ItemCraftResult;
 import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.Merchant;
@@ -943,6 +944,58 @@ public final class Bukkit {
         return server.getCraftingRecipe(craftingMatrix, world);
     }
 
+    /**
+     * Get the crafted item using the list of {@link ItemStack} provided.
+     *
+     * <p>The list is formatted as a crafting matrix where the index follow
+     * the pattern below:</p>
+     *
+     * <pre>
+     * [ 0 1 2 ]
+     * [ 3 4 5 ]
+     * [ 6 7 8 ]
+     * </pre>
+     *
+     * <p>The {@link World} and {@link Player} arguments are required to fulfill the Bukkit Crafting
+     * events.</p>
+     *
+     * <p>Calls {@link org.bukkit.event.inventory.PrepareItemCraftEvent} to imitate the {@link Player}
+     * initiating the crafting event.</p>
+     *
+     * @param craftingMatrix list of items to be crafted from.
+     *                       Must not contain more than 9 items.
+     * @param world The world the crafting takes place in.
+     * @param player The player to imitate the crafting event on.
+     * @return resulting {@link ItemCraftResult} containing the resulting item, matrix and any overflow items.
+     */
+    @NotNull
+    public static ItemCraftResult craftItemResult(@NotNull ItemStack[] craftingMatrix, @NotNull World world, @NotNull Player player) {
+        return server.craftItemResult(craftingMatrix, world, player);
+    }
+
+    /**
+     * Get the crafted item using the list of {@link ItemStack} provided.
+     *
+     * <p>The list is formatted as a crafting matrix where the index follow
+     * the pattern below:</p>
+     *
+     * <pre>
+     * [ 0 1 2 ]
+     * [ 3 4 5 ]
+     * [ 6 7 8 ]
+     * </pre>
+     *
+     * @param craftingMatrix list of items to be crafted from.
+     *                       Must not contain more than 9 items.
+     * @param world The world the crafting takes place in.
+     * @return resulting {@link ItemCraftResult} containing the resulting item, matrix and any overflow items.
+     */
+    @NotNull
+    public static ItemCraftResult craftItemResult(@NotNull ItemStack[] craftingMatrix, @NotNull World world) {
+        return server.craftItemResult(craftingMatrix, world);
+    }
+
+
     /**
      * Get the crafted item using the list of {@link ItemStack} provided.
      *
@@ -973,6 +1026,29 @@ public final class Bukkit {
         return server.craftItem(craftingMatrix, world, player);
     }
 
+    /**
+     * Get the crafted item using the list of {@link ItemStack} provided.
+     *
+     * <p>The list is formatted as a crafting matrix where the index follow
+     * the pattern below:</p>
+     *
+     * <pre>
+     * [ 0 1 2 ]
+     * [ 3 4 5 ]
+     * [ 6 7 8 ]
+     * </pre>
+     *
+     * @param craftingMatrix list of items to be crafted from.
+     *                       Must not contain more than 9 items.
+     * @param world The world the crafting takes place in.
+     * @return the {@link ItemStack} resulting from the given crafting matrix, if no recipe is found
+     * an ItemStack of {@link Material#AIR} is returned.
+     */
+    @NotNull
+    public static ItemStack craftItem(@NotNull ItemStack[] craftingMatrix, @NotNull World world) {
+        return server.craftItem(craftingMatrix, world);
+    }
+
     /**
      * Get an iterator through the list of crafting recipes.
      *

paper-api/src/main/java/org/bukkit/Server.java

@@ -35,6 +35,7 @@ import org.bukkit.generator.ChunkGenerator;
 import org.bukkit.help.HelpMap;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
+import org.bukkit.inventory.ItemCraftResult;
 import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.Merchant;
@@ -835,6 +836,74 @@ public interface Server extends PluginMessageRecipient {
     @NotNull
     public ItemStack craftItem(@NotNull ItemStack[] craftingMatrix, @NotNull World world, @NotNull Player player);
 
+    /**
+     * Get the crafted item using the list of {@link ItemStack} provided.
+     *
+     * <p>The list is formatted as a crafting matrix where the index follow
+     * the pattern below:</p>
+     *
+     * <pre>
+     * [ 0 1 2 ]
+     * [ 3 4 5 ]
+     * [ 6 7 8 ]
+     * </pre>
+     *
+     * @param craftingMatrix list of items to be crafted from.
+     *                       Must not contain more than 9 items.
+     * @param world The world the crafting takes place in.
+     * @return the {@link ItemStack} resulting from the given crafting matrix, if no recipe is found
+     * an ItemStack of {@link Material#AIR} is returned.
+     */
+    @NotNull
+    public ItemStack craftItem(@NotNull ItemStack[] craftingMatrix, @NotNull World world);
+
+    /**
+     * Get the crafted item using the list of {@link ItemStack} provided.
+     *
+     * <p>The list is formatted as a crafting matrix where the index follow
+     * the pattern below:</p>
+     *
+     * <pre>
+     * [ 0 1 2 ]
+     * [ 3 4 5 ]
+     * [ 6 7 8 ]
+     * </pre>
+     *
+     * <p>The {@link World} and {@link Player} arguments are required to fulfill the Bukkit Crafting
+     * events.</p>
+     *
+     * <p>Calls {@link org.bukkit.event.inventory.PrepareItemCraftEvent} to imitate the {@link Player}
+     * initiating the crafting event.</p>
+     *
+     * @param craftingMatrix list of items to be crafted from.
+     *                       Must not contain more than 9 items.
+     * @param world The world the crafting takes place in.
+     * @param player The player to imitate the crafting event on.
+     * @return resulting {@link ItemCraftResult} containing the resulting item, matrix and any overflow items.
+     */
+    @NotNull
+    public ItemCraftResult craftItemResult(@NotNull ItemStack[] craftingMatrix, @NotNull World world, @NotNull Player player);
+
+    /**
+     * Get the crafted item using the list of {@link ItemStack} provided.
+     *
+     * <p>The list is formatted as a crafting matrix where the index follow
+     * the pattern below:</p>
+     *
+     * <pre>
+     * [ 0 1 2 ]
+     * [ 3 4 5 ]
+     * [ 6 7 8 ]
+     * </pre>
+     *
+     * @param craftingMatrix list of items to be crafted from.
+     *                       Must not contain more than 9 items.
+     * @param world The world the crafting takes place in.
+     * @return resulting {@link ItemCraftResult} containing the resulting item, matrix and any overflow items.
+     */
+    @NotNull
+    public ItemCraftResult craftItemResult(@NotNull ItemStack[] craftingMatrix, @NotNull World world);
+
     /**
      * Get an iterator through the list of crafting recipes.
      *

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

@@ -0,0 +1,38 @@
+package org.bukkit.inventory;
+
+import java.util.List;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Container class containing the results of a Crafting event.
+ * <br>
+ * This class makes no guarantees about the nature or mutability of the returned
+ * values.
+ */
+public interface ItemCraftResult {
+
+    /**
+     * The resulting {@link ItemStack} that was crafted.
+     *
+     * @return {@link ItemStack} that was crafted.
+     */
+    @NotNull
+    public ItemStack getResult();
+
+    /**
+     * Gets the resulting matrix from the crafting operation.
+     *
+     * @return resulting matrix
+     */
+    @NotNull
+    public ItemStack[] getResultingMatrix();
+
+    /**
+     * Gets the overflowed items for items that don't fit back into the crafting
+     * matrix.
+     *
+     * @return overflow items
+     */
+    @NotNull
+    public List<ItemStack> getOverflowItems();
+}