User Tools

Site Tools


Sidebar

← Go back to the homepage

Fabric Tutorials

Setup

Basics

These pages are essential must-reads when modding with Fabric, and modding Minecraft in general, if you are new to modding, it is recommended you read the following.

Items

Blocks and Block Entities

Data Generation

World Generation

Commands

These pages will guide you through Mojang's Brigadier library which allows you to create commands with complex arguments and actions.

Events

These pages will guide you through using the many events included in Fabric API, and how to create your own events for you or other mods to use.

Entities

Fluids

Mixins & ASM

These pages will guide you through the usage of SpongePowered's Mixin library, which is a highly complex topic. We recommend you read these pages thoroughly.

Miscellaneous

Yarn

Contribute to Fabric

tutorial:items

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 and store it as a static final field. The constructor takes in an Item.Settings (or a FabricItemSettings) instance, which is used to set item properties such as the inventory category, durability, and stack count.

  1. public class ExampleMod implements ModInitializer {
  2.  
  3. // an instance of our new item
  4. public static final Item CUSTOM_ITEM = new Item(new FabricItemSettings().group(ItemGroup.MISC));
  5. [...]
  6. }

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 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.

  1. public class ExampleMod implements ModInitializer {
  2.  
  3. // an instance of our new item
  4. public static final Item CUSTOM_ITEM = new Item(new FabricItemSettings().group(ItemGroup.MISC));
  5.  
  6. @Override
  7. public void onInitialize() {
  8. Registry.register(Registry.ITEM, new Identifier("tutorial", "custom_item"), CUSTOM_ITEM);
  9. }
  10. }
Your new item has now been added to Minecraft. Run the run config ``Minecraft Client`` or runClient Gradle task to see it in action.

For simplicity, you can simplify your code as following:

  1. public class ExampleMod implements ModInitializer {
  2.  
  3. // an instance of our new item
  4. public static final Item CUSTOM_ITEM =
  5. Registry.register(Registry.ITEM, new Identifier("tutorial", "custom_item"),
  6. new Item(new FabricItemSettings().group(ItemGroup.MISC)));
  7.  
  8. @Override
  9. public void onInitialize() {
  10. }
  11. }

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.

  1. public class CustomItem extends Item {
  2.  
  3. public CustomItem(Settings settings) {
  4. super(settings);
  5. }
  6. }

A practical use-case for a custom item class would be making the item play a sound when you use it:

  1. public class CustomItem extends Item {
  2.  
  3. public CustomItem(Settings settings) {
  4. super(settings);
  5. }
  6.  
  7. @Override
  8. public TypedActionResult<ItemStack> use(World world, PlayerEntity playerEntity, Hand hand) {
  9. playerEntity.playSound(SoundEvents.BLOCK_WOOL_BREAK, 1.0F, 1.0F);
  10. return TypedActionResult.success(playerEntity.getStackInHand(hand));
  11. }
  12. }

Replace the old Item object with an instance of your new item class:

  1. public class ExampleMod implements ModInitializer {
  2.  
  3. // an instance of our new item
  4. public static final CustomItem CUSTOM_ITEM = new CustomItem(new FabricItemSettings().group(ItemGroup.MISC));
  5. [...]
  6. }
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 FabricItemSettings 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.

  1. public class ExampleMod implements ModInitializer {
  2.  
  3. // An instance of our new item, where the maximum stack size is 16
  4. public static final CustomItem CUSTOM_ITEM = new CustomItem(new FabricItemSettings().group(ItemGroup.MISC).maxCount(16));
  5. [...]
  6. }

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:

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

Similarly, you can use a CompostingChanceRegistry to make it compostable in a composter.

Next Steps

tutorial/items.txt · Last modified: 2022/10/22 11:52 by solidblock