The Minecraft Overviewer

a high-resolution Minecraft world renderer with a LeafletJS interface

Overviewer 0.9 released!

For an intro to Overviewer in general, see the front page of our documentation site.

Support for Minecraft 1.2 worlds is now merged into the "master" branch of our repository!

Those of you who have repositories with "anvil" or "rewrite" checked out will need to switch to the master branch (git checkout master).

Those of you who have the old "master" branch checked out will need to see This Post to upgrade to the new version. Config files are incompatible with this upgrade, so this is important!

Also to note if you're upgrading from 0.4 (the old master branch): remember that due to changes made to the format you WILL need to re-render your maps from scratch. Trying to update existing maps will NOT work. Also due to major changes to the web assets, you should not simply copy over custom web assets to the new version. In particular, custom overviewerConfig.js files can cause strange problems.

The new version has been arbitrarily named 0.9. Windows builds are now available on our downloads page.

As always, stop in on IRC with any questions or just to say hi!

This is still in beta because there are a few features yet missing, but since Minecraft 1.2 is released, we felt that it was more important to have the master branch compatible with the current Minecraft. Here are the features yet to be implemented:

  • Signs, Spawn markers, and other Points of Interest
  • Ordering of renders and worlds in the javascript interface Edit: Done! Mar 6 2012
  • Overlays


Anvil Support

Edit: The "anvil" branch is now merged into master as version 0.9. The note about using anvil is still relevant, but there no longer exists an "anvil" branch. Links to the docs updated. -brownan

The Overviewer now has initial support for the new Anvil map format (used in Minecraft 1.2)! You can find this version in the anvil branch on GitHub. If you need a Windows build, feel free to ask us in our IRC channel.

(Edit: we build the windows builds on-demand. Right now things are developing rapidly and the current version may be unstable, so that's why we're not building them automatically. Once things stabilize we'll start posting the new builds on to the github downloads page. -brownan)

Using the Anvil Branch

The Anvil branch is based on our recent code rewrite, which means that it has a different configuration format and command line options. Please see our blog post or the documentation for more details. Changes made during the rewrite made it much easier to upgrade the Overviewer to Anvil; making these same changes to the old code would be much harder, so we are not planning to update the old code to handle Anvil.

Due to the large changes made to support Anvil, you will need to render your maps from scratch. Trying to update existing maps will not work. Also, due to major changes to the web assets during the rewrite, you should not simply copy over custom web assets to the new version. In particular, custom overviewerConfig.js files can cause strange problems.

A Note about Biomes

In addition to the much taller worlds possible with Anvil, the new map format now stores biome information with the chunks. This means that you no longer have to run the Biome Extractor in order to get biome colors on your maps. Biome colors are working right now in the Anvil branch; go check it out!


RPM packages now available

To complement our APT repository, we now offer an RPM repository for RPM-based distros. Currently the RPMs are available for CentOS 5 and 6 and Fedora 16 but other targets could be added if there is enough interest. Details on installing the repo can be found over on RPM repo info page.

Are there any other platforms we should support? Let us know in the comments or drop by the IRC channel!


Status of the new beta, and comments on Anvil

Thanks to those that have tried the new beta and given us feedback. We've already fixed several bugs; things are shaping up nicely!

About the new "Anvil" level format, we will be supporting this, but it is a rather hefty change. Our tentative plan is to make a new branch off of the beta "rewrite" branch for the anvil level format. Once the anvil format makes its way out of the Minecraft "pre-release" stage and into a proper release, we will merge the branch of our code and the new format will be the only one supported from then on.

We currently don't have any plans to support the Anvil format in the old "master" branch. We are not against it, but I don't foresee anyone stepping up to do the work. This means there is a deadline for those of you to convert your config files and setups to the new config format if you want to stay up to date. We believe the new config format is not complicated enough to be a big barrier for converting. If you need help please see us in IRC!

We also currently don't have any plans to support both world formats in one code-base. The changes it requires are quite extensive and I don't see that as being a very feasible option. Thus, if you want to continue running an older version of Minecraft with the older level format in the future, you will be blocked from updating Overviewer past a certain point. We will probably end up leaving a Git branch or tag at the last commit that supports the old format for those that don't want to upgrade. However, as time goes on we think most everyone will end up updating (just like we did for the old chunk format when it upgraded to region files)

Again, this is our tentative plan. Things may still change depending on demand or who's willing to do what work or how difficult a task turns out to be.

As always, happy Overviewing!



About the new Config File format

Edit Mar 3 2012: The "anvil" branch has been merged into master. This post edited to reflect that.

Edit: Mar 1 2012, updated this post to reflect the new "anvil" branch.

In our efforts to rewrite the internals of The Overviewer, we have stripped of almost all its command line options and opted to require everything but the simplest renders into a new config file format. This post goes over the rationale and how to get started with the new format.


Before it was possible to run the Overviewer without a configuration file at all. Every option was on the command line, and the only thing you needed the config file for was custom rendermodes.

But as we were thinking about supporting multi-world, where a server may run many Minecraft worlds, we wanted Overviewer to handle options in a more general way. Some options may only apply to one render of one world, others may apply to all renders.

We briefly considered how to support this on a command line, perhaps with something like this:

./ --world=/path/world1 --opt=1 --world=/path/world2 --opt=2

but this seems cumbersome and confusing. It seems obvious that a more structured method of configuring your renders is needed.

The Config File

So here's the solution we came up with. It lets you individually specify "renders", which is a rendering of a world with a set of options. You can specify multiple renders of a single world with different options, renders of different worlds, etc. We tried to leave it as customizable as possible.

The configuration file is, as before, parsed as a regular python file, meaning you can put any extra complicated logic you want in there. After it's parsed, it expects three things to be defined:

  • a dictionary called "worlds" that maps world names to their paths on disk.
  • a dictionary called "renders" that maps render names to a dictionary of options.
  • a string called "outputdir" containing the path to the directory to place the output

I have written up further details about the config file on the documentation site: Head there and have a look over it to get an idea of what's possible. I don't want to repeat what's there, and I think that's a pretty good place to start.

Converting your existing setup to a config file

Most likely you have some setup where you run from a cron or on a schedule with a bunch of options. Let's say you're running this: -v --north-direction=upper-right --imgformat=jpg --rendermodes=smooth-lighting,smooth-night /path/to/myworld /path/to/mymap

To migrate to the new branch, you should first create a config file. It can be named anything you want. If your editor has syntax highlighting, it will be helpful to give it the extension .py, but it's not necessary.

Say you create "". This is what you'd add to that file to duplicate your setup:

worlds["myworld"] = "/path/to/myworld"

renders["dayrender"] = {
        "world": "myworld",
        "title": "Daytime",
        "rendermode": smooth_lighting,
        "imgformat": "jpg",
        "northdirection": "upper-right",

renders["nightrender"] = {
        "world": "myworld",
        "title": "Nighttime",
        "rendermode": smooth_night,
        "imgformat": "jpg",
        "northdirection": "upper-right",

outputdir = "/path/to/mymap"

Note: the 'world' option was named 'worldname' up until recently.

Then you run Overviewer with this command: --config=/path/to/

Yes, it is a bit more verbose, but you can see how it is much more customizable than before. You can change the options for the individual renders, add renders for other worlds, add additional renders for the same world (perhaps with a different north-direction!) It's up to you!

As always, join us in IRC if you have any questions!