263 lines
11 KiB
ReStructuredText
263 lines
11 KiB
ReStructuredText
======================
|
|
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] <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 :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
|
|
-------
|
|
|
|
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.
|
|
|
|
.. cmdoption:: --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 :option:`--forcerender` or
|
|
:option:`--check-tiles` is in effect. This option conflicts with
|
|
:option:`--forcerender` and :option:`--check-tiles`.
|
|
|
|
.. cmdoption:: --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 :option:`--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 :option:`--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 :option:`--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
|
|
:option:`--forcerender` and :option:`--no-tile-checks`
|
|
|
|
.. cmdoption:: --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,
|
|
:option:`--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 :option:`--check-tiles` and :option:`--no-tile-checks`
|
|
|
|
.. cmdoption:: --genpoi
|
|
|
|
.. note::
|
|
Don't use this flag without first reading :ref:`signsmarkers`!
|
|
|
|
Generates the POI markers for your map. This option does not do any tile/map
|
|
generation, and ONLY generates markers. See :ref:`signsmarkers` on how to
|
|
configure POI options.
|
|
|
|
|
|
.. cmdoption:: -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 :ref:`processes <processes>`
|
|
|
|
.. cmdoption:: -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.
|
|
|
|
.. cmdoption:: -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 :option:`--verbose<-v>` 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.
|
|
|
|
.. _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_texture_pack>` 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.
|