方块自定义组件

适用版本：国际版 26.30，中国版 3.8（1.21.90）。

方块自定义组件（Block Custom Component）允许开发者在数据驱动方块中使用自己规定的格式的组件。

方块自定义组件可通过 ScriptAPI 中世界启动前事件中的StartupEvent.blockComponentRegistry.registerCustomComponent()方法注册。

registerCustomComponent(name: string, customComponent: BlockCustomComponent): void

其中，name属性注册为自定义组件的名称，而customComponent是一个接口BlockCustomComponent。下面给出接口BlockCustomComponent允许的所有属性，每个属性都接收一个两参数的函数，第一个参数返回对应事件，第二个参数返回自定义组件中的参数。

每个组件条目下方的高亮标签均含注释，可鼠标悬停或手机点击查看。例：这是一个特殊标签

这是标签下的特殊注解。

。

---

beforeOnPlayerPlace属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

玩家放置方块前执行事件。

参数

beforeOnPlayerPlace?: (arg0: BlockComponentPlayerPlaceBeforeEvent, arg1: CustomComponentParameters) => void

参数：

• arg0：BlockComponentPlayerPlaceBeforeEvent类型，返回放置方块前的事件，包含方块、维度、放置玩家等信息。
• arg1：CustomComponentParameters类型，返回自定义组件中的参数。

示例

注册一个阻止非管理员放置方块的组件test:prevent_member_place，该组件不接收任何参数。

// @ts-check

import * as minecraft from "@minecraft/server";

minecraft.system.beforeEvents.startup.subscribe(event => {
    /** @type {minecraft.BlockCustomComponent} */
    const preventMemberPlaceComponent = {
        beforeOnPlayerPlace: (compEvent) => {
            const player = compEvent.player;
            if (!player) return;
            if (player.playerPermissionLevel < minecraft.PlayerPermissionLevel.Operator) compEvent.cancel = true;
        },
    };
    event.blockComponentRegistry.registerCustomComponent("test:prevent_member_place", preventMemberPlaceComponent);
});

---

onBlockStateChange属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

26.30+

该特性在游戏版本26.30+下可用，但该版本对于当前的中国版版本过高。在server模块脚本版本2.8.0+下可用。

Microsoft Learn JaylyMC projectxero.top

方块状态被更改时执行事件。

参数

onBlockStateChange?: (arg0: BlockComponentBlockStateChangeEvent, arg1: CustomComponentParameters) => void

参数：

• arg0：BlockComponentBlockStateChangeEvent类型，返回放置方块前的事件，包含方块、维度、上一个方块置换等信息。
• arg1：CustomComponentParameters类型，返回自定义组件中的参数。

示例

注册一个当test:is_lit方块状态变化时播放音效的组件test:playsound_on_lit_state_changed，该组件不接收任何参数。

// @ts-check

import * as minecraft from "@minecraft/server";

minecraft.system.beforeEvents.startup.subscribe(event => {
    /** @type {minecraft.BlockCustomComponent} */
    const playsoundOnLitStateChangedComponent = {
        onBlockStateChange: compEvent => {
            /** @type {boolean} */ // @ts-ignore
            const prevIsLit = compEvent.previousPermutation.getState("test:is_lit");
            // 熄灭后播放信标失效音效，点亮后播放信标激活音效
            compEvent.dimension.playSound(prevIsLit ? "beacon.deactivate" : "beacon.activate", compEvent.block.location);
        },
    };
    event.blockComponentRegistry.registerCustomComponent("test:playsound_on_lit_state_changed", playsoundOnLitStateChangedComponent);
});

---

onBreak属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.130+

该特性在游戏版本1.21.130+下可用，但该版本对于当前的中国版版本过高。在server模块脚本版本2.4.0+下可用。

Microsoft Learn JaylyMC projectxero.top

方块被破坏时执行事件。

参数

onBreak?: (arg0: BlockComponentBlockBreakEvent, arg1: CustomComponentParameters) => void

参数：

• arg0：BlockComponentBlockBreakEvent类型，返回破坏方块的事件，包含方块、维度、方块破坏者等信息。
• arg1：CustomComponentParameters类型，返回自定义组件中的参数。

示例

注册一个当方块被破坏后即生成实体的组件"test:spawn_entity_on_break"，该组件接收 2 个参数：entity_id*

字符串（必选）

（生成的实体）和count

整数

（生成的实体数量）。

// @ts-check

import * as minecraft from "@minecraft/server";

minecraft.system.beforeEvents.startup.subscribe(event => {
    /** @type {minecraft.BlockCustomComponent} */
    const spawnEntityOnBreakComponent = {
        onBreak: (compEvent, arg) => {
            /** @type {{entity_id: string, count?: number}} */ // @ts-ignore
            const params = arg.params;
            const entityId = params.entity_id;
            const count = params.count ?? 1;
            for (let i = 0; i < count; i++) { // @ts-ignore
                compEvent.dimension.spawnEntity(entityId, compEvent.block.location);
            }
        },
    };
    event.blockComponentRegistry.registerCustomComponent("test:spawn_entity_on_break", spawnEntityOnBreakComponent);
});

---

onEntity属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

26.10+

该特性在游戏版本26.10+下可用，但该版本对于当前的中国版版本过高。在server模块脚本版本2.6.0+下可用。

Microsoft Learn JaylyMC projectxero.top

---

onEntityFallOn属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

参数

beforeOnPlayerPlace?: (arg0: BlockComponentEntityFallOnEvent, arg1: CustomComponentParameters) => void

参数：

• arg0：BlockComponentEntityFallOnEvent类型，返回实体跌落的事件，包含方块、维度、跌落实体、跌落高度等信息。
• arg1：CustomComponentParameters类型，返回自定义组件中的参数。

示例

注册一个当实体落地即执行命令的组件test:run_command_on_entity_fall_on，该组件接收 1 个参数：command

字符串

（实体待执行的命令）。可结合minecraft:entity_fall_on组件控制至少要高于多高的高度才能执行。

// @ts-check

import * as minecraft from "@minecraft/server";

minecraft.system.beforeEvents.startup.subscribe(event => {
    /** @type {minecraft.BlockCustomComponent} */
    const runCommandOnEntityFallOnComponent = {
        onEntityFallOn: (compEvent, arg) => {
            /** @type {{command: string}} */ // @ts-ignore
            const params = arg.params;
            compEvent.entity?.runCommand(params.command);
        },
    };
    event.blockComponentRegistry.registerCustomComponent("test:run_command_on_entity_fall_on", runCommandOnEntityFallOnComponent);
});

---

onPlace属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

---

onPlayerBreak属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

更名

在server模块脚本版本1.12.0-1.19.0，请使用onPlayerDestroy。

Microsoft Learn JaylyMC projectxero.top

对于曾用名onPlayerDestroy，另见：

JaylyMC

---

onPlayerInteract属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

---

onRandomTick属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

---

onRedstoneUpdate属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

26.0+

该特性在游戏版本26.0+下可用，但该版本对于当前的中国版版本过高。在server模块脚本版本2.0.0+下可用。

需要前置组件

要使用该组件，请事先定义minecraft:redstone_consumer组件。

Microsoft Learn JaylyMC projectxero.top

此方块接收的红石信号更新后执行事件。

另见：minecraft:redstone_consumer组件。

参数

beforeOnPlayerPlace?: (arg0: BlockComponentRedstoneUpdateEvent, arg1: CustomComponentParameters) => void

参数：

• arg0：BlockComponentRedstoneUpdateEvent类型，返回实体跌落的事件，包含方块、维度、新红石信号强度和旧红石信号强度（1.26.10+，脚本版本2.6.0+）等信息。
• arg1：CustomComponentParameters类型，返回自定义组件中的参数。

示例

注册一个当接收到红石信号即使方块发光的组件test:lit_on_redstone_update，该组件接收 1 个参数：min_power

整数

（至少应为多大的红石强度可激活）。可结合minecraft:redstone_consumer组件控制至少要大于等于多少红石信号才能执行。

脚本逻辑

// @ts-check

import * as minecraft from "@minecraft/server";

minecraft.system.beforeEvents.startup.subscribe(event => {
    /** @type {minecraft.BlockCustomComponent} */
    const litOnRestoneUpdateComponent = {
        onRedstoneUpdate: (compEvent, arg) => {
            /** @type {{min_power: number}} */ // @ts-ignore
            const params = arg.params;
            // @ts-ignore
            const newBlockPermutation = compEvent.block.permutation.withState("test:is_lit", compEvent.powerLevel >= params.min_power ? true : false);
            compEvent.block.setPermutation(newBlockPermutation);
        },
    };
    event.blockComponentRegistry.registerCustomComponent("test:lit_on_redstone_update", litOnRestoneUpdateComponent);
});

这里定义了一个只有红石信号强度高于 10 才能被激活的红石灯。

方块定义

{
    "format_version": "1.26.10",
    "minecraft:block": {
        "description": {
            "identifier": "test:my_custom_lamp",
            "menu_category": {
                "category": "construction"
            },
            "states": {
                "test:is_lit": [false, true]
            }
        },
        "components": {
            "minecraft:geometry": "geometry.full_block",
            "minecraft:material_instances": { "*": { "texture": "redstone_lamp_off", "render_method": "blend" } },
            "minecraft:redstone_consumer": { "min_power": 0, "propagates_power": true },
            "test:lit_on_redstone_update": { "min_power": 10 }
        },
        "permutations": [
            {
                "condition": "query.block_state('test:is_lit')",
                "components": {
                    "minecraft:material_instances": { "*": { "texture": "redstone_lamp_on" } },
                    "minecraft:light_emission": 15
                }
            },
            {
                "condition": "!query.block_state('test:is_lit')",
                "components": {
                    "minecraft:material_instances": { "*": { "texture": "redstone_lamp_off" } },
                    "minecraft:light_emission": 0
                }
            }
        ]
    }
}

---

onStepOff属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

---

onStepOn属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

---

onTick属性

国际版

该特性仅在国际版可用。因为该组件必须配合ScriptAPI使用。

1.21.20+

该特性在游戏版本1.21.20+下可用。在server模块脚本版本1.12.0+下可用。

Microsoft Learn JaylyMC projectxero.top

参数

beforeOnPlayerPlace?: (arg0: BlockComponentTickEvent, arg1: CustomComponentParameters) => void

参数：

• arg0：BlockComponentTickEvent类型，返回方块循环执行的事件，包含方块、维度。
• arg1：CustomComponentParameters类型，返回自定义组件中的参数。

示例

注册一个循环执行命令的组件test:run_command_on_tick，该组件接收 1 个参数：command

字符串

（实体待执行的命令）。可结合minecraft:tick组件控制循环执行频率。

// @ts-check

import * as minecraft from "@minecraft/server";

minecraft.system.beforeEvents.startup.subscribe(event => {
    /** @type {minecraft.BlockCustomComponent} */
    const runCommandOnTickComponent = {
        onTick: (compEvent, arg) => {
            /** @type {{command: string}} */ // @ts-ignore
            const params = arg.params;
            compEvent.dimension.runCommand(params.command);
        },
    };
    event.blockComponentRegistry.registerCustomComponent("test:run_command_on_tick", runCommandOnTickComponent);
});

---

---

参考文档

• 接口BlockCustomComponent | projectxero.top