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

Properties

type

Methods

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

Properties

Readonlytype

type: BlockType

Remarks

The BlockType that the permutation has.

Methods

canBeDestroyedByLiquidSpread

  • canBeDestroyedByLiquidSpread(liquidType: Water): 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

canContainLiquid

  • canContainLiquid(liquidType: Water): 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

getAllStates

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

  • 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

  • getItemStack(amount?: number): ItemStack

  • Parameters

    • Optionalamount: number

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

    Returns ItemStack

    Remarks

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

getState

getTags

  • getTags(): string[]

  • Returns string[]

    Remarks

    Creates a copy of the permutation.

hasTag

  • hasTag(tag: string): boolean

  • 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

  • isLiquidBlocking(liquidType: Water): 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

liquidSpreadCausesSpawn

  • liquidSpreadCausesSpawn(liquidType: Water): 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

matches

  • matches<T extends string = MinecraftBlockTypes>(
        blockName: T,
        states?: BlockStateArg<T>,
    ): boolean

  • Type Parameters

    Parameters

    • blockName: T

      An optional set of states to compare against.

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

    Example: test.js

    // Script by WavePlayz

    import { world } from "@minecraft/server";

    // Function to check if a given block is red wool
    function isRedWool(block) {
        // Define the type id of block we are checking for
        let typeId = "wool";

        // Define the block state we are looking for
        // In this case, we want the color to be red
        let states = { color: "red" };

        // Check if the block matches the specified type and states
        // The 'matches' method returns true if the block is of the specified type and has the specified states
        return block.matches(typeId, states);
    }

withState

Staticresolve

  • resolve<T extends string = MinecraftBlockTypes>(
        blockName: T,
        states?: BlockStateArg<T>,
    ): BlockPermutation

  • Type Parameters

    Parameters

    • blockName: T

      Identifier of the block to check.

    • Optionalstates: 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

On This Page

Properties
Methods