Fabric Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Adding an Item ======

==== Introduction ====

Adding a basic item is one of the first steps in modding. You're going to need to create an ''<yarn class_1792>'' object, register it, and give it a texture. To add additional behavior to the item you will need a custom <yarn class_1792> 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 ''<yarn class_1792>'' and store it as a static final field. The constructor takes in an ''<yarn class_1792>.<yarn class_1793>'' (or a ''FabricItemSettings'' unless versions since 1.20.5) instance, which is used to set item properties such as the durability, and stack count. 

<yarncode java [enable_line_numbers="true"]>
public class ExampleMod implements ModInitializer {

    // an instance of our new item
    // for versions below 1.20.4
    public static final class_1792 CUSTOM_ITEM = new class_1792(new FabricItemSettings());
    // for versions since 1.20.5
    public static final class_1792 CUSTOM_ITEM = new class_1792(new class_1792.class_1793());
    [...]
}
</yarncode>

You'll use the vanilla registry system for registering new content. The basic syntax is ''<yarn class_2378>#<yarn method_10230>(Registry Type, <yarn class_2960>, Content)''. Registry types are stored as static fields in the ''<yarn class_7923>'' or ''<yarn class_2378>'' 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.

<yarncode java [enable_line_numbers="true"]>
public class ExampleMod implements ModInitializer {

    // an instance of our new item
    public static final class_1792 CUSTOM_ITEM = new class_1792(new class_1792.class_1793());

    @Override
    public void onInitialize() {
        class_2378.method_10230(class_7923.field_41178, new class_2960("tutorial", "custom_item"), CUSTOM_ITEM);
    }
}
</yarncode>
Your new item has now been added to Minecraft. Run the run config ''Minecraft Client'' or ''runClient'' Gradle task to see it in action, execute the command ''/give @s tutorial:custom_item'' in game.

{{:tutorial:2019-02-17_16.50.44.png?400|}}

For simplicity, you can simplify your code as following:
<yarncode java [enable_line_numbers="true"]>
public class ExampleMod implements ModInitializer {

    // an instance of our new item
    public static final class_1792 CUSTOM_ITEM =
      class_2378.method_10230(class_7923.field_41178, new class_2960("tutorial", "custom_item"),
        new class_1792(new class_1792.class_1793()));

    @Override
    public void onInitialize() {
    }
}
</yarncode>

==== 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 [[https://i.imgur.com/CqLSMEQ.png|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:
<code JavaScript>
{
  "parent": "item/generated",
  "textures": {
    "layer0": "tutorial:item/custom_item"
  }
}
</code>
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:

{{:tutorial:item_texture.png?400|}}

==== 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.
<yarncode java [enable_line_numbers="true"]>
public class CustomItem extends class_1792 {

    public CustomItem(class_1793 settings) {
        super(settings);
    }
}
</yarncode>

A practical use-case for a custom item class would be making the item play a sound when you use it:
<yarncode java [enable_line_numbers="true"]>
public class CustomItem extends class_1792 {

    public CustomItem(class_1793 settings) {
        super(settings);
    }

    @Override
    public class_1271<class_1799> method_7836(class_1937 world, class_1657 user, class_1268 hand) {
        user.method_5783(class_3417.field_14983, 1.0F, 1.0F);
        return class_1271.method_22427(user.method_5998(hand));
    }
}
</yarncode>

Replace the old <yarn class_1792> object with an instance of your new item class:
<yarncode java [enable_line_numbers="true"]>
public class ExampleMod implements ModInitializer {

    // an instance of our new item
    public static final CustomItem CUSTOM_ITEM = new CustomItem(new class_1792.class_1793());
    [...]
}
</yarncode>
If you did everything correctly, using the item should now play a sound.

==== 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.
<yarncode java [enable_line_numbers="true"]>
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 class_1792.class_1793().maxCount(16));
    [...]
}
</yarncode>

==== 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 use ''FuelRegistry'', for example:
<code java>
public class ExampleMod implements ModInitializer {
    [...]
    
    @Override
    public void onInitialize() {
        [...]
        FuelRegistry.INSTANCE.add(CUSTOM_ITEM, 300)
    }
}
</code>

Similarly, you can use a ''CompostingChanceRegistry'' to make it compostable in a composter.
==== Next Steps ====
[[tutorial:itemgroup|Add your item to your own ItemGroup]].