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 96546712f788e091749a1b4eebc6b1d6c3db7814..bd0e55562f1cabef3078573182e0cf9fbc844585 100644 --- a/src/main/java/org/bukkit/inventory/ItemFactory.java +++ b/src/main/java/org/bukkit/inventory/ItemFactory.java @@ -170,8 +170,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 a new ItemStack containing the result of the Enchantment + * @deprecated use {@link #enchantWithLevels(ItemStack, int, boolean, java.util.Random)}. This method's implementation is poorly + * designed and was originally broken. */ @NotNull + @Deprecated(since = "1.19.3") // Paper ItemStack enchantItem(@NotNull final Entity entity, @NotNull final ItemStack item, final int level, final boolean allowTreasures); /** @@ -184,8 +187,11 @@ public interface ItemFactory { * @param level the level to use, which is the level in the enchantment table * @param allowTreasures allow the treasure enchants, e.g. mending, if true. * @return a new ItemStack containing the result of the Enchantment + * @deprecated use {@link #enchantWithLevels(ItemStack, int, boolean, java.util.Random)}. This method's implementation is poorly + * designed and was originally broken. */ @NotNull + @Deprecated(since = "1.19.3") // Paper ItemStack enchantItem(@NotNull final World world, @NotNull final ItemStack item, final int level, final boolean allowTreasures); /** @@ -197,8 +203,11 @@ public interface ItemFactory { * @param level the level to use, which is the level in the enchantment table * @param allowTreasures allow treasure enchantments, e.g. mending, if true. * @return a new ItemStack containing the result of the Enchantment + * @deprecated use {@link #enchantWithLevels(ItemStack, int, boolean, java.util.Random)}. This method's implementation is poorly + * designed and was originally broken. */ @NotNull + @Deprecated(since = "1.19.3") // Paper ItemStack enchantItem(@NotNull final ItemStack item, final int level, final boolean allowTreasures); // Paper start - Adventure @@ -311,4 +320,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. + * + *

If the provided ItemStack is already enchanted, the existing enchants will be removed before enchanting.

+ * + *

Levels must be in range {@code [1, 30]}.

+ * + * @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 d4178bc7a51bdcfb2446510de66e4fff1b0a86ec..6fffdec6fa82f7aae901984dc0a844da02e6eb2e 100644 --- a/src/main/java/org/bukkit/inventory/ItemStack.java +++ b/src/main/java/org/bukkit/inventory/ItemStack.java @@ -679,6 +679,24 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat } // Paper start + /** + * Randomly enchants a copy of this {@link ItemStack} using the given experience levels. + * + *

If this ItemStack is already enchanted, the existing enchants will be removed before enchanting.

+ * + *

Levels must be in range {@code [1, 30]}.

+ * + * @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 asHoverEvent(final @NotNull java.util.function.UnaryOperator op) {