Controlling Minecraft from Python¶

Coordinate System¶

Most coordinates are in the form of a three integer vector (x,y,z) which address a specific tile in the game world. (0,0,0) is the spawn point sea level. (X,Z) is the ground plane, and Y is towards the sky. In other words, X is left and right, Z is forward and backward, and Y is up and down.

Minecraft’s odd x-y-z coordinate system

Minecraft Programming Reference¶

These are just a few highlights. A more detailed reference can be found in the full API reference.

World¶

world.getBlock(x, y, z)¶: Look up the type of block at the specified coordinates.

world.setBlock(x, y, z, block_type)¶: Set the block at the specified coordinates to the type block_type.

world.setBlocks(x1, y1, z1, x2, y2, z2, block_type)¶: Create a set of blocks starting at one coordinate point extending to another point with blocks of the type block_type. This can be used to make cubes or rectangles.

world.getHeight(x, z)¶: Look up the height (y coordinate) of the tallest brick at the specified x and y coordinates.

world.postToChat("Message")¶: Send a message over chat.

Player¶

player.getPos()¶: Look up the coordinates that the player is currently positioned at.

player.setPos(x, y, z)¶: Set the player’s position to the specified coordinates.

Blocks¶

As is the case in most things related to programming, the mcpi/block.py source code file is the ultimate authority for which blocks are available for your use. The table below lists those constants and includes a few notes about some of the blocks.

Block Name	Notes
`AIR`
`STONE`
`GRASS`
`DIRT`
`COBBLESTONE`
`WOOD_PLANKS`	Use `block_data` to control what kind of planks.
`SAPLING`
`BEDROCK`
`WATER_FLOWING`
`WATER`	An alias for `WATER_FLOWING`
`WATER_STATIONARY`
`LAVA_FLOWING`
`LAVA`	An alias for `LAVA_FLOWING`
`LAVA_STATIONARY`
`SAND`
`GRAVEL`
`GOLD_ORE`
`IRON_ORE`
`COAL_ORE`
`WOOD`	Use `block_data` to control what kind of wood.
`LEAVES`
`GLASS`
`LAPIS_LAZULI_ORE`
`LAPIS_LAZULI_BLOCK`
`SANDSTONE`
`BED`
`COBWEB`
`GRASS_TALL`
`WOOL`	Use `block_data` to control what color wool.
`FLOWER_YELLOW`
`FLOWER_CYAN`
`MUSHROOM_BROWN`
`MUSHROOM_RED`
`GOLD_BLOCK`
`IRON_BLOCK`
`STONE_SLAB_DOUBLE`
`STONE_SLAB`
`BRICK_BLOCK`
`TNT`
`BOOKSHELF`
`MOSS_STONE`
`OBSIDIAN`
`TORCH`
`FIRE`
`STAIRS_WOOD`
`CHEST`
`DIAMOND_ORE`
`DIAMOND_BLOCK`
`CRAFTING_TABLE`
`FARMLAND`
`FURNACE_INACTIVE`
`FURNACE_ACTIVE`
`DOOR_WOOD`
`LADDER`
`RAIL`
`STAIRS_COBBLESTONE`
`DOOR_IRON`
`REDSTONE_ORE`
`SNOW`
`ICE`
`SNOW_BLOCK`
`CACTUS`
`CLAY`
`SUGAR_CANE`
`FENCE`
`GLOWSTONE_BLOCK`
`BEDROCK_INVISIBLE`
`STONE_BRICK`
`GLASS_PANE`
`MELON`
`FENCE_GATE`
`GLOWING_OBSIDIAN`
`NETHER_REACTOR_CORE`

The underlying engine actually provides all of these block types. If you see one is missing from the MCPI block module, you are free to edit mcpi/block.py to add more blocks using the decimal value listed and following the pattern you find in the existing code.