471 lines
15 KiB
ReStructuredText
471 lines
15 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"
|
|
|
|
render["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 a world rendered with a
|
|
set of options. If you have more than one, when viewing the maps, you will
|
|
get a dropdown box to choose which map you want to look at.
|
|
|
|
You can render the same world multiple times with different options, or
|
|
render multiple worlds.
|
|
|
|
.. 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["survivalspawnoverlay"] = {
|
|
"world": "survival",
|
|
"title": "Spawn Overlay",
|
|
"rendermode": spawn_overlay,
|
|
"dimension": "overworld",
|
|
"overlay": ["survivalday", "survivalnight"],
|
|
}
|
|
|
|
renders["creative"] = {
|
|
"world": "creative",
|
|
"title": "Creative",
|
|
"rendermode": smooth_lighting,
|
|
"dimension": "overworld",
|
|
}
|
|
|
|
outputdir = "/home/username/mcmap"
|
|
textures = "/home/username/my_texture_pack.zip"
|
|
|
|
This config defines four maps for render, and one overlay. Two of them are of
|
|
the survival world's overworld, one is for the survival's nether, and one is for
|
|
a creative world. The overlay is the "spawn_overlay" (which highlights areas
|
|
that are dark enough for monsters to spawn) and it will be available when
|
|
viewing the survivalday and survivalnight maps.
|
|
|
|
Notice here we explicitly set the dimension property on each render. If
|
|
dimension is not specified, the default or overworld dimension is used.
|
|
|
|
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 ``textures`` option. This specifies a texture
|
|
pack to use for the rendering.
|
|
|
|
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**
|
|
|
|
``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"
|
|
|
|
**Default:** ``"overworld"``
|
|
|
|
``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.
|
|
|
|
``"nether_lighting"``
|
|
Similar to "nether" but with blocky lighting.
|
|
|
|
``"nether_smooth_lighting"``
|
|
Similar to "nether" but with smooth lighting.
|
|
|
|
Technical note: The actual object type for this option is a list of
|
|
*rendermode primitive* objects. See :ref:`customrendermodes` for more
|
|
information.
|
|
|
|
**Default:** ``"normal"``
|
|
|
|
``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.
|
|
|
|
.. _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: 127
|
|
|
|
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)
|
|
|
|
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",
|
|
}
|
|
|
|
|
|
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()]
|