A bit over two years ago I wrote a post about hacking minecraft with Python. During my holiday break this year I decided to revisit this, and have a bit more of a go with it. Some things have changed, including the Minecraft Bukkit Server that I used then (CanaryMod) being abandoned, and some new enhanced modules that let you run Minecraft PI Python code on a non-PI machine, with Python 3! So let's dig in.

Connecting Python programs to Minecraft¶

Minecraft Pi Edition¶

Quick recap: The Minecraft Pi Edition game included with the Raspbian OS for Raspberry Pi may be accessed by an Application Programming Interface (API). The API is a collection of well defined methods for a computer Application to do some things in Minecraft, and it was written by Mojang (Minecraft's creators) especially for the Pi Edition of the game, to be an Interface for Java and Python programs.

The MCPI API describes a computer protocol for a client program to connect to a Minecraft game server and then communicate with it through network messages. The core of the protocol is described in the file mcpi_protocol_spec.txt included with the MCPIPY download when you install it per the Raspberry Pi instructions, or the excellent tutorials and guides at Stuff About Code. I've also placed a copy of the spec' on my web site for easy finding.

The Stuff About Code site has lots of helpful information for hacking in Python 2.x and connecting your programs to Minecraft Pi Edition. If you have a Raspberry Pi, then this is the quickest and easiest option to get started. Martin O'Hanlon (the man behind Stuff About Code), together with David Whale, have written a fantastic book Adventures in Minecraft (you can find a link to purchase this on their web site), which introduces programming basics in Python. It is full of fun projects, and also extends MCPIPY with some higher-level primitive shapes (drawing lines, polygons and polyhedra, as well as turtle-graphics).

Minecraft Java Edition¶

If you don't have a Raspberry Pi, or you want to use a more familiar computer, then Martin O'Hanlon also has you covered. He created Raspberry Juice, a Bukkit server-compatible module that implements most of the MCPI API. The method described on Stuff About Code (and which I followed on my blog years ago) installs Raspberry Juice into the CanaryMod Bukkit server and then has you use Minecraft's Multiplayer mode to connect the game to CanaryMod.

Unfortunately those instructions are quite dated now, and CanaryMod itself has been abondoned. There is a newer Bukkit server that also works with Raspberry Juice, called Spigot. I have been able to follow Martin's instructions using Spigot instead of CanaryMod. My results were satisfactory, but I've found something even better.

Raspberry Jam: a new way to connect Python to Minecraft Java¶

A far easier way to start coding on Minecraft Java is to use raspberryjammod, a Minecraft Forge module. Forge is a Minecraft "modding" framework, widely used to expand or enhance the Java edition of the game with new modules such as better rendering, minigames, new creatures and blocks. Chances are good that Minecraft players reading this already know a lot about it.

The creator of raspberryjammod, Alexander Pruss, has documented installing and using it in an Instructable. The Instructable is really good and complete and I've successfully followed the instructions to install it on Macintosh, PC (Windows 10), and Linux (SUSE). I recommend following the instructable. It's almost as easy as installing Raspbian OS and getting going on a Pi.

A really neat thing about Dr. Pruss' work is: it also includes an updated version of the MCPIPY code from Stuff About Code, with additional examples, plus changes to make it compatible with Python 3! You can get it from Arpruss' raspberryjammod releases GitHub page (look for python-scripts.zip). These scripts still work with Python 2 and still target the original MCPI API, so you can use this Python code everywhere, including on the Pi.

Dr. Pruss' blog entries on Minecraft and Python (there is some overlap here) are well worth reading.

PythonTool Mod¶

The PythonTool Mod is another Forge mod, which works together with raspberryjammod to take the hacking experience even further. It improves on the Raspberry Jam base in a few important ways:

In-game script loading/reloading
Execute scripts by Equipping them and then Using them, rather than entering /py somescript commands in the Chat
Allows you to have a folder for your own scripts separate to the MCPIPY library
The website introduces Using Jupyter Notebooks to note-take and explore

There are instructions to install PythonTool Mod also. I have a few notes and gotchas though which I'd like to expand in my next blog post.