Package org.bukkit.inventory

Class ItemStack

java.lang.Object
org.bukkit.inventory.ItemStack
All Implemented Interfaces:
PersistentDataViewHolder, Cloneable, HoverEventSource<HoverEvent.ShowItem>, Translatable, ConfigurationSerializable, Translatable
public class ItemStack extends Object implements Cloneable, ConfigurationSerializable, Translatable, HoverEventSource<HoverEvent.ShowItem>, Translatable, PersistentDataViewHolder
Represents a stack of items.

IMPORTANT: An ItemStack is only designed to contain items. Do not use this class to encapsulate Materials for which Material.isItem() returns false.

  • Constructor Details

  • Method Details

    • of

      @Contract(value="_ -> new", pure=true) @NotNull public static @NotNull ItemStack of(@NotNull @NotNull Material type)
      Creates an itemstack with the specified item type and a count of 1.
      Parameters:
      type - the item type to use
      Returns:
      a new itemstack
      Throws:
      IllegalArgumentException - if the Material provided is not an item (Material.isItem())

    • of

      @Contract(value="_, _ -> new", pure=true) @NotNull public static @NotNull ItemStack of(@NotNull @NotNull Material type, int amount)
      Creates an itemstack with the specified item type and count.
      Parameters:
      type - the item type to use
      amount - the count of items in the stack
      Returns:
      a new itemstack
      Throws:
      IllegalArgumentException - if the Material provided is not an item (Material.isItem())
      IllegalArgumentException - if the amount is less than 1

    • getPersistentDataContainer

      public @NotNull PersistentDataContainerView getPersistentDataContainer()
      Description copied from interface: PersistentDataViewHolder
      Returns a custom tag container view capable of viewing tags on the object.

      Note that the tags stored on this container are all stored under their own custom namespace therefore modifying default tags using this PersistentDataViewHolder is impossible.

      Specified by:
      getPersistentDataContainer in interface PersistentDataViewHolder
      Returns:
      the persistent data container view

    • getType

      @NotNull public @NotNull Material getType()
      Gets the type of this item
      Returns:
      Type of the items in this stack

    • setType

      @Deprecated public void setType(@NotNull @NotNull Material type)
      Deprecated.
      Setting the material type of ItemStacks is no longer supported.

      This method is deprecated due to potential illegal behavior that may occur during the context of which this ItemStack is being used, allowing for certain item validation to be bypassed. It is recommended to instead create a new ItemStack object with the desired Material type, and if possible, set it in the appropriate context. Using this method in ItemStacks passed in events will result in undefined behavior.

      Sets the type of this item

      Note that in doing so you will reset the MaterialData for this stack.

      IMPORTANT: An ItemStack is only designed to contain items. Do not use this class to encapsulate Materials for which Material.isItem() returns false.

      Parameters:
      type - New type to set the items in this stack to
      See Also:

    • withType

      @NotNull @Contract(value="_ -> new", pure=true) public @NotNull ItemStack withType(@NotNull @NotNull Material type)
      Creates a new ItemStack with the specified Material type, where the item count and item meta is preserved.
      Parameters:
      type - The Material type of the new ItemStack.
      Returns:
      A new ItemStack instance with the specified Material type.

    • getAmount

      public int getAmount()
      Gets the amount of items in this stack
      Returns:
      Amount of items in this stack

    • setAmount

      public void setAmount(int amount)
      Sets the amount of items in this stack
      Parameters:
      amount - New amount of items in this stack

    • getData

      @Nullable @Deprecated(forRemoval=true, since="1.13") public @Nullable MaterialData getData()
      Deprecated, for removal: This API element is subject to removal in a future version.
      cast to BlockDataMeta and use BlockDataMeta.getBlockData(Material)
      Gets the MaterialData for this stack of items
      Returns:
      MaterialData for this item

    • setData

      @Deprecated(forRemoval=true, since="1.13") public void setData(@Nullable @Nullable MaterialData data)
      Deprecated, for removal: This API element is subject to removal in a future version.
      cast to BlockDataMeta and use BlockDataMeta.setBlockData(org.bukkit.block.data.BlockData)
      Sets the MaterialData for this stack of items
      Parameters:
      data - New MaterialData for this item

    • setDurability

      @Deprecated public void setDurability(short durability)
      Deprecated.
      durability is now part of ItemMeta. To avoid confusion and misuse, getItemMeta(), setItemMeta(ItemMeta) and Damageable.setDamage(int) should be used instead. This is because any call to this method will be overwritten by subsequent setting of ItemMeta which was created before this call.
      Sets the durability of this item
      Parameters:
      durability - Durability of this item

    • getDurability

      @Deprecated public short getDurability()
      Deprecated.
      see setDurability(short)
      Gets the durability of this item
      Returns:
      Durability of this item

    • getMaxStackSize

      public int getMaxStackSize()
      Get the maximum stack size for this item. If this item has a max stack size component (ItemMeta.hasMaxStackSize()), the value of that component will be returned. Otherwise, this item's Material's default maximum stack size will be returned instead.
      Returns:
      The maximum you can stack this item to.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • isSimilar

      public boolean isSimilar(@Nullable @Nullable ItemStack stack)
      This method is the same as equals, but does not consider stack size (amount).
      Parameters:
      stack - the item stack to compare to
      Returns:
      true if the two stacks are equal, ignoring the amount

    • clone

      @NotNull public @NotNull ItemStack clone()
      Overrides:
      clone in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • containsEnchantment

      public boolean containsEnchantment(@NotNull @NotNull Enchantment ench)
      Checks if this ItemStack contains the given Enchantment
      Parameters:
      ench - Enchantment to test
      Returns:
      True if this has the given enchantment

    • getEnchantmentLevel

      public int getEnchantmentLevel(@NotNull @NotNull Enchantment ench)
      Gets the level of the specified enchantment on this item stack
      Parameters:
      ench - Enchantment to check
      Returns:
      Level of the enchantment, or 0

    • getEnchantments

      @NotNull public @NotNull Map<Enchantment,Integer> getEnchantments()
      Gets a map containing all enchantments and their levels on this item.
      Returns:
      Map of enchantments.

    • addEnchantments

      public void addEnchantments(@NotNull @NotNull Map<Enchantment,Integer> enchantments)
      Adds the specified enchantments to this item stack.

      This method is the same as calling addEnchantment(org.bukkit.enchantments.Enchantment, int) for each element of the map.

      Parameters:
      enchantments - Enchantments to add
      Throws:
      IllegalArgumentException - if the specified enchantments is null
      IllegalArgumentException - if any specific enchantment or level is null. Warning: Some enchantments may be added before this exception is thrown.

    • addEnchantment

      public void addEnchantment(@NotNull @NotNull Enchantment ench, int level)
      Adds the specified Enchantment to this item stack.

      If this item stack already contained the given enchantment (at any level), it will be replaced.

      Parameters:
      ench - Enchantment to add
      level - Level of the enchantment
      Throws:
      IllegalArgumentException - if enchantment null, or enchantment is not applicable

    • addUnsafeEnchantments

      public void addUnsafeEnchantments(@NotNull @NotNull Map<Enchantment,Integer> enchantments)
      Adds the specified enchantments to this item stack in an unsafe manner.

      This method is the same as calling addUnsafeEnchantment(org.bukkit.enchantments.Enchantment, int) for each element of the map.

      Parameters:
      enchantments - Enchantments to add

    • addUnsafeEnchantment

      public void addUnsafeEnchantment(@NotNull @NotNull Enchantment ench, int level)
      Adds the specified Enchantment to this item stack.

      If this item stack already contained the given enchantment (at any level), it will be replaced.

      This method is unsafe and will ignore level restrictions or item type. Use at your own discretion.

      Parameters:
      ench - Enchantment to add
      level - Level of the enchantment

    • removeEnchantment

      public int removeEnchantment(@NotNull @NotNull Enchantment ench)
      Removes the specified Enchantment if it exists on this ItemStack
      Parameters:
      ench - Enchantment to remove
      Returns:
      Previous level, or 0

    • removeEnchantments

      public void removeEnchantments()
      Removes all enchantments on this ItemStack.

    • serialize

      @NotNull public @NotNull Map<String,Object> serialize()
      Description copied from interface: ConfigurationSerializable
      Creates a Map representation of this class.

      This class must provide a method to restore this class, as defined in the ConfigurationSerializable interface javadocs.

      Specified by:
      serialize in interface ConfigurationSerializable
      Returns:
      Map containing the current state of this class

    • deserialize

      @NotNull public static @NotNull ItemStack deserialize(@NotNull @NotNull Map<String,Object> args)
      Required method for configuration serialization
      Parameters:
      args - map to deserialize
      Returns:
      deserialized item stack
      See Also:

    • editMeta

      public boolean editMeta(@NotNull Consumer<? super ItemMeta> consumer)
      Edits the ItemMeta of this stack.

      The Consumer must only interact with this stack's ItemMeta through the provided ItemMeta instance. Calling this method or any other meta-related method of the ItemStack class (such as getItemMeta(), addItemFlags(ItemFlag...), lore(), etc.) from inside the consumer is disallowed and will produce undefined results or exceptions.

      Parameters:
      consumer - the meta consumer
      Returns:
      true if the edit was successful, false otherwise

    • editMeta

      public <M extends ItemMeta> boolean editMeta(@NotNull @NotNull Class<M> metaClass, @NotNull Consumer<@NotNull ? super M> consumer)
      Edits the ItemMeta of this stack if the meta is of the specified type.

      The Consumer must only interact with this stack's ItemMeta through the provided ItemMeta instance. Calling this method or any other meta-related method of the ItemStack class (such as getItemMeta(), addItemFlags(ItemFlag...), lore(), etc.) from inside the consumer is disallowed and will produce undefined results or exceptions.

      Type Parameters:
      M - the meta type
      Parameters:
      metaClass - the type of meta to edit
      consumer - the meta consumer
      Returns:
      true if the edit was successful, false otherwise

    • getItemMeta

      @UndefinedNullability public ItemMeta getItemMeta()
      Get a copy of this ItemStack's ItemMeta.
      Returns:
      a copy of the current ItemStack's ItemData

    • hasItemMeta

      public boolean hasItemMeta()
      Checks to see if any meta data has been defined.
      Returns:
      Returns true if some meta data has been set for this item

    • setItemMeta

      public boolean setItemMeta(@Nullable @Nullable ItemMeta itemMeta)
      Set the ItemMeta of this ItemStack.
      Parameters:
      itemMeta - new ItemMeta, or null to indicate meta data be cleared.
      Returns:
      True if successfully applied ItemMeta, see ItemFactory.isApplicable(ItemMeta, ItemStack)
      Throws:
      IllegalArgumentException - if the item meta was not created by the ItemFactory

    • getTranslationKey

      @NotNull @Deprecated(forRemoval=true) public @NotNull String getTranslationKey()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Description copied from interface: Translatable
      Get the translation key, suitable for use in a translation component.
      Specified by:
      getTranslationKey in interface Translatable
      Returns:
      the translation key

    • enchantWithLevels

      @NotNull public @NotNull ItemStack enchantWithLevels(@org.jetbrains.annotations.Range(from=1L, to=30L) int levels, boolean allowTreasure, @NotNull Random random)
      Randomly enchants a copy of this ItemStack using the given experience levels.

      If this ItemStack is already enchanted, the existing enchants will be removed before enchanting.

      Levels must be in range [1, 30].

      Parameters:
      levels - levels to use for enchanting
      allowTreasure - whether to allow enchantments where Enchantment.isTreasure() returns true
      random - Random instance to use for enchanting
      Returns:
      enchanted copy of the provided ItemStack
      Throws:
      IllegalArgumentException - on bad arguments

    • enchantWithLevels

      @NotNull public @NotNull ItemStack enchantWithLevels(@org.jetbrains.annotations.Range(from=1L, to=30L) int levels, @NotNull RegistryKeySet<@NotNull Enchantment> keySet, @NotNull Random random)
      Randomly enchants a copy of this ItemStack using the given experience levels.

      If the provided ItemStack is already enchanted, the existing enchants will be removed before enchanting.

      Levels must be in range [1, 30].

      Parameters:
      levels - levels to use for enchanting
      keySet - registry key set defining the set of possible enchantments, e.g. EnchantmentTagKeys.IN_ENCHANTING_TABLE.
      random - Random instance to use for enchanting
      Returns:
      enchanted copy of the provided ItemStack
      Throws:
      IllegalArgumentException - on bad arguments

    • asHoverEvent

      @NotNull public HoverEvent<HoverEvent.ShowItem> asHoverEvent(@NotNull UnaryOperator<HoverEvent.ShowItem> op)
      Description copied from interface: net.kyori.adventure.text.event.HoverEventSource
      Creates a hover event with value derived from this object.

      The event value will be passed through the provided callback to allow transforming the original value of the event.

      Specified by:
      asHoverEvent in interface HoverEventSource<HoverEvent.ShowItem>
      Parameters:
      op - transformation on value
      Returns:
      a hover event

    • displayName

      public @NotNull Component displayName()
      Get the formatted display name of the ItemStack.
      Returns:
      display name of the ItemStack

    • ensureServerConversions

      @NotNull public @NotNull ItemStack ensureServerConversions()
      Minecraft updates are converting simple item stacks into more complex NBT oriented Item Stacks. Use this method to ensure any desired data conversions are processed. The input itemstack will not be the same as the returned itemstack.
      Returns:
      A potentially Data Converted ItemStack

    • deserializeBytes

      @NotNull public static @NotNull ItemStack deserializeBytes(@NotNull @org.jetbrains.annotations.NotNull byte[] bytes)
      Deserializes this itemstack from raw NBT bytes. NBT is safer for data migrations as it will use the built in data converter instead of bukkits dangerous serialization system. This expects that the DataVersion was stored on the root of the Compound, as saved from the serializeAsBytes() API returned.
      Parameters:
      bytes - bytes representing an item in NBT
      Returns:
      ItemStack migrated to this version of Minecraft if needed.

    • serializeAsBytes

      @NotNull public @org.jetbrains.annotations.NotNull byte[] serializeAsBytes()
      Serializes this itemstack to raw bytes in NBT. NBT is safer for data migrations as it will use the built in data converter instead of bukkits dangerous serialization system.
      Returns:
      bytes representing this item in NBT.

    • serializeItemsAsBytes

      public static byte @NotNull [] serializeItemsAsBytes(@NotNull Collection<ItemStack> items)
      Serializes a collection of items to raw bytes in NBT. Serializes null items as empty().

      If you need a string representation to put into a file, you can for example use Base64 encoding.

      Parameters:
      items - items to serialize
      Returns:
      bytes representing the items in NBT
      See Also:

    • serializeItemsAsBytes

      public static byte @NotNull [] serializeItemsAsBytes(@Nullable @Nullable ItemStack @NotNull [] items)
      Serializes a collection of items to raw bytes in NBT. Serializes null items as empty().

      If you need a string representation to put into a file, you can for example use Base64 encoding.

      Parameters:
      items - items to serialize
      Returns:
      bytes representing the items in NBT
      See Also:

    • deserializeItemsFromBytes

      @NotNull public static @NotNull ItemStack @NotNull [] deserializeItemsFromBytes(byte @NotNull [] bytes)
      Deserializes this itemstack from raw NBT bytes.

      If you need a string representation to put into a file, you can for example use Base64 encoding.

      Parameters:
      bytes - bytes representing an item in NBT
      Returns:
      ItemStack array migrated to this version of Minecraft if needed
      See Also:

    • getI18NDisplayName

      @Nullable @Deprecated public @Nullable String getI18NDisplayName()
      Deprecated.
      ItemStack implements Translatable; use that and Component.translatable(net.kyori.adventure.translation.Translatable) instead.
      Gets the Display name as seen in the Client. Currently the server only supports the English language. To override this, You must replace the language file embedded in the server jar.
      Returns:
      Display name of Item

    • getMaxItemUseDuration

      @Deprecated(forRemoval=true) public int getMaxItemUseDuration()
      Deprecated, for removal: This API element is subject to removal in a future version.
      use getMaxItemUseDuration(org.bukkit.entity.LivingEntity); crossbows, later possibly more items require an entity parameter

    • getMaxItemUseDuration

      public int getMaxItemUseDuration(@NotNull LivingEntity entity)

    • asOne

      @NotNull public @NotNull ItemStack asOne()
      Clones the itemstack and returns it a single quantity.
      Returns:
      The new itemstack with 1 quantity

    • asQuantity

      @NotNull public @NotNull ItemStack asQuantity(int qty)
      Clones the itemstack and returns it as the specified quantity
      Parameters:
      qty - The quantity of the cloned item
      Returns:
      The new itemstack with specified quantity

    • add

      @NotNull public @NotNull ItemStack add()
      Adds 1 to this itemstack. Will not go over the items max stack size.
      Returns:
      The same item (not a clone)

    • add

      @NotNull public @NotNull ItemStack add(int qty)
      Adds quantity to this itemstack. Will not go over the items max stack size.
      Parameters:
      qty - The amount to add
      Returns:
      The same item (not a clone)

    • subtract

      @NotNull public @NotNull ItemStack subtract()
      Subtracts 1 to this itemstack. Going to 0 or less will invalidate the item.
      Returns:
      The same item (not a clone)

    • subtract

      @NotNull public @NotNull ItemStack subtract(int qty)
      Subtracts quantity to this itemstack. Going to 0 or less will invalidate the item.
      Parameters:
      qty - The amount to add
      Returns:
      The same item (not a clone)

    • getLore

      @Deprecated @Nullable public List<String> getLore()
      Deprecated.
      in favor of lore()
      If the item has lore, returns it, else it will return null
      Returns:
      The lore, or null

    • lore

      @Nullable public List<Component> lore()
      If the item has lore, returns it, else it will return null
      Returns:
      The lore, or null

    • setLore

      @Deprecated public void setLore(@Nullable List<String> lore)
      Deprecated.
      in favour of lore(java.util.List)
      Sets the lore for this item. Removes lore when given null.
      Parameters:
      lore - the lore that will be set

    • lore

      public void lore(@Nullable List<? extends Component> lore)
      Sets the lore for this item. Removes lore when given null.
      Parameters:
      lore - the lore that will be set

    • addItemFlags

      public void addItemFlags(@NotNull @NotNull ItemFlag... itemFlags)
      Set itemflags which should be ignored when rendering a ItemStack in the Client. This Method does silently ignore double set itemFlags.
      Parameters:
      itemFlags - The hideflags which shouldn't be rendered

    • removeItemFlags

      public void removeItemFlags(@NotNull @NotNull ItemFlag... itemFlags)
      Remove specific set of itemFlags. This tells the Client it should render it again. This Method does silently ignore double removed itemFlags.
      Parameters:
      itemFlags - Hideflags which should be removed

    • getItemFlags

      @NotNull public Set<ItemFlag> getItemFlags()
      Get current set itemFlags. The collection returned is unmodifiable.
      Returns:
      A set of all itemFlags set

    • hasItemFlag

      public boolean hasItemFlag(@NotNull @NotNull ItemFlag flag)
      Check if the specified flag is present on this item.
      Parameters:
      flag - the flag to check
      Returns:
      if it is present

    • translationKey

      @NotNull public @NotNull String translationKey()
      Gets the translation key.

      This is not the same as getting the translation key for the material of this itemstack.

      Specified by:
      translationKey in interface Translatable
      Returns:
      the translation key

    • getRarity

      @NotNull @Deprecated(forRemoval=true, since="1.20.5") public ItemRarity getRarity()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use ItemMeta.hasRarity() and ItemMeta.getRarity()
      Gets the item rarity of the itemstack. The rarity can change based on enchantments.
      Returns:
      the itemstack rarity

    • isRepairableBy

      public boolean isRepairableBy(@NotNull @NotNull ItemStack repairMaterial)
      Checks if an itemstack can repair this itemstack. Returns false if this or repairMaterial's type is not an item (Material.isItem()).
      Parameters:
      repairMaterial - the repair material
      Returns:
      true if it is repairable by, false if not

    • canRepair

      public boolean canRepair(@NotNull @NotNull ItemStack toBeRepaired)
      Checks if this itemstack can repair another. Returns false if this or toBeRepaired's type is not an item (Material.isItem()).
      Parameters:
      toBeRepaired - the itemstack to be repaired
      Returns:
      true if it can repair, false if not

    • damage

      @NotNull public @NotNull ItemStack damage(int amount, @NotNull LivingEntity livingEntity)
      Damages this itemstack by the specified amount. This runs all logic associated with damaging an itemstack like events and stat changes.
      Parameters:
      amount - the amount of damage to do
      livingEntity - the entity related to the damage
      Returns:
      the damaged itemstack or an empty one if it broke. May return the same instance of ItemStack
      See Also:

    • empty

      @NotNull public static @NotNull ItemStack empty()
      Returns an empty item stack, consists of an air material and a stack size of 0. Any item stack with a material of air or a stack size of 0 is seen as being empty by isEmpty().

    • isEmpty

      public boolean isEmpty()
      Returns whether this item stack is empty and contains no item. This means it is either air or the stack has a size of 0.

    • computeTooltipLines

      public @NotNull @Unmodifiable List<Component> computeTooltipLines(@NotNull TooltipContext tooltipContext, @Nullable Player player)
      Computes the tooltip lines for this stack.

      Disclaimer: Tooltip contents are not guaranteed to be consistent across different Minecraft versions.

      Parameters:
      tooltipContext - the tooltip context
      player - a player for player-specific tooltip lines
      Returns:
      an immutable list of components (can be empty)