This is an old revision of the document!
Table of Contents
Adding an Item
Introduction
Adding a basic item is one of the first steps in modding. You're going to need to create an Item
object, register it, and give it a texture. To add additional behavior to the item you will need a custom Item class. In this tutorial and all future ones, the “tutorial” namespace is used as a placeholder. If you have a separate modid, feel free to use it instead.
Registering an Item
First, create an instance of Item
. The constructor takes in an Item.Settings
(or a FabricItemSettings
unless versions since 1.20.5) instance, which is used to set item properties such as the durability, and stack count. For simplicity, we just do it in ExampleMod
class, and store them in static fields.
public class ExampleMod implements ModInitializer { // an instance of our new item // for versions below 1.20.4 public static final Item CUSTOM_ITEM = new Item(new FabricItemSettings()); // for versions since 1.20.5 public static final Item CUSTOM_ITEM = new Item(new Item.Settings()); [...] }
You'll use the vanilla registry system for registering new content. The basic syntax is Registry#register(Registry Type, Identifier, Content)
. Registry types are stored as static fields in the Registries
or Registry
class, and the identifier is what labels your content. Content is an instance of whatever you're adding. This can be called anywhere as long as it occurs during initialization.
For versions since 1.21, an Identifier
is created through Identifier.of(“namespace”, “path”)
. For versions below 1.21, it is created through new Identifier(“namespace”, “path”)
or new Identifier(“namespace:path”)
. It will fail if the namespace or path contains illegal characters.
Your new item has now been added to Minecraft. Run the run config
public class ExampleMod implements ModInitializer { // an instance of our new item public static final Item CUSTOM_ITEM = new Item(new Item.Settings()); @Override public void onInitialize() { // For versions below 1.21, please replace ''Identifier.of'' with ''new Identifier'' } }
Minecraft Client
or runClient
Gradle task to see it in action, execute the command /give @s tutorial:custom_item
in game.
For more simplicity, you can simplify your code by directly registering them when assigning the fields, as Register.register
will also return the registered object:
public class ExampleMod implements ModInitializer { // an instance of our new item public static final Item CUSTOM_ITEM = // For versions below 1.21, use ''new Identifier("tutorial", "custom_item")''. new Item(new Item.Settings())); @Override public void onInitialize() { } }
Best practice of registering items
In the code above, you simply created one item. However, it is not convenient if you have many items, as you need to register and create an Identifier
instance each time. Therefore, if you have many items in the mod, we can create a specific class to store item objects, such as ModItems
or TutorialItems
, and write a simple register
method to conveniently register items. You may also check vanilla Items
class to see how Minecraft completes it in a similar way.
public final class TutorialItems { private TutorialItems() {} // an instance of our new item public static final Item CUSTOM_ITEM = register(new Item(new Item.Settings()), "custom_item"); // For versions below 1.21, please replace ''Identifier.of'' with ''new Identifier'' } public static void initialize() { } }
Remember to refer to some method methods or fields in the mods initializes so as to statically load the class TutorialItems
.
public class ExampleMod implements ModInitializer { @Override public void onInitialize() { TutorialItems.initialize(); } }
Note: Some experienced users may decide to use reflection to automatically all static fields of a class. This is also a preferable way, but should be used with caution.
Adding Item textures
Registering a texture for an item requires an item model json file and a texture image. You're going to need to add these to your resource directory. The direct path of each is:
Item model: .../resources/assets/tutorial/models/item/custom_item.json Item texture: .../resources/assets/tutorial/textures/item/custom_item.png
Our example texture can be found here.
If you registered your item properly in the first step, your game will complain about a missing texture file in a fashion similar to this:
[Server-Worker-1/WARN]: Unable to load model: 'tutorial:custom_item#inventory' referenced from: tutorial:custom_item#inventory: java.io.FileNotFoundException: tutorial:models/item/custom_item.json
It conveniently tells you exactly where it expects your asset[s] to be found– when in doubt, check the log.
A basic item model template is:
{ "parent": "item/generated", "textures": { "layer0": "tutorial:item/custom_item" } }
The parent of your item changes how it's rendered in the hand and comes in useful for things like block items in the inventory. “item/handheld” is used for tools that are held from the bottom left of the texture. textures/layer0 is the location of your image file.
Final textured result:
Creating an Item class
To add additional behavior to the item you will need to create an Item class. The default constructor requires an Item.Settings
object.
public class CustomItem extends Item { public CustomItem(Settings settings) { super(settings); } }
A practical use-case for a custom item class would be making the item play a sound when you use it:
public class CustomItem extends Item { public CustomItem(Settings settings) { super(settings); } @Override public TypedActionResult<ItemStack> use(World world, PlayerEntity user, Hand hand) { user.playSound(SoundEvents.BLOCK_WOOL_BREAK, 1.0F, 1.0F); return TypedActionResult.success(user.getStackInHand(hand)); } }
Replace the old Item object with an instance of your new item class:
If you did everything correctly, using the item should now play a sound.
public final class TutorialItems { [...] // an instance of our new item public static final CustomItem CUSTOM_ITEM = new CustomItem(new Item.Settings()); [...] }
What if I want to change the stack size of my item?
For this you would use maxCount(int size)
inside Item.Settings
to specify the max stack size. Note that if your item is damageable you cannot specify a maximum stack size or the game will throw a RuntimeException.
public class ExampleMod implements ModInitializer { // An instance of our new item, where the maximum stack size is 16 public static final CustomItem CUSTOM_ITEM = new CustomItem(new Item.Settings().maxCount(16)); [...] }
Make your item become fuel, or compostable
If you want to make it a fuel so that it can be used in a furnace, you can register in FuelRegistry
when initializing the mod, for example:
public class ExampleMod implements ModInitializer { [...] @Override public void onInitialize() { [...] FuelRegistry.INSTANCE.add(TutorialItems.CUSTOM_ITEM, 300) } }
Similarly, you can use a CompostingChanceRegistry
to make it compostable in a composter.