Tutorial ItemStacks and how to use them

Discussion in 'Resources' started by Reflxction, Aug 7, 2017.

Thread Status:
Not open for further replies.
  1. Offline


    Hello guys! I thank you from the heart of the pizza for dedicating some of your precious time to reading this.
    I've decided to make a post explaining every single thing I know about ItemStacks. I know that most of the developers know how to use them (for real, it's very easy to use them), but thought making this would be a good idea, since no one has made it before. Also, please try to read every note I mention, they will help you.

    Chapter 1: Creating an ItemStack

    Part I
    : What is an ItemStack?

    An ItemStack is an item (wow, so strange). However, it can be used to be more than a normal item. With ItemStacks, you can:
    1- Give the item a custom colorful name
    2- Add colorful lores (using ArrayLists)
    3- Add enchantments, and the ability to hide them
    4- Add NBT tags
    5- Anything else a normal item can have/do.

    Part II: Creating an ItemStack
    First, we need to create the ItemStack. Creating an ItemStack is similar to creating an Object in Java.
    ItemStack stick = new ItemStack(Material.STICK);
    (the material can be whatever you want)
    Now, we've created an ItemStack. We called it "stick", and it's now a Stick.

    For the list of Enums of the materials, visit https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html.

    Now, you might be asking: How can I give it more things? That's so boring mate!
    The answer is: We need to use an ItemMeta.

    Part III: What is an ItemMeta?
    An ItemMeta is what holds the information of the ItemStack. ItemMetas can hold names, lores, enchantments, etc.
    ItemMetas are very easy to use, and that will be covered now.

    Part IV: Creating an ItemMeta & giving the ItemStack a custom name
    First, we need to create an ItemMeta, and assign it to the ItemStack we've just created. To do this, we use:
    ItemMeta stickmeta = stick.getItemMeta();
    Now, after we've assigned the ItemMeta to the ItemStack, we can do whatever we want.

    Now, we want to give the ItemStack a special name. We don't directly give it a name. We give the ItemMeta a name.
    Sounds confusing, huh?
    Nah, trust me, it's not.
    stickmeta.setDisplayName(ChatColor.GREEN + "Harry Potter's Wand");
    Now, we've gave it a name. The name is "Harry Potter's Wand", and it's colored green. Easy, huh?

    Part V: Lores on ItemStacks
    Note: Before getting into this part, I assume you know ArrayLists and how to use them. If you do not know what ArrayLists are, I suggest you to do so, to avoid the "I don't know what I am doing, but it's working".

    First, we will create an ArrayList to store the text in the lore in. To do so:
    ArrayList<String> sticklore = new ArrayList<>();
    Fantastic! We've just created an ArrayList. Now, we will need to add the lore. We will store them inside the ArrayList.
    sticklore.add(ChatColor.BLUE + "Point me!");
    You can add more than 1-line lore, just by repeating the above line and changing the text.

    If you ever watched the Harry Potter movie, you'd know what does that mean xD

    Okay, all good now. There is a lore, but we did not give this lore to the ItemStack. We do not give it to the ItemStack, we give it to the ItemMeta.
    To do so, we use:
    Fantastic! Now the ItemStack has that lore. Beautiful, huh?

    Part VI: Enchantments

    ItemStacks also give you the ability to add enchantments to them. Cool, don't you think so?

    There are 2 ways to add the enchantments to the ItemStack:
    • Give the ItemStack the enchantment directly.
    • Give the ItemMeta the enchantment.
    They both are very easy, and I will be covering both of them in this part.
    But before, you should know, there are 2 types of enchantments:
    Safe and unsafe enchantments

    Safe enchantments are enchantments that do not go above the item's ability to hold enchantments, and it's possible to get them in vanilla Minecraft, and they have limits to the enchantment level.

    Example: Power 5 on a bow

    Unsafe enchantments are enchantments that go above the item's ability to hold enchantments, and it's impossible to get them in vanilla Minecraft.

    Example: Sharpness and Smite on a diamond sword (In vanilla Minecraft, you cannot add both sharpness and smite on a single sword)

    Another example: Sharpness 100 on a diamond sword

    Giving the ItemStack the enchantment:
    stick.addUnsafeEnchantment(Enchantment.KNOCKBACK, 5);
    Note: The stick cannot (logically) hold any enchantment, so we're using unsafe enchantments.
    If the ItemStack was a sword (for example), you will have to use the item#addEnchantment(Enchantment.<enchant>, <level>); method.

    Giving the ItemMeta the enchantment:
    Giving ItemMetas the enchantment is easier (and can be better), because:
    • The method name is shorter
    • You don't need to check if the enchantment is safe or unsafe
    • Gives you the ability to use ItemFlags (those will be covered in further parts)
    stickmeta.addEnchant(Enchantment.KNOCKBACK, 5, true);

    Wait, there is a new parameter, a boolean. What is it for?

    The boolean parameter stands for ignoreLevelRestriction. It's better to set it to true, so you can add unsafe enchantments.

    Yay! Now we have enchantments on our fancy item.

    Part VII: What is an ItemFlag and how to use it

    An ItemFlag is an addon to ItemMetas. ItemFlags give you the ability to hide specific flags in the ItemStack, such as:

    • Hide the enchantments of the ItemStack
    • Hide the attributes of the ItemStack
    • Hide the potion effects of the ItemStack
    • Hide the Unbreakable NBT tag
    • More (can be found in Javadocs)

    To add an ItemFlag to the ItemMeta:
    For the list of emums of ItemFlags:

    Part VIII: Giving the ItemStack an ItemMeta

    In previous parts, we've created an ItemMeta and gave it a lot of nice things, however, we never gave it to the ItemStack. 1 line will do this:

    Amazing! Now, we have finished the ItemStack and gave it a lot of nice things. But, where do we get this ItemStack from? Well, that's up to you! You can define this ItemStack wherever you want (in events/commands/methods), and then give it to the player.

    If the ItemStack was in an onCommand method, you use:
    ((Player) sender).getInventory().addItem(stick);

    If the ItemStack was in an EventHandler, you use:

    (In most of the events, there is a getPlayer() method. If there wasn't, it could be event#getWhoClicked() or such.)

    If the ItemStack was in a method, you use:
    public void giveItem(Player player) {
    Last edited: Aug 10, 2017
    AlvinB and Zombie_Striker like this.
  2. Offline


    Might want to take this out since you never show how to use NBT compounds. Not that new devs need to know about them...
    Other than that, great guide! ;)
    Reflxction likes this.
  3. Offline


    I've listed it to give them an idea, however NBT compounds require you to use packets, and I'm not really familiar with them. Once I am, I'll make sure they are included.
  4. Offline


    Chances are though that a new dev who would read this tutorial would only use ItemData, now that there are quite a few methods that do NBT for them, like setDisplayName()
    Reflxction and (deleted member) like this.
  5. Offline


    @xTechno_ Last time I checked, editing NBT values doesn't use packets? What exactly would you use packets for to create something completely serverside? In the end, you change it back to a org.bukkit.ItemStack so you can add it like a regular item. You may have been thinking of reflection? But that doesn't really make sense. If you need help with NBT/Reflection I can help, infact I've made a util on it (Many utils are made on it which you can scrap if needed)
    Reflxction likes this.
  6. @PenguinOwl is quite correct. Even though I have a quite nice NBTUtil, I have never needed to use it to add some vanilla property to an Item or Entity (although some cases does exist), only times I've really used it is to add a unique identifier to items and entities which save on reloads (this is actually the best way I know of to do this).

    Also, perhaps you should touch on type-specific Meta's such as SpawnEggMeta and the like. I think they are quite 'hidden' from view to the average developer because of the casting you have to do.
    PhantomUnicorns and Reflxction like this.
  7. Offline


    @PhantomUnicorns Oh, I must have misunderstood the NBT compounds. Thanks for correcting me, I'll make sure to take a look at those utils.

    @AlvinB I totally forgot about those. I will add them once I get the chance to. Thanks for notifying me!
Thread Status:
Not open for further replies.

Share This Page