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

2
building.rst
View File

@@ -112,6 +112,8 @@ The following script (copied into your MCO source directory) should handle every
# build MCO
C_INCLUDE_PATH="`pwd`/Imaging-1.1.7/libImaging" python ./setup.py build
.. _centos:
CentOS
------
Since CentOS has an older version of Python (2.4), there are some difficulties

5
design/designdoc.rst
View File

@@ -15,6 +15,8 @@ Overviewer development.
So let's get started!
.. contents::
Background Info
===============
The Overviewer's task is to take Minecraft worlds and render them into a set of tiles that can be displayed with a Google Maps interface.
@@ -191,6 +193,9 @@ This is done at the end of :func:`textures._build_block`
.. image:: pixelfix.png
:alt: The 6 pixels manually added to each cube.
Other Cube Types
----------------
Chunk Rendering
===============
.. This goes over the rendering of a chunk

BIN
design/screenshot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 114 KiB

22
faq.rst Normal file
View File

@@ -0,0 +1,22 @@
==========================
Frequently Asked Questions
==========================
**The full map doesn't display even when fully zoomed out!**
Are you using the `-z` or `--zoom` option on your commandline or in
settings.py? If so, try removing it, or increasing the value you set. It's
quite likely you don't need it at all.
**You've added a few feature, but it's not showing up on my map!**
Some new features will only show up in newly-rendered areas. Use the
`--forcerender` option to update the entire map.
**How do I use this on CentOS 5?**
CentOS 5 comes with Python 2.4, but the Overviewer needs 2.6 or higher. See
the special instructions at :ref:ref:`centos`
**The background color of the map is black, and I don't like it!**
You can change this by using the ``--bg-color`` command line option, or
``bg_color`` in settings.py. See the `Options <options.html>`_ page for more
details.

2
index.rst
View File

@@ -54,6 +54,8 @@ Documentation Contents
building
installing
running
options
faq
design/designdoc

340
options.rst Normal file
View File

@@ -0,0 +1,340 @@
=======
Options
=======
.. contents::
:local:
Command line options
====================
.. cmdoption:: -h, --help
Shows the list of options and exits
.. cmdoption:: --advanced-help
Display help - including advanced options
Useful Options
--------------
.. cmdoption:: --rendermodes=MODE1[,MODE2,...]
Use this option to specify which render mode to use, such as lighting or
night. Use --list-rendermodes to get a list of available rendermodes, and
a short description of each. If you provide more than one mode (separated
by commas), Overviewer will render all of them at once, and provide a
toggle on the resulting map to switch between them.
If for some reason commas do not work for your shell (like if you're using
Powershell on Windows), you can also use a colon ':' or a forward slash '/'
to separate the modes.
See the `Render Modes`_ section for more information.
.. cmdoption:: --list-rendermodes
List the available render modes, and a short description of each.
.. cmdoption:: --north-direction=NORTH_DIRECTION
Specifies which corner of the screen north will point to.
Valid options are: lower-left, upper-left, upper-right, lower-right.
If you do not specify this option, it will default to whatever direction
the existing map uses. For new maps, it defaults to lower-left for
historical reasons.
.. cmdoption:: --settings=PATH
Use this option to load settings from a file. For more information see the
`Settings File`_ section below.
Less Useful Options
-------------------
.. cmdoption:: -p PROCS, --processes=PROCS
Adding the "-p" option will utilize more cores during processing. This
can speed up rendering quite a bit. The default is set to the same
number of cores in your computer, but you can adjust it.
Example to run 5 worker processes in parallel::
python overviewer.py -p 5 <Path to World> <Output Directory>
.. cmdoption:: -d, --delete
This option changes the mode of execution. No tiles are rendered, and
instead, files are deleted.
*Note*: Currently only the overviewer.dat file is deleted when you run with
this option
.. cmdoption:: --forcerender
Force re-rendering the entire map (or the given regionlist). This
is an easier way to completely re-render without deleting the map.
.. cmdoption:: --regionlist=regionlist
Use this option to specify manually a list of regions to consider for
updating. Without this option, every chunk in every region is checked for
update and if necessary, re-rendered. If this option points to a file
containing, 1 per line, the path to a region data file, then only those
in the list will be considered for update.
It's up to you to build such a list. On Linux or Mac, try using the "find"
command. You could, for example, output all region files that are older than
a certain date. Or perhaps you can incrementally update your map by passing
in a subset of regions each time. It's up to you!
Settings File
=============
You can optionally store settings in a file named settings.py (or really,
anything you want). It is a regular python script, so you can use any python
functions or modules you want. To use a settings file, use the --settings
command line option.
For a sample settings file, look at 'sample.settings.py'. Note that this file
is not meant to be used directly, but instead it should be used as a
collection of examples to guide writing your own.
Here's a (possibly incomplete) list of available settings, which are available
in settings.py. Note that you can also set command-line options in a similar
way.
imgformat=FORMAT
Set the output image format used for the tiles. The default is 'png',
but 'jpg' is also supported.
zoom=ZOOM
The Overviewer by default will detect how many zoom levels are required
to show your entire map. This option sets it manually.
*You do not normally need to set this option!*
This is equivalent to setting the dimensions of the highest zoom level. It
does not actually change how the map is rendered, but rather *how much of
the map is rendered.* Setting this option too low *will crop your map.*
(Calling this option "zoom" may be a bit misleading, I know)
To be precise, it sets the width and height of the highest zoom level, in
tiles. A zoom level of z means the highest zoom level of your map will be
2^z by 2^z tiles.
This option map be useful if you have some outlier chunks causing your map
to be too large, or you want to render a smaller portion of your map,
instead of rendering everything.
Remember that each additional zoom level adds 4 times as many tiles as
the last. This can add up fast, zoom level 10 has over a million tiles.
Tiles with no content will not be rendered, but they still take a small
amount of time to process.
web_assets_hook
This option lets you define a function to run after the web assets have
been copied into the output directory, but before any tile rendering takes
place. This is an ideal time to do any custom postprocessing for
markers.js or other web assets.
This function should accept one argument: a QuadtreeGen object.
web_assets_path
This option lets you provide alternative web assets to use when
rendering. The contents of this folder will be copied into the output folder
during render, and will overwrite any default files already copied by
Overviewer. See the web_assets folder included with Overviewer for the
default assets.
textures_path
This is like web_assets_path, but instead it provides an alternative texture
source. Overviewer looks in here for terrain.png and other textures before
it looks anywhere else.
north_direction
Specifies which corner of the screen north will point to.
Valid options are: lower-left, upper-left, upper-right, lower-right.
Render Modes
============
.. _rendermode-options: https://github.com/agrif/Minecraft-Overviewer/tree/rendermode-options
Rendermode options are a new way of changing how existing render modes
work, by passing in values at startup. For example, you can change how
dark the 'night' mode is, or enable lighting in 'cave' mode.
Options and Rendermode Inheritance
----------------------------------
Each mode will accept its own options, as well as the options for
parent modes; for example the 'night' mode will also accept options
listed for 'lighting' and 'normal'. Also, if you set an option on a
mode, all its children will also have that option set. So, setting the
'edge_opacity' option on 'normal' will also set it on 'lighting' and
'night'.
Basically, each mode inherits available options and set options from
its parent.
Eventually the :option:`--list-rendermodes` option will show parent
relationships. Right now, it looks something like this:
* normal
* lighting
* night
* cave
* overlay
* spawn
* mineral
How to Set Options
------------------
Available options for each mode are listed below, but once you know
what to set you'll have to edit *settings.py* to set them. Here's an
example::
rendermode_options = {
'lighting': {
'edge_opacity': 0.5,
},
'cave': {
'lighting': True,
'depth_tinting': False,
},
}
As you can see, each entry in ``rendermode_options`` starts with the mode name
you want to apply the options to, then a dictionary containing each option. So
in this example, 'lighting' mode has 'edge_opacity' set to 0.5, and 'cave' mode
has 'lighting' turned on and 'depth_tinting' turned off.
Defining Custom Rendermodes
---------------------------
Sometimes, you want to render two map layers with the same mode, but with two
different sets of options. For example, you way want to render a cave mode with
depth tinting, and another cave mode with lighting and no depth tinting. In this
case, you will want to define a 'custom' render mode that inherits from 'cave'
and uses the options you want. For example::
custom_rendermodes = {
'cave-lighting': {
'parent': 'cave',
'label': 'Lit Cave',
'description': 'cave mode, with lighting',
'options': {
'depth_tinting': False,
'lighting': True,
}
},
}
rendermode = ['cave', 'cave-lighting']
Each entry in ``custom_rendermodes`` starts with the mode name, and is followed
by a dictionary of mode information, such as the parent mode and description
(for your reference), a label for use on the map, as well as the options to
apply.
Every custom rendermode you define is on exactly equal footing with the built-in
modes: you can put them in the ``rendermode`` list to render them, you can
inherit from them in other custom modes, and you can even add options to them
with ``rendermode_options``, though that's a little redundant.
Option Listing
--------------
Soon there should be a way to pull out supported options from Overviewer
directly, but for right now, here's a reference of currently supported options.
normal
~~~~~~
* **edge_opacity** - darkness of the edge lines, from 0.0 to 1.0 (default: 0.15)
* **min_depth** - lowest level of blocks to render (default: 0)
* **max_depth** - highest level of blocks to render (default: 127)
* **height_fading** - darken or lighten blocks based on height (default: False)
lighting
~~~~~~~~
all the options available in 'normal', and...
* **shade_strength** - how dark to make the shadows, from 0.0 to 1.0 (default: 1.0)
night
~~~~~
'night' mode has no options of its own, but it inherits options from
'lighting'.
cave
~~~~
all the options available in 'normal', and...
* **depth_tinting** - tint caves based on how deep they are (default: True)
* **only_lit** - only render lit caves (default: False)
* **lighting** - render caves with lighting enabled (default: False)
mineral
~~~~~~~
The mineral overlay supports one option, **minerals**, that has a fairly
complicated format. **minerals** must be a list of ``(blockid, (r, g, b))``
tuples that tell the mineral overlay what blocks to look for. Whenever a block
with that block id is found underground, the surface is colored with the given
color.
See the *settings.py* example below for an example usage of **minerals**.
Example *settings.py*
---------------------
This *settings.py* will render three layers: a normal 'lighting' layer, a 'cave'
layer restricted to between levels 40 and 55 to show off a hypothetical subway
system, and a 'mineral' layer that has been modified to show underground rail
tracks instead of ore.
::
rendermode = ['lighting', 'subway-cave', 'subway-overlay']
custom_rendermodes = {
'subway-cave' : {'parent' : 'cave',
'label' : 'Subway',
'description' : 'a subway map, based on the cave rendermode',
'options' : {
'depth_tinting' : False,
'lighting' : True,
'only_lit' : True,
'min_depth' : 40,
'max_depth' : 55,
}
},
'subway-overlay' : {'parent' : 'mineral',
'label' : 'Subway Overlay',
'description' : 'an overlay showing the location of minecart tracks',
'options' : {'minerals' : [
(27, (255, 234, 0)),
(28, (255, 234, 0)),
(66, (255, 234, 0)),
]}
},
}
rendermode_options = {
'lighting' : {'edge_opacity' : 0.5},
# 'night' : {'shade_strength' : 0.5},
# 'cave' : {'only_lit' : True, 'lighting' : True, 'depth_tinting' : False},
}

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.