附加包教程：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之间，不能小于最小值。 | 整数 |
耐久魔咒影响系数：
| 魔咒等级 | 系数 |
|---|---|
| 无 | 1.0 |
| Ⅰ | 0.5 |
| Ⅱ | 0.33 |
| Ⅲ | 0.25 |
注：原版耐久附魔会影响物品被使用时掉耐久的概率，实际概率 = 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或负值会使物品无法挖掘此方块。 | 整数 |
原版工具挖掘速度参考：
| 速度值 | 对应工具类型 |
|---|---|
| 0 | 无法挖掘 |
| 2 | 木制工具 |
| 3 | 石制工具 |
| 4 | 铁制工具 |
| 6 | 钻石工具 |
| 7 | 下界合金工具 |
| 8 | 金制工具 |
- display_name 名称组件：设置物品名称。
需要格式版本：1.20.0+
"minecraft:display_name": "名称"
| 字段 | 功能描述 | 类型 |
|---|---|---|
| minecraft:display_name | 物品名称，可以指定本地化键名。 | 字符串 |
行为说明：
- 优先尝试翻译提供的字符串，翻译失败时显示原始字符串
- 未指定此组件时，游戏自动生成本地化键名：
- 旧版格式：
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 | 附魔槽位，也就是物品可附上哪些魔咒。可用值见下。 | 字符串 |
附魔槽位可用值：
| 字段 | 描述 |
|---|---|
| bow | 弓 |
| armor_feet | 靴子 |
| armor_torso | 胸甲 |
| armor_head | 头盔 |
| armor_legs | 护腿 |
| hoe | 锄 |
| axe | 斧 |
| pickaxe | 镐 |
| shovel | 锹 |
| sword | 剑 |
| elytra | 鞘翅 |
| fishing_rod | 钓鱼竿 |
| flintsteel | 打火石 |
| shears | 剪刀 |
| cosmetic_head | 生物头颅 |
| all | 全部，类似于书 |
原版物品附魔能力值：
| 物品名称或类型 | 能力值 |
|---|---|
| 木质工具 | 15 |
| 皮革服装 | 15 |
| 石质工具 | 5 |
| 锁链护甲 | 12 |
| 铁质护甲 | 9 |
| 铁质工具 | 14 |
| 金质护甲 | 25 |
| 金质工具 | 22 |
| 钻石质装备 | 10 |
| 海龟壳 | 9 |
| 下界合金质装备 | 15 |
| 其他可在附魔台附魔的物品 | 1 |
注：
- 工具指剑、镐、斧、锹和锄
- 服装指帽子、外套、裤子和靴子
- 护甲指头盔、胸甲、护腿和靴子
- 装备指剑、镐、斧、锹、锄、头盔、胸甲、护腿和靴子
-
entity_placer 实体放置组件：使物品可以放置为实体。(类似刷怪蛋)
"minecraft:entity_placer": {
"entity": "minecraft:cat",
"dispense_on": [
{
"tags": "q.any_tag('water')"
}
],
"use_on": [
"dirt" //方块 ID
]
}
| 字段 | 功能描述 | 类型 |
|---|---|---|
| entity | 要放置的实体ID。 | 字符串 |
| use_on | 仅允许在某些方块上放置，留空表示允许全部方块。 | 字符串列表或方块描述符列表 |
| dispense_on | 仅允许在某些方块上发射，留空表示允许全部方块。 | 字符串列表或方块描述符列表 |
版本说明：
当物品格式版本为1.19.80及以上时，此组件会导致物品可设置刷怪笼刷出的实体。
-
food 食物组件：使物品可以被食用。
| 字段 | 功能描述 | 类型 |
|---|---|---|
| nutrition | 回复的饥饿值，可以是负数。负数即扣除饥饿值。范围是整型的范围。 | 整数 |
| saturation_modifier | 回复的饱和度。必须是正数。计算公式：饥饿值 * 这里的值 * 2 = 饱和度。 | 浮点数 |
| can_always_eat | 是否允许在饥饿值满时食用。 | 布尔值 |
| using_converts_to | 食用后转化为物品的ID。忽略会导致物品直接消失。 | 字符串 |
饱和度新旧版本对应关系：
| 旧版 | 新版 |
|---|---|
| poor | 0.1 |
| low | 0.3 |
| normal | 0.6 |
| good | 0.8 |
| max | 1.0 |
| supernatural | 1.2 |
旧版语法说明（≤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 史诗
未完待续
