Bedrock API Reference

Appearance

@minecraft/server

@minecraft/server / BlockPermutation

Class: BlockPermutation ​

Defined in: @minecraft/server/index.d.ts:5082

Contains the combination of type BlockType and properties (also sometimes called block state) which describe a block (but does not belong to a specific Block).

Example ​

addTranslatedSign.ts

typescript
import { world, BlockPermutation, BlockSignComponent, BlockComponentTypes, DimensionLocation } from '@minecraft/server';
import { MinecraftBlockTypes } from '@minecraft/vanilla-data';

function addTranslatedSign(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const players = world.getPlayers();

  const dim = players[0].dimension;

  const signBlock = dim.getBlock(targetLocation);

  if (!signBlock) {
    log('Could not find a block at specified location.');
    return -1;
  }
  const signPerm = BlockPermutation.resolve(MinecraftBlockTypes.StandingSign, { ground_sign_direction: 8 });

  signBlock.setPermutation(signPerm);

  const signComponent = signBlock.getComponent(BlockComponentTypes.Sign) as BlockSignComponent;

  signComponent?.setText({ translate: 'item.skull.player.name', with: [players[0].name] });
}

Properties ​

localizationKey ​

readonly localizationKey: string

Defined in: @minecraft/server/index.d.ts:5090

Remarks ​

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

type ​

readonly type: BlockType

Defined in: @minecraft/server/index.d.ts:5096

Remarks ​

The BlockType that the permutation has.

Methods ​

canBeDestroyedByLiquidSpread() ​

canBeDestroyedByLiquidSpread(liquidType): boolean

Defined in: @minecraft/server/index.d.ts:5108

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.

canContainLiquid() ​

canContainLiquid(liquidType): boolean

Defined in: @minecraft/server/index.d.ts:5120

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.

getAllStates() ​

getAllStates(): Record<string, boolean | number | string>

Defined in: @minecraft/server/index.d.ts:5130

Returns ​

Record<string, boolean | number | string>

Returns the list of all of the block states that the permutation has.

Remarks ​

Returns all available block states associated with this block.

getItemStack() ​

getItemStack(amount?): ItemStack | undefined

Defined in: @minecraft/server/index.d.ts:5143

Parameters ​

amount? ​

number

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

Returns ​

ItemStack | undefined

Remarks ​

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

getState() ​

getState<T>(stateName): BlockStateSuperset[T] | undefined

Defined in: @minecraft/server/index.d.ts:5154

Type Parameters ​

T ​

T extends keyof BlockStateSuperset

Parameters ​

stateName ​

T

Name of the block state who's value is to be returned.

Returns ​

BlockStateSuperset[T] | undefined

Returns the state if the permutation has it, else undefined.

Remarks ​

Gets a state for the permutation.

getTags() ​

getTags(): string[]

Defined in: @minecraft/server/index.d.ts:5162

Returns ​

string[]

Remarks ​

Creates a copy of the permutation.

hasTag() ​

hasTag(tag): boolean

Defined in: @minecraft/server/index.d.ts:5186

Parameters ​

tag ​

string

Returns ​

boolean

Returns true if the permutation has the tag, else false.

Remarks ​

Checks to see if the permutation has a specific tag.

Example ​

checkBlockTags.ts

typescript
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

Defined in: @minecraft/server/index.d.ts:5197

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.

liquidSpreadCausesSpawn() ​

liquidSpreadCausesSpawn(liquidType): boolean

Defined in: @minecraft/server/index.d.ts:5210

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.

matches() ​

matches<T>(blockName, states?): boolean

Defined in: @minecraft/server/index.d.ts:5220

Type Parameters ​

T ​

T extends string = MinecraftBlockTypes

Parameters ​

blockName ​

T

An optional set of states to compare against.

states? ​

BlockStateArg<T>

Returns ​

boolean

Remarks ​

Returns a boolean whether a specified permutation matches this permutation. If states is not specified, matches checks against the set of types more broadly.

withState() ​

withState<T>(name, value): BlockPermutation

Defined in: @minecraft/server/index.d.ts:5235

Type Parameters ​

T ​

T extends keyof BlockStateSuperset

Parameters ​

name ​

T

Identifier of the block property.

value ​

BlockStateSuperset[T]

Value of the block property.

Returns ​

BlockPermutation

Remarks ​

Returns a derived BlockPermutation with a specific property set.

Throws ​

This function can throw errors.

resolve() ​

static resolve<T>(blockName, states?): BlockPermutation

Defined in: @minecraft/server/index.d.ts:5291

Type Parameters ​

T ​

T extends string = MinecraftBlockTypes

Parameters ​

blockName ​

T

Identifier of the block to check.

states? ​

BlockStateArg<T>

Returns ​

BlockPermutation

Remarks ​

Given a type identifier and an optional set of properties, will return a BlockPermutation object that is usable in other block APIs (e.g., block.setPermutation)

Throws ​

This function can throw errors.

Example ​

addBlockColorCube.ts

typescript
import { BlockPermutation, DimensionLocation } from '@minecraft/server';
import { Vector3Utils } from '@minecraft/math';
import { MinecraftBlockTypes } from '@minecraft/vanilla-data';

function addBlockColorCube(targetLocation: DimensionLocation) {
  const allWoolBlocks: string[] = [
    MinecraftBlockTypes.WhiteWool,
    MinecraftBlockTypes.OrangeWool,
    MinecraftBlockTypes.MagentaWool,
    MinecraftBlockTypes.LightBlueWool,
    MinecraftBlockTypes.YellowWool,
    MinecraftBlockTypes.LimeWool,
    MinecraftBlockTypes.PinkWool,
    MinecraftBlockTypes.GrayWool,
    MinecraftBlockTypes.LightGrayWool,
    MinecraftBlockTypes.CyanWool,
    MinecraftBlockTypes.PurpleWool,
    MinecraftBlockTypes.BlueWool,
    MinecraftBlockTypes.BrownWool,
    MinecraftBlockTypes.GreenWool,
    MinecraftBlockTypes.RedWool,
    MinecraftBlockTypes.BlackWool,
  ];

  const cubeDim = 7;

  let colorIndex = 0;

  for (let x = 0; x <= cubeDim; x++) {
    for (let y = 0; y <= cubeDim; y++) {
      for (let z = 0; z <= cubeDim; z++) {
        colorIndex++;
        targetLocation.dimension
          .getBlock(Vector3Utils.add(targetLocation, { x, y, z }))
          ?.setPermutation(BlockPermutation.resolve(allWoolBlocks[colorIndex % allWoolBlocks.length]));
      }
    }
  }
}