Edit

Share via

BlockPermutation Class

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

Properties

type

read-only type: BlockType;

The @minecraft/server.BlockType that the permutation has.

Type: BlockType

Methods

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.

Notes:

  • This function can throw errors.

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.

Notes:

  • This function can throw errors.

getAllStates

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

Returns all available block states associated with this block.

Returns Record<string, boolean | number | string> - Returns the list of all of the block states that the permutation has.

getItemStack

getItemStack(amount?: number): ItemStack | undefined

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

Parameters

  • amount?: number = 1

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

Returns ItemStack | undefined

Notes:

getState

getState(stateName: T): minecraftvanilladata.BlockStateSuperset[T] | undefined

Gets a state for the permutation.

Parameters

  • stateName: T

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

Returns minecraftvanilladata.BlockStateSuperset[T] | undefined - Returns the state if the permutation has it, else undefined.

getTags

getTags(): string[]

Creates a copy of the permutation.

Returns string[]

hasTag

hasTag(tag: string): boolean

Checks to see if the permutation has a specific tag.

Parameters

  • tag: string

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

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.

Notes:

  • This function can throw errors.

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.

Notes:

  • This function can throw errors.

matches

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

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

Parameters

  • blockName: T

    An optional set of states to compare against.

  • states: BlockStateArg<T>

Returns boolean

withState

withState(name: T, value: minecraftvanilladata.BlockStateSuperset[T]): BlockPermutation

Returns a derived BlockPermutation with a specific property set.

Parameters

  • name: T

    Identifier of the block property.

  • value: minecraftvanilladata.BlockStateSuperset[T]

    Value of the block property.

Returns BlockPermutation

Notes:

  • This function can throw errors.

resolve

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

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)

Parameters

  • blockName: T

    Identifier of the block to check.

  • states: BlockStateArg<T>

Returns BlockPermutation

Notes:

  • This function can throw errors.

Examples

addBlockColorCube.ts
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]));
      }
    }
  }
}

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

Examples

addTranslatedSign.ts
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] });
}

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