Custom Items

Now that the new Red Diamond material has been defined, it will be necessary to define the Red Diamond Item.  The Red Diamond Item will use the Red Diamond tool material.  The Red Diamond Item will be what players will see in the game.  It will be dropped by an ore block, and it will be used to craft tools and weapons, with all of the amazing powers that were given to the tool material. 

However, before going into the specifics of our Red Diamond Item, let’s discuss custom items in general.  Any custom item that you create will need to follow the same pattern:

  1. Create a new class that is a subclass of net.minecraft.item.Item or one its child subclasses (e.g. ItemSword)
  2. Define the properties associate with your new item in the new class
  3. Create a texture for the item
  4. Instantiate and register your item in the base mod class

Next, we need to turn our attention towards the properties that go into the custom items.  These are:

  • —  Item ID (itemID) – 256 to 32,000, but 0 to 2267 are used by MC and unavailable
  • —  Max Stack Size (maxStackSize) – the number of this item that can be held, default is 64
  • —  Icon (itemIcon) – texture file to be displayed for this item, a 16×16 pixel PNG image on a transparent background
  • —  Internal Name (unlocalizedName) – a text string that is used internally by Minecraft to identify the item
  • —  External Name – a formatted text string that is shown for the item when in the game, internally stored in a global hashMap (LanguageRegistry.modLanguageData) that is keyed on the internal name
  • —  Creative Tab (tabToDisplayOn) – defines which tab the item will appear in

There are two general approaches used to set these properties.  The first would be chaining the list of setters together on the same line as the constructor.  This approach is used to define the default items in the Item class.  The second approach is to place the default values in the object itself and initialize those values in the constructor.  In keeping with good object-oriented principles, the second approach will be used in this tutorial.  The values will be defined as static class properties and the setters will called in the constructor, which will provide the benefit of making the item easier to maintain. 

The values that can be used for the Creative Tab have been pre-defined by Minecraft as a set of static variables, which map to the various tabs in a self-explanatory way.  These can be found in the CreativeTabs class and are:

  • tabBlock,
  • tabDecorations,
  • tabRedstone,
  • tabTransport,
  • tabMisc,
  • tabFood,
  • tabTools,
  • tabCombat,
  • tabBrewing, and
  • tabMaterials.

Note: all items will appear in the general tab by default.

The texture file will probably be the most difficult part of creating a custom item.  This needs to be a 16×16 pixel PNG, with a transparent background.  The transparent background is important, because otherwise your texture will not blend with the rest of the screen when it is rendered on the screen.  The general approach is to start with one of the existing Minecraft textures and then modifying that will a graphical editing tool.  I have found Gimp (http://www.gimp.org/) works quite well and it is free.  However, you can use whichever graphical editor you so desire. 

Finally, we can consider how to register the custom item.  Naturally, this will need to be done in the base mod class, which will make it available to Minecraft.  Fortunately, Forge has a good job of making this pretty easy by providing two convenient methods to this for us.  To register your new item it is two simple lines of code:

GameRegistry.registerItem()
LanguageRegistry.addName()

Custom Red Diamond Item

This is our new Red Diamond item.  First create a new class in the reddiamond.item Java package and give it the name RedDiamondItem.  Next, enter or copy the class code below into the newly created class.  

We are defining item information (id, internal and external names) in the object to comply with good object oriented practices.  We are starting with the id of 5000 to ensure it will not conflict with the Minecraft ids.  However, it may necessary to change this value, or make it dynamically set at runtime, especially if you are using a lot of other mods that also define custom items.  For now let's not worry about dynamically changing the id.  The internal name will need to be unique amongst all the items as well, and we are using the setUnlocalizedName() method which will be set in the constructor and is inherited from the superclass.  It is very important to not forget to set this property, because MC will get confused if you don't.  The external name is what people will see when playing in the game, and it can pretty much be whatever you want.  The external name will be used when the item is registered with the mod. 

Since our RedDiamond will be used to create tools and weapons, we will place it in the Materials tab.  You can only have it appear in one of the tabs, so give it some thought and put it in the appropriate place.  In this case, it is pretty obvious where it belongs, but sometimes it may not be so obvious. 

 

import reddiamond.RedDiamondInfo;

import cpw.mods.fml.relauncher.Side;
import cpw.mods.fml.relauncher.SideOnly;
import net.minecraft.client.renderer.texture.IconRegister;
import net.minecraft.creativetab.CreativeTabs;
import net.minecraft.item.Item;

public class RedDiamondItem extends Item {
    
    public static int id = 5000;
    public static String internalName = "itemRedDiamond";
    public static String externalName = "Red Diamond";

    public RedDiamondItem(int id) {
        super(id);
        setCreativeTab(CreativeTabs.tabMaterials);
        setUnlocalizedName(internalName);
    }
    
    @Override
    @SideOnly(Side.CLIENT)
    public void registerIcons(IconRegister iconRegister){
        itemIcon = iconRegister.registerIcon(
            RedDiamondInfo.MOD_ID + ":RedDiamond");
    }

}

 

For the registerIcons() method, the default behavior is to look in the default MC location for the texture file.  Unfortunately, this will not work for this item, because there is no default MC texture.  Fortunately, there is a standard approach to follow for textures.  Create a separate directory specific to our mod (named after our modid) and tell it which texture file to use.  The syntax used is “modid:texture”.  For the modid, we are using the constant from the RedDiamondInfo class.  For the texture file, this will be the name of the PNG file, created for the item.  The details of the texture configuration will be explained in the next section.

Also, notice the annotation @SideOnly() this is telling Minecraft to only call this method on the client side.  There is no point in trying to call this method on server side, since there is nothing to render there. 

Next, it is necessary to create an instance of the new item and register it with our mod, so that it will be available for use.  If you don’t do this, then your item will exist but never be available for use in the game.  Notice that the redDiamondItem was defined as public and static, which makes it easily accessible to other objects, like our ore block that will drop it.  Then once the new item has been defined, it will need to be registered in the load() method.  This code will need to placed in the RedDiamondMod class and will need to be in two places.  In addition, you will need to ensure that import statements are added for the RedDiamondItem, GameRegistry and LanguageRegistry classes.  

This will need to go at the top of the class where the other class properties are defined.  

public static Item redDiamondItem = new RedDiamondItem(
    RedDiamondItem.id);

This will need to replace the existing load() method, which was originally empty.  

@EventHandler
public void load(FMLInitializationEvent event) {
    GameRegistry.registerItem(redDiamondItem, 
        RedDiamondItem.internalName);
    LanguageRegistry.addName(redDiamondItem, 
        RedDiamondItem.externalName);
}

 

The GameRegistry.registerItem() will create a new entry in an internal HashMap used by MC in the GameData class, which will then define the item in a global name space, thus making it available everywhere in the game.  This line of code will need to entered into the load() method, so that it will be called when the mod is being initialized. 

The LanguageRegistry.addName() will associate the new item with an externally visible text string or name.  Note: this is where the uniqueness of the internal name becomes important, because MC uses the internal name to reference the item and make the name association. 

Custom Red Diamond Item Texture

The creation of your textures will probably be the most difficult and time consuming aspect of Red Diamond custom item.  The first thing you want to do is to create a temporary directory to create a copy of some existing PNG file to be able to make changes without damaging the original. 

The default Minecraft textures are in the assets directory under temp (i.e.: mcp\temp\src\minecraft\assets\minecraft\textures\items).  These were created during the decompile step that happened with the install of the Forge bundle.  Drill down to the items subdirectory and make a copy of the diamond.png or emerald.png file, and copy it to your temporary directory.  Next, open this with a graphical image editor and change the pixels to shades of red for your red diamond.  Save this as a 16×16 pixel PNG file, with a transparent background. 

Here is an example of the red shade changes that was made for the red diamond texture.  This started with the emerald.png, and then the different shades of green were changed into shades of red.  Each square is one pixel on the 16×16 pixel map.  The graphical editor used here was GIMP. 

red_dia_edit

 

Once the new texture file has been created, you will need to copy it to the location where Minecraft will be able to find it during game play.  This was defined when the registerIcons() method was overridden.  It will look in the assets directory for a subdirectory, named after the modid (in all lowercase letters), and then follow the path of textures/items, and then look for a file with the provided name, plus “.png”.  It is very important that both the directory and file name match exactly.  For example, the path and file for our custom items would be:

src\minecraft\assets\reddiamond\textures\items\RedDiamond.png

which would correspond to the string that was in configured in the registerIcons(), “reddiamond:RedDiamond”.

Once all of this has been done, you will be able to launch your MCP and be able to see the Red Diamond in the Materials tab.  Go ahead and click the run button again, launch Minecraft, enter a world in single player mode, and verify that the Red Diamond Item is available.