Package io.artificial.enchantments.api

Interface EnchantmentDefinition

All Known Implementing Classes:
EnchantmentDefinitionImpl
public interface EnchantmentDefinition
Defines a custom enchantment that can be registered with the library.

An enchantment definition includes all metadata needed for registration, application to items, and effect scaling. Definitions are immutable after creation and can be built using the EnchantmentDefinition.Builder.

Example Usage: 


 EnchantmentDefinition myEnchant = EnchantmentDefinition.builder()
     .key(new NamespacedKey(plugin, "my_enchant"))
     .displayName(Component.text("My Enchant"))
     .description(Component.text("Does cool stuff"))
     .minLevel(1)
     .maxLevel(5)
     .scaling(LevelScaling.linear(1.0, 0.5))
     .applicable(Material.DIAMOND_SWORD, Material.IRON_SWORD)
     .rarity(EnchantmentDefinition.Rarity.RARE)
     .effectHandler(new MyEffectHandler())
     .build();
 
 ArtificialEnchantmentsAPI.registerBootstrapEnchantment(myEnchant);
Since:
0.1.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    EnchantmentDefinition.Builder
    Builder for creating enchantment definitions.
    static enum 
    EnchantmentDefinition.Rarity
    Rarity tiers for enchantments, affecting trading and loot weights.

  • Method Summary

    Modifier and Type
    Method
    Description
    static @NotNull EnchantmentDefinition.Builder
    builder()
    Creates a new builder for constructing enchantment definitions.
    double
    calculateScaledValue(int level)
    Calculates the scaled value for a given level.
    boolean
    conflictsWith(@NotNull EnchantmentDefinition other)
    Checks if this enchantment conflicts with another.
    @NotNull Set<org.bukkit.Material>
    getApplicableMaterials()
    Gets all materials this enchantment can be applied to.
    @NotNull Set<org.bukkit.NamespacedKey>
    getConflictingEnchantments()
    Gets all enchantment keys that conflict with this one.
    @Nullable net.kyori.adventure.text.Component
    getDescription()
    Gets the optional description shown in lore.
    @NotNull net.kyori.adventure.text.Component
    getDisplayName()
    Gets the display name shown to players.
    @Nullable EnchantmentEffectHandler
    getEffectHandler()
    Gets the effect handler for this enchantment, if any.
    @NotNull org.bukkit.NamespacedKey
    getKey()
    Gets the unique namespaced key for this enchantment.
    int
    getMaxLevel()
    Gets the maximum valid level for this enchantment.
    int
    getMinLevel()
    Gets the minimum valid level for this enchantment.
    @NotNull EnchantmentDefinition.Rarity
    getRarity()
    Gets the rarity tier of this enchantment.
    @NotNull LevelScaling
    getScaling()
    Gets the scaling formula for calculating effect values.
    boolean
    isApplicableTo(@NotNull org.bukkit.Material material)
    Checks if this enchantment can be applied to a specific material.
    boolean
    isApplicableTo(@NotNull org.bukkit.inventory.ItemStack item)
    Checks if this enchantment can be applied to an item.
    boolean
    isCurse()
    Checks if this is a curse enchantment.
    boolean
    isDiscoverable()
    Checks if this enchantment can be found in loot.
    boolean
    isTradeable()
    Checks if this enchantment can be traded with villagers.

  • Method Details

    • getKey

      @NotNull @NotNull org.bukkit.NamespacedKey getKey()
      Gets the unique namespaced key for this enchantment.
      Returns:
      the enchantment's key (never null)
      Since:
      0.1.0

    • getDisplayName

      @NotNull @NotNull net.kyori.adventure.text.Component getDisplayName()
      Gets the display name shown to players.
      Returns:
      the display name component (never null)
      Since:
      0.1.0

    • getDescription

      @Nullable @Nullable net.kyori.adventure.text.Component getDescription()
      Gets the optional description shown in lore.
      Returns:
      the description component, or null if none
      Since:
      0.1.0

    • getMinLevel

      int getMinLevel()
      Gets the minimum valid level for this enchantment.
      Returns:
      the minimum level (always >= 1)
      Since:
      0.1.0

    • getMaxLevel

      int getMaxLevel()
      Gets the maximum valid level for this enchantment.
      Returns:
      the maximum level (>= minLevel)
      Since:
      0.1.0

    • getScaling

      @NotNull @NotNull LevelScaling getScaling()
      Gets the scaling formula for calculating effect values.
      Returns:
      the level scaling instance (never null)
      Since:
      0.1.0

    • getApplicableMaterials

      @NotNull @NotNull Set<org.bukkit.Material> getApplicableMaterials()
      Gets all materials this enchantment can be applied to.
      Returns:
      set of applicable materials (never null)
      Since:
      0.1.0

    • isApplicableTo

      boolean isApplicableTo(@NotNull @NotNull org.bukkit.Material material)
      Checks if this enchantment can be applied to a specific material.
      Parameters:
      material - the material to check (must not be null)
      Returns:
      true if applicable
      Since:
      0.1.0

    • isApplicableTo

      boolean isApplicableTo(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Checks if this enchantment can be applied to an item.
      Parameters:
      item - the item to check (must not be null)
      Returns:
      true if applicable to the item's material
      Since:
      0.1.0

    • isCurse

      boolean isCurse()
      Checks if this is a curse enchantment.
      Returns:
      true if the enchantment is a curse
      Since:
      0.1.0

    • isTradeable

      boolean isTradeable()
      Checks if this enchantment can be traded with villagers.
      Returns:
      true if tradeable
      Since:
      0.1.0

    • isDiscoverable

      boolean isDiscoverable()
      Checks if this enchantment can be found in loot.
      Returns:
      true if discoverable
      Since:
      0.1.0

    • getRarity

      @NotNull @NotNull EnchantmentDefinition.Rarity getRarity()
      Gets the rarity tier of this enchantment.
      Returns:
      the rarity (never null)
      Since:
      0.1.0

    • getEffectHandler

      @Nullable @Nullable EnchantmentEffectHandler getEffectHandler()
      Gets the effect handler for this enchantment, if any.
      Returns:
      the effect handler, or null if this enchantment has no effects
      Since:
      0.1.0

    • calculateScaledValue

      double calculateScaledValue(int level)
      Calculates the scaled value for a given level.

      Uses the configured LevelScaling formula.

      Parameters:
      level - the enchantment level to calculate for
      Returns:
      the scaled value
      Throws:
      IllegalArgumentException - if level is invalid
      Since:
      0.1.0

    • conflictsWith

      boolean conflictsWith(@NotNull @NotNull EnchantmentDefinition other)
      Checks if this enchantment conflicts with another.
      Parameters:
      other - the other enchantment to check (must not be null)
      Returns:
      true if the enchantments cannot coexist on the same item
      Since:
      0.1.0

    • getConflictingEnchantments

      @NotNull @NotNull Set<org.bukkit.NamespacedKey> getConflictingEnchantments()
      Gets all enchantment keys that conflict with this one.
      Returns:
      set of conflicting enchantment keys (never null)
      Since:
      0.1.0

    • builder

      @NotNull static @NotNull EnchantmentDefinition.Builder builder()
      Creates a new builder for constructing enchantment definitions.

      The returned builder provides comprehensive validation methods including EnchantmentDefinition.Builder.validate(), EnchantmentDefinition.Builder.isValid(), and EnchantmentDefinition.Builder.getValidationErrors() for pre-build validation.

      Returns:
      a new builder instance
      Since:
      0.2.0