Package io.artificial.enchantments.api

Interface EnchantmentEffectHandler

public interface EnchantmentEffectHandler
Handler for enchantment effects triggered by game events.

Implement this interface to define custom behavior for your enchantments. Each method corresponds to a specific game event type and receives a context object with relevant data.

Typed Callbacks vs Event Bus:
You can handle effects through either typed callbacks (this interface) or the EnchantmentEventBus. Both paths fire through the same dispatch spine, so choose based on your preference:

  • Typed callbacks: Type-safe, compile-time checked, easier for simple effects
  • Event bus: Decoupled, allows multiple listeners, better for complex interactions

Cancellation:
Contexts that support cancellation implement Cancellable. Call EffectContext.tryCancel() to cancel the underlying Bukkit event. Cancellation propagates through both typed callbacks and event bus listeners.

Threading:
Handlers execute inline with the library's dispatch flow. Keep them light, avoid blocking work, and reschedule anything expensive through your own scheduler usage.

Example Implementation: 


 public class LifeStealHandler implements EnchantmentEffectHandler {
     @Override
     public void onEntityDamageByEntity(@NotNull CombatContext context) {
         if (!context.isAttack()) return;
         
         double scaledValue = context.getScaledValue();
         Player attacker = (Player) context.getAttacker();
         LivingEntity victim = context.getVictim();
         
         // Heal attacker based on scaled value
         double healAmount = context.getFinalDamage() * scaledValue * 0.1;
         attacker.heal(healAmount);
     }
 }
Since:
0.1.0
See Also:

  • Method Details

    • onEntityDamageByEntity

      default void onEntityDamageByEntity(@NotNull @NotNull CombatContext context)
      Called when an entity damages another entity (attack context).

      Fires for melee attacks, projectile hits, and other damage sources where an attacker can be identified.

      Parameters:
      context - the combat context with attacker, victim, and damage data
      Since:
      0.1.0

    • onEntityDamage

      default void onEntityDamage(@NotNull @NotNull CombatContext context)
      Called when an entity takes damage from any source.

      Fires for all damage events, including environmental damage where there may be no attacker. Check CombatContext.getAttacker() to determine if there is an attacking entity.

      Parameters:
      context - the combat context with victim and damage data
      Since:
      0.1.0

    • onShieldBlock

      default void onShieldBlock(@NotNull @NotNull CombatContext context)
      Called when a player successfully blocks with a shield.
      Parameters:
      context - the combat context with defender and damage data
      Since:
      0.1.0

    • onBlockBreak

      default void onBlockBreak(@NotNull @NotNull ToolContext context)
      Called after a block is broken.

      The drops list in the context can be modified to change what items are dropped from the broken block.

      Parameters:
      context - the tool context with player, tool, and block data
      Since:
      0.1.0

    • onBlockBreakPre

      default void onBlockBreakPre(@NotNull @NotNull ToolContext context)
      Called before a block break is confirmed (pre-event).

      Use this to cancel unbreakable blocks or apply pre-break effects. Cancelling here prevents the block from being broken.

      Parameters:
      context - the tool context with player, tool, and block data
      Since:
      0.1.0

    • onBlockPlace

      default void onBlockPlace(@NotNull @NotNull ToolContext context)
      Called when a player places a block.
      Parameters:
      context - the tool context with player, tool, and block data
      Since:
      0.1.0

    • onBlockInteract

      default void onBlockInteract(@NotNull @NotNull InteractionContext context)
      Called when a player interacts with a block (right-click, left-click).
      Parameters:
      context - the interaction context with player and block data
      Since:
      0.1.0

    • onEntityInteract

      default void onEntityInteract(@NotNull @NotNull InteractionContext context)
      Called when a player interacts with an entity (right-click).
      Parameters:
      context - the interaction context with player and entity data
      Since:
      0.1.0

    • onProjectileLaunch

      default void onProjectileLaunch(@NotNull @NotNull ProjectileContext context)
      Called when a projectile is launched (arrow, trident, etc.).

      Modify velocity, gravity, or pierce level through the context.

      Parameters:
      context - the projectile context with projectile and shooter data
      Since:
      0.1.0

    • onProjectileHit

      default void onProjectileHit(@NotNull @NotNull ProjectileContext context)
      Called when a projectile hits a block or entity.
      Parameters:
      context - the projectile context with hit data
      Since:
      0.1.0

    • onFishingAction

      default void onFishingAction(@NotNull @NotNull FishingContext context)
      Called when fishing rod actions occur (cast, reel, bite).

      Modify wait time and lure speed through the context.

      Parameters:
      context - the fishing context with player and hook data
      Since:
      0.1.0

    • onHeldTick

      default void onHeldTick(@NotNull @NotNull TickContext context)
      Called periodically while an item is held in the main or off hand.
      Parameters:
      context - the tick context with player and item data
      Since:
      0.1.0

    • onArmorTick

      default void onArmorTick(@NotNull @NotNull TickContext context)
      Called periodically while an armor item is equipped.
      Parameters:
      context - the tick context with player and item data
      Since:
      0.1.0

    • onItemUsed

      default void onItemUsed(@NotNull @NotNull ItemContext context)
      Called when an item is used (interacted with).
      Parameters:
      context - the item context with usage data
      Since:
      0.1.0

    • onDurabilityDamage

      default void onDurabilityDamage(@NotNull @NotNull ItemContext context)
      Called when an item takes durability damage.

      Modify the damage amount through the context.

      Parameters:
      context - the item context with durability data
      Since:
      0.1.0

    • onItemConsume

      default void onItemConsume(@NotNull @NotNull ConsumableContext context)
      Called when a player consumes an item (food, potion).

      Modify food level, saturation, and health restoration through the context.

      Parameters:
      context - the consumable context with consumption data
      Since:
      0.1.0

    • onBowShoot

      default void onBowShoot(@NotNull @NotNull WeaponContext context)
      Called when a bow or crossbow is fired.

      Modify force and critical hit status through the context.

      Parameters:
      context - the weapon context with bow and projectile data
      Since:
      0.1.0

    • onTridentThrow

      default void onTridentThrow(@NotNull @NotNull WeaponContext context)
      Called when a trident is thrown.

      Modify force and pierce level through the context.

      Parameters:
      context - the weapon context with trident and projectile data
      Since:
      0.1.0

    • onItemDrop

      default void onItemDrop(@NotNull @NotNull ItemContext context)
      Called when an item is dropped.
      Parameters:
      context - the item context with drop data
      Since:
      0.1.0

    • onItemPickup

      default void onItemPickup(@NotNull @NotNull ItemContext context)
      Called when an item is picked up.
      Parameters:
      context - the item context with pickup data
      Since:
      0.1.0

    • tryCancel

      default boolean tryCancel(@NotNull @NotNull Object context)
      Attempts to cancel the given context if it supports cancellation.

      Convenience method for handler implementations.

      Parameters:
      context - the context object to cancel
      Returns:
      true if cancellation was successful, false if not cancellable
      Since:
      0.1.0

    • isCancelled

      default boolean isCancelled(@NotNull @NotNull Object context)
      Checks if the given context has been cancelled.

      Convenience method for handler implementations.

      Parameters:
      context - the context object to check
      Returns:
      true if the context is cancellable and cancelled
      Since:
      0.1.0