Create a Custom Item

In format versions 1.20.50 and newer, custom items follow a unified structure. The behavior pack holds the item JSON file, which defines both how the item behaves in the game and how it looks in the inventory. You no longer need to create a separate client item JSON file in your resource pack unless you are working with legacy formats or very specific attachable setups.

To get a custom item into the game, you need four pieces working together: the item definition in the behavior pack, a 16x16 PNG image in the resource pack, a mapping in the item_texture.json file that gives that image a short name, and an entry in your language file so the item has a clean display name.

Create a folder named items inside your behavior pack if you do not have one already. Inside that folder, create a new JSON file for your item. The filename does not technically have to match the item identifier, but keeping them the same makes large packs much easier to maintain.

Every item needs a format_version and a minecraft:item object split into description and components. The description block assigns the unique identifier (which must include your custom namespace, never minecraft) and tells the game where to place the item in the creative inventory. If you leave out the menu_category object, the item will still be obtainable with the /give command, but players will not be able to find it by browsing the creative menu.

Inside the components block, you add the building blocks that give your item its traits. A simple crafting material only needs an icon and a max stack size, while more complex items might include food properties, durability, or fuel values.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "tut:ruby",
      "menu_category": {
        "category": "items",
        "group": "itemGroup.name.gem"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "tut_ruby"
      },
      "minecraft:max_stack_size": 64,
      "minecraft:glint": false,
      "minecraft:hand_equipped": false
    }
  }
}

Components are modular properties you attach inside the components object of your item file. You only need to include the components that differ from standard default behavior, though you should always define minecraft:icon so your item does not show up as an empty or broken slot.

In format version 1.20.50 and above, several components accept either a simple shorthand value (like a boolean or integer) or a full object. For example, minecraft:max_stack_size can just be set to an integer between 1 and 64. The table below covers the fundamental components you will use on almost every basic item.

Notice that the minecraft:icon component in the behavior pack does not point directly to a file path; instead, it uses a shortname like tut_ruby. This is because Bedrock decouples behavior definitions from file layouts using an atlas dictionary in the resource pack.

First, place your 16x16 PNG image inside your resource pack at RP/textures/items/ruby.png. Next, open or create RP/textures/item_texture.json. Inside the texture_data object, add a key matching the exact shortname you wrote in your behavior pack, and point its textures property to the path of your PNG file (leaving off the .png file extension). Always prefix your shortnames with your namespace and an underscore so you do not accidentally overwrite vanilla item textures or clash with other add-ons.

{
  "resource_pack_name": "tut_rp",
  "texture_name": "atlas.items",
  "texture_data": {
    "tut_ruby": {
      "textures": "textures/items/ruby"
    }
  }
}

If you load into a world right now, your item will have a working texture, but hovering over it in the inventory will show a raw string like item.tut:ruby. To give it a proper name that supports different languages, you need to add a translation entry to your resource pack's language file.

Open or create RP/texts/en_US.lang. Each line in a .lang file is a key-value pair separated by an equals sign, with no spaces around the equals sign. Unless you manually overrode the key using the minecraft:display_name component, the default key for any custom item without a client item file is item.<namespace>:<name>=Your Display Name. Note that older format versions required a .name suffix at the end of the key, so if you ever downgrade a pack or use a custom display_name key, keep track of which pattern your item expects.

item.tut:ruby=Ruby
item.tut:ruby.name=Ruby

Once your basic item works, turning it into custom food only requires adding two more components to your behavior pack file: minecraft:food and minecraft:use_modifiers. You do not need to change anything in the resource pack unless you want a different texture.

In modern Bedrock formats, you must pair minecraft:food with minecraft:use_modifiers. The food component controls how much hunger and saturation are restored when the item is consumed, while use_modifiers controls how many seconds the player has to hold down the use button to finish eating, as well as how much their movement slows down while chewing. You can also include minecraft:use_animation set to eat so the game plays the eating sound and bobbing animation while the button is held.

{
  "format_version": "1.20.50",
  "minecraft:item": {
    "description": {
      "identifier": "tut:candied_ruby",
      "menu_category": {
        "category": "equipment",
        "group": "itemGroup.name.miscFood"
      }
    },
    "components": {
      "minecraft:icon": {
        "texture": "tut_ruby"
      },
      "minecraft:use_animation": "eat",
      "minecraft:use_modifiers": {
        "use_duration": 1.6,
        "movement_modifier": 0.35
      },
      "minecraft:food": {
        "nutrition": 4,
        "saturation_modifier": 0.6,
        "can_always_eat": false
      }
    }
  }
}

Applies to Minecraft Bedrock 1.20.50 and newer. All components shown on this page are stable and do not require any Experimental toggles to be enabled in world settings.

Read out of the game itself, so the ids match the version you are building for.