Creating Your First Item

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.Properties, Item> itemFactory, Item.Properties settings) {
		// Create the item key.
		ResourceKey<Item> itemKey = ResourceKey.create(Registries.ITEM, ResourceLocation.fromNamespaceAndPath(FabricDocsReference.MOD_ID, name));

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

		// Register the item.
		Registry.register(BuiltInRegistries.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.Properties 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 maxStackSize method in the Item.Properties 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.Properties());

Item::new tells the register function to create an Item instance from an Item.Properties by calling the Item constructor (new Item(...)), which takes an Item.Properties 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 a Creative Tab

INFO

If you want to add the item to a custom CreativeModeTab, check out the Custom Creative Tabs page for more information.

For example purposes, we will add this item to the ingredients CreativeModeTab, 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(CreativeModeTabs.INGREDIENTS)
		.register((itemGroup) -> itemGroup.accept(ModItems.SUSPICIOUS_SUBSTANCE));

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

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 an Item Model Description, Texture and Model

For your item to have a proper appearance, it requires:

• An item texture
• An item model
• An item model description

Adding a Texture

INFO

For more information on this topic, see the Item Models page.

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

Adding a Model

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

INFO

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

@Override
public void appendHoverText(ItemStack stack, TooltipContext context, TooltipDisplay displayComponent, Consumer<Component> textConsumer, TooltipFlag type) {
	textConsumer.accept(Component.translatable("itemTooltip.fabric-docs-reference.lightning_stick").withStyle(ChatFormatting.GOLD));
}

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