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

方块事件

scripting
方块事件

格式版本 1.21.70

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

注册自定义组件 ​

方块事件在满足特定条件时触发，可以在世界加载前通过脚本注册的自定义组件中进行"监听"。

在每个自定义组件中，会列出事件处理函数（如beforeOnPlayerPlace）来配置每个事件触发时希望发生的操作。

以下示例会阻止非创造模式的玩家放置方块：

BP/scripts/creative_mode_only_component.js
js
import { world, GameMode } from "@minecraft/server";

/** @type {import("@minecraft/server").BlockCustomComponent} */
const BlockCreativeModeOnlyComponent = {
    beforeOnPlayerPlace(event) {
        const isInCreative = event.player?.getGameMode() === GameMode.creative;
        if (!isInCreative) event.cancel = true;
    },
};

world.beforeEvents.worldInitialize.subscribe(({ blockComponentRegistry }) => {
    blockComponentRegistry.registerCustomComponent(
        "wiki:creative_mode_only",
        BlockCreativeModeOnlyComponent
    );
});

应用自定义组件 ​

要将自定义组件绑定到自定义方块，只需在方块的JSON文件中将其列在minecraft:custom_components组件下。

与普通组件一样，自定义组件可以根据方块的permutation进行添加或移除。

minecraft:block
json
"components": {
    "minecraft:custom_components": ["wiki:creative_mode_only"]
}

事件列表 ​

玩家放置前 ​

DANGER

此事件不会在基岩版专用服务器（包括Realms）上触发，也不会在通过自定义方块物品放置时触发。

在玩家放置方块前触发。

自定义组件
js
beforeOnPlayerPlace(event) {
    event.block // 受此事件影响的方块。这是将被替换的方块。
    event.cancel // 如果设为true，将取消方块放置事件。
    event.dimension // 包含该方块的维度。
    event.face // 被放置的方块面。
    event.permutationToPlace // 将被放置的方块变种。可以修改为放置不同的变种。
    event.player // 正在放置方块的玩家。可能为undefined。
}

实体坠落 ​

依赖项

实体坠落事件需要方块上激活minecraft:entity_fall_on组件才能触发。

实体坠落事件需要方块的minecraft:collision_box组件在Y轴上高度为4或更高才能触发。

当实体坠落在方块上时触发。

minecraft:block > components
json
"minecraft:entity_fall_on": {
    "min_fall_distance": 5 // 触发此事件所需的最小坠落距离（可选）。
}
自定义组件
js
onEntityFallOn(event) {
    event.block // 受此事件影响的方块。
    event.dimension // 包含该方块的维度。
    event.entity // 坠落在方块上的实体。可能为undefined。
    event.fallDistance // 实体坠落前的下落距离。
}

放置 ​

当方块被放置时触发。

自定义组件
js
onPlace(event) {
    event.block // 受此事件影响的方块。
    event.dimension // 包含该方块的维度。
    event.previousBlock // 被替换方块的变种。
}

玩家破坏 ​

当玩家破坏方块时触发。

自定义组件
js
onPlayerDestroy(event) {
    event.block // 受此事件影响的方块。这是被破坏后的方块。
    event.destroyedBlockPermutation // 被破坏前方块的变种。
    event.dimension // 包含该方块的维度。
    event.player // 破坏方块的玩家。可能为undefined。
}

玩家交互 ​

当玩家与方块交互/使用时触发。

自定义组件
js
onPlayerInteract(event) {
    event.block // 受此事件影响的方块。
    event.dimension // 包含该方块的维度。
    event.face // 被交互的方块面。
    event.faceLocation // 相对于方块西北底角的交互位置。
    event.player // 与方块交互的玩家。可能为undefined。
}

随机刻 ​

在每个随机刻触发，可用于实现类似作物随机生长的行为。

自定义组件
js
onRandomTick(event) {
    event.block // 受此事件影响的方块。
    event.dimension // 包含该方块的维度。
}

离开方块 ​

依赖项

离开方块事件需要方块的minecraft:collision_box组件在Y轴上高度为4或更高才能触发。

当实体离开方块时触发。

自定义组件
js
onStepOff(event) {
    event.block // 受此事件影响的方块。
    event.dimension // 包含该方块的维度。
    event.entity // 离开方块的实体。可能为undefined。
}

踏上方块 ​

依赖项

踏上方块事件需要方块的minecraft:collision_box组件在Y轴上高度为4或更高才能触发。

当实体踏上方块时触发。

自定义组件
js
onStepOn(event) {
    event.block // 受此事件影响的方块。
    event.dimension // 包含该方块的维度。
    event.entity // 踏上方块的实体。可能为undefined。
}

刻更新 ​

依赖项

刻更新事件需要方块上激活minecraft:tick组件才能触发。

在方块minecraft:tick组件的interval_range范围内，每隔X到Y刻触发一次。

minecraft:block > components
json
"minecraft:tick": {
    "interval_range": [10, 20],
    "looping": true
}
自定义组件
js
onTick(event) {
    event.block // 受此事件影响的方块。
    event.dimension // 包含该方块的维度。
}

贡献者

编辑 方块事件

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

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