Edit

Share via

Block Class

  • Article

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.

Properties

dimension

read-only dimension: Dimension;

Returns the dimension that the block is within.

Type: Dimension

isAir

read-only isAir: boolean;

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

Type: boolean

Notes:

isLiquid

read-only isLiquid: boolean;

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

Type: boolean

Notes:

isSolid

read-only isSolid: boolean;

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

Type: boolean

Caution

This property is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

isValid

read-only isValid: boolean;

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

Type: boolean

Caution

This property is still in pre-release. Its signature may change or it may be removed in future releases.

isWaterlogged

read-only isWaterlogged: boolean;

Returns or sets whether this block has water on it.

Type: boolean

Notes:

location

read-only location: Vector3;

Coordinates of the specified block.

Type: Vector3

Notes:

  • This property can throw errors when used.

permutation

read-only permutation: BlockPermutation;

Additional block configuration data that describes the block.

Type: BlockPermutation

Notes:

type

read-only type: BlockType;

Gets the type of block.

Type: BlockType

Notes:

typeId

read-only typeId: string;

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.

Type: string

Notes:

x

read-only x: number;

X coordinate of the block.

Type: number

y

read-only y: number;

Y coordinate of the block.

Type: number

z

read-only z: number;

Z coordinate of the block.

Type: number

Methods

above

above(steps?: number): Block | undefined

Returns the @minecraft/server.Block above this block (positive in the Y direction).

Parameters

  • steps?: number = 1

    Number of steps above to step before returning.

Returns Block | undefined

Notes:

below

below(steps?: number): Block | undefined

Returns the @minecraft/server.Block below this block (negative in the Y direction).

Parameters

  • steps?: number = 1

    Number of steps below to step before returning.

Returns Block | undefined

Notes:

bottomCenter

bottomCenter(): Vector3

Returns the @minecraft/server.Vector3 of the center of this block on the X and Z axis.

Returns Vector3

canBeDestroyedByLiquidSpread

canBeDestroyedByLiquidSpread(liquidType: LiquidType): boolean

Returns whether this block is removed when touched by liquid.

Parameters

  • liquidType: LiquidType

    The type of liquid this function should be called for.

Returns boolean - Whether this block is removed when touched by liquid.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

canContainLiquid

canContainLiquid(liquidType: LiquidType): boolean

Returns whether this block can have a liquid placed over it, i.e. be waterlogged.

Parameters

  • liquidType: LiquidType

    The type of liquid this function should be called for.

Returns boolean - Whether this block can have a liquid placed over it.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

canPlace

canPlace(blockToPlace: BlockPermutation | BlockType | string, faceToPlaceOn?: Direction): boolean

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

Parameters

  • blockToPlace: BlockPermutation | BlockType | string

    Block type or block permutation to check placement for.

  • faceToPlaceOn?: Direction = null

    Optional specific face of this block to check placement against.

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

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

center

center(): Vector3

Returns the @minecraft/server.Vector3 of the center of this block on the X, Y, and Z axis.

Returns Vector3

east

east(steps?: number): Block | undefined

Returns the @minecraft/server.Block to the east of this block (positive in the X direction).

Parameters

  • steps?: number = 1

    Number of steps to the east to step before returning.

Returns Block | undefined

Notes:

getComponent

getComponent(componentId: T): BlockComponentReturnType<T> | undefined

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

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 @minecraft/server.BlockComponentTypes enum.

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

Notes:

getItemStack

getItemStack(amount?: number, withData?: boolean): ItemStack | undefined

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

Parameters

  • amount?: number = 1

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

  • withData?: boolean = false

    Whether additional data facets of the item stack are included.

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

Notes:

getMapColor

getMapColor(): RGBA

Returns RGBA

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

getRedstonePower

getRedstonePower(): number | undefined

Returns the net redstone power of this block.

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

Notes:

getTags

getTags(): string[]

Returns a set of tags for a block.

Returns string[] - The list of tags that the block has.

Notes:

hasTag

hasTag(tag: string): boolean

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

Parameters

  • tag: string

    Tag to check for.

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

Notes:

Examples

checkBlockTags.ts
import { DimensionLocation } from "@minecraft/server";

function checkBlockTags(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  // Fetch the block
  const block = targetLocation.dimension.getBlock(targetLocation);

  // check that the block is loaded
  if (block) {
    log(`Block is dirt: ${block.hasTag("dirt")}`);
    log(`Block is wood: ${block.hasTag("wood")}`);
    log(`Block is stone: ${block.hasTag("stone")}`);
  }
}

(preview) Work with this sample on the MCTools.dev code sandbox.

isLiquidBlocking

isLiquidBlocking(liquidType: LiquidType): boolean

Returns whether this block stops liquid from flowing.

Parameters

  • liquidType: LiquidType

    The type of liquid this function should be called for.

Returns boolean - Whether this block stops liquid from flowing.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

liquidCanFlowFromDirection

liquidCanFlowFromDirection(liquidType: LiquidType, flowDirection: Direction): boolean

Returns whether liquid can flow into the block from the provided direction, or flow out from the provided direction when liquid is placed into it with a bucket.

Parameters

  • liquidType: LiquidType

    The type of liquid this function should be called for.

  • flowDirection: Direction

Returns boolean - Whether liquid can flow into the block from the provided direction, or flow out from the provided direction when liquid is placed into it with a bucket

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

liquidSpreadCausesSpawn

liquidSpreadCausesSpawn(liquidType: LiquidType): boolean

Returns whether this block is removed and spawns its item when touched by liquid.

Parameters

  • liquidType: LiquidType

    The type of liquid this function should be called for.

Returns boolean - Whether this block is removed and spawns its item when touched by liquid.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

matches

matches(blockName: string, states?: Record<string, boolean | number | string>): boolean

Tests whether this block matches a specific criteria.

Parameters

  • blockName: string

    Block type identifier to match this API against.

  • states?: Record<string, boolean | number | string> = null

    Optional set of block states to test this block against.

Returns boolean - Returns true if the block matches the specified criteria.

Notes:

north

north(steps?: number): Block | undefined

Returns the @minecraft/server.Block to the north of this block (negative in the Z direction).

Parameters

  • steps?: number = 1

    Number of steps to the north to step before returning.

Returns Block | undefined

Notes:

offset

offset(offset: Vector3): Block | undefined

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

Parameters

  • offset: Vector3

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

Returns Block | undefined - 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.)

Notes:

setPermutation

setPermutation(permutation: BlockPermutation): void

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

Parameters

  • permutation: BlockPermutation

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

Notes:

setType

setType(blockType: BlockType | string): void

Sets the type of block.

Parameters

  • blockType: BlockType | string

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

Notes:

setWaterlogged

setWaterlogged(isWaterlogged: boolean): void

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

Parameters

  • isWaterlogged: boolean

    true if the block should have water within it.

Notes:

south

south(steps?: number): Block | undefined

Returns the @minecraft/server.Block to the south of this block (positive in the Z direction).

Parameters

  • steps?: number = 1

    Number of steps to the south to step before returning.

Returns Block | undefined

Notes:

trySetPermutation

trySetPermutation(permutation: BlockPermutation): boolean

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

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.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

west

west(steps?: number): Block | undefined

Returns the @minecraft/server.Block to the west of this block (negative in the X direction).

Parameters

  • steps?: number = 1

    Number of steps to the west to step before returning.

Returns Block | undefined

Notes: