Package io.artificial.enchantments.api.loot

Interface LootContext

public interface LootContext
Context for loot modification during block break events.

This context provides all the data needed to modify loot drops when a player breaks a block with an enchanted tool. The drops list is modifiable, allowing enchantments to add, remove, or change items.

Explicit Ownership:
Loot modification only occurs for enchantments that have explicitly registered a LootModifier via LootModifierRegistry. Non-targeted loot sources remain untouched unless explicitly opted in.

Usage Example: 


 LootModifier myModifier = context -> {
     // Get vanilla drops
     List<ItemStack> drops = context.getDrops();

     // Add bonus item
     context.addDrop(new ItemStack(Material.DIAMOND));

     // Double existing drops based on level
     int multiplier = 1 + context.getLevel();
     for (ItemStack drop : drops) {
         drop.setAmount(drop.getAmount() * multiplier);
     }
 };

Thread Safety:
Context instances are not thread-safe. Modifications should be done synchronously on the main thread during the block break event.

Since:
0.4.0
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addDrop(@NotNull org.bukkit.inventory.ItemStack drop)
    Adds a drop to the list.
    void
    clearDrops()
    Clears all drops from the list.
    @NotNull org.bukkit.block.Block
    getBlock()
    Gets the block being broken.
    @NotNull List<org.bukkit.inventory.ItemStack>
    getDrops()
    Gets the modifiable list of drops.
    int
    getEnchantmentLevel(@NotNull String enchantmentKey)
    Gets the level of a specific enchantment on the tool.
    int
    getExpToDrop()
    Gets the experience points to drop.
    int
    getLevel()
    Gets the enchantment level.
    @NotNull org.bukkit.Location
    getLocation()
    Gets the location where drops will spawn.
    @NotNull org.bukkit.entity.Player
    getPlayer()
    Gets the player breaking the block.
    double
    getScaledValue()
    Gets the scaled value calculated from the enchantment level.
    @NotNull org.bukkit.inventory.ItemStack
    getTool()
    Gets the tool item that triggered this loot modification.
    boolean
    hasEnchantment(@NotNull String enchantmentKey)
    Checks if the tool has a specific enchantment.
    boolean
    removeDrop(@NotNull org.bukkit.inventory.ItemStack drop)
    Removes a drop from the list.
    void
    setDrops(@Nullable List<org.bukkit.inventory.ItemStack> drops)
    Sets the entire drops list, replacing vanilla drops.
    void
    setExpToDrop(int exp)
    Sets the experience points to drop.

  • Method Details

    • getTool

      @NotNull @NotNull org.bukkit.inventory.ItemStack getTool()
      Gets the tool item that triggered this loot modification.

      This is the item the player is holding when breaking the block, containing the enchantment that registered this modifier.

      Returns:
      the tool item stack
      Since:
      0.4.0

    • getBlock

      @NotNull @NotNull org.bukkit.block.Block getBlock()
      Gets the block being broken.
      Returns:
      the block
      Since:
      0.4.0

    • getPlayer

      @NotNull @NotNull org.bukkit.entity.Player getPlayer()
      Gets the player breaking the block.
      Returns:
      the player
      Since:
      0.4.0

    • getLocation

      @NotNull @NotNull org.bukkit.Location getLocation()
      Gets the location where drops will spawn.

      Typically the block's location, but may be adjusted by other enchantments or plugins.

      Returns:
      the drop location
      Since:
      0.4.0

    • getDrops

      @NotNull @NotNull List<org.bukkit.inventory.ItemStack> getDrops()
      Gets the modifiable list of drops.

      This list contains the vanilla drops that would normally spawn. It is directly modifiable - changes are reflected in the actual drops that will spawn.

      Modification Options:

      Returns:
      the modifiable drops list
      Since:
      0.4.0

    • setDrops

      void setDrops(@Nullable @Nullable List<org.bukkit.inventory.ItemStack> drops)
      Sets the entire drops list, replacing vanilla drops.

      This replaces all drops. Use with care as it removes vanilla drops. For adding bonus drops, prefer addDrop(ItemStack).

      Parameters:
      drops - the new drops list, or null to clear all drops
      Since:
      0.4.0

    • addDrop

      void addDrop(@NotNull @NotNull org.bukkit.inventory.ItemStack drop)
      Adds a drop to the list.

      This is the preferred method for adding bonus items. The item is cloned before being added to prevent external modifications.

      Parameters:
      drop - the item to add
      Throws:
      IllegalArgumentException - if drop is null
      Since:
      0.4.0

    • removeDrop

      boolean removeDrop(@NotNull @NotNull org.bukkit.inventory.ItemStack drop)
      Removes a drop from the list.

      Removes the first matching item stack. The match is based on material and amount comparison.

      Parameters:
      drop - the item to remove
      Returns:
      true if an item was removed, false otherwise
      Since:
      0.4.0

    • clearDrops

      void clearDrops()
      Clears all drops from the list.

      This removes vanilla drops. Use with caution.

      Since:
      0.4.0

    • getLevel

      int getLevel()
      Gets the enchantment level.

      The level of the enchantment that registered this modifier. Use this to scale modifications appropriately.

      Returns:
      the enchantment level (at least 1)
      Since:
      0.4.0

    • getScaledValue

      double getScaledValue()
      Gets the scaled value calculated from the enchantment level.

      This is the pre-calculated value from the enchantment's LevelScaling. Use this for consistent scaling across enchantments.

      Returns:
      the scaled value
      Since:
      0.4.0

    • getExpToDrop

      int getExpToDrop()
      Gets the experience points to drop.
      Returns:
      the XP amount
      Since:
      0.4.0

    • setExpToDrop

      void setExpToDrop(int exp)
      Sets the experience points to drop.

      Use this to adjust XP drops. Set to 0 to prevent XP drops.

      Parameters:
      exp - the XP amount (clamped to 0+)
      Since:
      0.4.0

    • hasEnchantment

      boolean hasEnchantment(@NotNull @NotNull String enchantmentKey)
      Checks if the tool has a specific enchantment.

      Convenience method for checking if the tool has other enchantments that might affect loot drops.

      Parameters:
      enchantmentKey - the enchantment key to check
      Returns:
      true if the tool has this enchantment
      Since:
      0.4.0

    • getEnchantmentLevel

      int getEnchantmentLevel(@NotNull @NotNull String enchantmentKey)
      Gets the level of a specific enchantment on the tool.
      Parameters:
      enchantmentKey - the enchantment key to check
      Returns:
      the enchantment level, or 0 if not present
      Since:
      0.4.0