Skip to content

Creating and Registering Items

Jump to bottom
Christos Miniotis edited this page Apr 12, 2018 · 6 revisions

In order to create a Custom Item, you must first pick the Custom Item Type that you will be using, then create the Custom Item's Class and specify its properties, and, finally, register it during the initialization period. This page will contain all the info you need to do that.

Choosing the Custom Item Type

The Additions API contains individual classes that makes it easier to code for a specific Item Type. These are split up into two types: the plain Custom Items, which do not contain a texture, and the Textured Custom Items. All the classes that are available are the following:

Plain Custom Items Textured Custom Items
CustomItem CustomTexturedItem
CustomTool CustomTexturedTool
CustomArmor CustomTexturedArmor
CustomLeatherArmor CustomTexturedLeatherArmor
CustomBow CustomTexturedBow

Here's a detailed analysis of their abilities:

Custom Item

Using a Custom Item or Custom Textured Item, you can create simple items that do not fall into the other types of items. A good example of a Custom Textured Item is the Slime Bucket. The Slime Bucket is a Vanilla Additions Item that changes texture when you move in and out of a Slime Chunk. It is recommended that you use a Diamond Hoe as the base item if you wish to make a Custom Textured Item as it has many durability points to which textures can be assigned and doesn't have any abilities if you use setHoeAbilities(false).

Custom Tool

Using a Custom Tool or Custom Textured Tool you can create Swords, Axes, Pickaxes, Shovels, Hoes and any other type of weapon or tool that has attributes such as Attack Speed and Attack Damage. You will have to base your item off of an already existing tool in Vanilla Minecraft, such as a Diamond Sword. This Class makes it easier to create tools, as you can easily change the Attack Speed and Attack Damage by using addAttackSpeed(double) and addAttackDamage(double) methods respectively, that will be covered in detail in the item creation stage.

Custom Armor

Using these classes, you can create Custom Armor pieces. You will have to base your item off of an already existing armor piece in Vanilla Minecraft, such as a Diamond Chestplate. These classes also provide easy methods to change the Armor and Armor Toughness by using the addArmor(double) and addArmorToughness(double) methods respectively. WARNING: You cannot change the texture of the Custom Textured Armor! The only thing you can change is the texture of the icon. In order to get around this problem, you must use Custom Leather Armor and set a different color to give the illusion of a different texture.

Custom Leather Armor

Using these classes, you can create Custom Armor pieces that are based off of leather armor. These classes provide easy methods to change Armor and Armor Toughness, just like Custom Armor, but also provide a method to change the color of the Leather Armor by using setColor(color). WARNING: You cannot change the texture of the Custom Textured Armor! The only thing you can change is the texture of the icon. In order to get around this problem, you must set a different color to give the illusion of a different texture. The Additions API provides by default a resource pack that smooths out the Leather Armor Texture and will give a more realistic look to any armor that you create that has a different color. You cannot, however, hide the "Colored" text that Minecraft inserts into the the lore of the item.

Custom Bow

Using these classes, you can create Custom Bows and then use Custom Events to detect arrows shot by the Custom Bow. You can also use the Custom Textured Bow to add a textures to all 4 states of a bow.



Once you have chosen your Custom Item Type, you are ready to move on to creating the Custom Item itself.

Creating a Plain Custom Item

Custom Items can be created any way you want, either in line by using CustomItem cItem = new CustomItem() or by creating their own classes and extending CustomItem. I recommend the latter, as it allows you to check the instance of the Custom Item when using events and easily detect if a Custom Item is of a certain type.

First off, create your Custom Item Class. In this example, I'll call it the Tutorial Item. I'll make a package named items and create the TutorialItem.java class file inside of that package. Once the class is ready, add extends CustomItem to inherit all the Custom Item properties. Eclipse will inform you that there is an error, so add the constructor that Eclipse requires. It should end up looking like this:

public class TutorialItem extends CustomItem {

	public TutorialItem(Material material, int amount, short durability, String idName) {
		super(material, amount, durability, idName);
		// TODO Auto-generated constructor stub
	}

}

Since we will be specifying all of the Custom Item's properties in this class, go ahead and remove the Constructor's arguments. It should look like this:

public TutorialItem() {
	super(material, amount, durability, idName);
}

Now, you must specify the initial properties of the Custom Item. You will need to specify:

  • material: The Material upon which the Custom Item will be based. Keep in mind that the Custom Item will be inheriting the Material's abilities.

  • amount: The amount of items in the Item Stack when given in game. The Additions API is currently untested for any value other than 1, so please use 1 as your amount.

  • durability: How many durability points will be taken off the Material.

  • idName: The Unique ID that lets the API know which item is which. This must be similar to "plugin_name:item_name", just like Vanilla Minecraft uses minecraft:item_name for its items. It is recommended that all items from your plugin use the same plugin_name.


In my case, I will be using Material.WATCH for the material, 1 for the amount, (short) 0 for the durability and "tutorial_additions:tutorial_item" for the idName. In the end, it should look like this:

public TutorialItem() {
	super(Material.WATCH, 1, (short) 0, "tutorial_additions:tutorial_item");
}

At this point, you are free to do whatever you want with the item! There are many methods that you can use to change all kinds of properties of the Custom Item. For a full list and description of them, click here to visit the JavaDoc. I will be changing the name, the lore and I'll be adding a Fortune 3 enchantment, but you can do whatever you want! Here's how my code ended up looking like:

public TutorialItem() {
	super(Material.WATCH, 1, (short) 0, "tutorial_additions:tutorial_item");
	
	// Sets the Custom Item's name - it won't be in italic, it'll be plain white!
	setDisplayName("Timeman's Watch");
	// The CustomItem's lore - it has two lines and will be displayed in grey.
	setLore(Arrays.asList("This is an old watch", "made by Timeman's friend."));
	// This is a Fortune 3 Enchantment.
	addEnchantment(Enchantment.LOOT_BONUS_BLOCKS, 3);
}

Your Custom Item is ready! You might be interested in also adding a Recipe so that your players can craft the item. If so, choose the Custom Recipes tutorial on the right to check out how you can add Shaped Crafting Recipes, Shapeless Crafting Recipes and Furnace Recipes.

While your Custom Item is ready, the Additions API still doesn't know that it should load it. In order to tell it to do so, skip to the "Initializing the Custom Items" section below!

Creating a Textured Custom Item

Custom Textured Items are just like Custom Items (so if you skipped that part, go back and read it!), but also require a texture in a seperate zip file. Once again, start off by creating your class inside the items package, I'll be calling mine TutorialTexturedItem.java, and extending CustomTexturedItem. It should look like this:

public class TutorialTexturedItem extends CustomTexturedItem {

	public TutorialTexturedItem(DamageableItem dItem, String idName, String defaultTexture) {
		super(dItem, idName, defaultTexture);
		// TODO Auto-generated constructor stub
	}

}

Since we will be specifying all of the Custom Textured Item's properties in this class, go ahead and remove the Constructor's arguments. It should look like this:

public TutorialTexturedItem() {
	super(dItem, idName, defaultTexture);
}

Now, you must specify the initial properties of the Custom Textured Item. You will need to specify:

  • dItem: The Damageable Item upon which the Custom Textured Item will be based. This class contains some Enums that are similar to the Material class but can be used to create Custom Items as they are damageable, they have a durability values. To look at all the available Damageable Items, click here. <-- ADD THE LINK

  • idName: The Unique ID that lets the API know which item is which. This must be similar to "plugin_name:item_name", just like Vanilla Minecraft uses minecraft:item_name for its items. It is recommended that all items from your plugin use the same plugin_name.

  • defaultTexture: The name of the texture or model that your item will have. This will be used later on when making the resource pack. This should be the file name without the extension.


In my case, I will be using DamageableItem.DIAMOND_HOE for the dItem, "tutorial_additions:tutorial_textured_item" for the idName and "tutorial_textured_item" for the defaultTexture. In the end, it should look like this:

public TutorialTexturedItem() {
	super(DamageableItem.DIAMOND_HOE, "tutorial_additions:tutorial_textured_item", "tutorial_textured_item");
}

Before continuing with specifying any other of the Custom Textured Item's properties, it is recommended that you make the item unbreakable. In order for the item to obtain its Custom Texture without any issues, it shouldn't be able to change its durability value. Even though the API can handle a Custom Item that can be damaged, it is certainly not recommended.

You might also be interested in hiding the Unbreakable tag in the Custom Textured Item's lore. By default, Minecraft adds "Unbreakable" in the item's lore in a blue font, but can be hidden.

If you did both, it should look like this:

public TutorialTexturedItem() {
	super(DamageableItem.DIAMOND_HOE, "tutorial_additions:tutorial_textured_item", "tutorial_textured_item");
	
	// Makes the item unbreakable, so that the texture doesn't change
	setUnbreakable(true);
	// Removes the Unbreakable Tag from the Item's lore
	setUnbreakableVisibility(false);
}

You might have also noticed that I am using a Hoe as the base item. If you are looking to make simple Custom Textured Items that don't have any abilities by default, then you should consider using a Diamond Hoe and removing its default abilities. A Diamond Hoe has many durability points, so having multiple items or multiple textures should work just fine and you probably won't run out of durability points, but it also has very limited abilities. By default, when right clicked it plays a sound and tills the ground. However, this API provides a resource pack that contains some modified sound files, which maintain the Hoe's default abilities, but also let it disable the sound and its actions for Custom Items. In order to do so, you must add setHoeAbilities(false). In the end, it should look like this:

public TutorialTexturedItem() {
	super(DamageableItem.DIAMOND_HOE, "tutorial_additions:tutorial_textured_item", "tutorial_textured_item");
	
	// Makes the item unbreakable, so that the texture doesn't change
	setUnbreakable(true);
	// Removes the Unbreakable Tag from the Item's lore
	setUnbreakableVisibility(false);
	// Removes all of the Hoe's abilities and its sound
	setHoeAbilities(false);
}

At this point, you are free to do whatever you want with the item! There are many methods that you can use to change all kinds of properties of the Custom Item. For a full list and description of them, click here to visit the JavaDoc. I won't be changing anything this time, but if you want an example of what can be changed, check the Custom Item above.

Before moving on to the initialization, you must also add the resource pack that will be containing the Custom Item's texture.

First off, you must have your Texture or Model File ready. If you are using a texture, it must be in a square, 1:1 aspect ration and in .png format. If you haven't got a texture yet, then you can create one using tools such as Paint.NET and Photoshop. There are many tutorials on how to make textures for Minecraft online and I'll be making one myself with a few helpful files eventually. When that is done, it will be linked here.

Once you have your Texture or Model file ready, rename it to the defaultTexture that you specified earlier, without overriding the extension. So, in my case, it should be tutorial_textured_item.png. Make sure you don't put the extension twice, if you couldn't see an extension before renaming then don't add one afterwards!

You must now create the folders in which you will place the texture. Start by creating an assets folder. Within the assets folder, make a folder that will be named the same as your plugin_name that you used earlier for the ID Name. In my case, it will be tutorial_additions. Next, create within that folder a folder named textures and inside that folder, yet another one named items. Now, within the items, place your .png file that you prepared earlier. In my case, my file was placed in the following directories:

assets\tutorial_additions\textures\items\tutorial_textured_item.png

If you are using a Custom Model, you must also create a models folder within the textures folder, and place inside your model's json file, after renaming it to whatever you used for your defaultTexture.

Once you're done with adding all the files in the required folders, you can place the assets folder inside a zip file. To do that on Windows, right click on your assets folder, then hover your mouse over the Send To option and choose Compressed (zipped) folder from the menu that popped up. This will place everything in your assets folder within that zip file. Name the zip file however you want but keep it in mind as we will be using it later. I'll be naming it resource-pack.zip.

Finally, you can copy the generated zip file into your plugin's source code. Place it in the same directory as the plugin.yml file. In my case, since I'm using maven, I placed it in src/main/resources/resource-pack.zip.

If you're done with your Custom Item, then you can proceed to the initialization phase, where you will be telling the Additions API where the Resource Pack ZIP file is and which Custom Items it will load.

Creating Custom Tools

Custom Tools and Custom Textured Tools are exactly the same as all other Custom Items, so check out the previous sections but use the CustomTool and CustomTexturedTool classes respectively. However, there are a few methods you might want to keep in mind. Here are the ones that I use most of the time:

  • setFakeDurability(int) will add a Fake Durability Value to the Custom Item. This is to get around the Custom Item's Unbreakable tag, and adds text to the lore of the Custom Item to keep track of the durability, as well as a Boss Bar for ease of use. This method and its abilities will be covered in a later tutorial with more detail.
  • setEnchantable(true) will allow the Custom Tool to be enchanted using an Enchantment Table.
  • addAttackDamage(double) will add an Attribute to change the Attack Damage of the Custom Tool. However, the Attack Damage that you specify here should be the one that you see in the Item's lore by default in Vanilla Minecraft. So, for example, if you wanted the Attack Damage of a Diamond Sword, you would put 7D as the value.
  • addAttackSpeed(double) will add an Attribute to change the Attack Speed of the Custom Tool. However, the Attack Speed that you specify here should be the one that you see in the Item's lore by default in Vanilla Minecraft. So, for example, if you wanted the Attack Speed of a Diamond Sword, you would put 1.6D as the value.
  • setToolLikeAttribtues(true) will change the way that attributes are displayed in the Item's lore. Only use this if you changed the Attack Speed, Attack Damage or added an Attribute. By default, Vanilla Minecraft has a different style of text for Attributes and a different style of text for the Attack Damage and Attack Speed in tools. This method will add to the lore of the Custom Item the text that users expect to see in Tools from the game, and it will even work for Attributes other than Attack Speed and Attack Damage.
  • setAttributeVisibility(false) will remove the default attribute style of text that I mentioned above. Don't forget to use this if you used setToolLikeAttribtues(true), otherwise you'll have twice the Attribute lore!

Initializing the Resource Pack and the Custom Items

Once you have your Custom Items and their resource pack, if any, ready, you are ready to move on to the initialization phase. Here, you'll be telling the Additions API where your Resource Pack ZIP File is and which Custom Items it should load.

Start off by creating a Class where you'll be implementing Listener, then register it in your main class. If you haven't done so already, then you skipped the Setting up your workspace tutorial, so go ahead and follow that to create and register the class. In my case, I called the class Items.java. Within that class, you must create a listener that listens for the Additions API initialization. Your code should look like this:

public class Items implements Listener {

	@EventHandler
	public void onInitialization(AdditionsAPIInitializationEvent event) {
		
	}
	
}

If your Custom Items require a Resource Pack, then you can tell the Additions API where it is by using the addResourcePackFromPlugin method. This will require an instance of your plugin, so if you haven't already configured that in your main class by following the Setting up your workspace tutorial, then do it now. In my case, this is the code I used:

@EventHandler
public void onInitialization(AdditionsAPIInitializationEvent event) {
	event.addResourcePackFromPlugin(TutorialAdditions.getInstance(), "resource-pack.zip");
}

The first argument in the method specifies the plugin that contains the resource pack, while the second argument is the Resource Pack ZIP File's File Name.

Once you're done with your Resource Pack, you can register your Custom Items. To do so, you must use the addCustomItem method to create a new instance of the Custom Item and add it to the initialization sequence. Since I have two Custom Items that I want to initialize, my code looks like this:

@EventHandler
public void onInitialization(AdditionsAPIInitializationEvent event) {
	event.addResourcePackFromPlugin(TutorialAdditions.getInstance(), "resource-pack.zip");
	
	event.addCustomItem(new TutorialItem());
	event.addCustomItem(new TutorialTexturedItem());
}

And that should be it! Package your plugin and add it to the plugins folder.

IMPORTANT: When you are developing your plugin, make sure that you change the debug option in the Additions API config from false to super. This way, the Resource Pack will regenerate every time you launch the server and will also provide you with useful information about your items.

Before you start

Creating and editing Custom Items

Tutorials made by other people

Clone this wiki locally