Script API - v1.21.60
    Preparing search index...

    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)

    Index

    Constructors

    constructor

    Properties

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

    Constructors

    Properties

    chatSend: ChatSendBeforeEventSignal

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

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

    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);
            });
        }
    });
    effectAdd: EffectAddBeforeEventSignal

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

    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);
        }
    });
    entityRemove: EntityRemoveBeforeEventSignal

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

    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 ~");
    });
    explosion: ExplosionBeforeEventSignal

    This event is fired after an explosion occurs.

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

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

    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([]);
    });
    itemUse: ItemUseBeforeEventSignal

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

    itemUseOn: ItemUseOnBeforeEventSignal

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

    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"),
            );
        }
    });
    playerBreakBlock: PlayerBreakBlockBeforeEventSignal

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

    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!");
    });
    playerGameModeChange: PlayerGameModeChangeBeforeEventSignal
    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!");
        }
    });
    playerInteractWithBlock: PlayerInteractWithBlockBeforeEventSignal

    Fires before a player interacts with a block.

    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.
    playerInteractWithEntity: PlayerInteractWithEntityBeforeEventSignal

    Fires before a player interacts with an entity.

    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);
            });
        }
    });
    playerLeave: PlayerLeaveBeforeEventSignal

    Fires when a player leaves the game.

    playerPlaceBlock: PlayerPlaceBlockBeforeEventSignal

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

    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.
    });
    weatherChange: WeatherChangeBeforeEventSignal
    worldInitialize: WorldInitializeBeforeEventSignal

    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

    Constructors
    Properties