MCPI-Scratch: A Scratch Extension application to program Minecraft

The last blog post - Scratch, Minecraft and Raspberry Pi: how they fit together - explained different alternatives for programming Minecraft using Scratch. Unfortunately the easy alternatives are currently limited running everything on a Raspberry Pi using an older version of Scratch.

So I've been messing around with the Extension capabilities in Scratch 2 and have a helper application that will allow you to manipulate Minecraft using a standalone Scratch 2 editor.

First a quick recap:

Scratch2 has a mechanism for interacting with external programs - the Scratch Extension Protocol.  Scratch speaks HTTP to a helper app running on the same machine which in turn can then interact with any other program. All the details are in that earlier blog post.

I've chosen to write the helper app in python which interacts with the Minecraft Pi Protocol. That gives flexibility to connect to either a local CraftBukkit server with the RaspberryJuice mod or to Minecraft Pi Edition. We have both setups and its been tested on both of them.

Installation

The code is available over on github and the README has the most up to date details about how to install and get started but I'll do a quick summary here also.

If you are comfortable with git then you know how to clone the repo. If not, then the easiest thing is to download the project as a zip file.

Download and install Scratch 2 offline editor.

• Scratch and the helper app must be running on the same machine

Choose which Minecraft setup you wish to use. Either:

• Minecraft Pi Edition or
• CraftBukkit server with the RaspberryJuice mod

Getting Started

You will need to start the applications in the correct order.

1. Start Minecraft

• This must be running before you start MCPI-Scratch because the application attempts to create a connection on startup and will fail if Minecraft is not running.
• If you're using the Minecraft Pi Edition then you are done
• If you are running the CraftBukkit server with the RaspberryJuice mod then you will need to use the Minecraft launcher to also start a client to connect to the server
• The helper app needs a player in the world in order to orient itself and send position information back to Scratch
• A useful tip is to use the t cmd to open the chat console in Minecraft and get control of the mouse so you can get to another application.

2. Start MCPI-Scratch. 

• The application attempts to connect to localhost by default.
• $ python ./mcpi-scratch.py
• Use the -m host cmd-line arg to specify minecraft running on another machine
• For instance, if you are connecting to Minecraft running on a Rasperry Pi (change the IP in the example for the IP address of your RPi)
• $ python ./mcpi-scratch.py -m 192.168.1.117

3. Start Scratch. 

• When the editor loads, shift-click the File menu and select Import experimental HTTP extension and select the file mcpi-scratch.s2e in the MCPI-Scratch install directory. This file specifies the new blocks to use in Scratch and the messages they send/receive with the MCPI-Scratch app.
• You should now be able to select the More Blocks section in Scratch and see the Scratch Blocks that can be used in scripts

You should now be ready to write scripts to interact with Minecraft.

Blocks

In the initial release I've only implemented blocks for the following commands

• postToChat
• getPlayerPos
• setPlayerPos
• setBlock: this includes a flag to set the block using absolute coordinates or relative to the player position
• setBlocks

This is enough to get started. I'll add more blocks to represent the Minecraft Pi Protocol API if people are interested.

There is a good API reference at the StuffAboutCode blog and you can easily adapt the python examples from that blog to Scratch programs

Examples

The installation as a couple of sample scripts

postToChat

The postToChat.sb2 script is a good way to test your set up.

Simply open that file from the scratchExamples directory, click on the script in the Scratch editor, and it should print a hello message in the minecraft chat console.

If this is working then you're ready to try the other blocks.

simpleHouse

The simpleHouse.sb2 script creates a very simple square house using setBlocks block.

It also has some other statements to both clean up and test the other blocks.

rainbow

An adaptation of the rainbow example that is popular in python api tutorials for minecraft

(it took a painfully long time to figure out that the sine function in python and Scratch operate on radians and degrees respectively - fun with debugging...)

That's it. Give it a whirl.