附加包教程：7.物品（二）
本帖最后由 Cat_Anchor 于 2026-6-13 10:42 编辑前言
上期，我们成功向附加包中添加了物品，了解了物品组件。这一期，我们将继续学习物品组件。我们把所有组件和事件学习完之后，我会教你如何运用这些组件和事件。
https://klpbbs.com/static/image/hrline/line1.png
组件列表
| 普通组件
allow_off_hand允许副手组件：使物品可以被放在副手。
"minecraft:allow_off_hand": true字段功能描述类型
minecraft:allow_off_hand是否允许物品被放在副手。布尔值
block_placer放置方块组件：使物品可以被放置为方块。
需要格式版本：1.20.10+"minecraft:block_placer": {
"block": "bedrock",
"use_on": [
"dirt", // 泥土
"grass" // 草方块
],
"replace_block_item": false,
"aligned_placement": true
}字段功能描述类型
block要放置的方块ID，不能是隐藏方块（如下界反应核），否则放置时游戏崩溃。可以填写方块描述符。字符串或方块描述符
use_on仅允许在某些方块上放置，留空表示允许全部方块。字符串列表或方块描述符列表
replace_block_item替换被放置方块的物品形态。设为 true 时，物品的 ID 必须与被放置方块的 ID 一致。布尔值
aligned_placement是否可以将方块放置到刚才放置的方块的玩家正在移动的方向的面上。换句话说，是否允许使用此物品快速搭桥。默认为 false。布尔值旧名称：相同
版本：~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" // 种植（放置）的方块面，这里是方块的下方，可以是 UP 或 DOWN
}
bundle_interaction收纳交互组件：指定物品有收纳袋的 UI 和交互。
需要格式版本：1.21.40+
必须与 minecraft:storage_item 一起用。"minecraft:bundle_interaction": {
"num_viewable_slots": 64
}
字段功能描述类型
num_viewable_slots物品太多时显示多少种物品，范围是 1 到 64。整数
注：收纳袋有分层纹理，让交互时的物品看起来真的在收纳袋里面。这个特性使用两个纹理，需要在物品的图标组件中通过 bundle_open_back 字段和 bundle_open_front 字段指定对应的纹理短名。
can_destroy_in_creative禁用破坏组件：指定拿着物品时是否允许在创造模式下破坏方块。
"minecraft:can_destroy_in_creative": true字段功能描述类型
minecraft:can_destroy_in_creative把这个物品拿在手上而且处于创造模式时，可不可以破坏方块。布尔值
compostable堆肥组件：使物品可以堆肥并指定堆肥概率。
需要格式版本：1.21.60+"minecraft:compostable": {
"composting_chance": 50
}字段功能描述类型
composting_chance物品转变为一层肥料的概率，范围是 。50 表示 50% 的概率。整数
cooldown冷却组件：使物品使用后需要冷却一段时间才能继续使用。
需要格式版本：1.20.10+"minecraft:cooldown": {
"category": "custom_cooldown_type",
"type": "attack",
"duration": 0.2
}字段功能描述类型
category冷却类型。尝试使用不存在的冷却类型时，会注册为新的冷却类型。冷却类型一致的物品共享冷却时间。spear 为原版矛的冷却类型。字符串
type以互斥的方式定义冷却所适用的动作，因此一个动作类型的冷却不会影响另一个动作类型。可以是 attack 或 use，默认是 use。字符串
duration冷却时间，单位是秒。设为负数会让物品图标覆盖上冷却层。浮点数
custom_components自定义组件：使用由脚本定义的自定义物品组件。
需要格式版本：1.21.10 - 1.21.70。
在 1.21.80 及以上的版本中，开启“自定义组件 V2”实验性玩法或功能正式实装后，由于自定义组件的扁平化，此组件被弃用。"minecraft:custom_components": [
"complementary:fish_effect",
"complementary:apple_effect"
]字段功能描述类型
minecraft:custom_components一个或多个自定义组件的名称，自定义组件的触发器将按照顺序被触发。字符串列表
damage伤害组件：指定物品造成的额外伤害。
"minecraft:damage": 6字段功能描述类型
minecraft:damage武器造成的伤害，必须是正整数。此组件的值在 32767 及以下是安全的，但如果设为更大的值，由于溢出，有可能造成负值伤害。整数
damage_absorption伤害吸收组件：使物品被穿戴时，将外界伤害转化为耐久度消耗。
"minecraft:damage_absorption": {
"absorbable_causes": [
"entity_attack",
"lava"
]
}字段功能描述类型
absorbable_causes可吸收伤害的类型。字符串列表注：需要首先指定耐久度组件。
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加速挖掘的方块。字符串或方块描述符
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`，`1.16.100` 及以上的新版物品是 `item.物品命名空间 ID`。
可以使用 `%` 进行部分本地化。从 `%` 开始，到这一行结束，都会被视为本地化键名（需要测试），而它前面的部分不会被处理。例如：
```json
// 物品定义
"minecraft:display_name": "这里不会被翻译。%item.complementary:test.name\n§d带颜色的文本：%item.complementary:test.desc"
// 语言文件
item.complementary:test.name=物品名称
item.complementary:test.desc=物品描述
```
将显示为
```text
这里不会被翻译。物品名称
§d带颜色的文本：物品描述
```
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 乘上下面的对应值。等级值
无耐久魔咒1.0
Ⅰ0.5
Ⅱ0.33
Ⅲ0.25旧名称：minecraft:damageable
版本：~1.16.100
旧语法：
"minecraft:damageable": {
"max_damage": 326 //耐久值
}
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"
}字段功能描述类型
default_color默认染色颜色。可选，如果忽略这个字段，那么物品默认没有染色效果。在装染色水的炼药锅中染色后，纹理会变成 minecraft:icon 组件中 dyed 字段指定的纹理加上炼药锅中水的颜色。字符串注：此组件需要 1.21.30+ 的格式版本。
enchantable附魔组件：使物品可被附魔。
"minecraft:enchantable": {
"value": 59,
"slot": "sword"
}字段功能描述类型
value附魔能力，值越高，出好附魔、高等级的概率就越大。实际使用的值在 范围内。整数
slot附魔槽位，也就是物品可附上哪些魔咒。可用值见下。字符串以下是附魔槽位的可用值。字段描述
bow弓
armor_feet靴子
armor_torso胸甲
armor_head头盔
armor_legs护腿
hoe锄
axe斧
pickaxe镐
shovel锹
sword剑
elytra鞘翅
fishing_rod钓鱼竿
carrot_stick胡萝卜钓竿
flintsteel打火石
shears剪刀
cosmetic_head生物头颅
spear三叉戟
melee_spear矛
all全部，类似于书
none无
g_armor（未知）
g_tool（未知）
g_digging（未知）以下是原版物品的附魔能力。物品名称或类型能力值
木质工具15
皮革服装15
石质工具5
锁链护甲12
铁质护甲9
铁质工具14
金质护甲25
金质工具22
钻石质装备10
海龟壳9
下界合金质装备15
其他可在附魔台附魔的物品1注：工具指剑、镐、斧、锹和锄，服装指帽子、外套、裤子和靴子，护甲指头盔、胸甲、护腿和靴子，装备指剑、镐、斧、锹、锄、头盔、胸甲、护腿和靴子。
entity_placer放置实体组件：使物品可以放置为实体。
需要格式版本：1.20.0+"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 及以上时，此组件会导致物品可设置刷怪笼刷出的实体。
fire_resistant免疫火焰组件：指定物品的掉落物免疫火焰和熔岩伤害。
"minecraft:fire_resistant": {
"value": true
}字段功能描述类型
value是否免疫火焰和熔岩伤害，true 为免疫，false 为不免疫，默认值为 false。布尔值注意，此组件必须使用含 value 的对象赋值，不能直接指定值。
food食物组件：使物品可以被食用。
"minecraft:food": {
"nutrition": 4,
"saturation_modifier": 0.6,
"can_always_eat": true,
"using_converts_to": "bowl"
}字段功能描述类型
nutrition回复的饥饿值，可以是负数。负数即扣除饥饿值。范围是整型的范围。整数
saturation_modifier回复的饱和度。必须是正数。计算公式：饥饿值 * 这里的值 * 2 = 饱和度。浮点数
can_always_eat是否允许在饥饿值满时食用。布尔值
using_converts_to食用后转化为物品的ID。忽略会导致物品直接消失。字符串以下是旧版饱和度字符串与新版本饱和度数值的对应关系。旧版新版
poor0.1
low0.3
normal0.6
good0.8
max1.0
supernatural1.2旧名称：相同
版本：≤1.10
旧语法：
"minecraft:food": {
"saturation_modifier": "normal", // 可以用特定的字符串代替饱和度数字，这个用法直到~1.19才移除。下方列出了所有可填的字符串和对应的饱和度值。
"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 = 等级）
},
{ // 另一项效果，其中字段含义与上面相同
"name": "fire_resistance",
"chance": 1.0,
"duration": 300,
"amplifier": 0
}
]
}
fuel燃料组件：使物品可以在熔炉等方块里当燃料。
需要格式版本：1.20.0+"minecraft:fuel":{
"duration": 3.0
}字段功能描述类型
duration燃烧的时间（秒），以0.05为分度值，必须≥0.05。浮点数
glint闪光组件：指定物品是否有带魔咒物品的光效。
"minecraft:glint": true字段功能描述类型
minecraft:glint物品是否有魔咒的闪光效果，忽略实际上是否有魔咒。布尔值旧名称：minecraft:foil
版本：≤~1.20
旧语法：
"minecraft:foil": true //物品是否有附魔的闪光。true是有，false是没有。
hand_equipped手持组件：指定物品是否有手持动画。
"minecraft:hand_equipped": true字段功能描述类型
minecraft:hand_equipped物品是否有装备在手上的效果（物品竖立，就像握在手中）。布尔值
hover_text_color文本颜色组件：指定物品的悬停文本的颜色。
"minecraft:hover_text_color": "material_amethyst"字段功能描述类型
minecraft:hover_text_color物品的悬停文本的颜色。选中这个物品时，它的名字会被这个组件改变颜色。可以填写颜色代码，这里有所有颜色代码。字符串注：此组件在很长一段时间内（~1.16-~1.19）曾不可用，在旧版物品中则需要在资源包文件中指定此组件。
icon图标组件：指定物品纹理。
需要格式版本：1.20.10+"minecraft:icon": {
"textures": {
"default": "custom_chestplate_icon",
"dyed": "custom_chestplate_gray_icon",
"icon_trim": "test:custom_chestplate",
"bundle_open_back": "custom_bundle_back",
"bundle_open_front": "custom_bundle_front"
}
}字段功能描述类型
textures图标纹理合集。对象
textures/default默认纹理短名。字符串
textures/dyed染色模板的纹理短名，需要一个灰度纹理。字符串
textures/icon_trim带纹饰的物品的纹饰层纹理。只能填写物品的命名空间ID，否则似乎没有作用。字符串
textures/bundle_open_back物品有收纳袋的功能时，打开的收纳袋的背景层纹理。字符串
textures/bundle_open_front物品有收纳袋的功能时，打开的收纳袋的前景层纹理。字符串还可以这么写。"minecraft:icon": "test"字段功能描述类型
minecraft:icon默认纹理短名。字符串旧名称：minecraft:icon
版本：≤约1.20
旧语法：
"minecraft:icon": {
"texture": "custom_chestplate" //指定纹理短名。
}
interact_button交互按钮组件：指定物品的交互按钮及文本。
"minecraft:interact_button": "文本"字段功能描述类型
minecraft:interact_button拿着物品时添加一个交互按钮，并设置按钮上的文字为“文本”，可以使用本地化键名。也可以为布尔值，如果设置为true则有默认的“使用物品”提示。字符串或布尔值
kinetic_weapon动能武器组件：使物品使用时可以根据速度对实体造成伤害。
玩家使用带此组件的物品时，每刻都会对视野范围内直线上的所有无障碍的实体造成伤害和其他效果。伤害的计算基于玩家和实体投影到视图上的速度向量的点积。玩家和实体越互相靠近对方，实体方向越与视图向量对齐，伤害越高。使用 damage_multiplier 和 damage_modifier 计算修正伤害后，结果会被向下取整，作为最终的修正伤害。"minecraft:kinetic_weapon": {
"delay": 8,
"reach": {
"min": 2.0,
"max": 4.5
},
"creative_reach": {
"min": 2.0,
"max": 7.5
},
"hitbox_margin": 0.25,
"damage_multiplier": 1.2,
"damage_modifier": 0.0,
"damage_conditions": {
"max_duration": 175,
"min_relative_speed": 4.6
},
"knockback_conditions": {
"max_duration": 70,
"min_speed": 5.1
},
"dismount_conditions": {
"max_duration": 50,
"min_speed": 9.0
}
}字段功能描述类型
delay造成伤害和击退效果前等待的时间，以刻为单位，一秒是 20 刻。整数
reach沿着视图向量的可以击中实体的范围。对象
reach/min范围的最小值。浮点数
reach/max范围的最大值。浮点数
creative_reach创造模式下，沿着视图向量的可以击中实体的范围。对象
hitbox_margin检测实体的容差，以方块为单位。浮点数
damage_multiplier通过点积计算出伤害后，伤害会乘以这个值，得到第一个修正伤害。浮点数
damage_modifier第一个修正伤害加上这个值（可以为负），得到第二个修正伤害。它向下取整，得到最终的修正伤害。浮点数
damage_conditions应用伤害需要满足的条件。对象
knockback_conditions应用击退需要满足的条件。对象
dismount_conditions击落骑乘者需要满足的条件。对象
max_duration经过 delay 后，可以应用效果的时间（以刻为单位）。时间超过这个值，则不能造成对应效果。整数
min_relative_speed应用效果所需的玩家相对于实体（通过点积投影到视图向量上的）最小相对速度，单位为米每秒。浮点数
min_speed应用效果所需的（通过点积投影到视图向量上的）最小玩家速度，单位为米每秒。浮点数
注意：对于 damage_conditions knockback_conditions dismount_conditions 三个字段，如果省略其中任意字段，则相应的效果不会应用；
max_duration min_relative_speed min_speed 为 damage_conditions knockback_conditions dismount_conditions 的共通字段；
需要物品有 minecraft:use_modifiers 物品组件。
liquid_clipped接触水面组件：指定物品是否能接触水面。
"minecraft:liquid_clipped": true字段功能描述类型
minecraft:liquid_clipped拿着物品是否能接触水面。主要用于放置船或睡莲。布尔值
max_stack_size最大堆叠组件：指定物品的最大堆叠数。
"minecraft:max_stack_size": 1字段功能描述类型
minecraft:max_stack_size最大堆叠数量，正整数，范围是 1 - 64。整数
piercing_weapon穿刺武器组件：使物品可以穿刺攻击实体。
使物品可以对沿玩家视线方向的直线上的所有实体造成伤害。带有此组件的物品不能破坏方块，因为无论玩家看向什么，攻击动作总是优先的。"minecraft:piercing_weapon": {
"reach": {
"min": 2.0,
"max": 4.5
},
"creative_reach": {
"min": 2.0,
"max": 4.5
},
"hitbox_margin": 0.25
}字段功能描述类型
reach沿着视图向量的可以击中实体的范围。对象
reach/min范围的最小值。浮点数
reach/max范围的最大值。浮点数
creative_reach创造模式下，沿着视图向量的可以击中实体的范围。对象
hitbox_margin检测实体的容差，以方块为单位。浮点数
projectile投掷物组件：定义物品为投掷物。
需要格式版本：1.20.10+"minecraft:projectile": {
"minimum_critical_power": 1.25,
"projectile_entity": "arrow"
}字段功能描述类型
minimum_critical_power暴击需要的蓄力大小。浮点数
projectile_entity发射的实体 ID，此实体必须有 minecraft:projectile 组件（同名）。字符串有此组件的物品可用于 minecraft:shooter 组件中的弹药，也可以放进发射器里发射。
rarity稀有度组件：指定物品的稀有度。
"minecraft:rarity": "common"字段功能描述类型
minecraft:rarity填写物品稀有度，优先级低于 minecraft:hover_text_color。可用的稀有度见下。字符串以下是所有可用的稀有度。
值描述
common常见
uncommon罕见
rare稀有
epic史诗
record唱片组件：指定物品为唱片。
"minecraft:record": {
"comparator_signal": 1,
"duration": 5,
"sound_event": "ambient.tame"
}字段功能描述类型
comparator_signal在唱片机中播放时比较器输出的信号强度。默认是 1，可以填写任何数字，但会被钳制到 的范围。整数
duration唱片机持续生成粒子的时间长度，可以是 0。浮点数
sound_event要播放的声音，可以填写存档声音事件 ID 或声音 ID。如果填写原版唱片使用的声音事件 ID，那么这个物品会有原版唱片的描述（显示它的作者），播放时也会提示与原版唱片相同的内容。如果填写声音 ID 以播放自定义声音，那么可以使用 item.record_<id>.desc 翻译描述文本，其中 id 是以 . 为分界分隔声音 ID 得到的最后一部分字符串。字符串这里有声音事件 ID 的列表。
repairable修复组件：使物品可以被修复。
需要格式版本：1.20.10+"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)"
}
]
}字段功能描述类型
repair_items可以用于修复的物品。字符串列表或对象列表
repair_items/*/items可以用于修复的物品。字符串列表
repair_items/*/repair_amount修复的耐久量，填写数值或者 Molang 表达式。c.other 用于访问用于修复的物品。可以使用会生成随机数的 Molang 表达式。整数或字符串
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字段功能描述类型
minecraft:should_despawn物品的掉落物形式是否可以被刷新掉。布尔值
stacked_by_data数据值堆叠组件：指定物品是否根据数据值堆叠。
"minecraft:stacked_by_data": true字段功能描述类型
minecraft:stacked_by_data是否根据物品的数据值堆叠。如果是 true，则有不同数据值的同一物品不能堆叠，而且多个物品实体无法合为一个。如果是 false，则有不同数据值的同一物品可以堆叠，而且多个物品实体会自动合为一个，只要相互接近。布尔值
storage_item收纳组件：指定物品有收纳袋的功能。
需要格式版本：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": []
}字段功能描述类型
max_slots能存物品的种类数，范围是 1 到 64。整数
allow_nested_storage_items是否能嵌套收纳袋。布尔值
banned_items禁止放进收纳袋的物品 ID。字符串列表
allowed_items允许放进收纳袋的物品 ID，留空表示允许所有物品。字符串列表旧名称：minecraft:item_storage
版本：＜1.21.30.23
旧语法：
"minecraft:item_storage": {
"capacity": 64 //最大容量
}
一个物品占用的容量可用以下公式计算：物品数量 / 最大堆叠数 * 64 = 占用容量。如 53 个火把占用 53 / 64 * 64 = 53 的容量，7 个雪球占用 7 / 16 * 64 = 28 的容量，1 把钻石剑占用 1 / 1 * 64 = 64 的容量。但也有特殊情况，收纳袋占用 4 加上它自身被使用的容量，潜影盒不能放进收纳袋。
基岩版 1.19.70 以后，此组件就被移除了。在此之前，收纳袋的 UI 经过多次更改。请选择 1.19.60 的测试版（如 1.19.60.24）进行使用。
在开发者版本 1.19.80 中，此组件被直接赋值以决定容量（物品格式版本为 1.16.0），但在正式版本这么做会报错。
在开发者版本 1.20.0 中，未装东西的收纳袋纹理被更改了，但它仍然使用此组件，并且可以正常使用。
收纳袋已于 1.21.30.23 加入。
storage_weight_limit最大收纳容量：指定收纳袋类物品的最大收纳容量。
物品必须不可堆叠，而且必须有 minecraft:storage_item 组件。"minecraft:storage_weight_limit": {
"max_weight_limit": 64
}字段功能描述类型max_weight_limit收纳袋的最大容量，填写正整数，不能超过 64。容量公式：物品数量 / 最大堆叠数 * 64整数
storage_weight_modifier占用容量修饰符：指定物品在收纳袋类容器中占用的容量。
"minecraft:storage_weight_modifier": {
"weight_in_storage_item": 4
}字段功能描述类型weight_in_storage_item物品本身占用的容量，范围是 0 到 64。0 表示不能放进其他收纳袋里。整数
swing_duration挥舞时长：指定物品挥舞动画的时长。
"minecraft:swing_duration": {
"value": 1.25
}字段功能描述类型value挖掘或攻击时物品摆动 / 挥舞动画的持续时间。不影响实际效果。整数
swing_sounds挥舞声音：指定挥舞物品时发出的声音。
"minecraft:swing_sounds": {
"attack_miss": "item.spear.attack_miss",
"attack_hit": "item.spear.attack_hit",
"attack_critical_hit": "item.spear.attack_hit"
}字段功能描述类型
attack_miss攻击因实体无敌而未造成伤害或未命中时播放的声音。字符串
attack_hit攻击命中时播放的声音。字符串
attack_critical_hit攻击命中并造成暴击伤害时播放的声音。字符串注意：至少需要指定一个字段。
tags标签组件：指定物品的标签。
这个组件取代了以前的 "tag:xxx": {} 。"minecraft:tags": {
"tags": [
"minecraft:is_food"
]
}字段功能描述类型
tags物品拥有的标签，标签可以带命名空间，也可以不带。字符串列表
大部分标签没有现成的用途，但有些标签被游戏赋予了内置功能。下面我会列出这些功能。
字段描述
minecraft:is_spear矛
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投掷组件：使物品可以被投掷。
需要格式版本：1.20.10+
需要 minecraft:projectile 组件以指定要投掷的实体。"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
}字段功能描述类型
do_swing_animation投掷时是否有动画。布尔值
launch_power_scale蓄力增加的程度。可以是任何数字，如果是负数，那么投掷物向反方向发射。浮点数
max_draw_duration最大长按蓄力时间。设为小于等于 0 的值会导致立即发射。浮点数
min_draw_duration最小长按蓄力时间，长按时间小于这个会导致投掷不出去。设为小于等于 0 的值会导致立即发射。浮点数
max_launch_power能蓄的最大力量，可以是负数。浮点数
scale_power_by_draw_duration是否按照长按的时间增加蓄力力度。布尔值旧名称：minecraft:throwable
版本：~1.21
旧语法：
"minecraft:throwable": {
"do_swing_animation": false,
"launch_power_scale": 1.0,
"max_draw_duration": 0.0,
"max_launch_power": 1.0,
"min_draw_duration": 0.0,
"scale_power_by_draw_duration": false,
"default_offset_scale": 0.8, //（风弹）偏移比例。
"inside_block_offset_scale": 0.05 //（风弹）方块内偏移比例。
}
use_animation使用动画组件：指定物品的使用动画和音效。
"minecraft:use_animation": "eat"字段功能描述类型
minecraft:use_animation使用时的动画和音效。所有可用值见下。字符串以下是所有可用值和它们的解释，带 * 表示需要特定附着物。值描述
eat食用食物
drink饮用液体
bow拉弓*
crossbow拉弩*
camera相机拍照
spyglass望远镜*
spear三叉戟*
brush刷扫
block举盾*
none无动画
use_modifiers使用修饰符组件：指定物品使用的效果。
"minecraft:use_modifiers": {
"use_duration": 1.6,
"movement_modifier": 0.35,
"emit_vibrations": true,
"start_sound": "",
"start_using": "if_first"
}字段功能描述类型
use_duration使用这个物品需要的时长。浮点数
movement_modifier使用这个物品时的速度修饰符。可选，必须在 之间。浮点数
emit_vibrations使用物品时是否发出振动。需要格式版本 ≥ 1.21.120。布尔值
start_sound开始使用物品时播放的声音。需要格式版本 ≥ 1.21.130。字符串
start_using使用物品时，minecraft:use_modifiers 如何生效。always 表示总是生效，if_first 表示仅开始使用时生效。需要格式版本 ≥ 1.26.30。字符串旧名称：minecraft:use_duration
版本：≤1.20.40
旧语法：
"minecraft:use_duration": 1.1 // 使用时间。物品格式版本为 1.16.100 前，单位是刻（1 刻等于 0.05 秒）。物品格式版本为 1.16.100 及以后，单位是秒。
旧名称：minecraft:chargeable
版本：≤1.20.40
旧语法：
"minecraft:chargeable":{
"movement_modifier": 0.0, // 使用这个物品时的速度修饰符，修改这个可以实现类似于拉弓时行走缓慢的效果。吃东西时的修饰符是 0.35。
"on_complete": { // 使用完触发的事件
"event": "test", // 事件名称
"target": "self"
}
}
wearable穿戴组件：让物品可以被穿戴，并提供护甲值。
"minecraft:wearable":{
"hides_player_location": true,
"protection": 5,
"slot": "slot.armor.chest"
}字段功能描述类型
hides_player_location穿戴此物品时，玩家是否在定位栏与定位器地图上隐藏。默认为 false。布尔值
protection保护的程度。这个数值越高，盔甲的效果越好，必须是正整数或 0。整数
slot可以穿戴在哪里。指定为盔甲槽时，物品的最大堆叠数会被设为 1。所有可用槽位见下。字符串以下是所有可用的槽位。槽位值描述
slot.weapon.offhand副手
slot.armor.head头盔
slot.armor.chest胸甲
slot.armor.legs护腿
slot.armor.feet靴子旧名称：minecraft:armor
版本：≤1.20.20
旧语法：
"minecraft:armor": {
"protection": 5, // 保护的程度。这个数值越高，盔甲的效果越好，必须是正整数或 0。
"texture_type": "diamond" // 纹理类型，可以被 q.armor_texture_slot 查询到。
}
| 未知状态组件
以下组件未被官方承认，也没有对应文档。它们的功能未知，也可能会被移除，非常不建议使用它们。这些组件的解释可能不准确。
之前有很多这样的组件，但在 1.20.50.24 版本后它们已经被移除，仅剩下面这两个组件。它并不被游戏认为已经移除，更新日志也没有提到它被移除。
Frame Count | 纹理帧数
指定动态物品纹理中，纹理有多少帧。必须填写整数。
"minecraft:frame_count": 16
Block | 方块物品
指定物品为方块物品，也就是一个方块对应的物品形式。必须填写字符串，指定对应的方块 ID。在 1.21.40.23 后，其功能可能由 minecraft:block_placer 中的 replace_block_item 字段取代。
"minecraft:block": "minecraft:diamond_block"
| 已废弃组件和已移除组件
以下组件已被废弃或移除，非常不建议使用已废弃组件，现已无法使用已移除组件。这些组件的解释可能不准确。
指定物品为染料。"minecraft:dye_powder": {
"color": "red" // 填写颜色字符串，或数字 ID。
}
或者这么写。
"minecraft:dye_powder": 1 // 填写颜色字符串，或数字 ID。
指定物品的击退抗性。"minecraft:knockback_resistance": 0.5 // 击退抗性值，范围是 0.0 到 1.0。
忽略权限物品组件。"minecraft:ignores_permission": true // 使用物品时是否忽略权限，填布尔值。
翻转纹理物品组件。"minecraft:mirrored_art": true // 是否镜像翻转物品纹理，填布尔值。
快捷栏动画物品组件。"minecraft:animates_in_toolbar": true // 物品是否在快捷栏有动画，填布尔值。
可被爆炸破坏物品组件。"minecraft:explodable": false // 物品的掉落物形式是否会被爆炸破坏，填布尔值。
渲染偏移物品组件。"minecraft:render_offsets": false // 指定物品的渲染偏移，填布尔值或对象或字符串。false将禁用渲染偏移，字符串用于引用原版渲染偏移类型。
或者这么写。
"minecraft:render_offsets": "apple" //指定物品的渲染偏移，填布尔值或对象或字符串。这里引用了原版苹果物品的渲染偏移。
或者这么写。
"minecraft:render_offsets": {
"main_hand": { //物品在主手的渲染偏移。
"first_person": { //第一人称时...
"scale": [ //控制物品大小。
0.01,
0.01,
0.01
]
},
"third_person": { //第三人称时...
"scale": [
0.01,
0.01,
0.01
]
}
},
"off_hand": { //物品在副手的渲染偏移，格式与上面相同。
"first_person": {
"scale": [
0.01,
0.01,
0.01
]
},
"third_person": {
"scale": [
0.01,
0.01,
0.01
]
}
}
}
需要交互物品组件。"minecraft:requires_interact": true // 物品是否需要交互，填布尔值。
挖掘速度物品组件。"minecraft:mining_speed": 5 // 指定挖掘速度，填正整数。
武器物品组件。"minecraft:weapon": { // 添加伤害值的提示，并添加一些触发器。
"on_hurt_entity": { // 攻击实体并使其受伤时触发。
"event": "aaa", // 事件名称。
"target": "self" // 触发效果作用的目标。
},
"on_not_hurt_entity": { // 攻击实体但未使其受伤时触发。
"event": "bbb",
"target": "other"
},
"on_hit_block": { // 挖掘方块时触发。
"event": "ccc",
"target": "self"
}
}
使用物品触发器组件。"minecraft:on_use": {
"on_use": { // 使用（右键或长按）时触发。
"event": "aaa", // 事件名称。
"target": "self" // 触发效果作用的目标。
}
}
使用物品于方块触发器组件。"minecraft:on_use_on": {
"on_use_on": { // 使用于方块（右键方块或点击方块）时触发。
"event": "aaa", // 事件名称。
"target": "self" // 触发效果作用的目标。
}
}
肥料物品组件。"minecraft:fertilizer": {
"type": "bonemeal" // 指定肥料类型，填 bonemeal（骨粉）或 rapid（超级肥料）。
}
公文包物品组件。"minecraft:portfolio": {} // 指定物品为公文包。
地图物品组件。"minecraft:map": {} // 指定物品为地图。
剪刀物品组件。"minecraft:shears": {} // 指定物品为剪刀。
桶物品组件。"minecraft:bucket": {} // 指定物品为桶。
图标集物品组件。"minecraft:icon_atlas": {} // 指定物品图标集。
图标变种物品组件。"minecraft:icon_variant": {} // 指定物品图标变种。
相机物品组件。"minecraft:camera": {
"black_bars_duration": 0.2, // 顶部和底部的黑条持续的时长，单位是秒。
"black_bars_screen_ratio": 0.08, // 黑条与屏幕的比值，也就是黑条的宽度比屏幕的宽度得到的相对值，用于决定黑条的宽度。
"shutter_duration": 0.2, // 快门时长，拍摄一张照片所用的时间间隔，单位是秒。
"picture_duration": 1.0, // 显示照片的时长，拍摄后照片会显示在屏幕上，持续这里指定的值，单位是秒。
"slide_away_duration": 0.2 // 照片移走的时间，显示完的照片要花这个时间从屏幕下方划走，单位是秒。
} // 指定物品的相机动画参数。
https://klpbbs.com/static/image/hrline/line1.png
杂项
| 描述文档
以下是物品的 description 字段的示例。{
"identifier": "complementary:example",
"menu_category": {
"category": "equipment",
"group": "minecraft:itemGroup.name.cookedFood",
"is_hidden_in_commands": false
}
}字段功能描述类型
identifier物品的 ID。字符串
menu_category物品在创造模式物品栏中的位置和在命令中的可见性。对象
category物品在创造模式物品栏中的标签页。若不指定，则默认为 items。字符串
group可选，物品在创造模式物品栏中的分组。必须有命名空间。字符串
is_hidden_in_commands可选，物品是否在命令列表中隐藏，隐藏之后无法通过命令获取。布尔值
以下是 menu_category 的所有可用值和描述。字段描述
construction建筑
equipment装备
items物品
nature自然
none无
填写 none 时，物品不能通过创造模式物品栏获取。
group 字段是物品所在的“组”，可以展开或折叠。可以填写原版物品组的本地化键名，也可以创建新的物品组，请参考这篇教程。
| 你知道吗？
[*]在 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 这样的组件。
[*]扩展盔甲纹饰。（很久以后）
[*]添加物品存储实体的功能。（很久以后）
[*]目前不会添加自定义唱片。（已实现）
[*]目前不会添加自定义创造模式物品栏的标签页。
https://klpbbs.com/static/image/hrline/line8.png
总结
这一期，我把所有物品组件罗列了一遍。下一期，我们就开始讲物品事件。如果想要模板包告诉你这些组件到底怎么用，请看第九期。
第六期 第七期 第八期
历史版本/时间事件
1.20.0.20移除了minecraft:repairable中的on_repaired参数
1.20.0.20移除了minecraft:dye_powder
2023年4月23日增加了一些组件，美化了排版
1.20.0.22移除了minecraft:knockback_resistance
1.20.20.20移除了minecraft:creative_category、minecraft:ignores_permission、minecraft:mirrored_art、minecraft:armor、minecraft:wearable的mainhand、hotbar、inventory、enderchest和equippable字段，将minecraft:foil重命名为minecraft:glint，将minecraft:armor下的protection字段移动到minecraft:wearable下，在description下添加了menu_category字段
1.20.20.21移除了minecraft:animates_in_toolbar、minecraft:explodable、minecraft:render_offsets
1.20.30.20移除了minecraft:requires_interact，弃用了minecraft:mining_speed
1.20.30.22加入了minecraft:interact_button
1.20.40.21弃用了minecraft:weapon、minecraft:on_use、minecraft:on_use_on
1.20.50.20弃用了以"tag:xxx": {}的方式给物品添加标签，加入了minecraft:tags物品组件以代替以前的功能。
1.20.50.22弃用了minecraft:chargeable，将minecraft:use_duration重命名为minecraft:use_modifiers，这个新组件相当于minecraft:chargeable和minecraft:use_duration的合并。
1.20.50.23弃用了minecraft:digger中的on_dig参数。
2023年11月7日添加了一些组件的旧格式。
2023年11月26日移除了被游戏（基岩版1.20.50.24）认为“已移除”的minecraft:fertilizer、minecraft:portfolio、minecraft:map、minecraft:shears、minecraft:bucket、minecraft:icon_atlas、minecraft:icon_variant组件。
2023年12月19日根据1.20.60.23中的内容日志，移除了组件minecraft:wearable的dispensable字段和组件minecraft:block_placer的use_block_description字段
1.20.60.23移除了组件minecraft:food的on_consume字段，移除了整个物品事件系统（没错，就是移除了与components同级的那个events。）
2024年3月9日增加并修改了一些描述，根据原版风弹文档（没错，1.21更新的试炼钥匙和风弹是数据驱动的，不是硬编码）添加了两个新参数。
2024年5月3日根据实际情况更改了一些组件的描述，排版了一些内容。
1.21.10.22加入了minecraft:damage_absorption、minecraft:durability_sensor，修改了排版
2024年6月17日添加了更多minecraft:icon的信息
2024年7月20日添加了旧版minecraft:food的饱和度字符串信息，添加了minecraft:display_name组件（被我遗忘了很久很久的那个组件），将所有已废弃或移除的组件添加回这个页面，添加了minecraft:custom_components，补充了minecraft:item_storage的信息，稍微更改了排版，补充了minecraft:enchantable的信息
1.21.30.21加入了minecraft:rarity，补充了minecraft:projectile的信息
1.21.30.23加入了minecraft:storage_item和minecraft:bundle_interaction
1.21.30.24公开了minecraft:dyeable
2024年9月7日补充了minecraft:icon的信息，修改了minecraft:interact_button的描述
2024年9月18日补充了minecraft:icon和minecraft:dyeable的信息，再次修改了minecraft:interact_button的描述
2024年9月20日添加了minecraft:block和minecraft:camera，在正文末尾增加了一个板块，重新设计了本页样式，重写了部分说明。剩余重写工作将在以后完成。
2024年9月21日重写了剩余部分，补充了minecraft:durability_sensor的信息。
2024年10月1日补充了minecraft:durability_sensor的信息，添加了replace_block_item字段，修改了部分板块的描述
1.21.50.20添加了minecraft:compostable
2024年10月10日移除了minecraft:wearable的slot.saddle、slot.armor、slot.armor.body、slot.chest字段，修改了minecraft:block_placer的描述，优化了JSON排版
2024年11月9日修改了minecraft:use_animation的描述，增加了两个板块，将板块移入新的“杂项”大板块，优化了排版，补充了minecraft:tags的信息，修改了minecraft:throwable的描述
1.21.60.25加入了了minecraft:storage_weight_limit和minecraft:storage_weight_modifier，修改了minecraft:storage_item和minecraft:icon的信息，修改了一些杂项信息
2025年2月12日修改了大部分组件的信息，添加了被遗漏很久的minecraft:allow_off_hand组件
2025年4月10日加入了minecraft:icon的两个新字段，修改了minecraft:custom_components的信息
2025年8月2日加入了minecraft:fire_resistant，修改了minecraft:food和minecraft:display_name的信息
1.21.120.22加入了minecraft:swing_duration
1.21.120.23加入了minecraft:use_modifiers的emit_vibrations字段
1.21.130.20加入了minecraft:swing_sounds、minecraft:kinetic_weapon、minecraft:piercing_weapon、minecraft:cooldown的type字段
2025年10月19日修改了minecraft:fire_resistant和minecraft:enchantable的信息
1.21.130.27加入了minecraft:use_modifiers的start_sound字段，加入了minecraft:piercing_weapon与minecraft:kinetic_weapon的creative_reach字段
2026年2月9日补充了minecraft:enchantable和minecraft:wearable的信息
2026年6月13日加入了minecraft:use_modifiers的start_using字段，加入了minecraft:block_placer的aligned_placement字段，补充了一些信息
什么时候更新呢？mojang又加了几个新字段 怎么样才能使我的物品具有成书的ui，即点击“使用物品”后可以弹出一本预设好的书 关于收纳袋组件的问题，max_slots为啥我填16，实测的时候最大收纳值还64？
allowed_items是将允许收纳的物品添加在[]符号内吗？如果是多个物品是用逗号隔开吗？
我只会做收纳袋的第一个纹理，第二个纹理就不会了，就是那个打开袋子的。 感谢分享！ MC平方 发表于 2024-9-28 17:37
1.21.30版本，我使用最大堆叠组件，"minecraft:max_stack_size": 1，我填写数量是1，但导入游戏后显示的最 ...
其他支持1.21.30的模组都有最大堆叠是1的 1.21.30版本，我使用最大堆叠组件，"minecraft:max_stack_size": 1，我填写数量是1，但导入游戏后显示的最大堆叠数怎么变成64了，是哪里出错了，还是该组件被移除了
请问1.21.20更新以后，某些需要用到实验性-假日的组件岂不是全部用不了了？ 没有铁等级的挖掘速度？想编辑挖掘组件，该不会要把可以挖掘的东西全都写在组件里吧，那我想做镐之类的，他能挖的东西可多了，该不会挨个挨个写吧？ 本帖最后由 芓又又zyew 于 2023-4-22 15:47 编辑
笔记:
原版方块的tag标签https://wiki.mcbe-dev.net/p/%E6%96%B9%E5%9D%97/%E6%A0%87%E7%AD%BE
另外，addonsmaker制作的工具最下面会有一个minecraft:display_name，不过我也不知道用处是什么
页: [1]2