commit c07cfb5d07e4716c2eceef8d3deb56a4590fca8b Author: Andrew Brown Date: Fri Sep 30 19:22:02 2011 -0400 docs repo started diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..e1e0086 --- /dev/null +++ b/Makefile @@ -0,0 +1,132 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +default: html + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Overviewer.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Overviewer.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Overviewer" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Overviewer" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/building.rst b/building.rst new file mode 100644 index 0000000..1cf84f2 --- /dev/null +++ b/building.rst @@ -0,0 +1,3 @@ +=================================== +Building the Overviewer from Source +=================================== diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..794c403 --- /dev/null +++ b/conf.py @@ -0,0 +1,216 @@ +# -*- coding: utf-8 -*- +# +# Overviewer documentation build configuration file, created by +# sphinx-quickstart on Thu Sep 22 10:19:03 2011. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Overviewer' +copyright = u'2011, Andrew Brown and Contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.3.0' +# The full version, including alpha/beta/rc tags. +release = '0.3.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Overviewerdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Overviewer.tex', u'Overviewer Documentation', + u'Andrew Brown and Contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'overviewer', u'Overviewer Documentation', + [u'Andrew Brown and Contributors'], 1) +] diff --git a/design/cube_parts.png b/design/cube_parts.png new file mode 100644 index 0000000..e33c971 Binary files /dev/null and b/design/cube_parts.png differ diff --git a/design/cube_parts.svg b/design/cube_parts.svg new file mode 100644 index 0000000..698ee28 --- /dev/null +++ b/design/cube_parts.svg @@ -0,0 +1,299 @@ + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 24 + 24 + + + + + + + + + + diff --git a/design/designdoc.rst b/design/designdoc.rst new file mode 100644 index 0000000..32b6840 --- /dev/null +++ b/design/designdoc.rst @@ -0,0 +1,226 @@ +==================== +Design Documentation +==================== +So you'd like a technical overview of how The Overviewer works, huh? You've come +to the right place! + +This document's scope does not cover the details of the code. The code is fairly +well commented and not difficult to understand. Instead, this document is +intended to give an explanation to how the Overviewer was designed and how all +the pieces fit together. Think of this document as commenting on how all the +high level pieces of the code work. + +This document is probably a good read to anyone that wants to get involved in +Overviewer development. + +So let's get started! + +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. + +A Minecraft world extends indefinitely along the two horizontal axes, and are +exactly 128 units high. Minecraft worlds are made of cubes, where each slot in +the world's grid has a type that determines what it is (grass, stone, ...). +This makes worlds relatively uncomplicated to render, the Overviewer simply +determines what cubes to draw and where. Since everything in Minecraft is +aligned to a strict grid, placement and rendering decisions are completely +deterministic and can be performed in an iterative fashon. + +The coordinate system for Minecraft has three axes. The X and Z axes are the +horizontal axes. They extend indefinitely towards both positive and negative +infinity. (There are practical limits, but no theoretical limits). The Y axis +extends from 0 to 127, which corresponds with the world height limit. Each +block in Minecraft has a coordinate address, e.g. the block at 15,78,-35 refers +to 15 along the X axis, -35 along the Z axis, and 78 units up from bedrock. + +The world is divided up into *chunks*. A chunk is a 16 by 16 area of the world +that extends from bedrock to sky. In other words, a 16,128,16 "chunk" of the +world. Chunks also have an address, but in only 2 dimensions. To find the which +chunk a block is in, simply divide its X and Z coordinates by 16 and take the +floor. + +Minecraft worlds are generated on-the-fly by the chunk. This means not all +chunks will exist. There is no pattern to chunk generation, the game simply +generates them as needed. + +Chunks are stored on-disk in region files. A Minecraft region is a "region" of +32 by 32 chunks. Regions have their own address, and for a particular chunk one +can find its region by dividing its coordinates by 32 and taking the floor. A +region may contain all 1024 of its chunks, or only a subset of them, since not +all chunks may exist. The absence of a region file indicates none of its chunks +exist. + +About the Rendering +=================== + +Minecraft worlds are rendered in an approximated Isometric projection +[#isomorphicref]_, or +what I call the "Sim City projection" [#isomorphicnote]_. In the original design, the projection +acts as if your eye is infinitely far away looking down at the world at a 45 +degree angle in the South-East direction (now, the world can be rendered at any +of the 4 oblique directions). + +.. [#isomorphicref] http://en.wikipedia.org/wiki/Isometric_projection +.. [#isomorphicnote] To be honest, I'm not entirely sure it's technically an isomorphic projection. There are a lot of very similar projections. + +In order to render a Minecraft world, there are a few steps that need to happen. +These steps are explained in detail in the next few sections. + +1. Render each block +2. Render the chunks from the blocks +3. Render the tiles of the map from the chunks +4. Shrink and combine the tiles for the other zoom levels + +Block Rendering +=============== +.. This section shows how each block is pre-rendered + +The first step is rendering the blocks from the textures. Each block is built +and cached in global variables of the :mod:`textures` module. + +Textures come in the size 16 by 16 [#f1]_. In order to render a cube out of +this, I apply an `affine transformation`_ to the texture in order to skew it to +the right shape. + +.. image:: texturecubing.png + :alt: A texture gets rendered into a cube + +.. [#f1] + Textures can come in other sizes and are re-sized so this section applies + just the same. + +.. _affine transformation: http://en.wikipedia.org/wiki/Affine_transformation + +The result is an image of a cube that is 24 by 24 pixels large. This particular +size for the cubes was chosen for an important reason: 24 is divisible by 2 and +by 4. This makes placement much easier. E.g. in order to draw two cubes that are +next to each other in the world, one are drawn exactly 12 pixels over and 6 +pixels down from the other. These kind of placement decisions all happen on +exact pixel boundaries. + +The transformation happens in two stages. First, the texture is transformed for +the top of the cube. Then the texture is transformed for the left side of the +cube, which is mirrored for the right side of the cube. + +Top Transformation +------------------ +The transformation from the top is a simple `affine transformation`_. It is +actually several affine transformations: a re-size, a rotation, and a scaling; +but since multiple affine transformations can be chained together simply by +multiplying the transformation matrices together, only one transformation is +actually done. + +This can be seen in the function :func:`textures.transform_image`. It takes +these steps: + +1. The texture is re-sized to 17 by 17 pixels. This is done because the diagonal + of a square with sides 17 is approximately 24, which is the target size for + the bounding box of the cube image. So when it's rotated, it will be the + correct width. + +2. The image is rotated 45 degrees about its center. + +3. The image is scaled on the vertical axis by a factor of 1/2. + +This produces an image of size 24 by 12 as seen in the following sequence. + +.. image:: texturetopsteps.png + :alt: The 4 steps for transforming a texture square into the top of the cube. + +The final image, shown below, becomes the top of the cube. + +.. image:: dirt_top.png + :alt: Top of dirt + +On the left is the top of the dirt block at actual size after the +transformation, the right is the same but blown up by a factor of 10 with no +interpolation to show the pixels. + +Side Transformation +------------------- +The texture square is transformed for the sides of the cube in +:func:`textures.transform_image_side`. This is another `affine transformation`_, +but this time only two transformations are done: a re-size and a shear. + +1. First the texture is re-sized to 12 by 12 pixels. This is half the width of + 24 so it will have the correct width after the shear. + +2. The 12 by 12 square is sheared by a factor of 1.5 in the Y direction, + producing an image that is bounded by a 12 by 18 pixel square. + +.. image:: texturesidesteps.png + :alt: Texture being sheared for the side of the cube. + +This image is simply flipped along the horizontal axis for the other visible +side of the cube. + +.. image:: dirt_side.png + :alt: The sides of the dirt block + +Again, the left are the two sides of the dirt block at actual size, the right is +scaled with no interpolation by a factor of 10 to show the pixels. + +An Entire Cube +-------------- +These three images, the top and two sides, are pasted into a single 24 by 24 +pixel image to get the cube, as shown. + +However, notice from the middle of the three images in the sequence below that +the images as transformed don't fit together exactly. There is some overlap when +put in the 24 by 24 box in which they must fit. + +.. image:: cube_parts.png + :alt: How the cube parts fit together + +There is one more complication. The cubes don't tessellate perfectly. This +diagram illustrates when a cube is positioned next to another. The lower cubes +are 18 pixels lower and 12 pixels to either side, which is half the width and +3/4 the height respectively. + +.. image:: tessellation.png + :alt: Cubes don't tessellate perfectly + +The solution is to manually touch up those 6 pixels. 3 pixels are added on the +upper left of each cube, 3 on the lower right. Therefore, they all line up +perfectly! + +This is done at the end of :func:`textures._build_block` + +.. image:: pixelfix.png + :alt: The 6 pixels manually added to each cube. + +Chunk Rendering +=============== +.. This goes over the rendering of a chunk + +Tile Rendering +============== +.. Covers the placement of chunk images on a tile + +Reading the Data Files +====================== +.. + Covers how to extract the blocks of each chunk from the region files. Also + covers the nbt file stuff. + +Image Composition +================= +.. + Covers the issues I had with PIL's image composition and why we needed + something fancier. + +Multiprocessing +=============== +.. + Covers how the Overviewer utilizes multiple processors to render faster + +Caching +======= +.. How the overviewer determines what needs to be rendered and what doesn't + +Lighting +======== + +Cave Mode +========= diff --git a/design/dirt_side.png b/design/dirt_side.png new file mode 100644 index 0000000..0634307 Binary files /dev/null and b/design/dirt_side.png differ diff --git a/design/dirt_top.png b/design/dirt_top.png new file mode 100644 index 0000000..118fc54 Binary files /dev/null and b/design/dirt_top.png differ diff --git a/design/pixelfix.png b/design/pixelfix.png new file mode 100644 index 0000000..228c1c5 Binary files /dev/null and b/design/pixelfix.png differ diff --git a/design/pixelfix.svg b/design/pixelfix.svg new file mode 100644 index 0000000..0d7fd98 --- /dev/null +++ b/design/pixelfix.svg @@ -0,0 +1,206 @@ + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + diff --git a/design/tessellation.png b/design/tessellation.png new file mode 100644 index 0000000..6ecb295 Binary files /dev/null and b/design/tessellation.png differ diff --git a/design/tessellation.svg b/design/tessellation.svg new file mode 100644 index 0000000..b407e16 --- /dev/null +++ b/design/tessellation.svg @@ -0,0 +1,321 @@ + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/design/texturecubing.png b/design/texturecubing.png new file mode 100644 index 0000000..4e8f8fb Binary files /dev/null and b/design/texturecubing.png differ diff --git a/design/texturecubing.svg b/design/texturecubing.svg new file mode 100644 index 0000000..5ab6e50 --- /dev/null +++ b/design/texturecubing.svg @@ -0,0 +1,278 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + 16 + 16 + 24 + 24 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/design/texturesidesteps.png b/design/texturesidesteps.png new file mode 100644 index 0000000..2903b58 Binary files /dev/null and b/design/texturesidesteps.png differ diff --git a/design/texturesidesteps.svg b/design/texturesidesteps.svg new file mode 100644 index 0000000..fdb73f2 --- /dev/null +++ b/design/texturesidesteps.svg @@ -0,0 +1,401 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + 16 + 16 + + + + + + + + + + + + + + + + + + + 18 + + + + + + + + + 12 + + 12 + + + + + + + + + + + + + + + + + 12 + + + + + + + diff --git a/design/texturetopsteps.png b/design/texturetopsteps.png new file mode 100644 index 0000000..bb89610 Binary files /dev/null and b/design/texturetopsteps.png differ diff --git a/design/texturetopsteps.svg b/design/texturetopsteps.svg new file mode 100644 index 0000000..aa4d0a8 --- /dev/null +++ b/design/texturetopsteps.svg @@ -0,0 +1,531 @@ + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + 16 + 16 + + + + + + + + + + + + + + + + + + + 24 + + + + + + + + + + 24 + + + + + + + + + + + 17 + + + 17 + + + + + + + + + + + + + + + + + + + + + + + + + + 24 + + + + + + + 12 + + + + + + + + + + + + diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..f6a68d0 --- /dev/null +++ b/index.rst @@ -0,0 +1,47 @@ +======================== +The Minecraft Overviewer +======================== + +Introduction +============ +The Minecraft Overviewer is a command-line tool for rendering high-resolution +maps of Minecraft worlds. It generates a set of static html and image files and +uses the Google Maps API to display a nice interactive map. + +The Overviewer has been in active development for over a year and has many +features, including day and night lighting, cave rendering, mineral overlays, +and many plugins for even more features! It is written mostly in Python with +critical sections in C as an extension module. + +For a simple example of what your renders will look like, head over to `The +"Exmaple" Map `_. For more user-contributed +examples, see `The Example Wiki Page `_. + +Download +======== +The Overviewer works with Linux, Mac, and Windows! We provide Windows and Debian +built executables available for download on our `Github Homepage`_. + +To get your copy, head over to our `Github Homepage`_. If you are familiar with Git, you can clone the repository from there. If you would like a Debian or Windows executable, click on the Downloads link, or go `directly there `_. + +.. _Github Homepage: https://github.com/overviewer/Minecraft-Overviewer + +Documentation +============= + +.. toctree:: + :maxdepth: 2 + + quickstart + building + running + design/designdoc + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/quickstart.rst b/quickstart.rst new file mode 100644 index 0000000..859ff4f --- /dev/null +++ b/quickstart.rst @@ -0,0 +1,77 @@ +================ +Quickstart Guide +================ + +This guide is aimed at new users that want to get started using Minecraft +Overviewer. It is *not* meant to explain everything, but it should help you +generate your first map. + +Getting the Overviewer +====================== + +Head to our `Github Homepage `_. You can either download the Windows package if you're running Windows, install the Debian package if you're running Debian or Ubuntu, or Git-clone the source. Building from source should be as simple as a `python setup.py build` but for more information, see `Building the Overviewer from Source `_. + +Quick-link for Git Source. (Clone this) + git://github.com/overviewer/Minecraft-Overviewer.git + +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``. + +To generate your map, run:: + + overviewer.exe WorldName path\to\output\ # on windows, or + ./overviewer.py WorldName path/to/output/ # on other systems + +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. + +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. + +Running Overviewer on a Server +------------------------------ + +There are special considerations when running Overviewer on a server. For +information on how to do this, see `Running Overviewer on a Server`_. + +.. _Running Overviewer on a Server: https://github.com/overviewer/Minecraft-Overviewer/wiki/Running-Overviewer-on-a-Server + +Extra Features +============== + +Overviewer has a lot of features beyond generating the simple map we started with. Here's information on two of them. + +Render Modes +------------ + +Overviewer supports many different rendermodes. Run `./overviewer.py --list-rendermodes` to get a list. Two of the most popular rendermodes are *lighting* and *night*, which draw shadows for the corresponding time of day. To tell Overviewer what rendermode to use, run + + ./overviewer.py --rendermodes=lighting WorldName output/dir/ + +You can also specify multiple rendermodes at once, and Overviewer will render +them all and let you toggle between them on the generated web page. To get both +*lighting* and *night* on the same page, run:: + + ./overviewer.py --rendermodes=lighting,night WorldName output/dir/ + +Biomes +------ + +Minecraft Overviewer has support for using the biome info from the `Minecraft +Biome Extractor`_. If you run the biome extractor on your world, during the +next run Overviewer will automatically recognize the biome info and use it to +colorize your grass and leaves appropriately. This will only appear on updated +chunks, though; to colorize the entire world you will need to rerender from +scratch by deleting the old render. + +**Note**: as of Minecraft 1.8, you currently need to use a patched Biome +Extractor that can be found `here `_, or `here on GitHub +`_. + +.. _Minecraft Biome Extractor: http://www.minecraftforum.net/viewtopic.php?f=25&t=80902 diff --git a/running.rst b/running.rst new file mode 100644 index 0000000..378f042 --- /dev/null +++ b/running.rst @@ -0,0 +1,3 @@ +====================== +Running the Overviewer +======================