数据驱动物品组件

定义物品的显示名称。

参数
示例

minecraft:display_name：根对象。
- value：定义物品的显示名称。可以指定为特定名称，也可以指定为本地化键名。不指定时默认为本地化键名item.(命名空间):(ID)。

特定的物品名称：

"minecraft:display_name": {
    "value": "钻石剑"
}

本地化物品键名：

"minecraft:display_name": {
    "value": "item.diamond_sword.name"
}

`minecraft:durability`

定义物品的耐久度。

Durability does not implicitly damage itself when mining blocks. It must be handled via ScriptAPI. It does however implicitly damage itself when damaging mobs. Each hit on a mob decreases durability by 2. This does not match vanilla property for weapons, but does match vanilla property for tools.
When used with minecraft:wearable, hitting a mob with the item does not decrease durability by 2. Instead, it implicitly decreases durability by 1 when equipped and hit by an entity. This matches vanilla property.

参考翻译：
耐久度在挖掘方块时不会降低耐久，必须通过 ScriptAPI 强制降低耐久度。但是，当攻击生物时，每次击中生物都会降低 2 点耐久度，这并不符合武器的运作方式，而是工具的。
当使用minecraft:wearable时，攻击生物不会降低这 2 点耐久度。在穿着该物品时，被其他实体攻击后会降低 1 点耐久度，这是符合原版的运作方式的。

—— Bedrock Wiki

参数
示例

minecraft:durability：根对象。
- damage_chance：定义该物品有多大概率会在被使用后降低耐久度。不指定时默认为100%。
  - max*：最大有百分之多少的概率降低耐久度。
  - min*：最小有百分之多少的概率降低耐久度。
- max_durability*：定义物品的总耐久度。

"minecraft:durability": {
    "max_durability": 251
}

"minecraft:durability": {
    "damage_chance": { "min": 10, "max": 50 },
    "max_durability": 10
}

`minecraft:icon`

定义物品的图标。

重要组件

对于任何自定义物品，都必须定义该组件。否则，物品将无法正确展示贴图。

参数
示例

多值写法：

minecraft:icon*：根对象
- textures：定义该物品的贴图。
  - default：该物品的默认贴图。Minecraft 将会试图找到在资源包中定义的textures/item_texture.json的短 ID。详见贴图文件格式。
  - dyed：该物品的染色后贴图，仅当指定minecraft:dyeable组件后有意义。Minecraft 将会试图找到在资源包中定义的textures/item_texture.json的短 ID。详见贴图文件格式。

单值写法（1.20.40+）：

minecraft:icon*：该物品的默认贴图。Minecraft 将会试图找到在资源包中定义的textures/item_texture.json的短 ID。详见贴图文件格式。

单值写法（1.20.0 - 1.20.50）：

minecraft:icon*：根对象
- texture：该物品的贴图。Minecraft 将会试图找到在资源包中定义的textures/item_texture.json的短 ID。详见贴图文件格式。

对象型（多值写法）：

"minecraft:icon": {
    "textures": {
        "default": "apple"
    }
}

字符串型（单值写法）：

"minecraft:icon": "apple"

`minecraft:max_stack_size`

定义物品的最大堆叠数。

参数
示例

对象型：

minecraft:max_stack_size：根对象。
- value：物品的最大堆叠数，默认为64。

整型：

minecraft:max_stack_size：物品的最大堆叠数，默认为64。

对象型：

"minecraft:max_stack_size": {
    "value": 16
}

整型：

"minecraft:max_stack_size": 16

`minecraft:stacked_by_data`

定义是否允许不同数据值的同种物品堆叠。

参数
示例

对象型：

minecraft:stacked_by_data：根对象。
- value：是否允许不同数据值的物品或掉落物堆叠，默认为false。

布尔型：

minecraft:stacked_by_data：是否允许不同数据值的物品或掉落物堆叠，默认为false。

对象型：

"minecraft:stacked_by_data": {
    "value": true
}

布尔型：

"minecraft:stacked_by_data": true

`minecraft:tags`

国际版 1.20.50+ 中国版

定义物品标签。

参数
示例

minecraft:tags：根对象。
- tags：物品的标签列表。
  - ：物品标签。

有关原版使用的标签，参见物品标签。

"minecraft:tags": {
    "tags": [ "minecraft:planks", "example:foo" ]
}

功能性组件

特定类型物品可用的组件。

常见物品类型	常用组件	最低适用版本
剑	`minecraft:can_destroy_in_creative`、`minecraft:damage`、`minecraft:digger`、`minecraft:enchantable`、`minecraft:hand_equipped`、`minecraft:repairable`	1.20.30
工具	`minecraft:digger`、`minecraft:enchantable`、`minecraft:repairable`	1.20.30
盔甲	`minecraft:enchantable`、`minecraft:repairable`、`minecraft:wearable`	1.20.30
食物	`minecraft:food`、`minecraft:use_animation`、`minecraft:use_modifiers`	1.20.50
弹射物（如雪球）	`minecraft:cooldown`、`minecraft:projectile`、`minecraft:throwable`	1.20.10
弓类似物	`minecraft:shooter`、`minecraft:use_modifiers`	1.20.50
收纳袋	`minecraft:bundle_interaction`、`minecraft:storage_item`、`minecraft:storage_weight_limit`、`minecraft:storage_weight_modifier`	1.21.60

`minecraft:allow_off_hand`

允许玩家将物品放在副手。

参数
示例

对象型：

minecraft:allow_off_hand：根对象。
- value：是否能将物品放在副手，默认为false。

布尔型：

minecraft:allow_off_hand：是否能将物品放在副手，默认为false。

对象型：

"minecraft:allow_off_hand": {
    "value": true
}

布尔型：

"minecraft:allow_off_hand": true

`minecraft:block_placer`

可以在特定方块上放置特定方块。

参数
示例

minecraft:block_placer：根对象
- block*：将放置为何种方块。
- replace_block_item：（1.21.50+）是否将此物品与对应方块绑定，若绑定则当方块被破坏后将掉落该物品。备注：物品 ID 必须与对应的方块 ID 保持一致。
- use_on：可放置于的方块列表。如果留空，则默认为可放置于所有方块上。
  - ：方块 ID。

该组件有更完整的语法描述方块，请查阅官方文档。

"minecraft:block_placer": {
    "block": "seeds",
    "use_on": [ "dirt", "grass" ],
    "replace_block_item": true
}

"minecraft:block_placer": {
    "block": "minecraft:dirt",
    "use_on": [ "dirt", "grass", "anvil" ]
}

`minecraft:bundle_interaction`

国际版 1.21.40+

为物品启用收纳袋的交互模式和物品提示。

注意

要使用该组件，必须先定义minecraft:storage_item组件。

参数
示例

minecraft:bundle_interaction：根对象
- num_viewable_slots：定义从收纳袋顶部可访问的物品堆叠的最大数量。必须在1到64之间（含），默认值为12。

"minecraft:bundle_interaction": {
    "num_viewable_slots": 12
}

`minecraft:can_destroy_in_creative`

允许玩家在创造模式下手持该物品时可以破坏方块。如果设置为false，该物品就会像剑一样手持时无法破坏方块。

参数
示例

对象型：

minecraft:can_destroy_in_creative：根对象。
- value：是否允许玩家在创造模式下手持该物品时破坏方块，默认为true。

布尔型：

minecraft:can_destroy_in_creative：是否允许玩家在创造模式下手持该物品时破坏方块，默认为true。

对象型：

"minecraft:can_destroy_in_creative": {
    "value": false
}

布尔型：

"minecraft:can_destroy_in_creative": false

`minecraft:compostable`

国际版 1.21.60+

定义物品可在堆肥桶中用于堆肥。

参数
示例

minecraft:compostable：根对象。
- composting_chance*：有百分之多少的概率会堆肥成功。

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

`minecraft:cooldown`

定义物品使用后的冷却。

注意

要使用该组件，必须同时定义下面的组件：

minecraft:use_modifiers（1.20.50或更高格式版本）
minecraft:use_duration（1.20.30-1.20.40格式版本）

参数
示例

minecraft:cooldown：根对象。
- category：冷却类别，共享同种冷却类别的物品将会一起进入冷却阶段。
- duration：冷却时间，单位为秒。
- type：（1.21.130+）冷却类型，在使用或攻击时令此物品进入冷却状态。可选值为：use（使用后进入冷却，冷却期间不再允许使用，但允许攻击或进行其他操作）、attack（攻击后进入冷却，冷却期间不再允许攻击，但允许使用或进行其他操作）。默认值为use。

"minecraft:cooldown": {
    "category": "attack",
    "duration": 1.5,
    "type": "attack"
}

`minecraft:custom_components`

国际版 1.21.20 - 1.21.90

定义物品的自定义组件。自定义组件的行为需要在世界初始化前事件WorldInitializeBeforeEvent中定义。

警告

该组件必须配合 ScriptAPI 使用，因此该组件在现在或未来的中国版也是无效的。
该组件随着 1.21.90 的自定义组件 V2 的推出，已被弃用。在1.21.90或更高版本下的物品定义中不应再使用该组件。

参数
示例

minecraft:custom_components：根数组。
- ：自定义组件的名称。

"minecraft:custom_components": [
    "example:on_use"
]

`minecraft:damage`

定义物品的攻击伤害，类似剑。

参数
示例

对象型：

minecraft:damage：根对象。
- value：物品的攻击伤害。

整型：

minecraft:damage：物品的攻击伤害。

对象型：

"minecraft:damage": {
    "value": 7
}

整型：

"minecraft:damage": 7

`minecraft:damage_absorption`

国际版 1.21.20+

定义该物品在穿戴时可吸收何种类型的伤害，类似狼铠。

注意

要使用该组件，必须先定义minecraft:durability和minecraft:wearable组件。

参数
示例

minecraft:damage_absorption：根对象。
- absorbable_causes*：定义该物品将吸收的伤害类型列表。当实体在盔甲栏上穿戴该物品时，该物品会以降低耐久度为代价吸收列表中的伤害类型，使得实体免受这些类型的伤害。
  - ：伤害类型。可见/damage命令的可用伤害类型。

"minecraft:damage_absorption": {
    "absorbable_causes": [ "all" ]
}

`minecraft:digger`

定义物品破坏特定方块的速度。

参数
示例

minecraft:digger：根对象。
- destroy_speeds*：定义列表中的方块的破坏速度。
  - block：方块 ID。
  - block（替代）：方块标签。
    - tags：一个 Molang 表达式。通常使用query.any_tag()来代表拥有特定标签的方块。
  - speed：破坏方块的速度。若为负数则代表无法破坏。更多信息参见挖掘 - 中文 Minecraft Wiki，但请格外注意此值不支持浮点数。
- use_efficiency：定义有效率附魔的物品是否影响挖掘速度。

实测物品在使用此组件后，将变为指定的方块的合适挖掘工具。例如若指定minecraft:web，那么此物品挖掘蜘蛛网就能够掉落线。

"minecraft:digger": {
    "minecraft:digger": {
        "use_efficiency": true,
        "destroy_speeds": [
            { "block": { "tags": "query.any_tag( 'wood' )" }, "speed": 6 },
            { "block": "minecraft:coal_ore", "speed": 2 }
        ]
    }
}

`minecraft:durability_sensor`

国际版 1.21.20+

定义物品在降低耐久度后触发的事件。

参数
示例

minecraft:durability：根对象。
- durability_thresholds*：当物品耐久度降低到某个阈值时，触发事件。如果同时满足多个阈值，考虑所有阈值中最低的那个。至少指定 1 项。
  - ：耐久度阈值
    - durability：指定耐久度阈值，当物品耐久度低于此值时触发下面的事件。
    - particle_type：低于耐久度阈值时释放的粒子。
    - sound_event：低于耐久度阈值时播放的音效。

"minecraft:durability_sensor": {
    "durability_thresholds": [
        {
            "durability": 100,
            "particle_type": "minecraft:explosion_manual",
            "sound_event": "blast"
        },
        {
            "durability": 5,
            "sound_event": "raid.horn"
        }
    ]
}

`minecraft:dyeable`

国际版 1.21.30+

定义物品在炼药锅中可染色。

当该物品被染色前，使用minecraft:icon中规定的default贴图；而被染色后，使用minecraft:icon中规定的dyed贴图。

注意

要使用该组件，应同时在minecraft:icon组件中定义dyed的贴图。

参数
示例

minecraft:dyeable：根对象。
- default_color：该物品染色前采用的默认颜色，应指定为有效的颜色代码（#xxxxxx）。

"minecraft:dyeable": {
    "default_color": "#ffffff"
}

`minecraft:enchantable`

国际版 1.20.30+

定义物品为可附魔。

参数
示例

minecraft:enchantable：根对象。
- slot*：该物品可以按照什么类型的物品附魔。只能填写为下列值中的一种：
  armor_feet armor_torso armor_head armor_legs axe
  bow cosmetic_head crossbow elytra fishing_rod
  flintsteel hoe melee_spear pickaxe shears
  shield shovel sword all
- value*：附魔能力。该值越高越容易附魔出更好的魔咒。应在0-255之间（含）。更多信息参见中文 Minecraft Wiki。

`armor_feet`	`armor_torso`	`armor_head`	`armor_legs`	`axe`
`bow`	`cosmetic_head`	`crossbow`	`elytra`	`fishing_rod`
`flintsteel`	`hoe`	`melee_spear`	`pickaxe`	`shears`
`shield`	`shovel`	`sword`	`all`

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

`minecraft:entity_placer`

定义物品可生成实体。

参数
示例

minecraft:entity_placer：根对象。
- entity*：生成的实体的 ID。
- dispense_on：可在何种方块上通过发射器使用该物品并生成实体。留空则默认允许全部方块。
  - ：方块 ID。
- use_on：可在何种方块上使用该物品并生成实体。留空则默认允许全部方块。
  - ：方块 ID。

更完整的用法请查阅官方文档。

"minecraft:entity_placer": {
    "entity": "minecraft:spider",
    "dispense_on": [ "minecraft:web" ],
    "use_on": [ "minecraft:web" ]
}

"minecraft:entity_placer": {
    "entity": "minecraft:sheep"
}

`minecraft:fire_resistance`

国际版 1.21.110+

定义物品防火，类似于下界合金物品。

参数
示例

minecraft:fire_resistance：根对象。
- value：物品是否防火，默认为false。

"minecraft:fire_resistance": {
    "value": true
}

`minecraft:food`

国际版 1.20.30+

定义物品为食物。

参数
示例

编者注

新版的food组件相比旧版删去了大量功能，拆分到了其他组件或脚本功能中。以下为功能点差异，若读者有相关需求，请参考以下替代方案，若无法接受请使用旧版组件。

提供状态效果（或解除状态效果）：使用脚本的物品使用后事件（ItemCompleteUseAfterEvent）监听并对使用实体提供药效。
使用后随机传送：使用脚本的物品使用后事件（ItemCompleteUseAfterEvent）监听并传送实体（不要忘记加传送到地表的判定）。
使用冷却：使用物品组件minecraft:cooldown代替。

注意

要使用该组件，必须同时定义下面的组件：

minecraft:use_modifiers（1.20.50或更高格式版本）
minecraft:use_duration（1.20.30-1.20.40格式版本）

minecraft:food：根对象。
- nutrition：食物回复的饥饿值。默认为0。
- saturation_modifier：食物回复的饱和度等级。回复的饱和度将为饥饿值×饱和度系数×2。默认为0.6。
- using_converts_to：食物在食用完毕后将转化为的物品。应填写为物品 ID。
- can_always_eat：食物是否在任何情况下都可食用，否则仅当玩家的饥饿值不满时才可食用。

"minecraft:food": {
    "nutrition": 4,
    "saturation_modifier": 0.3
}

`minecraft:fuel`

定义该物品为燃料。

参数
示例

minecraft:fuel：根对象。
- duration：定义燃料在熔炉中的燃烧时长，单位秒。

"minecraft:fuel": {
    "duration": 80.0
}

`minecraft:glint`

定义该物品会像附魔书一样产生附魔光泽。

参数
示例

对象型：

minecraft:glint：根对象。
- value：物品是否有附魔光泽，默认为false。

布尔型：

minecraft:glint：物品是否有附魔光泽，默认为false。

对象型：

"minecraft:glint": {
    "value": true
}

布尔型：

"minecraft:glint": true

`minecraft:hand_equipped`

定义该物品像工具一样直立展示在玩家手中。

参数
示例

对象型：

minecraft:hand_equipped：根对象
- value：是否在手中像工具一样展示物品，默认为false。

布尔型：

minecraft:hand_equipped：是否在手中像工具一样展示物品，默认为false。

对象型：

"minecraft:hand_equipped": {
    "value": true
}

布尔型：

"minecraft:hand_equipped": true

`minecraft:hover_text_color`

定义物品悬浮文本的颜色。

参数
示例

对象型：

minecraft:hover_text_color：根对象。
- value：设置物品的悬浮文本颜色。可选值为格式化代码对应的名称，详见中文 Minecraft Wiki 对应的名称一列。

布尔型：

minecraft:hover_text_color：设置物品的悬浮文本颜色。可选值为格式化代码对应的名称，详见中文 Minecraft Wiki 对应的名称一列。

对象型：

"minecraft:hover_text_color": {
    "value": "aqua"
}

布尔型：

"minecraft:hover_text_color": "aqua"

`minecraft:interact_button`

国际版 1.20.30+

在触控设备中，为物品添加交互按钮。

参数
示例

minecraft:interact_button：在触控设备上，是否启用物品的交互按钮，以及该按钮上显示的文本。若指定为true，则默认显示为Use Item，否则显示为指定文本。允许指定为本地化键名。

默认，显示为“Use Item”：

"minecraft:interact_button": true

指定为特定文本：

"minecraft:interact_button": "Click me!"

`minecraft:kinetic_weapon`

国际版 1.21.130+

定义物品可造成动能伤害，类似于矛。

动能伤害每刻计算一次，根据使用者和目标投影到视线向量上的速度来计算伤害（通过点积），速度越快伤害越高；越对齐视线向量伤害也越高。若应用参数damage_multiplier和damage_modifier，伤害值将向下取整。

参数
示例

minecraft:kinetic_weapon：根对象。
- delay：施加伤害和效果前需要等待的游戏刻数。
- reach：定义目标必须在使用者的视线向量内多少格的范围才能被击中。如果目标和使用者之间有方块，也会阻止伤害及其效果。
  - max：目标和使用者之间的最大范围。默认值为3。
  - min：目标和使用者之间的最小范围。默认值为0。
- creative_reach：定义目标必须在创造模式使用者的视线向量内多少格的范围才能被击中。如果目标和使用者之间有方块，也会阻止伤害及其效果。
  - max：目标和使用者之间的最大范围。默认值为reach规定的值。
  - min：目标和使用者之间的最小范围。默认值为reach规定的值。
- hitbox_margin：允许使用者视线向量的偏移误差。默认值为0。
- damage_multiplier：在基础伤害的基础上的伤害乘数。默认值为1。
- damage_modifier：在基础伤害×伤害乘数（damage_multiplier）的基础上的伤害加和值，得到最终伤害。默认值为0。
- damage_conditions：应用伤害需满足的条件，条件不满足时不施加伤害。
  - max_duration：当delay参数计时完毕后，在多长的时间范围内时可施加伤害。如果为负数则不设限制。单位：游戏刻。默认值为-1。
  - min_relative_speed：目标和使用者之间的相对速度应至少为多大时施加伤害。默认值为0。
  - min_speed：使用者的速度应至少为多大时施加伤害。默认值为0。
- dismount_conditions：击落目标需满足的条件，条件不满足时不会使目标从载具上击落。
  - max_duration：当delay参数计时完毕后，在多长的时间范围内时可将目标从载具上击落。如果为负数则不设限制。单位：游戏刻。默认值为-1。
  - min_relative_speed：目标和使用者之间的相对速度应至少为多大时将目标从载具上击落。默认值为0。
  - min_speed：使用者的速度应至少为多大时将目标从载具上击落。默认值为0。
- knockback_conditions：击退目标需满足的条件，条件不满足时不击退目标。
  - max_duration：当delay参数计时完毕后，在多长的时间范围内时可击退目标。如果为负数则不设限制。单位：游戏刻。默认值为-1。
  - min_relative_speed：目标和使用者之间的相对速度应至少为多大时击退目标。默认值为0。
  - min_speed：使用者的速度应至少为多大时击退目标。默认值为0。

铁矛数据（见矛 - 中文 Minecraft Wiki）：

"minecraft:kinetic_weapon": {
    "delay": 12,
    "reach": {
        "min": 2.0,
        "max": 4.5
    },
    "creative_reach": {
        "min": 2.0,
        "max": 7.5
    },
    "hitbox_margin": 0.25,
    "damage_multiplier": 0.95,
    "damage_conditions": {
        "max_duration": 225,
        "min_relative_speed": 4.6
    },
    "knockback_conditions": {
        "max_duration": 90,
        "min_speed": 5.1
    },
    "dismount_conditions": {
        "max_duration": 50,
        "min_speed": 11.0
    }
}

`minecraft:liquid_clipped`

定义物品是否可与流体交互。

参数
示例

对象型：

minecraft:liquid_clipped：根对象。
- value：是否能与液体交互，默认为false。

布尔型：

minecraft:liquid_clipped：是否能与液体交互，默认为false。

对象型：

"minecraft:liquid_clipped": {
    "value": true
}

布尔型：

"minecraft:liquid_clipped": true

`minecraft:piercing_weapon`

国际版 1.21.130+

定义物品可造成戳刺伤害，类似于矛。

戳刺伤害根据使用者和目标投影到视线向量上的速度来计算伤害（通过点积）。需要注意：应用了该组件的物品不能破坏方块，因为戳刺伤害始终处于更高的优先级之中。

参数
示例

minecraft:piercing_weapon：根对象。
- reach：定义目标必须在使用者的视线向量内多少格的范围才能被击中。如果目标和使用者之间有方块，也会阻止伤害及其效果。
  - max：目标和使用者之间的最大范围。默认值为3。
  - min：目标和使用者之间的最小范围。默认值为0。
- hitbox_margin：允许使用者视线向量的偏移误差。默认值为0。

矛数据（见矛 - 中文 Minecraft Wiki）：

"minecraft:piercing_weapon": {
    "reach": {
        "min": 2,
        "max": 4.5,
    },
    "creative_reach": {
        "min": 2,
        "max": 7.5,
    },
    "hitbox_margin": 0.25
}

`minecraft:projectile`

定义物品为弹射物，例如箭。

参数
示例

minecraft:projectile：根对象。
- minimum_critical_power：定义蓄力需要多久才能暴击。单位秒。
- projectile_entity*：定义掷出何种实体。若未指定命名空间，默认为minecraft。

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

`minecraft:rarity`

国际版 1.21.30+

定义物品的稀有度。

注意：物品具有任何魔咒时稀有度会提升，由常见或少见变为稀有、或由稀有变为史诗。关于稀有度机制，详见稀有度 - 中文 Minecraft Wiki。

参数
示例

对象型：

minecraft:rarity：根对象。
- value：定义物品的基础稀有度。可选值为common（普通）、uncommon（少见）、rare（稀有）、epic（传奇）。

字符串型：

minecraft:rarity：定义物品的基础稀有度。可选值为common（普通）、uncommon（少见）、rare（稀有）、epic（传奇）。

对象型：

"minecraft:rarity": {
    "value": "rare"
}

字符串型：

"minecraft:rarity": "rare"

`minecraft:record`

定义物品为唱片。

参数
示例

minecraft:record：根对象。
- comparator_signal：在唱片机中通过红石信号输出的信号，应在0-15之间。
- duration：音乐时长，单位秒。
- sound_event：要播放的音效。

官方给出的自定义物品实例：

"minecraft:record": {
    "comparator_signal": 1,
    "duration": 5,
    "sound_event": "pre_ram.screamer"
}

`minecraft:repairable`

定义物品为可修复的。默认情况下，允许此物品和另一个同种类的物品在一起修复（例如两把损坏铁镐合成一把较新的铁镐），此时恢复的耐久度为二者相加。

参数
示例

minecraft:repairable：根对象。
- repair_items：可用于修复的物品及其修复耐久度值的列表。
  - ：可修复的物品项目
    - repair_amount：物品恢复的耐久度。当指定为整数时，恢复固定的耐久度值；指定为字符串时，可指定为一个 Molang，可使用context.other指定铁砧另一个槽位的物品。
    - items*：可用于修复的物品列表。
      - ：可用于修复的物品 ID。

"minecraft:repairable":{
    "repair_items": [
        {
            "items":[ "minecraft:diamond" ],
            "repair_amount": 10
        }
    ]
}

"minecraft:repairable":{
    "repair_items": [
        {
            "items":[ "minecraft:diamond" ],
            "repair_amount": "math.random(1, 10)"
        }
    ]
}

按原版计算公式修复（两物品的剩余耐久度 + 该类物品满耐久度 * 0.05）：

"minecraft:repairable":{
    "repair_items": [
        {
            "items":[
                "minecraft:diamond"
            ],
            "repair_amount": "math.min(query.remaining_durability + context.other->query.remaining_durability + math.floor(query.max_durability /20), context.other->query.max_durability)"
        }
    ]
}

`minecraft:shooter`

定义物品为某种弹射物的发射物，类似于弓或弩。

提示

若通过minecraft:durability定义了发射物的耐久度，该物品将仅在发射子弹时降低耐久度。近战攻击时该物品的耐久度将不受影响。

注意

要使用该组件，必须同时定义下面的组件：

minecraft:use_modifiers（1.20.50或更高格式版本）
minecraft:use_duration（1.20.20-1.20.40格式版本）

参数
示例

minecraft:shooter：根对象。
- ammunition*：定义该发射物使用何种子弹。
  - - item*：子弹所对应的物品 ID。该物品 ID 对应的物品必须具有minecraft:projectile组件，否则将会报错。
    - use_offhand：是否允许使用副手上的子弹，像弩和烟花一样。默认值为false。
    - search_inventory：是否搜索物品栏中是否有子弹可用，创造模式下不会消耗子弹。默认值为false，但通常设置为true。
    - use_in_creative：是否在创造模式下可用。若设置为false，则无法在物品栏中没有子弹时使用。默认值为false。
- charge_on_draw：拉动时是否蓄力充能。默认值为false。
- max_draw_duration：拉动最长时间。应小于等于minecraft:use_modifiers或minecraft:use_duration组件定义的使用时长，默认值为0。
- scale_power_by_draw_duration：是否随着拉动时间的增长而增加对应子弹（弹射物）发射时威力，默认值为false。

"minecraft:shooter": {
    "ammunition": [
        {
            "item": "minecraft:snowball",
            "use_offhand": true,
            "search_inventory": true,
            "use_in_creative": true
        }
    ],
    "max_draw_duration": 1,
    "scale_power_by_draw_duration": true,
    "charge_on_draw": false
}

`minecraft:should_despawn`

定义该物品对应的掉落物是否会在一段时间后消失。

参数
示例

对象型：

minecraft:should_despawn：根对象。
- value：掉落物是否会在一段时间后消失，默认为true。

布尔型：

minecraft:should_despawn：掉落物是否会在一段时间后消失，默认为true。

对象型：

"minecraft:should_despawn": {
    "value": false
}

布尔型：

"minecraft:should_despawn": false

`minecraft:storage_item`

国际版 1.21.40+

定义该物品为可存储物品，可以存储其他物品，类似于收纳袋。

注意

要使用该组件：

必须先定义minecraft:max_stack_size组件，并将其值设为1，否则该组件可能无法正常工作。
建议定义minecraft:bundle_interaction组件，以使此物品能够正常交互。

参数
示例

minecraft:storage_item：根对象。
- allow_nested_storage_items：是否允许该类物品嵌套存储，例如收纳袋存储收纳袋。
- allowed_items：允许存储的物品，不在此列名单中的物品无法存储。若设置为空则允许存储一切物品。
  - ：允许存储的物品 ID。
- banned_items：禁止存储的物品，在此列名单中的物品无法存储。
  - ：允许存储的物品 ID。
- max_slots：该物品的最大槽位数。
- max_weight_limit：（1.21.40 - 1.21.50）该物品在其他可存储物品中占用的容量。注：1.21.60或更高格式版本请使用minecraft:storage_weight_limit组件。
- weight_in_storage_item：（1.21.40 - 1.21.50）该物品在其他可存储物品中占用的容量。注：1.21.60或更高格式版本请使用minecraft:storage_weight_modifier组件。

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

`minecraft:storage_weight_limit`

国际版 1.21.60+

定义该可存储物品最多可以存储多少物品。

注意

要使用该组件，必须先定义minecraft:storage_item组件。

参数
示例

minecraft:storage_weight_limit：根对象。
- max_weight_limit：定义该可存储物品（类似于收纳袋）的最大空间。必须在0-64之间，默认为64。

"minecraft:storage_weight_limit": {
    "max_weight_limit": 64
}

`minecraft:storage_weight_modifier`

国际版 1.21.60+

定义该物品在存储到一个可存储物品时需要占用多大空间。

参数
示例

minecraft:storage_weight_modifier：根对象。
- weight_in_storage_item：定义该物品在存储到一个可存储物品（类似于收纳袋）时需要占用多大空间。默认为4，若为0则代表该物品无法存储到其他可存储物品中。

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

`minecraft:swing_duration`

国际版 1.21.120+

定义该物品的挥舞动画（例如攻击、挖掘时）所需时间。仅决定视觉效果，不会影响其他底层机制（例如攻击时间等）。

参数
示例

minecraft:swing_duration：根对象。
- value：定义该物品的挥舞动画所需时间。默认值为0.3。

"minecraft:swing_duration": {
    "value": 0.3
}

`minecraft:swing_sounds`

国际版 1.21.130+

定义该物品的挥舞音效。

参数
示例

minecraft:swing_sounds：根对象。
- attack_miss：定义未击中时的音效。
- attack_hit：定义击中时的音效。
- attack_critical_hit：定义暴击时的音效。

"minecraft:swing_sounds": {
    "attack_critical_hit": "attack.critical"
}

`minecraft:throwable`

定义该物品可掷出，类似于雪球或鸡蛋。

注意

要使用该组件，必须先定义minecraft:projectile组件。

参数
示例

minecraft:throwable：根对象。
- do_swing_animation：物品掷出后是否播放摆手动画。
- launch_power_scale：随着蓄力时间增长而增加的弹射物威力比例。默认值为1.0（即蓄力时间增长，弹射物威力不增加）。设置负值将导致弹射物以反方向掷出。
- max_draw_duration：最长蓄力时间，单位秒。默认为0.0。
- min_draw_duration：最段蓄力时间，单位秒。默认为0.0。
- max_launch_power：弹射物的最大威力（以保证弹射物的威力不会无限增大）。
- scale_power_by_draw_duration：是否随着蓄力时间的增长而增加弹射物掷出时的威力，默认值为false。

"minecraft:throwable": {
    "do_swing_animation": true,
    "launch_power_scale": 1.5,
    "max_launch_power": 1.5
}

`minecraft:use_animation`

定义物品的使用动画。

参数
示例

对象型：

minecraft:use_animation：根对象。
- value：使用物品时播放的动画，可选值为eat、drink、bow、block、camera、crossbow、none、brush、spear、spyglass，不使用该组件时则不播放动画。

字符串型：

minecraft:use_animation：使用物品时播放的动画，可选值为eat、drink、bow、block、camera、crossbow、none、brush、spear、spyglass，不使用该组件时则不播放动画。

对象型：

"minecraft:use_animation": {
    "value": "eat"
}

字符串型：

"minecraft:use_animation": "eat"

`minecraft:use_duration`

国际版 1.20.20 - 1.20.40

定义该物品的使用时长。

注意

要使用该组件，必须同时定义下列组件中的 1 个：

minecraft:food
minecraft:shooter
minecraft:throwable

警告

该组件在高于1.20.50的格式版本下已被弃用。在高版本下，使用minecraft:use_modifiers代替之。

参数
示例

minecraft:use_duration：该物品的使用时长。单位为秒，默认值为1.6。

"minecraft:use_duration": 1.6

`minecraft:use_modifiers`

国际版 1.20.50+

定义该物品的使用时长。

注意

要使用该组件，必须同时定义下列组件中的 1 个：

minecraft:food
minecraft:shooter
minecraft:throwable

参数
示例

minecraft:use_modifiers：根对象。
- use_duration*：使用时长。例如苹果的该值为1.6。
- movement_modifier：定义玩家使用物品时的速度倍率，必须小于等于1。例如苹果的该值为0.35。
- emit_vibrations：（1.21.120+）定义玩家使用物品时是否发出振动。
- start_sound：（1.21.130+）定义玩家在使用物品后播放何种音效。

"minecraft:use_modifiers": {
    "use_duration": 1.6,
    "movement_modifier": 0.35,
    "emit_vibrations": true,
    "start_sound": "random.orb"
}

"minecraft:use_modifiers": {
    "use_duration": 3
}

`minecraft:wearable`

定义该物品为可穿戴物品，例如盔甲。

参数
示例

minecraft:wearable：根对象。
- slot*：定义可穿戴的位置。可选值：slot.weapon.offhand、slot.armor.head、slot.armor.chest、slot.armor.legs、slot.armor.feet。
- protection：物品可提供的护甲值。默认为0。
- hides_player_location：（1.21.90+）穿戴后是否在定位栏中隐藏玩家位置。

"minecraft:wearable": {
    "slot": "slot.armor.chest",
    "protection": 10
}

"minecraft:wearable": {
    "slot": "slot.armor.head",
    "hides_player_location": true
}

旧版本组件

本部分为 1.16.X 或以前的物品格式版本可用的组件。其中，下述几乎所有物品组件都有新版本的平替。读者可以在这里的旧版文档中查看这些组件接受的参数。

备注：minecraft:food的新版本平替组件无法完全平替旧版功能，需要脚本补充其功能。

旧版本组件	新版本可用的平替组件	新版本组件需求的最低格式版本
`minecraft:block`	`minecraft:block_placer`	1.20.10
`minecraft:foil`	`minecraft:glint`	1.20.20
`minecraft:food`	`minecraft:food`	1.20.30
`minecraft:hand_equipped`	`minecraft:hand_equipped`	1.20.20
`minecraft:hover_text_color`（RP）	`minecraft:hover_text_color`	1.20.10
`minecraft:icon`（RP）	`minecraft:icon`	1.20.0
`minecraft:max_damage`	`minecraft:durability`	1.20.0
`minecraft:max_stack_size`	`minecraft:max_stack_size`	1.20.20
`minecraft:seed`	`minecraft:block_placer`	1.20.10
`minecraft:stacked_by_data`	`minecraft:stacked_by_data`	1.20.20
`minecraft:use_animation`（RP）	`minecraft:use_animation`	1.20.20
`minecraft:use_duration`	`minecraft:use_modifiers`	1.20.50

`minecraft:block`

国际版旧版

定义物品可以放置为方块。

参数
示例

minecraft:block：将放置为何种方块。

"minecraft:block": "minecraft:camera"

`minecraft:foil`

国际版旧版中国版

定义该物品会像附魔书一样产生附魔光泽。

参数
示例

minecraft:foil：物品是否有附魔光泽，默认为false。

"minecraft:foil": true

`minecraft:food`

国际版旧版中国版

定义物品为食物。

注意

要使用该组件，必须同时定义minecraft:use_duration组件。

参数
示例

minecraft:food：根对象。
- nutrition：食物回复的饥饿值。
- saturation_modifier：食物回复的饱和度等级。回复的饱和度将为饥饿值×饱和度系数×2。可选值及其对应饱和度系数如下表：
  可选值 poor low normal good max supernatural
  饱和度系数 0.1 0.3 0.6 0.8 1.0 1.2
- using_converts_to：食物在食用完毕后将转化为的物品。应填写为物品 ID。
- on_use_action：食物在食用完毕后的行为。可选值：chrous_teleport、suspicious_stew_effect、none，默认为none。
- on_use_range：食物在食用完毕后的影响范围。仅在on_use_action指定为chrous_teleport时有意义，代表随机传送的范围。
  - 0：X 轴偏移，默认值为0.0。
  - 1：Y 轴偏移，默认值为0.0。
  - 2：Z 轴偏移，默认值为0.0。
- cooldown_type：食物在使用后进入的冷却类型，共享同种冷却类型的物品将会一起进入冷却阶段。
- cooldown_time：食物在使用后进入的冷却时间，单位为游戏刻，共享同种冷却类型的物品将会一起进入冷却阶段。
- can_always_eat：食物是否在任何情况下都可食用，否则仅当玩家的饥饿值不满时才可食用。
- effects：食物在食用后提供的状态效果。
  - ：状态效果信息。
    - name：提供的状态效果 ID。
    - chance：有多大的几率提供这个状态效果。应在0.0-1.0之间（含）。不同状态效果间，该值是独立判断的。
    - duration：提供的状态效果时长，单位秒（即使是瞬时状态效果）。
    - amplifier：提供的状态效果放大倍数，提供的等级为放大倍数 + 1。
- remove_effects：食物在食用后解除的状态效果。
  - ：解除的状态效果 ID。

可选值	`poor`	`low`	`normal`	`good`	`max`	`supernatural`
饱和度系数	0.1	0.3	0.6	0.8	1.0	1.2

紫颂果：

"minecraft:food": {
    "nutrition": 4,
    "saturation_modifier": "low",
    "on_use_action": "chorus_teleport",
    "on_use_range": [ 8, 8, 8 ],
    "cooldown_type": "chorusfruit",
    "cooldown_time": 20,
    "can_always_eat": true
}

金苹果：

"minecraft:food": {
    "nutrition": 4,
    "saturation_modifier": "supernatural",
    "can_always_eat": true,
    "effects": [
        {
            "name": "regeneration",
            "chance": 1.0,
            "duration": 5,
            "amplifier": 1
        },
        {
            "name": "absorption",
            "chance": 1.0,
            "duration": 120,
            "amplifier": 0
        }
    ]
}

`minecraft:hand_equipped`

国际版旧版中国版

定义该物品像工具一样直立展示在玩家手中。

参数
示例

minecraft:hand_equipped：是否在手中像工具一样展示物品，默认为false。

"minecraft:hand_equipped": true

`minecraft:hover_text_color`

国际版旧版 RP 中国版 RP

定义物品悬浮文本的颜色。

参数
示例

minecraft:hover_text_color：设置物品的悬浮文本颜色。可选值为格式化代码对应的名称，详见中文 Minecraft Wiki 对应的名称一列。

"minecraft:hover_text_color": "aqua"

`minecraft:icon`

国际版旧版 RP 中国版 RP

定义物品的图标。

重要组件

对于任何自定义物品，都必须定义该组件。否则，物品将无法正确展示贴图。

参数
示例

minecraft:icon*：该物品的默认贴图。Minecraft 将会试图找到在资源包中定义的textures/item_texture.json的短 ID。详见贴图文件格式。

"minecraft:icon": "apple"

`minecraft:max_damage`

国际版旧版中国版

定义物品的耐久度。

参数
示例

minecraft:max_damage：该物品的耐久度。应在0-32767之间（含）。

"minecraft:max_damage": 1000

`minecraft:max_stack_size`

国际版旧版中国版

定义物品的最大堆叠数。

参数
示例

minecraft:max_stack_size：物品的最大堆叠数，默认为64。

"minecraft:max_stack_size": 16

`minecraft:seed`

国际版旧版中国版

定义物品为种子。

参数
示例

minecraft:seed：根对象。
- crop_result：种植后放置的方块。
- plant_at：可被种植的方块列表。
  - ：方块 ID。

"minecraft:seed": {                                  
    "crop_result": "sweet_berry_bush", 
    "plant_at": [ "grass", "dirt", "podzol" ]
}

`minecraft:stacked_by_data`

国际版旧版中国版

定义是否允许不同数据值的同种物品堆叠。

参数
示例

minecraft:stacked_by_data：是否允许不同数据值的物品或掉落物堆叠，默认为false。

"minecraft:stacked_by_data": true

`minecraft:use_animation`

国际版旧版 RP 中国版 RP

定义物品的使用动画。

参数
示例

minecraft:use_animation：使用物品时播放的动画，可选值为eat、drink、bow、block、camera、crossbow、none、brush、spear、spyglass，不使用该组件时则不播放动画。

"minecraft:use_animation": "eat"

`minecraft:use_duration`

国际版旧版中国版

定义该物品的使用时长。

注意

要使用该组件，必须同时定义minecraft:food组件。

参数
示例

minecraft:use_duration：该物品的使用时长。单位为游戏刻，默认值为32。

"minecraft:use_duration": 32

中国版组件

仅中国版可用的组件。其中，下述部分物品组件有国际版组件的平替，或组件的部分功能有国际版组件的平替。

中国版组件	国际版可用的平替组件	国际版组件需求的最低格式版本
`netease:allow_offhand`	`minecraft:allow_off_hand`	1.20.20
`netease:armor`	`minecraft:wearable`、`minecraft:enchantable`（可平替部分功能）	1.20.30
`netease:compostable`	`minecraft:compostable`	1.21.60（中国版版本低）
`netease:cooldown`	`minecraft:cooldown`	1.20.10
`netease:egg`	`minecraft:entity_placer`	1.20.0
`netease:fire_resistance`	`minecraft:fire_resistance`	1.21.110（中国版版本低）
`netease:fuel`	`minecraft:fuel`	1.20.0
`netease:projectile`	`minecraft:projectile`	1.20.10
`netease:weapon`	`minecraft:damage`、`minecraft:enchantable`、`minecraft:digger`（可平替部分功能）	1.20.30

`netease:allow_offhand`

允许玩家将物品放在副手。

注意

使用该组件的物品，在放到副手后可能无法支持minecraft:foil、netease:render_offsets等组件。

参数
示例

netease:allow_offhand：根对象。
- value*：是否能将物品放在副手。

"netease:allow_offhand": {
    "value": true
}

`netease:armor`

定义物品为盔甲。

参数
示例

netease:armor：根对象。
- defense：定义盔甲的防御值。默认值为0。
- enchantment：定义盔甲的附魔能力。默认值为0。
- armor_slot*：定义盔甲槽位。可选值为0（头盔）、1（胸甲）、2（护腿）、3（靴子）。
- toughness：定义盔甲韧性，应在0-20之间（含）。默认值为0。
- knockback_resistance：定义盔甲的击退抗性，应在0-1之间（含）。默认值为0.0。

"netease:armor":{
    "defense": 10,
    "enchantment": 4,
    "armor_slot": 0
}

`netease:bucket`

定义该物品为桶。

注意

要使用该组件，需在物品描述中将custom_item_type设置为bucket。

参数
示例

netease:bucket：根对象。
- fill_liquid*：定义使用时倒出的流体方块 ID。默认值为flowing_water。

"netease:bucket": {
    "fill_liquid": "flowing_water"
}

`netease:compostable`

定义物品可在堆肥桶中用于堆肥。

参数
示例

netease:compostable：有百分之多少的概率会堆肥成功。例如设置为 50 时则有 50% 的概率堆肥成功。

"netease:compostable": 50

`netease:cooldown`

定义物品使用后的冷却。

注意

定义了食物组件minecraft:food的物品，其冷却需在食物组件中定义。

参数
示例

netease:cooldown：根对象。
- category：冷却类型，共享同种冷却类型的物品将会一起进入冷却阶段。默认值为item。
- duration：冷却时间，单位为游戏刻。

"netease:cooldown": {
    "category": "item",
    "duration": 10
}

`netease:customtips`

定义物品的描述信息。

参数
示例

netease:customtips：根对象。
- value*：物品的描述信息。

"netease:customtips": {
    "value": "§8右键可发射"
}

`netease:egg`

定义物品可生成实体。

参数
示例

netease:egg：根对象。
- entity*：生成的实体的 ID。

"netease:egg": {
    "entity": "minecraft:sheep"
}

`netease:enchant_material`

定义物品为附魔材料，类似于青金石。

参数
示例

netease:enchantment_material：根对象。
- value*：物品是否为附魔材料。

"netease:enchantment_material": {
    "value": true
}

`netease:fire_resistant`

定义物品防火，类似于下界合金物品。

参数
示例

netease:fire_resistant：根对象。
- value*：物品是否防火。

"netease:fire_resistant": {
    "value": true
}

`netease:frame_anim_in_scene`

中国版 RP

定义物品的序列帧。

参数
示例

netease:weapon：根对象。
- flipbook_texture*：序列帧资源的路径。
- atlas_tile*：在图集中声明的名称。
- ticks_per_frame*：代表多少帧切换一次贴图，按 1 秒 20 帧算，设置 20 的话即为 1 秒切换一帧贴图。
- blend_frames：切换贴图的时候是否混合上一帧。

"netease:frame_anim_in_scene": {
    "texture_path": "textures/items/watch_atlas",
    "ticks_per_frame": 1
}

`netease:frame_animation`

中国版 RP

定义蓄力物品的序列帧。

参数
示例

netease:weapon：根对象。
- texture_name*：item_texture.json中定义的序列帧数组。
- frame_count：定义序列帧帧数。默认值为1。
- animate_in_toolbar：在物品栏中是否支持动画。默认值为true。

"netease:frame_animation": {
    "frame_count": 3,
    "texture_name": "bow_pulling",
    "animate_in_toolbar": true
}

`netease:fuel`

定义该物品为燃料。

参数
示例

netease:fuel：根对象。
- duration：定义燃料在熔炉中的燃烧时长，单位秒。

"netease:fuel": {
    "duration": 80.0
}

`netease:initial_user_data`

定义物品的初始属性。

参数
示例

netease:initial_user_data：根对象。
- display：物品的显示信息。
  - Name（注意大写）：物品的初始名称。
  - Lore（注意大写）：物品的描述信息。
    - ：物品描述。第 i 个元素代表第 i 行描述。
  - ShowInHand（注意大写）：手持是否显示物品。
- ench：物品的附魔信息列表。
  - ：附魔信息。
    - id*：附魔 ID。
      - __type__：下面的__value__值的类型，1代表字节型（Byte），2代表短整型（short）。
      - __value__：附魔 ID 对应的数字 ID。若为自定义附魔，则需将该值设为255并设置modEnchant。
      - modEnchant：仅当__value__为255时有意义，指定设置的附魔 ID。
    - lvl*：附魔等级。
      - __type__：下面的__value__值的类型，1代表字节型（Byte），2代表短整型（short）。
      - __value__：附魔等级。
- minecraft:keep_on_death：物品是否在玩家死亡后掉落。默认值为false。
- minecraft:item_lock：指定物品锁定。可选值为0（不锁定）、1（无法移动）、2（无法丢弃），默认为0。
- 其他可用键名及可用值请参考基岩版物品格式 - 中文 Minecraft Wiki。

"netease:initial_user_data": {
    "display": {
        "Name": "同铁砧命名",
        "Lore": ["第一行描述", "第二行描述"]
    },
    "ench": [{
        "id": {
            "__type__":2,
            "__value__":12
        },
        "lvl": {
            "__type__":2,
            "__value__":10
        }
    }],
    "minecraft:keep_on_death": true,
    "ModAttackDamage": 20
}

`netease:projectile`

定义物品为弹射物。

参数
示例

netease:projectile：定义将掷出的弹射物。

"netease:projectile": "minecraft:snowball"

`netease:render_offsets`

定义该物品在右手时的渲染偏移。

参数
示例

netease:render_offsets：根对象
- controller_position_adjust：物品位置偏移。
  - 0：X 轴偏移，默认值为0.0。
  - 1：Y 轴偏移，默认值为0.0。
  - 2：Z 轴偏移，默认值为0.0。
- controller_rotation_adjust：物品旋转偏移。
  - 0：X 轴偏移，默认值为0.0。
  - 1：Y 轴偏移，默认值为0.0。
  - 2：Z 轴偏移，默认值为0.0。
- controller_scale：物品大小。默认值为1.0。

"netease:render_offsets": {
    "controller_position_adjust": [0.0, 0.1, 0.0],
    "controller_rotation_adjust": [0.0, -45.0, 0.0],
    "controller_scale": 1
},

`netease:shield`

定义该物品为盾。

注意

要使用该组件，需在物品描述中将custom_item_type设置为shield。

参数
示例

netease:shield：根对象
- defence_damage_source_list：防御的伤害类型。为空时默认设置为原版的格挡伤害逻辑。
  - ：伤害类型。可见/damage命令的可用伤害类型。
- undefence_damage_source_list：不防御的伤害类型。不宜和defence_damage_source_list存在相同元素。
  - ：伤害类型。可见/damage命令的可用伤害类型。
- is_consume_damage：是否消耗物品的耐久度。

"netease:shield":{
    "defence_damage_source_list": [ "drowning" ],
    "undefence_damage_source_list": [ "entity_attack" ],
    "is_consume_damage": false
}

`netease:show_in_hand`

手持时是否显示该物品。

参数
示例

netease:show_in_hand：根对象
- value*：手持时是否显示该物品。

"netease:show_in_hand": {
    "value": true
}

`netease:weapon`