The Minecraft Overviewer

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 overviewer.py 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.

Why?

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:

./overviewer.py --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: http://docs.overviewer.org/en/latest/config/. 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 overviewer.py from a cron or on a schedule with a bunch of options. Let's say you're running this:

overviewer.py -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 "myovconfig.py". 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:

overviewer.py --config=/path/to/myovconfig.py

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!