diff --git a/paper-api/src/main/java/org/bukkit/inventory/ItemFactory.java b/paper-api/src/main/java/org/bukkit/inventory/ItemFactory.java index e1986aea72..0a814c1f65 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/ItemFactory.java +++ b/paper-api/src/main/java/org/bukkit/inventory/ItemFactory.java @@ -338,4 +338,21 @@ public interface ItemFactory { */ @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 + // Paper start - enchantWithLevels with tag specification + /** + * 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 keySet registry key set defining the set of possible enchantments, e.g. {@link io.papermc.paper.registry.keys.tags.EnchantmentTagKeys#IN_ENCHANTING_TABLE}. + * @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, @NotNull io.papermc.paper.registry.set.RegistryKeySet<@NotNull Enchantment> keySet, @NotNull java.util.Random random); + // Paper end - enchantWithLevels with tag specification } diff --git a/paper-api/src/main/java/org/bukkit/inventory/ItemStack.java b/paper-api/src/main/java/org/bukkit/inventory/ItemStack.java index a55ff2ecfb..3c4e83494d 100644 --- a/paper-api/src/main/java/org/bukkit/inventory/ItemStack.java +++ b/paper-api/src/main/java/org/bukkit/inventory/ItemStack.java @@ -678,6 +678,23 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat return Bukkit.getServer().getItemFactory().enchantWithLevels(this, levels, allowTreasure, random); } + /** + * Randomly enchants a copy of this {@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 levels levels to use for enchanting + * @param keySet registry key set defining the set of possible enchantments, e.g. {@link io.papermc.paper.registry.keys.tags.EnchantmentTagKeys#IN_ENCHANTING_TABLE}. + * @param random {@link java.util.Random} instance to use for enchanting + * @return enchanted copy of the provided ItemStack + * @throws IllegalArgumentException on bad arguments + */ + public @NotNull ItemStack enchantWithLevels(final @org.jetbrains.annotations.Range(from = 1, to = 30) int levels, final @NotNull io.papermc.paper.registry.set.RegistryKeySet<@NotNull Enchantment> keySet, final @NotNull java.util.Random random) { + return Bukkit.getItemFactory().enchantWithLevels(this, levels, keySet, random); + } + @NotNull @Override public net.kyori.adventure.text.event.HoverEvent asHoverEvent(final @NotNull java.util.function.UnaryOperator op) {