Package io.artificial.enchantments.internal.scaling

Class ScalingUtils

java.lang.Object
io.artificial.enchantments.internal.scaling.ScalingUtils
public final class ScalingUtils extends Object
Internal scaling utilities for the effect dispatch spine.

This class provides factory methods and wrappers for scaling formulas used internally by the enchantment effect system. All scaling functions are pure (no side effects, thread-safe).

Formula Reference:
  • Linear: result = base + (level - 1) * increment
  • Exponential: result = base * multiplier^(level - 1)
  • Diminishing: result = max * (level / (level + scalingFactor))
  • Constant: result = value (independent of level)
See Also:

  • Method Details

    • linear

      @NotNull public static @NotNull LevelScaling linear(double base, double increment)
      Creates a linear scaling formula.

      Formula: base + (level - 1) * increment

      Example: Sharpness-style damage increase 

       base = 1.0, increment = 0.5
 Level 1: 1.0 + (0) * 0.5 = 1.0
 Level 5: 1.0 + (4) * 0.5 = 3.0
 Level 10: 1.0 + (9) * 0.5 = 5.5
      Parameters:
      base - the base value at level 1
      increment - the amount added per level above 1
      Returns:
      a LevelScaling instance using linear progression

    • exponential

      @NotNull public static @NotNull LevelScaling exponential(double base, double multiplier)
      Creates an exponential scaling formula.

      Formula: base * multiplier^(level - 1)

      Warning: Exponential scaling grows rapidly. Use with care at high levels to avoid overpowered values.

      Example: 

       base = 2.0, multiplier = 1.5
 Level 1: 2.0 * 1.5^0 = 2.0
 Level 5: 2.0 * 1.5^4 = 10.125
 Level 10: 2.0 * 1.5^9 = 76.27
      Parameters:
      base - the base value at level 1
      multiplier - the factor multiplied per level (must be > 0)
      Returns:
      a LevelScaling instance using exponential progression
      Throws:
      IllegalArgumentException - if multiplier is not positive

    • diminishing

      @NotNull public static @NotNull LevelScaling diminishing(double maxValue, double scalingFactor)
      Creates a diminishing returns scaling formula.

      Formula: maxValue * (level / (level + scalingFactor))

      This formula approaches maxValue asymptotically as level increases, preventing values from becoming overpowered at high enchantment levels.

      Example: 

       maxValue = 10.0, scalingFactor = 5.0
 Level 1: 10.0 * (1 / 6) = 1.67
 Level 5: 10.0 * (5 / 10) = 5.0
 Level 10: 10.0 * (10 / 15) = 6.67
 Level 100: 10.0 * (100 / 105) = 9.52
      Parameters:
      maxValue - the asymptotic maximum value approached at high levels
      scalingFactor - controls how quickly the curve approaches maxValue (higher = slower)
      Returns:
      a LevelScaling instance using diminishing returns
      Throws:
      IllegalArgumentException - if maxValue or scalingFactor is not positive

    • constant

      @NotNull public static @NotNull LevelScaling constant(double value)
      Creates a constant scaling formula (value independent of level).

      Formula: value

      Parameters:
      value - the constant value returned for all levels
      Returns:
      a LevelScaling instance returning a fixed value

    • custom

      @NotNull public static @NotNull LevelScaling custom(@NotNull @NotNull Function<Integer,Double> formula)
      Creates a custom scaling formula from a user-defined function.

      This allows consumers to define arbitrary scaling formulas for specialized use cases not covered by the built-in formulas.

      The function must be pure (no side effects) and thread-safe.

      Example: 

       // Quadratic scaling: value = level^2
 LevelScaling quadratic = ScalingUtils.custom(level -> (double) level * level);
 
 // Logarithmic scaling: value = log(level + 1)
 LevelScaling logScale = ScalingUtils.custom(level -> Math.log(level + 1));
      Parameters:
      formula - the custom formula as a Function<Integer, Double>
      Returns:
      a LevelScaling instance using the custom formula
      Throws:
      IllegalArgumentException - if formula is null

    • decaying

      @NotNull public static @NotNull LevelScaling decaying(double maxValue, double decayFactor)
      Creates an alternative diminishing returns formula using exponential decay.

      Formula: maxValue * (1 - decayFactor^level)

      This variant approaches maxValue from below using exponential decay, providing a different curve shape than the standard diminishing formula.

      Example: 

       maxValue = 10.0, decayFactor = 0.9
 Level 1: 10.0 * (1 - 0.9) = 1.0
 Level 5: 10.0 * (1 - 0.9^5) = 4.1
 Level 10: 10.0 * (1 - 0.9^10) = 6.51
 Level 100: 10.0 * (1 - 0.9^100) ≈ 10.0
      Parameters:
      maxValue - the maximum value approached at infinite level
      decayFactor - the decay rate per level (0 < decayFactor < 1)
      Returns:
      a LevelScaling instance using exponential decay
      Throws:
      IllegalArgumentException - if maxValue is not positive or decayFactor not in (0, 1)

    • validateLevel

      public static void validateLevel(int level)
      Validates that a level is valid (>= 1).
      Parameters:
      level - the level to validate
      Throws:
      IllegalArgumentException - if level < 1

    • calculateRounded

      public static int calculateRounded(@NotNull @NotNull LevelScaling scaling, int level)
      Calculates a value and rounds to the nearest integer. Useful for discrete values like damage amounts.
      Parameters:
      scaling - the scaling formula
      level - the enchantment level
      Returns:
      the rounded value

    • calculateFloored

      public static int calculateFloored(@NotNull @NotNull LevelScaling scaling, int level)
      Calculates a value and floors to the nearest integer. Useful for ensuring minimum thresholds.
      Parameters:
      scaling - the scaling formula
      level - the enchantment level
      Returns:
      the floored value

    • calculateCeiled

      public static int calculateCeiled(@NotNull @NotNull LevelScaling scaling, int level)
      Calculates a value and ceils to the nearest integer. Useful for ensuring at least a certain amount.
      Parameters:
      scaling - the scaling formula
      level - the enchantment level
      Returns:
      the ceiled value