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

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

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

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

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

above(steps?: number): Block
Parameters
- Optionalsteps: number
  Number of steps above to step before returning.
Returns Block
Remarks
Returns the Block above this block (positive in the Y direction).

Throws
This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

below

below(steps?: number): Block
Parameters
- Optionalsteps: number
  Number of steps below to step before returning.
Returns Block
Remarks
Returns the Block below this block (negative in the Y direction).

Throws
This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

bottomCenter

bottomCenter(): Vector3
Returns Vector3
Remarks
Returns the @minecraft/server.Location of the center of this block on the X and Z axis.

canPlace

canPlace(
blockToPlace: string | BlockPermutation | BlockType,
faceToPlaceOn?: Direction,
): boolean
Beta
Parameters
- blockToPlace: string | BlockPermutation | BlockType
  Block type or block permutation to check placement for.
- OptionalfaceToPlaceOn: 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
Returns Vector3
Remarks
Returns the @minecraft/server.Location of the center of this block on the X, Y, and Z axis.

east

east(steps?: number): Block
Parameters
- Optionalsteps: number
  Number of steps to the east to step before returning.
Returns Block
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 extends keyof BlockComponentTypeMap>(
componentId: T,
): BlockComponentTypeMap[T]

Type Parameters

T extends keyof BlockComponentTypeMap

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

getItemStack(amount?: number, withData?: boolean): ItemStack
Parameters
- Optionalamount: number
  Number of instances of this block to place in the item stack.
- OptionalwithData: boolean
  Whether additional data facets of the item stack are included.
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

getRedstonePower

getRedstonePower(): number
Beta
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

getTags

getTags(): string[]
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

hasTag

hasTag(tag: string): boolean
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

isValid(): boolean
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

matches(
blockName: string,
states?: Record<string, string | number | boolean>,
): boolean
Parameters
- blockName: string
  Block type identifier to match this API against.
- Optionalstates: 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?: number): Block
Parameters
- Optionalsteps: number
  Number of steps to the north to step before returning.
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

offset(offset: Vector3): 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
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: BlockPermutation): void
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

setType(blockType: string | BlockType): void
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

setWaterlogged

setWaterlogged(isWaterlogged: boolean): void
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

south(steps?: number): Block
Parameters
- Optionalsteps: number
  Number of steps to the south to step before returning.
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

trySetPermutation(permutation: BlockPermutation): boolean
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

west(steps?: number): Block
Parameters
- Optionalsteps: number
  Number of steps to the west to step before returning.
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);
```

Class Block

Example: createWall.ts

Index

Properties

Methods

Properties

Readonlydimension

Remarks

Example: blockExplode.js

ReadonlyisAir

Remarks

Throws

Example: bridgeEgg.js

ReadonlyisLiquid

Remarks

Throws

Example: debug.ts

Readonly BetaisSolid

Remarks

Throws

Readonly BetaisWaterlogged

Remarks

Throws

Readonlylocation

Remarks

Throws

Example: blockExplode.js

Readonlypermutation

Remarks

Throws

Example: blockStates.js

Readonlytype

Remarks

Throws

ReadonlytypeId

Remarks

Throws

Readonlyx

Remarks

Readonlyy

Remarks

Readonlyz

Remarks

Methods

above

Parameters

Returns Block

Remarks

Throws

below

Parameters

Returns Block

Remarks

Throws

bottomCenter

Returns Vector3

Remarks

canPlace

Parameters

Returns boolean

Remarks

Throws

center

Returns Vector3

Remarks

east

Parameters

Returns Block

Remarks

Throws

getComponent

Type Parameters

Parameters

Returns BlockComponentTypeMap[T]

Remarks

Throws

Example: addChestItem.js

Example: editHangingSign.js

Example: editSign.js

Example: pistonAttachedBlocks.js

`Readonly`dimension

`Readonly`isAir

`Readonly`isLiquid

`Readonly` `Beta`isSolid

`Readonly` `Beta`isWaterlogged

`Readonly`location

`Readonly`permutation

`Readonly`type

`Readonly`typeId

`Readonly`x

`Readonly`y

`Readonly`z