9. API - The Block class

The block module defines the Block class, which is used to represent the type of a block and any associated data it may have, and the Blocks class which is used to implement the blocks attribute on the World class.

Note

All items in this module are available from the picraft namespace without having to import picraft.block directly.

The following items are defined in the module:

9.1. Block

class picraft.block.Block(id, data)[source]

Represents a block within the Minecraft world.

Blocks within the Minecraft world are represented by two values: an id which defines the type of the block (air, stone, grass, wool, etc.) and an optional data value (defaults to 0) which means different things for different block types (e.g. for wool it defines the color of the wool).

Blocks are represented by this library as a namedtuple() of the id and the data. Calculated properties are provided to look up the name and description of the block from a database derived from the Minecraft wiki, and classmethods are defined to construct a block definition from an id or from alternate things like a name or an RGB color:

>>> Block.from_id(0, 0)
<Block "air" id=0 data=0>
>>> Block.from_id(2, 0)
<Block "grass" id=2 data=0>
>>> Block.from_name('stone')
<Block "stone" id=1 data=0>
>>> Block.from_color('#ffffff')
<Block "wool" id=35 data=0>

The default constructor attempts to guess which classmethod to call based on the following rules (in the order given):

  1. If the constructor is passed a string beginning with ‘#’ that is 7 characters long, it calls from_color()
  2. If the constructor is passed a tuple containing 3 values, it calls from_color()
  3. If the constructor is passed a string (not matching the case above) it calls from_name()
  4. Otherwise the constructor calls from_id() with all given parameters

This means that the examples above can be more easily written:

>>> Block(0, 0)
<Block "air" id=0 data=0>
>>> Block(2, 0)
<Block "grass" id=2 data=0>
>>> Block('stone')
<Block "stone" id=1 data=0>
>>> Block('#ffffff')
<Block "wool" id=35 data=0>

Aliases are provided for compatibility with the official reference implementation (AIR, GRASS, STONE, etc):

>>> import picraft.block
>>> picraft.block.WATER
<Block "flowing_water" id=8 data=0>
classmethod from_color(color, exact=False)[source]

Construct a Block instance from a color which can be represented as:

  • A tuple of (red, green, blue) integer byte values between 0 and 255
  • A tuple of (red, green, blue) float values between 0.0 and 1.0
  • A string in the format ‘#rrggbb’ where rr, gg, and bb are hexadecimal representations of byte values.

If exact is False (the default), and an exact match for the requested color cannot be found, the nearest color (determined simply by Euclidian distance) is returned. If exact is True and an exact match cannot be found, a ValueError will be raised:

>>> from picraft import *
>>> Block.from_color('#ffffff')
<Block "wool" id=35 data=0>
>>> Block.from_color('#ffffff', exact=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "picraft/block.py", line 351, in from_color
    if exact:
ValueError: no blocks match color #ffffff
>>> Block.from_color((1, 0, 0))
<Block "wool" id=35 data=14>

Note that calling the default constructor with any of the formats accepted by this method is equivalent to calling this method:

>>> Block('#ffffff')
<Block "wool" id=35 data=0>
classmethod from_id(id, data=0)[source]

Construct a Block instance from an id integer. This may be used to construct blocks in the classic manner; by specifying a number representing the block’s type, and optionally a data value. For example:

>>> from picraft import *
>>> Block.from_id(1)
<Block "stone" id=1 data=0>
>>> Block.from_id(2, 0)
<Block "grass" id=2 data=0>

The optional data parameter defaults to 0. Note that calling the default constructor with an integer parameter is equivalent to calling this method:

>>> Block(1)
<Block "stone" id=1" data=0>
classmethod from_name(name, data=0)[source]

Construct a Block instance from a name, as returned by the name property. This may be used to construct blocks in a more “friendly” way within code. For example:

>>> from picraft import *
>>> Block.from_name('stone')
<Block "stone" id=1 data=0>
>>> Block.from_name('wool', data=2)
<Block "wool" id=35 data=2>

The optional data parameter can be used to specify the data component of the new Block instance; it defaults to 0. Note that calling the default constructor with a string that doesn’t start with “#” is equivalent to calling this method:

>>> Block('stone')
<Block "stone" id=1 data=0>
id

The “id” or type of the block. Each block type in Minecraft has a unique value. For example, air blocks have the id 0, stone, has id 1, and so forth. Generally it is clearer in code to refer to a block’s name but it may be quicker to use the id.

data

Certain types of blocks have variants which are dictated by the data value associated with them. For example, the color of a wool block is determined by the data attribute (e.g. white is 0, red is 14, and so on).

pi

Returns a bool indicating whether the block is present in the Pi Edition of Minecraft.

pocket

Returns a bool indicating whether the block is present in the Pocket Edition of Minecraft.

name

Return the name of the block. This is a unique identifier string which can be used to construct a Block instance with from_name().

description

Return a description of the block. This string is not guaranteed to be unique and is only intended for human use.

9.2. BLOCK_COLORS

picraft.block.BLOCK_COLORS

A set of the available colors that can be used with Block.from_color(). Each color is represented as (red, green, blue) tuple where each component is an integer between 0 and 255.

9.3. Compatibility

Finally, the module also contains compatibility values equivalent to those in the mcpi.block module of the reference implementation. Each value represents the type of a block with no associated data:

  • AIR
  • BED
  • BEDROCK
  • BEDROCK_INVISIBLE
  • BOOKSHELF
  • BRICK_BLOCK
  • CACTUS
  • CHEST
  • CLAY
  • COAL_ORE
  • COBBLESTONE
  • COBWEB
  • CRAFTING_TABLE
  • DIAMOND_BLOCK
  • DIAMOND_ORE
  • DIRT
  • DOOR_IRON
  • DOOR_WOOD
  • FARMLAND
  • FENCE
  • FENCE_GATE
  • FIRE
  • FLOWER_CYAN
  • FLOWER_YELLOW
  • FURNACE_ACTIVE
  • FURNACE_INACTIVE
  • GLASS
  • GLASS_PANE
  • GLOWING_OBSIDIAN
  • GLOWSTONE_BLOCK
  • GOLD_BLOCK
  • GOLD_ORE
  • GRASS
  • GRASS_TALL
  • GRAVEL
  • ICE
  • IRON_BLOCK
  • IRON_ORE
  • LADDER
  • LAPIS_LAZULI_BLOCK
  • LAPIS_LAZULI_ORE
  • LAVA
  • LAVA_FLOWING
  • LAVA_STATIONARY
  • LEAVES
  • MELON
  • MOSS_STONE
  • MUSHROOM_BROWN
  • MUSHROOM_RED
  • NETHER_REACTOR_CORE
  • OBSIDIAN
  • REDSTONE_ORE
  • SAND
  • SANDSTONE
  • SAPLING
  • SNOW
  • SNOW_BLOCK
  • STAIRS_COBBLESTONE
  • STAIRS_WOOD
  • STONE
  • STONE_BRICK
  • STONE_SLAB
  • STONE_SLAB_DOUBLE
  • SUGAR_CANE
  • TNT
  • TORCH
  • WATER
  • WATER_FLOWING
  • WATER_STATIONARY
  • WOOD
  • WOOD_PLANKS
  • WOOL