How to Make a Custom Item in Minecraft Bedrock

Before you start

You need two packs working together:

• Behavior pack (BP): holds the item definition (the JSON file you will write).
• Resource pack (RP): holds the item's icon texture and its display name.

If you have not set up packs before, the add-on basics guide covers folder structure and manifest files. The short version: put your work-in-progress packs in the development_behavior_packs and development_resource_packs folders inside your com.mojang directory. On Windows that is %appdata%\Minecraft Bedrock\users\shared\games\com.mojang (type it into Win+R to open it).

You will also need:

• A text editor (VS Code, Notepad++, or even Notepad works).
• An image editor for the 16×16 icon (Krita, GIMP, Paint.NET, or Aseprite).
• A UUID generator (e.g. uuidgenerator.net) if you are creating new manifests.

The item file (behavior pack)

Create a file called items/ruby.json inside your behavior pack folder. (The file name does not matter to the game; only the identifier inside does, but a sensible name helps you.)

Here is a complete, valid item definition. Copy it, change the identifier and icon name to your own, and you have a working item:

{
  "format_version": "1.26.50",
  "minecraft:item": {
    "description": {
      "identifier": "myaddon:ruby",
      "menu_category": {
        "category": "items"
      }
    },
    "components": {
      "minecraft:icon": "myaddon_ruby",
      "minecraft:max_stack_size": 16
    }
  }
}

What each part does:

• format_version: set to "1.26.50". This is the current stable line.
• identifier: your item's unique ID. Use the pattern namespace:name (lowercase letters, digits, underscores). Never use the minecraft: namespace. It is reserved for vanilla.
• menu_category.category: which creative-inventory tab the item appears in. Valid values: construction, equipment, items, nature.
• minecraft:icon: a short name that points to the texture (explained in the next section).
• minecraft:max_stack_size: how many fit in one slot (default is 64).

The texture (resource pack)

The item's icon is a small PNG image (16×16 pixels is the conventional size) that you register in a JSON file inside your resource pack.

Step 1: Save your icon as textures/items/ruby.png inside the resource pack folder. (The file name just needs to match the path you register below.)

Step 2: Create (or edit) the file textures/item_texture.json in the resource pack root:

{
  "texture_data": {
    "myaddon_ruby": {
      "textures": "textures/items/ruby"
    }
  }
}

Key points:

• The key myaddon_ruby is the short name you referenced in minecraft:icon in the BP file. They must match exactly.
• The value textures/items/ruby is the path to the PNG without the .png extension, relative to the RP root.
• The file must be named exactly item_texture.json and live in RP/textures/. Common mistakes: item_textures.json, texture/item_texture.json, or Item_texture.json. All of these will not work.

Name it (language file)

By default, Minecraft looks for a language key based on the item's identifier. Add this line to texts/en_US.lang in your resource pack:

item.myaddon:ruby=Ruby

That is the form used by the Bedrock Wiki and it works on 1.26.50. The pattern is item.<identifier>=Display Name.

Alternative: you can also set an explicit display name in the item JSON and use your own key:

"minecraft:display_name": { "value": "myaddon.ruby.custom_name" }

Then in en_US.lang write myaddon.ruby.custom_name=Shiny Ruby. This is useful if you want a name that does not follow the default pattern.

Get it in game

Once both packs are active in your world (activate the BP; if it has a dependency on the RP, both turn on together), you can grab the item two ways:

1. Creative inventory: open the creative menu and look in the tab you set in menu_category (e.g. the "Items" tab for "category": "items").
2. /give command: with cheats enabled, type /give @s myaddon:ruby (add a count: /give @s myaddon:ruby 5).

If the item does not appear, check the Content Log (Settings → Creator → enable both content-log toggles, then press Ctrl+H in game). It will tell you if the JSON is invalid or a file is missing.

Make it food, a tool, or stackable

Once the basic item works, you can add behaviour with more components. All of these go inside the "components" object in your BP item file.

Edible (food)

To make the item eatable you need three components together:

{
  "format_version": "1.26.50",
  "minecraft:item": {
    "description": {
      "identifier": "myaddon:berry",
      "menu_category": { "category": "items" }
    },
    "components": {
      "minecraft:icon": "myaddon_berry",
      "minecraft:food": { "nutrition": 4, "saturation_modifier": 0.3 },
      "minecraft:use_animation": { "value": "eat" },
      "minecraft:use_modifiers": { "start_using": "always", "use_duration": 1.6, "movement_modifier": 0.35 }
    }
  }
}

• minecraft:food: nutrition (hunger restored) and saturation_modifier (must be greater than 0).
• minecraft:use_animation: "eat" or "drink" for the holding animation.
• minecraft:use_modifiers: use_duration is required (how long the eating takes, in seconds). Without it the food will not work.

Durable tool

"minecraft:durability": { "max_durability": 36 },
"minecraft:damage": 5,
"minecraft:hand_equipped": true

• minecraft:durability: makes the item breakable. max_durability is the total hits before it breaks (0 to 32767).
• minecraft:damage: extra attack damage (plain integer, 0 to 32767).
• minecraft:hand_equipped: set to true to render the item like a tool in third person.

Other useful components

• "minecraft:max_stack_size": 1: limit the stack (e.g. for unique items).
• "minecraft:glint": true: adds the enchanted shimmer effect.

Here is a video showing a more complex item add-on (magnet boots). It is an older video, so the exact JSON syntax may differ slightly from the current format, but the concept is the same:

What changed recently (items)

The item format has been evolving. Here are the changes most relevant to you as of 1.26.50:

• 1.26.30: use_modifiers.start_using now defaults to "if_first" (previously "always"). If you want the old behaviour, set it explicitly.
• 1.26.30: item files with empty components are rejected. Always include at least one component.
• 1.26.0: minecraft:damage now supports values above 255 (up to 32767).
• 1.21.90: Custom Components V2 (script-based) was introduced for items. This is an advanced topic and not needed for basic items.
• 1.21.130: minecraft:kinetic_weapon component added (used by the vanilla copper spear).

Older tutorials (pre-2024) often show a different icon syntax ("minecraft:icon": {"texture": "..."}) and may require the now-removed Holiday Creator Features experiment. Ignore those; the string form "minecraft:icon": "short_name" is current.

Common mistakes

Work through this list if your item is not showing or looks wrong:

1. Item invisible or shows a raw key name. The minecraft:icon short name does not match the key in item_texture.json, or the PNG path is wrong. Check both files character by character.
2. Wrong file name for the texture JSON. It must be exactly item_texture.json in RP/textures/. Not item_textures.json, not texture/item_texture.json.
3. Empty components object. On format 1.26.30+ this causes a content error and the item will not register. Add at least minecraft:icon.
4. Missing menu_category. Without it the item may not appear in the creative inventory. Set a category so it shows up.
5. Identifier not lowercase or uses minecraft: namespace. Use your own namespace: myaddon:ruby, not minecraft:ruby.
6. Pack not active in the world. Make sure both the BP and RP are activated. If the BP depends on the RP, activating the BP should activate both.
7. JSON syntax error. One missing comma or extra comma breaks the whole file. Paste your JSON into jsonlint.com to check. (Minecraft does allow // comments in JSON, but online linters will flag them. That is fine, the game will still read the file.)
8. Edits not showing. If your packs are in the normal behavior_packs / resource_packs folders, they may be cached. Move them to development_behavior_packs / development_resource_packs, then exit and re-enter the world.

When in doubt, open the Content Log (Settings → Creator, enable both toggles, Ctrl+H in game). It lists every registration error with the file name.

FAQ

Do I need an experimental toggle?

No. Basic custom items (icon, name, stack size, food, durability, damage) work on stable 1.26.50 with no experiments enabled. Older guides that mention "Holiday Creator Features" are outdated.

What size should the icon PNG be?

16×16 pixels is the traditional Minecraft item-icon size and what most add-ons use. Larger images will load but will look out of place next to vanilla items.

Can I have multiple items in one pack?

Yes. Create one JSON file per item in BP/items/, register each icon in item_texture.json, and add a lang line for each. They all share the same pack.

Why does my item show as a black square?

The texture is not being found. Check that the path in item_texture.json matches the actual PNG location (without the .png extension), and that the short name matches minecraft:icon in the BP file exactly.

Can I make the item unstackable?

Set "minecraft:max_stack_size": 1 in the components.

Where do I find the content log on Windows?

In game: Settings → Creator → enable both content-log settings, then press Ctrl+H to open the history. The log file is also written to %APPDATA%\logs (the exact folder name may vary with newer installs).

Do I need to restart Minecraft after editing a file?

If your packs are in the development_* folders, exiting and re-entering the world is usually enough. If they are in the normal behavior_packs / resource_packs folders, a full restart is safer because of caching.