Skip to content
iPlugin

Metadata System

Add Special Functions to Items

Overview

The metadata system allows you to add special functions to items, such as custom durability, attribute bonuses, and special effects. With simple configurations, you can equip items with rich functionalities.

What is Metadata

Metadata refers to additional function configurations for items. They do not affect the basic appearance of items but add special behaviors and effects to them.

Complete List of Metadata Types

All metadata types implemented in Zaphkiel:

Metadata TypeFunctionExample Usage
attributeAttribute bonusesModify attributes like attack damage, attack speed, and armor value
can-destroyList of breakable blocksRestrict blocks a tool can break in Adventure mode
can-place-onList of placeable blocksRestrict positions where a block can be placed in Adventure mode
colorColor settingDye leather armor, set potion colors
dataItem data valueSet the CustomModelData of an item
iconIcon materialDynamically change the item's material type
itemflagItem flagsHide displays of enchantments, attributes, etc.
nativeNative NBTDirectly set the item's NBT data
potionPotion effectsAdd base potion types and custom effects to potion items
shinyGlowing effectMake items glow like enchanted ones without showing enchantment info
skullSkull settingsCustom player skulls, textured skulls, HeadDatabase integration
spawnerSpawn egg typeSet the entity type spawned by a spawn egg
tipharethTiphareth integrationIntegrate with the Tiphareth plugin's resource pack
unbreakableUnbreakable statusSet items to be unbreakable
uniqueUnique identifierAdd unique identification info to items

Basic Metadata Configuration

Durability Metadata

Equip items with a custom durability system:

my_tool:
  icon: diamond_pickaxe
  display: default_display_1
  name:
    item_name: '&6Magical Pickaxe'
  data:
    durability: 100         # Custom durability value
  meta:
    durability:
      remains: minecraft:stick  # Item to become after durability is exhausted
  event:
    on_damage: item damage 1    # Reduce durability when used

Attribute Metadata

Add attribute bonuses to items:

my_sword:
  icon: diamond_sword
  name:
    item_name: '&cPowerful Sword'
  meta:
    attribute:
      mainhand:             # Attributes when held in main hand
        damage: +10         # +10 attack damage
        attack_speed: +20%  # +20% attack speed
      offhand:              # Attributes when held in off hand
        armor: +5           # +5 armor value

Appearance & Visual Metadata

Color Metadata (color)

Set colors for leather armor and potions:

colored_leather_armor:
  icon: leather_chestplate
  name: '&cRed Leather Armor'
  meta:
    color: 255-0-0          # RGB format: Red-Green-Blue

magic_potion:
  icon: potion
  name:
    item_name: '&5Purple Potion'
  meta:
    color: 128-0-128        # Purple potion

Icon Metadata (icon)

Dynamically change the item's material type:

dynamic_icon_item:
  icon: stone
  name:
    item_name: '&aDynamic Icon Item'
  meta:
    icon: diamond           # Change icon to diamond at runtime

Shiny Metadata (shiny)

Make items glow like enchanted ones without showing enchantment info:

glowing_item:
  icon: diamond
  name:
    item_name: '&bGlowing Diamond'
  meta:
    shiny: true             # Add glowing effect without showing enchantment info

Skull Metadata (skull)

Customize player skulls and textured skulls:

custom_skull:
  icon: player_head
  name:
    item_name: '&6Custom Skull'
  meta:
    skull:
      # Method 1: Player name
      owner: "Notch"
      
      # Method 2: Custom texture
      textures:
        value: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
        id: "12345678-1234-1234-1234-123456789abc"
      
      # Method 3: HeadDatabase integration
      head-database: "1234"

Functional Metadata

Data Metadata (data)

Set the CustomModelData of an item:

custom_model_item:
  icon: diamond_sword
  name:
    item_name: '&6Custom Model Sword'
  meta:
    data: 1001              # Set CustomModelData to 1001

Item Flag Metadata (itemflag)

Hide various types of item info displays:

clean_sword:
  icon: diamond_sword
  name:
    item_name: '&cClean Sword'
  meta:
    # In Minecraft 1.21+, to hide default attributes of weapons (e.g., attack damage, attack speed),
    # you need to modify these attributes first, then use HIDE_ATTRIBUTES to hide them
    attribute:
      mainhand:
        damage: 0          # Set attack damage to 0
        attack_speed: 0    # Set attack speed to 0
    itemflag:
      - HIDE_ENCHANTS        # Hide enchantments
      - HIDE_ATTRIBUTES      # Hide attributes (requires attribute modification first)
      - HIDE_UNBREAKABLE     # Hide unbreakable flag
      - HIDE_DESTROYS        # Hide breakable blocks info
      - HIDE_PLACED_ON       # Hide placeable blocks info
      - HIDE_POTION_EFFECTS  # Hide potion effects

Important Note

  • In Minecraft 1.21+, the HIDE_ATTRIBUTES flag can only hide modified attributes
  • For items with default attributes (e.g., weapons), you need to first modify these attributes (e.g., set to 0) using the attribute metadata, then HIDE_ATTRIBUTES will take effect
  • If you only set HIDE_ATTRIBUTES without modifying attributes, the weapon's default attack damage and attack speed will still be displayed

Unbreakable Metadata (unbreakable)

Set items to be unbreakable:

unbreakable_tool:
  icon: diamond_pickaxe
  name:
    item_name: '&aEternal Pickaxe'
  meta:
    unbreakable: true       # Set as unbreakable

Unique Identifier Metadata (unique)

Add unique identifiers to each item instance:

unique_item:
  icon: diamond
  name:
    item_name: '&6Unique Diamond'
  meta:
    unique: true            # Add unique identifier to each item instance

Adventure Mode Metadata

Can-Destroy Metadata (can-destroy)

Restrict blocks a tool can break in Adventure mode:

special_pickaxe:
  icon: diamond_pickaxe
  name:
    item_name: '&6Special Pickaxe'
  meta:
    can-destroy:
      - minecraft:stone
      - minecraft:cobblestone
      - minecraft:iron_ore

Can-Place-On Metadata (can-place-on)

Restrict positions where a block can be placed in Adventure mode:

special_block:
  icon: minecraft:dirt
  name:
    item_name: '&aSpecial Dirt'
  meta:
    can-place-on:
      - minecraft:grass_block
      - minecraft:stone

Potion & Entity Metadata

Potion Metadata (potion)

Add base potion types and custom effects to potion items:

magic_potion:
  icon: potion
  name:
    item_name: '&5Magic Potion'
  meta:
    potion:
      base: HEALING          # Base potion type
      # Custom potion effects (effect name: duration-level)
      SPEED: 600-1           # Speed I, lasts 30 seconds (600 ticks)
      STRENGTH: 1200-2       # Strength II, lasts 60 seconds
      REGENERATION: 300-1    # Regeneration I, lasts 15 seconds

Spawn Egg Metadata (spawner)

Deprecation Warning

This metadata is deprecated in Minecraft 1.13+. Starting from 1.13, different entity types correspond to different spawn egg item types, and the spawned entity of a spawn egg cannot be modified via NBT data.

It is recommended to directly use the corresponding spawn egg item types (e.g., zombie_spawn_egg, skeleton_spawn_egg, etc.).

Set the entity type spawned by a spawn egg:

custom_spawn_egg:
  icon: zombie_spawn_egg
  name:
    item_name: '&cCustom Spawn Egg'
  meta:
    spawner: ZOMBIE          # Set to spawn zombies

Advanced Metadata

Based on the mapping support information provided, here is the complete documentation for native NBT metadata (native).

Native NBT Metadata (native)

Directly set the item's NBT data, supporting nested structures and data mapping:

Basic Usage

nbt_item:
  icon: stick
  name:
    item_name: '&eNBT Item'
  meta:
    native:
      CustomTag: "custom_value"
      Damage: 10
      HideFlags: 63

Nested Structure Support

The native metadata fully supports complex nested NBT structures:

advanced_nbt_item:
  icon: diamond_sword
  name:
    item_name: '&6Advanced NBT Item'
  meta:
    native:
      # Simple values
      Version: 1
      Enabled: true
      # Nested objects
      Zap:
        current_attributes:
          list:
            attack_damage: 123
            attack_speed: 1.6
        metadata:
          creator: "admin"
          timestamp: 1640995200
      # Multi-level nesting
      CustomSystem:
        config:
          settings:
            auto_repair: true
            max_durability: 1000

Data Mapping Integration

The native metadata is perfectly integrated with data-mapper data mapping, supporting dynamic display and data reference:

dynamic_nbt_item:
  icon: iron_sword
  name:
    item_name: '&cDynamic NBT Item'
  data-mapper:
    damage: it                              # Reference value from the data node
    hello: it                               # Reference value from the data node
    type_damage: "&Zap.type.attack_damage"  # Reference nested value from native NBT
    current_level: "&Stats.level"           # Reference value from native NBT
    current_exp: "&Stats.experience"        # Reference value from native NBT
  meta:
    native:
      hello: "world"                        # Can be referenced by data-mapper
      Zap:
        type:
          attack_damage: 123                # Can be referenced via path
      Stats:
        level: 5
        experience: 1250
  display: dynamic_display

# display configuration
dynamic_display:
  name: '&cDynamic NBT Item &7[Level {current_level}]'
  lore:
    - '&7Damage: &e{type_damage}'
    - '&7Greeting: &a{hello}'
    - '&7Experience: &e{current_exp}'
    - '&7Level: &a{current_level}'

Mapping Syntax Explanation

When referencing native NBT data in data-mapper, use the following syntax:

  • "&Path" - Reference nested values in NBT, using dots to separate paths
  • it - Reference values with the same name from the data node
  • Supports complex Kether script expressions for data processing

Practical Application Example

rpg_weapon:
  icon: diamond_sword
  name:
    item_name: '&6{weapon_name} &7+{enhancement_level}'
  data-mapper:
    weapon_name: "&WeaponData.name"
    enhancement_level: "&WeaponData.enhancement.level"
    total_damage: |-
      &WeaponData.base_damage + &WeaponData.enhancement.bonus_damage
  meta:
    native:
      WeaponData:
        name: "Legendary Sword"
        base_damage: 100
        enhancement:
          level: 5
          bonus_damage: 25
  display: weapon_display

weapon_display:
  name: '&6{weapon_name} &7+{enhancement_level}'
  lore:
    - '&7Base Damage: &c{WeaponData.base_damage}'
    - '&7Enhancement Damage: &e+{WeaponData.enhancement.bonus_damage}'
    - '&7Total Damage: &a{total_damage}'

Tiphareth Integration Metadata (tiphareth)

Integrate with the Tiphareth plugin's resource pack:

tiphareth_item:
  icon: diamond_sword
  name:
    item_name: '&dTiphareth Item'
  meta:
    tiphareth: "custom_model_name"  # Tiphareth model name

Practical Metadata Examples

Equipment Items

warrior_helmet:
  icon: diamond_helmet
  name:
    item_name: '&4Warrior Helmet'
  meta:
    attribute:
      # Attributes when equipped on head
      head:
        # Armor +8
        armor: +8
        # Max Health +20
        max_health: +20
        # Knockback Resistance +0.1
        knockback_resistance: +0.1
    # Unbreakable
    unbreakable: true
    # Hide attribute display
    itemflag:
      - HIDE_ATTRIBUTES
      - HIDE_UNBREAKABLE

Metadata Locking

Locking Metadata

Use the !! suffix to lock metadata, ensuring forced application after configuration updates:

my_weapon:
  data:
    durability!!: 200       # Lock durability value
  meta:
    durability!!:           # Lock durability configuration
      remains: minecraft:stick
    attribute:              # Do not lock attribute configuration
      mainhand:
        damage: +15

Functions of Locking

  • Balance Adjustment: Take effect immediately after modifying weapon attributes
  • Function Fixes: Force updates after fixing metadata issues
  • Unified Standards: Ensure all items of the same type use the same metadata

On this page

OverviewWhat is MetadataComplete List of Metadata TypesBasic Metadata ConfigurationDurability MetadataAttribute MetadataAppearance & Visual MetadataColor Metadata (color)Icon Metadata (icon)Shiny Metadata (shiny)Skull Metadata (skull)Functional MetadataData Metadata (data)Item Flag Metadata (itemflag)Unbreakable Metadata (unbreakable)Unique Identifier Metadata (unique)Adventure Mode MetadataCan-Destroy Metadata (can-destroy)Can-Place-On Metadata (can-place-on)Potion & Entity MetadataPotion Metadata (potion)Spawn Egg Metadata (spawner)Advanced MetadataNative NBT Metadata (native)Basic UsageNested Structure SupportData Mapping IntegrationMapping Syntax ExplanationPractical Application ExampleTiphareth Integration Metadata (tiphareth)Practical Metadata ExamplesEquipment ItemsMetadata LockingLocking MetadataFunctions of Locking