Minecraft mapping with Python, Pygame and OpenGL

When playing Minecraft, I love doing stuff underground: mining, spelunking and digging great big tunnels. I really wanted to map out the mines I have dug and the caverns I have explored. There are a lot of great Minecraft mapping tools, but not many of them that seem oriented to underground mapping. I also thought it would be fun to write my own, and I have a few ideas for distinct directions to develop it in when it gets far enough. This series of articles will cover all the code that I've written and will span a range of topics including Pygame, OpenGL, Numpy and the structure of Minecraft maps.

You can see some teaser images of the sort of things I have working right now over on the right. The textures are from the Painterly Pack, which I thoroughly recommend as a Minecraft texture pack.

Here's the rough plan for the series:

  1. 2D rendering strategy
  2. Pygame – Making a diagnostic texture
  3. PyOpenGL – Rendering with a pixel shader
  4. PyOpenGL – Tiled rendering with a pixel shader
  5. Pygame – Zooming and panning
  6. NBT – Reading Minecraft files
  7. Numpy – Flattening a Minecraft map
  8. Lighting
  9. Rotating and flipping to render mine-cart tracks
  10. Ambient occlusion to give a sense of depth

The tentative schedule is going to be Tuesdays and Fridays. This Friday we'll start with an overview of the basic rendering strategy for our maps.


  1. Cool! Hopefully you'll post the code somewhere so folks can play with it?

  2. Yep, I plan to put all the code online by the end of the series. I'm working in a local git repository, but I've not given a lot of thought to how to share it. I think I'll have examples to download each post and then I'll maybe put the repository up on github when I'm done.

  3. > I'll maybe put the repository up on github when I'm done.

    I would encourage you to put it up as soon as possible. You already have it in git scm, and putting it on github will help you get some 'skin in the game' as far as staying committed to the project. Plus, in the event that you never 'get around to finishing it completely', having a 70% version on github gives the community the opportunity to pick up the torch and someday complete your vision (power of forking).

    Additionally, if you're really committed to the project, you're going to be enrolling people in your vision anyway. It'll simply be convenient to point them at the github repo rather then "Come over to my laptop and I'll show you the code...if I remember where I put it"

  4. Good points, Travis. Coincidentally, just yesterday I created a github project for it, in part because I realised it was going to be a right pain to upload files for each post to a web-server and then keep them up to date if I later had to fix bugs in them. There will be a link in Friday's post, but if you're impatient you can see it here: https://github.com/weeble/clockworkcodex_minemap

    Be warned that I've been tidying up the code as I write each post. The as-yet undiscussed code is rather more chaotic.

  5. Awesome, thank you! You should look into github's advanced linking features, I'm pretty sure you can link to specific lines in source files and have them jumped to AND highlighted. Sounds like a great resource for your posts.

    I know that you can also very easily transclude gists, so I imagine the same is true for source files?

    Keep up the good work!