amulet.api.block module

class amulet.api.block.Block(namespace, base_name, properties=None, extra_blocks=None)[source]

A class to manage the state of a block.

It is an immutable object that contains a namespaced name, properties and extra blocks.

Here’s a few examples on how create a Block object:

>>> # Create a block with the namespace `minecraft` and base name `stone`
>>> stone = Block("minecraft", "stone")
>>> # Create a water block with the level property
>>> water = Block(
>>>     "minecraft",  # the namespace
>>>     "water",  # the base name
>>>     {  # A dictionary of properties.
>>>         # Keys must be strings and values must be a numerical or string NBT type.
>>>         "level": StringTag("0")  # define a property `level` with a string value `1`
>>>     }
>>> )
>>> # The above two examples can also be achieved by creating the block from the Java blockstate.
>>> stone = Block.from_string_blockstate("minecraft:stone")
>>> water = Block.from_string_blockstate("minecraft:water[level=0]")

Java 1.13 added the concept of waterlogging blocks whereby some blocks have a waterlogged property. Bedrock achieved the same behaviour by added a layering system. The layering system allows any block to be the second block. In order to support both formats and future proof the editor Amulet adds the concept of extra blocks. Extra blocks are a sequence of zero or more blocks stored in the extra_blocks property of the Block instance. Amulet places no restrictions on which blocks can be extra blocks but some validation will be done when saving based on the format being saved to.

>>> # Create a waterlogged stone block.
>>> waterlogged_stone = Block("minecraft", "stone",
>>>     # extra_blocks can be a Block instance or iterable of Block instances.
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
>>> # The above can also be achieved by adding together a stone and water block.
>>> waterlogged_stone = stone + water
>>> repr(waterlogged_stone)
'Block(minecraft:stone, extra_blocks=(minecraft:water[level="0"]))'
__init__(namespace, base_name, properties=None, extra_blocks=None)[source]

Constructs a Block instance.

>>> stone = Block("minecraft", "stone")
>>>
>>> # Create a water block with the level property
>>> water = Block(
>>>     "minecraft",  # the namespace
>>>     "water",  # the base name
>>>     {  # A dictionary of properties.
>>>         # Keys must be strings and values must be a numerical or string NBT type.
>>>         "level": StringTag("0")  # define a property `level` with a string value `1`
>>>     }
>>> )
Parameters
  • namespace (str) – The string namespace of the block. eg minecraft

  • base_name (str) – The string base name of the block. eg stone

  • properties (Optional[Mapping[str, Union[ByteTag, ShortTag, IntTag, LongTag, StringTag]]]) – A dictionary of properties. Keys must be strings and values must be a numerical or string NBT type.

  • extra_blocks (Union[Block, Iterable[Block], None]) – A Block instance or iterable of Block instances

classmethod join(blocks)[source]

Join an interable of Block objects back into one block class. This is the reverse of the __iter__ method.

>>> stone = Block.from_string_blockstate("minecraft:stone")
>>> water = Block.from_string_blockstate("minecraft:water[level=0]")
>>> stone_water = Block.join([stone, water])
>>> stone_water2 = Block.join(stone_water)
>>> assert stone_water == stone_water2
Parameters

blocks (Iterable[Block]) – An iterable of one or more Block objects.

Returns

A new Block instance

classmethod from_string_blockstate(blockstate)[source]

Parse a Java format blockstate where values are all strings and populate a Block class with the data.

>>> stone = Block.from_string_blockstate("minecraft:stone")
>>> water = Block.from_string_blockstate("minecraft:water[level=0]")
Parameters

blockstate (str) – The Java blockstate string to parse.

Returns

A Block instance containing the state.

classmethod from_snbt_blockstate(blockstate)[source]

Parse a blockstate where values are SNBT of any type and populate a Block class with the data.

property namespaced_name: str[source]

The namespace:base_name of the blockstate represented by the Block object.

>>> water = Block.from_string_blockstate("minecraft:water[level=0]")
>>> water.namespaced_name
'minecraft:water'
Returns

The namespace:base_name of the blockstate

property namespace: str[source]

The namespace of the blockstate represented by the Block object.

>>> water = Block.from_string_blockstate("minecraft:water[level=0]")
>>> water.namespace
'minecraft'
Returns

The namespace of the blockstate

property base_name: str[source]

The base name of the blockstate represented by the Block object.

>>> water = Block.from_string_blockstate("minecraft:water[level=0]")
>>> water.base_name
'water'
Returns

The base name of the blockstate

property properties: Mapping[str, Union[ByteTag, ShortTag, IntTag, LongTag, StringTag]][source]

The mapping of properties of the blockstate represented by the Block object.

>>> water = Block.from_string_blockstate("minecraft:water[level=0]")
>>> water.properties
{"level": StringTag("0")}
Returns

A dictionary of the properties of the blockstate

property blockstate: str[source]

The Java blockstate string of this Block object Note if there are extra blocks this will only show the base block. Note this will only contain properties with StringTag values.

>>> stone = Block("minecraft", "stone")
>>> stone.blockstate
'minecraft:stone'
>>> water = Block("minecraft", "water", {"level": StringTag("0")})
>>> water.blockstate
`minecraft:water[level=0]`
Returns

The blockstate string

property snbt_blockstate: str[source]

A modified version of the Java blockstate format that supports all NBT types. Converts the property values to the SNBT format to preserve type. Note if there are extra blocks this will only show the base block.

>>> bell = Block("minecraft", "bell", {
>>>     "attachment":StringTag("standing"),
>>>     "direction":IntTag(0),
>>>     "toggle_bit":ByteTag(0)
>>> })
>>> bell.snbt_blockstate
'minecraft:bell[attachment="standing",direction=0,toggle_bit=0b]'
Returns

The SNBT blockstate string

property full_blockstate: str[source]

The SNBT blockstate string of the base block and extra blocks.

>>> bell = Block("minecraft", "bell", {
>>>     "attachment":StringTag("standing"),
>>>     "direction":IntTag(0),
>>>     "toggle_bit":ByteTag(0)
>>> })
>>> water = Block("minecraft", "water", {"liquid_depth": IntTag(0)})
>>> waterlogged_bell = bell + water
>>> waterlogged_bell.full_blockstate
'minecraft:bell[attachment="standing",direction=0,toggle_bit=0b]{minecraft:water[liquid_depth=0]}'
Returns

The blockstate string

property base_block: Block[source]

Returns an instance of Block containing only the base block without any extra blocks

>>> waterlogged_stone = Block("minecraft", "stone",
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
>>> waterlogged_stone.base_block
Block(minecraft:stone)
Returns

A Block object

property extra_blocks: Tuple[Block, ...][source]

Returns a tuple of the extra blocks contained in the Block instance

>>> waterlogged_stone = Block("minecraft", "stone",
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
>>> waterlogged_stone.extra_blocks
(Block(minecraft:water[level="0"]),)
Returns

A tuple of Block objects

property block_tuple: Tuple[Block, ...][source]

Returns the stack of blocks represented by this object as a tuple. This is a tuple of base_block and extra_blocks

>>> waterlogged_stone = Block("minecraft", "stone",
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
>>> waterlogged_stone.block_tuple
(Block(minecraft:stone), Block(minecraft:water[level="0"]))
Returns

A tuple of Block objects

static parse_blockstate_string(blockstate, snbt=False)[source]

Parse a Java or SNBT blockstate string and return the raw data.

To parse the blockstate and return a Block instance use from_string_blockstate() or from_snbt_blockstate()

Parameters
  • blockstate (str) – The blockstate to parse

  • snbt (bool) – Are the property values in SNBT format. If false all values must be an instance of StringTag

Return type

Tuple[str, str, Mapping[str, Union[ByteTag, ShortTag, IntTag, LongTag, StringTag]]]

Returns

namespace, block_name, properties

__str__()[source]
>>> waterlogged_stone = Block("minecraft", "stone",
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
>>> str(waterlogged_stone)
'minecraft:stone{minecraft:water[level="0"]}'
Return type

str

Returns

A string showing the information of the Block class.

__repr__()[source]
>>> waterlogged_stone = Block("minecraft", "stone",
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
>>> repr(waterlogged_stone)
'Block(minecraft:stone, extra_blocks=(minecraft:water[level="0"]))'
Return type

str

Returns

The base blockstate string of the Block object along with the blockstate strings of included extra blocks

__iter__()[source]

Iterate through all the blocks in this Block instance.

>>> waterlogged_stone = Block("minecraft", "stone",
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
>>> for block in waterlogged_stone:
>>>     print(block)
:rtype: :py:class:`~typing.Iterable`\[:py:class:`~amulet.api.block.Block`]

minecraft:stone minecraft:water[level=”0”]

__len__()[source]

The number of blocks contained within the Block instance.

>>> waterlogged_stone = Block("minecraft", "stone",
>>>     extra_blocks=Block("minecraft", "water", {"level": StringTag("0")})
>>> )
:rtype: :py:class:`int`
>>> len(waterlogged_stone)
2
__eq__(other)[source]

Checks the equality of this Block object to another Block object

>>> stone = Block("minecraft", "stone")
>>> stone == stone
True
Parameters

other (Block) – The Block object to check against

Return type

bool

Returns

True if the Blocks objects are equal, False otherwise

__gt__(other)[source]

Allows blocks to be sorted so numpy.unique can be used on them

Return type

bool

__hash__()[source]

Hashes the Block object

Return type

int

Returns

A hash of the Block object

__add__(other)[source]

Add the blocks from other to this block.

>>> stone = Block("minecraft", "stone")
>>> water = Block("minecraft", "water", {"level": StringTag("0")})
>>> waterlogged_stone = stone + water
>>> repr(waterlogged_stone)
'Block(minecraft:stone, extra_blocks=(minecraft:water[level="0"]))'
Parameters

other (Block) – The Block object to add to this Block

Return type

Block

Returns

A new instance of Block with the blocks from other appended to the end of extra_blocks

__sub__(other)[source]

Remove all blocks in other from the extra_blocks of this instance of Block

>>> stone = Block("minecraft", "stone")
>>> water = Block("minecraft", "water", {"level": StringTag("0")})
>>> waterlogged_stone = stone + water
>>> stone = waterlogged_stone - water
Parameters

other (Block) – The Block object to subtract from this Block.

Return type

Block

Returns

A new Block instance with the blocks in other removed from the extra blocks.

remove_layer(layer)[source]

Removes the block at the given index and returns the resulting new Block object.

>>> stone = Block("minecraft", "stone")
>>> water = Block("minecraft", "water", {"level": StringTag("0")})
>>> waterlogged_stone = stone + water
>>> stone = waterlogged_stone.remove_layer(1)
Parameters

layer (int) – The layer of extra block to remove.

Return type

Block

Returns

A new instance of Block with the same data but with the block at the specified layer removed.

Raises

BlockException – Raised when you remove the base block from a Block with no other extra blocks.

__sizeof__()[source]

Size of object in memory, in bytes.