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()] 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 =============