Program more Minecraft Pi

Learn how to get started with Minecraft Pi, a brilliant tool for learning to code Python on the Raspberry Pi...

Our house, in the middle of the field

Minecraft is a revolutionary sandbox game in which the protagonist, known only as Steve, is tasked with surviving and thriving in a huge, blocky 3D world considerably bigger than planet Earth. Each one-metre segment of the world is represented by a block. The block could be any one of a number of items and the deeper you dig into the earth the rarer the items might be. It’s your challenge to dig, build and survive against an army of nocturnal monsters by harnessing the items you discover.

Minecraft Pi removes the survival element of the game, leaving you in a kind of Lego construction mode, where you have an infinite supply of many of the game’s items and free reign to build with them. Minecraft Pi is also the only version of Minecraft (which is available on just about every gaming platform in circulation) where the player is actively encouraged to hack the world using a simple application programming interface (API). In this tutorial we’re going to learn the basics…

Our house, in the middle of the field
Our house, in the middle of the field


Step 01 Install Minecraft Pi

We’ve already covered the installation of Minecraft on the Raspberry Pi in a previous tutorial. You can find our full write-up in our previous Minecraft tutorial. If you know what to do with a tar ball and don’t need to follow step-by-step instruction, you just need to download the relevant file and unpack it into your home folder.

Step 02 You must start X

There are a few things you need to bear in mind when coding and playing Minecraft on the Pi. Lots of people seem to get caught out by the fact the game won’t work from the command line. Assuming that you haven’t set your Pi to do so, you must start the desktop environment with startx. Launch the game from the terminal by entering the mcpi folder and typing:


Step 03 Desktop shortcut

Launching the game from the terminal isn’t everyone’s cup of tea. Coupled with the fact you need a separate terminal window open to launch your Minecraft Pi scripts (meaning you need two terminal windows open) it’s worth creating a desktop shortcut to launch the game. Open a terminal and type:

cd ~/Desktop

Now create a new desktop file by typing: nano minecraft.desktop and copy the following into it:

[Desktop Entry]
Name=Minecraft Pi
Comment=Minecraft for the Pi

Press CTRL+X, Y and then press Enter in order to save the file and exit. The icon isn’t in the mcpi folder by default, so you will need to do a Google Image search for the Minecraft icon, call it ‘icon.png’ and drop it into the folder. It needs to be 256 x 256 pixels and you may need to restart your desktop environment before the icon appears.

Step 04 Tabbing out

One thing from our first Minecraft Pi tutorial that’s worth reiterating is the fiddly nature of playing Minecraft Pi and starting scripts at the same time. Minecraft Pi needs to be running before you will be able to start a Python script that interacts with the game. This being the case, you will need to press Tab from Minecraft Pi in order to release the mouse so that you can then interact with the terminal window and load all of your Python scripts.

Step 05 Read the docs!

You might think there is no documentation to help you code with Minecraft Pi, but you’d be wrong. Well, partially anyway. You see, one thing all good software scientists know is that the source code for a program doubles up as a great instruction manual. For example, all the block types and names you can use in the game can be found by browsing through the script found in the /mcpi/api/python/ mcpi folder. Even better, you are able to find all of the functions you can carry out in the game simply by looking in ‘’ – they’re even well commented so you know that setPos allows you to ‘set entity position’.

Step 06 A warning about scripts

What do you think you’re going to call your very first Minecraft Pi script? There’s an immediate temptation to call it ‘’ isn’t there? Sadly, doing this can render the scripting aspect of Minecraft on the Raspberry Pi completely broken because you’ve potentially just overwritten the most important source code file in the game. Take a look in the /mcpi/api/python/mcpi folder – each of
these file names is out of bounds!

Step 07 Copy the API folder

The best way to keep the original API files of Minecraft Pi safe is to create a copy of the API folder that can be used separately. Do this by creating a new folder in your home folder and entering it (eg mkdir mc_projects && cd mc_ projects) and then typing the following:

cp -r ~/mcpi/api/python/* .

The space followed by the full stop is required at the end of the command.

Step 08 Your first script

Next we’ll create a quick test script and make sure that we can successfully use the Python Minecraft API from its new location. Using your favourite text editor, type the following and save it as ‘’:

from mcpi.minecraft import Minecraft
from mcpi import block

mc = Minecraft.create()
mc.postToChat(“Minecraft API Connected”)

If Minecraft Pi isn’t running, start it now. When you’re in the game, press Tab to release the mouse, open a terminal window and navigate to your Minecraft project folder.

Once inside, type python and hit return – you will see the message ‘Minecraft API Connected’ appear as text chat within Minecraft Pi. We recommend that you start all of your Minecraft Pi scripts with this boilerplate code.

Step 09 It didn't work?!

If at this point you’re getting an error from Python, look back over your boilerplate code to ensure that everything’s correct – nine times out of ten, it’s because of a typo. If you’re getting an import error you may have had an issue copying the API folder to the new location. Retrace your steps from the beginning and try again.

Step 10 The fun starts here...

Now that we’ve successfully tested our boilerplate code we can start having real fun with the Minecraft Pi API and Python. There are a wide range of options to take advantage of, such as getting and setting blocks, finding and setting the player’s position, changing and setting the camera and so on. The most commonly used API features, though, are the ones that revolve around manipulating the player’s position and creating new blocks at set positions in the game world.

Step 11 The co-ordinates system

It’s impossible to do anything in Minecraft Pi unless you’re familiar with reading and interpreting the games co- ordinate system. It’s a fairly unusual system too, which switches the Y and Z co-ordinates in 3D space – in Minecraft Pi ‘X’ is sideways movement, ‘Z’ is forward movement and ‘Y’ is vertical movement. You can always find your current co- ordinates by glancing in the top-left corner of the screen, where they’re displayed. It’s worth taking a few minutes just to get familiar with the co-ordinates and how they change when you move around the game-world.

Step 12 Origin point

When you load up a new Minecraft game for the first time, you’ll start at the exact centre of the map, meaning your co-ordinates will be 0, 0, 0. Why is this useful? Because it makes building blocks and collections of blocks much easier for the beginner. At the origin point you don’t need to work out where your surrounding blocks are – they’re simply plus or minus 0.

Step 13 getPos

Let’s start out with one of the most simple operations with the API – finding your location. Knowing exactly where the player is in the game word is a surprisingly powerful and useful ability in Minecraft Pi. You can use it to help you do any number of things, including setting blocks near (or under) the player and triggering events (like finding specific locations). In the below example we’ll find the player location and periodically set it to the variable my_pos and prove that it works by printing it to the chat window.

from mcpi.minecraft import Minecraft
from mcpi import block
import time

mc = Minecraft.create()
mc.postToChat(“Minecraft API Connected”)
while True:
   my_pos = mc.player.getPos()
   mc.postToChat(“My position is:” + str(my_pos))

Step 14 setBlock

The next most common action is setting a block to a certain type. You can find the full list of available blocks in the mcpi folder in a script called ‘’. We can append to our script in Step 13 by dropping a particular block type in our wake as we walk around the game world. After the ‘mc.postToChat’ line in our previous script add: mc.setBlock((my_pos), block. STONE) so the while loop section of the script now looks like this:

mc.postToChat(“Stone path mode!”)
while True:
   my_pos = mc.player.getPos()
   mc.setBlock((my_pos), block.STONE)

Now, when you activate this script when playing the game, you should notice that your character will drop a block of stone every second at your current location. You should also consider making use of the setBlocks function to set a number of blocks simultaneously using the start co-ordinates and the end co-ordinates – this can help you on your way to creating much bigger structures.

Step 15 Teleport Steve

So far we’ve read the location of the player and used it in the game, let’s finish off by manipulating the player’s location using the setPOS method. In the following script we’re going to draw the player back to the origin point, assuming they’ve wandered off and got lost:

from mcpi.minecraft import Minecraft
from mcpi import block
import time

mc = Minecraft.create()
mc.postToChat(“Minecraft API Connected”)

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

If you wanted to drop the player from a great height instead, you would change the Y co-ordinate to a large positive number. For example:

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