API Refernce¶

Read and write Minecraft .mcstructure files.

mcstructure.COMPABILITY_VERSION: int = 17959425¶: The compability version for a block. The four bytes making up this integer determine the game version number. For example, 17879555 is 01 10 D2 03 in hex meaning 1.16.210.03.

mcstructure.STRUCTURE_MAX_SIZE: tuple[int, int, int] = (64, 384, 64)¶: The maximum size a structure can have. This does not apply for structures created externally and thus is not affect structures created with this library.

mcstructure.is_valid_structure_name(name: str, *, with_prefix: bool = False) → bool¶

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

mcstructure.has_suitable_size(size: tuple[int, int, int]) → bool¶

Returns False if size is greater than the size of structures that can be created within Minecraft.

See also

STRUCTURE_MAX_SIZE

Parameters:: size (tuple[int, int, int])
Return type:: bool

class mcstructure.Block(identifier: str, *, waterlogged: bool = False, block_entity_data: Sequence[Tag[Any, Any]] | None = None, tick_queue_data: Tag[Any, Any] | None = None, **states: str | bool | int)¶

name¶: The name of the block.

states¶

The states of the block.

Type:: dict[str, str | bool | int]

Examples

Block("minecraft:beehive", honey_level=4)
Block("minecraft:grass")

Parameters:

identifier (str) – The identifier of the block (e.g. “minecraft:wool”).
states (dict[str, str | bool | int]) –
The block states such as color or stone_type. This varies by every block.

See also

https://learn.microsoft.com/en-us/minecraft/creator/reference/content/blockreference/examples/blockstateslist
waterlogged (bool) – Whether this block is waterlogged.
block_entity_data (collections.abc.Sequence[nbtx.Tag[Any, Any]] | None) – Block entity data like the content of a container.
tick_queue_data (nbtx.Tag[Any, Any] | None)

identifier: str¶

states: dict[str, str | bool | int]¶

waterlogged: bool¶

block_entity_data: Sequence[Tag[Any, Any]] | None¶

tick_queue_data: Tag[Any, Any] | None¶

stringify(*, with_namespace: bool = True, with_states: bool = True) → str¶

Returns a human-readable representation of the block.

This format matches the one used for commands like setblock.

Parameters:

with_namespace (bool) – Whether to include the block’s namespace.
with_states (bool) – Whether to include the block’s states.

Return type:

str

property namespace_and_name: tuple[str | None, str]¶

The namespace and the name of the block.

Examples

>>> from mcstructure import Block
>>>
>>> block = Block("minecraft:wool", color="red")
>>> block.namespace_and_name
("minecraft", "wool")
>>>
>>> block = Block("foobar")
>>> block.namespace_and_name
(None, "foobar")

property name: str¶

The name of the block.

Examples

>>> from mcstructure import Block
>>>
>>> block = Block("minecraft:wool", color="red")
>>> block.name
"wool"
>>>
>>> block = Block("foobar")
>>> block.name
"foobar"

property namespace: str | None¶

The namespace of the block.

Examples

>>> from mcstructure import Block
>>>
>>> block = Block("minecraft:wool", color="red")
>>> block.namespace
"minecraft"
>>>
>>> block = Block("foobar")
>>> (block.namespace,)
(None,)

class mcstructure.Structure(size: tuple[int, int, int], fill: Block | None = Block(identifier='minecraft:air', states={}, waterlogged=False, block_entity_data=None, tick_queue_data=None))¶

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

structure¶: The numpy array representing the blocks in the structure. Each entry is an ID associated with a block present in palette().

entities¶: A list of entities the structure contains.

_size¶: Size of the structure stored internally.

_palette¶: Internal list of blocks that are used within the structure. The position of the block in the list represents its ID. Modification of this list should be done with caution and if you do so consider modifying structure appropriately. Instead use methods like set_block().

Parameters:

size (tuple[int, int, int]) – The size of the structure.
fill (Block | None) –
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.

'minecraft:air' is used as default.

classmethod load(file: BinaryIO) → Self¶

Loads a structure from a file.

Examples

from mcstructure import Structure

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

Parameters:: file (BinaryIO) – File object to read.
Return type:: Self

property size: tuple[int, int, int]¶: The size of the structure.

property palette: list[Block]¶: A copy of the palette.

get_structure() → ndarray[tuple[Any, ...], dtype[Any]]¶

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

Return type:: ndarray[tuple[Any, …], dtype[Any]]

as_nbt() → TagCompound[Any, Any]¶

Serialize the structure as a NBT data.

Examples

from mcstructure import Structure

struct = Structure((5, 5, 5), None)
nbt = struct.as_nbt()
print(nbt.pretty())

Return type:: TagCompound[Any, Any]

dump(file: BinaryIO) → None¶

Serialize the structure as a NBT file.

Examples

from mcstructure import Structure

struct = Structure((5, 5, 5), None)
with open("house.mcstructure", "wb") as f:
    struct.dump(f)

Parameters:: file (BinaryIO) – File object to write to.
Return type:: None

get_block(coordinate: Tuple[int, int, int]) → Block | None¶

Returns the block in a specific position.

Parameters:: coordinate (Tuple[int, int, int]) – The coordinte of the block.
Return type:: Block | None

add_entity(nbt_data: Tag[Any, Any]) → Self¶

Adds an entity to the structure.

Parameters:: nbt_data (Tag[Any, Any]) – The NBT data of the entity to add. The best approach would be to export a structure from the game, display the NBT data and use that as a reference.
Return type:: Self

set_block(coordinate: Tuple[int, int, int], block: Block | None) → Self¶

Places a block in the structure.

Parameters:

coordinate (Tuple[int, int, int]) – Relative coordinates of the block’s position.
block (Block | None) – The block to place. If this is set to None “Structure Void” blocks will be used.

Return type:

Self

set_blocks(from_coordinate: Tuple[int, int, int], to_coordinate: Tuple[int, int, int], block: Block) → Self¶

Fills an area in the structure with blocks.

Notes

Both start and end points are included.

Parameters:

from_coordinate (Tuple[int, int, int]) – Relative coordinates of the start edge.
to_coordinate (Tuple[int, int, int]) – Relative coordinates of the end edge.
block (Block) – The block to place. If this is set to None “Structure Void” blocks will be used to fill.

Return type:

Self

resize(size: tuple[int, int, int], fill: Block | None = Block(identifier='minecraft:air', states={}, waterlogged=False, block_entity_data=None, tick_queue_data=None)) → Self¶

Resizes the structure.

This function erases blocks that are out of bounds and fill newly created space with fill (default is air).

Parameters:

size (tuple[int, int, int]) – The new size of the structure.
fill (Block | None) – The block to fill newly created space with. If this is set to None (default) then “Structure Void” blocks will be used.

Return type:

Self

combine(other: Structure, position: Tuple[int, int, int] = (0, 0, 0)) → Structure¶

Combines another structure into this structure.

Parameters:

other (Structure) – The other structure to combine with.
position (Tuple[int, int, int]) –
The position to place the other structure at.

note: This position is relative to the current structure’s origin. ( no negative coordinates allowed )

Returns:

The combined structure.

Return type:

Structure