Package io.artificial.enchantments.api.book

Interface EnchantedBook

All Known Implementing Classes:
EnchantedBookImpl
public interface EnchantedBook
API for creating and managing enchanted books with custom enchantments.

This interface provides methods for creating enchanted books, querying their enchantments, and extracting enchantments for application to other items.

Books use the same native-first storage model as items, storing enchantments directly in the book's ItemMeta. This ensures compatibility with vanilla anvil mechanics and client visibility without packet manipulation.

Example Usage: 


 // Create a book with a single enchantment
 ItemStack book = EnchantedBook.builder(api)
     .withEnchantment(lifeSteal, 3)
     .build();

 // Create a book with multiple enchantments
 ItemStack multiBook = EnchantedBook.builder(api)
     .withEnchantment(sharpness, 5)
     .withEnchantment(fireAspect, 2)
     .withEnchantment(looting, 3)
     .build();

 // Query a book's enchantments
 Map<EnchantmentDefinition, Integer> enchants = EnchantedBook.getEnchantments(book);
Since:
0.2.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    EnchantedBook.Builder
    Builder for creating enchanted books.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull EnchantedBook.Builder
    builder()
    Gets a builder for creating enchanted books.
    @NotNull Map<org.bukkit.NamespacedKey,Integer>
    getAllEnchantmentKeys(@NotNull org.bukkit.inventory.ItemStack book)
    Gets all enchantment keys on a book as NamespacedKey to level mapping.
    int
    getEnchantmentLevel(@NotNull org.bukkit.inventory.ItemStack book, @NotNull EnchantmentDefinition enchantment)
    Gets the level of a specific artificial enchantment on a book.
    int
    getEnchantmentLevel(@NotNull org.bukkit.inventory.ItemStack book, @NotNull org.bukkit.NamespacedKey key)
    Gets the level of an artificial enchantment by its key.
    @NotNull Map<EnchantmentDefinition,Integer>
    getEnchantments(@NotNull org.bukkit.inventory.ItemStack book)
    Gets all artificial enchantments stored on a book.
    boolean
    hasCustomEnchantments(@NotNull org.bukkit.inventory.ItemStack book)
    Checks if an enchanted book contains custom (artificial) enchantments.
    boolean
    hasEnchantment(@NotNull org.bukkit.inventory.ItemStack book, @NotNull EnchantmentDefinition enchantment)
    Checks if a specific artificial enchantment exists on a book.
    boolean
    hasEnchantment(@NotNull org.bukkit.inventory.ItemStack book, @NotNull org.bukkit.NamespacedKey key)
    Checks if an artificial enchantment exists by its key.
    boolean
    isEnchantedBook(@NotNull org.bukkit.inventory.ItemStack item)
    Checks if an item is an enchanted book (vanilla or custom).

  • Method Details

    • isEnchantedBook

      boolean isEnchantedBook(@NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Checks if an item is an enchanted book (vanilla or custom).

      This returns true for both vanilla ENCHANTED_BOOK items and books created through this API.

      Parameters:
      item - the item to check (must not be null)
      Returns:
      true if the item is an enchanted book
      Throws:
      IllegalArgumentException - if item is null
      Since:
      0.2.0

    • hasCustomEnchantments

      boolean hasCustomEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack book)
      Checks if an enchanted book contains custom (artificial) enchantments.

      This distinguishes between books with only vanilla enchantments and books that have enchantments registered through this API.

      Parameters:
      book - the book to check (must not be null)
      Returns:
      true if the book has at least one artificial enchantment
      Throws:
      IllegalArgumentException - if book is null or not a book
      Since:
      0.2.0

    • getEnchantments

      @NotNull @NotNull Map<EnchantmentDefinition,Integer> getEnchantments(@NotNull @NotNull org.bukkit.inventory.ItemStack book)
      Gets all artificial enchantments stored on a book.

      Returns a map of enchantment definitions to their levels. Only enchantments registered through this API are included.

      Parameters:
      book - the book to query (must not be null)
      Returns:
      unmodifiable map of enchantments to levels (never null, may be empty)
      Throws:
      IllegalArgumentException - if book is null or not a book
      Since:
      0.2.0

    • getEnchantmentLevel

      int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack book, @NotNull @NotNull EnchantmentDefinition enchantment)
      Gets the level of a specific artificial enchantment on a book.
      Parameters:
      book - the book to query (must not be null)
      enchantment - the enchantment to look for (must not be null)
      Returns:
      the enchantment level, or 0 if not present
      Throws:
      IllegalArgumentException - if book or enchantment is null
      Since:
      0.2.0

    • getEnchantmentLevel

      int getEnchantmentLevel(@NotNull @NotNull org.bukkit.inventory.ItemStack book, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Gets the level of an artificial enchantment by its key.
      Parameters:
      book - the book to query (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      the enchantment level, or 0 if not present
      Throws:
      IllegalArgumentException - if book or key is null
      Since:
      0.2.0

    • getAllEnchantmentKeys

      @NotNull @NotNull Map<org.bukkit.NamespacedKey,Integer> getAllEnchantmentKeys(@NotNull @NotNull org.bukkit.inventory.ItemStack book)
      Gets all enchantment keys on a book as NamespacedKey to level mapping.

      This includes both vanilla and artificial enchantments.

      Parameters:
      book - the book to query (must not be null)
      Returns:
      unmodifiable map of all enchantment keys to levels
      Throws:
      IllegalArgumentException - if book is null or not a book
      Since:
      0.2.0

    • hasEnchantment

      boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack book, @NotNull @NotNull EnchantmentDefinition enchantment)
      Checks if a specific artificial enchantment exists on a book.
      Parameters:
      book - the book to check (must not be null)
      enchantment - the enchantment to look for (must not be null)
      Returns:
      true if the book has the enchantment at any level
      Throws:
      IllegalArgumentException - if book or enchantment is null
      Since:
      0.2.0

    • hasEnchantment

      boolean hasEnchantment(@NotNull @NotNull org.bukkit.inventory.ItemStack book, @NotNull @NotNull org.bukkit.NamespacedKey key)
      Checks if an artificial enchantment exists by its key.
      Parameters:
      book - the book to check (must not be null)
      key - the enchantment's namespaced key (must not be null)
      Returns:
      true if the book has the enchantment at any level
      Throws:
      IllegalArgumentException - if book or key is null
      Since:
      0.2.0

    • builder

      @NotNull @NotNull EnchantedBook.Builder builder()
      Gets a builder for creating enchanted books.

      The returned builder can be used to construct books with one or more enchantments. Books are created as ENCHANTED_BOOK items with enchantments stored in native ItemMeta.

      Returns:
      a new book builder instance
      Since:
      0.2.0