Items

Stats and components

A custom item behaves like the vanilla item under it (its material:), so a sword built on a stick hits as hard as a stick. These settings, added to the item's definition, change the numbers:

sword:
  material: IRON_SWORD
  model: sword
  durability: 500                     # replaces the material's own
  enchantments: { sharpness: 3, unbreaking: 2 }
  attributes:
    - attack_damage: 9
    - attack_speed: -2.4
    - max_health: { amount: 4, operation: add, slot: hand }
  food: { nutrition: 6, saturation: 7.2, always: false }
  flags: [HIDE_ENCHANTS, HIDE_ATTRIBUTES]

These are real item components. The game applies them, other plugins can read them, and the item keeps them even on a server without RP Engine.

Names are vanilla's#

Use the names from the Minecraft wiki, without a minecraft: prefix: sharpness, unbreaking, attack_damage, max_health. Anything the server knows is accepted.

A name that matches nothing is reported once in the console when the item is first given, not when the pack loads, and only that one setting is skipped. The rest of the item still works.

Attributes#

The short form is a name and an amount:

  attributes:
    - attack_damage: 9

The long form adds an operation and a slot:

  attributes:
    - max_health: { amount: 4, operation: add, slot: hand }

`operation`	What it does
`add`	Adds the amount. The default
`multiply_base`	Adds a fraction of the base value
`multiply`	Multiplies the total

slot is where the item has to be for it to apply: hand, offhand, head, chest, legs, feet, armor (any armour slot) or any.

Durability#

durability: replaces the material's own maximum.

Food#

  food: { nutrition: 6, saturation: 7.2, always: false }

nutrition is in half-drumsticks. always: true lets it be eaten on a full hunger bar, like a golden apple.

Minecraft 1.20.5 or newer

durability, food, stack and glow are item components that arrived in 1.20.5. On an older server they are skipped with a console warning, and the item uses its material's own values.

  flags: [HIDE_ENCHANTS, HIDE_ATTRIBUTES]

These are Bukkit's item flag names (HIDE_ENCHANTS, HIDE_ATTRIBUTES, HIDE_UNBREAKABLE, HIDE_DYE and so on), in either case. HIDE_POTION_EFFECTS and HIDE_ADDITIONAL_TOOLTIP (its name from 1.20.5) are treated as the same flag. A flag your server's version does not have is a console warning, not an error.

Wearing and keeping#

crown:
  material: GOLDEN_APPLE
  hat: true                # right-click to wear it on your head
  keep-on-death: true      # survives dying

hat: right-clicking puts the item on your head. If you are already wearing something there, nothing happens.
A 3D hat on a helmet (material: NETHERITE_HELMET with a model:, and no armor: art of its own) is worn showing its model, not the vanilla helmet, and keeps the helmet's armour points. Minecraft 1.21.2 and newer.
keep-on-death: the item stays with the player when they die and is given back when they respawn, without turning on keepInventory for the whole server.

liquid: mypack:acid makes the item a bucket of that liquid.