Pages

Tuesday, 9 April 2013

Minecraft: Pi Edition - API Tutorial

This tutorial started off as an article I wrote on Minecraft: Pi Edition for the Issue 11 of The Mag Pi, a magazine written by Raspberry Pi enthusiasts, and builds on my first post Raspberry Pi - Minecraft - API Basics, which describes the basics of how to use the API. I highly recommend you give The Mag Pi a go, its always full of interesting and relevant articles.

Minecraft is a world of cubes or blocks, all with a relative size of 1m x 1m x 1m, and every block has a position in the world of x, y, z; x and z being the horizontal positions and y being the vertical.

The API works by changing the ‘server’, which runs underneath the game, allowing you to interact with these blocks and the player, such as:

Get the player’s position

Change (or set) the player’s position

Get the type of block

Change a block

Change the camera angle

Post messages to the player

Libraries

You can interact with the server directly by sending a message to it, but the nice people at Mojang also provide libraries for python and java which simplify and standardise using the API.

The libraries are installed along with the game in the /opt/minecraft-pi/api/java and api/python directories.

The following example is written in Python and uses Mojang’s python api library.

API Example

Create Directory

We need to create a directory to put our program into.

mkdir ~/minecraft-magpi

Create program

Open the Python 2 editor Idle (or your favourite editor) and create a program file called minecraft-magpi.py in the ~/minecraft-magpi directory

We are going to need 3 modules, the minecraft.py and block.py modules from the minecraft directory containing the library we just copied and the standard time module so we can introduce delays into our program.

import mcpi.minecraft as minecraft

import mcpi.block as block

import time

Next, we need to use the Minecraft class in the python library to create a connection to the game’s server, this object will also be how we interact with the game and will provide access to all the functions. When your program runs this statement, Minecraft will have to be running and you will need to be in a game, otherwise you will get errors.

mc = minecraft.Minecraft.create()

Using our minecraft object, mc, we can then interact with the game and send the player a message. We will also put a delay in using the time.sleep() function otherwise the whole program will run too fast for us to see what’s going on.

mc.postToChat("Hello Minecraft World")

time.sleep(5)

Using the program built so far, you can test to make sure everything is working. Load up minecraft and create a (or enter an existing) world then if you’re using Idle pick 'Run, Run Module' from the menu. If all has been setup correctly you will see the “Hello Minecraft World” message in the game.

Interacting with the player is done through the player class of the mc object allowing us to find the position and change the position of the player. The next block of code finds the players position using the getPos() command, which returns an object of x,y and z coordinates, the setPos() command is then used to move the player 50 blocks up, by adding 50 to the player’s y coordinate. We then add a delay, so there is enough time for your player to fall down to the ground!

playerPos = mc.player.getPos()

mc.player.setPos(playerPos.x, playerPos.y + 50, playerPos.z)

mc.postToChat("Dont look down")

time.sleep(5)

You can use the position of the player as a starting point for interacting blocks, this way you can find out what block the player is standing on or place blocks around the player, there is however a challenge, the x, y and z coordinates returned by the getPos() function are decimals (aka floats), as your player can be in the middle of a block, but to interact with blocks we need to use whole numbers (aka integers), so we need to use the function getTilePos(), which returns the block (or tile) he’s standing on.

The code below gets the players tile position, it then calls the minecraft API’s getBlock() function to find out the type of block the player is standing on (by minusing 1 from the y co-ordinate) before using setBlock() to create blocks of the same type the player is standing on around him. So if your player is standing on DIRT, he will end up with DIRT surrounding him, however if he is standing on STONE, STONE will appear.

We have now trapped our player within 4 blocks (providing he doesn’t break out!), in order to set him free we need to remove a block. Removing blocks is done using setBlock(), but rather than making the block solid like WOOD or STONE we set it to AIR.

A full list of all the available blocks can be found in either the minecraft api specification or in the block.py module in the python api library ~/mcpi/api/python/mcpi/block.py.

The API also allows you to set many blocks at a time, allowing you to create cuboids very quickly using the setBlocks() command. It works by specifying 2 sets of x,y,z coordinates which it then fills the gap between the 2 coordinates with a certain block you pass as the final parameter. The code below will create a diamond floor underneath our player 50 blocks (across) x 1 block (up) x 50 blocks (along), with our player in the middle (i.e. 25 behind and to the left, 25 in front and to the right).

setBlocks(x1, y1, z1, x2, y2, z2, blockType, blockData) - set lots of blocks all at the same time by providing 2 sets of co-ordinates (x, y, z) and fill the gap between with a blockType

player.getPos() - get the precise position of a player

player.setPos(x, y, z) - set (change) the players position

player.getTilePos() - get the position of the block where the player current is

There are a few other functions available in the api which should be explored but using only the small number discussed in this article, its possible, with some imagination and a small amount of programming knowledge to create some quite fantastic constructions, tools and utilities.

I love minecraft, its a tremendously creative game and with the Pi edition’s API it opens up new level of creativity and will hopefully encourage more people to try their hand at programming.

WHAT IS mkdir ~/minecraft-magpi AND WHERE CAN I FIND IT??? I CHECKED THROUGH MY COMPUTER, PORPERTIES OF EVERUTHING... AND STILL COULDN'T FIND IT... WHEN YOU SAY; We need to create a directory to put our program and api library into mkdir ~/minecraft-magpi. I GET TOTALLY COFUSED BECAUSE I DON'T KNOW WHERE ALL THIS STUFF IS... :/

AS I SAID BEFORE, I AM WORKING ON A PROJECT THAT WILL ME MASSIVE!!! SO PLEASE HELP AND REPLY FAST!

I'm of the C64 and Amiga generation (wonderful wonderful times for all of us fortunate enough), and now have the absolute privilege to meet people like yourself doing what we did for fun way back in the day.. It swells me with pride to see what you are doing, and now I can share the basics with my 13 yo son in his favourite game .. A truly magical time for us old guys to pass on... It is a privilege to meet you Martin, and continued good fortune to you for establishing this wonderful project

If its setup correctly you should have a folder called minecraft in the same folder as your minecraft-magpi.py program which has got all the api py files including minecraft.py, block.py, connection.py, vec3.py, etc

Sorry its difficult to offer any advice other than start at the top and try again. You should have copied the minecraft python api library to the /home/pi/minecraft-magpi/minecraft directory when you did this step:

Thanks so much! Also, did you know that the current version of NOOBS (raspberrypi.org/downloads) has Minecraft Pi Edition pre installed? I didn't like it that way, because I Like going inside and changing the names of worlds and things like that. :) I went ahead and uninstalled the pre-installed package, then did it the way your tutorial shows, then I played around until I got a nice grass block icon for it on the desktop. Just wondering, if I follow your tutorial for making a Minecraft server on my Raspberrry Pi, does it run a PC Minecraft server, or a Pi Edition one? Keep up the good work!

Hi, at the Raspberry Jam at PyConUK Coventry, Sept 2014, you handed out a neat four-page (4xA5) version of this article, which would be ideal for schools. Is that available as a freely distributable PDF, please, and if so from where? Looking forward to your book.

hi I am new to the raspberry pi and I am using the IDLE to code. I have got an error coming up on the screen when I run it saying. in import minecraft.Minecraft ImportError: No module named. when you reply could you break it down so that I could understand the code a bit better. and what does it mean by module.

The usual problem if you get the "no module named connection" error is because the code is being run in python 3 not python 2. This might not be your issue because you seem pretty clear that you are using IDLE (and not IDLE 3), but I would double check that the python shell shows you are running Python 2.x.x.

If you submit a post in the forum http://www.stuffaboutcode.com/p/adventures-in-minecraft-forum.html along with your code I will do my best to help you.

You might also find the videos on the companion website, they take you through adventure 1 step by step.