582 lines
19 KiB
ReStructuredText
582 lines
19 KiB
ReStructuredText
.. _configfile:
|
|
|
|
======================
|
|
The Configuration File
|
|
======================
|
|
|
|
Using a configuration file is now the preferred way of running The Overviewer.
|
|
You will need to create a blank file and specify it when running The Overviewer
|
|
like this::
|
|
|
|
overviewer.py --config=path/to/my_configfile
|
|
|
|
|
|
The config file is formatted in Python syntax. If you aren't familiar with
|
|
Python, don't worry, it's pretty simple. Just follow the examples.
|
|
|
|
A Simple Example
|
|
================
|
|
|
|
::
|
|
|
|
worlds["My world"] = "/home/username/server/world"
|
|
|
|
renders["normalrender"] = {
|
|
"world": "My world",
|
|
"title": "Normal Render of My World",
|
|
}
|
|
|
|
outputdir = "/home/username/mcmap"
|
|
|
|
This defines a single world, and a single render of that world. You can see
|
|
there are two main sections.
|
|
|
|
The ``worlds`` dictionary
|
|
Define items in the ``worlds`` dictionary as shown to tell The Overviewer
|
|
where to find your worlds. The keys to this dictionary ("My world" in the
|
|
example) is a name you give, and is referenced later in the render
|
|
dictionary. If you want to render more than one world, you would put more
|
|
lines like this one. Otherwise, one is sufficient.
|
|
|
|
The ``renders`` dictionary
|
|
Each item here declares a "render" which is a map of one dimension of one
|
|
world rendered with the given options. If you declare more than one render,
|
|
then you will get a dropdown box to choose which map you want to look at
|
|
when viewing the maps.
|
|
|
|
You are free to declare as many renders as you want with whatever options
|
|
you want. For example, you are allowed to render multiple worlds, or even
|
|
render the same world multiple times with different options.
|
|
|
|
.. note::
|
|
|
|
Since this is Python syntax, keep in mind you need to put quotation marks
|
|
around your strings. ``worlds[My world]`` will not work. It must be
|
|
``worlds["My world"]``
|
|
|
|
A more complicated example
|
|
==========================
|
|
::
|
|
|
|
worlds["survival"] = "/home/username/server/survivalworld"
|
|
worlds["creative"] = "/home/username/server/creativeworld"
|
|
|
|
renders["survivalday"] = {
|
|
"world": "survival",
|
|
"title": "Survival Daytime",
|
|
"rendermode": smooth_lighting,
|
|
"dimension": "overworld",
|
|
}
|
|
|
|
renders["survivalnight"] = {
|
|
"world": "survival",
|
|
"title": "Survival Daytime",
|
|
"rendermode": smooth_night,
|
|
"dimension": "overworld",
|
|
}
|
|
|
|
renders["survivalnether"] = {
|
|
"world": "survival",
|
|
"title": "Survival Nether",
|
|
"rendermode": nether_smooth_lighting,
|
|
"dimension": "nether",
|
|
}
|
|
|
|
renders["creative"] = {
|
|
"world": "creative",
|
|
"title": "Creative",
|
|
"rendermode": smooth_lighting,
|
|
"dimension": "overworld",
|
|
}
|
|
|
|
outputdir = "/home/username/mcmap"
|
|
texturepath = "/home/username/my_texture_pack.zip"
|
|
|
|
This config defines four maps for render. Two of them are of the survival
|
|
world's overworld, one is for the survival's nether, and one is for the creative
|
|
world.
|
|
|
|
Notice here we explicitly set the dimension property on each render. If
|
|
dimension is not specified, the default or overworld dimension is used. It is
|
|
necessary e.g. for the nether render.
|
|
|
|
Also note here we specify some different rendermodes. A rendermode refers to how
|
|
the map is rendered. The Overviewer can render a map in many different ways, and
|
|
there are many preset rendermodes, and you can even create your own (more on
|
|
that later).
|
|
|
|
And finally, note the usage of the ``texturepath`` option. This specifies a
|
|
texture pack to use for the rendering. Also note that it is set at the top level
|
|
of the config file, and therefore applies to every render. It could be set on
|
|
individual renders to apply to just those renders.
|
|
|
|
.. note::
|
|
|
|
See the ``sample_config.py`` file included in the repository for another
|
|
example.
|
|
|
|
Config File Specifications
|
|
==========================
|
|
|
|
The config file is a python file and is parsed with python's execfile() builtin.
|
|
This means you can put arbitrary logic in this file. The Overviewer gives the
|
|
execution of the file a local dict with a few pre-defined items (everything in
|
|
the overviewer_core.rendermodes module).
|
|
|
|
If the above doesn't make sense, just know that items in the config file take
|
|
the form ``key = value``. Two items take a different form:, ``worlds`` and
|
|
``renders``, which are described below.
|
|
|
|
``worlds``
|
|
This is pre-defined as an empty dictionary. The config file is expected to
|
|
add at least one item to it.
|
|
|
|
Keys are arbitrary strings used to identify the worlds in the ``renders``
|
|
dictionary.
|
|
|
|
Values are paths to worlds (directories with a level.dat)
|
|
|
|
e.g.::
|
|
|
|
worlds['myworld'] = "/path/to/myworld"
|
|
|
|
**You must specify at least one world**
|
|
|
|
``renders``
|
|
This is also pre-defined as an empty dictionary. The config file is expected
|
|
to add at least one item to it.
|
|
|
|
Keys are strings that are used as the identifier for this render in the
|
|
javascript, and also as the directory name for the tiles, but it's
|
|
essentially up to you. It thus is recommended to make it a string with no
|
|
spaces or special characters, only alphanumeric characters.
|
|
|
|
Values are dictionaries specifying the configuration for the render. Each of
|
|
these render dictionaries maps strings naming configuration options to their
|
|
values. Valid keys and their values are listed in the :ref:`renderdict`
|
|
section.
|
|
|
|
e.g.::
|
|
|
|
renders['myrender'] = {
|
|
'world': 'myworld',
|
|
'title': 'Minecraft Server Title',
|
|
}
|
|
|
|
**You must specify at least one render**
|
|
|
|
``outputdir = "<output directory path>"``
|
|
This is the path to the output directory where the rendered tiles will
|
|
be saved.
|
|
|
|
e.g.::
|
|
|
|
outputdir = "/path/to/output"
|
|
|
|
**Required**
|
|
|
|
.. _processes:
|
|
|
|
``processes = num_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 can also be specified with :option:`--processes <-p>`
|
|
|
|
e.g.::
|
|
|
|
processes = 2
|
|
|
|
.. _outputdir:
|
|
|
|
|
|
.. _renderdict:
|
|
|
|
Render Dictonary Keys
|
|
---------------------
|
|
|
|
The render dictionary is a dictionary mapping configuration key strings to
|
|
values. The valid configuration keys are listed below.
|
|
|
|
.. note::
|
|
|
|
Any of these items can be specified at the top level of the config file to
|
|
set the default for every render. For example, this line at the top of the
|
|
config file will set the world for every render to 'myworld' if no world is
|
|
specified::
|
|
|
|
world = 'myworld'
|
|
|
|
Then you don't need to specify a ``world`` key in the render dictionaries::
|
|
|
|
render['arender'] = {
|
|
'title': 'This render doesn't explicitly declare a world!',
|
|
}
|
|
|
|
``world``
|
|
Specifies which world this render corresponds to. Its value should be a
|
|
string from the appropriate key in the worlds dictionary.
|
|
|
|
**Required**
|
|
|
|
``title``
|
|
This is the display name used in the user interface. Set this to whatever
|
|
you want to see displayed in the Map Type control (the buttons in the upper-
|
|
right).
|
|
|
|
**Required**
|
|
|
|
.. _option_dimension:
|
|
|
|
``dimension``
|
|
Specified which dimension of the world should be rendered. Each Minecraft
|
|
world has by default 3 dimensions: The Overworld, The Nether, and The End.
|
|
Bukkit servers are a bit more complicated, typically worlds only have a
|
|
single dimension, in which case you can leave this option off.
|
|
|
|
The value should be a string. It should either be one of "overworld",
|
|
"nether", "end", or the directory name of the dimension within the world.
|
|
e.g. "DIM-1"
|
|
|
|
.. note::
|
|
|
|
If you choose to render your nether dimension, you must also use a
|
|
nether :ref:`rendermode<option_rendermode>`. Otherwise you'll
|
|
just end up rendering the nether's ceiling.
|
|
|
|
**Default:** ``"overworld"``
|
|
|
|
.. _option_rendermode:
|
|
|
|
``rendermode``
|
|
This is which rendermode to use for this render. There are many rendermodes
|
|
to choose from. This can either be a rendermode object, or a string, in
|
|
which case the rendermode object by that name is used.
|
|
|
|
e.g.::
|
|
|
|
"rendermode": "normal",
|
|
|
|
Here are the rendermodes and what they do:
|
|
|
|
``"normal"``
|
|
A normal render with no lighting. This is the fastest option.
|
|
|
|
``"lighting"``
|
|
A render with per-block lighting, which looks similar to Minecraft
|
|
without smooth lighting turned on. This is slightly slower than the
|
|
normal mode.
|
|
|
|
``"smooth_lighting"``
|
|
A render with smooth lighting, which looks similar to Minecraft with
|
|
smooth lighting turned on.
|
|
|
|
*This option looks the best* but is also the slowest.
|
|
|
|
``"night"``
|
|
A "nighttime" render with blocky lighting.
|
|
|
|
``"smooth_night"``
|
|
A "nighttime" render with smooth lighting
|
|
|
|
``"nether"``
|
|
A normal lighting render of the nether. You can apply this to any
|
|
render, not just nether dimensions. The only difference between this and
|
|
normal is that the ceiling is stripped off, so you can actually see
|
|
inside.
|
|
|
|
.. note::
|
|
|
|
Selecting this rendermode doesn't automatically render your nether
|
|
dimention. Be sure to also set the
|
|
:ref:`dimension<option_dimension>` option to 'nether'.
|
|
|
|
``"nether_lighting"``
|
|
Similar to "nether" but with blocky lighting.
|
|
|
|
``"nether_smooth_lighting"``
|
|
Similar to "nether" but with smooth lighting.
|
|
|
|
``"cave"``
|
|
A cave render with depth tinting (blocks are tinted with a color
|
|
dependent on their depth, so it's easier to tell overlapping caves
|
|
apart)
|
|
|
|
**Default:** ``"normal"``
|
|
|
|
.. note::
|
|
|
|
The value for the 'rendermode' key can be either a *string* or
|
|
*rendermode object* (strings simply name one of the built-in rendermode
|
|
objects). The actual object type is a list of *rendermode primitive*
|
|
objects. See :ref:`customrendermodes` for more information.
|
|
|
|
``northdirection``
|
|
This is direction that north will be rendered. This north direction will
|
|
match the established north direction in the game where the sun rises in the
|
|
east and sets in the west.
|
|
|
|
Here are the valid north directions:
|
|
|
|
* ``"upper-left"``
|
|
* ``"upper-right"``
|
|
* ``"lower-left"``
|
|
* ``"lower-right"``
|
|
|
|
**Default:** ``"upper-left"``
|
|
|
|
``rerenderprob``
|
|
This is the probability that a tile will be rerendered even though there may
|
|
have been no changes to any blocks within that tile. Its value should be a
|
|
floating point number between 0.0 and 1.0.
|
|
|
|
**Default:** ``0``
|
|
|
|
``imgformat``
|
|
This is which image format to render the tiles into. Its value should be a
|
|
string containing "png", "jpg", or "jpeg".
|
|
|
|
**Default:** ``"png"``
|
|
|
|
``imgquality``
|
|
This is the image quality used when saving the tiles into the JPEG image
|
|
format. Its value should be an integer between 0 and 100.
|
|
|
|
**Default:** ``95``
|
|
|
|
``bgcolor``
|
|
This is the background color to be displayed behind the map. Its value
|
|
should be either a string in the standard HTML color syntax or a 4-tuple in
|
|
the format of (r,b,g,a). The alpha entry should be set to 0.
|
|
|
|
**Default:** ``#1a1a1a``
|
|
|
|
.. _option_texture_pack:
|
|
|
|
``texturepath``
|
|
This is a where a specific texture pack can be found to be used during this render.
|
|
It can be either a folder or a directory. Its value should be a string.
|
|
|
|
``crop``
|
|
You can use this to render a small subset of your map, instead of the entire
|
|
thing. The format is (min x, min z, max x, max z).
|
|
|
|
(The coordinates are block coordinates. The same you get with the debug menu
|
|
in-game)
|
|
|
|
Example that only renders a 1000 by 1000 square of land about the origin::
|
|
|
|
renders['myrender'] = {
|
|
'world': 'myworld',
|
|
'title': "Cropped Example",
|
|
'crop': (-500, -500, 500, 500),
|
|
}
|
|
|
|
.. warning::
|
|
|
|
If you decide to change the bounds on a render, you may find it produces
|
|
unexpected results.
|
|
|
|
For an expansion to the bounds, because chunks in the new bounds have
|
|
the same mtime as the old, tiles will not automatically be updated. You
|
|
may need to use :option:`--forcerender` to force those tiles to update.
|
|
|
|
For reductions to the bounds, because there is currently no mechanism to
|
|
detect tiles that shouldn't exist but do, old tiles may remain and will
|
|
not get deleted. The only fix for this currently is to delete that
|
|
render directory and render it again with :option:`--forcerender`.
|
|
|
|
``forcerender``
|
|
This is a boolean. If set to ``True`` (or any non-false value) then this
|
|
render will unconditionally re-render every tile regardless of whether it
|
|
actually needs updating or not.
|
|
|
|
The :option:`--forcerender` command line option acts similarly, but with
|
|
one important difference. Say you have 3 renders defined in your
|
|
configuration file. If you use :option:`--forcerender`, then all 3 of those
|
|
renders get re-rendered completely. However, if you just need one of them
|
|
re-rendered, that's unnecessary extra work.
|
|
|
|
If you set ``'forcerender': True,`` on just one of those renders, then just
|
|
that one gets re-rendered completely. The other two render normally (only
|
|
tiles that need updating are rendered).
|
|
|
|
You probably don't want to leave this option in your config file, it is
|
|
intended to be used temporarily, such as after a setting change, to
|
|
re-render the entire map with new settings. If you leave it in, then
|
|
Overviewer will end up doing a lot of unnecessary work rendering parts of
|
|
your map that may not have changed.
|
|
|
|
Example::
|
|
|
|
renders['myrender'] = {
|
|
'world': 'myworld',
|
|
'title': "Forced Example",
|
|
'forcerender': True,
|
|
}
|
|
|
|
.. _customrendermodes:
|
|
|
|
Custom Rendermodes and Rendermode Primitives
|
|
============================================
|
|
|
|
We have generalized the rendering system. Every rendermode is made up of a
|
|
sequence of *rendermode primitives*. These primitives add some functionality to
|
|
the render, and stacked together, form a functional rendermode. Some rendermode
|
|
primitives have options you can change. You are free to create your own
|
|
rendermodes by defining a list of rendermode primitives.
|
|
|
|
There are 9 rendermode primitives. Each has a helper class defined in
|
|
overviewer_core.rendermodes, and a section of C code in the C extension.
|
|
|
|
A list of rendermode primitives defines a rendermode. During rendering, each
|
|
rendermode primitive is applied in sequence. For example, the lighting
|
|
rendermode consists of the primitives "Base" and "Lighting". The Base primitive
|
|
draws the blocks with no lighting, and determines which blocks are occluded
|
|
(hidden). The Lighting primitive then draws the appropriate shading on each
|
|
block.
|
|
|
|
More specifically, each primitive defines a draw() and an is_occluded()
|
|
function. A block is rendered if none of the primitives determine the block is
|
|
occluded. A block is rendered by applying each primitives' draw() function in
|
|
sequence.
|
|
|
|
The Rendermode Primitives
|
|
-------------------------
|
|
|
|
Base
|
|
This is the base of all non-overlay rendermodes. It renders each block
|
|
according to its defined texture, and applies basic occluding to hidden
|
|
blocks.
|
|
|
|
Nether
|
|
This doesn't affect the drawing, but occludes blocks that are connected to
|
|
the ceiling.
|
|
|
|
HeightFading
|
|
Draws a colored overlay on the blocks that fades them out according to their
|
|
height.
|
|
|
|
Depth
|
|
Only renders blocks between the specified min and max heights.
|
|
|
|
**Options**
|
|
|
|
min
|
|
lowest level of blocks to render. Default: 0
|
|
|
|
max
|
|
highest level of blocks to render. Default: 255
|
|
|
|
EdgeLines
|
|
Draw edge lines on the back side of blocks, to help distinguish them from
|
|
the background.
|
|
|
|
**Options**
|
|
|
|
opacity
|
|
The darkness of the edge lines, from 0.0 to 1.0. Default: 0.15
|
|
|
|
Cave
|
|
Occlude blocks that are in direct sunlight, effectively rendering only
|
|
caves.
|
|
|
|
**Options**
|
|
|
|
only_lit
|
|
Only render lit caves. Default: False
|
|
|
|
DepthTinting
|
|
Tint blocks a color according to their depth (height) from bedrock. Useful
|
|
mainly for cave renders.
|
|
|
|
Lighting
|
|
Applies lighting to each block.
|
|
|
|
**Options**
|
|
|
|
strength
|
|
how dark to make the shadows. from 0.0 to 1.0. Default: 1.0
|
|
|
|
night
|
|
whether to use nighttime skylight settings. Default: False
|
|
|
|
color
|
|
whether to use colored light. Default: False
|
|
|
|
SmoothLighting
|
|
Applies smooth lighting to each block.
|
|
|
|
**Options**
|
|
|
|
(same as Lighting)
|
|
|
|
ClearBase
|
|
Forces the background to be transparent. Use this in place of Base
|
|
for rendering pure overlays.
|
|
|
|
.. warning::
|
|
|
|
Overlays are currently not functional in this branch of code. We are
|
|
working on them. Please inquire in :ref:`IRC<help>` for more information.
|
|
|
|
SpawnOverlay
|
|
Color the map red in areas where monsters can spawn. Either use
|
|
this on top of other modes, or on top of ClearBase to create a
|
|
pure overlay.
|
|
|
|
MineralOverlay
|
|
Color the map according to what minerals can be found
|
|
underneath. Either use this on top of other modes, or on top of
|
|
ClearBase to create a pure overlay.
|
|
|
|
**Options**
|
|
|
|
minerals
|
|
A list of (blockid, (r, g, b)) tuples to use as colors. If not
|
|
provided, a default list of common minerals is used.
|
|
|
|
Defining Custom Rendermodes
|
|
---------------------------
|
|
Each rendermode primitive listed above is a Python *class* that is automatically
|
|
imported in the context of the config file (They come from
|
|
overviewer_core.rendermodes). To define your own rendermode, simply define a
|
|
list of rendermode primitive *objects* like so::
|
|
|
|
my_rendermode = [Base(), EdgeLines(), SmoothLighting()]
|
|
|
|
If you want to specify any options, they go as parameters to the rendermode
|
|
primitive object's constructor::
|
|
|
|
my_rendermode = [Base(), EdgeLines(opacity=0.2),
|
|
SmoothLighting(strength=0.5, color=True)]
|
|
|
|
Then you can use your new rendermode in your render definitions::
|
|
|
|
render["survivalday"] = {
|
|
"world": "survival",
|
|
"title": "Survival Daytime",
|
|
"rendermode": my_rendermode,
|
|
"dimension": "overworld",
|
|
}
|
|
|
|
Note the lack of quotes around ``my_rendermode``. This is necessary since you
|
|
are referencing the previously defined list, not one of the built-in
|
|
rendermodes.
|
|
|
|
Built-in Rendermodes
|
|
--------------------
|
|
The built-in rendermodes are nothing but pre-defined lists of rendermode
|
|
primitives for your convenience. Here are their definitions::
|
|
|
|
normal = [Base(), EdgeLines()]
|
|
lighting = [Base(), EdgeLines(), Lighting()]
|
|
smooth_lighting = [Base(), EdgeLines(), SmoothLighting()]
|
|
night = [Base(), EdgeLines(), Lighting(night=True)]
|
|
smooth_night = [Base(), EdgeLines(), SmoothLighting(night=True)]
|
|
nether = [Base(), EdgeLines(), Nether()]
|
|
nether_lighting = [Base(), EdgeLines(), Nether(), Lighting()]
|
|
nether_smooth_lighting = [Base(), EdgeLines(), Nether(), SmoothLighting()]
|
|
cave = [Base(), EdgeLines(), Cave(), DepthTinting()]
|