Wednesday 21 May 2014

Minecraft Graphics Turtle

Spiral built using the Minecraft Turtle
I have had this idea of creating a 3d graphics turtle in Minecraft for a little while so one Sunday morning while I was waiting for the boy to finish a swimming lesson this is what I did.

The Minecraft Graphics Turtle allows you to use the Minecraft world as your drawing studio and unlike most graphics turtle's you aren't confined to 2d space, you can go up and down as well as left and right, and when your master piece is finished, you can walk around it!

Note - The Minecraft Turtle is now part of the minecraft-stuff module, see for documentation and install instructions.

The MinecraftTurtle is really easy to install and use, clone it and run the setup program.

If you want to get started quickly through, I would download the complete code from my github, as it contains some examples and all the files you need to have go.

Download Minecraft Turtle Code:
cd ~
git clone

Install the library
cd ~/minecraft-turtle
python install
python3 install

Try the 'squares' example:
Startup Minecraft and load a game.
cd ~/minecraft-turtle/examples

Create your own turtle program:
The turtle is really easy to program, Open IDLE, create a new file and save it.
from mcturtle import minecraftturtle
from mcpi import minecraft
from mcpi import block

#create connection to minecraft
mc = minecraft.Minecraft.create()

#get players position
pos = mc.player.getPos()

#create minecraft turtle at the players position and give it a name
steve = minecraftturtle.MinecraftTurtle(mc, pos)

#tell the turtle to go forward 15 blocks

#tell the turtle to go right 90 degrees

#tell the turtle to go up by 45 degress

tell the turtle to go forward 25 blocks

Run the program and you should see the turtle draw 2 lines, one straight ahead, the other at a 90 degree angle right and a 45 degree angle up.

The turtle supports lots of other commands:
#create the turtle
#  position is optional, without it gets created at 0,0,0
steve = minecraftturtle.MinecraftTurtle(mc, pos)

#rotate right, left by a number of degrees

#pitch up, down by a number of degress

#go forward, backward by a number of blocks

#get the turtles position
turtlePos = steve.position

#set the turtles position

#set the turtles headings (angle)

#put the pen up/down

#get if the pen is down
print steve.isdown()

#change the block the pen writes with

#change the turtles speed (1 - slowest, 10 - fastest, 0 - no animation, it just draws the lines)

#return the turtle to the position it started in

Have a look at the other examples and see what you can create.


  1. Cool stuff.
    By the way, the 'import minecraftturtle' statement is outside the code block.

  2. Awesome! Also, you forgot to share this on G+. I never would have seen it if I hadn't seen it on reddit/r/mcpi.

  3. Hi!
    Awesome stuff you got there! I'm a C# programmer that wants to learn Python with my kid. I'm so glad that I found your blog, packed with cool stuff to get my kids curiosity up. I just got one question. I noticed that you are in Windows with Minecraft 1.6.4 when you run your scripts. Are you going against MineCraftPi or is it possible to run the Python scripts against the PC version of Minecraft?

    Again, great work!

    1. Yes, you need to setup a bukkit server and use a plugin called "raspberryjuice" but its a pretty simple setup. Check out

    2. Ah, great!
      After some tinkering, connecting to the server, (NOT changing the port :) ) I think i got a connection to MC. But nothing happens. The script runs but I can't see anything. No errors ether.
      I'm I missing something?


    3. Never mind, I restarted the server and ran the script again and its working like a charm!
      In one hand this is so simple, but in the other so empowering and awesome. Thanks!

  4. Can anyone point me to a link which documents the raw Raspberry Pi Minecraft "protocol"? It looks like you send ASCII commands to TCP port 4711. I'm wanting to connect FMS Logo to Minecraft using the Canary Mod server with the Raspberry Juice plugin, just like what is described here using the Python language. I suppose I can reverse engineer the protocol from the python source, but I think I'd find it easier if there was a documentation of just the wire protocol. Thanks.

    1. Its described in a text document called mcpi_protocol_spec.txt which is installed with Minecraft: Pi edition. If you download Minecraft: Pi edition, extract the files you will find it in there.

    2. Excellent. Thank you a bunch. For those in a similar situation, you can search for "mcpi_protocol_spec.txt" and find a copy without needing to download the Minecraft: Pi edition tarball.

  5. This was a really great idea!

    Hope you don't mind my tooting my horn: Your minecraft turtle class inspired me to write my own version.I started off wanting it to be simpler so as to use it for some very introductory teaching this summer, but it ended up having more bells and whistles, like line thickness control, yaw/pitch/roll control (crucial for some applications), polygon filling, push/pop (handy for L-systems), and the ability to use an entity, e.g., the player or a horse, as the turtle (OK, using an npc entity requires an extension to the MC API). Documentation and links and screenshots are included in my Instructable for modding desktop Minecraft to have the API:

  6. I have been working through the Adventures in Minecraft book with my son, and this looked cool.
    I have saved to the mcpi folder (on PC) where the, etc. are.
    I get this error when running:
    import minecraftturtle
    ImportError: No module named minecraftturtle

    Does the file need to be compiled, as the others seem to all have .pyc version too.

    1. If you want to use import minecraftturtle, then you need to have it in the same folder that your may .py file is. If you want to kee it in the mcpi folder, then do:
      import mcpi.minecraftturtle as minecraftturtle

  7. oh my goodness that is awesome. i just ran the spiral example!

  8. I was wondering if there is a way to change bricks.


Note: only a member of this blog may post a comment.