mcstructure#

Note

In the entire project (and officially since the “Better Together Update”) the term “Minecraft” refers to the edition of Minecraft that is also known as “Bedrock Edition”.

Features that this library provide are only useful for the above named edition of Minecraft.

This library lets you programmatically create and edit Minecraft structures. You are able to save these as .mcstructure files and for example use them in behavior packs.

You may aswell read them and identify blocks and and entities that were saved with a Structure Block in-game.

Installation#

pip install mcstructure

Basic Usage#

from mcstructure import Block, Structure

struct = Structure(
    (7, 7, 7),
    Block("minecraft:wool", color = "red")
)

(struct
    .set_block((1, 1, 1), Block("minecraft:grass"))
    .set_block((2, 2, 2), Block("minecraft:grass"))
    .set_block((3, 3, 3), Block("minecraft:grass"))
    .set_block((4, 4, 4), Block("minecraft:grass"))
    .set_block((5, 5, 5), Block("minecraft:grass"))
    .set_block((6, 6, 6), Block("minecraft:grass"))
)

with open("house.mcstructure", "wb") as f:
    struct.dump(f)

with open("house.mcstructure", "rb") as f:
    struct = Structure.load(f)

API#

Read and write Minecraft .mcstructure files.

mcstructure.is_valid_structure_name(name, with_prefix=False)#

Validates the structure name.

Parameters

  • name (str) – The name of the structure.

  • with_prefix (bool) – Whether to take the prefix (e.g. mystructure:) into account.

Return type

bool

class mcstructure.Block(identifier, **states)#
name#

The name of the block.

states#

The states of the block.

Type

dict[str, Any]

Example

Block("minecraft:wool", color = "red")
Parameters

  • identifier (str) – The identifier of the block (e.g. “minecraft:wool”).

  • states (dict[str, Any]) – The block states such as “color” or “stone_type”. This varies by every block.

identifier: str#
states: dict[str, Any]#
get_namespace_and_name()#

Returns the namespace and the name of the block.

Return type

tuple[Optional[str], str]

get_name()#

Returns the name of the block.

Return type

str

get_namespace()#

Returns the namespace of the block.

Return type

Optional[str]

class mcstructure.Structure(size, fill=Block(identifier='minecraft:air', states={}))#

Class representing a Minecraft structure that consists of blocks and entities.

size#

The size of the structure.

Parameters

  • size (tuple[int, int, int]) – The size of the structure.

  • fill (Optional[Block]) –

    Fill the structure with this block at creation of a new structure object.

    If this is set to None the structure is filled with “Structure Void” blocks. Or defaultly it’ll be filled with “air”.

classmethod load(file)#

Loads an mcstructure file.

Parameters

file (BinaryIO) – File object to read.

property size: tuple[int, int, int]#
get_structure()#

Returns the structure as a numpy array filled with the corresponding block objects.

Return type

numpy.ndarray[Any, numpy.dtype[mcstructure.Block]]

dump(file)#

Serialize the structure as a mcstructure.

Parameters

file (BinaryIO) – File object to write to.

Return type

None

mirror(axis)#

Flips the structure.

Parameters

axis (str) – Turn the structure either the X or Z axis. Use "X", "x",``”Z”`` or "z".

Return type

mcstructure.Structure

rotate(by)#

Rotates the structure.

Parameters

by (int) – Rotates the structure by 90, 180 or 270 degrees.

Return type

mcstructure.Structure

get_block(coordinate)#

Returns the block in a specific position.

Parameters

coordinate (Tuple[int, int, int]) – The coordinte of the block.

Return type

Optional[mcstructure.Block]

set_block(coordinate, block)#

Puts a block into the structure.

Parameters

  • coordinate (Tuple[int, int, int]) – Relative coordinates of the block’s position.

  • block (Optional[mcstructure.Block]) – The block to place. If this is set to None “Structure Void” will be used.

Return type

mcstructure.Structure

set_blocks(from_coordinate, to_coordinate, block)#

Puts multiple blocks into the structure.

Parameters

  • from_coordinate (Tuple[int, int, int]) – Relative coordinates of the block’s position where you may want to start fill

  • to_coordinate (Tuple[int, int, int]) – Relative coordinates of the block’s position where you may want to end fill

  • points (Note! The fill will include both start and end) –

  • block (mcstructure.Block) – The block to place. If this is set to None “Structure Void” will be used to fill.

Return type

mcstructure.Structure