====================== 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 :ref:`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: Usage ===== For this section, we assume the executable is ``overviewer.py``. Replace that with ``overviewer.exe`` for windows. Overviewer usage:: overviewer.py [--rendermodes=...] [options] overviewer.py --config= [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 :ref:`configfile` 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: Options ------- These options change the way the render works, and are intended to be things you only have to use once-in-a-while. .. cmdoption:: --forcerender Forces The Overviewer to re-render every tile regardless of whether it thinks it needs updating or not. This is similar to deleting your output directory and rendering from scratch. This is the default mode for first-time renders. This option overrides :option:`--check-tiles` and :option:`--no-tile-checks` .. cmdoption:: --check-tiles Forces The Overviewer to check each tile on disk and compare its modification time to the modification time of the part of the world that tile renders. This is slightly slower than the default, but can be useful if there are some tiles that somehow got skipped. This option is the default when The Overviewer detects the last render was interrupted midway through. This option overrides :option:`--forcerender` and :option:`--no-tile-checks` .. cmdoption:: --no-tile-checks With this option, The Overviewer will not do any checking of tiles on disk to determine what tiles need updating. Instead, it will look at the time that the last render was performed, and render parts of the map that were changed since then. This is the fastest option, but could cause problems if the clocks of the Minecraft server and the machine running The Overviewer are not in sync. This option is the default unless the condition for :option:`--forcerender` or :option:`--check-tiles` is in effect. This option overrides :option:`--forcerender` and :option:`--check-tiles`. .. cmdoption:: -p , --processes 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 :ref:`processes ` .. _installing-textures: 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 :ref:`texture_pack` option. Running on a Live Map ===================== If you're running the Overviewer on a live server or a single player world that's running, read this section. Minecraft doesn't really like it when other programs go snooping around in a live world, so running Overviewer on a live world usually creates a few errors, usually "corrupt chunk" errors. You *can* do this, but it's not a supported way of running Overviewer. To get around this, you can copy your live world somewhere else, and render the copied world instead. If you're already making backups of your world, you can use the backups to make the render. Many people even use their backups to run Overviewer on a different machine than the one running the Minecraft server. There used to be a few things to be careful about, but right now there's only one important thing left. Preserving Modification Times ----------------------------- 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. Biome Support ============= Minecraft Overviewer has support for using the biome info from the `Minecraft Biome Extractor`_. If you run the biome extractor on your world, during the next run Overviewer will automatically recognize the biome info and use it to colorize your grass and leaves appropriately. This will only appear on updated chunks, though; to colorize the entire world you will need to re-render from scratch by using :option:`--forcerender` .. note:: as of Minecraft 1.8, you currently need to use a patched Biome Extractor that can be found `here `_, or `here on GitHub `_. .. _Minecraft Biome Extractor: http://www.minecraftforum.net/viewtopic.php?f=25&t=80902