Minecraft Pi Edition API Reference

This guide features a reference sheet for the Minecraft Pi Edition Python API.

Minecraft Pi Edition API

Before making use of this reference guide you should first have Minecraft Pi Edition installed to your Raspberry Pi.

The Minecraft Pi Edition Python API consists of three separate libraries, all designed to interact with the game client in various ways.

  • minecraft.py This is the main library for interacting with the game. The library provides five different classes for interacting with the game client.
    • Class Minecraft This is the main class for interacting with the game and contains four sub-classes.
      • Class camera Used to modify the player’s camera angle and position.
      • Class player Allows us to get and modify the player’s position in the game world.
      • Class entity Gives the ability to get and set the position of entities (players) in the game world.
      • Class events Allows you to retrieve events that have happened within the game.
  • block.py
    • Class Block This class defines a block within the game world and is used to describe a block’s type and subtype. This file also contains a constant for each of the possible blocks.
  • event.py
    • Class BlockEvent With this class, you can check what event happened to a block. This event gives details of what block it happened to, what player caused the event and what the event was.

Minecraft API Class

This section references the core functions of the Minecraft Pi Edition API. These functions are typically used to interact with the Minecraft game world.

.create() function

.create(address = "localhost", port = 4711)

This function creates a connection to a Minecraft Pi Edition client and returns an object that you can use to interact with the client.

There are two different ways you can use this function. The first is not to use any of the parameters.

Without any parameters, the .create() function makes a connection to the localhost client on port 4711.

#Use default address and port
mc = minecraft.Minecraft.create()

Alternatively, you can provide an IP address and a port to connect to. Defining an IP address will allow you to connect to a remote Minecraft Pi Edition client.

#Specify both IP address and port
mc = minecraft.Minecraft.create("192.168.1.1", 4711)

.getBlock() function

.getBlock(x, y, z)

This function retrieves the ID of a block at the specified x, y, and z position. It returns the ID of the block as an integer.

For example, using the following will retrieve the ID of the block at position 0, 0, 0.

#Retrieves the block ID for the block at position 0, 0, 0
blockID = mc.getBlock(0, 0, 0)

.getBlocks() function

.getBlocks(x0, y0, z0, x1, y1, z1)

This is similar to the previous function but instead gets the ID’s of blocks from a cuboid. These ID’s are returned as integers within a Python list.

You can loop through the returned list to see the ID of each of the blocks.

For the following example, we will check the blocks in the area from 1, 1, 1 to 2, 2, 2.

#Retrieves block ID's from 1, 1, 1 to 2, 2, 2
blockIdList = mc.getBlocks(1, 1, 1, 2, 2, 2)
for block in blockIdList:
    print(block)

.getBlockWithData() function

.getBlockWithData(x, y, z)

This is similar to the previous functions, however instead of returning the block ID as an integer it instead returns a Block object.

The block object contains information about the block such as it’s block ID and it’s data ID.

You can use this function just like the previous ones. All you need to do is specifiy the x, y and z position of the block.

#Gets a Block object from the specified position
blockObj = mc.getBlockWithData(0, 0, 0)

.setBlock() function

.setBlock(x, y, z, blockID, [blockSubtype])

Using the .setBlock() function we are able to change the block at the specified position to the specified block ID.

It has an optional fifth parameter for blocks that have subtypes, for example, the wool block.

Below we have an example of using the .setBlock() function. One example uses just the block ID and the other uses the block subtype as well.

#Sets the block at 0, 0, 0 to a stone (ID 1) block
mc.setBlock(0, 0, 0, 1)
#Sets the block at 1, 1, 1 to a red (Subtype 14) wool (ID 35) block
mc.setBlock(0, 0, 0, 35, 14)

.setBlocks() function

.setBlocks(x1, y1, z1, x2, y2, z2, blockID, [blockSubtype])

Using this function you are able to set a cuboid of blocks to a defined ID.

This function will fill in all blocks between the two sets of positions with the defined block.

#Sets blocks between 1, 1, 1, and 2, 2, 2 to stone (ID 1)
mc.setBlocks(1, 1, 1, 2, 2, 2, 1)

.getHeight() function

.getHeight(x, z)

This function will return the y position of the highest non-air block at a specified x and z position.

#find the y position at 0, 0,
y = mc.getHeight(0, 0)

.getPlayerEntityIds() function

.getPlayerEntityIds()

This function returns the entity ID’s of all connected players.

The ID’s are returned as integers stored in a list.

playerEntities = mc.getPlayerEntityIds()

for playerEntities in playerID:
    print(playerID)

.saveCheckpoint() function

mc.saveCheckpoint()

Saves a checkpoint, creating a snapshot of the world as it stands.

You can restore the Minecraft world to this checkpoint at any time.

.restoreCheckpoint() function

mc.restoreCheckpoint()

Restores the Minecraft game world to how it was when the first checkpoint was created.

Before running this command, you must first run the .saveCheckpoint() function.

.postToChat() function

.postToChat(message)

This function allows you to post a message into the game chat.

Below is an example of using the function to post the text “Hello World” into the chat.

mc.postToChat("Hello World")

.setting() function

mc.setting(settings, status)

Using this function, you can change the settings for the current game.

All you need to do is specify the name of the setting then the value you want to assign to it.

#Sets the nametags_visible setting to false
mc.setting("nametags_visible", False)

Minecraft Player API Class

The functions referenced here are for interacting with players within the game world.

.player.getPos() function

.player.getPos()

This function is used to retrieve the position of the player.

The position is returned as a vector but can be unpacked using Python. The values in this vector are stored as floats.

#Gets the position of the player and stores it as a vector 
pos = mc.player.getPos()

#Print the players x position
print(pos.x)

#Gets the position of the player and unpacks the result to the x, y and z variables
x, y, z = mc.player.getPos()

.player.setPos() function

.player.setPos(x, y, z)

This function moves the player to the specified x, y, and z position.

Below is an example of moving the player to position 0, 0 and 0 in the world.

mc.player.setPos(0, 0, 0)

.player.getTilePos() Function

.player.getTilePos()

Gets the position of the “tile” that the player is currently on.

This function returns the position as a vector. The tile position is stored as an integer as it represents the blocks exact position within the game world.

Like the .getPos() function, you can also use Python’s unpack ability to unpack this vector back to the individual x, y, and z values.

#Retrieves the tile position as a vector
tilePos = mc.player.getTilePos()

#retrieves the individual x, y and z positions of the tile
tileX, tileY, tileZ = mc.player.getTilePos()

.player.setTilePos() Function

.player.setTilePos(x, y, z)

This function moves the player to the tile specified at the x, y and z co-ordinates.

Below we have an example of moving the player to the tile at 0, 0, 0.

mc.player.setTilePos(0, 0, 0)

.player.setting() Function

.player.setting(setting, status)

Using this function you are able to change the settings for the player.

Below we have an example of setting the players “AutoJump” option to “True“.

mc.player.setting("autojump", True)

Minecraft Entity API

The Minecraft Entity API allows you to interact with different players on a server. This API should be used in conjunction with the .getPlayerEntityIds() function.

These are similar to the player functions but can be used to specify individual players.

.entity.getPos() Function

.entity.getPos(entityId)

Retrieves the position of the specified entity and returns it as a vector.

Below is an example of retrieving the position of an entity.

#Retrieves the vector position of the specified ID
entityPos = mc.entity.getPos(entityId)

#Retrieves the unpacked positions for the entity
entX, entY, entZ = mc.entity.getPos(entityId)

.entity.setPos() Function

.entity.setPos(entityId, x,  y, z)

Moves the specified player the the specified x, y and z position in the world.

mc.entity.setPos(entityId, 0, 0, 0)

.entity.getTilePos() Function

.entity.getTilePos(entityId)

Retrieves the tile position of the specified user. This position as returned as a vector.

#Gets the tile position of the specified entity as a vector
entityTilePos = mc.entity.getTilePos(entityId)

#Gets the unpacked tile position for the entity
entTileX, entTileY, entTileZ = mc.entity.getTilePos(entityId)

.entity.setTilePos() Function

.entity.setTilePos(entityId, x,  y, z)

Moves the entity to the specified tile at the x, y, and z coordinates.

mc.entity.setTilePos(entityId, 0, 0, 0)

Minecraft Camera API

This part of the Minecraft Pi Edition API let’s you control the camera.

.camera.setNormal() Function

.camera.setNormal(entityId)

This function sets the camera mode for the specified entity back to normal.

mc.camera.setNormal()
mc.camera.setNormal(entityId)

.camera.setFixed() Function

.camera.setFixed()

Sets the camera mode to a fixed view.

mc.camera.setFixed()

.camera.setFollow() Function

.camera.setFollow(entityId)

This command sets the camera to follow a specified entity.

You can use this API function to get the camera to follow a particular player.

mc.camera.setFollow(entityId)

.camera.setPos() Function

.camera.setPos(x, y, z)

Changes the position of the camera to the specified x, y and z position.

Below you can see an example of using this to move the camera to the position, 0, 0, 0.

mc.camera.setPos(0, 0, 0)

Minecraft Block Event API

This API allows you to handle block events within Python.

The BlockEvent Object

This object contains five different variables that tell us about the event.

These objects are returned by the .pollBlockHits() function.

blockEvent = mc.events.pollBlockHits()
  • .type This variable stores the event type.
    blockEventType = blockEvent.type
  • .pos Stores a vector (x, y, z) with the position of where the event occured.
    blockEventPos = blockEvent.pos
    blockX, blockY, blockZ = blockEvent.pos
  • .face The face of the block where the event occured.
    blockEventFace = blockEvent.face
  • .entityId The ID of the entity that caused this event to occur.
    blockEventEntityId = blockEvent.entityId

.events.pollBlockHits() Function

This command returns all the block hit events that have occured since the function was last called.

These events are returned as a “BlockEvent” object. This object gives you various bits of information about the event.

Every time this function is called, all events in the queue are removed.

Below is an example of polling for events then printing out the event. By printing out the event, you can see the information that is returned.

blockHitEvents = mc.events.pollBlockHits()

for blockEvent in blockHitEvents:
    print blockEvent

.events.clearAll() Function

.events.clearAll()

This function clears all existing events from the queue.

Using this function is similar to running the .pollBlockHits() function, however, no data is returned.

mc.events.clearAll()

Minecraft API Block Object

  • .id The ID of the blocks type. You can see the corresponding constants below.
  • .data The subtype of a block. You can see the block subtypes below.

Block Constants

Below is a list of all the Block Constants and their corresponding ID.

Constant NameBlock ID
AIR0
STONE1
GRASS2
DIRT3
COBBLESTONE4
WOOD_PLANKS5
SAPLING6
BEDROCK7
WATER_FLOWING8
WATER8
WATER_STATIONARY9
LAVA_FLOWING10
LAVA10
LAVA_STATIONARY11
SAND12
GRAVEL13
GOLD_ORE14
IRON_ORE15
COAL_ORE16
WOOD17
LEAVES18
GLASS20
LAPIS_LAZULI_ORE21
LAPIS_LAZULI_BLOCK22
SANDSTONE24
BED26
COBWEB30
GRASS_TALL31
WOOL35
FLOWER_YELLOW37
FLOWER_CYAN38
MUSHROOM_BROWN39
MUSHROOM_RED40
GOLD_BLOCK41
IRON_BLOCK42
STONE_SLAB_DOUBLE43
STONE_SLAB44
BRICK_BLOCK45
TNT46
BOOKSHELF47
MOSS_STONE48
OBSIDIAN49
TORCH50
FIRE51
STAIRS_WOOD53
CHEST54
DIAMOND_ORE56
DIAMOND_BLOCK57
CRAFTING_TABLE58
FARMLAND60
FARMLAND_INACTIVE61
FARMLAND_INACTIVE61
FURNACE_ACTIVE62
DOOR_WOOD64
LADDER65
STAIRS_COBBLESTONE67
DOOR_IRON71
REDSTONE_ORE73
SNOW78
ICE79
SNOW_BLOCK80
CACTUS81
CLAY82
SUGAR_CANE83
FENCE85
GLOWSTONE_BLOCK89
BEDROCK_INVISIBLE95
STONE_BRICK98
GLASS_PANE102
MELON103
FENCE_GATE107
GLOWING_OBSIDIAN246
NETHER_REACTOR_CORE247

Block Subtypes

Below is a list of blocks that have special subtypes, use this list to find the ID’s you require.

Wool
0 : White
1 : Orange
2 : Magenta
3 : Light Blue
4 : Yellow
5 : Lime
6 : Pink
7 : Grey
8 : Light Grey
9 : Cyan
10 : Purple
11 : Blue
12 : Brown
13 : Green
14 : Red
15 : Black

Wood
0 : Oak (Up / Down)
1 : Spruce (Up / Down)
2 : Birch (Up / Down)

Sapling
0 : Oak
1 : Spruce
2 : Birch

GRASS_TALL
0 : Shrub
1 : Grass
2 : Fern

TORCH
1 : Pointing East
2 : Pointing West
3 : Pointing South
4 : Pointing North
5 : Facing Up

STONE_BRICK
0 : Stone Brick
1 : Mossy Stone Brick
2 : Cracked Stone Brick
3 : Chisled Stone Brick

STONE_SLAB/STONE_SLAB_DOUBLE
0 : Stone
1 : Sandstone
2 : Wooden
3 : Cobblestone
4 : Brick
5 : Stone Brick

TNT
0 : Inactive
1 : Ready to explode

Leaves
1 : Oak Leaves
2 : Spruce Leaves
3 : Birch Leaves

Sandstone
0 : Sandstone
1 : Chiseled Sandstone
2 : Smooth Sandstone

STAIRS_[WOOD, COBBLESTONE]
0 : Ascending East
1 : Ascending West
2 : Ascending South
3 : Ascending North
4 : Ascending East (Upside Down)
5 : Ascending West (Upside Down)
6 : Ascending South (Upside Down)
7 : Ascending North (Upside Down)

LADDER, CHEST, FURNACE, FENCE_GATE
2 : Facing North
3 : Facing South
4 : Facing West
5 : Facing East

[WATER, LAVA]_STATIONARY
07 : Level of water, 0 is lowest, 7 is highest.

NETHER_REACTOR_CORE
0 : Unused
1 : Active
2 : Stopped / Used Up

Hopefully this resource has helped you understand the Minecraft Pi Edition Python API.