From 8c71c802d2a2267f3d32814f2d7f35210a721e52 Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Sun, 22 Jan 2012 01:26:04 -0500 Subject: [PATCH 1/2] docs update to Running page and new page Config. Removed Options. Added all about the new config file format. Needs checking for accuracy. Also need to update the faq and other sections of the docs now that the options page is gone. --- docs/index.rst | 2 +- docs/options.rst | 789 ----------------------------------------------- docs/running.rst | 200 ++++++++---- 3 files changed, 133 insertions(+), 858 deletions(-) delete mode 100644 docs/options.rst diff --git a/docs/index.rst b/docs/index.rst index 5b65e89..9aab495 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -142,7 +142,7 @@ Documentation Contents installing building running - options + config faq design/designdoc diff --git a/docs/options.rst b/docs/options.rst deleted file mode 100644 index 4c752e4..0000000 --- a/docs/options.rst +++ /dev/null @@ -1,789 +0,0 @@ -==================== -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, which is typically generated - from the signs in your world. This is useful if you want to generate your - own and don't want this one getting in the way. - - **Settings file:** - Option name: ``skipjs`` - - Format: Boolean - - Default: False - -.. cmdoption:: --stochastic-render - - Provides a probability that a non-updated tile will be rerendered - anyway. Use this if there's a new rendering feature you want to - use, but you don't want to rerender the entire map at once. - - **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) - -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. diff --git a/docs/running.rst b/docs/running.rst index 8429ff3..a65db98 100644 --- a/docs/running.rst +++ b/docs/running.rst @@ -11,32 +11,87 @@ command line. If you installed Overviewer from a package manager, the command is navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds, the command is ``overviewer.exe``. For other systems, it's ``overviewer.py``. -The basic usage for Windows is:: +What follows in this section is a few examples to get you started. For full +usage, see the :ref:`usage` section. - overviewer.exe [options] +So, let's render your first map! Let's say you want to render your single player +world called "My World". Let's also say you want to save it c:\mcmap. You +would type into your command prompt the following:: -And similarly for other systems:: + overviewer.exe "My World" c:\mcmap - overviewer.py [options] +If you're on Linux or a Mac, you could do something like one of the following:: -**World** - World can be one of several things. + overviewer.py "My World" /home/username/mcmap - 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. - 3. If your single-player world name is in the format "World #" (e.g. "World - 1"), you can just specify the number. +or -**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 :doc:`options` page for a list of options you can - specify. + overviewer.py "My World" /Users/username/mcmap + +Those will look for a single player world by that name. You can also specify the +path to the world you want to render. This is useful for rendering servers. + +Let's say you have a server installed in /home/username/mcserver. This command +will render the default dimension (in the case of Bukkit multiworld servers, the +default world is used. You can also specify the directory to the specific world +you want to render). + +:: + + overviewer.py /home/username/mcserver /home/username/mcmap + +After you enter one of the commands, The Overviewer should start rendering your +map. 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 The Overviewer will +automatically re-render only what's needed. + +Specifying a different rendermode +--------------------------------- +There are a few built-in rendermodes for you to choose from. Each will render +your map differently. For example, if you want smooth lighting (which looks +really good), you would add ``--rendermodes=smooth-lighting`` to your command. +e.g. + +:: + + overviewer.py --rendermodes=smooth-lighting /home/username/mcserver /home/username/mcmap + +The rendermodes you have to choose from are: + +* normal (the default) +* lighting +* smooth-lighting +* cave + +You can specify more than one. Just separate them with a comma! + +.. _usage: + +Usage +===== + +For this section, we assume the executable is ``overviewer.py``. Replace that +with ``overviewer.exe`` for windows. + +Overviewer usage:: + + overviewer.py [--rendermodes=...] [options] + overviewer.py --config= [options] + +The first form is for basic or quick renderings without having to create a +config file. It is intentionally limited because the amount of configuration was +becoming unmanageable for the command line. + +The second, preferred usage involves creating a configuration file which +specifies all the options including what to render, where to place the output, +and all the settings. See :ref:`configfile` for details on that. 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:: @@ -50,66 +105,75 @@ current directory in the top level of the source tree:: 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! +.. _options: -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 re-render only what's needed. +Options +------- + +These options change the way the render works, and are intended to be things you +only have to use once-in-a-while. + +.. cmdoption:: --forcerender + + Forces The Overviewer to re-render every tile regardless of whether it + thinks it needs updating or not. This is similar to deleting your output + directory and rendering from scratch. + + This is the default mode for first-time renders. This option overrides + :option:`--check-tiles` and :option:`--no-tile-checks` + +.. cmdoption:: --check-tiles + + Forces The Overviewer to check each tile on disk and compare its + modification time to the modification time of the part of the world that + tile renders. This is slightly slower than the default, but can be useful if + there are some tiles that somehow got skipped. + + This option is the default when The Overviewer detects the last render was + interrupted midway through. This option overrides :option:`--forcerender` + and :option:`--no-tile-checks` + +.. cmdoption:: --no-tile-checks + + With this option, The Overviewer will not do any checking of tiles on disk + to determine what tiles need updating. Instead, it will look at the time + that the last render was performed, and render parts of the map that were + changed since then. This is the fastest option, but could cause problems if + the clocks of the Minecraft server and the machine running The Overviewer + are not in sync. + + This option is the default unless the condition for :option:`--forcerender` + or :option:`--check-tiles` is in effect. This option overrides + :option:`--forcerender` and :option:`--check-tiles`. .. _installing-textures: 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. +If Overviewer is running on a machine with the Minecraft client installed, it +will automatically use the default textures from Minecraft. -You have several options: +If, however, you're running on a machine without the Minecraft client installed, +or if you want to use different textures, you will need to provide the textures +manually. This is common for servers. -* 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 want or need to provide your own textures, you have several options: - * 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:: +* 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, thinking the client is installed, 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/ + 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. + texture pack. If you've built the Overviewer from source or are using the + windows exe, place the file in the same directory as overviewer.py or + overviewer.exe. -* You can put a terrain.png file anywhere you want and point to its - location with the :option:`--textures-path` option. This should - point to the directory containing the terrain.png, not to the file - itself. - -* Alternately, you can download any texture pack ZIP you like and - point to this directly with :option:`--textures-path`. - -Note: the :option:`--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` +* Specify any terrain.png or texture pack you want with the + :ref:`texture_pack` option. Running on a Live Map ===================== @@ -138,9 +202,9 @@ 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. +GNU ``tar`` automatically handles modification times correctly. ``rsync -a +--delete`` will handle this correctly as well. If you use some other tool, +you'll have to figure out how to do this yourself. Biome Support ============= From 9e278a056807695d2e3df5a5864d9bd76431c53f Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Sun, 22 Jan 2012 01:28:15 -0500 Subject: [PATCH 2/2] of course I fogot to add this file --- docs/config.rst | 370 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 370 insertions(+) create mode 100644 docs/config.rst diff --git a/docs/config.rst b/docs/config.rst new file mode 100644 index 0000000..b1fdca0 --- /dev/null +++ b/docs/config.rst @@ -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 = ""`` + 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()]