NOTE: This isn't really a serious draft of any kind. It was just made to demonstrate how an article would look like if translated to a simplified, controlled form of English (specifically, ASD-STE100 issue 8).

Adding a basic item is one of the first things to do when learning how to make a mod. To add an item, you must make an Item object, add it to the register, and give it a texture. To add more behavior to the item, it is necessary to make a custom Item class.

In all of the tutorials, the “tutorial” namespace is used as a placeholder. Replace this with your modid in your code. Names starting with “example” are also placeholders – replace these with sensible names in your code.

First, make an instance of Item and store it as a static final constant. You must also pass in a Item.Settings (or a FabricItemSettings) instance. This is used to set the item's properties – for example, its durability or its stack count.

public class ExampleMod implements ModInitializer {
 
    // an instance of our new item
    public static final Item EXAMPLE_ITEM = new Item(new FabricItemSettings());
    [...]
}

Then, you must add the item to the item register with the “register” method. This method is part of the vanilla registry system. Use the Registry#register() method with these arguments in this sequence:

• Registry Type, which is the register to add the item to
• Identifier, which is the identifier of the item
• Content, which is the item's properties.

You must call the method during initialization. The location of the method in your code is not important.

The identifier argument is made of two strings – the modid and the item's name. Pass in the constant you made in the first step as the content argument.

public class ExampleMod implements ModInitializer {
 
    // an instance of our new item
    public static final Item EXAMPLE_ITEM = new Item(new FabricItemSettings());
 
    @Override
    public void onInitialize() {
        Registry.register(Registries.ITEM, new Identifier("tutorial", "example_item"), EXAMPLE_ITEM);
    }
}

Your have added an item to Minecraft! Run the run config Minecraft Client or the runClient Gradle task to see it in action. You can use the command /give @s tutorial:example_item to get the item immediately.

You can also call the method when you make the constant in the first step. This can simplify the code.

public class ExampleMod implements ModInitializer {
 
    // an instance of our new item
    public static final Item EXAMPLE_ITEM =
      Registry.register(Registries.ITEM, new Identifier("tutorial", "example_item"),
        new Item(new FabricItemSettings()));
 
    @Override
    public void onInitialize() {
    }
}

To add a texture for the item, you must have an item model json file and a texture image. You must add these to your resource directory. The direct path of each is:

  Item model: .../resources/assets/tutorial/models/item/example_item.json
  Item texture: .../resources/assets/tutorial/textures/item/example_item.png

Our example texture can be found here.

If you added your item to the register correctly in the first step, your game will send a warning to the log similar to this:

  [Server-Worker-1/WARN]: Unable to load model: 'tutorial:example_item#inventory' referenced from: tutorial:example_item#inventory: java.io.FileNotFoundException: tutorial:models/item/example_item.json

It usefully tells you where the game expects your asset(s) to be found – when you are not sure that something is correct, look at the log.

A basic item model template is:

{
  "parent": "item/generated",
  "textures": {
    "layer0": "tutorial:item/example_item"
  }
}

The parent of your item changes how the item is rendered when held in the hand. Use “item/generated” for items that are held from the bottom center of the texture. Use “item/handheld” for tools that are held from the bottom left of the texture. The textures object is used to add texture files. Put the path of your texture file as the value for “layer0” in the format “[modid]:item/[item_name]”.

When you have applied the changes, your item will look like this:

To add more behavior to the item, it is necessary to create a custom Item class. You must pass in an Item.Settings object in the constructor.

public class ExampleItem extends Item {
 
    public ExampleItem(Settings settings) {
        super(settings);
    }
}

A custom item class can do many things. For example, this class tells the item make a sound when it is used.

public class ExampleItem extends Item {
 
    public ExampleItem(Settings settings) {
        super(settings);
    }
 
    @Override
    public TypedActionResult<ItemStack> use(World world, PlayerEntity playerEntity, Hand hand) {
        playerEntity.playSound(SoundEvents.BLOCK_WOOL_BREAK, 1.0F, 1.0F);
        return TypedActionResult.success(playerEntity.getStackInHand(hand));
    }
}

To add the changes to the game, replace the old Item object with an instance of your new custom item class

public class ExampleMod implements ModInitializer {
 
    // an instance of our new item
    public static final ExampleItem EXAMPLE_ITEM = new ExampleItem(new FabricItemSettings());
    [...]
}

If you completed all the steps correctly, the item will make a sound when it is used.

To change the maximum size of a stack of that item, use use maxCount(int size) inside FabricItemSettings. You cannot specify a maximum stack size if your item is damageable. If you do, 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 ExampleItem EXAMPLE_ITEM = new ExampleItem(new FabricItemSettings().maxCount(16));
    [...]
}

If you want to let the item be used as fuel in a furnace, you can add it to the FuelRegistry.

public class ExampleMod implements ModInitializer {
    [...]
 
    @Override
    public void onInitialize() {
        [...]
        FuelRegistry.INSTANCE.add(EXAMPLE_ITEM, 300)
    }
}

You can also add it to the CompostingChanceRegistry to make it compostable in a composter.

Add your item to your own ItemGroup.