Minecraft Tutorials: The Ore Dictionary

Time for another installment of my tutorial series on modding Minecraft.  This time I will discuss using the ore dictionary provided by Forge.

This tutorial will assume that you understand how to create a block or item, and how to add a new crafting recipe to your mod.  The code examples I present are from code written as this series progresses, so some of my code my be different from yours, unless you're following the whole series.

Anywho, suppose you have this mod, to which you've added a new ore, gem, type of wood, or what have you.  For example in this series we added copper.  There are a metric ton of mods that add copper as an ore.  Wouldn't it be nice if our copper ingots worked in there recipes and their copper ingots worked in ours?  This is where the ore dictionary comes in.  The ore dictionary stores a map of different ores, gems, etc, that are registered with the same String name and allows modders to add shaped and shapeless recipes using String names instead of ItemStacks.  With this you can make your mod's ores and other items compatible with other mods you don't even know exist!  Without it adding that kind of compatibility would require extra code for any and every mod you thought might maybe be used at the same time as your mod!

Before we get started there one important thing you should know: the ore dictionary relies on modders all following the same naming convention when registering their ores to the dictionary.  This convention is typeName for example oreCopper, ingotCopper, gemSapphire, dustGold, etc.
There's a nice article on common names in the ore dictionary on the Forge wiki and I highly recommend taking a look at it.

Now that we get how useful it is, let's use it.  I'll use the copper ore and ingot we created in previous tutorials for these examples.  First we want to make it possible for other mods to use our copper in their recipes.  I will do this with a call to the registerOre method from the OreDictionary class, which takes two parameters, a String name which ought to follow the convention I mentioned earlier, and an Item or Block which is the ore, or ingot or whatever that we are registering.  I am placing this call in ModItems.init() for the copper ingot and ModBlocks.init() for copper ore.  You could also place them directly in the preInit method of your main mod class.  My ModItems and ModBlocks classes now look like this (changes are highlighted):

package me.codasylph.grindermod.items;

import cpw.mods.fml.common.registry.GameRegistry;

import net.minecraft.item.Item;

import net.minecraft.item.Item.ToolMaterial;

import net.minecraftforge.common.util.EnumHelper;

import net.minecraftforge.oredict.OreDictionary;

public class ModItems

{

       public static ToolMaterial COPPER = EnumHelper.addToolMaterial("COPPER", 2, 160, 8.0F, 1.0F, 10);

      

       public static Item copperIngot = new CopperIngot();

       public static Item copperPickaxe = new CopperPickaxe();

       public static Item copperAxe = new CopperAxe();

       public static Item copperShovel = new CopperShovel();

       public static Item copperHoe = new CopperHoe();

       public static Item copperSword = new CopperSword();

      

       public static void init()

       {

              GameRegistry.registerItem(copperIngot, copperIngot.getUnlocalizedName());

              GameRegistry.registerItem(copperPickaxe, copperPickaxe.getUnlocalizedName());

              GameRegistry.registerItem(copperAxe,copperAxe.getUnlocalizedName());

              GameRegistry.registerItem(copperShovel,copperShovel.getUnlocalizedName());

              GameRegistry.registerItem(copperHoe,copperHoe.getUnlocalizedName());

              GameRegistry.registerItem(copperSword,copperSword.getUnlocalizedName());

             

              OreDictionary.registerOre("ingotCopper", copperIngot);

       }

}

package me.codasylph.grindermod.blocks;

import cpw.mods.fml.common.registry.GameRegistry;

import net.minecraft.block.Block;

import net.minecraftforge.oredict.OreDictionary;

public class ModBlocks

{

       public static Block copperOre = new CopperOre();

      

       public static void init()

       {

              GameRegistry.registerBlock(copperOre, copperOre.getUnlocalizedName());

             

              OreDictionary.registerOre("oreCopper", copperOre);

       }

}

Our copper ingots and ore can now be used in other mods recipes (assuming they actually use the ore dictionary, most do).  If you would like to test this you could either build the mod and install it with other forge compatible mods or if you're using eclipse, place another mod's jar file in the eclipse/mods folder and run your testing environment.  *You may also need to include something like CodeChickenCore if you get errors because the mod is obfuscated.

We're halfway done.  Now we want to be able to use other mods' copper in our recipes.  This we do with a call to the method GameRegistry.addRecipe.  addRecipe() takes one parameter that is an instance of IRecipe, the ore dictionary adds two new classes ShapedOreRecipe and ShapelessOreRecipes which both implement IRecipe.  Conveniently these two classes also take the same parameters as GameRegistry.addShapedRecipe and GameRegistry.addShapelessRecipe respectively, except that they can take a String name of an ore in place of an ItemStack. The line to add a our copper pickaxe would therefore be this:

GameRegistry.addRecipe(new ShapedOreRecipe(new ItemStack(ModItems.copperPickaxe), new Object[]{"CCC"," S "," S ",'C', "ingotCopper", 'S', stickStack}));

Since vanilla items are part of the ore dictionary I could even replace stickStack with "stickWood" allowing sticks from mods to work in this recipe.  Lastly, since our copper ingot is registered to the dictionary, I can remove the recipe I made in Crafting and Smelting Recipes as this one is sufficient.  Having done all that my ModRecipes class now looks like this: 

package me.codasylph.grindermod;

import me.codasylph.grindermod.blocks.ModBlocks;

import me.codasylph.grindermod.items.ModItems;

import net.minecraft.init.Blocks;

import net.minecraft.init.Items;

import net.minecraft.item.ItemStack;

import net.minecraftforge.oredict.OreDictionary;

import net.minecraftforge.oredict.ShapedOreRecipe;

import cpw.mods.fml.common.registry.GameRegistry;

public class ModRecipes

{

       private static ItemStack copperIngotStack =  new ItemStack(ModItems.copperIngot);

       private static ItemStack stickStack =  new ItemStack(Items.stick);

      

       public static void init()

       {

              //Shapeless Recipes

              GameRegistry.addShapelessRecipe(new ItemStack(Items.slime_ball), new ItemStack(Items.dye,1,10), new ItemStack(Items.egg), new ItemStack(Items.sugar));

              //Shaped Recipes

              GameRegistry.addRecipe(new ShapedOreRecipe(new ItemStack(ModItems.copperPickaxe), new Object[]{"CCC"," S "," S ",'C', "ingotCopper", 'S', stickStack}));

             

              //Smelting Recipes

              GameRegistry.addSmelting(ModBlocks.copperOre, copperIngotStack, 0.5F);

       }

}

A final thought, there's still more functionality in the ore dictionary than what was covered here.  I highly recommend checking out the declaration of OreDictionary, it is extremely useful and also extremely well commented!

To return to the table of contents click here.

Minecraft Tutorials: Crafting And Smelting Recipes

Another Minecraft modding tutorial.  In this tutorial I will discuss adding your own crafting and smelting recipes to a mod.  This tutorial assumes an understanding of block and item creation, as well as the main mod file.  As always, the code I'll be showing is built on code from all the tutorials thus far, and if you haven't been following allow exactly, your code is going to be a little bit different.

Minecraft has three standard types of recipes: Shapeless, Shaped, and Smelting. I'll go over each of them in turn, but first I'll make a class to handle all of them.  Let's call it ModRecipes and place it in the main mod package. All of our recipes will be registered in a new init() method.  Right now my ModRecipes class looks like this:

package me.codasylph.grindermod;

public class ModRecipes

{

       public static void init()

       {

             

       }

}

At this point we should also go ahead and call ModRecipes.init() in the init() method of the main mod class so that we can test the recipes as we go. For reference my main mod class looks like this now:

package me.codasylph.grindermod;

import me.codasylph.grindermod.blocks.CopperOre;

import me.codasylph.grindermod.blocks.ModBlocks;

import me.codasylph.grindermod.items.ModItems;

import cpw.mods.fml.common.Mod;

import cpw.mods.fml.common.event.FMLInitializationEvent;

import cpw.mods.fml.common.event.FMLPostInitializationEvent;

import cpw.mods.fml.common.event.FMLPreInitializationEvent;

import cpw.mods.fml.common.registry.GameRegistry;

@Mod(modid = "grindermod", name = "Grinder Mod", version = "1.0")

public class GrinderMod

{     

       @Mod.EventHandler

       public void preInit(FMLPreInitializationEvent event)

       {

              GameRegistry.registerWorldGenerator(new WorldGenGinderMod(), 0);

              ModBlocks.init();

              ModItems.init();

       }

       @Mod.EventHandler

       public void init(FMLInitializationEvent event)

       {

              ModRecipes.init();

       }

       @Mod.EventHandler

       public void postInit(FMLPostInitializationEvent event)

       {

             

       }

}

Now then, recipes! Actually first: ItemStacks

The way Minecraft works there's only one instance of a given Item.  You register that instance and it is the only instance of that item. What you end up with in your inventory is an ItemStack.  An ItemStack is a separate class with several properties, including what it's a stack of and how big it is. The constructor takes three parameters, an Item, an int that determines the size, and finally an int that determines the damage on the item (also known as the meta data). The constructor is overloaded so you may also pass just the Item for a stack of one undamaged item, or the Item and the size for a stack of the given size in which the items are undamaged. You can have an ItemStack of item. More importantly can and will have many many instances of the ItemStack class, include many stacks with the same item.  ItemStacks have more properties but none we need to understand right now.

So now the recipes!

Shapeless recipes are those that require a amount of certain items to be placed in a crafting grid to produce a given item, but the arrangement doesn't matter.  Vanilla examples of shapeless recipes include turning a block of iron or gold into nine ingots or turning dye and a block of wool into wool of that color.  In this example I will add a shapeless recipe that makes a slime ball out of an egg, some sugar, and lime dye.  The line looks like this:

GameRegistry.addShapelessRecipe(new ItemStack(Items.slime_ball), new ItemStack(Items.dye,1,10), new ItemStack(Items.egg), new ItemStack(Items.sugar));

addShapelessRecipe takes a variable number of parameters of the type ItemStack.  The first parameter dictates the output and all the following parameters dictate the ingredients. If you run your testing environment at this point you should be able to throw lime dye, an egg, and a pile of sugar in to a crafting grid and get yourself a brand spanking new ball o' slime.  Yum! :p

Shaped recipes require items in a specified arrangement on the crafting grid to produce a particular product.  Vanilla examples include all the the tools in Minecraft.  In this example I will add a shaped recipe that uses sticks and the copper ingot we created in A Basic Item to create the pickaxe we created in A Basic Tool. It will look like this:

GameRegistry.addShapedRecipe(new ItemStack(ModItems.copperPickaxe), new Object[]{

       "CCC",

       " S ",

       " S ", 'C', new ItemStack(ModItems.copperIngot), 'S', new ItemStack(Items.stick)});

This takes two parameters (kinda), the first is the output.  The second is an array of Objects with the recipe.  The first three objects are strings of three characters each, that represent each row the the crafting grid. The remaining objects are the characters and what ItemStack they represent. Spaces always mean any empty slot and do not need to be defined. 

Here's another example that makes a vanilla furnace out of sandstone instead of cobblestone.

GameRegistry.addShapedRecipe(new ItemStack(Blocks.furnace), new Object[]{

       "SSS",

       "S S",

       "SSS", 'S', new ItemStack(Blocks.sandstone)});

Again you should be able to try either of these recipes out in the testing environment now.

Smelting recipes are those that convert one Item or Block into another inside a furnace.  Presumably by the judicious application of heat.  Most smelting recipes are of the ore into ingot variety, but other vanilla examples include turning logs into charcoal or raw food into cooked food. In this example I will add a smelting recipe to turn the copper ore we created in A Basic Block into the ingot we made in A Basic Item. The line looks like this:

GameRegistry.addSmelting(ModBlocks.copperOre, new ItemStack(ModItems.copperIngot), 0.5F);

This method takes three parameters, unlike the previous methods the first parameter is the input instead of the output, and may be an instance of Block, Item, or ItemStack.  The second parameter is the output and must be and instance of ItemStack.  The final parameter is a float that dictates how much experience the player receives for smelting the item.  0.5 is slightly less than the amount received for smelting iron and a little more than that received for cooking a food item.

A final thought, you'll notice we used ModItems.copperIngot several times, if we went in and added shaped recipes for all the copper tools we'd use it quite a few more times.  It can be beneficial, there for, to declare an instance of ItemStack for each item you'll be using in multiple recipes so you're not calling the constructor over and over again for no reason.  After taking this advice my ModRecipes class looks like this:

package me.codasylph.grindermod;

import me.codasylph.grindermod.blocks.ModBlocks;

import me.codasylph.grindermod.items.ModItems;

import net.minecraft.init.Blocks;

import net.minecraft.init.Items;

import net.minecraft.item.ItemStack;

import cpw.mods.fml.common.registry.GameRegistry;

public class ModRecipes

{

       private static ItemStack copperIngotStack =  new ItemStack(ModItems.copperIngot);

       private static ItemStack stickStack =  new ItemStack(Items.stick);

      

       public static void init()

       {

              //Shapeless Recipes

              GameRegistry.addShapelessRecipe(new ItemStack(Items.slime_ball), new ItemStack(Items.dye,1,10), new ItemStack(Items.egg), new ItemStack(Items.sugar));

              //Shaped Recipes

              GameRegistry.addShapedRecipe(new ItemStack(ModItems.copperPickaxe), new Object[]{

                     "CCC",

                     " S ",

                     " S ", 'C', copperIngotStack, 'S', stickStack});

             

              //Smelting Recipes

              GameRegistry.addSmelting(ModBlocks.copperOre, copperIngotStack, 0.5F);

       }

}

That's all folks!  To return to the table of contents click here.

Minecraft Tutorials: Adding To World Generation

This is a continuation of the my minecraft modding tutorial.  In this post I'll discuss how to add a new ore to world generation.  This tutorial assumes you are at least familiar with creating a basic mod file, and creating a block.  The code I will be showing is built on all of my previous tutorials so if you haven't been following along your code may be slightly different, which is ok.

If you have been following along, you'll remember that in our block tutorial we created a copper ore block, but up until now we've had no way to obtain this block other than in creative mode, or through cheat commands.  Now we will add a WorldGenerator which will cause our copper ore to spawn naturally in the world. To do this I will create a new class that implements the interface IWorldGenerator. Since this is likely the only WorldGenerator we will have in our mod I will place it in my main mod package, but if you had other classes that affected world generation, such as new biomes, you might put it in a world sub-package or something.

I'll name my class WorldGenGinderMod. At this point I have an error because I must implement an inherited method called generate.  My generate method looks like this:

@Override

public void generate(Random random, int chunkX, int chunkZ, World world, IChunkProvider chunkGenerator, IChunkProvider chunkProvider)

{

       switch(world.provider.dimensionId)

       {

       case 0:

              break;

       case 1:

              break;

       case -1:

              break;

       default:

              break;

       }

      

}

The switch statement takes the dimensionid of the current world provider, we will be using the 0 case only, because 0 is the id for the Overworld. If we wanted to generate in the Nether we would use -1, or 1 for the end.  If we had our own custom dimension it would have its own unique id that we could use.  Techinically, we could forgo the switch statement all together because the way we will generate our ore is by replacing stone blocks, but using this switch prevents our code from running when it definitely isn't needed.

Before adding any more code to generate() I'm going to write another method that does the generating, this way if we wanted to reuse the method for other things, like generating a different ore, we could do so without repeat code.  This method will be called generateOre, and it is a bit more complex than any code I've discussed so far, so please bear with me.  It looks like this:

private void generateOre(Block newBlock, Block oldBlock, World world, Random random, int blockPosX, int blockPosZ, int minVeinSize,

              int maxVeinSize, int spawnChance, int minY, int maxY )

{

        WorldGenMinable minable = new WorldGenMinable(block, (minVeinSize + random.nextInt(maxVeinSize - minVeinSize)), Blocks.stone);

        int posX;

        int posY;

        int posZ;

        

     for(int i = 0; i < spawnChance; i++)

     {

         posX = blockPosX + random.nextInt(16);

         posY = minY + random.nextInt(maxY - minY);

         posZ = blockPosZ + random.nextInt(16);

         minable.generate(world, random, posX, posY, posZ);

     }

}

This method takes a *ton* of parameters, but names should be fairly self explanatory, so lets jump in to what it's actually doing. 

First we add a WorldGenMinable object, this is what actually does the replacing of stone with our copper ore.  Its constructor takes three parameters, the block we want to have spawn, the number of blocks to replace, and the block we are replacing. I pass newBlock to the first parameter, and oldBlock to the third parameter. Since we want the amount of blocks in a vein to be kind of random, we use (minVeinSize + random.nextInt(maxVeinSize - minVeinSize)) to generate a random number between our minimum and maximum vein sizes and pass this to the second parameter. If later we want to have generate ore with a fixed vein size we can do this by making the minVeinSize and maxVeinSize parameters equal.

Next we declare some ints for use in our for loop.  The for loop increments through until it reaches the spawnChance we passed, so it will continue to run longer for higher values of spawnChance.  In the loop we generate some semi-random coordinates and then pass them to the generate method of our WorldGenMinable object minable, this method will do all the replacing, and thankfully someone else has already written it for us so we don't even have to look at it! If you would like to see the declaration and you are using eclipse you can highlight it and hit F3, I warn you, it is a lot of maths.

Now we want to come back to *our* generate() method and add a call to our new method under case 0:

this.generateOre(ModBlocks.copperOre, Blocks.stone, world, random, chunkX*16, chunkZ*16, 10, 15, 10, 0, 90);

We pass ModBlocks.copperOre in the first parameter, since this is the new block we want to have spawn. We are replacing Blocks.stone, so its only going to spawn in stone, then we pass the world and a our random object (no sense in generating another one), multiplying chunkX and chunkZ by 16 converts them from chunk coordinates to block coordinates. Next we pass our min and max vein sizes, 10 and 15 will make our veins about the size of a vein of coal.  We pass 10 for our chance to spawn, and then the last two parameters dictate what y levels our ore will spawn, 0 to 90 means that it will spawn down until it reaches bedrock and up to a height of 90, so it will be seen in some mountain ranges.

My whole WorldGenGrinderMod class looks like this:

package me.codasylph.grindermod;

import java.util.Random;

import me.codasylph.grindermod.blocks.ModBlocks;

import net.minecraft.block.Block;

import net.minecraft.init.Blocks;

import net.minecraft.world.World;

import net.minecraft.world.chunk.IChunkProvider;

import net.minecraft.world.gen.feature.WorldGenMinable;

import cpw.mods.fml.common.IWorldGenerator;

public class WorldGenGrinderMod implements IWorldGenerator {

       @Override

       public void generate(Random random, int chunkX, int chunkZ, World world, IChunkProvider chunkGenerator, IChunkProvider chunkProvider)

       {

              switch(world.provider.dimensionId)

              {

              case 0:

                     this.generateOre(ModBlocks.copperOre, Blocks.stone, world, random, chunkX*16, chunkZ*16, 10, 15, 10, 0, 90);

              case 1:

                     break;

              case -1:

                     break;

              default:

                     break;

              }

             

       }

       private void generateOre(Block newBlock, Block oldBlock, World world, Random random, int blockPosX, int blockPosZ, int minVeinSize,

                     int maxVeinSize, int spawnChance, int minY, int maxY )

       {

               WorldGenMinable minable = new WorldGenMinable(newBlock, (minVeinSize + random.nextInt(maxVeinSize - minVeinSize)), oldBlock);

               int posX;

               int posY;

               int posZ;

               

            for(int i = 0; i < spawnChance; i++)

            {

               posX = blockPosX + random.nextInt(16);

                posY = minY + random.nextInt(maxY - minY);

                posZ = blockPosZ + random.nextInt(16);

                minable.generate(world, random, posX, posY, posZ);

            }

       }

}

If later I wanted to add different ore I would just make another call to generateOre under the case for the dimensionId I wanted it to spawn in.

Last, but certainly not least, I need to register my WorldGenerator, this will be done in the main mod class.  You could make a separate class that handles this, but because most mods will only have one WorldGenerator there isn't as much of a reason to do so. I will just add a call to the registration method in my preInit.  The line looks like this:

GameRegistry.registerWorldGenerator(new WorldGenGinderMod(), 0);

It takes two parameters, an object that implements IWorldGenerator, and a weight, the weight determines when the generator will run, the higher the number the later they run.

Now if you run the testing environment you should be able to track down some copper ore! Please note that chunks that have already been generated prior to adding this code won't contain any ore, you'll have to create a new world or at least generate new chunks to find the ore.

Next tutorial? Recipes!

You may return to the table of contents here.