<no title> — MCPQ 2.0.0 documentation

EntityType¶: alias of Block

class Block(value)¶

Block is a subtype of python str, so supports all standard string operations. Additionally, it supports methods to manipulate block ComponentData in component-format and name and namespace parts of a block.

Note

While the class is called Block it can also be used for items, item stacks and even entities in commands or for serialization.

from mcpq import Minecraft, Vec3, Block
mc = Minecraft()

# you can turn a normal string into a block like so:
block = Block("namespace:name[componentkey1=componentvalue1]")
block = Block("acacia_stairs[facing=east]")  # namespace 'minecraft:' can be ommited
print(block)
# >>> "acacia_stairs[facing=east]"  # note, 'Block()' is not shown, direct string

# block comparison and ordering is always done on the id:
bs = [Block("minecraft:stone"), Block("other:block_name"), Block("air"), Block("another:name")]
print(sorted(bs))
# >>> ['another:name', 'air', 'stone', 'other:block_name']
# sorted first by namespace: 'another', 'minecraft' and 'other'
# and then by name, so 'air' < 'stone'

# similarly comparison to strings with or without namespace will succeed
# while component data is ignored for normal comparison
block = Block("acacia_stairs[facing=east]")
assert block == "acacia_stairs" and block == "minecraft:acacia_stairs"
# if you want to compare component data as well, use equals()
block.equals("acacia_stairs")  # false
block.equals("acacia_stairs[half=top,facing=east]")  # false
block.equals("acacia_stairs[facing=east]")  # true
block.equals('acacia_stairs[facing="east"]')  # true

Note that constructing a Block using the Block(...) constructor does not perform any checking at all, such that invalid or unknown blocks could be constructed. To actually check if the type of the block exists on the server, use the MaterialFilter class and use withData() and withMergeData() for setting component data on blocks:

from mcpq import Minecraft
mc = Minecraft()

# returns the block and raises an error if the block does not exist
block = mc.blocks.getById("acacia_stairs")
# similarly, if you want "any wool block" you could use
wool_block = mc.blocks.endswith("wool").first()  # returns None if no block exists

# afterwards you can set the component data directly
waterlogged_block = block.withData({"waterlogged": True})

Checkout withData() and withMergeData() for more examples regarding component data.

property id: str¶

The full namespace:name of the block as string.

Returns:: the string namespace:name of given block (including “minecraft” prefix)
Return type:: str

property type: str¶

Similar to the id but excluding the “minecraft” namespace but including non-vanilla namespaces. This is a valid block id as the “minecraft” namespace is assumed by default if no namespace is provided.

Returns:: the block name of namespace:name of given vanilla block or the id of non-vanilla block
Return type:: str

property name: str¶

The name string of namespace:name excluding the namespace.

Caution

The returned string might not be a valid block id without its namespace if the namespace is something other than “minecraft”! Use type instead, which will remove the “minecraft” prefix but not other namespaces.

Returns:: the string type of namespace:name of given block without the namespace
Return type:: str

property namespace: str¶

The namespace string of namespace:name. This returns “minecraft” for vanilla blocks.

Returns:: the string namespace of namespace:name of given block
Return type:: str

property datastr: str¶

The data/components string of given block in form ‘[component1=value1,component2=value2]’. Looks like '[]' if this block has no component data.

Returns:: the string data/components of namespace:name[component1=value1,...] of given block
Return type:: str

property hasData: bool¶: Check if the string has component data, but does not actually parse the data. For that use getData().

asBlockStateForItem() → Block¶

Return the current Block with its data as a block_state component. This can be used to give players placeable blocks as items with certain component data.

from mcpq import Minecraft
mc = Minecraft()
b = mc.blocks.endswith("_stairs").first().withData({"waterlogged": True})
mc.getPlayer().giveItems(b.asBlockStateForItem())  # give player a waterlogged stair to place

equals(value: object) → bool¶

Check if value equals self, i.e., compare id and component data. Component data will be parsed and compared via equality for this.

Note

Normal equality == will only compare id for checking against strings.

Parameters:: value (object) – the string or Block to compare against
Returns:: whether the supplied Block has the same id and component data
Return type:: bool

getData() → ComponentData¶

Parse and return datastr as ComponentData. Is equivalent to ComponentData.parse(self.datastr).

Returns:: this block’s parsed string component data
Return type:: ComponentData

withId(type_id: str | Block) → Block¶

Return a new Block with the given type_id as its id but with the (copied) ComponentData of this block.

from mcpq import Block
b = Block("acacia_stairs[waterlogged=true]")
sb = Block("oak_sign")
watersign = b.withId("oak_sign")
watersign = b.withId(sb)  # replace the id of b with id of sb
print(watersign)  # in both cases:
# >>> "oak_sign[waterlogged=true]"

Parameters:: type_id (str | Block) – the (block) id that should replace this block’s
Returns:: a new block with this block’s component data and the new id
Return type:: Block

Return a new Block with the id of this block but replace the ComponentData of the form [key1=value1,key2=value2] on this block with the given data. The given data may have the form of a dict, ComponentData, Block or string and will be parsed and/or converted as required. If data is None the component data is deleted instead.

from mcpq import Block, NBT
b = Block("acacia_stairs[facing=east]")
waterstairs = b.withData({"waterlogged": True})  # convert to component data
waterstairs = b.withData("[waterlogged=true]")  # parse string and use component data
wb = Block("other_block[waterlogged=true]")
waterstairs = b.withData(wb)  # id of b + data of wb
waterstairs = b.withData(wb.getData())  # use data of wb
nbt = NBT({"waterlogged": True})
waterstairs = b.withData(nbt.asComponentData())  # convert nbt to component data
print(waterstairs)  # in all 5 cases: ('facing=east' is overwritten)
# >>> "acacia_stairs[waterlogged=true]"

# to delete the component data
print(b.withData())
# >>> "acacia_stairs"

Parameters:: data (dict[str, bool | int | str] | str | ComponentData | Block | None, optional) – component data that should replace this block’s, defaults to None
Returns:: a new block with this block’s id and the new component data
Return type:: Block

withMergeData(data: dict[str, bool | int | str] | str | ComponentData | Block) → Block¶

Return a new Block with the id of this block but merge the given ComponentData of the form [key1=value1,key2=value2] onto the one on this block. The given data may have the form of a dict, ComponentData, Block or string and will be parsed and/or converted as required.

from mcpq import Block, NBT
b = Block("acacia_stairs[facing=east,half=top]")
newstairs = b.withMergeData({"waterlogged": True, "half": "bottom"})  # convert to component data
newstairs = b.withMergeData("[waterlogged=true,half=bottom]")  # parse string and use component data
wb = Block("other_block[waterlogged=true,half=bottom]")
newstairs = b.withMergeData(wb)  # id of b + merge data of wb
newstairs = b.withMergeData(wb.getData())  # merge data of wb
nbt = NBT({"waterlogged": True, "half": "bottom"})
newstairs = b.withMergeData(nbt.asComponentData())  # convert nbt to component data
print(newstairs)  # in all 5 cases:
# >>> 'acacia_stairs[facing="east",half="bottom",waterlogged=true]'

Parameters:: data (dict[str, bool | int | str] | str | ComponentData | Block) – component data that should be merged onto this block’s
Returns:: a new block with this block’s id and data with the new component data merged on top of it
Return type:: Block

Table of Contents

Search