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

createTranslatedSign.ts

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

Hierarchy

  • BlockPermutation

Constructors

Properties

type: BlockType

Remarks

The BlockType that the permutation has.

Methods

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

  • Parameters

    • Optional amount: number

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

      Optional

    Returns ItemStack

    Remarks

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

  • Parameters

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

  • Returns string[]

    Remarks

    Creates a copy of the permutation.

  • 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

    check_block_tags.js

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

  • Parameters

    • blockName: string

      An optional set of states to compare against.

    • Optional states: Record<string, string | number | boolean>
      Optional

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

  • Parameters

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

  • Parameters

    • blockName: string

      Identifier of the block to check.

    • Optional states: Record<string, string | number | boolean>
      Optional

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