Bedrock Wiki
新手入门指南
JSON UI
Meta
NBT
世界生成
动画控制器
命令
实体
战利品、配方与交易
文档
方块
服务器
概念
物品
视觉效果
粒子效果
脚本编写
虚拟现实

物品事件

scripting
物品事件

格式版本 1.21.70

创建自定义物品时使用最新格式版本可获得最新功能和改进。本维基旨在分享关于自定义物品的最新信息，当前目标格式版本为 1.21.70。

注册自定义组件 ​

当满足特定条件时，物品事件将被触发，并可在世界加载前通过脚本注册的自定义组件中进行"监听"。

在每个自定义组件中，列出了事件处理函数（如 onBeforeDurabilityDamage），用于配置每个事件触发时希望执行的操作。

以下示例可防止物品在攻击实体时受到耐久度损耗：

BP/scripts/unbreakable_component.js
js
import { world } from "@minecraft/server";

const ItemUnbreakableComponent = {
    onBeforeDurabilityDamage(event) {
        event.durabilityDamage = 0;
    },
};

world.beforeEvents.worldInitialize.subscribe(({ itemComponentRegistry }) => {
    itemComponentRegistry.registerCustomComponent("wiki:unbreakable", ItemUnbreakableComponent);
});

应用自定义组件 ​

要将自定义组件绑定到自定义物品，只需在物品JSON的 minecraft:custom_components 组件中列出它们。

minecraft:item
json
"components": {
    "minecraft:custom_components": ["wiki:unbreakable"]
}

事件列表 ​

耐久度损耗前 ​

当包含此组件的物品攻击实体并即将受到耐久度损耗时，将调用此事件。

自定义组件
js
onBeforeDurabilityDamage(event) {
    event.attackingEntity // 攻击实体。
    event.durabilityDamage // 事件发生时应用于物品耐久度的损耗值。
    event.hitEntity // 被攻击的实体。
    event.itemStack // 用于攻击实体的物品堆叠。
}

使用完成 ​

依赖项

使用完成事件需要物品上激活了 minecraft:use_modifiers 组件才能触发。

当包含此组件的物品使用持续时间完成时，将调用此事件。

minecraft:item > components
json
"minecraft:use_modifiers": {
    "use_duration": 5
}
自定义组件
js
onCompleteUse(event) {
    event.itemStack // 返回已完成充能的物品堆叠。
    event.source // 返回触发此物品事件的源实体。
}

消耗 ​

当包含此组件的物品被实体食用时，将调用此事件。

依赖项

使用完成事件需要物品上同时激活了 minecraft:use_modifiers 和 minecraft:food 组件才能触发。

minecraft:item > components
json
"minecraft:food": {},
"minecraft:use_modifiers": {
    "use_duration": 5
}
自定义组件
js
onConsume(event) {
    event.itemStack // 被消耗的物品堆叠。
    event.source // 消耗物品的源实体。
}

攻击实体 ​

当包含此组件的物品用于攻击另一个实体时，将调用此函数。

自定义组件
js
onHitEntity(event) {
    event.attackingEntity // 攻击实体。
    event.hadEffect // 判断攻击是否命中或产生效果。
    event.hitEntity // 被攻击的实体。
    event.itemStack // 用于攻击实体的物品堆叠。
}

挖掘方块 ​

当包含此组件的物品用于挖掘方块时，将调用此函数。

自定义组件
js
onMineBlock(event) {
    event.block // 受此事件影响的方块。
    event.itemStack // 用于挖掘方块的物品堆叠。
    event.minedBlockPermutation // 被挖掘的方块置换状态。
    event.source // 挖掘方块的实体。
}

使用 ​

当包含此组件的物品被玩家使用时，将调用此函数。

自定义组件
js
onUse(event) {
    event.itemStack // 物品被使用时的物品堆叠。
    event.source // 使用物品的玩家。
}

在方块上使用 ​

当包含此组件的物品在方块上使用时，将调用此函数。

自定义组件
js
onUseOn(event) {
    event.source // 在方块上使用物品的实体。
    event.usedOnBlockPermutation // 物品被使用的方块置换状态。
}

贡献者

编辑 物品事件

本页面上的文本和图像内容根据 知识共享署名 4.0 国际许可协议

本页中的代码示例根据 MIT 许可证