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 =============