Item For Developers

This section is dedicated to developers. If you are looking for the server admins' page, click here

Many of the fields referenced on this page might be or require platform-specific values. Check the glossary

The item module aims to ease and improve the QOL of both server admins and developers by providing common, intuitive methods of creating and customizing objects.

It does so by providing a comprehensive API with method chaining and basic constructors that reduces the overhead introduced by ItemMeta.

NOTE: the item module automatically imports the corresponding wrappers module (when working with the item-base module, the wrappers-base will be imported, with the item-serializer the wrappers-serializer is and so on). This is required for features like enchantments to work properly and across versions.

All the objects described in this section are part of the base module, which is totally independent of any platform. If you want to store or load data on files, you will need to import the serializer module and use ItemYAGLParser#addAllParsers() JUST ONCE before starting any IO operation (it also includes calls to WrappersYAGLParser#addAllParsers() so you are not needed to specify that). Any reference to bukkit requires the bukkit module imported.

Items

The core class of this module is Item. This interface introduces various methods to add, edit or remove attributes in the current item.

In this section, we will go over every implementation of Item, how they can be used and what are their capabilities. Before proceeding, the reader must know the two most important functions:

• Item#newItem(): allows creating a new empty implementation of Item. This will create an empty item ready to be used;

• Item#copy(Class): allows copying the current Item to another implementation of it. This is extremely useful for converting items, but be aware that in some cases it may cause information loss. For example, converting a RecipeItem to an Item will discard every previous configured recipe.

  Every time in this Wiki the copy keyword is present, it means that the item in question should invoke the copy() function.

Item implementations
Item
RecipeItem
PersistentItem

Item

Item is the parent of all other items. As previously anticipated, it provides a huge number of methods to facilitate the developer creation and declaration of items. It does so by allowing method chaining for every setter, adder or remover method, thus keeping alive the coding flow.

BukkitItem

When using the item-bukkit module, the developer will be able to convert the item in ItemStacks. To do so, it is required to copy the current item to a BukkitItem and then invoke the BukkitItem#create method:

ItemStack stack = Item.newItem("diamond_sword").setAmount(1).copy(BukkitItem.class).create();

NOTE: you can also use BukkitItem#newItem to immediately have access to the create method, without calling copy.

In case the developer wants more control, or requires a feature in the moment of the creation that YAGL does not introduce, a BukkitItem#create(Class, Consumer) is provided: this allows changing the final stack meta at the moment of the creation. As an example, let's go over the creation of a skull with the skin of a player:

// The Material enum can be used as well!
ItemStack skull = BukkitItem.newItem(Material.PLAYER_HEAD).create(SkullMeta.class, skullMeta -> {
  OfflinePlayer player = Bukkit.getOfflinePlayer(uuid);
  if (player != null) skullMeta.setOwningPlayer(player);
});

RecipeItem

RecipeItem, which directly inherits from Item, introduces only one feature: custom crafting recipes. While we will look later at how to create different recipes, it is worth nothing that this special implementation allows specifying as many recipes as the user desires, thanks to the setRecipes(Recipe[]) and addRecipes(Recipe[]) methods.

A RecipeItem can be created by copying the current item or by using Item#newRecipeItem.

BukkitRecipeItem

WARNING: by default, these will not be registrable. To actually register the recipes on the server and start using them, an instance of BukkitRecipeItem is required. This inherits from both RecipeItem and BukkitItem and provides actual uses for the methods registerRecipes and unregisterRecipes.

NOTE: a clearRecipes method is also present, which will delete all the previously set recipes. Doing so will NOT unregister them, so it is advised to manually unsubscribe all of them before proceeding.

RecipeItem recipeItem = BukkitItem.newRecipeItem("diamond_block").setRecipes(/* ... */);
recipeItem.registerRecipes();
/* ... */
recipeItem.unregisterRecipes();
recipeItem.clearRecipes();

PersistentItem

WARNING: this section requires the bukkit module to be imported.

The PersistentItem is a special type of item that, once in the player inventory, it cannot be moved, dropped or given. Instead, the developer can choose actions for click or interact events, as well as behaviours in the player's inventory and upon death.

A PersistentItem can be directly created using its constructor, or by copying it from an Item (useful when loading from configuration files). Once created, it can always be retrieved by its corresponding ItemStack using PersistentItem#getPersistentItem(ItemStack).

Here is a list of useful methods provided by this implementation:

• setMobility(Mobility): uses Mobility to specify if the item should be movable inside the player's inventory or totally static;
• setDeathAction(DeathAction): uses DeathAction to specify if, upon the player's death, the item should disappear or be respawned;
• onClick(ClickItemAction): executes the given action upon the InventoryClickEvent being called. It supplies:
  • the Player that clicked;
  • the PersistentItem in the form of ItemStack;
  • the ClickType.
• onInteract(InteractItemAction): executes the given action upon the PlayerInteractEvent being called. It supplies:
  • the Player that interacted;
  • the PersistentItem in the form of ItemStack;
  • the Action.

NOTE: in order for the PersistentItem to work properly, it is mandatory to register PersistentListener in the onEnable plugin method.