🔢 物品数据

简介

物品数据指的是旧版本中的物品 NBT（命名二进制标签），或 1.20.5 及以上版本中的物品组件。通过这些数据，我们可以自定义物品的各个方面，例如名称、提示框中的描述信息、属性以及 原版 Minecraft 提供的其他功能。

与其他插件的兼容性

如果您希望 CraftEngine 物品保留外部插件物品的数据，请按照以下配置进行配置：

items:
  default:example_item:
    data:
      external:
        plugin: neigeitems
        id: example_item

信息

支持的插件可以在此页面上找到。

对于使用命名空间ID的插件物品，只需使用 <命名空间>:<路径> 作为 ID。例如：

译者注：原则上不允许使用中文作为命名空间ID，请参阅此页面，还有请先查看注意事项

id: test_namespace:test/my_path

对于像 MMOItems 这样包含类型的插件，您需要使用冒号 : 将类型与标识符分隔开。例如：

id: MATERIAL:IRON_INGOT

硬编码数据

提示

在此语境中，硬编码数据意味着配置格式由插件提供和维护，这确保了跨不同版本的兼容性。这些格式由插件定义，因此它们可能与游戏本身使用的标准 NBT（命名二进制标签）或组件格式不同。这种方法的优点是插件处理所有维护工作，包括版本兼容性，因此你无需担心游戏版本之间的更改或更新。

item-name（物品名称）

控制物品的默认名称。该名称无法通过铁砧修改，不能在物品展示框中显示名称，带有该组件的旗帜在充当地图标记时也不会显示名称。此组件对物品名称的控制等级永远最低，会被其他所有影响物品名称的组件覆盖。

items:
  default:topaz_rod:
    data:
      item-name: "<!i><#FF8C00>黄玉钓竿" # 在这里我们使用 <!i> 是因为 1.20.4 及以下版本没有 item_name 组件。

custom-name（自定义名称）

控制物品的自定义名称，类似于在铁砧中设置的名称。

items:
  default:topaz_rod:
    data:
      custom-name: "<!i><#FF8C00>黄玉钓竿"

lore（物品提示框中的描述信息）

控制物品提示框中所显示的描述信息。

items:
  default:topaz_rod:
    data:
      lore: 
        - "我去这鱼竿直接把我24K狗眼闪瞎了"

unbreakable（无法破坏）

控制物品是否无法被破坏。

items:
  default:topaz_rod:
    data:
      unbreakable: true

enchantment（魔咒）

控制物品存储的魔咒信息。

items:
  default:topaz_rod:
    data:
      enchantment:
        minecraft:sharpness: 1
        custom:enchant: 3

提示

当物品类型为附魔书时，任何魔咒都将自动转换为“无活性”的魔咒。

dyed-color（所染颜色）

控制物品存储的颜色。

items:
  default:sofa:
    data:
      dyed-color: 255,255,255

custom-model-data（自定义模型数据）

items:
  default:sofa:
    data:
      custom-model-data: 100

警告

为了确保向后兼容性，此处上下文中的 custom-model-data 仅支持整数值。如果您想使用较新版本的功能，应使用 components 代替。

hide-tooltip（隐藏物品提示框）

隐藏此物品上由指定 components 提供的任何工具提示。这适用于所有版本，因为插件处理了跨版本兼容性。原名 HideFlags。

items:
  default:sofa:
    data:
      hide-tooltip:
        - dyed_color
        - enchantments
        - attribute_modifiers

attribute-modifiers（属性修饰符）

将属性修饰符应用于物品。

items:
  default:sofa:
    data:
      attribute-modifiers:
        - type: attack_speed
          amount: 1.0
          operation: add_value # add_value, add_multiplied_base, add_multiplied_total
          id: namespace:custom_attribute # 可选
          slot: any # any, hand, armor, mainhand, offhand, head, chest, legs, feet 或 body
          display: # 1.21.5
            type: override
            value: <yellow>攻击速度 +1

提示

您可以在旧版本上安全使用最新的属性名称，因为插件会帮助您进行转换。最新的属性名称可以在 https://zh.minecraft.wiki/w/属性#已知属性项上找到。

food（食物）(1.20.5+)

items:
  default:magic_apple:
    material: apple
    data:
      food: 
        nutrition: 5
        saturation: 3.5
        can-always-eat: false

提示

对于在旧版 Minecraft 中设置食物相关属性，请参阅 food。

jukebox-playable（插入唱片机所播放的音乐）(1.21+)

控制物品存储的音乐信息，以及是否能插进唱片机中播放。

items:
  default:music_stick:
    material: stick
    data:
      jukebox-playable: default:credits_music

item-model（物品模型）(1.21.2+)

控制物品的物品模型映射。

items:
  default:music_stick:
    data:
      item-model: default:music_stick

控制物品的提示框的外观。

items:
  default:topaz_rod:
    data:
      tooltip-style: minecraft:topaz #namespace:tooltip_style_id

提示

要创建物品提示框背景和边框样式，您必须将纹理放置在以下目录中：https://zh.minecraft.wiki/w/数据组件#tooltip_style

trim（盔甲纹饰）

控制物品存储的盔甲纹饰数据。提示框中会显示盔甲纹饰的名称。

trim:
  pattern: eye # 参阅下方的盔甲纹饰图案
  material: iron # 参阅下方的盔甲纹饰材料

提示

你可以从 盔甲纹饰图案 和 盔甲纹饰材料 获取到的文件名作为参数，不要带上 .json 后缀，并且请忽略以 _ 开头的文件。

equippable（可穿戴性）(1.21.2+)

控制物品是否可被生物装备穿戴。

equippable:
  # 物品可被穿戴的装备槽位
  slot: head # HEAD / CHEST / LEGS / FEET / BODY / MAIN_HAND / OFF_HAND / SADDLE
             # 头盔 / 胸甲  / 护腿  / 靴子 / 身体  / 主手      / 副手     / 鞍

  # 可选参数
  # 物品被穿戴时的装备模型的命名空间ID。
  # 此值不存在时，若装备在头部则根据物品模型渲染物品，否则什么也不会渲染。
  # 此处的目录指的是 assets/<命名空间>/equipment/<路径>.json
  asset-id: minecraft:topaz
  # 当此项存在且物品被玩家穿戴时，玩家第一人称视角将渲染指定的纹理遮罩。
  # 此遮罩可以使用多个设置此标签的物品互相叠加，每个物品指定的遮罩都会被渲染，
  # 且渲染顺序按照主手、副手、头盔、胸甲、护腿、靴子、身体、鞍的顺序依次叠加渲染。
  # 当遮罩纹理渲染时，遮罩纹理被视为独立纹理，即无法作为动态纹理或GUI纹理渲染，但可以指定纹理过滤方式。
  # 此处的目录指的是 assets/<命名空间>/textures/<路径>
  # 译者注：这里不允许使用中文作为命名空间ID
  camera-overlay: 命名空间:路径
  # 是否可以使用发射器使生物穿戴此物品。如果物品本身有特殊的发射器行为则此项无效。
  dispensable: true
  # 生物在受到会影响损害盔甲的伤害时此物品是否会受损而减少耐久。
  damage-on-hurt: true
  # 物品是否可以直接使用穿戴。
  swappable: true
  # >= 1.21.5
  # 对生物使用此物品时，是否可以让被交互的生物在允许的空槽位上穿戴此物品。
  equip-on-interact: true

自定义数据

警告

自定义数据不由插件维护，其格式可能随着 Minecraft 的更新而改变，特别是最近组件的频繁更改。

NBT (1.20-1.20.4)

注意

由于 NBT（命名二进制标签）已过时，此处不详细讨论。https://zh.minecraft.wiki/w/物品格式

items:
  default:topaz_rod:
    data:
      nbt:
        CustomModelData: 1000

组件 (1.20.5+)

自定义组件的格式严格遵循 Minecraft Wiki 的规范。下面将通过几个示例来帮助你熟悉如何配置自定义组件。示例按难度从简到繁排列，建议你依次学习，以获得丝滑的学习体验。

max_damage [★]

从图中可以看出，max_damage 接受一个 I（表示整数参数）。因此，在我们的配置中只需直接使用一个整数即可。

items:
  guide:test:
    data:
      components:
        minecraft:max_damage: 128

food [★★]

从图中可以看出，food 需要三个参数：类型为 整数 的 nutrition，类型为 单精度浮点数 的 saturation，以及类型为 布尔 的 can_always_eat。

items:
  guide:test:
    data:
      components:
        minecraft:food:
          nutrition: 4
          saturation: 2.0
          can_always_eat: false

block_state [★★]

根据此处的描述，我们需要提供 键值对，其中值必须是 字符串 类型。

items:
  default:palm_leaves:
    data:
      components:
        minecraft:block_state:
          distance: '1'
          persistent: 'false'
          waterlogged: 'false'

instrument [★★★]

当一个选项支持多种数据类型时，您可以根据具体需求选择合适的类型。

items:
  guide:horn:
    material: goat_horn
    data:
      components:
        minecraft:instrument: "seek_goat_horn"

items:
  guide:horn:
    material: goat_horn
    data:
      components:
        minecraft:instrument:
          description:
            text: "自定义乐器"
            color: "red"
          sound_event: minecraft:block.note_block.bell
          use_duration: 1
          range: 16

fireworks [★★★★]

items:
  guide:firework:
    material: firework_rocket
    data:
      components:
        minecraft:fireworks:
          flight_duration: 3
          explosions:
            - shape: small_ball
              colors: [11223344]
              fade_colors: [0]
              has_trail: true
              has_twinkle: true

移除组件 (1.20.5+)

去除物品的组件

items:
  test:item:
    data:
      remove-components:
        - minecraft:equippable

客户端侧数据

client-bound-data 仅存在于客户端侧，不涉及任何服务器端侧数据。通过使用客户端侧物品数据，您可以轻松实时更新物品提示框中的描述信息，包括 item_model 和 custom_model_data 等数据。此外，与其他插件不同，CraftEngine 的客户端侧物品数据在创造模式不会被摸坏。

警告

如果你启用了 paper-global.yml 的 enable-item-obfuscation 则需要将 minecraft:custom_data 添加到 dont-obfuscate 部分内，否则在查看其他实体时无法正确显示。

信息

只需在您的配置区域添加一个 client-bound-data 部分，然后将所需数据从之前的 data 部分移动（剪切+粘贴）到里面。

items:
  default:topaz_rod:
    client-bound-data:
      item-name: "<!i><#FF8C00>骗你的我不是黄玉钓竿"
    data:
      item-name: "<!i><#FF8C00>黄玉钓竿"

提示

client-bound-data 对冒险模式中的玩家非常有用，它允许玩家在服务器端破坏某些真自定义方块。

items:
  default:topaz_pickaxe:
    material: golden_pickaxe
    custom-model-data: 1000
    settings:
      tags:
        - "default:topaz_tools"
    client-bound-data:
      components:
        # 客户端侧方块状态
        can_break:
          blocks: minecraft:note_block
          state:
            "instrument": "hat"
            "note": "0"
            "powered": "false"
    data:
      item-name: "<!i><#FF8C00><i18n:item.topaz_pickaxe>"
      tooltip-style: minecraft:topaz
      components:
        minecraft:max_damage: 64
        # 服务端侧方块状态
        can_break:
          blocks: "craftengine:note_block_1"
    model:
      template: default:model/simplified_handheld
      arguments:
        path: "minecraft:item/custom/topaz_pickaxe"

简介​

与其他插件的兼容性​

硬编码数据​

item-name（物品名称）​

custom-name（自定义名称）​

lore（物品提示框中的描述信息）​

unbreakable（无法破坏）​

enchantment（魔咒）​

dyed-color（所染颜色）​

custom-model-data（自定义模型数据）​

hide-tooltip（隐藏物品提示框）​

attribute-modifiers（属性修饰符）​

food（食物）(1.20.5+)​

jukebox-playable（插入唱片机所播放的音乐）(1.21+)​

item-model（物品模型）(1.21.2+)​

tooltip-style（物品提示框背景和边框样式）(1.21.2+)​

trim（盔甲纹饰）​

equippable（可穿戴性）(1.21.2+)​

自定义数据​

NBT (1.20-1.20.4)​

组件 (1.20.5+)​

移除组件 (1.20.5+)​

客户端侧数据​

简介