Items

To create custom items using addonpacks, create a JSON file at:

addon/<namespace>/item/<item_id>.json

For example, addon/mypack/item/cool_sword.json registers the item mypack:cool_sword.

---

Item Types

Every item file requires a type field that determines what kind of item it is.

minecraft:item

A basic item with no special behaviour.

addon/mypack/item/basic_item.json

{
  "type": "minecraft:item",
  "properties": {}
}

---

minecraft:block_item

An item that represents a block (i.e. can be placed). Requires the target block to already be registered.

Field	Type	Description
block	Identifier	The registry ID of the target block.

addon/mypack/item/my_block_item.json

{
  "type": "minecraft:block_item",
  "block": "mypack:my_block",
  "properties": {}
}

---

minecraft:sword

A sword item. Requires a registered tool material.

Field	Type	Default	Description
tool_material	String	—	Registry ID of the tool material to use.
attack_damage	Float	3.0	Additional attack damage on top of the tool material's base.
attack_speed	Float	-2.4	Attack speed modifier.

addon/mypack/item/emerald_sword.json

{
  "type": "minecraft:sword",
  "tool_material": "mypack:emerald",
  "attack_damage": 3,
  "attack_speed": -2.4,
  "properties": {}
}

---

minecraft:armor

An armor item. Requires a registered armor material.

Field	Type	Description
armor_material	String	Registry ID of the armor material to use.
armor_type	String	Which armor slot this piece occupies. One of helmet, chestplate, leggings, boots, body.

addon/mypack/item/dirt_chestplate.json

{
  "type": "minecraft:armor",
  "armor_material": "mypack:dirt",
  "armor_type": "chestplate",
  "properties": {}
}

---

Properties

The properties object is available on all item types and supports the following fields. All fields are optional.

components

Data components to attach to the item. Minecraft's built-in components are documented on the Minecraft wiki. Palladium also adds its own components; see the Data Components page for the full list.

"properties": {
  "components": {
    "minecraft:rarity": "epic",
    "minecraft:glider": {}
  }
}

tab

Places the item into one or more creative mode tabs. Accepts a single entry or an array of entries.

Simple placement: just add the item to a tab without a specific position:

"tab": "minecraft:tools_and_utilities"

Positional placement: insert the item relative to another item in the tab:

Field	Type	Description
type	String	add_after or add_before.
tab	Identifier	The creative tab to place the item in.
target	Identifier	The item to place this item after or before.

"tab": {
  "type": "add_after",
  "tab": "minecraft:combat",
  "target": "minecraft:diamond_sword"
}

Multiple tabs: use an array to place the item in several tabs at once:

"tab": [
  {
    "type": "add_after",
    "tab": "minecraft:building_blocks",
    "target": "minecraft:stone"
  },
  {
    "type": "add_before",
    "tab": "minecraft:natural_blocks",
    "target": "minecraft:stone"
  }
]

---

Required Assets

Your item will have no texture or name until you provide the following files.

Item Definition File

Since Minecraft 1.21.4, every item requires an item definition file that tells the game which model to render:

assets/<namespace>/items/<item_id>.json

{
  "model": {
    "type": "minecraft:model",
    "model": "<namespace>:item/<item_id>"
  }
}

Item Model File

This is the actual model that defines the shape and textures of the item. For a flat 2D item (the most common case), it looks like this:

assets/<namespace>/models/item/<item_id>.json

{
  "parent": "minecraft:item/generated",
  "textures": {
    "layer0": "<namespace>:item/<item_id>"
  }
}

The layer0 value points to your texture at assets/<namespace>/textures/item/<item_id>.png.

You can also use a custom 3D model exported from Blockbench here instead of the generated flat model.

Language File

To give your item a name, add an entry to your language file at assets/<namespace>/lang/en_us.json:

assets/<namespace>/lang/en_us.json

{
  "item.<namespace>.<item_id>": "My Item Name"
}

---

Full Examples

Basic item with a rarity and equippable slot

addon/mypack/item/magic_hat.json

{
  "type": "minecraft:item",
  "properties": {
    "components": {
      "minecraft:rarity": "epic",
      "minecraft:equippable": {
        "slot": "head"
      }
    },
    "tab": {
      "type": "add_after",
      "tab": "minecraft:tools_and_utilities",
      "target": "minecraft:elytra"
    }
  }
}

assets/mypack/items/magic_hat.json

{
  "model": {
    "type": "minecraft:model",
    "model": "mypack:item/magic_hat"
  }
}

assets/mypack/models/item/magic_hat.json

{
  "parent": "minecraft:item/generated",
  "textures": {
    "layer0": "mypack:item/magic_hat"
  }
}

Block item placed in multiple tabs

addon/mypack/item/my_block.json

{
  "type": "minecraft:block_item",
  "block": "mypack:my_block",
  "properties": {
    "tab": [
      {
        "type": "add_after",
        "tab": "minecraft:building_blocks",
        "target": "minecraft:stone"
      },
      {
        "type": "add_before",
        "tab": "minecraft:natural_blocks",
        "target": "minecraft:stone"
      }
    ]
  }
}