#Class: Block

Beta

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

readonly dimension: Dimension

Beta

#Remarks

Returns the dimension that the block is within.

#isAir

readonly isAir: boolean

Beta

#Remarks

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

#Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#isLiquid

readonly isLiquid: boolean

Beta

#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

#isSolid

readonly isSolid: boolean

Beta

#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

#isValid

readonly isValid: boolean

Beta

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

#isWaterlogged

readonly isWaterlogged: boolean

Beta

#Remarks

Returns or sets whether this block has water on it.

#Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#localizationKey

readonly localizationKey: string

Beta

#Remarks

Key for the localization of this block's name used in .lang files.

#Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#location

readonly location: Vector3

Beta

#Remarks

Coordinates of the specified block.

#Throws

This property can throw when used.

#permutation

readonly permutation: BlockPermutation

Beta

#Remarks

Additional block configuration data that describes the block.

#Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#type

readonly type: BlockType

Beta

#Remarks

Gets the type of block.

#Throws

This property can throw when used.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#typeId

readonly typeId: string

Beta

#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

#x

readonly x: number

Beta

#Remarks

X coordinate of the block.

#y

readonly y: number

Beta

#Remarks

Y coordinate of the block.

#z

readonly z: number

Beta

#Remarks

Z coordinate of the block.

#Methods

#above()

above(steps?): Block | undefined

Beta

#Parameters

#steps?

number

Number of steps above to step before returning. Defaults to: 1

#Returns

Block | undefined

#Remarks

Returns the Block above this block (positive in the Y direction).

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#below()

below(steps?): Block | undefined

Beta

#Parameters

#steps?

number

Number of steps below to step before returning. Defaults to: 1

#Returns

Block | undefined

#Remarks

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

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#bottomCenter()

bottomCenter(): Vector3

Beta

#Returns

Vector3

#Remarks

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

#canBeDestroyedByLiquidSpread()

canBeDestroyedByLiquidSpread(liquidType): boolean

Beta

#Parameters

#liquidType

Water

The type of liquid this function should be called for.

#Returns

boolean

Whether this block is removed when touched by liquid.

#Remarks

Returns whether this block is removed when touched by liquid.

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#canContainLiquid()

canContainLiquid(liquidType): boolean

Beta

#Parameters

#liquidType

Water

The type of liquid this function should be called for.

#Returns

boolean

Whether this block can have a liquid placed over it.

#Remarks

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

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#canPlace()

canPlace(blockToPlace, faceToPlaceOn?): boolean

Beta

#Parameters

#blockToPlace

string | BlockPermutation | BlockType

Block type or block permutation to check placement for.

#faceToPlaceOn?

Direction

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.

#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()

center(): Vector3

Beta

#Returns

Vector3

#Remarks

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

#east()

east(steps?): Block | undefined

Beta

#Parameters

#steps?

number

Number of steps to the east to step before returning. Defaults to: 1

#Returns

Block | undefined

#Remarks

Returns the Block to the east of this block (positive in the X direction).

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#getComponent()

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

Beta

#Type Parameters

#T

T extends string

#Parameters

#componentId

T

The identifier of the component (e.g., 'minecraft:inventory'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs are those in the BlockComponentTypes enum and custom component IDs registered with the BlockComponentRegistry.

#Returns

BlockComponentReturnType<T> | undefined

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

#getComponents()

getComponents(): BlockComponent[]

Beta

#Returns

BlockComponent[]

#Remarks

Returns all scripting components that are present on this block.

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#getItemStack()

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

Beta

#Parameters

#amount?

number

Number of instances of this block to place in the item stack. Defaults to: 1 Bounds: [1, 255]

#withData?

boolean

Whether additional data facets of the item stack are included. Defaults to: false

#Returns

ItemStack | undefined

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

#getLightLevel()

getLightLevel(): number

World Mutation Beta

#Returns

number

The brightness level on the block.

#Remarks

Returns the total brightness level of light shining on a certain block.

#Throws

This function can throw errors.

InvalidArgumentError

LocationInUnloadedChunkError

#getMapColor()

getMapColor(): RGBA

Beta

#Returns

RGBA

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#getParts()

getParts(): Block[] | undefined

Beta

#Returns

Block[] | undefined

#Preview

#Remarks

Returns array of all loaded block parts if this block has the 'minecraft:multi_block' trait. If it does not have the trait returns undefined

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#getRedstonePower()

getRedstonePower(): number | undefined

Beta

#Returns

number | undefined

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

#getSkyLightLevel()

getSkyLightLevel(): number

World Mutation Beta

#Returns

number

The brightness level on the block.

#Remarks

Returns the brightness level of light shining from the sky on a certain block.

#Throws

This function can throw errors.

InvalidArgumentError

LocationInUnloadedChunkError

#getTags()

getTags(): string[]

Beta

#Returns

string[]

The list of tags that the block has.

#Remarks

Returns a set of tags for a block.

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#hasComponent()

hasComponent(componentId): boolean

Beta

#Parameters

#componentId

string

The identifier of the component (e.g., 'minecraft:inventory') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.

#Returns

boolean

#Remarks

Returns true if the specified component is present on this block.

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#hasTag()

hasTag(tag): boolean

Beta

#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

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

#isLiquidBlocking()

isLiquidBlocking(liquidType): boolean

Beta

#Parameters

#liquidType

Water

The type of liquid this function should be called for.

#Returns

boolean

Whether this block stops liquid from flowing.

#Remarks

Returns whether this block stops liquid from flowing.

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#liquidCanFlowFromDirection()

liquidCanFlowFromDirection(liquidType, flowDirection): boolean

Beta

#Parameters

#liquidType

Water

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

#Remarks

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.

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#liquidSpreadCausesSpawn()

liquidSpreadCausesSpawn(liquidType): boolean

Beta

#Parameters

#liquidType

Water

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.

#Remarks

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

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#matches()

matches(blockName, states?): boolean

Beta

#Parameters

#blockName

string

Block type identifier to match this API against.

#states?

Record<string, string | number | boolean>

Optional set of block states to test this block against.

#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

#north()

north(steps?): Block | undefined

Beta

#Parameters

#steps?

number

Number of steps to the north to step before returning. Defaults to: 1

#Returns

Block | undefined

#Remarks

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

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#offset()

offset(offset): Block | undefined

Beta

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

#Remarks

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

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#setPermutation()

setPermutation(permutation): void

World Mutation Beta

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

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#setType()

setType(blockType): void

World Mutation Beta

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

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#setWaterlogged()

setWaterlogged(isWaterlogged): void

World Mutation 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.

#Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#south()

south(steps?): Block | undefined

Beta

#Parameters

#steps?

number

Number of steps to the south to step before returning. Defaults to: 1

#Returns

Block | undefined

#Remarks

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

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#trySetPermutation()

trySetPermutation(permutation): boolean

Beta World Mutation

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

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#west()

west(steps?): Block | undefined

Beta

#Parameters

#steps?

number

Number of steps to the west to step before returning. Defaults to: 1

#Returns

Block | undefined

#Remarks

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

#Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

#同领域相关

• BlockBoundingBox
• BlockBoundingBoxUtils
• BlockComponent
• BlockComponentBlockBreakEvent
• BlockComponentBlockStateChangeEvent
• BlockComponentEntityEvent