diff --git a/building.rst b/building.rst index d0d83ff..c5c1790 100644 --- a/building.rst +++ b/building.rst @@ -112,6 +112,8 @@ The following script (copied into your MCO source directory) should handle every # build MCO C_INCLUDE_PATH="`pwd`/Imaging-1.1.7/libImaging" python ./setup.py build +.. _centos: + CentOS ------ Since CentOS has an older version of Python (2.4), there are some difficulties diff --git a/design/designdoc.rst b/design/designdoc.rst index 17eac0f..d94391e 100644 --- a/design/designdoc.rst +++ b/design/designdoc.rst @@ -15,6 +15,8 @@ Overviewer development. So let's get started! +.. contents:: + Background Info =============== The Overviewer's task is to take Minecraft worlds and render them into a set of tiles that can be displayed with a Google Maps interface. @@ -191,6 +193,9 @@ This is done at the end of :func:`textures._build_block` .. image:: pixelfix.png :alt: The 6 pixels manually added to each cube. +Other Cube Types +---------------- + Chunk Rendering =============== .. This goes over the rendering of a chunk diff --git a/design/screenshot.png b/design/screenshot.png new file mode 100644 index 0000000..953b50e Binary files /dev/null and b/design/screenshot.png differ diff --git a/faq.rst b/faq.rst new file mode 100644 index 0000000..ab555a0 --- /dev/null +++ b/faq.rst @@ -0,0 +1,22 @@ +========================== +Frequently Asked Questions +========================== + +**The full map doesn't display even when fully zoomed out!** + Are you using the `-z` or `--zoom` option on your commandline or in + settings.py? If so, try removing it, or increasing the value you set. It's + quite likely you don't need it at all. + +**You've added a few feature, but it's not showing up on my map!** + Some new features will only show up in newly-rendered areas. Use the + `--forcerender` option to update the entire map. + +**How do I use this on CentOS 5?** + CentOS 5 comes with Python 2.4, but the Overviewer needs 2.6 or higher. See + the special instructions at :ref:ref:`centos` + +**The background color of the map is black, and I don't like it!** + You can change this by using the ``--bg-color`` command line option, or + ``bg_color`` in settings.py. See the `Options `_ page for more + details. + diff --git a/index.rst b/index.rst index 3653e77..fb5e7c0 100644 --- a/index.rst +++ b/index.rst @@ -54,6 +54,8 @@ Documentation Contents building installing running + options + faq design/designdoc diff --git a/options.rst b/options.rst new file mode 100644 index 0000000..2d21a58 --- /dev/null +++ b/options.rst @@ -0,0 +1,340 @@ +======= +Options +======= + +.. contents:: + :local: + +Command line options +==================== + +.. cmdoption:: -h, --help + + Shows the list of options and exits + +.. cmdoption:: --advanced-help + + Display help - including advanced options + +Useful Options +-------------- +.. cmdoption:: --rendermodes=MODE1[,MODE2,...] + + Use this option to specify which render mode to use, such as lighting or + night. Use --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. + + See the `Render Modes`_ section for more information. + +.. cmdoption:: --list-rendermodes + + List the available render modes, and a short description of each. + +.. cmdoption:: --north-direction=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. + +.. cmdoption:: --settings=PATH + + Use this option to load settings from a file. For more information see the + `Settings File`_ section below. + +Less Useful Options +------------------- + +.. cmdoption:: -p PROCS, --processes=PROCS + + Adding the "-p" option will utilize more cores during processing. This + can speed up rendering quite a bit. The default is set to the same + number of cores in your computer, but you can adjust it. + + Example to run 5 worker processes in parallel:: + + python overviewer.py -p 5 + +.. cmdoption:: -d, --delete + + This option changes the mode of execution. No tiles are rendered, and + instead, files are deleted. + + *Note*: Currently only the overviewer.dat file is deleted when you run with + this option + +.. 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. + +.. cmdoption:: --regionlist=regionlist + + Use this option to specify manually a list of regions to consider for + updating. Without this option, every chunk in every region is checked for + update and if necessary, re-rendered. If this option points to a file + containing, 1 per line, the path to a region data file, then only those + in the list will 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! + + + +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 --settings +command line option. + +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. + +Here's a (possibly incomplete) list of available settings, which are available +in settings.py. Note that you can also set command-line options in a similar +way. + +imgformat=FORMAT + Set the output image format used for the tiles. The default is 'png', + but 'jpg' is also supported. + +zoom=ZOOM + The Overviewer by default will detect how many zoom levels are required + to show your entire map. This option sets it manually. + + *You do not normally need to set this option!* + + This is equivalent to setting the dimensions of the highest zoom level. It + does not actually change how the map is rendered, but rather *how much of + the map is rendered.* Setting this option too low *will crop your map.* + (Calling this option "zoom" may be a bit misleading, I know) + + 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. + + Remember that each additional zoom level adds 4 times as many tiles as + the last. This can add up fast, zoom level 10 has over a million tiles. + Tiles with no content will not be rendered, but they still take a small + amount of time to process. + +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. + + This function should accept one argument: a QuadtreeGen object. + +web_assets_path + This option lets you provide alternative web assets to use when + rendering. The contents of this folder will be copied into the output folder + during render, and will overwrite any default files already copied by + Overviewer. See the web_assets folder included with Overviewer for the + default assets. + +textures_path + This is like web_assets_path, but instead it provides an alternative texture + source. Overviewer looks in here for terrain.png and other textures before + it looks anywhere else. + +north_direction + Specifies which corner of the screen north will point to. + Valid options are: lower-left, upper-left, upper-right, lower-right. + +Render Modes +============ + +.. _rendermode-options: https://github.com/agrif/Minecraft-Overviewer/tree/rendermode-options + +Rendermode options are a new way of changing how existing render modes +work, by passing in values at startup. For example, you can change how +dark the 'night' mode is, or enable lighting in 'cave' mode. + +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 + + * 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 *settings.py* 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. + +Defining Custom Rendermodes +--------------------------- + +Sometimes, you want to render two map layers with the same mode, but with two +different sets of options. For example, you way want to render a cave mode with +depth tinting, and another cave mode with lighting and no depth tinting. In this +case, you will want to define a 'custom' render mode that inherits from 'cave' +and uses the options you want. For example:: + + custom_rendermodes = { + 'cave-lighting': { + 'parent': 'cave', + 'label': 'Lit Cave', + 'description': 'cave mode, with lighting', + 'options': { + 'depth_tinting': False, + 'lighting': True, + } + }, + } + + rendermode = ['cave', 'cave-lighting'] + +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. + +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**. + +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}, + } diff --git a/running.rst b/running.rst index 70a400f..8c9904d 100644 --- a/running.rst +++ b/running.rst @@ -5,20 +5,131 @@ Running the Overviewer Rendering your First Map ======================== -Overviewer is a command-line application, and so it needs to be run from the command line. If you installed Overviewer from a package manager, the command is ``overviewer.py``. If you downloaded it manually, open a terminal window and navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds, the command is ``overviewer.exe``. For other systems, it's ``./overviewer.py``. +Overviewer is a command-line application, and so it needs to be run from the +command line. If you installed Overviewer from a package manager, the command is +``overviewer.py``. If you downloaded it manually, open a terminal window and +navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds, +the command is ``overviewer.exe``. For other systems, it's ``overviewer.py``. -To generate your map, run:: +The basic usage for Windows is:: - overviewer.exe WorldName path\to\output\ # on windows, or - ./overviewer.py WorldName path/to/output/ # on other systems + overviewer.exe [options] -where ``WorldName`` is the name of the world you want to render, and -``path/to/output`` is the place where you want to store the rendered world. The -first render can take a while, depending on the size of your world. You can, if -you want to, provide a path to the world you want to render, instead of -providing a world name and having Overviewer auto-discover the world path. +And similarly for other systems:: -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! + overviewer.py [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 rerender only what's needed. +**World** + World can be one of several things. + 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. + +**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 `Options `_ page for a list of options you can + specify. + +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:: + + overviewer.exe c:\server\world c:\mcmap + +For Mac or Linux builds from source, you would run something like this with the +current directory in the top level of the source tree:: + + ./overviewer.py /opt/minecraft/server/world /opt/minecraft/mcmap + +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! + +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 rerender only what's needed. + +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. + +You have several options: + +* 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'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:: + + 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. + +* You can put a terrain.png file anywhere you want and point to its location + with the ``--textures-path`` option. This should point to the directory containing + the terrain.png, not to the file itself. + +Note: the ``--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` + +Running on a Live Map +===================== +If you're running the Overviewer on a live server or a single player world +that's running, read this section. + +Minecraft doesn't really like it when other programs go snooping around in a +live world, so running Overviewer on a live world usually creates a few errors, +usually "corrupt chunk" errors. You *can* do this, but it's not a supported way +of running Overviewer. + +To get around this, you can copy your live world somewhere else, and render the +copied world instead. If you're already making backups of your world, you can +use the backups to make the render. Many people even use their backups to run +Overviewer on a different machine than the one running the Minecraft server. + +There used to be a few things to be careful about, but right now there's only +one important thing left. + +Preserving Modification Times +----------------------------- + +The important thing to be careful about when copying world files to another +location is file modification times, which Overviewer uses to figure out what +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.