Package io.artificial.enchantments.api.book

Interface EnchantedBook.Builder

All Known Implementing Classes:
EnchantedBookBuilderImpl
Enclosing interface:
EnchantedBook
public static interface EnchantedBook.Builder
Builder for creating enchanted books.

This builder follows a fluent API pattern for convenient book creation. Multiple enchantments can be added, and books are validated on build.

Since:
0.2.0

  • Method Details

    • withEnchantment

      @NotNull @NotNull EnchantedBook.Builder withEnchantment(@NotNull @NotNull EnchantmentDefinition enchantment, int level)
      Adds an enchantment to the book at the specified level.

      The level must be within the enchantment's defined min/max bounds. If the enchantment is already present, the higher level is kept (matching vanilla behavior for combining books).

      Parameters:
      enchantment - the enchantment to add (must not be null)
      level - the level to apply (must be within bounds)
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if enchantment is null or level is invalid
      Since:
      0.2.0

    • withEnchantment

      @NotNull @NotNull EnchantedBook.Builder withEnchantment(@NotNull @NotNull org.bukkit.NamespacedKey key, int level)
      Adds an enchantment by its registry key.

      This is a convenience method that looks up the definition before adding.

      Parameters:
      key - the enchantment's namespaced key (must not be null)
      level - the level to apply
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if enchantment not found or level invalid
      Since:
      0.2.0

    • displayName

      @NotNull @NotNull EnchantedBook.Builder displayName(@Nullable @Nullable String displayName)
      Sets a custom display name for the book.

      If not set, the book will use the default name based on its enchantments (e.g., "Enchanted Book" or "Book of Life Steal").

      Parameters:
      displayName - the custom display name, or null for default
      Returns:
      this builder for chaining
      Since:
      0.2.0

    • lore

      @NotNull @NotNull EnchantedBook.Builder lore(@NotNull @NotNull String... lore)
      Adds lore lines to the book.

      These lines appear below the enchantment descriptions in the book's tooltip.

      Parameters:
      lore - the lore lines to add (must not be null)
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if lore is null
      Since:
      0.2.0

    • treasure

      @NotNull @NotNull EnchantedBook.Builder treasure(boolean treasure)
      Sets whether the book is a "treasure" book (from chests/loot).

      This affects anvil cost calculation - treasure books cost more.

      Parameters:
      treasure - true if this is a treasure book
      Returns:
      this builder for chaining
      Since:
      0.2.0

    • build

      @NotNull @NotNull org.bukkit.inventory.ItemStack build()
      Builds and returns the enchanted book.

      The book is created as an ENCHANTED_BOOK item with all specified enchantments stored in native ItemMeta. The returned item is a new ItemStack instance.

      Returns:
      the created enchanted book
      Throws:
      IllegalStateException - if no enchantments were added
      Since:
      0.2.0

    • reset

      @NotNull @NotNull EnchantedBook.Builder reset()
      Resets the builder to its initial state.

      This clears all enchantments and settings, allowing the builder to be reused for creating another book.

      Returns:
      this builder for chaining
      Since:
      0.2.0