Your first custom item

In this guide you will make a Ruby: a simple shiny gem that stacks up to 64, shows up in the creative inventory and has its own name and icon. It does nothing fancy yet, but every sword, food and armor piece you make later starts from exactly this file.

There are two ways to do it. The quick way takes a couple of minutes on your phone. The by-hand way shows you every file, so you understand what is going on.

The quick way: GodCraft

GodCraft makes the item file, the texture, the name and the pack files for you. You never open a JSON file.

1. Open the Workshop and add an Item to your add-on.
2. Draw the icon in the pixel editor, or start from a vanilla texture and recolor it.
3. Type the name and pick the settings you want, like the stack size.
4. Tap Export. GodCraft writes the manifests, UUIDs and language files and gives you a .mcaddon to open in Minecraft.

Curious what is inside that .mcaddon? Read on.

By hand

You need a behavior pack (BP) and a resource pack (RP) that are already set up. If you do not have them yet, follow Project setup first. In every example we use the namespace myname. Replace it with your own short name, in lowercase, everywhere it appears.

These are the files you will make or change:

Step 1: the item file

Create a folder called items in your behavior pack and add this file:

{
  "format_version": "1.26.30",
  "minecraft:item": {
    "description": {
      "identifier": "myname:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:icon": {
        "textures": {
          "default": "myname_ruby"
        }
      },
      "minecraft:display_name": {
        "value": "item.myname:ruby.name"
      },
      "minecraft:max_stack_size": 64
    }
  }
}

Let's go through it piece by piece.

• format_version tells the game which version of the item rules your file follows. Use a recent one so all the modern components work.
• identifier is the item's unique ID. It is always namespace:name. Never use the minecraft namespace for a new item: that one belongs to the game.
• menu_category decides where the item shows up in the creative inventory. The category can be construction, nature, equipment, items or none (hidden). You can also add a group such as "minecraft:itemGroup.name.sword" to tuck it into an existing folder.
• components is where the item gets its features. Each component is one feature.

The three components used here:

• minecraft:icon picks the picture. default is the short name you will define in item_texture.json in step 3, not a file path.
• minecraft:display_name sets the name. Here it points to a key in the language file, so the name can be translated.
• minecraft:max_stack_size is how many fit in one slot. Use a number from 1 to 64.

Step 2: the texture

Draw a 16x16 pixel PNG and save it in your resource pack:

A 16x16 PNG with a transparent background

Keep the background transparent, or the icon will be a square. If you are new to pixel art, Pixel textures has tips for making small images look good.

Step 3: register the texture

The game does not read PNG files by path from the item. Instead, item_texture.json gives each picture a short name, and the item uses that name. Create (or open) this file:

{
  "resource_pack_name": "myname",
  "texture_name": "atlas.items",
  "texture_data": {
    "myname_ruby": {
      "textures": "textures/items/ruby"
    }
  }
}

Notice two things:

1. The key myname_ruby matches the default value in the item's icon component.
2. The path has no .png at the end.

When you add more items later, put them all in this one file as extra entries inside texture_data. Do not make a second item_texture.json.

Step 4: the name

Open (or create) the English language file and add one line:

item.myname:ruby.name=Ruby

The part before = must match the value of minecraft:display_name exactly. The part after it is what players see. Lang files are plain text: one entry per line, no quotes, no commas.

Step 5: test it

1. Copy both packs into Minecraft, or export them (see Export and install).
2. Create a new world and turn on both packs in its settings.
3. Open the chat and type the /give command:

/give @s myname:ruby 64

You should get a full stack of rubies with your icon and the name "Ruby". In a creative world you will also find it in the Items tab of the inventory.

When something goes wrong

Turn on Content Log in Minecraft's creator settings to see exact error messages. More fixes are in Troubleshooting.

What next?

Your ruby is a plain item. Now give it a job:

• Make something players can eat in Custom food.
• Turn rubies into a sword or a pickaxe in Weapons and tools.
• Make a full ruby armor set in Custom armor.
• Let players craft rubies in Crafting and furnace recipes.

To see how Mojang builds its own items, browse the vanilla items.