LogalDeveloper/Minecraft-Overviewer
Archived
0
Fork 0
Code Activity

docs update to Running page and new page Config. Removed Options.

Browse Source 
Added all about the new config file format. Needs checking for accuracy.
Also need to update the faq and other sections of the docs now that the
options page is gone.
This commit is contained in:
Andrew Brown
2012-01-22 01:26:04 -05:00
parent 163dd66a38
commit 8c71c802d2
3 changed files with 133 additions and 858 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
docs/running.rst
View File

@@ -11,32 +11,87 @@ command line. If you installed Overviewer from a package manager, the command is
navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds,
the command is ``overviewer.exe``. For other systems, it's ``overviewer.py``.
The basic usage for Windows is::
What follows in this section is a few examples to get you started. For full
usage, see the :ref:`usage` section.
overviewer.exe [options] <World> <Output Dir>
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::
And similarly for other systems::
overviewer.exe "My World" c:\mcmap
overviewer.py [options] <World> <Output Dir>
If you're on Linux or a Mac, you could do something like one of the following::
**World**
World can be one of several things.
overviewer.py "My World" /home/username/mcmap
1. The path to your Minecraft world on your hard drive
2. The name of a single player world on your current system. Note that if it
has spaces, you will need to put the world name in quotes.
3. If your single-player world name is in the format "World #" (e.g. "World
1"), you can just specify the number.
or
**Output Dir**
This is the directory you would like to put the rendered tiles and
supporting HTML and javascript files. You should use the same output
directory each time; the Overviewer will automatically re-render only the
tiles that need rendering on subsequent runs.
::
**options**
See the :doc:`options` page for a list of options you can
specify.
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::
@@ -50,66 +105,75 @@ current directory in the top level of the source tree::
The first render can take a while, depending on the size of your world.
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!
.. _options:
Incremental updates are just as easy, and a lot faster. If you go and change
something inside your world, run the command again and Overviewer will
automatically re-render only what's needed.
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`.
.. _installing-textures:
Installing the Textures
=======================
If you're running on a machine without the Minecraft client installed, you will
need to provide the terrain.png file manually for the Overviewer to use in
rendering your world. This is common for servers.
All Overviewer needs is a terrain.png file. If the Minecraft client is
installed, it will use the terrain.png that comes with Minecraft. If the
Minecraft client is not installed or you wish to use a different terrain.png,
for example a custom texture pack, read on.
If Overviewer is running on a machine with the Minecraft client installed, it
will automatically use the default textures from Minecraft.
You have several options:
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 have the Minecraft client installed, the Overviewer will automatically
use those textures. This is a good solution since the Minecraft Launcher will
always keep this file up-to-date and you don't have to do anything extra.
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, even if the rest of the client files are
missing. On Linux, try a command like this::
* 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/
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, simply place the
file in the same directory as overviewer.py or overviewer.exe. For
installations, you will need to specify the path... see the next bullet.
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.
* You can put a terrain.png file anywhere you want and point to its
location with the :option:`--textures-path` option. This should
point to the directory containing the terrain.png, not to the file
itself.
* Alternately, you can download any texture pack ZIP you like and
point to this directly with :option:`--textures-path`.
Note: the :option:`--check-terrain` option is useful for debugging terrain.png issues.
For example::
$ ./overviewer.py --check-terrain
2011-09-26 21:51:46,494 [INFO] Found terrain.png in '/home/achin/.minecraft/bin/minecraft.jar'
2011-09-26 21:51:46,497 [INFO] Hash of terrain.png file is: `6d53f9e59d2ea8c6f574c9a366f3312cd87338a8`
::
$ ./overviewer.py --check-terrain --textures-path=/tmp
2011-09-26 21:52:52,143 [INFO] Found terrain.png in '/tmp/terrain.png'
2011-09-26 21:52:52,145 [INFO] Hash of terrain.png file is: `6d53f9e59d2ea8c6f574c9a366f3312cd87338a8`
* Specify any terrain.png or texture pack you want with the
:ref:`texture_pack<option_texture_pack>` option.
Running on a Live Map
=====================
@@ -138,9 +202,9 @@ 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``
will handle this correctly as well. If you use some other tool, you'll have to
figure out how to do this yourself.
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
=============