Running the Overviewer

Rendering your First Map

Overviewer is a command-line application, and so it needs to be run from the command line. If you installed Overviewer from a package manager, the command is overviewer.py. If you downloaded it manually, open a terminal window and navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds, the command is overviewer.exe. For other systems, it’s overviewer.py.

What follows in this section is a few examples to get you started. For full usage, see the Usage section.

So, let’s render your first map! Let’s say you want to render your single player world called “My World”. Let’s also say you want to save it c:mcmap. You would type into your command prompt the following:

overviewer.exe "My World" c:\mcmap

If you’re on Linux or a Mac, you could do something like one of the following:

overviewer.py "My World" /home/username/mcmap

or

overviewer.py "My World" /Users/username/mcmap

Those will look for a single player world by that name. You can also specify the path to the world you want to render. This is useful for rendering servers.

Let’s say you have a server installed in /home/username/mcserver. This command will render the default dimension (in the case of Bukkit multiworld servers, the default world is used. You can also specify the directory to the specific world you want to render).

overviewer.py /home/username/mcserver /home/username/mcmap

After you enter one of the commands, The Overviewer should start rendering your map. When the render is done, open up index.html using your web-browser of choice. Pretty cool, huh? You can even upload this map to a web server to share with others! Simply upload the entire folder to a web server and point your users to index.html!

Incremental updates are just as easy, and a lot faster. If you go and change something inside your world, run the command again and The Overviewer will automatically re-render only what’s needed.

Specifying a different rendermode

There are a few built-in rendermodes for you to choose from. Each will render your map differently. For example, if you want smooth lighting (which looks really good), you would add --rendermodes=smooth-lighting to your command. e.g.

overviewer.py --rendermodes=smooth-lighting /home/username/mcserver /home/username/mcmap

The rendermodes you have to choose from are:

  • normal (the default)
  • lighting
  • smooth-lighting
  • cave

You can specify more than one. Just separate them with a comma!

Usage

For this section, we assume the executable is overviewer.py. Replace that with overviewer.exe for windows.

Overviewer usage:

overviewer.py [--rendermodes=...] [options] <World> <Output Dir>
overviewer.py --config=<config file> [options]

The first form is for basic or quick renderings without having to create a config file. It is intentionally limited because the amount of configuration was becoming unmanageable for the command line.

The second, preferred usage involves creating a configuration file which specifies all the options including what to render, where to place the output, and all the settings. See The Configuration File for details on that.

For example, on Windows if your Minecraft server runs out of c:\server\ and you want to put the rendered map in c:\mcmap\, run this:

overviewer.exe c:\server\world c:\mcmap

For Mac or Linux builds from source, you would run something like this with the current directory in the top level of the source tree:

./overviewer.py /opt/minecraft/server/world /opt/minecraft/mcmap

The first render can take a while, depending on the size of your world.

Options

The following three options change the way The Overviewer determines which tiles to update, and are intended to be things you only have to use in special situations. You should not normally have to specify these options; the default is typically correct.

--no-tile-checks

With this option, The Overviewer will determine which tiles to render by looking at the saved last-render timestamp and comparing it to the last-modified time of the chunks of the world. It builds a tree of tiles that need updating and renders only those tiles.

This option does not do any checking of tile mtimes on disk, and thus is the cheapest option: only rendering what needs updating while minimising disk IO.

The caveat is that the only thing to trigger a tile update is if Minecraft updates a chunk. Any other reason a tile may have for needing re-rendering is not detected. This means that changes in your render configuration will not be reflected in your world except in updated chunks. It could also cause problems if the system clock of the machine running Minecraft is not stable.

This option is the default unless --forcerender or --check-tiles is in effect. This option conflicts with --forcerender and --check-tiles.

--check-tiles

Forces The Overviewer to check each tile on disk and check to make sure it is up to date. This also checks for tiles that shouldn’t exist and deletes them.

This is functionally equivalent to --no-tile-checks with the difference that each tile is individually checked. It is therefore useful if the tiles are not consistent with the last-render timestamp that is automatically stored. This option was designed to handle the case where the last render was interrupted – some tiles have been updated but others haven’t, so each one is checked before it is rendered.

This is slightly slower than --no-tile-checks due to the additonaly disk-io involved in reading tile mtimes from the filesystem

Since this option also checks for erroneous tiles, It is also useful after you delete sections of your map, e.g. with worldedit, to delete tiles that should no longer exist.

The caveats with this option are the same as for --no-tile-checks with the additional caveat that tile timestamps in the filesystem must be preserved. If you copy tiles or make changes to them with an external tool that modifies mtimes of tiles, it could cause problems with this option.

This option is automatically activated when The Overviewer detects the last render was interrupted midway through. This option conflicts with --forcerender and --no-tile-checks

--forcerender

Forces The Overviewer to re-render every tile regardless of whether it thinks it needs updating or not. It does no tile mtime checks, and therefore ignores the last render time of the world, the last modification times of each chunk, and the filesystem mtimes of each tile. It unconditionally renders every tile that exists.

The caveat with this option is that it does no checks, period. Meaning it will not detect tiles that do exist, but shouldn’t (this can happen if your world shrinks for some reason. For that specific case, --check-tiles is actually the appropriate mode).

This option is useful if you have changed a render setting and wish to re-render every tile with the new settings.

This option is automatically activated for first-time renders. This option conflicts with --check-tiles and --no-tile-checks

--genpoi

Note

Don’t use this flag without first reading Signs and Markers!

Generates the POI markers for your map. This option does not do any tile/map generation, and ONLY generates markers. See Signs and Markers on how to configure POI options.

-p <procs>, --processes <procs>

This specifies the number of worker processes to spawn on the local machine to do work. It defaults to the number of CPU cores you have, if not specified.

This option can also be specified in the config file as processes

-v, --verbose

Activate a more verbose logging format and turn on debugging output. This can be quite noisy but also gives a lot more info on what The Overviewer is doing.

-q, --quiet

Turns off one level of logging for quieter output. You can specify this more than once. One -q will suppress all INFO lines. Two will suppress all INFO and WARNING lines. And so on for ERROR and CRITICAL log messages.

If --verbose is given, then the first -q will counteract the DEBUG lines, but not the more verbose logging format. Thus, you can specify -v -q to get only INFO logs and higher (no DEBUG) but with the more verbose logging format.

--update-web-assets

Update web assets, including custom assets, without starting a render. This won’t update overviewerConfig.js, but will recreate overviewer.js

Installing the Textures

If Overviewer is running on a machine with the Minecraft client installed, it will automatically use the default textures from Minecraft.

If, however, you’re running on a machine without the Minecraft client installed, or if you want to use different textures, you will need to provide the textures manually. This is common for servers.

If you want or need to provide your own textures, you have several options:

  • If you’re running the Overviewer on a server, you can still put the minecraft.jar file (not the launcher) into the correct location and the Overviewer will find and use it, thinking the client is installed, even if the rest of the client files are missing. On Linux, try a command like this:

    wget -N http://s3.amazonaws.com/MinecraftDownload/minecraft.jar -P ~/.minecraft/bin/
    
  • You can manually extract the terrain.png from minecraft.jar or your favorite texture pack. If you’ve built the Overviewer from source or are using the windows exe, place the file in the same directory as overviewer.py or overviewer.exe.

  • Specify any terrain.png or texture pack you want with the texturepath option.

If you copy your world before you render it

The important thing to be careful about when copying world files to another location is file modification times, which Overviewer uses to figure out what parts of the map need updating. If you do a straight copy, usually this will update the modification times on all the copied files, causing Overviewer to re-render the entire map. To copy files on Unix, while keeping these modification times intact, use cp -p. For people who render from backups, GNU tar automatically handles modification times correctly. rsync -a --delete will handle this correctly as well. If you use some other tool, you’ll have to figure out how to do this yourself.