LogalDeveloper/Minecraft-Overviewer
Archived
0
Fork 0
Code Activity

finished up the essential documentation

Browse Source
This commit is contained in:
Andrew Brown
2011-10-01 15:58:31 -04:00
parent 061db039c1
commit a6035a15c3
7 changed files with 493 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
running.rst
View File

@@ -5,20 +5,131 @@ 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``.
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``.
To generate your map, run::
The basic usage for Windows is::
overviewer.exe WorldName path\to\output\ # on windows, or
./overviewer.py WorldName path/to/output/ # on other systems
overviewer.exe [options] <World> <Output Dir>
where ``WorldName`` is the name of the world you want to render, and
``path/to/output`` is the place where you want to store the rendered world. The
first render can take a while, depending on the size of your world. You can, if
you want to, provide a path to the world you want to render, instead of
providing a world name and having Overviewer auto-discover the world path.
And similarly for other systems::
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!
overviewer.py [options] <World> <Output Dir>
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 rerender only what's needed.
**World**
World can be one of several things.
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.
**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 `Options <options.html>`_ page for a list of options you can
specify.
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.
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 Overviewer will
automatically rerender only what's needed.
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.
You have several options:
* 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'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::
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.
* You can put a terrain.png file anywhere you want and point to its location
with the ``--textures-path`` option. This should point to the directory containing
the terrain.png, not to the file itself.
Note: the ``--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`
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``
will handle this correctly as well. If you use some other tool, you'll have to
figure out how to do this yourself.