Class WorldBeforeEvents

A set of events that fire before an actual action occurs. In most cases, you can potentially cancel or modify the impending event. Note that in before events any APIs that modify gameplay state will not function and will throw an error. (e.g., dimension.spawnEntity)

Properties

chatSend effectAdd entityRemove explosion itemUse itemUseOn playerBreakBlock playerGameModeChange playerInteractWithBlock playerInteractWithEntity playerLeave playerPlaceBlock weatherChange worldInitialize

Properties

Readonly BetachatSend

chatSend: ChatSendBeforeEventSignal

Remarks

This event is triggered after a chat message has been broadcast or sent to players.

Example: customCommand.ts

import { world, DimensionLocation } from "@minecraft/server";

function customCommand(targetLocation: DimensionLocation) {
  const chatCallback = world.beforeEvents.chatSend.subscribe((eventData) => {
    if (eventData.message.includes("cancel")) {
      // Cancel event if the message contains "cancel"
      eventData.cancel = true;
    } else {
      const args = eventData.message.split(" ");

      if (args.length > 0) {
        switch (args[0].toLowerCase()) {
          case "echo":
            // Send a modified version of chat message
            world.sendMessage(`Echo '${eventData.message.substring(4).trim()}'`);
            break;
          case "help":
            world.sendMessage(`Available commands: echo <message>`);
            break;
        }
      }
    }
  });
}

Example: subscribe.js

import { WeatherType, system, world } from "@minecraft/server";

world.beforeEvents.chatSend.subscribe((event) => {
    const { message, sender } = event;
    const { dimension } = sender;

    if (message === "!weather clear") {
        event.cancel = true;
        system.run(() => {
            dimension.setWeather(WeatherType.Clear);
        });
    }
});

ReadonlyeffectAdd

effectAdd: EffectAddBeforeEventSignal

Remarks

This event is triggered after an event has been added to an entity.

Example: cancelEffect.js

import { Player, world } from "@minecraft/server";

world.beforeEvents.effectAdd.subscribe((event) => {
    if (event.entity instanceof Player) {
        // Cancel any effects that apply to players.
        event.cancel = true;

        // Message player that effect is not added
        event.entity.sendMessage("You can't get the following effect:");
        // For some reason, the effect type is translated based on server's language.
        event.entity.sendMessage("Effect Type: " + event.effectType);
        event.entity.sendMessage("Effect Duration: " + event.duration);
    }
});

ReadonlyentityRemove

entityRemove: EntityRemoveBeforeEventSignal

Remarks

Fires before an entity is removed from the world (for example, unloaded or removed after being killed.)

Example: spawnLightning.ts

import { world } from "@minecraft/server";

// Subscribe to entityRemove event
world.beforeEvents.entityRemove.subscribe((data) => {
    world.sendMessage("Entity Removed: " + data.removedEntity.typeId);
    // Spawn lightning when an entity is removed.
    data.removedEntity.runCommandAsync("summon lightning_bolt ~ ~10 ~");
});

Readonlyexplosion

explosion: ExplosionBeforeEventSignal

Remarks

This event is fired after an explosion occurs.

Example: cancelExplosion.ts

import { world } from "@minecraft/server";

world.beforeEvents.explosion.subscribe((data) => {
    world.sendMessage("Explosion at " + data.dimension.id + " dimension.");
    data.cancel = true;
});

Example: disableBlockDestroy.ts

import { world } from "@minecraft/server";

world.beforeEvents.explosion.subscribe((data) => {
    // Force the explosion to not destroy blocks, but it can impact entities still.
    data.setImpactedBlocks([]);
});

ReadonlyitemUse

itemUse: ItemUseBeforeEventSignal

Remarks

This event fires when an item is successfully used by a player.

ReadonlyitemUseOn

itemUseOn: ItemUseOnBeforeEventSignal

Remarks

This event fires when an item is used on a block by a player.

Example: subscribe.ts

import { world, Player, BlockPermutation } from "@minecraft/server";

// Subscribe to the itemUseOn event before it happens
world.beforeEvents.itemUseOn.subscribe((event) => {
    const { source, block, itemStack } = event;
    if (!(source instanceof Player)) return;

    source.sendMessage("You used " + itemStack.typeId + " on " + block.typeId);

    // If the item is a diamond, set the block to be a diamond block
    if (itemStack.typeId === "minecraft:diamond") {
        block.setPermutation(
            BlockPermutation.resolve("minecraft:diamond_block")
        );
    }
});

ReadonlyplayerBreakBlock

playerBreakBlock: PlayerBreakBlockBeforeEventSignal

Remarks

This event fires before a block is broken by a player.

Example: disableBlockBreaking.js

import { world } from "@minecraft/server";

// Disable the ability of a player from breaking a block.
world.beforeEvents.playerBreakBlock.subscribe((event) => {
    event.cancel = true;
    event.player.sendMessage("You can't break blocks!");
});

ReadonlyplayerGameModeChange

playerGameModeChange: PlayerGameModeChangeBeforeEventSignal

Example: disableGameModeChange.js

import { world } from "@minecraft/server";

// Disable the ability of any players without admin tag from changing gamemode.
world.beforeEvents.playerGameModeChange.subscribe((event) => {
    if (!event.player.hasTag("admin")) {
        event.cancel = true;
        event.player.sendMessage("You can't change gamemode!");
    }
});

ReadonlyplayerInteractWithBlock

playerInteractWithBlock: PlayerInteractWithBlockBeforeEventSignal

Remarks

Fires before a player interacts with a block.

Example: prompt.ts

import { system, world } from "@minecraft/server";
import { MessageFormData } from "@minecraft/server-ui";

// Subscribe to playerInteractWithBlock event to detect if a player interacts with a block
world.beforeEvents.playerInteractWithBlock.subscribe((event) => {
    // Check if player interacts with a crafter whilst holding diamonds
    if (
        event.block.typeId === "minecraft:crafter" &&
        event.itemStack &&
        event.itemStack.typeId === "minecraft:diamond"
    ) {
        // Cancel interaction
        event.cancel = true;

        // Use system.run to queue for later in the current tick to bypass read-only state
        system.run(() => {
            // Show the player a message form
            new MessageFormData()
                .title("Crafter")
                .body("This is a crafter!")
                .button1("Close")
                .show(event.player);
        });
    }
});

// Please note that playerInteractWithBlock does not fire when player interacts with air.

ReadonlyplayerInteractWithEntity

playerInteractWithEntity: PlayerInteractWithEntityBeforeEventSignal

Remarks

Fires before a player interacts with an entity.

Example: villagerPrompt.ts

import { system, world } from "@minecraft/server";
import { MessageFormData } from "@minecraft/server-ui";

// Subscribe to playerInteractWithEntity event to detect if a player interacts with a block
world.beforeEvents.playerInteractWithEntity.subscribe((event) => {
    // Check if player interacts with a villager whilst holding diamonds
    if (
        event.target.typeId === "minecraft:villager" ||
        event.target.typeId === "minecraft:villager_v2"
    ) {
        // Cancel interaction
        event.cancel = true;

        // Use system.run to queue for later in the current tick to bypass read-only state
        system.run(() => {
            // Show the player a message form
            new MessageFormData()
                .title("villager")
                .body("This is a villager!")
                .button1("Close")
                .show(event.player);
        });
    }
});

ReadonlyplayerLeave

playerLeave: PlayerLeaveBeforeEventSignal

Remarks

Fires when a player leaves the game.

Readonly BetaplayerPlaceBlock

playerPlaceBlock: PlayerPlaceBlockBeforeEventSignal

Remarks

This event fires before a block is placed by a player.

Example: onPlayerPlaceBlock.ts

import { world } from "@minecraft/server";

// Subscribe to playerPlaceBlock event
world.beforeEvents.playerPlaceBlock.subscribe((event) => {
    event.cancel = true; // Cancel place block interaction if needed.
    event.block; // Block impacted by this event.
    event.dimension; // Dimension that contains the block.
    event.permutationBeingPlaced; // Permutation of the replaced block.
    event.player; // Player that placed the block.
    event.face; // Face of the block that was placed on.
    event.faceLocation; // Location of the face that was placed on.
});

ReadonlyweatherChange

weatherChange: WeatherChangeBeforeEventSignal

ReadonlyworldInitialize

worldInitialize: WorldInitializeBeforeEventSignal

Remarks

This event fires immediately when the script environment is initialized on a World. Not all script functionality may be available. For guaranteed access to world state, use the world initialize after event.

Settings

Member Visibility

On This Page

Properties