Skip to content

Adding an item

Overview

Our addon so far has only one class: AddonTemplate (or whatever you renamed it to). This class extends JavaPlugin and implements PylonAddon. There are some comments inside the class to explain what each part does - have a read through and try to understand how it works. Our addon doesn't actually do anything yet though - so let's add a new item!

Let's create an unbreakable diamond sword to start with.

To create a simple item, we only need two things: a key for the item, and an item stack.

Adding the item

Creating a key

NamespacedKeys are how Pylon identifies custom items, blocks, researches, entities, and more.

What are NamespaceKeys and why are we using them?

A key is just a simple piece of text, like pylonbase:copper_dust, which allows Pylon to uniquely identify your item. This is very similar to how vanilla Minecraft items have IDs. Why don't we just use copper_dust as the key? Well, what if two addons add an item called copper_dust? We won't be able to tell which one is which! To fix this, Pylon uses NamespacedKeys, which just means we take a string and your addon's name, and put them together - for example, my_addon:copper_dust.

To create a new NamespacedKey called 'epic_sword', we can do the following (inside onEnable): 

1
NamespacedKey epicSwordKey = new NamespacedKey(this, "epic_sword");

Creating the item stack

The second thing we need is an actual item. We'll use ItemStackBuilder for this.

ItemStackBuilder contains several different methods to help you create ItemStacks. For example, you can use .set(<component>, <value>) to set some of the item's values, like enchantments, whether the item is unbreakable, and so on.

Whenever you're creating a Pylon item, make sure you use ItemStackBuilder.pylonItem(<material>, <key>).

Why use ItemStackBuilder.pylonItem, and not any of the other ways to create an ItemStack?

There are others ways to create ItemStacks, but do not use these to create Pylon items. Under the hood, Pylon stores item keys in PersistentDataContainers, or PDCs (we'll cover them later in the tutorial - if you don't know what a PDC is, for now just imagine it as a simple way to store data inside an in-game item). When you call ItemStackBuilder.pylonItem and supply a key, that key is written to the item's PersistentDataContainer automatically. If you supply your own item stack, its PDC won't contain the item's key, and Pylon won't be able to differentiate that item with a regular Minecraft item.

ItemStackBuilder also sets the name and lore of the item to the default translation keys (which will be explained later in this tutorial).

To create an unbreakable diamond sword, you can do as follows: 

1
2
3
ItemStack epicSword = ItemStackBuilder.pylonItem(Material.DIAMOND_SWORD, epicSwordKey)
        .set(DataComponentTypes.UNBREAKABLE, Unbreakable.unbreakable())
        .build();

Registering the item

Now, we need to register our item with Pylon. This means we need to pass two things: the item stack, and the class that should be used to represent the item. We'll cover what this actually means (and how to make your own item classes) in the next tutorial, but for now, you can use the default PylonItem class: 

1
PylonItem.register(PylonItem.class, epicSword);

Adding the item to the guide

Since we've registered our item, it'll already show up in searches. However, we haven't added it to a page in the guide. Let's add the item to the 'combat' page in the guide. The combat page is added by Pylon base, and stored in the BasePages class. Adding a new item to it is very easy:

1
BasePages.COMBAT.addItem(epicSwordKey);

Putting it all together

Here's the complete code: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
    // Called when our plugin is enabled
    @Override
    public void onEnable() {
        instance = this;

        // Every Pylon addon must call this BEFORE doing anything Pylon-related
        registerWithPylon();

        NamespacedKey epicSwordKey = new NamespacedKey(this, "epic_sword");
        ItemStack epicSword = ItemStackBuilder.pylonItem(Material.DIAMOND_SWORD, epicSwordKey)
                .set(DataComponentTypes.UNBREAKABLE, Unbreakable.unbreakable())
                .build();
        PylonItem.register(PylonItem.class, epicSword);
        BasePages.COMBAT.addItem(epicSwordKey);
    }
Now let's test it out!