Minecraft API

This is a reference of Minecraft: Pi Edition's: Python API Library.

If you want to know more about how to use the API, including tutorials, see my projects and download code, visit my minecraft page.


  • minecraft.py
    • Class Minecraft - main class for connecting and interacting with the game
      • Class camera - changing camera angle and postion
      • Class player - getting and changing the players position and setting
      • Class entity - getting and changing entities position and setting
      • Class events - retreiving events which have occured in the game
  • block.py
    • Class Block - definition of a block, specifically its type
  • event.py
    • Class BlockEvent - definition of a block event, specifically what event, what block and what player
  • vec3.py
    • Class Vec3 - generic class for managing a 3 dimension vector (i.e. x,y,z)
  • connection.py - internal module used by the api
  • util.py - internal module used by the api


"Main class for interacting with the Minecraft world, includes functions for creating a connection, modifying players and blocks and capturing events"

.create(address = "localhost", port = 4711)
"Create connection to Minecraft (address, port) => Minecraft object"

#use default address and port
mc = minecraft.Minecraft.create()
#specify ip address and port
mc = minecraft.Minecraft.create("", 4711)

"Get block (x,y,z) => id:int"

#retrieves the block type for the block at 0,0,0
blockType = mc.getBlock(0,0,0)

"Get a cuboid of blocks (x0,y0,z0,x1,y1,z1) => [id:int]"

Not implemented in the API

"Get block with data (x,y,z) => Block"

#retrieves a block object for the block at 0,0,0
blockObj = mc.getBlockWithData(0,0,0)

"Set block (x,y,z,id,[data])"

#sets a block at an x, y, z co-ordinate to a particular type
#sets a block to a particular type and 'subtype'
mc.setblock(0,0,0,block.WOOD.id, 1)

.setBlocks(x0,y0,z0,x1,y1,z1,blockType, blockData)
"Set a cuboid of blocks (x0,y0,z0,x1,y1,z1,id,[data])"

#sets many blocks at a time, filling the gap between 2 sets of x, y, z co-ordinates
mc.setBlocks(-1, -1, -1, 1, 1, 1, block.STONE.id)

"Get the height of the world (x,z) => int"

#find the y (vertical) of an x, z co-ordinate which represents the 'highest' (non-air) block
y = mc.getHeight(0,0)

"Get the entity ids of the connected players => [id:int]"

#get the entity id's of the players connected to the game
entityIds = mc.getPlayerEntityIds()
for entityId in entityIds:
    print entityId

"Save a checkpoint that can be used for restoring the world"


"Restore the world state to the checkpoint"


"Post a message to the game chat"

#write 'Hello Minecraft World' to the chat window
mc.postToChat("Hello Minecraft World")

.setting(setting, status)
"Set a world setting (setting, status). keys: world_immutable, nametags_visible"

#change world immutable to True
mc.setting("world_immutable", True)
#change nametags_visible setting to False
mc.setting("nametags_visible", False)


"Gets the player's position in the world as a Vec3 of floats (decimal numbers), if the player is in the middle of a block x.5 is returned"

#get players position as floats
playerPos = mc.player.getPos()

"Moves the player to a position in the world by passing co-ordinates ([x,y,z])"

#set the players position as floats

"Gets the position of the 'tile' the player is currently on."

#get the position of the tile the players is on
playerTile = mc.player.getTilePos()

"Move the player to a tile position in the world by passing co-ordinates ([x,y,z])"

#set the position of the tile the player is on

.setting(setting, status)
"Set a player setting (setting, status). keys: autojump"

#change the autojump setting to True
mc.player.setting("autojump", True)


The entity functions are used in conjunction with the .getPlayerEntityIds() function to interact with the entity (or players) in a game.  Entity functions are useful for multiplayer games.  

#get the entity id's of the players connected to the game
entityIds = mc.getPlayerEntityIds()
1stEntityId = entityIds[0]
2ndEntityId = entityIds[1]

"Gets an entities position in the world as a Vec3 of floats (decimal numbers), if the entity is in the middle of a block x.5 is returned"

#get first entity position as floats
entityPos = mc.entity.getPos(entityId)

"Moves the entity to a position in the world by passing co-ordinates ([x,y,z])"

#set the players position as floats

"Gets the position of the 'tile' the entity is currently on."

#get the position of the tile the entity is on
entityTile = mc.entity.getTilePos(entityId)

"Move the entity to a tile position in the world by passing co-ordinates ([x,y,z])"

#set the position of the tile the entity is on


"Set camera mode to normal Minecraft view ([entityId])"

#set camera mode to normal for a specific player

"Set camera mode to fixed view"

#set camera mode to fixed 

"Set camera mode to follow an entity ([entityId])"

#set camera mode to follow for a specific player

"Set camera entity position (x,y,z)"

#set camera position to a specific position of x, y, z


"Block Hits (Only triggered by sword) => [BlockEvent]"

#get block event hits that have occured since the last time the function was run
blockEvents = mc.events.pollBlockHits()
for blockEvent in blockEvents:
    print blockEvent

"Clear all old events"

#clear all events that have happened since the events where last got


"The definition of a Block in Minecraft, used to describe a block type and (if applicable) its data; also contains constants for the blocks type id's, e.g. BLOCK.AIR.id"

#create block of a specific type
blockObj = block.Block(id)
#create a block of a specific type and apply a data value
blockObj = block.Block(id, data)

"The id (or type) of block"

Block id constants:
AIR                 = Block(0)
STONE               = Block(1)
GRASS               = Block(2)
DIRT                = Block(3)
COBBLESTONE         = Block(4)
WOOD_PLANKS         = Block(5)
SAPLING             = Block(6)
BEDROCK             = Block(7)
WATER_FLOWING       = Block(8)
WATER               = WATER_FLOWING
LAVA_FLOWING        = Block(10)
LAVA                = LAVA_FLOWING
LAVA_STATIONARY     = Block(11)
SAND                = Block(12)
GRAVEL              = Block(13)
GOLD_ORE            = Block(14)
IRON_ORE            = Block(15)
COAL_ORE            = Block(16)
WOOD                = Block(17)
LEAVES              = Block(18)
GLASS               = Block(20)
LAPIS_LAZULI_ORE    = Block(21)
SANDSTONE           = Block(24)
BED                 = Block(26)
COBWEB              = Block(30)
GRASS_TALL          = Block(31)
WOOL                = Block(35)
FLOWER_YELLOW       = Block(37)
FLOWER_CYAN         = Block(38)
MUSHROOM_BROWN      = Block(39)
MUSHROOM_RED        = Block(40)
GOLD_BLOCK          = Block(41)
IRON_BLOCK          = Block(42)
STONE_SLAB          = Block(44)
BRICK_BLOCK         = Block(45)
TNT                 = Block(46)
BOOKSHELF           = Block(47)
MOSS_STONE          = Block(48)
OBSIDIAN            = Block(49)
TORCH               = Block(50)
FIRE                = Block(51)
STAIRS_WOOD         = Block(53)
CHEST               = Block(54)
DIAMOND_ORE         = Block(56)
DIAMOND_BLOCK       = Block(57)
CRAFTING_TABLE      = Block(58)
FARMLAND            = Block(60)
FURNACE_ACTIVE      = Block(62)
DOOR_WOOD           = Block(64)
LADDER              = Block(65)
DOOR_IRON           = Block(71)
REDSTONE_ORE        = Block(73)
SNOW                = Block(78)
ICE                 = Block(79)
SNOW_BLOCK          = Block(80)
CACTUS              = Block(81)
CLAY                = Block(82)
SUGAR_CANE          = Block(83)
FENCE               = Block(85)
GLOWSTONE_BLOCK     = Block(89)
STONE_BRICK         = Block(98)
GLASS_PANE          = Block(102)
MELON               = Block(103)
FENCE_GATE          = Block(107)
GLOWING_OBSIDIAN    = Block(246)

"The data (or sub-type) of a block"

Data Values of blocks:
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

0: Oak (up/down)
1: Spruce (up/down)
2: Birch (up/down)
(below not on Pi)
3: Jungle (up/down)
4: Oak (east/west)
5: Spruce (east/west)
6: Birch (east/west)
7: Jungle (east/west)
8: Oak (north/south)
9: Spruce (north/south)
10: Birch (north/south)
11: Jungle (north/south)
12: Oak (only bark)
13: Spruce (only bark)
14: Birch (only bark)
15: Jungle (only bark)

WOOD_PLANKS (Not on Pi):
0: Oak
1: Spruce
2: Birch
3: Jungle

0: Oak
1: Spruce
2: Birch
3: Jungle (Not on Pi)

0: Shrub
1: Grass
2: Fern
3: Grass (color affected by biome) (Not on Pi)

0: Standing on the floor
1: Pointing east
2: Pointing west
3: Pointing south
4: Pointing north

0: Stone brick
1: Mossy stone brick
2: Cracked stone brick
3: Chiseled stone brick

0: Stone
1: Sandstone
2: Wooden
3: Cobblestone
4: Brick
5: Stone Brick
Below - not on Pi
6: Nether Brick
7: Quartz

Not on Pi
0-7: Height of snow, 0 being the lowest, 7 being the highest.

0: Inactive
1: Ready to explode

1: Oak leaves
2: Spruce leaves
3: Birch leaves

0: Sandstone
1: Chiseled sandstone
2: Smooth sandstone

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)

2: Facing north
3: Facing south
4: Facing west
5: Facing east

0-7: Level of the water, 0 being the highest, 7 the lowest

0: Unused
1: Active
2: Stopped / used up


"The definition of a BlockEvent in minecraft, used to describe an event in minecraft affecting blocks; returned by the Minecraft.events.pollBlockHits() method."

blockEvent = mc.events.pollBlockHits()

"Type of block event; there is only 1 event currently implemented BlockEvent.HIT"

blockEventType = blockEvent.type

BlockEvent types:
0: BlockEvent.HIT

"The position of the block where the event occured, i.e. the block which was hit.  .pos returns a Vec3 object of x,y,z co-ordinates"

blockEventPos = BlockEvent.pos

"The face of the block where the event occured"

blockEventFace = BlockEvent.face

"entityId of the player who caused the block event, i.e. the player who hit the block"

blockEventPlayer - BlockEvent.entityId


"The definition of a 3 part vector in Minecraft, i.e. a set of x, y, z co-ordinates; x and z are the horizontal positions, y the vertical"

position = vec3.Vec(0,0,0)

"x position"

xPos = position.x
"y position"

yPos = position.y
"z position"

zPos = position.z


  1. Whenever I need a place to remember the list, I'll go here!

  2. Are these all of the commads that the raspberry pi minecraft has to offer if not then could someone link me to a in depth list of commands?

    1. Im pretty sure this is a complete list. Do you think something is missing?

  3. Hi Martin, love your work. I'm wondering if there is a method to give the direction the player is currently facing. Obviously you can use position deltas to work out where someone may be facing when on the move, but if they are stationary, a Vec3 does not give directional information. Any ideas?

    1. Unfortunately not, there isnt a api call to get the players heading. As you say you can use the players pos to find out the direction they are travelling.

  4. In the .pollBlockHits section you may want to add a colon ':' in that for loop. As a one-day-old python programmer it messed me up for a bit

    1. Ditto in .getPlayerEntityIds() example "for" loop - missing ":"

      (PS - thanks Martin for a great ressource, alongside the book! =o)

  5. Hello, Martin. I'm a Japanese Minecraft user. I'm trying to gather information about Minecraft PI and add it to the website 'Minecraft Japan Wiki'. I have ever translated this page into Japanese for personal needs and want to contribue my translation to 'Minecraft Japan Wiki'. Could I ask you to permit my publishing the translation of this page on 'Minecraft Japan Wiki'? I'm looking forward to your reply.

    1. Hi, I have only just seen this comment. You have my permission to publish a translation of this page. A link back would be nice ;)