(For more resources related to this topic, see here.)
Getting ready
Before you begin, you will need a running copy of Minecraft: Pi Edition. Start a game in a new or existing world, and wait for the game world to load.
How to do it…
Follow these steps to connect to the running Minecraft game:
-
Open a fresh terminal by double-clicking on the LXTerminal icon on the desktop.
-
Type cd ~/mcpi/api/python/mcpi into the terminal.
-
Type python to begin the Python interpreter.
-
Enter the following Python code:
import minecraft
mc = minecraft.Minecraft.create()
mc.postToChat(“Hello, world!”) -
In the Minecraft window, you should see a message appear!
How it works…
First, we used the cd command, which we have seen previously to move to the location where the Python API is located. The application programming interface (API) consists of code provided by the Minecraft developers that handles some of the more basic functionality you might need. We used the ~ character as a shortcut for your home directory (/home/pi). Typing in cd /home/pi/mcpi/api/python/mcpi would have exactly the same effect, but requires more typing.
We then start the Python interpreter. An interpreter is a program that executes code line by line as it is being typed. This allows us to get instant feedback on the code we are writing. You may like to explore the IDLE interpreter by typing idle into the terminal instead of python. IDLE is more advanced, and is able to color your code based on its meaning (so you can spot errors more easily), and can graphically suggest functions available for use.
Then we started writing real Python code. The first line, import minecraft, gives us access to the necessary parts of the API by loading the minecraft module. There are several Python code files inside the directory we moved to, one of which is called minecraft.py, each containing a different code module. The main module we want access to is called minecraft.
We then create a connection to the game using mc = minecraft.Minecraft.create(). mc is the name we have given to the connection, which allows us to use the same connection in any future code. minecraft. tells Python to look in the minecraft module. Minecraft is the name of a class in the minecraft module that groups together related data and functions. create() is a function of the Minecraft class that creates a connection to the game.
Finally, we use the connection we have created, and its postToChat method to display a message in Minecraft. The way that our code interacts with the game is completely hidden from us to increase fl exibility: we can use almost exactly the same code to interact with any game of Minecraft: Pi Edition, and it is possible to use many different programming languages. If the developers want to change the way the communication works, they can do so, and it won’t affect any of the code we have written.
Behind the scenes, some text describing our command is sent across a network connection to the game, where the command is interpreted and performed. By default, the connection is to the very Raspberry Pi that we are running the code on, but it is also possible to send these commands over the Internet from any computer to any network-connected Raspberry Pi running Minecraft. A description of all of these text-based messages can be found in ~/ mcpi/api/spec: the message sent to the game when we wrote mc.postToChat(“Hello,world!“) was chat.post(“Hello, world!”). This way of doing things allows any programming language to communicate with the running Minecraft game. As well as Python, a Java API is included that is capable of all the same tasks, and the community has created versions of the API in several other languages.
There’s more…
There are many more functions provided in the Python API, some of the main ones are described here. You can explore the available commands using Python’s help function: after importing the minecraft module, help(minecraft) will list the contents of that module, along with any text descriptions provided by the writer of the module. You can also use help to provide information on classes and functions.
It is also possible to create your own API by building on top of the existing functions. For example, if you find yourself wanting to create a lot of spheres, you could write your own function that makes use of those provided, and import your module wherever you need it.
The minecraft module
The following code assumes that you have imported the minecraft module and created a connection to the running Minecraft game using mc = minecraft.Minecraft.create().
Whenever x, y, and z coordinates are used, x and z are both different directions that follow the ground, and y is the height, with 0 at sea level.
|
Code |
Description |
|
mc.getBlock(x,y,z) |
This gets the type of a block at a particular location as a number. These numbers are all provided in the block module. |
|
mc.setBlock(x,y,z, type) |
The sets the block at a particular position to a particular type. There is also a setBlocks function that allows a cuboid to be filled – this will be faster than setting blocks individually. |
|
mc.getHeight(x,z) |
This gets the height of the world at the given location. |
|
mc.getPlayerEntityIds() |
This gets a list of IDs of all connected players. |
|
mc.saveCheckpoint() |
This saves the current state of the world. |
|
mc.restoreCheckpoint() |
This restores the state of the world from the saved checkpoint. |
|
mc.postToChat(message) |
This posts a message to the game chat. |
|
mc.setting(setting, status) |
This changes a game setting (such as “world_immutable” or “nametags_visible”) to True or False. |
|
mc.camera.setPos(x,y,z) |
This moves the game camera to a particular location. Other options are setNormal(player_id), setFixed(), and setFollow(player_id). |
|
mc.player.getPos() |
This gets the position of the host player. |
|
mc.player.setPos(x,y,z) |
This moves the host player. |
|
mc.events.pollBlockHits() |
This gets a list of all blocks that have been hit since the last time the events were requested. Each event describes the position of the block that was hit. |
|
mc.events.clearAll() |
This clears the list of events. At the time of writing, only block hits are recorded, but more event types may be included in the future. |
The block module
Another useful module is the block module: use import block to gain access to its contents. The block module has a list of all available blocks, and the numbers used to represent them. For example, a block of dirt is represented by the number 3. You can use 3 directly in your code if you like, or you can use the helpful name block.DIRT, which will help to make your code more readable.
Some blocks, such as wool, have additional information to describe their color. This data can be provided after the block’s ID in all functions. For example, to create a block of red wool, where 14 is the data value representing “red”:
mc.setBlock(x, y, z, block.WOOL, 14)
Full information on the additional data values can be found online at http://www.minecraftwiki.net/wiki/Data values(Pocket_Edition).
Summary
This article gave us a simple code to interact with the game. It also explained how Python communicates with the game. The other aspects brought forth by the article include overview of other API functions, which can build useful functions on top of existing ones.
Resources for Article:
Further resources on this subject:
- Creating a file server (Samba) [Article]
- Webcam and Video Wizardry [Article]
- Instant Minecraft Designs – Building a Tudor-style house [Article]