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

getAllStates getItemStack getState getTags hasTag matches withState resolve

Constructors

Private constructor

Properties

Readonly type

type: BlockType

Remarks

The BlockType that the permutation has.

Methods

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

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