Class BlockPermutation

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

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

Hierarchy

  • BlockPermutation

Constructors

constructor

Properties

type

Methods

canBeDestroyedByLiquidSpread canContainLiquid getAllStates getItemStack getState getTags hasTag isLiquidBlocking liquidSpreadCausesSpawn matches withState resolve

Constructors

Private constructor

Properties

Readonly type

type: BlockType

Remarks

The BlockType that the permutation has.

Methods

canBeDestroyedByLiquidSpread

  • 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

canContainLiquid

  • 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

getAllStates

  • Returns Record<string, string | number | boolean>

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

    Remarks

    Returns all available block states associated with this block.

getItemStack

  • Parameters

    • Optional amount: number

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

    Returns undefined | ItemStack

    Remarks

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

getState

  • Type Parameters

    • T extends keyof BlockStateSuperset

    Parameters

    • stateName: T

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

    Returns undefined | BlockStateSuperset[T]

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

    Remarks

    Gets a state for the permutation.

getTags

  • Returns string[]

    Remarks

    Creates a copy of the permutation.

hasTag

  • 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

    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

  • 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

liquidSpreadCausesSpawn

  • 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

matches

  • Type Parameters

    • T extends string = MinecraftBlockTypes

    Parameters

    • blockName: T

      An optional set of states to compare against.

    • Optional 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

  • Type Parameters

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

Static resolve

  • Type Parameters

    • T extends string = MinecraftBlockTypes

    Parameters

    • blockName: T

      Identifier of the block to check.

    • Optional 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

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

Settings

Member Visibility

Theme

On This Page