Package io.artificial.enchantments.api

Interface EnchantmentDefinition.Builder

All Known Implementing Classes:
EnchantmentDefinitionBuilder
Enclosing interface:
EnchantmentDefinition
public static interface EnchantmentDefinition.Builder
Builder for creating enchantment definitions.

All properties must be set before calling build(), except for optional properties which have sensible defaults.

Required Properties:

Since:
0.1.0

  • Method Details

    • key

      @NotNull @NotNull EnchantmentDefinition.Builder key(@NotNull @NotNull org.bukkit.NamespacedKey key)
      Sets the unique namespaced key for this enchantment.
      Parameters:
      key - the enchantment key (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • displayName

      @NotNull @NotNull EnchantmentDefinition.Builder displayName(@NotNull @NotNull net.kyori.adventure.text.Component name)
      Sets the display name shown to players.
      Parameters:
      name - the display name (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • description

      @NotNull @NotNull EnchantmentDefinition.Builder description(@Nullable @Nullable net.kyori.adventure.text.Component description)
      Sets the optional description for lore display.
      Parameters:
      description - the description, or null for none
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • minLevel

      @NotNull @NotNull EnchantmentDefinition.Builder minLevel(int minLevel)
      Sets the minimum valid level.
      Parameters:
      minLevel - the minimum level (must be >= 1)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • maxLevel

      @NotNull @NotNull EnchantmentDefinition.Builder maxLevel(int maxLevel)
      Sets the maximum valid level.
      Parameters:
      maxLevel - the maximum level (must be >= minLevel)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • scaling

      @NotNull @NotNull EnchantmentDefinition.Builder scaling(@NotNull @NotNull LevelScaling scaling)
      Sets the scaling formula using a LevelScaling instance.
      Parameters:
      scaling - the scaling formula (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • scaling

      @NotNull @NotNull EnchantmentDefinition.Builder scaling(@NotNull @NotNull Function<Integer,Double> formula)
      Sets a custom scaling formula using a lambda.
      Parameters:
      formula - the formula function (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • scaling

      @NotNull default @NotNull EnchantmentDefinition.Builder scaling(@NotNull @NotNull String algorithmName, double... params)
      Sets the scaling formula using a registered algorithm by name.

      Uses the ScalingAlgorithmRegistry to look up the algorithm and create a configured LevelScaling instance.

      Example: 

      
 .scaling("LINEAR", 1.0, 0.5)        // base=1.0, increment=0.5
 .scaling("EXPONENTIAL", 1.0, 1.2)   // base=1.0, multiplier=1.2
 .scaling("CONSTANT", 5.0)           // value=5.0 at all levels
      Parameters:
      algorithmName - the algorithm name (must not be null, case-insensitive)
      params - the algorithm-specific parameters
      Returns:
      this builder for chaining
      Throws:
      IllegalArgumentException - if algorithm not found or parameters invalid
      Since:
      0.2.0
      See Also:

    • applicable

      @NotNull @NotNull EnchantmentDefinition.Builder applicable(@NotNull @NotNull org.bukkit.Material... materials)
      Sets applicable materials from a varargs list.
      Parameters:
      materials - the materials (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • applicable

      @NotNull @NotNull EnchantmentDefinition.Builder applicable(@NotNull @NotNull Set<org.bukkit.Material> materials)
      Sets applicable materials from a set.
      Parameters:
      materials - the material set (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • curse

      @NotNull @NotNull EnchantmentDefinition.Builder curse(boolean curse)
      Sets whether this is a curse enchantment.
      Parameters:
      curse - true for curse enchantments
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • curse

      @NotNull @NotNull EnchantmentDefinition.Builder curse()
      Marks this enchantment as a curse (convenience method).
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • tradeable

      @NotNull @NotNull EnchantmentDefinition.Builder tradeable(boolean tradeable)
      Sets whether this enchantment is tradeable with villagers.
      Parameters:
      tradeable - true if tradeable
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • discoverable

      @NotNull @NotNull EnchantmentDefinition.Builder discoverable(boolean discoverable)
      Sets whether this enchantment appears in loot tables.
      Parameters:
      discoverable - true if discoverable
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • rarity

      @NotNull @NotNull EnchantmentDefinition.Builder rarity(@NotNull @NotNull EnchantmentDefinition.Rarity rarity)
      Sets the rarity tier.
      Parameters:
      rarity - the rarity (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • effectHandler

      @NotNull @NotNull EnchantmentDefinition.Builder effectHandler(@Nullable @Nullable EnchantmentEffectHandler handler)
      Sets the effect handler for this enchantment.
      Parameters:
      handler - the effect handler, or null for no effects
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • conflictsWith

      @NotNull @NotNull EnchantmentDefinition.Builder conflictsWith(@NotNull @NotNull org.bukkit.NamespacedKey key)
      Adds a conflicting enchantment key.
      Parameters:
      key - the conflicting enchantment key (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • conflictsWith

      @NotNull @NotNull EnchantmentDefinition.Builder conflictsWith(@NotNull @NotNull org.bukkit.NamespacedKey... keys)
      Adds multiple conflicting enchantment keys.
      Parameters:
      keys - the conflicting keys (must not be null)
      Returns:
      this builder for chaining
      Since:
      0.1.0

    • build

      @NotNull @NotNull EnchantmentDefinition build()
      Builds and returns the enchantment definition.
      Returns:
      the completed definition
      Throws:
      IllegalStateException - if required properties are not set
      Since:
      0.1.0

    • validate

      default void validate()
      Validates the current builder state without building.

      This method performs the same validation as build() but provides detailed error information without actually creating the enchantment definition. Use this for pre-build validation when you need to check configuration before attempting to build.

      Default Behavior: The default implementation calls getValidationErrors() and throws an exception if any non-warning errors exist. Override in implementations for custom validation.

      Throws:
      IllegalStateException - if validation fails, with detailed error message
      Since:
      0.2.0

    • isValid

      default boolean isValid()
      Checks if the current builder state is valid.

      This is a non-throwing alternative to validate(). Returns true only if all validation rules pass and the enchantment can be built successfully.

      Default Behavior: Returns true if getValidationErrors() returns no non-warning errors.

      Returns:
      true if valid, false if validation errors exist
      Since:
      0.2.0

    • getValidationErrors

      @NotNull default @NotNull List<String> getValidationErrors()
      Gets all validation errors for the current builder state.

      Returns a list of detailed error messages describing what validation rules are currently violated. An empty list indicates the builder is in a valid state.

      Validation checks include:

      • Required fields: key, displayName, scaling, applicable materials
      • Level bounds: minLevel >= 1, maxLevel >= minLevel
      • Material set: non-empty set of applicable materials
      • Conflicts: no self-conflicts (enchantment cannot conflict with itself)
      • Cross-property: warnings for curse + tradeable combinations

      Default Behavior: Returns an empty list. Override in implementations to provide actual validation logic.

      Returns:
      unmodifiable list of validation error and warning messages (empty if valid)
      Since:
      0.2.0