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

// A function the creates a sign at the specified location with the specified text
import { DimensionLocation, BlockPermutation, BlockComponentTypes } from '@minecraft/server';
import { MinecraftBlockTypes } from '@minecraft/vanilla-data';

function createSignAt(location: DimensionLocation) {
    const signBlock = location.dimension.getBlock(location);

    if (!signBlock) {
        console.warn('Could not find a block at specified location.');
        return;
    }

    const signPerm = BlockPermutation.resolve(MinecraftBlockTypes.StandingSign, { ground_sign_direction: 8 });
    signBlock.setPermutation(signPerm); // Update block to be a sign

    // Update the sign block's text
    // with "Steve's Head"
    const signComponent = signBlock.getComponent(BlockComponentTypes.Sign);
    if (signComponent) {
        signComponent.setText({ translate: 'item.skull.player.name', with: ['Steve'] });
    }
}

Constructors

new BlockPermutation()

private new BlockPermutation(): BlockPermutation

Returns

BlockPermutation

Properties

type

Beta

readonly type: BlockType

Remarks

The BlockType that the permutation has.

Methods

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?): ItemStack

Parameters

Parameter	Type	Description
amount?	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()

getState(stateName): string | number | boolean

Parameters

Parameter	Type	Description
stateName	string	Name of the block state who's value is to be returned.

Returns

string | number | boolean

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

Remarks

Gets a state for the permutation.

---

getTags()

Beta

getTags(): string[]

Returns

string[]

Remarks

Creates a copy of the permutation.

---

hasTag()

Beta

hasTag(tag): boolean

Parameters

Parameter	Type
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

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

// Fetch the block
const block = world.getDimension("overworld").getBlock({ x: 1, y: 2, z: 3 });
const blockPerm = block.getPermutation();

console.log(`Block is dirt: ${blockPerm.hasTag("dirt")}`);
console.log(`Block is wood: ${blockPerm.hasTag("wood")}`);
console.log(`Block is stone: ${blockPerm.hasTag("stone")}`);

---

matches()

matches(blockName, states?): boolean

Parameters

Parameter	Type	Description
blockName	string	An optional set of states to compare against.
states?	Record<string, string | number | boolean>	-

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(name, value): BlockPermutation

Parameters

Parameter	Type	Description
name	string	Identifier of the block property.
value	string | number | boolean	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(blockName, states?): BlockPermutation

Parameters

Parameter	Type	Description
blockName	string	Identifier of the block to check.
states?	Record<string, string | number | boolean>	-

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

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

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;

function placeRainbowCube(location: DimensionLocation) {
    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++;
                location.dimension
                    .getBlock({ x: location.x + x, y: location.y + y, z: location.z + z })
                    ?.setPermutation(BlockPermutation.resolve(allWoolBlocks[colorIndex % allWoolBlocks.length]));
            }
        }
    }
}