Package org.bukkit.inventory

Interface ItemFactory

public interface ItemFactory

An instance of the ItemFactory can be obtained with Server.getItemFactory().

The ItemFactory is solely responsible for creating item meta containers to apply on item stacks.

Method Summary

Modifier and Type	Method	Description
HoverEvent<HoverEvent.ShowItem>	asHoverEvent(@NotNull ItemStack item, UnaryOperator<HoverEvent.ShowItem> op)	Creates a hover event for the given item.
@Nullable ItemMeta	asMetaFor(@NotNull ItemMeta meta, @NotNull Material material)	Returns an appropriate item meta for the specified material.
@Nullable ItemMeta	asMetaFor(@NotNull ItemMeta meta, @NotNull ItemStack stack)	Returns an appropriate item meta for the specified stack.
@NotNull ItemStack	createItemStack(@NotNull String input)	Create a new ItemStack given the supplied input.
Component	displayName(@NotNull ItemStack itemStack)	Get the formatted display name of the ItemStack.
@NotNull ItemStack	enchantItem(@NotNull World world, @NotNull ItemStack item, int level, boolean allowTreasures)	Deprecated. use enchantWithLevels(ItemStack, int, boolean, java.util.Random).
@NotNull ItemStack	enchantItem(@NotNull Entity entity, @NotNull ItemStack item, int level, boolean allowTreasures)	Deprecated. use enchantWithLevels(ItemStack, int, boolean, java.util.Random).
@NotNull ItemStack	enchantItem(@NotNull ItemStack item, int level, boolean allowTreasures)	Deprecated. use enchantWithLevels(ItemStack, int, boolean, java.util.Random).
@NotNull ItemStack	enchantWithLevels(@NotNull ItemStack itemStack, @org.jetbrains.annotations.Range(from=1L, to=30L) int levels, boolean allowTreasure, Random random)	Randomly enchants a copy of the provided ItemStack using the given experience levels.
@NotNull ItemStack	enchantWithLevels(@NotNull ItemStack itemStack, @org.jetbrains.annotations.Range(from=1L, to=30L) int levels, RegistryKeySet<@NotNull Enchantment> keySet, Random random)	Randomly enchants a copy of the provided ItemStack using the given experience levels.
@NotNull ItemStack	ensureServerConversions(@NotNull ItemStack item)	Minecraft's updates are converting simple item stacks into more complex NBT oriented Item Stacks.
boolean	equals(@Nullable ItemMeta meta1, @Nullable ItemMeta meta2)	This method is used to compare two item meta data objects.
@NotNull Color	getDefaultLeatherColor()	Returns the default color for all leather armor.
@Nullable String	getI18NDisplayName(@Nullable ItemStack item)	Deprecated. ItemStack implements Translatable; use that and Component.translatable(net.kyori.adventure.translation.Translatable) instead.
ItemMeta	getItemMeta(@NotNull Material material)	This creates a new item meta for the material.
@Nullable Material	getSpawnEgg(@NotNull EntityType type)	Gets a Material representing the spawn egg for the provided EntityType.
net.md_5.bungee.api.chat.hover.content.Content	hoverContentOf(Entity entity)	Deprecated. use HoverEventSource.asHoverEvent()
net.md_5.bungee.api.chat.hover.content.Content	hoverContentOf(Entity entity, @Nullable String customName)	Deprecated. use Entity.asHoverEvent(java.util.function.UnaryOperator)
net.md_5.bungee.api.chat.hover.content.Content	hoverContentOf(Entity entity, net.md_5.bungee.api.chat.BaseComponent customName)	Deprecated. use Entity.asHoverEvent(java.util.function.UnaryOperator)
net.md_5.bungee.api.chat.hover.content.Content	hoverContentOf(Entity entity, net.md_5.bungee.api.chat.BaseComponent[] customName)	Deprecated. use Entity.asHoverEvent(java.util.function.UnaryOperator)
net.md_5.bungee.api.chat.hover.content.Content	hoverContentOf(@NotNull ItemStack itemStack)	Deprecated. use HoverEventSource.asHoverEvent()
boolean	isApplicable(@Nullable ItemMeta meta, @Nullable Material material)	This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified Material.
boolean	isApplicable(@Nullable ItemMeta meta, @Nullable ItemStack stack)	This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified ItemStack.

Method Details

getItemMeta

@UndefinedNullability
ItemMeta getItemMeta(@NotNull
 @NotNull Material material)

This creates a new item meta for the material.

Parameters:

material - The material to consider as base for the meta

Returns:

a new ItemMeta that could be applied to an item stack of the specified material

isApplicable

boolean isApplicable(@Nullable
 @Nullable ItemMeta meta,
 @Nullable
 @Nullable ItemStack stack)
              throws IllegalArgumentException

This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified ItemStack.

A SkullMeta would not be valid for a sword, but a normal ItemMeta from an enchanted dirt block would.

Parameters:

meta - Meta to check

stack - Item that meta will be applied to

Returns:

true if the meta can be applied without losing data, false otherwise

Throws:

IllegalArgumentException - if the meta was not created by this factory

isApplicable

boolean isApplicable(@Nullable
 @Nullable ItemMeta meta,
 @Nullable
 @Nullable Material material)
              throws IllegalArgumentException

This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified Material.

A SkullMeta would not be valid for a sword, but a normal ItemMeta from an enchanted dirt block would.

Parameters:

meta - Meta to check

material - Material that meta will be applied to

Returns:

true if the meta can be applied without losing data, false otherwise

Throws:

IllegalArgumentException - if the meta was not created by this factory

equals

boolean equals(@Nullable
 @Nullable ItemMeta meta1,
 @Nullable
 @Nullable ItemMeta meta2)
        throws IllegalArgumentException

This method is used to compare two item meta data objects.

Parameters:

meta1 - First meta to compare, and may be null to indicate no data

meta2 - Second meta to compare, and may be null to indicate no data

Returns:

false if one of the meta has data the other does not, otherwise true

Throws:

IllegalArgumentException - if either meta was not created by this factory

asMetaFor

@Nullable
@Nullable ItemMeta asMetaFor(@NotNull
 @NotNull ItemMeta meta,
 @NotNull
 @NotNull ItemStack stack)
                      throws IllegalArgumentException

Returns an appropriate item meta for the specified stack.

The item meta returned will always be a valid meta for a given ItemStack of the specified material. It may be a more or less specific meta, and could also be the same meta or meta type as the parameter. The item meta returned will also always be the most appropriate meta.

Example, if a SkullMeta is being applied to a book, this method would return a BookMeta containing all information in the specified meta that is applicable to an ItemMeta, the highest common interface.

Parameters:

meta - the meta to convert

stack - the stack to convert the meta for

Returns:

An appropriate item meta for the specified item stack. No guarantees are made as to if a copy is returned. This will be null for a stack of air.

Throws:

IllegalArgumentException - if the specified meta was not created by this factory

asMetaFor

@Nullable
@Nullable ItemMeta asMetaFor(@NotNull
 @NotNull ItemMeta meta,
 @NotNull
 @NotNull Material material)
                      throws IllegalArgumentException

Returns an appropriate item meta for the specified material.

The item meta returned will always be a valid meta for a given ItemStack of the specified material. It may be a more or less specific meta, and could also be the same meta or meta type as the parameter. The item meta returned will also always be the most appropriate meta.

Example, if a SkullMeta is being applied to a book, this method would return a BookMeta containing all information in the specified meta that is applicable to an ItemMeta, the highest common interface.

Parameters:

meta - the meta to convert

material - the material to convert the meta for

Returns:

An appropriate item meta for the specified item material. No guarantees are made as to if a copy is returned. This will be null for air.

Throws:

IllegalArgumentException - if the specified meta was not created by this factory

getDefaultLeatherColor

@NotNull
@NotNull Color getDefaultLeatherColor()

Returns the default color for all leather armor.

Returns:

the default color for leather armor

createItemStack

@NotNull
@NotNull ItemStack createItemStack(@NotNull
 @NotNull String input)
                            throws IllegalArgumentException

Create a new ItemStack given the supplied input.

The input should match the same input as expected by Minecraft's /give command. For example,

"minecraft:diamond_sword[minecraft:enchantments={levels:{"minecraft:sharpness": 3}}]"

would yield an ItemStack of Material.DIAMOND_SWORD with an ItemMeta containing a level 3 Enchantment.SHARPNESS enchantment.

Parameters:

input - the item input string

Returns:

the created ItemStack

Throws:

IllegalArgumentException - if the input string was provided in an invalid or unsupported format

getSpawnEgg

@Nullable
@Nullable Material getSpawnEgg(@NotNull
 @NotNull EntityType type)

Gets a Material representing the spawn egg for the provided EntityType.
Will return null for EntityTypes that do not have a corresponding spawn egg.

Parameters:

type - the entity type

Returns:

the Material of this EntityTypes spawn egg or null

enchantItem

@NotNull
@Deprecated(since="1.19.3")
@NotNull ItemStack enchantItem(@NotNull
 @NotNull Entity entity,
 @NotNull
 @NotNull ItemStack item,
 int level,
 boolean allowTreasures)

Deprecated.

use enchantWithLevels(ItemStack, int, boolean, java.util.Random). This method's implementation is poorly designed and was originally broken.

Enchants the given item at the provided level.
If an item that is air is passed through an error is thrown.

Parameters:

entity - the entity to use as a source of randomness

item - the item to enchant

level - the level to use, which is the level in the enchantment table

allowTreasures - allows treasure enchants, e.g. mending, if true.

Returns:

a new ItemStack containing the result of the Enchantment

enchantItem

@NotNull
@Deprecated(since="1.19.3")
@NotNull ItemStack enchantItem(@NotNull
 @NotNull World world,
 @NotNull
 @NotNull ItemStack item,
 int level,
 boolean allowTreasures)

Deprecated.

use enchantWithLevels(ItemStack, int, boolean, java.util.Random). This method's implementation is poorly designed and was originally broken.

Enchants the given item at the provided level.
If an item that is air is passed through an error is thrown.

Parameters:

world - the world to use as a source of randomness

item - the item to enchant

level - the level to use, which is the level in the enchantment table

allowTreasures - allow the treasure enchants, e.g. mending, if true.

Returns:

a new ItemStack containing the result of the Enchantment

enchantItem

@NotNull
@Deprecated(since="1.19.3")
@NotNull ItemStack enchantItem(@NotNull
 @NotNull ItemStack item,
 int level,
 boolean allowTreasures)

Deprecated.

use enchantWithLevels(ItemStack, int, boolean, java.util.Random). This method's implementation is poorly designed and was originally broken.

Enchants the given item at the provided level.
If an item that is air is passed through an error is thrown.

Parameters:

item - the item to enchant

level - the level to use, which is the level in the enchantment table

allowTreasures - allow treasure enchantments, e.g. mending, if true.

Returns:

a new ItemStack containing the result of the Enchantment

asHoverEvent

@NotNull
HoverEvent<HoverEvent.ShowItem> asHoverEvent(@NotNull
 @NotNull ItemStack item,
 @NotNull
 UnaryOperator<HoverEvent.ShowItem> op)

Creates a hover event for the given item.

Parameters:

item - The item

Returns:

A hover event

displayName

@NotNull
Component displayName(@NotNull
 @NotNull ItemStack itemStack)

Get the formatted display name of the ItemStack.

Parameters:

itemStack - the ItemStack

Returns:

display name of the ItemStack

getI18NDisplayName

@Nullable
@Deprecated(since="1.18.1")
@Nullable String getI18NDisplayName(@Nullable
 @Nullable ItemStack item)

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.

Parameters:

item - Item to return Display name of

Returns:

Display name of Item

ensureServerConversions

@NotNull
@NotNull ItemStack ensureServerConversions(@NotNull
 @NotNull ItemStack item)

Minecraft's 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.

Parameters:

item - The item to process conversions on

Returns:

A potentially Data-Converted-ItemStack

hoverContentOf

@NotNull
@Deprecated
net.md_5.bungee.api.chat.hover.content.Content hoverContentOf(@NotNull
 @NotNull ItemStack itemStack)

Deprecated.

use HoverEventSource.asHoverEvent()

Creates a Content of that ItemStack for displaying.

Parameters:

itemStack - the itemstack

Returns:

the Content of that ItemStack

hoverContentOf

@NotNull
@Deprecated
net.md_5.bungee.api.chat.hover.content.Content hoverContentOf(@NotNull
 Entity entity)

Deprecated.

use HoverEventSource.asHoverEvent()

Creates a Content of that Entity for displaying. Uses the display name of the entity, if present.

Parameters:

entity - Entity to create the HoverEvent for

Returns:

the Content of that Entity

hoverContentOf

@NotNull
@Deprecated
net.md_5.bungee.api.chat.hover.content.Content hoverContentOf(@NotNull
 Entity entity,
 @Nullable
 @Nullable String customName)

Deprecated.

use Entity.asHoverEvent(java.util.function.UnaryOperator)

Creates a Content of that Entity for displaying.

Parameters:

entity - Entity to create the HoverEvent for

customName - a custom name that should be displayed, if not passed entity name will be displayed

Returns:

the Content of that Entity

hoverContentOf

@NotNull
@Deprecated
net.md_5.bungee.api.chat.hover.content.Content hoverContentOf(@NotNull
 Entity entity,
 @Nullable
 net.md_5.bungee.api.chat.BaseComponent customName)

Deprecated.

use Entity.asHoverEvent(java.util.function.UnaryOperator)

Creates a Content of that Entity for displaying.

Parameters:

entity - Entity to create the HoverEvent for

customName - a custom name that should be displayed, if not passed entity name will be displayed

Returns:

the Content of that Entity

hoverContentOf

@NotNull
@Deprecated
net.md_5.bungee.api.chat.hover.content.Content hoverContentOf(@NotNull
 Entity entity,
 @NotNull
 net.md_5.bungee.api.chat.BaseComponent[] customName)

Deprecated.

use Entity.asHoverEvent(java.util.function.UnaryOperator)

Creates a Content of that Entity for displaying.

Parameters:

entity - Entity to create the HoverEvent for

customName - a custom name that should be displayed, if not passed entity name will be displayed

Returns:

the Content of that Entity

enchantWithLevels

@NotNull
@NotNull ItemStack enchantWithLevels(@NotNull
 @NotNull ItemStack itemStack,
 @org.jetbrains.annotations.Range(from=1L, to=30L) int levels,
 boolean allowTreasure,
 @NotNull
 Random random)

Randomly enchants a copy of the provided 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:

itemStack - ItemStack to enchant

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
@NotNull ItemStack enchantWithLevels(@NotNull
 @NotNull ItemStack itemStack,
 @org.jetbrains.annotations.Range(from=1L, to=30L) int levels,
 @NotNull
 RegistryKeySet<@NotNull Enchantment> keySet,
 @NotNull
 Random random)

Randomly enchants a copy of the provided 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:

itemStack - ItemStack to enchant

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