The Ore Dictionary: Registering Items/Blocks To Alias To Minecraft
Many modders make custom blocks or items that they would like to behave similarly to vanilla blocks and items. To make this easy Forge provides an "ore dictionary". The OreDictionary class implements a system/registry which associates items/blocks with a string name (which can be same as vanilla types).
By default, Forge has changed out many of these default vanilla recipes to accept ore dictionary items.
Tip: For official documentation on the Ore Dictionary, see here.
Warning: The information in the link above is a bit out of date with respect to registration. It recommends registering Ore Dictionary in the pre-init handling method but now that there are separate registry events for blocks and items which fire after pre-init it means that you'd be registering ore dictionary entries before you register your actual blocks and items. So it is now recommended (confirmed by LexManos) that you should register ore dictionary in your item registry event handler after you register your actual items.
Tip: To see the list of vanilla ore dictionary names, look in the net.minecraftforge.oredict.OreDictionary class.
For example, wood planks are one of the items with an ore dictionary alias. So to register a new block or item that Minecraft will accept as a wood plank, simply put OreDictionary.registerOre("plankWood", yourBlockInstance); in your mods' method for handling the init life cycle event in your common proxy.
Registering Items/Blocks To Alias To Other Mods
Key Point: In addition to aliasing to the vanilla items, the ore dictionary also allows you to alias between other people's mods. For example, if you know a mod that has a "ingotCopper" registered in the ore dictionary, you could make your own version that would be treated the same in that mod's recipes provided you also register yours as "ingotCopper". Alternatively you can register other mods' ores to the dictionary.
Using Ore Dictionary As Recipe Ingredients
So what if you want to use something from the ore dictionary as input to a recipe? The recipe registration methods accept the ore dictionary name preceeded by a ":". For example:
mod.addRecipe("woodenBoots 1", 3, 2, ":woodPlank", "", ":woodPlank", ":woodPlank", "", ":woodPlank");
Using Ore Dictionary Elsewhere
Outside of recipes, wherever you have code that looks for a specific item/block you should consider comparing with the Ore Dictionary because that would maximize compatibility with other mods.
The OreDictionary class provides the getOres() method (which returns an ArrayList of ItemStacks). You then need to loop through that list and compare with whatever ItemStack you're interested in.
Note: You should use the version of the getOres() method that takes a String parameter.
To loop through the list and compare, OreDictionary has a method called containsMatch(). Unfortunately that method is private so you can't access it, but it is a simple method that you can just copy. Then you just pass in the ArrayList you got from the getOres() method, plus the ItemStack you're interested in.
Warning: The loop required for containsMatch() can be slow so try not to invoke it every tick if you can avoid it. For example, if you're interested in checking something the player is holding it is better to check it whenever something new is equipped rather than every tick.
Further Reading
These other tutorials can give you better idea of actual implementations with the ore dictionary:
So cool! Super thank you for writing this!
ReplyDelete