iPlugin | Metadata System

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 Type	Function	Example Usage
`attribute`	Attribute bonuses	Modify attributes like attack damage, attack speed, and armor value
`can-destroy`	List of breakable blocks	Restrict blocks a tool can break in Adventure mode
`can-place-on`	List of placeable blocks	Restrict positions where a block can be placed in Adventure mode
`color`	Color setting	Dye leather armor, set potion colors
`data`	Item data value	Set the CustomModelData of an item
`icon`	Icon material	Dynamically change the item's material type
`itemflag`	Item flags	Hide displays of enchantments, attributes, etc.
`native`	Native NBT	Directly set the item's NBT data
`potion`	Potion effects	Add base potion types and custom effects to potion items
`shiny`	Glowing effect	Make items glow like enchanted ones without showing enchantment info
`skull`	Skull settings	Custom player skulls, textured skulls, HeadDatabase integration
`spawner`	Spawn egg type	Set the entity type spawned by a spawn egg
`tiphareth`	Tiphareth integration	Integrate with the Tiphareth plugin's resource pack
`unbreakable`	Unbreakable status	Set items to be unbreakable
`unique`	Unique identifier	Add 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

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

Metadata System