附加包教程：7.物品（二）

前言

上期，我们成功向附加包中添加了物品，了解了物品组件。这一期，我们将继续学习物品组件。我们把所有组件和事件学习完之后，我会教你如何运用这些组件和事件。

组件列表

1.普通组件

• allow_off_hand 允许副手组件：使物品可以被放在副手。

  "minecraft:allow_off_hand": true

• block_placer 放置方块组件：使物品可以被放置为方块。

  需要格式版本：1.20.10+
  "minecraft:block_placer": {
    "block": "bedrock",
    "use_on": [
   "dirt", //泥土
   "grass" //草方块
    ],
    "replace_block_item": false
  }

  字段	功能描述	类型
  block	要放置的方块ID，不能是隐藏方块(如下界反应核)，否则放置时游戏崩溃。可以填写方块描述符。	字符串或方块描述符
  use_on	仅允许在某些方块上放置，留空表示允许全部方块。	字符串列表或方块描述符列表
  replace_block_item	替换被放置方块的物品形态。设为true时，物品的ID必须与被放置方块的ID一致。	布尔值

  旧名称：相同
  版本：~1.16.100
  旧语法：
  "minecraft:block_placer": {
    "block": "bedrock", //要放置的方块ID。
    "use_on": [ //指定允许在哪些方块上放置。
   "dirt", //泥土
   "grass" //草方块
    ],
    "use_block_description": true
  }
  旧名称：minecraft:seed
  版本：≤1.10
  旧语法：
  "minecraft:seed": {
    "crop_result": "cave_vines", //种植的作物ID（放置的方块ID）
    "plant_at": [ //可以种植（放置）在...方块上
   "cave_vines", //洞穴藤蔓
   "cave_vines_head_with_berries"  //带果实的洞穴藤蔓头
    ],
    "plant_at_any_solid_surface": true, //可以种植（放置）在任何固体表面上
    "plant_at_face": "DOWN" //种植（放置）的方块面，这里是方块的下方
  }

• bundle_interaction 收纳交互组件：指定物品有收纳袋的 UI 和交互。

  需要格式版本：1.21.40+
  必须与 minecraft:storage_item 一起用。
  "minecraft:bundle_interaction": {
    "num_viewable_slots": 64
  }

  字段	功能描述	类型
  num_viewable_slots	物品太多时显示多少种物品，范围是1到64。	整数

  注：收纳袋有分层纹理，让交互时的物品看起来真的在收纳袋里面。这个特性使用三个纹理，要在物品纹理映射到路径时指定，命名格式为 <物品名>_open <物品名>_open_front 和 <物品名>_open_back。例如：

  {
    "texture_data": {
   "my_item": {
     "textures": [
       "textures/items/my_item",
       "textures/items/my_item_open",
       "textures/items/my_item_open_back",
       "textures/items/my_item_open_front"
     ]
   }
    }
  }

  此时，点击物品后物品纹理是 my_item_open，选中物品准备取出时的物品纹理是 my_item_open_back 和 my_item_open_front 的组合。

• can_destroy_in_creative 禁用破坏组件：指定拿着物品时是否允许在创造模式下破坏方块。

  "minecraft:can_destroy_in_creative": true

• compostable 堆肥组件：使物品可以堆肥并指定堆肥概率。

  "minecraft:compostable": {
    "composting_chance": 50
  }

• cooldown 冷却组件：使物品使用后需要冷却一段时间才能继续使用。

  需要格式版本：1.20.10+
  "minecraft:cooldown": {
    "category": "custom_cooldown_type",
    "duration": 0.2
  }

  字段	功能描述	类型
  category	冷却类型。尝试使用不存在的冷却类型时，会注册为新的冷却类型。冷却类型一致的物品共享冷却时间。	字符串
  duration	冷却时间，单位是秒。设为负数会让物品图标覆盖上冷却层。	浮点数

• custom_components 自定义组件：使用由脚本定义的自定义物品组件。

  需要格式版本：1.21.10+
  "minecraft:custom_components": [
    "complementary:fish_effect",
    "complementary:apple_effect"
  ]

  字段	功能描述	类型
  minecraft :custom_components	一个或多个自定义组件的名称，自定义组件的触发器将按照顺序被触发。	字符串列表

• damage 伤害组件：指定物品造成的额外伤害。

  "minecraft:damage": 6  //必须正整数

• damage_absorption 伤害吸收组件：使物品被穿戴时，将外界伤害转化为耐久度消耗。

  "minecraft:damage_absorption": {
    "absorbable_causes": [
   "entity_attack",
   "lava"
    ]
  }  //注：需要首先指定耐久组件。

• durability 耐久组件：让物品拥有耐久度，并允许这种物品在工作台和铁砧上合并。

  需要格式版本：1.20.0+
  "minecraft:durability": {
    "damage_chance": {
   "min": 15,
   "max": 100
    },
    "max_durability": 36
  }

  字段	功能描述	类型
  max_durability	最大耐久值。	整数
  damage_chance	掉耐久的概率。	对象
  damage_chance/min	掉耐久的概率范围中的最小值，必须在0-100之间，不能大于最大值。	整数
  damage_chance/max	掉耐久的概率范围中的最大值，必须在0-100之间，不能小于最小值。	整数

耐久魔咒影响系数：

注：原版耐久附魔会影响物品被使用时掉耐久的概率，实际概率 = damage_chance × 对应附魔系数。

旧名称：minecraft:damageable
版本：~1.16.100
旧语法：
"minecraft:damageable": {
  "max_damage": 326 //耐久值
}

• digger 挖掘组件：使物品能加速挖掘方块。

  "minecraft:digger": {
  "use_efficiency": false,
  "destroy_speeds": [
    "dirt", // 方块 ID
    {
      "block": "minecraft:nether_wart_block",
      "speed": 5
    },
    {
      "block": {
        "tags": "q.any_tag('wood', 'pumpkin', 'plant')"
      },
      "speed": 4
    }
  ]
  }

  字段	功能描述	类型
  use_efficiency	是否使用效率魔咒。	布尔值
  destroy_speeds	加速挖掘的方块配置列表。	字符串列表或对象列表
  destroy_speeds/*	单个方块及其挖掘速度配置。	字符串列表或对象列表
  destroy_speeds/*/block	加速挖掘的方块ID或描述符。	字符串或方块描述符
  destroy_speeds/*/speed	挖掘速度值。设为0或负值会使物品无法挖掘此方块。	整数

原版工具挖掘速度参考：

• display_name 名称组件：设置物品名称。

  需要格式版本：1.20.0+
  "minecraft:display_name": "名称"

  字段	功能描述	类型
  minecraft:display_name	物品名称，可以指定本地化键名。	字符串

行为说明：

1. 优先尝试翻译提供的字符串，翻译失败时显示原始字符串

2. 未指定此组件时，游戏自动生成本地化键名：

   • 旧版格式：item.<命名空间ID>.name
     （示例：item.minecraft:iron_sword.name）
   • 1.16.100+新版格式：item.<命名空间ID>
     （示例：item.minecraft:iron_sword）

使用示例：

// 直接显示文本
"minecraft:display_name": "传奇宝剑"

// 使用本地化键名
"minecraft:display_name": "item.custom_sword.legendary"

• durability_sensor 耐久检测组件：检测耐久值低于某值，并播放声音或显示粒子。

  "minecraft:durability_sensor": {
  "durability_thresholds": [
    {
      "durability": 4000,
      "particle_type": "campfiresmoketall",
      "sound_event": "ambient"
    },
    {
      "durability": 1000,
      "particle_type": "shriek",
      "sound_event": "add.chest"
    }
  ]
  }

  字段	功能描述	类型
  durability_thresholds	检测阈值。同时触发时，最低阈值的优先级最高。	对象列表
  durability_thresholds/*/durability	耐久检测阈值。	整数
  durability_thresholds/*/particle_type	旧版粒子 ID。注意，不是 /particle 命令中的ID，而是旧版粒子的 ID。	字符串
  durability_thresholds/*/sound_event	声音ID。可填写的值可以参考 minecraft:record 组件的声音字段可用值。	字符串

• dyeable 染色组件：使物品可在炼药锅中染色，并指定基色。

  "minecraft:dyeable":{
  "default_color": "#17714A"
  }  //此组件需要 1.21.30+ 的版本。

• enchantable 附魔组件：使物品可被附魔。

  "minecraft:enchantable": {
  "value": 59,
  "slot": "sword"
  }

  字段	功能描述	类型
  value	附魔能力，值越高，出好附魔、高等级的概率就越大。实际使用的值在 [0, 255] 范围内。	整数
  slot	附魔槽位，也就是物品可附上哪些魔咒。可用值见下。	字符串

附魔槽位可用值：

原版物品附魔能力值：

注：

• 工具指剑、镐、斧、锹和锄
• 服装指帽子、外套、裤子和靴子
• 护甲指头盔、胸甲、护腿和靴子
• 装备指剑、镐、斧、锹、锄、头盔、胸甲、护腿和靴子

• entity_placer 实体放置组件：使物品可以放置为实体。(类似刷怪蛋)

"minecraft:entity_placer": {
  "entity": "minecraft:cat",
  "dispense_on": [
    {
      "tags": "q.any_tag('water')"
    }
  ],
  "use_on": [
    "dirt" //方块 ID
  ]
}

版本说明：
当物品格式版本为1.19.80及以上时，此组件会导致物品可设置刷怪笼刷出的实体。

• food 食物组件：使物品可以被食用。

  字段	功能描述	类型
  nutrition	回复的饥饿值，可以是负数。负数即扣除饥饿值。范围是整型的范围。	整数
  saturation_modifier	回复的饱和度。必须是正数。计算公式：饥饿值 这里的值 2 = 饱和度。	浮点数
  can_always_eat	是否允许在饥饿值满时食用。	布尔值
  using_converts_to	食用后转化为物品的ID。忽略会导致物品直接消失。	字符串

饱和度新旧版本对应关系：

旧版语法说明（≤1.10）：

"minecraft:food": {
  "saturation_modifier": "normal",  // 可使用特定字符串
  "is_meat": true,  // 是否为肉类
  "on_use_action": "chorus_teleport",  // 可选值：chorus_teleport/suspicious_stew_effect/none
  "on_use_range": [8, 8, 8],  // 紫颂果传送范围（方块）
  "cooldown_type": "chorusfruit",  // 可选值：chorusfruit/none
  "cooldown_time": 20,  // 冷却时间（刻）
  "effects": [  // 食用效果列表
    {
      "name": "regeneration",  // 效果ID
      "chance": 1.0,  // 触发概率（0.0-1.0）
      "duration": 30,  // 持续时间（秒）
      "amplifier": 4  // 效果倍率（实际等级=值+1）
    }
  ]
}

• fuel 燃料组件：使物品可以在熔炉等方块里当燃料。

  需要格式版本：1.20.0+
  "minecraft:fuel":{
  "duration": 3.0
  }
  字段    功能描述    类型
  duration    燃烧的时间（秒），以0.05为分度值，必须≥0.05。    浮点数

• glint 闪光组件：指定物品是否有带魔咒物品的光效。

  "minecraft:glint": true

  旧名称：minecraft:foil
  版本：≤~1.20
  旧语法：
  "minecraft:foil": true //物品是否有附魔的闪光。true是有，false是没有。

• hand_equipped 手持组件：指定物品是否有手持动画。

  "minecraft:hand_equipped": true

• hover_text_color 文本颜色组件：指定物品的悬停文本的颜色。

  "minecraft:hover_text_color": "material_amethyst"

  字段	功能描述	类型	备注
  minecraft: hover_text_color	控制物品悬停时的文本颜色	字符串	1. 可接受颜色代码值 2. 在 1.16-1.19 版本期间不可用 3. 旧版需通过资源包文件指定

颜色代码示例：

"minecraft:hover_text_color": "material_amethyst"

查看所有颜色

• icon 图标组件：指定物品纹理。

  字段路径	功能描述	类型	格式版本
  minecraft:icon	物品图标配置	字符串/对象	1.20.10+
  textures	图标纹理合集	对象	1.20.10+
  textures/default	默认纹理短名	字符串	1.20.10+
  textures/dyed	染色模板的灰度纹理短名	字符串	1.20.10+
  textures/icon_trim	带纹饰的物品纹饰层纹理（需完整命名空间ID）	字符串	1.20.10+

完整代码示例（1.20.10+）：

"minecraft:icon": {
  "textures": {
    "default": "custom_chestplate_icon",
    "dyed": "custom_chestplate_gray_icon",
    "icon_trim": "test:custom_chestplate"
  }
}

简化写法（1.20.10+）：

"minecraft:icon": "test"

旧版本（1.20.10-）
"minecraft:icon": {
  "texture": "custom_chestplate"
}

• interact_button 交互按钮组件：指定物品的交互按钮及文本。

  字段	功能描述	类型
  minecraft:interact_button	拿着物品时添加交互按钮，可设置按钮文字（支持本地化键名）或设为布尔值（true时显示默认"使用物品"提示）	字符串或布尔值

完整代码示例：

"minecraft:interact_button": "文本"
"minecraft:interact_button": true

• liquid_clipped 接触水面组件：指定物品是否能接触水面。

  "minecraft:liquid_clipped": true

• max_stack_size 最大堆叠组件：指定物品的最大堆叠数。

  "minecraft:max_stack_size": 1

• projectile 投掷物组件：定义物品为投掷物。

  字段	功能描述	类型	格式版本
  minimum_critical_power	暴击需要的蓄力大小	浮点数	1.20.10+
  projectile_entity	发射的实体ID（该实体必须包含minecraft:projectile组件）	字符串	1.20.10+

完整代码示例（1.20.10+）：

"minecraft:projectile": {
  "minimum_critical_power": 1.25,
  "projectile_entity": "arrow"
}

• rarity 稀有度组件：指定物品的稀有度。

  "minecraft:rarity": "common"

  以下是所有可用的稀有度。
  值    描述
  common    常见
  uncommon罕见
  rare    稀有
  epic    史诗

• record 唱片组件：指定物品为唱片。

  "minecraft:record": {
  "comparator_signal": 1,
  "duration": 5,
  "sound_event": "ambient.tame"
  }

  字段	功能描述	类型
  comparator_signal	在唱片机中播放时比较器输出的信号强度（默认1，范围[1,15]）	整数
  duration	唱片机持续生成粒子的时间长度（可为0）	浮点数
  sound_event	要播放的声音事件ID（仅支持原版声音事件）	字符串

  声音事件ID

• repairable 修复组件：使物品可以被修复。

  字段	功能描述	类型
  repair_items	可以用于修复的物品列表	字符串列表或对象列表
  repair_items/*/items	可以用于修复的物品ID列表	字符串列表
  repair_items/*/repair_amount	修复的耐久量（数值或Molang表达式） • 使用c.other访问修复物品 • 支持随机数表达式	数值/Molang

完整代码示例：

"minecraft:repairable":{
  "repair_items": [
    "anvil", //可以是单个物品ID。
    { //还可以是一个对象。
      "items": [
        "anvil" //物品ID
      ],
      "repair_amount": "math.min(q.remaining_durability + c.other->q.remaining_durability + math.floor(q.max_durability /20), c.other->q.max_durability)"
    }
  ]
}

• shooter 射手组件：使物品可以射出弹射物。

  需要格式版本：1.20.10+
  "minecraft:shooter": {
  "ammunition": [
    {
      "item": "minecraft:arrow",
      "use_offhand": true,
      "search_inventory": true,
      "use_in_creative": true
    }
  ],
  "charge_on_draw": false,
  "max_draw_duration": 0.0,
  "scale_power_by_draw_duration": true
  }

  字段	功能描述	类型
  scale_power_by_draw_duration	是否按照长按的时间增加蓄力力度	布尔值
  charge_on_draw	控制射击行为模式： - true：类似弩（长按装弹，再按发射） - false：类似弓（长按蓄力，松开发射）	布尔值
  max_draw_duration	最大蓄力时间（必须≤物品使用时间）	浮点数
  ammunition	可用弹药配置列表	对象列表
  ammunition/*/item	弹药物品ID（需含minecraft:projectile组件）	字符串
  ammunition/*/use_offhand	是否允许使用副手物品作为弹药	布尔值
  ammunition/*/search_inventory	是否从物品栏搜索弹药	布尔值
  ammunition/*/use_in_creative	创造模式是否消耗弹药	布尔值

• should_despawn 防止刷新组件：指定物品的掉落物形式是否可以被刷新而消失。

  "minecraft:should_despawn": false

• stacked_by_data 数据值堆叠组件：指定物品是否根据数据值堆叠。

  字段	功能描述	类型
  minecraft:stacked_by_data	控制物品是否根据数据值(stack data)堆叠：- true：不同数据值的物品不能堆叠，物品实体不会自动合并- false：不同数据值的物品可以堆叠，物品实体会自动合并	布尔值

完整代码示例：

"minecraft:stacked_by_data": false

• storage_item 收纳组件：指定物品有收纳袋的功能。

  字段	功能描述	类型	格式版本
  minecraft:storage_item	收纳袋物品配置	对象	1.21.40+
  max_slots	能存储的物品种类数（范围1-64）	整数	1.21.40+
  allow_nested_storage_items	是否允许嵌套其他收纳袋	布尔值	1.21.40+
  banned_items	禁止放入的物品ID列表	字符串列表	1.21.40+
  allowed_items	允许放入的物品ID列表（留空表示允许所有）	字符串列表	1.21.40+

完整代码示例（1.21.40+）：

"minecraft:storage_item": {
  "max_slots": 64,
  "allow_nested_storage_items": true,
  "banned_items": [
    "minecraft:shulker_box",
    "minecraft:undyed_shulker_box"
  ],
  "allowed_items": []
}

旧版语法（<1.21.30.23）

"minecraft:item_storage": {
  "capacity": 64
}

物品数量 / 最大堆叠数 * 64 = 占用容量

• storage_weight_limit 最大收纳容量：指定收纳袋类物品的最大收纳容量。

  "minecraft:storage_weight_limit": {
  "max_weight_limit": 64
  }
  收纳袋的最大容量，填写正整数，不能超过 64。容量公式：物品数量 / 最大堆叠数 * 64

• storage_weight_modifier 占用容量修饰符：指定物品在收纳袋类容器中占用的容量。

  "minecraft:storage_weight_modifier": {
  "weight_in_storage_item": 4
  }
  

• tags 标签组件：指定物品的标签。

  这个组件取代了以前的 "tag:xxx": {} 。
  "minecraft:tags": {
  "tags": [
    "minecraft:is_food"
  ]
  }

  标签名称	功能说明
  minecraft:is_sword	标记物品为剑
  minecraft:is_pickaxe	标记物品为镐
  minecraft:is_axe	标记物品为斧
  minecraft:is_shovel	标记物品为锹
  minecraft:is_hoe	标记物品为锄
  minecraft:is_shears	标记物品为剪刀
  minecraft:is_food	标记物品为食物
  minecraft:is_meat	标记物品为肉类食物
  minecraft:is_crop	标记物品为作物
  minecraft:transform_materials	锻造台升级材料
  minecraft:transformable_items	可升级装备
  minecraft:transform_templates	装备升级模板
  minecraft:trim_materials	盔甲纹饰材料
  minecraft:trimmable_armors	可添加纹饰的盔甲
  minecraft:trim_templates	盔甲纹饰模板
  minecraft:bookshelf_books	可放入雕纹书架的书籍
  minecraft:decorated_pot_sherds	饰纹陶罐碎片
  minecraft:lectern_books	可放置在讲台上的书籍
  minecraft:stone_tool_materials	可替代圆石制作石质工具的材料

  此外，给物品添加标签可以让物品参与使用标签作为输入的配方。

• throwable 投掷组件：使物品可以被投掷。

基础信息

参数表格

旧版本参数（风弹专用）

代码示例

"minecraft:throwable": {
  "do_swing_animation": false,
  "launch_power_scale": 1.0,
  "max_draw_duration": 0.0,
  "min_draw_duration": 0.0,
  "max_launch_power": 1.0,
  "scale_power_by_draw_duration": false
}

• minecraft:use_animation 组件

可用动画类型

1 * 表示需要特定类型的物品才能正确显示动画

代码示例

{
  "minecraft:use_animation": "drink"
}

• use_modifiers 使用修饰符组件：指定物品使用的效果。

代码示例

// 新版本语法（1.20.10+）
"minecraft:use_modifiers": {
  "use_duration": 1.6,
  "movement_modifier": 0.35
}

// 旧版设置（≤1.20.40）
"minecraft:use_duration": 1.1

// 旧版系统（≤1.20.40） 
"minecraft:chargeable": {
  "movement_modifier": 0.0,
  "on_complete": {
    "event": "use_complete",
    "target": "self"
  }
}

• wearable 穿戴组件：让物品可以被穿戴，并提供护甲值。

可用装备槽位

新旧版本对比

// 新版语法（1.20.20+）
"minecraft:wearable": {
  "protection": 5,
  "slot": "slot.armor.chest"
}

// 旧版语法（≤1.20.20）
"minecraft:armor": {
  "protection": 5,
  "texture_type": "diamond"  // 已废弃参数
}

2.已废弃组件和已移除组件

一些组件已被废弃或移除，非常不建议使用已废弃组件，现已无法使用已移除组件。这种东西肯定没人看,就不写了。

杂项

完整示例：

{
  "description": {
    "identifier": "complementary:example",
    "menu_category": {
      "category": "equipment",
      "group": "minecraft:itemGroup.name.cookedFood",
      "is_hidden_in_commands": false
    }
  }
}

menu_category 可用值说明

重要说明：

• 当设置为 none 时：

  • 物品将完全从创造模式物品栏移除
  • 只能通过命令或合成获取该物品
  • 不影响物品在生存模式中的正常使用

::: tip 你知道吗？

在 1.21.40 以前的格式版本中，true 可以写为 1，false 可以写为 0，反之亦然。

浮点数可以写为整数，例如本应写为 2.0 的值可以写为 2。1.21.40 及以后，JSON 语法分析程序更加严格，不再允许这么写。

item_properties 字段可能出现在与组件同级的位置，是一个含有物品属性的对象，其作用未知。

一些物品的定义文件中可能会出现一些例如 minecraft:armor_toughness 的组件，但这些组件没有任何作用。

这说明某些情况下，无效组件并不会引发内容日志。
:::

开发计划

• 注：以下内容可能不准确或不会实现。
• 通过SAPI获取收纳袋存储的物品。
• 添加物品组。（已实现）
• 添加物品属性。（中长期）
• 添加物品动态纹理。（中长期）
• 添加onEquip和onUnequip触发器。（中长期）
• 重新添加 minecraft:knockback_resistance 这样的组件。
• 扩展盔甲纹饰。（很久以后）
• 添加物品存储实体的功能。（很久以后）
• 目前不会添加自定义唱片。
• 目前不会添加自定义创造模式物品栏的标签页。
  模板包，请解压.zip