mcpi-scratch

ScratchX extension application to manipulate Minecraft throught the Pi Protocol api

View project on GitHub

MCPI-Scratch

A ScratchX extension application for the Minecraft-Pi Protocol

Introduction

MCPI-Scratch lets you write Scratch scripts to manipulate Minecraft.

More specifically, its an extension application for the ScratchX online editor that allows you to use blocks that represent the Minecraft Pi Protocol API. It actually uses a slightly cut-down version of the API specified by the RaspberryJuice mod which allows it to connect to both:

  • Minecraft Pi Edition
  • CanaryMod server with the RaspberryJuice mod

A more detailed description of how it works is provided in this blog entry

You might also want to have a look at the documentation at ScriptCraft which has a nice The Young Person's Guide to Programming in Minecraft. It has lots of general tips, for example on how to set up a flat world in CanaryMod, before getting into its own javascript specific API.

See also the excellent set of tutorials for programming with the Pi Edition API. Its written for Python but the information can be easily applied to Scratch.

You will also want to keep this reference for block IDs and metadata handy.

To make it easier for Scrachers to get up and going, I've chosen to include the Minecraft Pi Edition API in this distribution. I don't think it violates the Minecraft EULA but it may be that I need to remove it later and you add it yourself.

The API is the one from Minecraft Pi Edition and not the modded API from RaspberryJuice. But it might be worth changing to that one later if it gives extra functionality.

Installation

Download and install this project distribution. The application mcpi-scratch.py is a bridge between ScratchX and your Minecraft server

You need to run this application on the same machine as the browser you use to access ScratchX

Minecraft can either be runnnig on the same machine or on another machine which you can specify as a startup parameter. MCPI-Scratch expects Minecraft to be listening on the default port for the Minecraft Pi Protocol - 4711

MCPI-Scratch takes an optional command-line argument for the host of the minecraft server or minecraft pi edition

$ python ./mcpi-scratch.py -h
usage: mcpi-scratch.py [-h] [-m HOST]

scratch2MinecraftPi is a Scratch2 extension helper app to allow Scratch
programs to manipulate Minecraft through the Pi protocol

optional arguments:
  -h, --help  show this help message and exit
  -m HOST     hostname/IP for the machine running Minecraft. Default is
              localhost

Getting Started

Start the applications in the following order:

  1. Make sure you have Python installed

  2. 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. You can use either:

    • Minecraft Pi Edition or
    • CanaryMod server with the RaspberryJuice mod + plus the Minecraft launcher to start a client to connect to the server

  3. Start MCPI-Scratch The application attempts to connect to localhost by default. Use the -m host cmd-line arg to specify minecraft running on another machine $ python ./mcpi-scratch.py or $ python ./mcpi-scratch.py -m 192.168.1.117 (the IP for your RPi or CanaryMod server)

  4. Open ScratchX with a browser. You can copy this url http://jbaragry.github.io/mcpi-scratch/mcpi-scratch.js to use in ScratchX
    Alternatively you can open MCPI-Scrarch directly in ScratchX
    You can also open the url of one of the .sbx examples in the samples provided on the github page

Scratch Blocks

MCPI-Scratch supports the following Blocks

  • setPlayerPos:
    • set the Player's x,y,z coordinates (in minecraft, the y coordinate is the vertical plane [height])
  • postToChat:
    • post a string to the chat window
  • postPlayerPosToChat:
    • post a Player's x,y,z coords to the chat window. Useful to have on the scratch canvas so that you can easily find where you are
  • setBlock:
    • set a block at the x,y,z coordinates. The blockType (e.g., WOOL) and metadata (e.g., colour) can also be set. The coords can be absolute or relative the player position
  • setBlocks:
    • set a collection of blocks between 2 x,y,z coordinates. BlockType and metadata can also be set.
  • setLine:
    • set a line of blocks between to x,z coordinates at a particular height (y). BlockType and metadata can also be set
  • setCircle:
    • set a circle with center at x,z coordinates and at a particular height (y). BlockType and metadata can also be set

Changelog

See the README file on the project github page