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 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.
- If the constructor is passed a string beginning with ‘#’ that is 7
characters long, it calls
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