Bedrock Wiki
Beginner's Guide
Animation Controllers
Blocks
Commands
Concepts
Documentation
Entities
Items
JSON UI
Loot, Recipes & Trading
Meta
NBT
Particles
Scripting
Servers
Visuals
World Generation

Block Events

scripting
Block Events

FORMAT VERSION 1.21.70

Using the latest format version when creating custom blocks provides access to fresh features and improvements. The wiki aims to share up-to-date information about custom blocks, and currently targets format version 1.21.70.

Registering Custom Components ​

Block events trigger when certain conditions are met and can be "listened" to in custom components which are registered in scripts before the world is loaded.

Within each custom component, event handler functions (such as beforeOnPlayerPlace) are listed to configure what you want to happen when each event is triggered.

This example prevents the player from placing the block if they aren't in creative mode:

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
    );
});

Applying Custom Components ​

To bind a custom component to a custom block, simply list them in the minecraft:custom_components component in your block JSON.

Like any normal component, custom components can be added and removed based on the block's permutation.

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

List of Events ​

Before Player Place ​

DANGER

This event is not triggered on Bedrock Dedicated Servers (including Realms), or when placed by a custom block item.

Runs before a player places the block.

Custom Component
js
beforeOnPlayerPlace(event) {
    event.block // Block impacted by this event. This is the block that will be replaced.
    event.cancel // If set to true, cancels the block place event.
    event.dimension // Dimension that contains the block.
    event.face // The block face that was placed onto.
    event.permutationToPlace // The block permutation that will be placed. Can be changed to place a different permutation instead.
    event.player // The player that is placing this block. May be undefined.
}

Entity Fall On ​

DEPENDENCIES

The entity fall on event requires the minecraft:entity_fall_on component to be active on your block to trigger.

The entity fall on event requires the minecraft:collision_box component to be 4 or higher on the Y-axis in order to trigger.

Runs when an entity falls on the block.

minecraft:block > components
json
"minecraft:entity_fall_on": {
    "min_fall_distance": 5 // The minimum distance an entity must fall to trigger this event (optional).
}
Custom Component
js
onEntityFallOn(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
    event.entity // The entity that stepped on the block. May be undefined.
    event.fallDistance // The distance that the entity fell before landing.
}

Place ​

Runs when the block is placed.

Custom Component
js
onPlace(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
    event.previousBlock // Permutation of the replaced block.
}

Player Destroy ​

Runs when the player destroys the block.

Custom Component
js
onPlayerDestroy(event) {
    event.block // Block impacted by this event. This is the block after it has been destroyed.
    event.destroyedBlockPermutation // Permutation of the block before it was destroyed.
    event.dimension // Dimension that contains the block.
    event.player // The player that destroyed the block. May be undefined.
}

Player Interact ​

Runs when the player interacts with / uses the block.

Custom Component
js
onPlayerInteract(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
    event.face // The block face that was interacted with.
    event.faceLocation // Location relative to the bottom north-west corner of the block that the player interacted with.
    event.player // The player that interacted with the block. May be undefined.
}

Random Tick ​

Triggered on every random tick, allowing for behavior like random crop growth.

Custom Component
js
onRandomTick(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
}

Step Off ​

DEPENDENCY

The step off event requires the minecraft:collision_box component to be 4 or higher on the Y-axis in order to trigger.

Runs when an entity steps off the block.

Custom Component
js
onStepOff(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
    event.entity // The entity that stepped on the block. May be undefined.
}

Step On ​

DEPENDENCY

The step on event requires the minecraft:collision_box component to be 4 or higher on the Y-axis in order to trigger.

Runs when an entity steps onto the block.

Custom Component
js
onStepOn(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
    event.entity // The entity that stepped on the block. May be undefined.
}

Tick ​

DEPENDENCY

The tick event requires the minecraft:tick component to be active on your block to trigger.

Triggers between X and Y amount of ticks inside interval_range of the block's minecraft:tick component.

minecraft:block > components
json
"minecraft:tick": {
    "interval_range": [10, 20],
    "looping": true
}
Custom Component
js
onTick(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
}

Contributors

Edit Block Events on GitHub

Text and image content on this page is licensed under the Creative Commons Attribution 4.0 International License

Code samples on this page are licensed under the MIT License