This page will introduce you into some key concepts relating to items, and how you can register, texture, model and name them.

If you aren't aware, everything in Minecraft is stored in registries, and items are no exception to that.

Preparing Your Items Class

To simplify the registering of items, you can create a method that accepts a string identifier, some item settings and a factory to create the Item instance.

This method will create an item with the provided identifier and register it with the game's item registry.

You can put this method in a class called ModItems (or whatever you want to name the class).

Mojang does this with their items as well! Check out the Items class for inspiration.

public class ModItems {
	public static Item register(String name, Function<Item.Settings, Item> itemFactory, Item.Settings settings) {
		// Create the item key.
		RegistryKey<Item> itemKey = RegistryKey.of(RegistryKeys.ITEM, Identifier.of(FabricDocsReference.MOD_ID, name));

		// Create the item instance.
		Item item = itemFactory.apply(settings.registryKey(itemKey));

		// Register the item.
		Registry.register(Registries.ITEM, itemKey, item);

		return item;
	}

}

Notice the usage of a Function interface for the factory, which will later allow us to specify how we want our item to be created from the item settings using Item::new.

Registering an Item

You can now register an item using the method now.

The register method takes in an instance of the Item.Settings class as a parameter. This class allows you to configure the item's properties through various builder methods.

TIP

If you want to change your item's stack size, you can use the maxCount method in the Item.Settings class.

This will not work if you've marked the item as damageable, as the stack size is always 1 for damageable items to prevent duplication exploits.

public static final Item SUSPICIOUS_SUBSTANCE = register("suspicious_substance", Item::new, new Item.Settings());

Item::new tells the register function to create an Item instance from an Item.Settings by calling the Item constructor (new Item(...)), which takes an Item.Settings as a parameter.

However, if you now try to run the modified client, you can see that our item doesn't exist in-game yet! This is because you didn't statically initialize the class.

To do this, you can add a public static initialize method to your class and call it from your mod's initializer class. Currently, this method doesn't need anything inside it.

public static void initialize() {
}

public class FabricDocsReferenceItems implements ModInitializer {
	@Override
	public void onInitialize() {
		ModItems.initialize();
	}
}

Calling a method on a class statically initializes it if it hasn't been previously loaded - this means that all static fields are evaluated. This is what this dummy initialize method is for.

Adding the Item to an Item Group

INFO

If you want to add the item to a custom ItemGroup, check out the Custom Item Groups page for more information.

For example purposes, we will add this item to the ingredients ItemGroup, you will need to use Fabric API's item group events - specifically ItemGroupEvents.modifyEntriesEvent

This can be done in the initialize method of your items class.

// Get the event for modifying entries in the ingredients group.
// And register an event handler that adds our suspicious item to the ingredients group.
ItemGroupEvents.modifyEntriesEvent(ItemGroups.INGREDIENTS)
		.register((itemGroup) -> itemGroup.add(ModItems.SUSPICIOUS_SUBSTANCE));

Loading into the game, you can see that our item has been registered, and is in the Ingredients item group:

However, it's missing the following:

• Item Model
• Texture
• Translation (name)

Naming The Item

The item currently doesn't have a translation, so you will need to add one. The translation key has already been provided by Minecraft: item.mod_id.suspicious_substance.

Create a new JSON file at: src/main/resources/assets/mod-id/lang/en_us.json and put in the translation key, and its value:

{
  "item.mod_id.suspicious_substance": "Suspicious Substance"
}

You can either restart the game or build your mod and press F3+T to apply changes.

Adding a Texture and Model

To give your item a texture and model, simply create a 16x16 texture image for your item and save it in the assets/mod-id/textures/item folder. Name the texture file the same as the item's identifier, but with a .png extension.

For example purposes, you can use this example texture for suspicious_substance.png

Download Texture

When restarting/reloading the game - you should see that the item still has no texture, that's because you will need to add a model that uses this texture.

You're going to create a simple item/generated model, which takes in an input texture and nothing else.

Create the model JSON in the assets/mod-id/models/item folder, with the same name as the item; suspicious_substance.json

{
  "parent": "minecraft:item/generated",
  "textures": {
    "layer0": "fabric-docs-reference:item/suspicious_substance"
  }
}

Breaking Down the Model JSON

• parent: This is the parent model that this model will inherit from. In this case, it's the item/generated model.
• textures: This is where you define the textures for the model. The layer0 key is the texture that the model will use.

Most items will use the item/generated model as their parent, as it's a simple model that just displays the texture.

There are alternatives, such as item/handheld which is used for items that are "held" in the player's hand, such as tools.

Creating the Item Model Description

Minecraft doesn't automatically know where your items' model files can be found, we need to provide an item model description.

Create the item description JSON in the assets/mod-id/items, with the same file name as the identifier of the item: suspicious_substance.json.

{
  "model": {
    "type": "minecraft:model",
    "model": "fabric-docs-reference:item/suspicious_substance"
  }
}

Breaking Down the Item Model Description JSON

• model: This is the property that contains the reference to our model.
  • type: This is the type of our model. For most items, this should be minecraft:model
  • model: This is the model's identifier. It should have this form: mod-id:item/item_name

Your item should now look like this in-game:

Making the Item Compostable or a Fuel

Fabric API provides various registries that can be used to add additional properties to your item.

For example, if you want to make your item compostable, you can use the CompostableItemRegistry:

// Add the suspicious substance to the composting registry with a 30% chance of increasing the composter's level.
CompostingChanceRegistry.INSTANCE.add(ModItems.SUSPICIOUS_SUBSTANCE, 0.3f);

Alternatively, if you want to make your item a fuel, you can use the FuelRegistryEvents.BUILD event:

// Add the suspicious substance to the registry of fuels, with a burn time of 30 seconds.
// Remember, Minecraft deals with logical based-time using ticks.
// 20 ticks = 1 second.
FuelRegistryEvents.BUILD.register((builder, context) -> {
	builder.add(ModItems.SUSPICIOUS_SUBSTANCE, 30 * 20);
});

Adding a Basic Crafting Recipe

If you want to add a crafting recipe for your item, you will need to place a recipe JSON file in the data/mod-id/recipe folder.

For more information on the recipe format, check out these resources:

• Recipe JSON Generator
• Minecraft Wiki - Recipe JSON

Custom Tooltips

If you want your item to have a custom tooltip, you will need to create a class that extends Item and override the appendTooltip method.

INFO

This example uses the LightningStick class created in the Custom Item Interactions page.

@Override
public void appendTooltip(ItemStack stack, TooltipContext context, List<Text> tooltip, TooltipType type) {
	tooltip.add(Text.translatable("itemTooltip.fabric-docs-reference.lightning_stick").formatted(Formatting.GOLD));
}

Each call to add() will add one line to the tooltip.