跳到主要内容

🗡️ 物品

概述​

每个自定义物品都是 items: 下的一个条目，并使用 namespace:path 作为唯一 ID（如 default:topaz_sword）。物品由若干彼此独立的配置段组成，可以按需添加。省略 material 时会使用 config.yml 中的默认值；如果条目本身使用原版物品 ID，则会忽略 material。

结构​

每个物品都遵循同一套骨架。每个顶层键回答一个问题：

items:
  default:my_item:            # 物品 ID，其他地方都用 default:my_item 引用
    material: paper           # 可选  → 基于哪个原版物品（默认值见 config.yml）
    data:                     # 可选  → 携带什么数据组件（名称、描述、附魔……）
      ...
    model:                    # 可选  → 长什么样
      ...
    behavior:                 # 可选  → 交互行为（放置方块、放置家具……）
      ...
    settings:                 # 可选  → 插件驱动的特性（燃料、标签、可修复、可附魔……）
      ...
    events:                   # 可选  → 对事件的响应
      ...

除了以上配置段，物品上还有几个根级字段：custom_model_data、item_model、hand_animation_on_swap、oversized_in_gui、swap_animation_scale。原版物品 ID 还可以使用 override_data 修改默认数据。详见物品模型 → 根字段与物品数据 → 覆写原版物品数据。

配置段​

快速上手​

1. 最简物品​

最简单的物品只需指定一张贴图。省略 material 时会使用 config.yml 中的默认值：

items:
  default:ruby:
    material: paper
    texture: minecraft:item/custom/ruby

2. 添加名称和手持模型​

通过 data 设置显示名称，并选择工具类 material，即可获得对应的 3D 手持效果：

items:
  default:ruby_sword:
    material: golden_sword
    texture: minecraft:item/custom/ruby_sword
    data:
      item_name: "<!i><#FF8C00>Ruby Sword"
      lore:
        - "Forged in the depths"

3. 让它能放置方块​

添加 behavior 后，玩家便可右键放置对应的自定义方块：

items:
  default:ruby_sword:
    material: golden_sword
    texture: minecraft:item/custom/ruby_sword
    data:
      item_name: "<!i><#FF8C00>Ruby Sword"
    behavior:
      type: block_item
      block: default:ruby_block

4. 完整配置模型、属性和设置​

需要精确控制时，可以用完整模型定义替代简化的 texture，并添加战斗属性和工具标签：

items:
  default:ruby_sword:
    material: golden_sword
    custom_model_data: 10001
    data:
      item_name: "<!i><#FF8C00>Ruby Sword"
      attribute_modifiers:
        - type: attack_damage
          amount: 7
          operation: add_value
          slot: mainhand
    model:
      type: minecraft:model
      path: minecraft:item/custom/ruby_sword
      generation:
        parent: minecraft:item/handheld
        textures:
          layer0: minecraft:item/custom/ruby_sword
    settings:
      tags:
        - minecraft:swords
    behavior:
      type: block_item
      block: default:ruby_block

按目标查找配置​

目标参考页面
设置物品名称、描述、附魔物品数据
做成食物物品数据 → food
修改原版物品类型的默认数据物品数据 → 覆写原版物品数据
创建简单的 2D 或手持模型物品模型 → 简化模型
做弓、弩、钓鱼竿模型物品模型 → 简化模型
构建复杂的模型映射物品模型 → 模型类型
添加着色（染色盔甲、草色、药水……）模型 → Tints
让物品放置方块方块物品
让物品放置家具家具物品
设置耐久度物品数据 → max_damage
响应事件（食用、攻击、点击）事件
配置更新后迁移已有物品物品更新器
将展示数据保存在客户端（付费版）物品数据 → 客户端绑定数据