of course I fogot to add this file
This commit is contained in:
Andrew Brown
370
docs/config.rst
Normal file
370
docs/config.rst
Normal file
@@ -0,0 +1,370 @@
|
||||
.. _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 --configfile=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 ``render`` 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"
|
||||
|
||||
render["survivalday"] = {
|
||||
"world": "survival",
|
||||
"title": "Survival Daytime",
|
||||
"rendermode": smooth_lighting,
|
||||
"dimension": "overworld",
|
||||
}
|
||||
|
||||
render["survivalnight"] = {
|
||||
"world": "survival",
|
||||
"title": "Survival Daytime",
|
||||
"rendermode": smooth_night,
|
||||
"dimension": "overworld",
|
||||
}
|
||||
|
||||
render["survivalnether"] = {
|
||||
"world": "survival",
|
||||
"title": "Survival Nether",
|
||||
"rendermode": nether_smooth_lighting,
|
||||
"dimension": "nether",
|
||||
}
|
||||
|
||||
render["survivalspawnoverlay"] = {
|
||||
"world": "survival",
|
||||
"title": "Spawn Overlay",
|
||||
"rendermode": spawn_overlay,
|
||||
"dimension": "overworld",
|
||||
"overlay": ["survivalday", "survivalnight"],
|
||||
}
|
||||
|
||||
render["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).
|
||||
|
||||
After the config file is evaluated, the ``worlds`` and ``render`` dictionaries,
|
||||
along with other global level configuration options, are used to configure The
|
||||
Overviewer's rendering.
|
||||
|
||||
``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 ``render``
|
||||
dictionary.
|
||||
|
||||
Values are paths to worlds (directories with a level.dat)
|
||||
|
||||
``render``
|
||||
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. 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 below.
|
||||
|
||||
Render Dictonary Keys
|
||||
---------------------
|
||||
|
||||
``world``
|
||||
Specifies which world this render corresponds to. Its value should be a
|
||||
string from the appropriate key in the worlds dictionary.
|
||||
|
||||
**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"**
|
||||
|
||||
``title``
|
||||
This is the display name used in the user interface. Set this to whatever
|
||||
you want to see under the dropdown box for map selection.
|
||||
|
||||
**Deafult: Worldname - Dimension**
|
||||
|
||||
``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.
|
||||
|
||||
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**
|
||||
|
||||
Global Options
|
||||
--------------
|
||||
These values are set directly in the config file. Example::
|
||||
|
||||
texture_pack = "/home/username/minecraft/my_texture_pack.zip"
|
||||
|
||||
.. _option_texture_pack:
|
||||
|
||||
``texture_pack = "<texture pack path>"``
|
||||
This is a string indicating the path to the texture pack to use for
|
||||
rendering.
|
||||
|
||||
TODO: More to come here
|
||||
|
||||
.. _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
|
||||
Fades out blocks 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 constructors to the rendermode
|
||||
primitive objects::
|
||||
|
||||
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()]
|
||||
Reference in New Issue
Block a user