Paper/patches/api/0355-Add-enchantWithLevels-API.patch

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Jason Penilla <11360596+jpenilla@users.noreply.github.com>
Date: Wed, 16 Mar 2022 20:35:13 -0700
Subject: [PATCH] Add enchantWithLevels API

Deprecate upstream's newer and poorly implemented similar
API.

diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java
index 8c248dac47464757e013c25393fe9bf604ded7c2..0217f98a74140bbae454d467de27c12b6060ca75 100644
--- a/src/main/java/org/bukkit/inventory/ItemFactory.java
+++ b/src/main/java/org/bukkit/inventory/ItemFactory.java
@@ -185,8 +185,11 @@ public interface ItemFactory {
      * @param level the level to use, which is the level in the enchantment table
      * @param allowTreasures allows treasure enchants, e.g. mending, if true.
      * @return the modified ItemStack, or a copy if the ItemStack cannot be enchanted directly
+     * @deprecated use {@link #enchantWithLevels(ItemStack, int, boolean, java.util.Random)}. This method's implementation is poorly
+     * designed and was originally broken.
      */
     @NotNull
+    @Deprecated // Paper
     ItemStack enchantItem(@NotNull final Entity entity, @NotNull final ItemStack item, final int level, final boolean allowTreasures);
 
     /**
@@ -200,8 +203,11 @@ public interface ItemFactory {
      * @param allowTreasures allow the treasure enchants, e.g. mending, if true.
      * @return the modified ItemStack, or a copy if the ItemStack cannot be
      * enchanted directly
+     * @deprecated use {@link #enchantWithLevels(ItemStack, int, boolean, java.util.Random)}. This method's implementation is poorly
+     * designed and was originally broken.
      */
     @NotNull
+    @Deprecated // Paper
     ItemStack enchantItem(@NotNull final World world, @NotNull final ItemStack item, final int level, final boolean allowTreasures);
 
     /**
@@ -214,8 +220,11 @@ public interface ItemFactory {
      * @param allowTreasures allow treasure enchantments, e.g. mending, if true.
      * @return the modified ItemStack, or a copy if the ItemStack cannot be
      * enchanted directly
+     * @deprecated use {@link #enchantWithLevels(ItemStack, int, boolean, java.util.Random)}. This method's implementation is poorly
+     * designed and was originally broken.
      */
     @NotNull
+    @Deprecated // Paper
     ItemStack enchantItem(@NotNull final ItemStack item, final int level, final boolean allowTreasures);
 
     // Paper start - Adventure
@@ -328,4 +337,22 @@ public interface ItemFactory {
     @Deprecated
     net.md_5.bungee.api.chat.hover.content.Content hoverContentOf(@NotNull org.bukkit.entity.Entity entity, @NotNull net.md_5.bungee.api.chat.BaseComponent[] customName);
     // Paper end - bungee hover events
+
+    // Paper start - enchantWithLevels API
+    /**
+     * Randomly enchants a copy of the provided {@link ItemStack} using the given experience levels.
+     *
+     * <p>If the provided ItemStack is already enchanted, the existing enchants will be removed before enchanting.</p>
+     *
+     * <p>Levels must be in range {@code [1, 30]}.</p>
+     *
+     * @param itemStack ItemStack to enchant
+     * @param levels levels to use for enchanting
+     * @param allowTreasure whether to allow enchantments where {@link org.bukkit.enchantments.Enchantment#isTreasure()} returns true
+     * @param random {@link java.util.Random} instance to use for enchanting
+     * @return enchanted copy of the provided ItemStack
+     * @throws IllegalArgumentException on bad arguments
+     */
+    @NotNull ItemStack enchantWithLevels(@NotNull ItemStack itemStack, @org.jetbrains.annotations.Range(from = 1, to = 30) int levels, boolean allowTreasure, @NotNull java.util.Random random);
+    // Paper end - enchantWithLevels API
 }
diff --git a/src/main/java/org/bukkit/inventory/ItemStack.java b/src/main/java/org/bukkit/inventory/ItemStack.java
index f9faef1b73b5027a3d22e76a0b33b7c952f3ae08..eac7adf622b91489711a2f8bcff77fb31292dd67 100644
--- a/src/main/java/org/bukkit/inventory/ItemStack.java
+++ b/src/main/java/org/bukkit/inventory/ItemStack.java
@@ -656,6 +656,24 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
     }
 
     // Paper start
+    /**
+     * Randomly enchants a copy of this {@link ItemStack} using the given experience levels.
+     *
+     * <p>If this ItemStack is already enchanted, the existing enchants will be removed before enchanting.</p>
+     *
+     * <p>Levels must be in range {@code [1, 30]}.</p>
+     *
+     * @param levels levels to use for enchanting
+     * @param allowTreasure whether to allow enchantments where {@link org.bukkit.enchantments.Enchantment#isTreasure()} returns true
+     * @param random {@link java.util.Random} instance to use for enchanting
+     * @return enchanted copy of the provided ItemStack
+     * @throws IllegalArgumentException on bad arguments
+     */
+    @NotNull
+    public ItemStack enchantWithLevels(final @org.jetbrains.annotations.Range(from = 1, to = 30) int levels, final boolean allowTreasure, final @NotNull java.util.Random random) {
+        return Bukkit.getServer().getItemFactory().enchantWithLevels(this, levels, allowTreasure, random);
+    }
+
     @NotNull
     @Override
     public net.kyori.adventure.text.event.HoverEvent<net.kyori.adventure.text.event.HoverEvent.ShowItem> asHoverEvent(final @NotNull java.util.function.UnaryOperator<net.kyori.adventure.text.event.HoverEvent.ShowItem> op) {