From f2b2fd52d4b93194e914fa79f803018b7843a0bf Mon Sep 17 00:00:00 2001 From: Bukkit/Spigot <noreply+git-bukkit@papermc.io> Date: Mon, 6 Nov 2023 20:37:32 +1100 Subject: [PATCH] #712: Add API to get full result of crafting items By: James Peters <email@jamesdpeters.com> --- .../src/main/java/org/bukkit/Bukkit.java | 76 +++++++++++++++++++ .../src/main/java/org/bukkit/Server.java | 69 +++++++++++++++++ .../org/bukkit/inventory/ItemCraftResult.java | 38 ++++++++++ 3 files changed, 183 insertions(+) create mode 100644 paper-api/src/main/java/org/bukkit/inventory/ItemCraftResult.java diff --git a/paper-api/src/main/java/org/bukkit/Bukkit.java b/paper-api/src/main/java/org/bukkit/Bukkit.java index d0532011ad..b9c181540e 100644 --- a/paper-api/src/main/java/org/bukkit/Bukkit.java +++ b/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. * diff --git a/paper-api/src/main/java/org/bukkit/Server.java b/paper-api/src/main/java/org/bukkit/Server.java index e0df925316..e033b5753c 100644 --- a/paper-api/src/main/java/org/bukkit/Server.java +++ b/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. * diff --git a/paper-api/src/main/java/org/bukkit/inventory/ItemCraftResult.java b/paper-api/src/main/java/org/bukkit/inventory/ItemCraftResult.java new file mode 100644 index 0000000000..ebb4d19e0a --- /dev/null +++ b/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(); +}