==================== Settings and Options ==================== Overviewer settings can be set in two places, on the command line when you run the overviewer, or in a settings file. You specify a settings file to use with the :option:`--settings` command line option. .. note:: Any command line option can optionally be set in the settings file. However, there are some settings that can only be set in the settings file. .. note:: Some options go by different names on the command line and the settings file. Those are noted in bold below. The first section of this document covers command line options. The second part covers the more advanced ways of customizing The Overviewer using settings files. .. contents:: :local: Command line options ==================== All Options: ======================================== ================================== :option:`--advanced-help` Print out help on all options :option:`--bg-color` Change the background of the map :option:`--changelist` Outputs a list of changed tiles :option:`--changelist-format` Sets the format of the change list :option:`--check-terrain` Output information on the textures :option:`--display-config` Displays the configuration :option:`--forcerender` Forces every tile to render :option:`-h`, :option:`--help <-h>` Prints help on the basic options :option:`--imgformat` Choose from png or jpg output :option:`--imgquality` Change jpg output quality :option:`--list-rendermodes` List the installed rendermodes :option:`--no-signs` Do not place signs on the map :option:`--north-direction` Choose which direction is north :option:`--optimize-img` Run pngcrush on outputted tiles :option:`-p`, :option:`--processes <-p>` Choose the number of worker processes :option:`-q`, :option:`--quiet <-q>` Print less output :option:`--regionlist` Only render specified areas of a map :option:`--rendermodes` Choose which rendermode(s) to use :option:`--settings` Specify an external settings file :option:`--skip-js` Do not output generated javascript files :option:`--stochastic-render` Re-render parts of the map randomly :option:`--textures-path` Specify custom textures to use :option:`-v`, :option:`--verbose <-v>` Print more output :option:`-V`, :option:`--version <-V>` Print out the version :option:`--web-assets-path` Specify alternate web assets :option:`-z`, :option:`--zoom <-z>` Do not touch ======================================== ================================== Help Options ------------ .. cmdoption:: -h, --help Shows the list of options and exits .. cmdoption:: --advanced-help Display help - including advanced options Useful Options -------------- .. cmdoption:: --settings Use this option to load settings from a file. For more information see the `Settings File`_ section below. **Not available in settings file (duh)** .. cmdoption:: --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. .. note:: We define cardinal directions by the sun in game; the sun rises in the East and sets in the West. **Settings file:** Option name: ``north_direction`` Format: One of the above strings. .. cmdoption:: --rendermodes [,MODE2,...] Use this option to specify which render mode to use, such as lighting or night. Use :option:`--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. **More information is available in the** :ref:`render-modes` **section of the docs** List of built-in render-modes: * normal * lighting * smooth-lighting * smooth-night * night * cave Built-in overlays: * spawn * mineral .. note:: You can create custom rendermodes too! See the :ref:`custom-rendermodes` section for more information! Example:: ./overviewer.py --rendermodes=lighting,night /opt/server/world /opt/map **Settings file:** Option name: ``rendermode`` **Note the lack of an s** Format: a list of strings. Default: only render the normal mode .. cmdoption:: --list-rendermodes List the available render modes, and a short description of each, and exit. **Not available in settings file** Less Useful Options ------------------- .. cmdoption:: --bg-color Configures the background color for the Google Map output. Specify in #RRGGBB format. **Settings file:** Option name: ``bg_color`` Format: A string in the above format. Default: "#1A1A1A" .. cmdoption:: --changelist Outputs a list of changed tiles to the named file. If the file doesn't exist, it is created. If it does exist, its contents are overwritten. This could be useful for example in conjunction with a script to upload only changed tiles to your web server. **Settings file:** Option name: ``changelist`` Format: String (path plus filename) Default: Not specified (no changelist outputted) .. cmdoption:: --changelist-format Chooses absolute or relative paths for the output with the :option:`--changelist` option. Valid values for format are "relative" or "absolute". **Settings file:** Option name: ``changelist_format`` Format: A string (one of the above) Default: "relative" .. cmdoption:: --check-terrain When this option appears on the command line, Overviewer prints the location and hash of the terrain.png it will use, and then exits. This is useful for debugging terrain.png path problems, especially with :option:`--textures-path`. Use this to see what terrain.png your current setup has selected. See the :ref:`installing-textures` section for an example. **Not available in settings file** .. cmdoption:: --display-config Display the configuration parameters and exit. Doesn't render the map. This is useful to help validate a configuration setup. **Not available in settings file** .. 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. This is useful if you change texture packs and want to re-render everything in the new textures, or if you're changing the :option:`--north-direction`. **Settings file:** Option name: ``forcerender`` Format: A boolean Default: False .. cmdoption:: --imgformat Specifies the output format for the tiles. Currently supported options are "png" or "jpg". **Settings file:** Option name: ``imgformat`` Format: A string, either "png" or "jpg" Default: "png" .. cmdoption:: --imgquality When using ":option:`--imgformat` jpg", this specifies the jpeg quality parameter. This can help save disk space for larger maps. For saving space with pngs, see :option:`--optimize-img` **Settings file:** Option name: ``imgquality`` Format: An integer 1-100 Default: 95 .. cmdoption:: --no-signs Doesn't output signs to markers.js. This has the effect of disabling signs on your map. **Settings file:** Option name: ``nosigns`` Format: Boolean Default: False .. cmdoption:: --optimize-img When using ":option:`--imgformat` png" (the default), this performs file size optimizations on the output. The level parameter is an integer specifying one of the following: 1. Run pngcrush on all tiles 2. Run pngcrush plus advdef on all tiles 3. Run pngcrush plus advdef with more aggressive settings. These options may double the time or worse it takes to render your map, and can be expected to give around 19-23% reduction in file size. These options also require the corresponding program(s) installed and in your system path ($PATH or %PATH% environment variable) **Settings file:** Option name: ``optimizeimg`` Format: an integer Default: not set (no optimization) .. cmdoption:: -p , --processes On multi-cored or multi-processor machines, The Overviewer will perform its work on *all* cores by default. If you want to manually specify how many workers to run in parallel, use this option. Example to run 5 worker processes in parallel:: overviewer.py -p 5 **Settings file:** Option name: ``procs`` Format: an integer. Default: ``multiprocessing.cpu_count()`` .. cmdoption:: -q, --quiet Prints less output. You can specify this multiple times. **Settings file:** Option name: ``quiet`` Format: an integer Default: 0 .. cmdoption:: --regionlist Use this option to specify manually a list of regions to consider for updating. In normal operation, every chunk in every region is checked for update and if necessary, re-rendered. With this option, only the chunks in the specified regions are checked. This option should name a file containing, 1 per line, the path to the region files to 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! .. warning:: This option may currently be broken. Use at your own risk! Patches welcome! **Settings file:** Option name: ``regionlist`` Format: A string representing the region list file. Default: Scan all region files. .. note:: See sample.settings.py for an example on how to build a region list file. .. cmdoption:: --skip-js Skip the generation and output of markers.js and regions.js to the output directory. **Settings file:** Option name: ``skipjs`` Format: Boolean Default: False .. cmdoption:: --stochastic-render Provides a probability that a non-updated tile will be re-rendered anyway. Use this if there's a new rendering feature you want to use or if there's a part of your map you need re-rendered, but you don't want to re-render the entire map at once using :option:`--forcerender`. In other words, setting this to e.g. ``0.7`` will force 70% of your map to be re-rendered. The portion of your map that gets re-rendered is random. The idea is that, after a few renders with this setting, most all of your map will eventually get re-rendered. It spreads the work of a :option:`--forcerender` out over several runs. **Settings file:** Option name: ``stochastic_render`` Format: a floating-point number in the range 0.0 to 1.0 Default: 0.0 .. cmdoption:: --textures-path Use this option to specify an alternate terrain.png (and other textures) to when rendering a world. ``path`` specifies the **containing directory** of terrain.png. Alternately, ``path`` can specify a zip file containing the textures, such as a texture pack. The Overviewer will look for terrain.png in the following places in this order: path specified by this option, the program's directory, the overviewer_core/data/textures directory within the source directory, the default textures that come with Minecraft if it's installed. .. note:: If you installed Overviewer from the Debian package or chose to install the overviewer from source (``python setup.py install``), then there isn't a source directory; this option may be necessary to specify non-default textures. If you're having trouble getting The Overviewer to recognize your textures, see the :option:`--check-terrain` option. Also see the :ref:`installing-textures` section of the documentation. **Settings file:** Option name: ``textures_path`` Format: A string (path to a dir with a terrain.png) Default: None .. cmdoption:: -v, --verbose Prints more output. You can specify this multiple times. Specifying this option also has the effect of changing the output format to a more verbose one with additional information, in addition to outputting more lines. If you specify both :option:`-v` and :option:`-q`, you can get the more verbose line without additional output from debug lines. **Settings file:** Option name: ``verbose`` Format: an integer Default: 0 .. cmdoption:: -V, --version Displays the version information and exits **Not available in settings file** .. cmdoption:: --web-assets-path When The Overviewer runs, it copies the files from the web_assets directory to the destination directory. If you wish to override a file with your own, for example, to make changes, you may put your modified copies in your own directory and specify the directory with this option. Files in the folder specified by ``path`` will override files from the web_assets directory, letting you customize the files. If you're running from source and are comfortable merging with Git, it may be better to edit the web_assets directly. If we update one of the files, you can use Git to merge in our changes with yours. If, however, you do not like Git, and don't mind having to manually update or merge web assets (or don't care for web asset updates at all), then copy all the web assets to a directory of your own and use this option. See the :ref:`web-assets` section for more info on customizing your web assets. **Settings file:** Option name: ``web_assets_path`` Format: A string (path to a directory to use for custom web assets) Default: Not set (no additional web assets used) .. cmdoption:: -z , --zoom .. warning:: This option does not do what you think it does. You almost certainly do not want to set this. This option effectively sets *how far the map can be zoomed out*. The Overviewer will by default determine how many *zoom levels* your map needs to show the entire map. This option overrides that; setting this option lower than automatically determined will *crop your map* and parts will be cut off. (We acknowledge that name zoom is misleading) 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. **If you are getting a "your map is waaaay too big" error** then this option may help you render your map. That error is unlikely in naturally generated worlds, but some really giant worlds may still cross the threshold. The Overviewer will refuse to automatically render maps that require zoom level 15 and above, so if you get this error, try specifying ``--zoom 15``. If your map is still cut off around the edges, increase the zoom level by 1 and try again. **Settings file:** Option name: ``zoom`` Format: An integer. Default: Automatically calculated from the world size. .. note:: There are **more settings** that cannot be specified on the command line. See the section below! .. _settings-file: 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 :option:`--settings` command line option when you run the Overviewer. 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. It contains a number of examples to get you started, but you almost certainly don't want to use it as-is. You can specify *any of the above* options in your settings file *in addition to the ones documented below*. For the command-line options, find its listed "Option name" which is the Python identifier you will use. For example, if you wanted to specify :option:`--bg-color`, you would look and see its option name is "bg_color" (note the underscore) and you would put this line in your settings file:: bg_color = "#000000" Settings file options --------------------- In addition to the `Command line options`_, you can specify these options. .. describe:: 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. Set this identifier to a Python *function object* to be called. This function should accept one argument: a :class:`overviewer_core.googlemap.MapGen` object. .. warning:: Currently, this option only works if the :option:`--skip-js` option is set .. describe:: rendermode_options Different rendermodes have different options. This option is a dictionary that maps rendermode names to option dictionaries. See the `Render Modes`_ section for relevant options to the render modes. .. describe:: custom_rendermodes You can also specify your own custom rendermodes with this option. This is a dictionary mapping your rendermode name to a dictionary of parameters to use. See the `Defining Custom Rendermodes`_ section for more information. .. _render-modes: Render Modes ============ A rendermode is a unique way of rendering a Minecraft map. The normal render mode was the original, and we've since added a render mode with proper lighting, a rendermode for nighttime lighting, and we have a rendermode that only shows caves. Beyond that, there are also render "overlays" that can be toggled on or off, overlaying a proper rendering. These can be used to show where minerals are and such. Specify your rendermodes with :option:`--rendermodes`. You can get a list of all rendermodes installed with :option:`--list-rendermodes`. 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 * smooth-lighting * smooth-night * 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 your settings file 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. 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) * **nether** - enables nether-mode by removing the top set of contiguous in each column (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**. .. _custom-rendermodes: Defining Custom Rendermodes --------------------------- Custom rendermodes allow you to take an existing rendermode, and define a new one with a particular set of options. You can, for example, render two map layers with the same mode, but with two different sets of options. You can do this by defining a custom rendermode in your :ref:`settings-file` .. note:: You *must* use a :ref:`settings file ` in order to define custom rendermodes. Let's say you want to render a cave mode with depth tinting, and another cave mode with lighting and no depth tinting. In this case, you can to define a custom render mode that inherits from 'cave' and uses the options you want. Like this:: custom_rendermodes = { 'cave-lighting': { 'parent': 'cave', 'label': 'Lit Cave', 'description': 'cave mode, with lighting', 'options': { 'depth_tinting': False, 'lighting': True, } }, } rendermode = ['cave', 'cave-lighting'] These lines would go in your settings file as written. 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. 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}, } .. _web-assets: Customizing Web Assets ====================== The web assets are the static html files stored in overviewer_core/data/web_assets that are copied to the destination directory when you run the Overviewer. Some of these files are actually templates and certain parameters are set at render time depending on various factors. Others are just straight up copied. You should not typically need to edit the files in here, but if you like customizing things or want to edit them for whatever reason, here's two ways: 1. If you're not afraid of Git and you're running the Overviewer from a Git clone of our repository, you can edit the files in overviewer_core/data/web_assets directly. When you pull in changes from us, you will have to merge, but using Git should make this relatively painless. 2. Otherwise, the recommended way is to use the :option:`--web-assets-path` option. Use this option and point it to a directory of customized web assets to copy. Files from the original web_assets directory are still copied, but any files in the custom web assets directory will override the originals. This way you can customize a few files and leave the rest alone. The downside is, if you want to upgrade you will have to merge in your changes with any of our changes manually. To avoid merging entirely, just copy *all* the web assets to your custom web assets folder. You'll keep the old version of all files for eternity, missing out on new features we may add, but you won't have to deal with merges at all.