Friday, 15 February 2013

Raspberry Pi - Minecraft - Analogue Clock

I saw a couple of posts on the raspberry pi forum by a guy called SleepyOz who had created both digital and analogue clocks in Minecraft, the digital clock looks particularly good and this gave me the inspiration to create my own analogue clock.

I wanted mine to be massive, big enough so you could walk on the arms as they went round and I was also keen that it use the Mojang supplied api, so I could create some re-usable functions which would no doubt be useful in the future such as:
  • DrawCircle
  • DrawLine
  • FindPointOnCircle
The code is pretty simple, its draws a great big circle, then using trigonometry it finds where a hand (or line) needs to be drawn, by calculating what angle a clock hand would point too and finding that point on the circle before drawing a line from the centre of the clock to that point.

The time is then updated by clearing the previous hand by drawing the previous line again but setting the blocks to air, and then recreating the new hand.

If you want know more about the minecraft api and a rather gentler introduction, check out this post, Raspberry Pi - Minecraft API - the basics.

Download and run
You can download the code direct from git-hub, so run minecraft, open/create a world and follow the instructions:

sudo apt-get install git-core
cd ~
git clone
cd minecraft-clock

If you want to have a go yourself, try the following:

Create a directory for the program

mkdir ~/minecraft-clock

Copy the python api class library from minecraft to the programs directory

cp -r ~/mcpi/api/python/mcpi ~/minecraft-clock/minecraft

Create python program

nano ~/minecraft-bridge/

or open Idle and save to the minecraft-clock directory

Be careful cutting and pasting the code from a web browser and you can end up with odd characters in the program which will end in syntax errors.
#Raspberry Pi, Minecraft Analogue Clock

#import the module from the minecraft directory
import minecraft.minecraft as minecraft
#import minecraft block module
import minecraft.block as block
#import time, so delays can be used
import time
#import datetime, to get the time!
import datetime
#import math so we can use cos and sin
import math

#mid point circle algorithm
def drawCircle(mc, x0, y0, z, radius, blockType):
    f = 1 - radius
    ddf_x = 1
    ddf_y = -2 * radius
    x = 0
    y = radius
    mc.setBlock(x0, y0 + radius, z, blockType)
    mc.setBlock(x0, y0 - radius, z, blockType)
    mc.setBlock(x0 + radius, y0, z, blockType)
    mc.setBlock(x0 - radius, y0, z, blockType)

    while x < y:
        if f >= 0:
            y -= 1
            ddf_y += 2
            f += ddf_y
        x += 1
        ddf_x += 2
        f += ddf_x   
        mc.setBlock(x0 + x, y0 + y, z, blockType)
        mc.setBlock(x0 - x, y0 + y, z, blockType)
        mc.setBlock(x0 + x, y0 - y, z, blockType)
        mc.setBlock(x0 - x, y0 - y, z, blockType)
        mc.setBlock(x0 + y, y0 + x, z, blockType)
        mc.setBlock(x0 - y, y0 + x, z, blockType)
        mc.setBlock(x0 + y, y0 - x, z, blockType)
        mc.setBlock(x0 - y, y0 - x, z, blockType)

#Brensenham line algorithm
def drawLine(mc, x, y, z, x2, y2, blockType):
    steep = 0
    coords = []
    dx = abs(x2 - x)
    if (x2 - x) > 0: sx = 1
    else: sx = -1
    dy = abs(y2 - y)
    if (y2 - y) > 0: sy = 1
    else: sy = -1
    if dy > dx:
        steep = 1 
        x,y = y,x
        dx,dy = dy,dx
        sx,sy = sy,sx
    d = (2 * dy) - dx
    for i in range(0,dx):
        if steep: mc.setBlock(y, x, z, blockType)
        else: mc.setBlock(x, y, z, blockType)
        while d >= 0:
            y = y + sy
            d = d - (2 * dx)
        x = x + sx
        d = d + (2 * dy)
    mc.setBlock(x2, y2, z, blockType)

#find point on circle
def findPointOnCircle(cx, cy, radius, angle):
    x = cx + math.sin(math.radians(angle)) * radius
    y = cy + math.cos(math.radians(angle)) * radius
    return((int(x + 0.5),int(y + 0.5)))

def getAngleForHand(positionOnClock):
    angle = 360 * (positionOnClock / 60.0)
    return angle

def drawHourHand(mc, clockCentre, hours, minutes, blockType):
    if (hours > 11): hours = hours - 12
    angle = getAngleForHand(int((hours * 5) + (minutes * (5.0/60.0))))
    hourHandEnd = findPointOnCircle(clockCentre.x, clockCentre.y, 10.0, angle)
    drawLine(mc, clockCentre.x, clockCentre.y, clockCentre.z - 1, hourHandEnd[0], hourHandEnd[1], blockType)

def drawMinuteHand(mc, clockCentre, minutes, blockType):
    angle = getAngleForHand(minutes)
    minuteHandEnd = findPointOnCircle(clockCentre.x, clockCentre.y, 18.0, angle)
    drawLine(mc, clockCentre.x, clockCentre.y, clockCentre.z, minuteHandEnd[0], minuteHandEnd[1], blockType)

def drawSecondHand(mc, clockCentre, seconds, blockType):
    angle = getAngleForHand(seconds)
    secondHandEnd = findPointOnCircle(clockCentre.x, clockCentre.y, 20.0, angle)
    drawLine(mc, clockCentre.x, clockCentre.y, clockCentre.z + 1, secondHandEnd[0], secondHandEnd[1], blockType)

#function to draw the clock
def drawClock(mc, clockCentre, radius, time):
    blockType = block.DIAMOND_BLOCK
    #draw the circle
    drawCircle(mc, clockCentre.x, clockCentre.y, clockCentre.z, radius, blockType)

    #draw hour hand
    drawHourHand(mc, clockCentre, time.hour, time.minute, block.DIRT)
    #draw minute hand
    drawMinuteHand(mc, clockCentre, time.minute, block.STONE)

    #draw second hand
    drawSecondHand(mc, clockCentre, time.second, block.WOOD_PLANKS)

#function to update the time on the clock
def updateTime(mc, clockCentre, lastTime, time):
    #draw hour and minute hand
    if (lastTime.minute != time.minute):
        #clear hour hand
        drawHourHand(mc, clockCentre, lastTime.hour, lastTime.minute, block.AIR)
        #new hour hand
        drawHourHand(mc, clockCentre, time.hour, time.minute, block.DIRT)
        #clear hand
        drawMinuteHand(mc, clockCentre, lastTime.minute, block.AIR)
        #new hand
        drawMinuteHand(mc, clockCentre, time.minute, block.STONE)

    #draw second hand
    if (lastTime.second != time.second):
        #clear hand
        drawSecondHand(mc, clockCentre, lastTime.second, block.AIR)
        #new hand
        drawSecondHand(mc, clockCentre, time.second, block.WOOD_PLANKS)

if __name__ == "__main__":

    clockCentre = minecraft.Vec3(0, 30, 0)
    radius = 20
    #Connect to minecraft by creating the minecraft object
    # - minecraft needs to be running and in a game
    mc = minecraft.Minecraft.create()

    #Post a message to the minecraft chat window 
    mc.postToChat("Hi, Minecraft Analogue Clock,")

    lastTime =
    #draw the clock
    drawClock(mc, clockCentre, radius, lastTime)
    #loop until Ctrl C is pressed
        while True:
            nowTime =
            #update the time on the clock
            updateTime(mc, clockCentre, lastTime, nowTime)
            lastTime = nowTime
    except KeyboardInterrupt:
        print "stopped"

The complete code repository is also on github

Note - minecraft must be running and you must be in a game

python ~/minecraft-clock/

or if using Idle, click Run Module


  1. Hi,

    after spending several hours trying to figure out on my own how to run this program, I now ask for your help. First of all I have to tell you that I don`t know much about programming, especially in linux/python.

    Allright, so here`s what I already figured out:

    After running python I can type in:

    import minecraft.minecraft as minecraft
    mc = minecraft.Minecraft.create()

    And then I can do some basic stuff like:


    But know I want to do more and therefore I tried to install your program, but I`m stuck. I made a folder home/pi/mcpi/minecraft-clock and copied all the files from the mcpi folder (like event.pyc, etc.) into it.

    Then I used Midori to surf to your site, copied the sourcecode, opened IDLE, used "paste" to copy the code, but when I click "Save As" I get the error: "Non-ASCII found, yet no encoding declared. Add a line like # -*- coding: utf-8 -*- to your file." Do you know what I`m doing wrong?

    Thanks a lot for sharing your code - that really helps guys like me trying to understand how to program with minecraft.

    By the way, I`m a teacher from germany and I bought ten raspberry pi in order to show pupils how to build some cool stuff and make a few simple programs. As I said - I`m not a big programmer myself, that`s why I spend my weekends trying to understand how Python, Minecraft and other programs like Scratch work. Then I try to simplify it in order to explain it in a very simple way so that a 12 year old can understand it.

    Therefore I would appreciate it a lot if you could maybe write some very, very simple programs that just build a tower or something like that, so that pupils can understand what`s going on.

    Again - thanks a lot for your work - I really like your blog!

    1. Hi,

      I suspect the route of your troubles is that you are getting some odd characters when you are cutting and pasting the code out of the web browser (they have a habit of doing that!), before pasting the code in idle, try putting it into a standard text editor and then saving it to a standard text file. Hopefully that will ensure you have nothing but plain text in your file. If that doesnt work follow the link to github and download the code file direct from their.


  2. Hi - thanks for your answer! Just wanted to let you know that I got it running now - I hope you don`t mind if I copy your program to my ten Raspberry Pi to show it to my pupils :)

    Great work! Greetings from Germany!

  3. Hi Martin:

    Awesome work! I’m new to Linux and also new to Python programming, so it took me a bit of time to get this working. I wanted to share some tips for beginners. My son is really interested in learning to program and loves minecraft, so your posts are a perfect combination for learning!

    I’d like to make a few suggestions, to help other kids or novices who are totally new at this (like me), to get started:
    1) Power on your raspberrypi, login, and type ‘startx’

    2) If you haven’t already installed minecraft, you must do this first. Follow the link and instructions at:

    3) Launch the LXTerminal program from the desktop.

    4) You are now in your user directory /home/pi (assuming your username is pi). If you are not in your home directory, go there.

    5) Use the following commands within LXTerminal (* Note: modified from above, i.e. I removed the ‘~/’ from the commands):
    (a) Create a directory for the program:
    mkdir minecraft-clock

    (b) Copy the python api class library from the original minecraft to the programs directory:
    cp -r mcpi/api/python/mcpi minecraft-clock/minecraft

    (c) Create the python program using a text editor program called nano (* Note: I changed the name to for consistency for the program and directory):
    nano minecraft-clock/

    (d) You will now see an empty screen in nano. You must copy and paste the program code into nano. ** However, the code on this web-page contains hidden characters, and doesn’t work. Instead use Martin’s code from his link at:
    (i) go to that page
    (ii) press
    (iii) press ‘Raw’
    (iv) Copy that code, and paste into nano

    (e) You must now save the nano file. Do this by pressing “Ctrl-o”

    (f) exit the nano program, i.e. “Ctrl-x”

    (g) Launch the IDLE program on the desktop (wait for it . . .) Then, open the minecraft-clock/ program with:
    File --> Open --> minecraft-clock -->

    (i) Go back to LXTerminal, and run the game and start playing:
    cd mcpi
    Press ‘Start Game’, select world, etc . . .
    Pause game by pressing “Esc”

    (j) Go back to IDLE, and run the Python program:
    Run --> Run Module
    (a new shell will open by itself, and start running)

    (k) Go back to minecraft and resume your game:
    Press “Back to game”
    (after several seconds, the clock will build itself in the world and start working. Awesome!!!)

    I hope other beginners find this comment useful.

    Thanks for all the awesome work you've done!

    Nick (Victoria, Canada)

    1. Thanks for the in-depth instructions, I do have a habit of simplifying, one of the things I was thinking about doing was adding instructions about how to download the code straight from git, removing all the ambiguity, but I'm conscious this means people don't see the code or have to learn how to make it work. What do you think? Would it be helpful.

  4. Hi Martin, I think people should definitely see the code, and I would leave it for them to copy and paste. There's a lot of learning that can be done when the instructions are limited. At the same time, I noticed my son, and perhaps other beginners, might get frustrated with a limited instruction set. So my instructions are more about getting beginners engaged (hooked on programming minecraft!), and hoping that will compel them to explore programming further.

    I also liked medienistik's comment above about making some "low level" programs, that beginners can explore. Like building a rectangular block tower, or a pyramid, or other simple shapes. I'll see if I can put something together over the next week, and I will send your way.

    1. Check out my minecraft api - the basics post, this might give you what your looking for.

  5. I am getting an import error "ImportError: No module named 'connection'" And I have tried several things to try to run the programs but it doesn't work, help please.

    1. Its the same issue as your other comment - Are you using Python 3? The python api library from mojang only works with Python 2.

  6. I come from the future and see that on THURSDAY, 21 NOVEMBER 2013

    "I was also keen that it use the Mojang supplied api, so I could create some re-usable functions which would no doubt be useful in the future such as:
    FindPointOnCircle" will become true and you will create a Python graphics module.

    Just a joke.

  7. Now that you have created "minecraftstuff", another version of this program
    can be made that is much shorter and replaces the shape drawing code
    with calls to the "minecraftstuff" module. It will need to include the Python
    module with it though.

    I'm not saying Martin should make it though, I'm just saying it's possible.