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

Block Events

scripting
Block Events

FORMAT VERSION 1.26.10

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.26.10.

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/creativeModeOnly.js
js
import { system, GameMode } from "@minecraft/server"; // Must be version 2.0.0 or higher

/** @type {import("@minecraft/server").BlockCustomComponent} */
const BlockCreativeModeOnlyComponent = {
    beforeOnPlayerPlace(event) {
        const gameMode = event.player?.getGameMode();

        if (gameMode !== GameMode.Creative) {
            event.cancel = true;
        }
    },
};

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

Applying Custom Components ​

To bind a custom component to a block, simply list it in the components of your block JSON.

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

Requires format version 1.21.90 or later.

minecraft:block
json
"components": {
    "wiki:creative_mode_only": {}
}

List of Events ​

Before Player Place ​

Called before a player places the block, preventing the client-side placement of 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.
}

Break ​

Called whenever the block is removed from the world, including when replaced via commands.

Custom Component
js
onBreak(event) {
    event.block // Block impacted by this event. This is the block after it has been broken.
    event.dimension // Dimension that contains the block.
    event.blockDestructionSource // The block that broke the block (such as an extended piston). May be undefined.
    event.brokenBlockPermutation // Permutation of the block before it was broken.
    event.entitySource // The entity that broke the block. May be undefined.
}

Entity ​

Called when an entity executes an event on the block.

Events can be triggered by the execute_event_on_home_block entity event response or by vanilla entity components (see vanilla entity events). Events will not necessarily be received by this hook in the same tick that the entity requests for the event to be executed.

Custom Component
js
onEntity(event) {
    event.block // Block impacted by this event.
    event.blockPermutation // The permutation of the block when it was originally affected by the entity.
    event.dimension // Dimension that contains the block.
    event.entitySource // The entity that executed the event on the block.
    event.name // The name of the event executed by the entity. May be custom or one of the vanilla events listed below.
}

Vanilla Entity Events ​

Event NameRequired Entity ComponentDescription
"on_escape"minecraft:behavior.avoid_blockExecuted after the entity escapes from the block.
"on_home"minecraft:behavior.go_homeExecuted after the entity reaches the block.
"on_place"minecraft:behavior.place_blockExecuted after the entity places the block.
"on_reach"minecraft:behavior.move_to_blockExecuted after the entity reaches the block.
"on_take"minecraft:behavior.take_blockExecuted after the entity takes the block.

Custom Dog Example ​

minecraft:entity
json
"components": {
    // The dog's home will be set to its kennel
    "minecraft:home": {
        "restriction_radius": 32,
        "restriction_type": "random_movement",
        "home_block_types": ["wiki:kennel", "wiki:large_kennel"]
    }
},
"events": {
    // Event that can be triggered to make this dog's kennel bigger
    "wiki:upgrade_kennel": {
        "execute_event_on_home_block": {
            "event": "wiki:on_upgrade"
        }
    }
}
Custom Component
js
onEntity({ name, block }) {
    if (name === "wiki:on_upgrade") {
        // Upgrade regular kennel to large kennel
        block.setType("wiki:large_kennel");
    }
}

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 taller than 3.2 pixels on the Y-axis in order to trigger.

Called 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 ​

Called 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 Break ​

Called when the player breaks the block.

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

Player Interact ​

EMPTY BUCKETS

The onPlayerInteract hook is not called when the player interacts with the block using an empty bucket.

Called 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.
}

Redstone Update ​

DEPENDENCY

The redstone update event requires the minecraft:redstone_consumer component to be active on your block to trigger.

Triggers every time the block receives a redstone update.

This happens in the following situations:

  • The block is placed
  • The chunk containing the block is loaded
  • The redstone power level of the block changes
minecraft:block > components
json
"minecraft:redstone_consumer": {
    "min_power": 5 // The minimum power level needed to trigger this event.
}
Custom Component
js
onRedstoneUpdate(event) {
    event.block // Block impacted by this event.
    event.dimension // Dimension that contains the block.
    event.powerLevel // The redstone power level received by the block.
}

Step Off ​

DEPENDENCY

The step off event requires the minecraft:collision_box component to be taller than 3.2 pixels on the Y-axis in order to trigger.

Called 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 taller than 3.2 pixels on the Y-axis in order to trigger.

Called 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