mkmd#

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)#
Parameters

  • identifier (str) –

  • states (dict[str, Any]) –

name#

The name of the block.

states#

The states of the block.

Type

dict[str, Any]

Example

Block(“minecraft:wool”, color = “red”)

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

tuple[Optional[str], str]

get_name()#
Return type

str

get_namespace()#
Return type

Optional[str]

class mcstructure.Structure(size, fill=Block(identifier='minecraft:air', states={}))#
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.

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

get_block(coordinate)#
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)#
Parameters

  • from_coordinate (tuple[int, int, int]) –

  • to_coordinate (tuple[int, int, int]) –

  • block (mcstructure.Block) –

Return type

mcstructure.Structure