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 class which is
used to implement the blocks
attribute on the
World
class.
Note
All items in this module, except the compatibility constants, 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 thename
anddescription
of the block from a database derived from the Minecraft wiki, and classmethods are defined to construct a block definition from anid
or from alternate things like aname
or anRGB 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):
- If the constructor is passed a string beginning with ‘#’ that is 7
characters long, it calls
from_color()
- If the constructor is passed a tuple containing 3 values, it calls
from_color()
- If the constructor is passed a string (not matching the case above)
it calls
from_name()
- 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 isTrue
and an exact match cannot be found, aValueError
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>
- A tuple of
-
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 thename
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 withfrom_name()
.
-
description
¶ Return a description of the block. This string is not guaranteed to be unique and is only intended for human use.
-
COLORS
¶ A class attribute containing a sequence of the colors available for use with
from_color()
.
-
NAMES
¶ A class attribute containing a sequence of the names available for use with
from_name()
.
- If the constructor is passed a string beginning with ‘#’ that is 7
characters long, it calls
9.2. 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 | FURNACE_ACTIVE | MUSHROOM_RED |
BED | FURNACE_INACTIVE | NETHER_REACTOR_CORE |
BEDROCK | GLASS | OBSIDIAN |
BEDROCK_INVISIBLE | GLASS_PANE | REDSTONE_ORE |
BOOKSHELF | GLOWING_OBSIDIAN | SAND |
BRICK_BLOCK | GLOWSTONE_BLOCK | SANDSTONE |
CACTUS | GOLD_BLOCK | SAPLING |
CHEST | GOLD_ORE | SNOW |
CLAY | GRASS | SNOW_BLOCK |
COAL_ORE | GRASS_TALL | STAIRS_COBBLESTONE |
COBBLESTONE | GRAVEL | STAIRS_WOOD |
COBWEB | ICE | STONE |
CRAFTING_TABLE | IRON_BLOCK | STONE_BRICK |
DIAMOND_BLOCK | IRON_ORE | STONE_SLAB |
DIAMOND_ORE | LADDER | STONE_SLAB_DOUBLE |
DIRT | LAPIS_LAZULI_BLOCK | SUGAR_CANE |
DOOR_IRON | LAPIS_LAZULI_ORE | TNT |
DOOR_WOOD | LAVA | TORCH |
FARMLAND | LAVA_FLOWING | WATER |
FENCE | LAVA_STATIONARY | WATER_FLOWING |
FENCE_GATE | LEAVES | WATER_STATIONARY |
FIRE | MELON | WOOD |
FLOWER_CYAN | MOSS_STONE | WOOD_PLANKS |
FLOWER_YELLOW | MUSHROOM_BROWN | WOOL |
Use these compatibility constants by importing the block module explicitly. For example:
>>> from picraft import block
>>> block.AIR
<Block "air" id=0 data=0>
>>> block.TNT
<Block "tnt" id=46 data=0>