pluginiPlugin

元数据系统

为物品添加特殊功能

概述

元数据系统让你可以为物品添加特殊功能，比如自定义耐久度、属性加成、特殊效果等。通过简单的配置，你就能让物品拥有丰富的功能。

什么是元数据

元数据就是物品的附加功能配置。它们不影响物品的基本外观，但会给物品添加特殊的行为和效果。

完整元数据类型列表

基于 Zaphkiel 内部实现的所有元数据类型：

元数据类型功能示例用途
attribute属性加成攻击力、攻击速度、护甲值等属性修改
can-destroy可破坏方块列表冒险模式下限制工具可破坏的方块
can-place-on可放置方块列表冒险模式下限制方块可放置的位置
color颜色设置皮革装备染色、药水颜色
data物品数据值设置物品的 CustomModelData
icon图标材质动态更改物品材质类型
itemflag物品标志隐藏附魔、属性等信息显示
native原生NBT直接设置物品的NBT数据
potion药水效果为药水物品添加基础药水类型和自定义效果
shiny发光效果让物品产生附魔光效但不显示附魔信息
skull头颅设置自定义玩家头颅、材质头颅、HeadDatabase集成
spawner刷怪蛋类型设置刷怪蛋生成的实体类型
tipharethTiphareth集成与Tiphareth插件的材质包集成
unbreakable无法破坏设置物品为无法破坏状态
unique唯一标识为物品添加唯一标识信息

基础元数据配置

耐久度元数据

让物品拥有自定义的耐久度系统：

my_tool:
  icon: diamond_pickaxe
  display: default_display_1
  name:
    item_name: '&6魔法镐'
  data:
    durability: 100         # 自定义耐久度数值
  meta:
    durability:
      remains: minecraft:stick  # 耐久度耗尽后变成的物品
  event:
    on_damage: item damage 1    # 使用时减少耐久度

属性元数据

为物品添加属性加成：

my_sword:
  icon: diamond_sword
  name:
    item_name: '&c强力剑'
  meta:
    attribute:
      mainhand:             # 主手持有时的属性
        damage: +10         # 增加10点攻击力
        attack_speed: +20%  # 增加20%攻击速度
      offhand:              # 副手持有时的属性
        armor: +5           # 增加5点护甲值

外观与视觉元数据

颜色元数据 (color)

为皮革装备和药水设置颜色：

colored_leather_armor:
  icon: leather_chestplate
  name:
    item_name: '&c红色皮甲'
  meta:
    color: 255-0-0          # RGB格式：红-绿-蓝
 
magic_potion:
  icon: potion
  name:
    item_name: '&5紫色药水'
  meta:
    color: 128-0-128        # 紫色药水

图标元数据 (icon)

动态更改物品材质类型：

dynamic_icon_item:
  icon: stone
  name:
    item_name: '&a动态图标物品'
  meta:
    icon: diamond           # 运行时将图标改为钻石

发光元数据 (shiny)

让物品产生附魔光效但不显示附魔信息：

glowing_item:
  icon: diamond
  name:
    item_name: '&b发光钻石'
  meta:
    shiny: true             # 添加发光效果但隐藏附魔信息

头颅元数据 (skull)

自定义玩家头颅、材质头颅：

custom_skull:
  icon: player_head
  name:
    item_name: '&6自定义头颅'
  meta:
    skull:
      # 方式1：玩家名称
      owner: "Notch"
      
      # 方式2：自定义材质
      textures:
        value: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvIn19fQ=="
        id: "12345678-1234-1234-1234-123456789abc"
      
      # 方式3：HeadDatabase集成
      head-database: "1234"

功能性元数据

数据元数据 (data)

设置物品的 CustomModelData：

custom_model_item:
  icon: diamond_sword
  name:
    item_name: '&6自定义模型剑'
  meta:
    data: 1001              # 设置CustomModelData为1001

物品标志元数据 (itemflag)

隐藏物品的各种信息显示：

clean_sword:
  icon: diamond_sword
  name:
    item_name: '&c简洁剑'
  meta:
    # 在 Minecraft 1.21+ 中，要隐藏武器的默认属性（如攻击伤害、攻击速度），
    # 需要先修改这些属性，然后才能用 HIDE_ATTRIBUTES 隐藏它们
    attribute:
      mainhand:
        damage: 0          # 将攻击伤害设为 0
        attack_speed: 0    # 将攻击速度设为 0
    itemflag:
      - HIDE_ENCHANTS        # 隐藏附魔
      - HIDE_ATTRIBUTES      # 隐藏属性（需要先修改属性才能隐藏）
      - HIDE_UNBREAKABLE     # 隐藏无法破坏标志
      - HIDE_DESTROYS        # 隐藏可破坏信息
      - HIDE_PLACED_ON       # 隐藏可放置信息
      - HIDE_POTION_EFFECTS  # 隐藏药水效果

重要说明

  • 在 Minecraft 1.21+ 中，HIDE_ATTRIBUTES 标志只能隐藏被修改过的属性
  • 对于武器等有默认属性的物品，需要先使用 attribute 元数据修改这些属性（如设置为 0），然后 HIDE_ATTRIBUTES 才能生效
  • 如果只设置 HIDE_ATTRIBUTES 而不修改属性，武器的默认攻击伤害和攻击速度仍会显示

无法破坏元数据 (unbreakable)

设置物品为无法破坏状态：

unbreakable_tool:
  icon: diamond_pickaxe
  name:
    item_name: '&a永恒镐'
  meta:
    unbreakable: true       # 设置为无法破坏

唯一标识元数据 (unique)

为每个物品实例添加唯一标识：

unique_item:
  icon: diamond
  name:
    item_name: '&6独特钻石'
  meta:
    unique: true            # 为每个物品实例添加唯一标识

冒险模式元数据

可破坏方块元数据 (can-destroy)

限制工具在冒险模式下可破坏的方块：

special_pickaxe:
  icon: diamond_pickaxe
  name:
    item_name: '&6特殊镐子'
  meta:
    can-destroy:
      - minecraft:stone
      - minecraft:cobblestone
      - minecraft:iron_ore

可放置方块元数据 (can-place-on)

限制方块在冒险模式下可放置的位置：

special_block:
  icon: minecraft:dirt
  name:
    item_name: '&a特殊泥土'
  meta:
    can-place-on:
      - minecraft:grass_block
      - minecraft:stone

药水与生物元数据

药水元数据 (potion)

为药水物品添加基础药水类型和自定义效果：

magic_potion:
  icon: potion
  name:
    item_name: '&5魔法药水'
  meta:
    potion:
      base: HEALING          # 基础药水类型
      # 自定义药水效果 (效果名称: 持续时间-等级)
      SPEED: 600-1           # 速度I，持续30秒(600tick)
      STRENGTH: 1200-2       # 力量II，持续60秒
      REGENERATION: 300-1    # 再生I，持续15秒

刷怪蛋元数据 (spawner)

弃用警告

此元数据在 Minecraft 1.13+ 版本中已弃用。 从 1.13 开始，不同实体类型对应不同的刷怪蛋物品类型，无法通过 NBT 数据修改刷怪蛋的生成实体。

建议直接使用对应的刷怪蛋物品类型（如 zombie_spawn_egg、skeleton_spawn_egg 等）。

设置刷怪蛋生成的实体类型：

custom_spawn_egg:
  icon: zombie_spawn_egg
  name:
    item_name: '&c自定义刷怪蛋'
  meta:
    spawner: ZOMBIE          # 设置生成僵尸

高级元数据

根据你提供的映射支持信息，我来重新给出完整的原生NBT元数据 (native) 文档内容。

原生NBT元数据 (native)

直接设置物品的NBT数据，支持嵌套结构和数据映射：

基础用法

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

嵌套结构支持

native 元数据完全支持复杂的嵌套NBT结构：

advanced_nbt_item:
  icon: diamond_sword
  name:
    item_name: '&6高级NBT物品'
  meta:
    native:
      # 简单值
      Version: 1
      Enabled: true
      # 嵌套对象
      Zap:
        current_attributes:
          list:
            attack_damage: 123
            attack_speed: 1.6
        metadata:
          creator: "admin"
          timestamp: 1640995200
      # 多层嵌套
      CustomSystem:
        config:
          settings:
            auto_repair: true
            max_durability: 1000

数据映射集成

native 元数据与 data-mapper 数据映射完美集成，支持动态显示和数据引用

dynamic_nbt_item:
  icon: iron_sword
  name:
    item_name: '&c动态NBT物品'
  data-mapper:
    damage: it                              # 引用 data 节点中的值
    hello: it                               # 引用 data 节点中的值
    type_damage: "&Zap.type.attack_damage"  # 引用 native NBT 中的嵌套值
    current_level: "&Stats.level"           # 引用 native NBT 中的值
    current_exp: "&Stats.experience"        # 引用 native NBT 中的值
  meta:
    native:
      hello: "world"                        # 可被 data-mapper 引用
      Zap:
        type:
          attack_damage: 123                # 可通过路径引用
      Stats:
        level: 5
        experience: 1250
  display: dynamic_display
 
# display 配置
dynamic_display:
  name: '&c动态NBT物品 &7[等级 {current_level}]'
  lore:
    - '&7伤害: &e{type_damage}'
    - '&7问候: &a{hello}'
    - '&7经验值: &e{current_exp}'
    - '&7等级: &a{current_level}'

映射语法说明

在 data-mapper 中引用 native NBT 数据时，使用以下语法：

  • "&路径" - 引用 NBT 中的嵌套值，使用点号分隔路径
  • it - 引用 data 节点中的同名值
  • 支持复杂的 Kether 脚本表达式进行数据处理

实际应用示例

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: "传说之剑"
        base_damage: 100
        enhancement:
          level: 5
          bonus_damage: 25
  display: weapon_display
 
weapon_display:
  name: '&6{weapon_name} &7+{enhancement_level}'
  lore:
    - '&7基础伤害: &c{WeaponData.base_damage}'
    - '&7强化伤害: &e+{WeaponData.enhancement.bonus_damage}'
    - '&7总伤害: &a{total_damage}'

Tiphareth集成元数据 (tiphareth)

与Tiphareth插件的材质包集成：

tiphareth_item:
  icon: diamond_sword
  name:
    item_name: '&dTiphareth物品'
  meta:
    tiphareth: "custom_model_name"  # Tiphareth模型名称

实用元数据示例

装备类物品

warrior_helmet:
  icon: diamond_helmet
  name:
    item_name: '&4战士头盔'
  meta:
    attribute:
      # 头部装备时的属性
      head:
        # 护甲值 +8
        armor: +8
        # 最大生命值 +20
        max_health: +20
        # 击退抗性 +0.1
        knockback_resistance: +0.1
    # 无法破坏
    unbreakable: true
    # 隐藏属性显示
    itemflag:
      - HIDE_ATTRIBUTES
      - HIDE_UNBREAKABLE

元数据锁定

锁定元数据

使用 !! 后缀可以锁定元数据，确保配置更新后强制应用

my_weapon:
  data:
    durability!!: 200       # 锁定耐久度数值
  meta:
    durability!!:           # 锁定耐久度配置
      remains: minecraft:stick
    attribute:              # 不锁定属性配置
      mainhand:
        damage: +15

锁定的作用

  • 平衡性调整：修改武器属性后立即生效
  • 功能修复：修复元数据问题后强制更新
  • 统一标准：确保所有同类物品使用相同的元数据

目录