Class Block

Represents a block in a dimension. A block represents a unique X, Y, and Z within a dimension and get/sets the state of the block at that location. This type was significantly updated in version 1.17.10.21.

Example

createWall.ts 

import {
    Vector3Utils,
    VECTOR3_NORTH,
    VECTOR3_WEST,
    VECTOR3_EAST,
    VECTOR3_SOUTH,
} from "@minecraft/math";
import { Entity } from "@minecraft/server";
import { MinecraftBlockTypes } from "@minecraft/vanilla-data";

const VECTOR3_NORTHWEST = Vector3Utils.add(VECTOR3_NORTH, VECTOR3_WEST);
const VECTOR3_NORTHEAST = Vector3Utils.add(VECTOR3_NORTH, VECTOR3_EAST);
const VECTOR3_SOUTHWEST = Vector3Utils.add(VECTOR3_SOUTH, VECTOR3_WEST);
const VECTOR3_SOUTHEAST = Vector3Utils.add(VECTOR3_SOUTH, VECTOR3_EAST);

/**
 * Get the blocks from player surroundings and set to obsidian
 */
export function createWallAroundEntity(entity: Entity) {
    const location = entity.location;
    const block = entity.dimension.getBlock(location);
    if (!block) return;
    const blockNorth = block.north();
    const blockSouth = block.south();
    const blockEast = block.east();
    const blockWest = block.west();
    const blockNorthWest = block.offset(VECTOR3_NORTHWEST);
    const blockNorthEast = block.offset(VECTOR3_NORTHEAST);
    const blockSouthWest = block.offset(VECTOR3_SOUTHWEST);
    const blockSouthEast = block.offset(VECTOR3_SOUTHEAST);
    const blocks = [
        blockNorth,
        blockSouth,
        blockEast,
        blockWest,
        blockNorthWest,
        blockNorthEast,
        blockSouthWest,
        blockSouthEast,
    ];
    // Check if the player have contact with cactus or sweet berry bush
    for (const block of blocks) {
        if (!block) continue;
        block.setType(MinecraftBlockTypes.Obsidian);
    }
}

Hierarchy

  • Block

Constructors

constructor

Properties

dimension isAir isLiquid isSolid isWaterlogged location permutation type typeId x y z

Methods

above below bottomCenter canPlace center east getComponent getItemStack getMapColor getRedstonePower getTags hasTag isValid matches north offset setPermutation setType setWaterlogged south trySetPermutation west

Constructors

Private constructor

Properties

Readonly dimension

dimension: Dimension

Remarks

Returns the dimension that the block is within.

Example

blockExplode.js 

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

// Block explodes when player break block
world.afterEvents.playerBreakBlock.subscribe((event) => {
    event.block.dimension.createExplosion(event.block.location, 1);
});

Readonly isAir

isAir: boolean

Remarks

Returns true if this block is an air block (i.e., empty space).

Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Example

bridgeEgg.js 

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

// bridge egg
world.afterEvents.entitySpawn.subscribe(({ entity }) => {
    if (entity.typeId === "minecraft:egg") {
        const id = system.runInterval(() => {
            const block = entity.dimension.getBlock(entity.location).below();
            if (block.isAir)
                block.setPermutation(
                    BlockPermutation.resolve("minecraft:wool")
                );
            else system.clearRun(id);
        });
    }
});

Readonly isLiquid

isLiquid: boolean

Remarks

Returns true if this block is a liquid block - (e.g., a water block and a lava block are liquid, while an air block and a stone block are not. Water logged blocks are not liquid blocks).

Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Example

debug.ts 

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

// Block at (0, 0, 0)
const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
if (block.isLiquid) {
    console.warn("block is liquid");
}

Readonly Beta isSolid

isSolid: boolean

Remarks

Returns true if this block is solid and impassible - (e.g., a cobblestone block and a diamond block are solid, while a ladder block and a fence block are not).

Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Example

alertOnSolidBlock.js 

// Script by WavePlayz

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

// Subscribe to the event that triggers when a player places a block
world.afterEvents.playerPlaceBlock.subscribe((eventData) => {
    // Destructure the block object from the event data
    const { block } = eventData;

    // Check if the placed block is solid
    if (block.isSolid) {
        // Get the coordinates of the block's location
        let { x, y, z } = block.location;

        // Create a string of the coordinates in the format "x, y, z"
        let coordinates = [x, y, z].join(", ");

        // Send a message to the world indicating the location of the placed solid block
        world.sendMessage(
            "You placed a solid block at location: " + coordinates
        );
    }
});

Readonly Beta isWaterlogged

isWaterlogged: boolean

Remarks

Returns or sets whether this block has a liquid on it.

Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Readonly location

location: Vector3

Remarks

Coordinates of the specified block.

Throws

This property can throw when used.

Example

blockExplode.js 

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

// Block at (0, 0, 0)
const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
block.dimension.createExplosion(block.location, 10);

Readonly permutation

permutation: BlockPermutation

Remarks

Additional block configuration data that describes the block.

Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Example

blockStates.js 

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

// Block at (0, 0, 0)
const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
console.warn(block.typeId, JSON.stringify(block.permutation.getAllStates()));

Readonly type

type: BlockType

Remarks

Gets the type of block.

Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Readonly typeId

typeId: string

Remarks

Identifier of the type of block for this block. Warning: Vanilla block names can be changed in future releases, try using 'Block.matches' instead for block comparison.

Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Readonly x

x: number

Remarks

X coordinate of the block.

Readonly y

y: number

Remarks

Y coordinate of the block.

Readonly z

z: number

Remarks

Z coordinate of the block.

Methods

above

below

  • Parameters

    • Optional steps: number

      Number of steps below to step before returning.

      Optional

    Returns Block

    Remarks

    Returns the Block below this block (negative in the Y direction).

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    copy.js 

    // Script by WavePlayz

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

    // Subscribe to the event that triggers when a player places a block
    world.afterEvents.playerPlaceBlock.subscribe((eventData) => {
        // Extract the player and block objects from the event data
        const { player, block } = eventData;

        // Get the block that is directly below the block that was just placed
        const blockBelowThePlacedBlock = block.below(1);

        // Get the type of the block that is below the placed block
        const blockBelowThePlacedBlockType = blockBelowThePlacedBlock.type;

        // Set the type of the newly placed block to be the same as the block below it
        block.setType(blockBelowThePlacedBlockType);
    });

bottomCenter

  • Returns Vector3

    Remarks

    Returns the Vector3 of the center of this block on the X and Z axis.

canPlace

  • Beta

    Parameters

    • blockToPlace: string | BlockPermutation | BlockType

      Block type or block permutation to check placement for.

    • Optional faceToPlaceOn: Direction

      Optional specific face of this block to check placement against.

      Optional

    Returns boolean

    Returns true if the block type or permutation can be placed on this block, else false.

    Remarks

    Checks to see whether it is valid to place the specified block type or block permutation, on a specified face on this block

    Throws

    This function can throw errors.

    Error

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

center

  • Returns Vector3

    Remarks

    Returns the Vector3 of the center of this block on the X, Y, and Z axis.

east

getComponent

  • Type Parameters

    Parameters

    • componentId: T

      The identifier of the component (e.g., 'minecraft:inventory'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs can be found as part of the BlockComponentTypes enum.

    Returns BlockComponentTypeMap[T]

    Returns the component if it exists on the block, otherwise undefined.

    Remarks

    Gets a component (that represents additional capabilities) for a block - for example, an inventory component of a chest block.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    addChestItem.js 

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

    // Chest Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    block.setPermutation(BlockPermutation.resolve("minecraft:chest"));

    const inventory = block.getComponent("inventory").container;
    inventory.addItem(new ItemStack("minecraft:cobblestone", 64));

    Example

    editHangingSign.js 

    import {
        BlockPermutation,
        ItemStack,
        SignSide,
        world,
    } from "@minecraft/server";
    import { MinecraftBlockTypes } from "@minecraft/vanilla-data";

    // Chest Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    block.setPermutation(
        BlockPermutation.resolve(MinecraftBlockTypes.BirchHangingSign)
    );

    const sign = block.getComponent("minecraft:sign");
    sign.setText("back", SignSide.Back);
    sign.setText("front", SignSide.Front);

    Example

    editSign.js 

    import { BlockPermutation, ItemStack, world } from "@minecraft/server";
    import { MinecraftBlockTypes } from "@minecraft/vanilla-data";

    // Chest Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    block.setPermutation(
        BlockPermutation.resolve(MinecraftBlockTypes.DarkoakStandingSign)
    );

    const sign = block.getComponent("minecraft:sign");
    sign.setText("lol");

    Example

    pistonAttachedBlocks.js 

    import { BlockPermutation, ItemStack, world } from "@minecraft/server";
    import { MinecraftBlockTypes } from "@minecraft/vanilla-data";

    // Chest Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    block.setPermutation(BlockPermutation.resolve(MinecraftBlockTypes.Piston));

    const piston = block.getComponent("piston");
    console.warn(piston.state, JSON.stringify(piston.getAttachedBlocksLocations()));

getItemStack

  • Parameters

    • Optional amount: number

      Number of instances of this block to place in the item stack.

      Optional
    • Optional withData: boolean

      Whether additional data facets of the item stack are included.

      Optional

    Returns ItemStack

    An itemStack with the specified amount of items and data. Returns undefined if block type is incompatible.

    Remarks

    Creates a prototype item stack based on this block that can be used with Container/ContainerSlot APIs.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

getMapColor

getRedstonePower

  • Returns number

    Returns undefined if redstone power is not applicable to this block.

    Remarks

    Returns the net redstone power of this block.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    isPowered.js 

    // Script by WavePlayz

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

    // Function to check if a given block is powered by redstone
    function isBlockPowered(block) {
        // Get the redstone power level of the block
        // The 'getRedstonePower' method returns a number representing the power level
        // If the power level is greater than 0, it means the block is powered
        return block.getRedstonePower() > 0;
    }

getTags

hasTag

  • Parameters

    • tag: string

      Tag to check for.

    Returns boolean

    Returns true if the permutation of this block has the tag, else false.

    Remarks

    Checks to see if the permutation of this block has a specific tag.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    check_block_tags.js 

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

    // Fetch the block
    const block = world.getDimension("overworld").getBlock({ x: 1, y: 2, z: 3 });

    console.log(`Block is dirt: ${block.hasTag("dirt")}`);
    console.log(`Block is wood: ${block.hasTag("wood")}`);
    console.log(`Block is stone: ${block.hasTag("stone")}`);

isValid

  • Returns boolean

    True if this block object is still working and valid.

    Remarks

    Returns true if this reference to a block is still valid (for example, if the block is unloaded, references to that block will no longer be valid.)

matches

  • Parameters

    • blockName: string

      Block type identifier to match this API against.

    • Optional states: Record<string, string | number | boolean>

      Optional set of block states to test this block against.

      Optional

    Returns boolean

    Returns true if the block matches the specified criteria.

    Remarks

    Tests whether this block matches a specific criteria.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    test.js 

    // Script by WavePlayz

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

    // Function to check if a given block is red wool
    function isRedWool(block) {
        // Define the type id of block we are checking for
        let typeId = "wool";

        // Define the block state we are looking for
        // In this case, we want the color to be red
        let states = { color: "red" };

        // Check if the block matches the specified type and states
        // The 'matches' method returns true if the block is of the specified type and has the specified states
        return block.matches(typeId, states);
    }

north

  • Parameters

    • Optional steps: number

      Number of steps to the north to step before returning.

      Optional

    Returns Block

    Remarks

    Returns the Block to the north of this block (negative in the Z direction).

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    blockAtNorth.js 

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

    // Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    const blockAtNorth = block.north();

offset

  • Parameters

    • offset: Vector3

      The offset vector. For example, an offset of 0, 1, 0 will return the block above the current block.

    Returns Block

    Block at the specified offset, or undefined if that block could not be retrieved (for example, the block and its relative chunk is not loaded yet.)

    Remarks

    Returns a block at an offset relative vector to this block.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

setPermutation

  • Parameters

    • permutation: BlockPermutation

      Permutation that contains a set of property states for the Block.

    Returns void

    Remarks

    Sets the block in the dimension to the state of the permutation.

    This function can't be called in read-only mode.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    bedrockToAir.js 

    import { BlockPermutation, world } from "@minecraft/server";
    // Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    if (block.typeId === "minecraft:bedrock") {
        block.setPermutation(BlockPermutation.resolve("minecraft:air"));
    }

setType

  • Parameters

    • blockType: string | BlockType

      Identifier of the type of block to apply - for example, minecraft:powered_repeater.

    Returns void

    Remarks

    Sets the type of block.

    This function can't be called in read-only mode.

    Throws

    This function can throw errors.

    Error

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    troll.js 

    // Script by WavePlayz

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

    // Get all available block types in the game
    const blockTypes = BlockTypes.getAll();

    // Function to get a random block type from the list of block types
    const getRandomBlockType = () =>
        blockTypes[Math.floor(blockTypes.length * Math.random())];

    // Subscribe to the event that triggers when a player places a block
    world.afterEvents.playerPlaceBlock.subscribe((eventData) => {
        // Destructure the player and block objects from the event data
        const { player, block } = eventData;

        // Get a random block type
        const randomBlockType = getRandomBlockType();

        // Send a message to the player indicating the type of block they placed
        player.sendMessage("You placed the " + randomBlockType.id + " block, xD");

        // Change the type of the placed block to the random block type
        block.setType(randomBlockType);
    });

setWaterlogged

  • Beta

    Parameters

    • isWaterlogged: boolean

      true if the block should have water within it.

    Returns void

    Remarks

    Sets whether this block has a water logged state - for example, whether stairs are submerged within water.

    This function can't be called in read-only mode.

    Throws

    This function can throw errors.

    Error

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

south

  • Parameters

    • Optional steps: number

      Number of steps to the south to step before returning.

      Optional

    Returns Block

    Remarks

    Returns the Block to the south of this block (positive in the Z direction).

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    blockAtSouth.js 

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

    // Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    const nearbyBlock = block.south();

trySetPermutation

  • Beta

    Parameters

    • permutation: BlockPermutation

      Permutation that contains a set of property states for the Block.

    Returns boolean

    Returns true if the block permutation data was successfully set, else false.

    Remarks

    Tries to set the block in the dimension to the state of the permutation by first checking if the placement is valid.

    This function can't be called in read-only mode.

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

west

  • Parameters

    • Optional steps: number

      Number of steps to the west to step before returning.

      Optional

    Returns Block

    Remarks

    Returns the Block to the west of this block (negative in the X direction).

    Throws

    This function can throw errors.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

    Example

    blockAtWest.js 

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

    // Block at (0, 0, 0)
    const block = world.getDimension("overworld").getBlock({ x: 0, y: 0, z: 0 });
    const blockAtWest = block.west(10);

Settings

Member Visibility

Theme

On This Page