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 minecraftbase_name (
str
) – The string base name of the block. eg stoneproperties (
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
]) – ABlock
instance or iterable ofBlock
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
- 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 usefrom_string_blockstate()
orfrom_snbt_blockstate()
- __str__()[source]¶
>>> waterlogged_stone = Block("minecraft", "stone", >>> extra_blocks=Block("minecraft", "water", {"level": StringTag("0")}) >>> ) >>> str(waterlogged_stone) 'minecraft:stone{minecraft:water[level="0"]}'
- __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
- 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
- __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"]))'
- __sub__(other)[source]¶
Remove all blocks in other from the
extra_blocks
of this instance ofBlock
>>> stone = Block("minecraft", "stone") >>> water = Block("minecraft", "water", {"level": StringTag("0")}) >>> waterlogged_stone = stone + water >>> stone = waterlogged_stone - water
- 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
- 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.