Class Item

java.lang.Object
com.github.darksoulq.abyssallib.world.item.Item
All Implemented Interfaces:
Cloneable
public class Item extends Object implements Cloneable
Represents a custom item within the AbyssalLib framework. This class serves as the primary template for creating new items, handling their data components, tooltips, and interaction logic.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Item.Tooltip
    Internal class used to configure the visual representation of an item's tooltip.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    Item.Tooltip
    tooltip
    The helper object used to build and manage procedural tooltips.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Item(net.kyori.adventure.key.Key id)
    Constructs a new custom item definition.
    Item(net.kyori.adventure.key.Key id, org.bukkit.Material base)
    Constructs a new custom item definition.
    Item(org.bukkit.inventory.ItemStack stack)
    Internal constructor for wrapping an existing item stack.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addTranslationProvider(ItemTranslationProvider provider)
    Adds a translation provider to this item for resolving localized text elements dynamically.
    static CustomBlock
    asBlock(Item item)
    Attempts to find the custom block associated with a block-item.
    Item
    clone()
    Performs a deep clone of the item, including its stack, map, and tooltip state.
    void
    createTooltip(Item.Tooltip tooltip)
    Called when a tooltip is being generated.
    void
    createTooltip(Item.Tooltip tooltip, @Nullable org.bukkit.entity.Player player)
    Called when a tooltip is being generated for a specific viewer.
    boolean
    equals(Object o)
    Compares this item against another object for equality based on Key.
    ComponentMap
    getComponentMap()
    Retrieves the component map managing the item's state and data.
    CTag
    getCTag()
    Retrieves the AbyssalLib persistent data tag for this item.
    <C extends DataComponent<?>>
    C
    getData(DataComponentType<C> type)
    Retrieves the data component of the specified type.
    net.kyori.adventure.key.Key
    getId()
    Retrieves the unique Key associated with this item.
    org.bukkit.inventory.ItemStack
    getStack()
    Retrieves the underlying Bukkit ItemStack managed by this instance.
    org.bukkit.inventory.ItemStack
    getStack(@Nullable org.bukkit.entity.Player player)
    Creates a temporary clone of the item and renders it for a specific player's view.
    List<ItemTranslationProvider>
    getTranslationProviders()
    Retrieves the list of local translation providers applied to this item.
    boolean
    hasData(DataComponentType<?> type)
    Checks if this item possesses a specific component type.
    int
    hashCode()
    Generates a hash code derived from the item's unique Key.
    boolean
    hasTag(ItemTag tag)
    Checks if this item belongs to a specific ItemTag.
    boolean
    hasTag(net.kyori.adventure.key.Key id)
    Checks if this item belongs to a specific tag by its Key.
    boolean
    isHidden()
    Gets whether or not this item should be hidden in /give
    ActionResult
    onAnvil(AnvilContext ctx)
    Called when this item is placed in an anvil and requires custom logic.
    ActionResult
    onClick(org.bukkit.entity.Player player, int slot, org.bukkit.inventory.PlayerInventory inventory, InventoryClickType type)
    Callback triggered when a player clicks this item inside an inventory GUI.
    void
    onCraft(org.bukkit.entity.Player player)
    Called when a player successfully crafts this item.
    ActionResult
    onDrop(org.bukkit.entity.Player player)
    Called when a player drops this item onto the ground.
    ActionResult
    onHit(org.bukkit.entity.LivingEntity source, org.bukkit.entity.Entity target)
    Callback triggered after an entity hits another entity with this item.
    void
    onInventoryTick(org.bukkit.entity.Player player)
    Called once per tick for every player that has this item in their inventory.
    ActionResult
    onMine(org.bukkit.entity.LivingEntity source, org.bukkit.block.Block target)
    Callback triggered after an entity successfully mines a block with this item.
    ActionResult
    onPickup(org.bukkit.entity.Player player)
    Called when a player picks this item up from the ground.
    void
    onSlotChange(org.bukkit.entity.Player player, @Nullable Integer newSlot)
    Called when the item's position within a player's inventory changes.
    ActionResult
    onSwapHand(org.bukkit.entity.Player player, org.bukkit.inventory.EquipmentSlot current)
    Called when a player uses the swap-hand key with this item.
    ActionResult
    onUse(org.bukkit.entity.LivingEntity source, org.bukkit.inventory.EquipmentSlot hand, ClickType type)
    Callback triggered when a player uses this item while clicking into the air.
    ActionResult
    onUseOn(UseContext ctx)
    Callback triggered when a player uses this item on a specific block or entity.
    static Item
    resolve(org.bukkit.inventory.ItemStack stack)
    Resolves a standard Bukkit stack into a custom library Item.
    void
    setCTag(CTag container)
    Sets the AbyssalLib persistent data tag for this item.
    void
    setData(DataComponent<?> component)
    Adds or updates a data component for this item.
    void
    setHidden(boolean hidden)
    Sets whether or not this item should be hidden in /give
    void
    setTag(ItemTag tag)
    Adds this custom item's identity to an existing tag's logic.
    void
    unsetData(DataComponentType<?> type)
    Removes the data component associated with the provided type.
    void
    updateTooltip()
    Updates the item's data components (Lore, DisplayTooltip, TooltipStyle) based on the current state of the tooltip object.

    Methods inherited from class Object

    getClass, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • tooltip

      public Item.Tooltip tooltip
      The helper object used to build and manage procedural tooltips.

  • Constructor Details

    • Item

      @Internal public Item(org.bukkit.inventory.ItemStack stack)
      Internal constructor for wrapping an existing item stack.
      Parameters:
      stack - The ItemStack to wrap and analyze.

    • Item

      public Item(net.kyori.adventure.key.Key id)
      Constructs a new custom item definition.
      Parameters:
      id - The unique Key for the item (e.g, "plugin_id:item_name").

    • Item

      public Item(net.kyori.adventure.key.Key id, org.bukkit.Material base)
      Constructs a new custom item definition.
      Parameters:
      id - The unique Key for the item (e.g., "plugin_id:item_name").
      base - The base Material used for the underlying item stack.

  • Method Details

    • getTranslationProviders

      public List<ItemTranslationProvider> getTranslationProviders()
      Retrieves the list of local translation providers applied to this item.
      Returns:
      A list of ItemTranslationProvider instances.

    • addTranslationProvider

      public void addTranslationProvider(ItemTranslationProvider provider)
      Adds a translation provider to this item for resolving localized text elements dynamically.
      Parameters:
      provider - The ItemTranslationProvider to add.

    • createTooltip

      public void createTooltip(Item.Tooltip tooltip)
      Called when a tooltip is being generated. Override to add static lines.
      Parameters:
      tooltip - The Item.Tooltip instance to populate with lines and styles.

    • createTooltip

      public void createTooltip(Item.Tooltip tooltip, @Nullable @Nullable org.bukkit.entity.Player player)
      Called when a tooltip is being generated for a specific viewer.
      Parameters:
      tooltip - The Item.Tooltip instance to populate.
      player - The Player viewing the item, or null if unknown.

    • updateTooltip

      public void updateTooltip()
      Updates the item's data components (Lore, DisplayTooltip, TooltipStyle) based on the current state of the tooltip object.

    • setData

      public void setData(DataComponent<?> component)
      Adds or updates a data component for this item.
      Parameters:
      component - The DataComponent instance to apply.

    • getData

      public <C extends DataComponent<?>> C getData(DataComponentType<C> type)
      Retrieves the data component of the specified type.
      Type Parameters:
      C - The specific type of DataComponent.
      Parameters:
      type - The DataComponentType to look for.
      Returns:
      The found component, or null if not set.

    • hasData

      public boolean hasData(DataComponentType<?> type)
      Checks if this item possesses a specific component type.
      Parameters:
      type - The DataComponentType to verify.
      Returns:
      True if the component is present, false otherwise.

    • unsetData

      public void unsetData(DataComponentType<?> type)
      Removes the data component associated with the provided type.
      Parameters:
      type - The DataComponentType identifying the component to unset.

    • hasTag

      public boolean hasTag(net.kyori.adventure.key.Key id)
      Checks if this item belongs to a specific tag by its Key.
      Parameters:
      id - The Key of the tag (e.g., "minecraft:swords").
      Returns:
      True if the item is included in the tag.

    • hasTag

      public boolean hasTag(ItemTag tag)
      Checks if this item belongs to a specific ItemTag.
      Parameters:
      tag - The ItemTag instance to check.
      Returns:
      True if the item stack matches the tag criteria.

    • setTag

      public void setTag(ItemTag tag)
      Adds this custom item's identity to an existing tag's logic.
      Parameters:
      tag - The ItemTag to extend with this item.

    • setHidden

      public void setHidden(boolean hidden)
      Sets whether or not this item should be hidden in /give
      Parameters:
      hidden - whether or not to hide the item

    • isHidden

      public boolean isHidden()
      Gets whether or not this item should be hidden in /give
      Returns:
      whether or not to hide the item

    • onMine

      public ActionResult onMine(org.bukkit.entity.LivingEntity source, org.bukkit.block.Block target)
      Callback triggered after an entity successfully mines a block with this item.
      Parameters:
      source - The LivingEntity performing the mining.
      target - The Block that was destroyed.
      Returns:
      The resulting ActionResult determining event continuation.

    • onHit

      public ActionResult onHit(org.bukkit.entity.LivingEntity source, org.bukkit.entity.Entity target)
      Callback triggered after an entity hits another entity with this item.
      Parameters:
      source - The LivingEntity attacker.
      target - The Entity victim.
      Returns:
      The resulting ActionResult for the hit event.

    • onUseOn

      public ActionResult onUseOn(UseContext ctx)
      Callback triggered when a player uses this item on a specific block or entity.
      Parameters:
      ctx - The UseContext containing information about the interaction.
      Returns:
      The ActionResult of the block interaction.

    • onUse

      public ActionResult onUse(org.bukkit.entity.LivingEntity source, org.bukkit.inventory.EquipmentSlot hand, ClickType type)
      Callback triggered when a player uses this item while clicking into the air.
      Parameters:
      source - The LivingEntity using the item.
      hand - The EquipmentSlot used for the click.
      type - The ClickType (Right-click or Left-click) performed in air.
      Returns:
      The ActionResult of the air interaction.

    • onInventoryTick

      public void onInventoryTick(org.bukkit.entity.Player player)
      Called once per tick for every player that has this item in their inventory.
      Parameters:
      player - The Player carrying the item.

    • onSlotChange

      public void onSlotChange(org.bukkit.entity.Player player, @Nullable @Nullable Integer newSlot)
      Called when the item's position within a player's inventory changes.
      Parameters:
      player - The Player whose inventory was updated.
      newSlot - The index of the new slot, or null if moved out of inventory.

    • onClick

      public ActionResult onClick(org.bukkit.entity.Player player, int slot, org.bukkit.inventory.PlayerInventory inventory, InventoryClickType type)
      Callback triggered when a player clicks this item inside an inventory GUI.
      Parameters:
      player - The Player clicking.
      slot - The raw slot index clicked.
      inventory - The PlayerInventory involved.
      type - The InventoryClickType representing the click style.
      Returns:
      The ActionResult determining if the click is allowed.

    • onDrop

      public ActionResult onDrop(org.bukkit.entity.Player player)
      Called when a player drops this item onto the ground.
      Parameters:
      player - The Player who dropped the item.
      Returns:
      The ActionResult of the drop.

    • onPickup

      public ActionResult onPickup(org.bukkit.entity.Player player)
      Called when a player picks this item up from the ground.
      Parameters:
      player - The Player picking up the item.
      Returns:
      The ActionResult of the pickup.

    • onSwapHand

      public ActionResult onSwapHand(org.bukkit.entity.Player player, org.bukkit.inventory.EquipmentSlot current)
      Called when a player uses the swap-hand key with this item.
      Parameters:
      player - The Player swapping the item.
      current - The EquipmentSlot the item was in before the swap.
      Returns:
      The ActionResult of the swap action.

    • onAnvil

      public ActionResult onAnvil(AnvilContext ctx)
      Called when this item is placed in an anvil and requires custom logic.
      Parameters:
      ctx - The AnvilContext containing the input and result slots.
      Returns:
      The ActionResult of the anvil process.

    • onCraft

      public void onCraft(org.bukkit.entity.Player player)
      Called when a player successfully crafts this item.
      Parameters:
      player - The Player who completed the craft.

    • getId

      public net.kyori.adventure.key.Key getId()
      Retrieves the unique Key associated with this item.
      Returns:
      The item's unique Key.

    • getStack

      public org.bukkit.inventory.ItemStack getStack()
      Retrieves the underlying Bukkit ItemStack managed by this instance.
      Returns:
      The underlying ItemStack.

    • getStack

      public org.bukkit.inventory.ItemStack getStack(@Nullable @Nullable org.bukkit.entity.Player player)
      Creates a temporary clone of the item and renders it for a specific player's view.
      Parameters:
      player - The Player for whom the stack is being generated.
      Returns:
      A localized ItemStack with a customized tooltip.

    • getComponentMap

      public ComponentMap getComponentMap()
      Retrieves the component map managing the item's state and data.
      Returns:
      The internal ComponentMap.

    • getCTag

      public CTag getCTag()
      Retrieves the AbyssalLib persistent data tag for this item.
      Returns:
      A CTag instance for accessing persistent data.

    • setCTag

      public void setCTag(CTag container)
      Sets the AbyssalLib persistent data tag for this item.
      Parameters:
      container - The CTag data to apply to the item's persistent data container.

    • resolve

      public static Item resolve(org.bukkit.inventory.ItemStack stack)
      Resolves a standard Bukkit stack into a custom library Item.
      Parameters:
      stack - The ItemStack to check.
      Returns:
      A custom Item instance if valid, otherwise null.

    • asBlock

      public static CustomBlock asBlock(Item item)
      Attempts to find the custom block associated with a block-item.
      Parameters:
      item - The Item to analyze.
      Returns:
      The CustomBlock counterpart, or null if not a block.

    • clone

      public Item clone()
      Performs a deep clone of the item, including its stack, map, and tooltip state.
      Returns:
      A new Item clone.

    • equals

      public boolean equals(Object o)
      Compares this item against another object for equality based on Key.
      Overrides:
      equals in class Object
      Parameters:
      o - The other object to compare.
      Returns:
      True if both items share the same unique Key.

    • hashCode

      public int hashCode()
      Generates a hash code derived from the item's unique Key.
      Overrides:
      hashCode in class Object
      Returns:
      The integer hash code.