Convert all GitHub wiki pages into ReStructuredText documents, set up ReadTheDocs

README.md

@@ -1,9 +1,11 @@
-# MobArena
-[![Build Status](https://travis-ci.org/garbagemule/MobArena.svg?branch=master)](https://travis-ci.org/garbagemule/MobArena)
+MobArena [![Build Status](https://travis-ci.org/garbagemule/MobArena.svg?branch=master)](https://travis-ci.org/garbagemule/MobArena) [![Documentation Status](https://readthedocs.org/projects/mobarena/badge/?version=latest)](http://mobarena.readthedocs.io/en/latest/?badge=latest)
+========
+
+MobArena is an arena-style minigame for Spigot-based Minecraft servers
 
-MobArena is an arena-style minigame for Bukkit-based Minecraft servers.
 
 ## Getting Started
+
 If you don't want to compile the plugin yourself, grab a release artifact from 
 one of these two sites:
 
@@ -13,7 +15,9 @@ one of these two sites:
 The wiki here on Github should have all the information you need to get 
 started using the plugin.
 
+
 ## Getting Help
+
 If you run into problems or need help with something, feel free to hop on IRC 
 (#mobarena @ irc.esper.net) to have a chat. If you don't know what IRC is or 
 don't have an IRC client, you can use a web-based one:
@@ -24,7 +28,9 @@ Remember, though, that IRC is _idle chat_, which means you likely won't get a
 response immediately. It could take anything from a couple of seconds to a 
 day, but your message _will_ be seen.
 
+
 ## Bugs and Suggestions
+
 Found a bug or have a great idea for the plugin? Use the issue tracker here on 
 Github to submit a bug report or feature request. Please have a look through 
 the existing issues before you post a new one to avoid duplicates.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = MobArena
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# MobArena documentation build configuration file, created by
+# sphinx-quickstart on Wed Nov 29 13:24:13 2017.
+#
+# 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.
+
+# 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.
+import os
+import sys
+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.todo']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'MobArena'
+copyright = '2017, garbagemule, Justin W. Flory (jflory7), MobArena contributors'
+author = 'garbagemule, Justin W. Flory (jflory7), MobArena 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.99'
+# The full version, including alpha/beta/rc tags.
+release = '0.99.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- 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 = 'alabaster'
+
+# 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 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']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'MobArenadoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'MobArena.tex', 'MobArena Documentation',
+     'garbagemule, Justin W. Flory (jflory7), MobArena contributors', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'mobarena', 'MobArena Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'MobArena', 'MobArena Documentation',
+     author, 'MobArena', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+

docs/index.rst

@@ -0,0 +1,32 @@
+.. MobArena documentation master file, created by
+   sphinx-quickstart on Wed Nov 29 13:24:13 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to MobArena's documentation!
+====================================
+
+.. toctree::
+   :maxdepth: 1
+   :name: dev
+   :caption: Developer resources
+   :glob:
+
+   dev/*
+
+.. toctree::
+   :maxdepth: 1
+   :name: user
+   :caption: User documentation
+   :glob:
+
+   user/*
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=MobArena
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+## Theme for Sphinx documentation
+Sphinx
+sphinx_rtd_theme

docs/test-docs.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+#
+# Script to automatically build and test the Sphinx documentation currently in
+# the repo. This script should always be run before submitting a new pull
+# request.
+# 
+# If you're on Windows, please use the `make.bat` script in `docs/` directory.
+#
+
+make clean html
+

docs/user/announcements.rst

@@ -0,0 +1,23 @@
+####################
+Announcement strings
+####################
+
+The ``announcements.yml`` file is where all of MobArena's announcements
+and messages are stored. You can freely edit this file however you see
+fit, and color codes are supported. **To add color to a message**, use
+the ``&``-character followed by a valid color code. You can find a list
+of valid codes `right
+here <http://minecraft.gamepedia.com/Formatting_codes#Color_codes>`__,
+and you can find examples in the default file.
+
+Note that some of the announcements take a variable, represented in the
+message by a ``%``-character. You can leave this character out if you
+don't want the variable in the message. It is not possible to add
+variables to announcements that don't take them by default, and
+announcements that take one variable cannot take more than that one
+variable.
+
+If you **don't want to see a specific announcement**, you have to set
+its value to ``''`` (note: two single-quotes, not one double-quote).
+This will cause MobArena to ignore the announcement. Note that simply
+removing the node will not work, as MobArena forcefully adds it back in.

docs/user/arena-setup.rst

@@ -0,0 +1,270 @@
+###########
+Arena setup
+###########
+
+**On this page:** \* `Building an arena <#building-an-arena>`__ \*
+`About regions, warps, etc. <#about-regions-warps-etc>`__ \* `Setup
+Mode <#setup-mode>`__ \* `Commands <#setup-mode-commands>`__ \* `The
+Toolbox <#the-toolbox>`__ \* `Regions <#regions->`__ \*
+`Warps <#warps->`__ \* `Spawnpoints <#spawnpoints->`__ \*
+`Chests <#chests->`__
+
+Building an arena
+=================
+
+A well-built arena consists of a **lobby** for class selection, an
+**arena floor**, and either a **spectator area** or an **exit point**.
+Let's go over each one...
+
+**Lobby:** The lobby is where your players will be selecting their
+classes when they join an arena. A well-formed lobby consists of *a sign
+for each class*, which the players will click to choose a given class,
+as well as an *iron block*, which the players will click when they are
+ready to start. The signs must have the name of the class on the first
+line (case-sensitive), but you can put whatever you want on the
+remaining three lines. Note that MobArena *does not* "register" class
+sign creation, so you *will not* get a confirmation message (if you do,
+it is another plugin interfering).
+
+**Arena floor:** This is where your players will be fighting monsters.
+The arena floor should be enclosed in walls, and possibly with a roof,
+such that the players and monsters have no way of getting out. This
+ensures that players won't be able to just wander out of the arena.
+
+**Spectator area:** When players want to spectate a session, they can
+use the ``/ma spec`` command to get warped to the spectator area of an
+arena. This is also where arena players are warped to when they die, if
+``spectate-after-death: true`` in the config-file. The area should be
+designed so that it *is not* possible for the spectators to wander out
+(into the arena or away from the area), because spectators are
+invincible.
+
+**Exit point:** Upon typing ``/ma leave``, arena players and spectators
+will be warped to the location they joined from, unless the arena has an
+exit warp (optional). Using exit points, it is possible to control
+exactly where players go after a session.
+
+About regions, warps, etc.
+--------------------------
+
+Once our arena is built, it's time to set up the MobArena regions,
+warps, and points. Before we do so, let's take a look at what these
+things are and what MobArena uses them for...
+
+**Regions:** An arena needs an *arena region*, and optionally a *lobby
+region*. MobArena uses the arena region to make sure that players aren't
+cheating (by kicking them from the arena if they move outside the
+region), and to make sure that only MobArena's own mobs are spawned
+inside of it. MobArena is extremely xenophobic (afraid of strangers), so
+it tries its best to keep unwanted mobs out of the sessions. Regions are
+set using the Region tools.
+
+**Warps:** When players join a MobArena session, they are teleported to
+the *lobby warp* inside the lobby, where they will *pick their class*
+and ready up using the *ready block* (block of iron). When everyone is
+ready, the players are teleported to the *arena warp* inside of the
+arena. Spectators will be teleported to the *spectator warp* in the
+spectator area, and when players leave an arena, they will either be
+teleported to where they joined from, or to the *exit warp*, if it has
+been set up. Warps are set using the Warps tool.
+
+**Spawnpoints:** The *spawnpoints* of an arena are the locations where
+monsters can spawn from. MobArena will only spawn monsters from
+spawnpoints that have players nearby (in a 15-block radius). Note that
+the number of mobs spawned doesn't depend on how many spawnpoints an
+arena has - the number of mobs is determined by a formula (see
+[[Formulas]]) that only involves the wave number and player count
+(unless you use fixed amounts). Spawnpoints are added using the
+Spawnpoints tool.
+
+**Containers:** The *containers* of an arena are locations of chests,
+dispensers, etc. which contain items that will be renewed when the arena
+ends. Only registered containers will have their contents renewed, so it
+is not enough to simply put a chest in the arena - it also needs to be
+registered using the Chests tool.
+
+Setup Mode
+==========
+
+We will set up the arena using *Setup Mode*. When we enter Setup Mode,
+MobArena will temporarily store our inventory and give us a set of
+golden tools (the *Toolbox*), each with a different function. We will
+also be able to *fly*, making moving around the arena a lot easier.
+Last, but not least, we will *not* be able to chat or type normal
+commands while in Setup Mode, because Setup Mode starts an *isolated
+conversation* with us.
+
+**To enter Setup Mode:** Type ``/ma setup <arena>``, where ``<arena>``
+is the name of an arena. Note that if you only have one arena, you don't
+have to type the arena name. If the arena you want to set up has not yet
+been created, first type ``/ma addarena <arena>`` to create it.
+
+**To leave Setup Mode:** Type ``done``.
+
+Note that if you have just installed MobArena, there will be a premade
+arena-node called ``default`` in the config-file already. If you want a
+different name, create a new arena first, and then remove the default
+arena by typing ``/ma delarena default``.
+
+In the next section, we will take a look at the different commands
+available in Setup Mode...
+
+Setup Mode Commands
+-------------------
+
+Setup Mode is an *isolated conversation*, which means Setup Mode will
+intercept everything we type. The reason for this is that it makes the
+commands in Setup Mode shorter (e.g. ``exp`` instead of
+``/ma expandregion``), and it also prevents us from accidentally typing
+commands from other plugins.
+
+Below is a list of all the commands we can use in Setup Mode. Many of
+the commands have short-hand aliases which might make them even faster
+to type out. As an example, the ``expand`` command has the alias
+``exp``. Sometimes it's easier to remember the longer names, but the
+short-hand aliases are provided for faster setup.
+
+-  | ``done``
+   | Leave Setup Mode.
+   | **Aliases:** ``end`` ``stop`` ``done`` ``quit``
+
+-  | ``help``
+   | Display help screen.
+   | **Aliases:** ``?`` ``h``
+
+-  | ``missing``
+   | Display a list of missing (mandatory) regions, warps, and points.
+   | This command is useful if you have forgotten how far you are in the
+     setup process, and what you still need to set up.
+   | **Aliases:** ``miss``
+
+-  | ``expand <region> <amount> <direction>``
+   | Expand a region by some amount in some direction.
+   | Valid regions: ``ar`` for the arena region, or ``lr`` for the lobby
+     region
+   | Valid amounts: positive integers (whole numbers)
+   | Valid directions: ``up``, ``down``, or ``out``
+   | **Example:** ``expand ar 5 up``
+   | **Aliases:** ``exp``
+
+-  | ``show [<region>|<warp>|<point>]``
+   | Show a region, warp, or point(s) as red wool blocks.
+   | Valid regions: ``ar`` for the arena region, or ``lr`` for the lobby
+     region
+   | Valid warps: ``arena``, ``lobby``, ``spec``, ``exit``
+   | Valid points: ``spawns`` (or just ``sp``) for spawnpoints,
+     ``chests`` (or just ``c``) for chests
+   | **Example:** ``show sp``
+
+The Toolbox
+-----------
+
+The Toolbox is a set of golden tools, where each tool has a specific
+function. We will use these tools to set up the regions, warps, and
+points of our arena. The tools are used by left- or right-clicking a
+block while holding them, and the actions vary depending on the specific
+tool.
+
+Note that the functions of a tool are described in the *item tooltip*,
+which we can see by opening up our inventory and hovering our mouse over
+the tools.
+
+Regions |Region Tools|
+~~~~~~~~~~~~~~~~~~~~~~
+
+The arena and lobby regions can be set up using the Region tools (axe).
+There are two golden axes in the Toolbox, and they both behave the same,
+except that one is for the arena region, and the other is for the lobby
+region. The tools are named accordingly, and they will display either
+"Arena Region" or "Lobby Region" above the quickbar when we select them.
+
+Note that the behavior of the Region tools is similar to that of the
+WorldEdit wand (wooden axe), so if you are familiar with defining
+regions in WorldEdit, the Region tools should feel familiar.
+
+| **Left-click:** Set the first point to be the location of the target
+  block
+| **Right-click:** Set the second point to be the location of the target
+  block
+
+Upon setting both points, the region will be defined. Type ``show ar``
+(or ``show lr``) to check that the region spans the desired area. If the
+region is a little bit too small, use the ``expand`` command (see above)
+to make it a little bigger.
+
+**Note:** The region MUST look like a box (3D) and not a rectangle (2D).
+If the region is just a rectangle, your arena will not work correctly.
+The same applies if the arena floor is not fully contained in the box,
+so make sure to expand the region down a block or two to be sure.
+
+Warps |Warps Tool|
+~~~~~~~~~~~~~~~~~~
+
+The arena, lobby, spectator, and exit warps can be set up using the
+Warps tool (hoe). The tool knows about all the warps, and we have to
+*cycle through them* to select the warp we want to place. The default
+selected warp is the *arena warp*.
+
+| **Left-click:** Set the currently selected warp on top of the target
+  block
+| **Right-click:** Cycle between available warps
+
+When left-clicking, the selected warp will be set to the top of the
+clicked block. The pitch (up and down) will be set to 0, which means
+when players are teleported, they will be looking "straight ahead". The
+yaw (rotation, left/right) will be set to whatever direction we are
+facing, when we set the warp. This means that we need to rotate
+ourselves to be looking in the direction we want the players to look in
+when they are teleported to the point.
+
+**Note:** The arena, lobby, and spectator warps are all required. The
+exit warp is optional.
+
+Spawnpoints |Spawnpoints Tool|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The spawnpoints can be set up using the Spawnpoints tool (sword). The
+tool knows about all the spawnpoints of the arena, and allows us to
+remove existing ones or add new ones as we please.
+
+| **Left-click:** Add a spawnpoint on top of the target block
+| **Right-click:** Remove the spawnpoint on top of the target block (if
+  the spawnpoint exists)
+
+When left-clicking, a spawnpoint will be added on top of the clicked
+block, if one doesn't already exist. Right-clicking a block will remove
+a spawnpoint on that block, if one exists.
+
+**Note:** Due to limitations and "bugs" in Minecraft, it is not possible
+(read: viable) to spawn mobs further than 15 blocks away from a player,
+and still make it target and attack the player naturally. Therefore, it
+is recommended to place many spawnpoints, so that every single location
+in the arena is within a 15-block radius of a spawnpoint. If a player is
+not within 15 blocks of any spawnpoint, MobArena will print a warning to
+the console with the coordinates. If no players are within 15 blocks of
+any spawnpoint, MobArena will default to using all spawnpoints, which
+may result in mobs spawning far away from players, so they will have to
+run around searching for them.
+
+Chests |Chests Tool|
+~~~~~~~~~~~~~~~~~~~~
+
+The chests and containers can be set up using the Chests tool (spade).
+It works very much like the Spawnpoints tool, but requires that the
+clicked block is a valid container.
+
+| **Left-click:** Register the clicked container (if it wasn't
+  registered)
+| **Right-click:** Unregister the clicked container (if it was
+  registered)
+
+When left-clicking a container, MobArena will register the container (if
+it wasn't registered already), such that when an arena session ends, the
+container will be restored to contain whatever was in it when the arena
+began. Right-clicking a container will unregister it.
+
+.. |Region Tools| image:: http://puu.sh/4wwCH.png
+.. |Warps Tool| image:: http://puu.sh/4wwIB.png
+.. |Spawnpoints Tool| image:: http://puu.sh/4wwCJ.png
+.. |Chests Tool| image:: http://puu.sh/4wwIF.png
+

docs/user/class-chests.rst

@@ -0,0 +1,106 @@
+############
+Class chests
+############
+
+**On this page:** \* `About Class Chests <#about-class-chests>`__ \*
+`Linked Class Chests <#linked-class-chests>`__
+
+About Class Chests
+------------------
+
+If some of your favorite items aren't supported by MobArena's internal
+[[item parser\|Item and Reward Syntax]], or if you just want to be able
+to configure your class items from in-game, the **class chests** may be
+what you're looking for!
+
+--------------
+
+**Note: The Class Chests will only work for arenas with
+``use-class-chests: true``, and the classes *MUST* exist in the
+config-file for MobArena to recognize them, however the items and armor
+lists can be empty.** \* \* \*
+
+The idea behind the class chests is to simply place some **chests below
+the corresponding class signs** in the lobby, and fill them with
+whatever items you want the given class to have. When the players
+activate the class signs, the **contents of the chests are copied to the
+player inventory**. This suggests a type of "control room" setup, where
+an admin-only access room below the lobby contains the chests, allowing
+admins to warp down there and change the contents of the chests.
+
+.. figure:: img/1.png
+   :alt: Lobby and Control Room
+
+   Lobby and Control Room
+
+For easier access and modification of the class chests, omitting the
+control room from the arena or lobby region may prove useful. Otherwise,
+arenas may have to be temporarily disabled or put into edit mode to
+allow warping to and changing the contents of the chests.
+
+The class chests can be located **up to 6 blocks below the sign** itself
+or below the block right behind the sign (for wall signs, this would be
+the block the sign is attached to). The chest may also be in the block
+directly behind the sign itself - this is safe, because MobArena
+prevents players in the lobby from opening inventories, so if your lobby
+is in a tight spot, this might be the better option.
+
+**Multiple sign rows:** It is possible to have two rows of class signs
+in the lobby and still use this feature. Simply place the class chest
+for the sign of the bottom row exactly at the 6-block limit, and the
+class chest for the sign of the top row one block up and behind the
+other chest (in a stair-like fashion). The blocks are searched in a
+vertical/pillar-like fashion, which is the reason this works.
+
+.. figure:: img/2.png
+   :alt: Chests Below
+
+   Chests Below
+
+To get **auto-equipped armor** from the class chests, place the armor
+pieces in the **last four slots of the third row** in the chest.
+MobArena will check these four slots, and if any of them are armor
+pieces, they will be equipped. Note that the item placed in the very
+last slot (bottom right), will always be equipped as a helmet (this
+allows wool blocks, pumpkins, etc. to be used as helmets). The order of
+the other three slots doesn't matter.
+
+The **fifth last slot**, right next to the armor slots, will be equipped
+as an **off-hand** item.
+
+.. figure:: img/3.png
+   :alt: Armor Slots
+
+   Armor Slots
+
+The class chests are the best way to add items that are not currently
+supported by the MobArena [[item parser\|Item Syntax]]. This is because
+the class chests **simply copy the contents of the chests** to the
+player inventories, thus making any items supported by Bukkit supported
+by MobArena.
+
+.. figure:: img/4.png
+   :alt: Dyed Armor
+
+   Dyed Armor
+
+Linked Class Chests
+-------------------
+
+If per-arena class chest setups is too troublesome (e.g. if you have
+many arenas), if you don't need per-arena setups, or if you simply want
+a single, global class chest for each class, *linked class chests* are
+what you're looking for.
+
+When you link a chest to a class, MobArena will always copy the contents
+of that chest to the player's inventory, when they pick the given class,
+regardless of any local class chests (note that the arena must still
+have ``use-class-chests: true``).
+
+To link a chest to a class, simply look at the chest and type
+``/ma classchest <class>``, and you're done! The linked class chests may
+exist in any world, but remember that there can only be one class chest
+per class, and that local class chests will be ignored!
+
+To unlink a class chest, you will have to open the config-file and
+remove the ``classchest`` node from the given class.

docs/user/commands.rst

@@ -0,0 +1,91 @@
+########
+Commands
+########
+
+Note: All MobArena commands start with ``/ma``, and most of them can be
+disabled using [[Permissions]].
+
+If you are looking for ways to disable non-MobArena commands, look in
+the ``global-settings``-section of the [[config-file setup page\|setting
+up the config-file]].
+
+Player commands
+~~~~~~~~~~~~~~~
+
+These commands can be issued by all players. They include joining,
+leaving, spectating and listing arenas as well as listing players.
+
+-  ``/ma join (<arena>)`` or ``/ma j (<arena>)`` - Join the arena with
+   the given name.
+-  ``/ma leave`` or ``/ma l`` - Leave the current arena, or the
+   spectator area.
+-  ``/ma notready`` - Get a list of all players who aren't ready.
+-  ``/ma spec (<arena>)`` or ``/ma s (<arena>)`` - Spectate the arena
+   with the given name.
+-  ``/ma arenas`` - Get a list of all arenas. Green names are enabled,
+   gray names are disabled.
+-  ``/ma players`` - Get a list of all arena players.
+-  ``/ma players <arena>`` - Get a list of arena players in the
+   specified arena.
+-  ``/ma class <class>`` - While in the lobby, manually pick the given
+   class instead of punching signs.
+
+Admin commands
+~~~~~~~~~~~~~~
+
+Only ops and the console can issue these commands. They include
+forcefully starting or ending arenas, enabling/disabling individual
+arenas or MobArena entirely.
+
+-  ``/ma enable`` - Enable MobArena.
+-  ``/ma disable`` - Disable MobArena.
+-  ``/ma enable <arena>`` - Enable the arena with the specified name.
+-  ``/ma disable <arena>`` - Disable the arena with the specified name.
+-  ``/ma force end`` - Forcefully end all arenas.
+-  ``/ma force end <arena>`` - Forcefully end the arena with the
+   specified name; forces all players to leave.
+-  ``/ma force start <arena>`` - Forcefully start the arena with the
+   specified name; forces all players who aren't ready to leave.
+-  ``/ma notready <arena>`` - Get a list of all players in the given
+   arena who aren't ready.
+-  ``/ma restore <player>`` - Restore the inventory of the player with
+   the given name, if possible.
+-  ``/ma config reload`` - Reload the config-file into memory. This is
+   useful if changes are made in the config-file while the server is
+   running.
+
+Setup commands
+~~~~~~~~~~~~~~
+
+Only ops (and the console, if it makes sense) can issue these commands.
+They include setting warp points, spawnpoints and region points.
+
+-  ``/ma setup <arena>`` - Enter [[Setup Mode\|Arena Setup]] for the
+   given arena.
+-  ``/ma addarena <arena>`` - Create a new arena-node in the current
+   world.
+-  ``/ma delarena <arena>`` - Delete the arena with the given name.
+-  ``/ma editarena <arena>`` - Toggle Edit Mode for the given arena.
+-  ``/ma editarena <arena> [true|false]`` - Turn on or off Edit Mode for
+   the given arena.
+-  ``/ma setting <arena>`` - List all per-arena settings for the given
+   arena.
+-  ``/ma setting <arena> <setting>`` - Check the current value of the
+   given setting for the given arena.
+-  ``/ma setting <arena> <setting> <value>`` - Set the value of the
+   given setting for the given arena to the given value.
+-  ``/ma checkspawns`` - Shows the spawnpoints (of the arena you are
+   currently standing in) which cover your current location as red wool
+   blocks. This command can be used to check if specific points in your
+   arena are actually covered by spawnpoints or not.
+-  ``/ma classchest <class>`` - While looking at a chest, link the chest
+   to the given class as a [[linked class chest\|Class Chests]]. Linking
+   a class chest means MobArena will always copy the items from the
+   linked chest, regardless of any local class chests in arena lobbies.
+   This is useful if you want a global class chest for a class.
+-  ``/ma auto-generate <arena>`` - Auto-generate a new arena with the
+   given name. The arena will be generated just below the player in the
+   world they are standing in.
+-  ``/ma auto-degenerate <arena>`` - Degenerate the arena with the given
+   name, effectively restoring the patch that was "bulldozed" with the
+   auto-generator.

docs/user/getting-started.rst

@@ -0,0 +1,60 @@
+###############
+Getting started
+###############
+
+To get MobArena up and running on your server, you'll first have to
+download it and stick it in your server's plugins-folder.
+
+When the plugin has been loaded up, you'll have to build an arena if you
+haven't already. Then it's time to set it up. Follow the instructions on
+the [[Arena Setup]] page, which has all the information you'll need to
+get your arena up and running in no time at all. After setup, you're
+ready to play! Check out the [[Using MobArena]] page for a brief
+description of the usage commands.
+
+The default arena setup is only meant as a starting point, so you may
+want to configure the waves, the rewards, the classes, or perhaps some
+of the arena-specific settings. The various pages on this wiki will help
+you configure MobArena to your liking. Here are a couple of links to get
+you started:
+
+-  [[Setting up the config-file]]
+-  [[Setting up the waves]]
+-  [[MobArena Commands]]
+
+Also make sure to have a look at the [[Item and Reward Syntax]] page, if
+you're planning to change the classes or the rewards. MobArena uses its
+own semi-compact item syntax in the config-file, so you'll need to get
+familiar with it to get things like enchantments and sub-types to work.
+
+****************
+More information
+****************
+
+Always make sure to check the pages on the wiki when you're in doubt -
+99% of the information you'll ever need is right here. Check out the
+[[list of wiki
+pages\|https://github.com/garbagemule/MobArena/wiki/\_pages]] to see if
+maybe you'd be able to find your answer there. You can also check the
+project pages on
+[[Spigot\|https://www.spigotmc.org/resources/mobarena.34110/]] and
+[[Bukkit\|http://dev.bukkit.org/bukkit-plugins/mobarena/]].
+
+***********************
+Suggestions, bugs, etc.
+***********************
+
+If you think you have found a bug, or if you have a suggestion for the
+plugin, you can create a ticket here on Github. Make sure to be as
+descriptive as possible, because the more information you can provide,
+the easier it is to do something about your bug report or feature
+request.
+
+If you'd rather have a little chat about the plugin, you can visit the
+[[IRC channel\|http://webchat.esper.net/?channels=#mobarena]] (#mobarena
+@ EsperNet) - please note that IRC is *idle chat*, which means people
+will appear to be in the channel, but they might not be at their
+computers when you join. Hop on, ask your question, and then hang around
+until you get an answer; it may be seconds, minutes or hours, but there
+is no harm in hanging around the channel indefinitely (as many people
+do).

docs/user/item-reward-syntax.rst

@@ -0,0 +1,186 @@
+######################
+Item and reward syntax
+######################
+
+**On this page:** \* `Overview <./Item-and-Reward-Syntax#an-overview>`__
+\* `Single Items <./Item-and-Reward-Syntax#1-single-items>`__ \*
+`Multiple Items <./Item-and-Reward-Syntax#2-multiple-items>`__ \* `Item
+Sub-Types <./Item-and-Reward-Syntax#3-item-sub-types-potions-wool-dyes-etc>`__
+\* `Note about item
+IDs <./Item-and-Reward-Syntax#an-important-note-on-using-item-ids>`__ \*
+`Enchantments <./Item-and-Reward-Syntax#enchantments>`__ \* `Economy
+Money <./Item-and-Reward-Syntax#economy-money>`__ \* `Command
+Rewards <./Item-and-Reward-Syntax#command-rewards>`__
+
+An Overview
+~~~~~~~~~~~
+
+Items in MobArena follow a very specific syntax that you **must** obey,
+or you will experience missing items or errors. Be attentive to the
+details, because if you aren't, there will be consequences.
+
+MobArena allows these three different ways of defining items:
+
+::
+
+    Single:    [<id>|<name>]
+    Multiple:  [<id>|<name>]:<amount>
+    Sub-types: [<id>|<name>]:<data>:<amount>
+
+Confusing? Let's break them down one by one.
+
+1. Single Items
+~~~~~~~~~~~~~~~
+
+::
+
+    [<id>|<name>]
+
+This means you can use either the item ID (``<id>``), or the item name
+(``<name>``) as defined in the `Material enum of the Bukkit
+API <https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html>`__.
+The item names are case-insensitive.
+
+Note that the Material enum changes when there are new items or
+sometimes if items were reworked. As an example, the ``SPLASH_POTION``
+enum value is not available in versions prior to Minecraft 1.9. Before
+then, splash potions were simply ``POTION``\ s with a higher data value.
+
+**Make sure to read `the important note on item
+IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!**
+
+Examples: ``diamond_sword``, ``stone``, ``42`` (iron block), ``322``
+(snowball)
+
+2. Multiple Items
+~~~~~~~~~~~~~~~~~
+
+::
+
+    [<id>|<name>]:<amount>
+
+This way, you append an ``<amount>`` to the item, specifying how many of
+the given item you want. This is useful for giving out stuff like arrows
+or potions that you generally want to give more than one of.
+
+Note that if you use this syntax, it is indeed the *amount* you specify,
+not the item sub-type. We go over sub-types in the `next
+section <./Item-Syntax#3-item-sub-types-potions-wool-dyes-etc>`__.
+
+**Make sure to read `the important note on item
+IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!**
+
+Examples: ``arrow:64``, ``grilled_pork:4``, ``46:10`` (10x TNT),
+``142:5`` (5x potato)
+
+3. Item Sub-Types (potions, wool, dyes etc.)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    [<id>|<name>]:<data>:<amount>
+
+This way, you append **BOTH** a ``<data>`` value (the sub-type) and an
+``<amount>``, regardless of how many of the given item you want. This
+syntax is mostly used with potions, which have special sub-type values
+in the 8000's and 16000's. Check out `this
+page <http://www.minecraftwiki.net/wiki/Potions#Primary_potions>`__ for
+the potion sub-types.
+
+For wool and dyes (ink sacks), you don't have to use the numeric data
+value. Instead, you can use the *color names* as defined in the
+`DyeColor *enum* of the Bukkit
+API <http://jd.bukkit.org/rb/apidocs/src-html/org/bukkit/DyeColor.html#line.10>`__.
+
+**Make sure to read `the important note on item
+IDs <./Item-Syntax#an-important-note-on-using-item-ids>`__!**
+
+Examples: ``wool:blue:1`` (one blue wool), ``ink_sack:brown:10`` (ten
+cocoa beans), ``potion:8201:1`` (one strength potion), ``373:8197:2``
+(two health potions)
+
+An important note on using item IDs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you choose to use item IDs, there is a catch. If an item is *alone*
+in its node, it **MUST** be enclosed in apostrophes, or YAML will crap
+itself. For example, if you decide to have a Barbarian class that only
+has a pair of *lederhosen* as armor, and nothing put a couple of health
+potions, you need to do it like this:
+
+::
+
+    classes:
+        Barbarian:
+            items: '373:8197:2'
+            armor: '300'
+
+In other words, you have to put ``'300'`` in the ``armor``-node, *not
+just* ``300``, and you have to put ``'373:8197:2'`` in the
+``items``-node, *not just* ``373:8197:2``. This requirement is removed
+if you use the item names instead, or if you add
+`enchantments <./Item-Syntax#enchantments>`__ to the given item.
+
+Enchantments
+~~~~~~~~~~~~
+
+Enchantments can be added to items by appending a space, followed by a
+*semi-colon separated list* of pairs ``<eid>:<level>``, where ``<eid>``
+is an enchantment ID as defined by the `Enchantment Wrappers in the
+Bukkit
+API <http://jd.bukkit.org/rb/apidocs/src-html/org/bukkit/enchantments/Enchantment.html#line.12>`__
+(the numbers in the parentheses at the end of each line), i.e.:
+
+::
+
+    <item> <eid>:<level>;<eid>:<level>;...
+
+The ``<item>`` is any item following the normal item syntax as described
+above. Here is an example:
+
+::
+
+    diamond_sword 16:2;19:5
+
+This line gives a diamond sword with sharpness (ID 16) level 2, and
+knockback (ID 19) level 5.
+
+Economy Money
+~~~~~~~~~~~~~
+
+::
+
+    $<amount>
+
+MobArena supports entry fees and rewards in the form of money from
+economy plugins. This feature *requires Vault*. The format quite simply
+means that you type in a dollar sign followed by a valid monetary value.
+
+Examples: ``$1``, ``$5``, ``$3.14`` (v0.96+), ``$0.99`` (v0.96+)
+
+Command Rewards
+~~~~~~~~~~~~~~~
+
+Since v0.99, MobArena supports commands as rewards. This means that you
+can have the server run a command that targets the recipient player.
+This is useful for granting persistent permissions via your permissions
+plugin, or integrating with rewards from other plugins, like rewarding
+tokens or special items with lore. The basic syntax is this:
+
+::
+
+    cmd:/give <player> dirt
+
+If the player is "garbagemule", this setting will run the command "/give
+garbagemule dirt" when the arena session ends. Note that this syntax
+will display as
+``[MobArena] You just earned a reward: /give <player> dirt``, which
+isn't very pretty. If you want the reward to have a title, simply expand
+the ``cmd`` with the name in a parenthesis:
+
+::
+
+    cmd(a very nice thing):/give <player> dirt
+
+This will display as
+``[MobArena] You just earned a reward: a very nice thing``

docs/user/leaderboards.rst

@@ -0,0 +1,68 @@
+############
+Leaderboards
+############
+
+MobArena supports so-called *leaderboards* (although technically they
+are more like scoreboards or session signs). By arranging signs in a
+two-dimensional grid on a wall, spectators can see which classes each
+player has chosen, which wave they died on, how many kills and how much
+damage they have done, etc.
+
+.. figure:: img/leaderboards/1.png
+   :alt: Sign Grid
+
+   Sign Grid
+
+The requirements for leaderboards are at the very least two rows of
+signs on a wall as seen in the screenshot above. The top row should not
+be empty, however, as it should contain the leaderboard *headers*, which
+denote what kind of information the signs below them display. How many
+headers (and which) you want is entirely up to you.
+
+.. figure:: img/leaderboards/2.png
+   :alt: Top Left Sign
+
+   Top Left Sign
+
+To get started, replace the top left empty sign (or place it if you
+haven't already), and write ``[MA]<name>``, where ``<name>`` is the name
+of your arena, on the first line. In the screenshot above, I have set up
+the top left sign for the arena named Jail by writing ``[MA]jail`` on
+it. MobArena automatically fills in the rest of the text and the colors
+for you.
+
+.. figure:: img/leaderboards/3.png
+   :alt: Sign Text Screen
+
+   Sign Text Screen
+
+MobArena will then tell you that the sign has been created, and that you
+should set up the rest of the signs. The rest of the headers follow the
+same kind of format as the top left sign, so you simply write
+``[MA]<stat>``, where ``<stat>`` is one of the following:
+
+-  ``class`` - The class name of the player
+-  ``lastWave`` - The last wave the player was part of (current wave if
+   still alive)
+-  ``kills`` - The number of monsters the player has killed
+-  ``dmgDone`` - The amount of damage the player has dealt
+-  ``dmgTaken`` - The amount of damage the player has taken
+-  ``swings`` - The number of times the player has swung their weapon
+-  ``hits`` - The number of times the player has swung their weapon and
+   successfully hit a monster
+
+In the screenshot above, I have already set up a couple of signs, and
+I'm about to set up the sign for damage done. As with the top left sign,
+your only job is to tell MobArena which stat you want - it'll take care
+of colors and formatting automatically. Note that MobArena's sign
+handling is case sensitive, so make sure you get it right.
+
+.. figure:: img/leaderboards/4.png
+   :alt: Final Setup
+
+   Final Setup
+
+When you're done setting up the leaderboards, they should look something
+like the screenshot above, and you should be good to go! Leaderboards
+can be set up anywhere (even outside of the world the arena is in), but
+you can only have a single leaderboard per arena.

docs/user/monster-types.rst

@@ -0,0 +1,38 @@
+#############
+Monster types
+#############
+
+MobArena supports any monster available in the `EntityType
+enum <https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html>`__.
+You don't have to write the names in all caps, and you can omit or
+include underscores (``_``), hyphens (``-``), and periods (``.``) as you
+please.
+
+Some monsters are a little special. Creepers, for instance, can be
+charged or powered, meaning their explosions become much more powerful,
+and their appearance changes. Another example is slimes and magma cubes,
+which have different sizes.
+
+MobArena supports some of the variations of these different monster
+types, and they are listed here:
+
+-  ``explodingsheep`` is a MobArena-specific type of sheep that bounces
+   around and explodes when in the proximity of a player
+-  ``poweredcreeper`` is a charged/powered creeper
+-  ``angrywolf`` is an aggressive wolf with red eyes
+-  ``babyzombie`` is a baby-version of a zombie
+-  ``babypigman`` is a baby-version of a pigman
+-  ``babyzombievillager`` is a baby-version of a zombie villager
+-  ``killerbunny`` is a killer bunny version of a rabbit
+
+As for slimes and magma cubes, both monster types are assigned a random
+size when they spawn. However, they also both support size suffixes that
+force them to be a specific size. They are:
+
+-  ``tiny`` size 1
+-  ``small`` size 2
+-  ``big`` size 3
+-  ``huge`` size 4
+
+As an example, ``slimehuge`` will spawn a size 4 slime, while
+``magmacubetiny`` will spawn a size 1 magma cube.

docs/user/permissions.rst

@@ -0,0 +1,179 @@
+###########
+Permissions
+###########
+
+A permissions plugin **is NOT required** for MobArena to work, but if
+you want that extra bit of control, here's a rundown of the different
+types of permission nodes you can use with MobArena.
+
+**NOTE: MobArena uses sane defaults. This means that by default, all
+players can use all arenas and all classes, and ops can use all admin
+and setup commands. Unless you want to prevent some groups from
+accessing certain arenas or classes, or you want to give non-ops admin
+and setup permissions, there is no need to mess with any permissions at
+all, so go away from this page and remove all occurrences of
+``mobarena`` in your permissions-file!**
+
+Arenas
+~~~~~~
+
+Did you read the note at the top? If not, read it before you continue.
+
+So, you want to remove permissions for certain arenas from certain
+users? Alright, that means you will have to *negate* or *revoke* the
+permissions in your permissions plugin. In bPermissions, the negation
+modifier is a caret, ``^``, in GroupManager and PermissionsEx it is a
+minus, ``-``, and in zPermissions it is by setting the permission to
+``false``. The examples below revoke the permission for the default
+arena.
+
+| bPermissions: ``^mobarena.arenas.default``
+| GroupManager: ``-mobarena.arenas.default``
+| zPermissions: ``mobarena.arenas.default: false``
+
+I recommend letting everyone enjoy all your arenas, but this could be
+used in combination with "leveling" plugins to allow players to use
+"harder" arenas at higher levels. It could also be used for
+sponsors-only arenas.
+
+Still confused? Check the `sample setup <#sample-setup>`__ at the bottom
+of the page!
+
+Classes
+~~~~~~~
+
+Did you read the note at the top? If not, read it before you continue.
+
+Alright, if you're reading this, you want to remove permissions for
+certain classes from certain users. As with the arena permissions, you
+need to *negate* or *revoke* the permissions in your permissions plugin.
+In bPermissions, the negation modifier is a caret, ``^``, in
+GroupManager and PermissionsEx it is a minus, ``-``, and in zPermissions
+it is by setting the permission to ``false``. The examples below revoke
+the permission for the Knight class.
+
+| bPermissions: ``^mobarena.classes.knight``
+| GroupManager: ``-mobarena.classes.knight``
+| zPermissions: ``mobarena.classes.knight: false``
+
+**Note how the class name is lowercase.** This is important. Even if the
+Knight class is called ``KnIGhT`` in your config-file, it MUST be all
+lowercase in your permissions-file.
+
+As with arenas, I recommend letting everyone enjoy all the classes,
+unless you have a special reason not to.
+
+Still confused? Check the `sample setup <#sample-setup>`__ at the bottom
+of the page!
+
+Commands
+~~~~~~~~
+
+Did you read the note at the top? If not, read it before you continue.
+
+If you're reading this, you want to either give certain users access to
+some of the admin and/or setup commands, or you want to remove some of
+the user commands from some groups. If this is not the case, stop
+reading and leave this page!
+
+The first group of commands are the user commands. They are accessible
+by all players by default, so don't put ``mobarena.use.*`` or something
+stupid like that in your permissions-file! If you want a group to not
+have access to the user commands, *negate* the permission
+``mobarena.use``, which is the *parent permission node* for all the user
+commands. See the classes and arenas sections for information on how to
+negate permissions. If that doesn't work, negate the
+``mobarena.use.join`` and ``mobarena.use.spec`` permissions. That should
+be enough.
+
+::
+
+    mobarena.use.join
+    mobarena.use.leave
+    mobarena.use.spec
+    mobarena.use.arenalist
+    mobarena.use.playerlist
+    mobarena.use.notready
+    mobarena.use.class
+
+The admin commands are simple. They allow disabling/enabling MobArena
+and individual arenas, kicking players from the arenas, restoring player
+inventories if they got lost somehow, forcing arenas to start or end,
+and teleporting in and out of arenas regardless of what the arena state
+is. If you want to grant all of these permissions, use the *parent
+permission node* ``mobarena.admin``. Don't mess around with ``*`` or
+something stupid like that.
+
+::
+
+    mobarena.admin.enable
+    mobarena.admin.kick
+    mobarena.admin.restore
+    mobarena.admin.force
+    mobarena.admin.teleport
+
+Setup commands are only for ops, just like admin commands. **Do not**
+give these permissions to random people, because they can remove your
+arenas and destroy your config-files, if they do something stupid. The
+setup commands allow you to manage arenas, regions, spawnpoints, chests,
+leaderboards, etc. They also allow you to set up new classes in-game. If
+you want to grant all of these permissions, use the *parent permission
+node* ``mobarena.setup``. Don't mess around with ``*`` or something
+stupid like that.
+
+::
+
+    mobarena.setup.config
+    mobarena.setup.setup
+    mobarena.setup.setting
+    mobarena.setup.addarena
+    mobarena.setup.removearena
+    mobarena.setup.editarena
+    mobarena.setup.spawnpoints
+    mobarena.setup.containers
+    mobarena.setup.checkdata
+    mobarena.setup.checkspawns
+    mobarena.setup.classchest
+    mobarena.setup.classes
+    mobarena.setup.leaderboards
+    mobarena.setup.autogenerate
+    mobarena.setup.autodegenerate
+
+Sample setup
+~~~~~~~~~~~~
+
+Assume you have a class called DiamondKnight that you only want your
+donors to be able to use (very common use case). How do you set up your
+permissions plugin when you have to revoke the class permission from the
+default group, but the donor group inherits from the default group? It's
+very simple: You're doing it wrong...
+
+What you have to do instead is make an *auxiliary default*-group that
+contains all your default permissions, and have your default group
+inherit from that group, and furthermore revoke the DiamondKnight class
+permission in MobArena. Your donor group then also inherits from the
+auxiliary group, and everything is wonderful. Confusing? Here's a
+pseudo-code example:
+
+::
+
+    default-aux:                            <-- This is the auxiliary group that is to
+      permissions:                              be inherited by the default group and
+      - essentials.balance                      the donor group. It is not used for
+      - essentials.pay                          anything else.
+      - essentials.sell
+
+    default:                                <-- This is the default group. It inherits
+      inherits: default-aux                     from default-aux, but also revokes the
+      permissions:                              permission for the special class.
+      - -mobarena.classes.diamondknight
+
+    donor:                                  <-- This is the donor group, which also
+      inherits: default-aux                     inherits from default-aux, but it
+      permissions:                              does not revoke any class permissions,
+      - essentials.balance.others               which means it has access to all of
+      - essentials.kit                          them by default.
+
+This sample setup is **pseudo code** and cannot be simply copy/pasted
+into your own permissions file. It's your job to figure out how your
+permissions plugin works, and what its syntax is.

docs/user/setting-up-config-file.rst

@@ -0,0 +1,530 @@
+##########################
+Setting up the config file
+##########################
+
+**On this page:** \*
+`Overview <./Setting-up-the-config-file#wiki-an-overview>`__ \*
+```global-settings`` <./Setting-up-the-config-file#wiki-global-settings>`__
+\* ```classes`` <./Setting-up-the-config-file#wiki-classes>`__ \* `Bring
+your own items <./Setting-up-the-config-file#bring-your-own-items>`__ \*
+`Slot-specific armor
+nodes <./Setting-up-the-config-file#slot-specific-armor-nodes>`__ \*
+`Price <./Setting-up-the-config-file#price>`__ \* `Unbreakable
+items <./Setting-up-the-config-file#wiki-unbreakable-weaponsarmor>`__ \*
+`Per-class
+permissions <./Setting-up-the-config-file#wiki-per-class-permissions>`__
+\* `Pet classes <./Setting-up-the-config-file#wiki-pet-classes>`__ \*
+`Mounts <./Setting-up-the-config-file#wiki-mounts>`__ \*
+```arenas`` <./Setting-up-the-config-file#wiki-arenas>`__ \*
+```settings`` <./Setting-up-the-config-file#wiki-settings>`__ \*
+```waves`` <./Setting-up-the-config-file#wiki-waves>`__ \*
+```rewards`` <./Setting-up-the-config-file#wiki-rewards>`__ \*
+```coords`` <./Setting-up-the-config-file#wiki-coords>`__
+
+An Overview
+~~~~~~~~~~~
+
+*Note: When editing the config-file, you **MUST use spaces for
+indentation**! Using tabs instead of spaces will give you errors!*
+
+The config-file, ``plugins/MobArena/config.yml``, consists of 3
+sections: ``global-settings``, ``classes``, and ``arenas``. The default
+config-file that is generated when MobArena is first loaded looks
+something like this:
+
+::
+
+    [...]
+    global-settings:
+        update-notification: true
+        enabled: true
+        allowed-commands: /list
+        prefix: '&a[MobArena] '
+    classes:
+        Knight:
+            items: diamond_sword, grilled_pork:2
+            armor: 306,307,308,309
+        Archer:
+            items: wood_sword, bow, arrow:128, grilled_pork
+            armor: 298,299,300,301
+        [...]
+    arenas:
+        default:
+            settings:
+                prefix: ''
+                world: Tundra
+                enabled: true
+                protect: true
+                clear-wave-before-next: false
+                [...]
+            waves:
+                [...]
+            rewards:
+                [...]
+
+Note about notation: ``[true|false]`` means the setting must be "true or
+false", either or. ``<time>`` means the setting must be an amount of
+time (in seconds or server ticks), always a whole number, and always
+``0`` or greater. ``<amount>`` is similar to time.
+
+global-settings
+---------------
+
+The ``global-settings`` are few, but important. Note that if
+``enabled: false``, no arenas can be joined, regardless of their
+individual ``enabled`` status.
+
+-  ``enabled: [true|false]`` - This determines if MobArena is enabled or
+   not. If set to ``false``, players will not be able to join any arenas
+   at all, regardless of what the arenas' individual statuses are.
+-  ``update-notification: [true|false]`` - If true, MobArena will send a
+   message to ops when they log on if a new version of MobArena is
+   available.
+-  ``allowed-commands: <com1>, <com2>, ...`` - A comma-separated list of
+   the commands that players are allowed to use while in the lobby
+   and/or arena. This is useful if you don't want players to use
+   teleport-commands, flying carpets, kill commands, etc. If you write
+   the command WITH its forward-slash, the entire command and all
+   "sub-commands" will be allowed. For instance, writing ``/kill`` will
+   allow both ``/kill``, ``/kill Sausageman22`` and ``/kill Notch``.
+   Writing the command WITHOUT its forward-slash will allow only that
+   specific command or "sub-command". Writing ``kill`` will thus ONLY
+   allow ``/kill``, but not ``/kill Sausageman22``.
+-  ``prefix: <prefix>`` - The prefix MobArena uses for all of its
+   messages. The default is the classic green ``[MobArena]``, but you
+   can change it to whatever you want. You can override the prefix for
+   specific arenas by using the arena-specific setting with the same
+   name.
+
+I recommended leaving the update notifications on, and disabling
+commands like ``/kill`` and ``/tp``.
+
+classes
+-------
+
+The ``classes``-section is slightly more complicated. It is divided into
+*class-branches*, where each branch denotes the *name of the class*, and
+each branch has mandatory nodes ``items`` and ``armor``, as well as
+optional slot-specific armor nodes and optional nodes ``price``,
+``permissions``, ``lobby-permissions``, ``unbreakable-weapons``, and
+``unbreakable-armor``.
+
+**Note:** YAML is picky about how you type your items. Make sure you
+read the short [[Item and Reward Syntax]]-page and fully understand it
+before you attempt to modify the config file!
+
+::
+
+    classes:
+        Archer:
+            items: wood_sword, bow, arrow:128, grilled_pork
+            armor: 298,299,300,301
+            permissions:
+            - EffectiveArrows.use.*
+            - -mobarena.use.leave
+        Tank:
+            items: iron_sword
+            armor: 310,311,312,313
+            offhand: shield
+        Knight:
+            items: '276'
+            armor: iron_helmet, iron_chestplate, iron_leggings, iron_boots
+        Wolf Master:
+            items: stone_sword, grilled_pork, bone:2
+            armor: 298,299,300,301
+        Crusader:
+            items: iron_sword, hay_block:17
+            armor: 302,303,304,305
+            price: $5
+
+Bring your own items
+~~~~~~~~~~~~~~~~~~~~
+
+MobArena allows you to just bring your own items into the arena via the
+implicit 'My Items' class. What this means is that if you just place a
+sign in the lobby with the text My Class, you'll get the items that you
+had before joining the arena. Items are still restored on dying in or
+leaving the arena.
+
+For a smooth, own-items-only experience, ditch the signs and set the
+per-arena setting ``default-class`` to ``myitems``.
+
+Slot-specific armor nodes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to use off-hand items, or if you just want to be explicit
+about which items go where in the armor slots, use the optional
+slot-specific armor nodes: ``offhand``, ``helmet``, ``chestplate``,
+``leggings``, ``boots``. In the example above, the **Tank** class gets a
+shield in its off-hand slot.
+
+Price
+~~~~~
+
+The optional ``price`` node can be used to give classes a per-session
+price. When a player tries to pick a class that has a price, they will
+only be able to if they can afford it. The money is withdrawn when the
+arena starts, i.e. picking different priced classes in succession will
+not (necessarily) result in empty player wallets. In the example above,
+the **Crusader** class costs ``$5``.
+
+Unbreakable weapons/armor
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The optional ``unbreakable-weapons`` and ``unbreakable-armor`` nodes can
+be used to toggle on or off the unbreakability of class items and armor.
+The nodes *default to true*, so they are really only necessary if you
+want to toggle OFF the feature, i.e. if you want items to deteriorate
+and break! If that's what you want, set the nodes to false.
+
+.. raw:: html
+
+   <pre>
+   classes:
+       FrailTank:
+           items: diamond_sword
+           armor: 310,311,312,313
+           <font color="blue">unbreakable-weapons: false</font>
+           <font color="blue">unbreakable-armor: false</font>
+   </pre>
+
+Per-class permissions
+~~~~~~~~~~~~~~~~~~~~~
+
+Using the optional ``permissions``-node, you can give classes special
+permissions to customize them even more. Each permission must be listed
+with a dash (-) in front of it. If you want a class to *not* have a
+permission, put a dash/minus at the very beginning of the permission
+node. In the example above, the **Archer** class will be able to use the
+EffectiveArrows plugin, but won't be able to use ``/ma leave`` (meaning
+it's impossible to leave the arena without dying).
+
+.. raw:: html
+
+   <pre>
+   classes:
+       Archer:
+           items: wood_sword, bow, arrow:128, grilled_pork
+           armor: 298,299,300,301
+           <font color="blue">permissions:</font>
+           <font color="blue">- EffectiveArrows.use.*</font>
+           <font color="blue">- -mobarena.use.leave</font>
+   </pre>
+
+The optional ``lobby-permissions``-node gives players special
+permissions while they are in the lobby *after they have picked a
+class*. This feature can be used e.g. in combination with a shop plugin
+and a base class that perhaps has nothing (maybe except for a few
+potions).
+
+.. raw:: html
+
+   <pre>
+   classes:
+       Basic:
+           items: ''
+           armor: ''
+           <font color="blue">lobby-permissions:</font>
+           <font color="blue">- shop.buy</font>
+   </pre>
+
+Pet classes
+~~~~~~~~~~~
+
+For every bone (Material name: ``bone``, data value: ``352``) in a
+class' items-list (or class chest), one wolf pet will spawn upon arena
+start. In the example above, every player that picks the **Wolf Master**
+class will have 2 wolves spawn upon arena start. The wolves are
+invincible, but deal less damage than normal wolves.
+
+.. raw:: html
+
+   <pre>
+   classes:
+       Wolf Master:
+           items: stone_sword, grilled_pork, <font color="blue">bone:2</font>
+           armor: 298,299,300,301
+   </pre>
+
+Mounts
+~~~~~~
+
+To give a class a horse mount, give it a hay block in the items-list (or
+place a hay block in the class chest). The item stack amount (in the
+first encountered stack) determines the variant and barding of the
+horse. You can use this table to figure out which hay block amount you
+need for your desired variant and barding:
+
++----------------+------------+------------+------------+---------------+
+|                | **None**   | **Iron**   | **Gold**   | **Diamond**   |
++================+============+============+============+===============+
+| **Horse**      | 1          | 9          | 17         | 25            |
++----------------+------------+------------+------------+---------------+
+| **Donkey**     | 2          | -          | -          | -             |
++----------------+------------+------------+------------+---------------+
+| **Mule**       | 3          | -          | -          | -             |
++----------------+------------+------------+------------+---------------+
+| **Skeleton**   | 4          | -          | -          | -             |
++----------------+------------+------------+------------+---------------+
+| **Zombie**     | 5          | -          | -          | -             |
++----------------+------------+------------+------------+---------------+
+
+Note that only normal horses can have barding.
+
+In the example above, every player that picks the **Crusader** class
+will have a white horse with gold barding upon arena start. The mounts
+are invincible.
+
+.. raw:: html
+
+   <pre>
+   classes:
+       Crusader:
+           items: iron_sword, <font color="blue">hay_block:17</font>
+           armor: 302,303,304,305
+   </pre>
+
+arenas
+------
+
+This section is by far the largest, and it is divided into several
+smaller branches. In the above example, ``default`` denotes the *name*
+of the default arena. This name can be altered, but it must contain no
+spaces (use underscores instead). The arena name is significant when a
+server has multiple arenas and no Master Lobby (will be featured later).
+Let's go over the different branches:
+
+settings
+~~~~~~~~
+
+The settings-branch is quite extensive, and besides the ``world``-node,
+it is basically just a bunch of toggles (on/off, true/false), though a
+few are number-based.
+
+-  ``prefix: <prefix>`` - An arena-specific prefix to use for
+   messages/announcements in this arena only. The default is the empty
+   string (``''``), which means the ``global-settings`` prefix will be
+   used.
+-  ``world: <name>`` - The name of the world the arena resides in.
+-  ``enabled: [true|false]`` - If false, players cannot join the arena.
+-  ``protect: [true|false]`` - If false, the arena will not be protected
+   from explosions and players breaking the blocks.
+-  ``entry-fee: [$<amount>|<item>:<amount>]`` - Follows the exact same
+   notation as the class items and rewards (read the [[Item and Reward
+   Syntax]]-page). ``$20`` will subtract 20 of whatever currency you use
+   from the players upon joining. ``$5, stick:2`` will require the
+   player to have 5 currency units and 2 sticks to join the arena. The
+   entry-fee will be refunded if the player leaves before the arena
+   starts.
+-  ``default-class: <class>`` - If non-empty, this class is
+   automatically assigned to players when they join the arena. The class
+   name must be all lowercase and with no spaces.
+-  ``clear-wave-before-next: [true|false]`` - If true, no monsters will
+   spawn before all monsters of the previous wave have been killed.
+-  ``clear-boss-before-next: [true|false]`` - If true, no new waves will
+   spawn before the current boss (if any) is dead.
+-  ``clear-wave-before-boss: [true|false]`` - If true, a boss wave will
+   not spawn until all previous monsters have been killed.
+-  ``auto-equip-armor: [true|false]`` - If true, armor pieces will
+   automatically be equipped upon class selection. Note that this does
+   not work if a class has more than 1 of an armor piece type.
+-  ``soft-restore: [true|false]`` - If true, all destroyed blocks will
+   be saved in a "repair list", which will be used to restore blocks at
+   arena end. No data is saved to the harddrive. Note that this setting,
+   if true, ignores the ``protect`` flag.
+-  ``soft-restore-drops: [true|false]`` - If true, blocks destroyed by
+   players will drop as items like they normally do (using pickaxes,
+   spades, etc.). Note that this makes it very easy for classes with
+   pickaxes to "mine the arena" and build forts.
+-  ``require-empty-inv-join: [true|false]`` - If false, players'
+   inventories will be saved upon joining, and restored upon
+   death/leaving.
+-  ``require-empty-inv-spec: [true|false]`` - If false, players can
+   spectate the arena without having to empty their inventories.
+-  ``hellhounds: [true|false]`` - If true, all pet wolves in the arena
+   will be in flames! This has no actual function, and is purely for the
+   cool-factor. Also useful for distinguishing enemy wolves and pet
+   wolves.
+-  ``pvp-enabled: [true|false]`` - If true, players can damage each
+   other in the arena.
+-  ``monster-infight: [true|false]`` - If false, monsters will no longer
+   damage each other.
+-  ``allow-teleporting: [true|false]`` - If false, all warping to and
+   from the arena region is blocked. Useful for preventing players from
+   summoning other players into the arena for help.
+-  ``spectate-on-death: [true|false]`` - If false, players will not get
+   warped to the spectator area, but instead be "kicked" from the arena
+   (essentially a forced /ma leave).
+-  ``auto-respawn: [true|false]`` - If false, players will be greeted
+   with the typical death screen upon dying in the arena, and will have
+   to click the respawn button to respawn. With this setting at false,
+   players will actually die in the arena, meaning plugins like Heroes
+   and mcMMO will properly trigger their resetting of internal data upon
+   respawn.
+-  ``share-items-in-arena: [true|false]`` - If false, players will not
+   be able to drop items in the arena.
+-  ``min-players: <amount>`` - Gives a lower limit on how many players
+   are required to start the arena. The default of ``0`` is the same as
+   ``1``, which means 1 or more players may start the arena. Note that
+   this feature is incompatible with ``auto-start-timer`` and
+   ``start-delay-timer``!
+-  ``max-players: <amount>`` - Gives an upper limit on how many players
+   may join the arena. The default of ``0`` means no limit.
+-  ``max-join-distance: <distance>`` - The maximum distance (in blocks)
+   from which players can join or spectate the arena. If 0 (default),
+   there is no limit, and players can join from any world. Note that the
+   distance is calculated from every corner of the arena region, and
+   that players not in the arena world won't be able to join or
+   spectate.
+-  ``first-wave-delay: <time>`` - The time (in seconds) before the first
+   wave of monsters upon arena start.
+-  ``wave-interval: <time>`` - The time (in seconds) between each new
+   wave of monsters. If clear-wave-before-next: true, this setting will
+   be ignored.
+-  ``final-wave: <number>`` - The number of the final wave before the
+   arena is force ended. This is useful if you want to set a cap on how
+   many waves an arena will have.
+-  ``monster-limit: <amount>`` - The maximum amount of monsters MobArena
+   is allowed to spawn for this arena. The next wave, if any, will not
+   spawn until there is room for more monsters.
+-  ``monster-exp: [true|false]`` - If true, monsters will drop
+   experience orbs. This is useful if you wish to give players the
+   ability to spend the gathered experience on enchants or something
+   else (using different plugins) during the session.
+-  ``keep-exp: [true|false]`` - If true, players will keep the
+   experience they gather in the arenas after death. This is useful if
+   you want to allow players to level up or gather experience in the
+   arenas. NOTE: If using ``display-waves-as-level`` or
+   ``display-timer-as-level``, set ``keep-exp`` to false.
+-  ``food-regen: [true|false]`` - If true, a full food bar will cause
+   players to regenerate health while in the arena. Note that this
+   potentially makes tank-like classes extremely overpowered, since
+   diamond armor (by default) coupled with a full food bar will make a
+   player very hard to kill.
+-  ``lock-food-level: [true|false]`` - If true, the food bar will be
+   locked for all players in the arena, meaning they will not end up
+   starving, and they will be able to sprint around as they please.
+-  ``player-time-in-arena: <time of day>`` - When set to anything but
+   world, this setting will freeze the apparent world time for players
+   in the arena to whatever value you set. This is useful for making
+   time-of-day themed arenas (e.g. constant night time for a cemetery,
+   broad daylight for a pirate ship). Valid values are: dawn, sunrise,
+   morning, midday, noon, day, afternoon, evening, sunset, dusk, night,
+   midnight.
+-  ``auto-ignite-tnt: [true|false]`` - If true, TNT will be
+   automatically ignited when placed. This is useful for preventing
+   Oddjob-like classes from forting.
+-  ``auto-start-timer: <time>`` - The time (in seconds) before the arena
+   will be force started after the first player has joined the lobby
+   (the default of 0 means deactivated or infinite time). Non-ready
+   players will be removed from the lobby. This setting is useful to
+   prevent ill-minded players from delaying or preventing other players
+   from starting the arena. Note that this feature is incompatible with
+   ``min-players``!
+-  ``start-delay-timer: <time>`` - The time (in seconds) before the
+   arena can be started after the first player has joined the lobby.
+   This setting is useful if you want to give your players a fixed
+   window of time to join the arena after the first player has joined,
+   so they can't just start it off right away. Note that this feature is
+   incompatible with ``min-players``!
+-  ``display-waves-as-level: [true|false]`` - When set to true, the
+   players' level counter (above the experience bar) will be used to
+   display the current wave number. If the wave announcements in the
+   announcements-file are silenced, this can be used to make a much less
+   "spammy" MobArena experience. NOTE: Do not use this if ``keep-exp``
+   is set to true!
+-  ``display-timer-as-level: [true|false]`` - When set to true, the
+   players' level counter (above the experience bar) will be used to
+   display the auto-start timer in the lobby. NOTE: Do not use this if
+   ``keep-exp`` is set to true!
+-  ``auto-ready: [true|false]`` - When set to true, players are
+   automatically flagged as ready when they pick a class. Useful for
+   arenas with many players where hitting an iron block becomes
+   difficult.
+-  ``use-scoreboards: [true|false]`` - Whether to use scoreboards in
+   MobArena or not.
+-  ``isolated-chat: [true|false]`` - When set to true, all chat messages
+   sent by arena players will be seen only by other arena players in the
+   same arena. The arena players will still be able to see chat messages
+   from other players on the server who aren't in an arena.
+-  ``global-end-announce: [true|false]`` - When set to true, MobArena
+   will announce the ``arena-end-global`` message (see
+   [[Announcements]]) to all players on the server when an arena ends.
+-  ``global-join-announce: [true|false]`` - When set to true, MobArena
+   will announce the ``arena-join-global`` message (see
+   [[Announcements]]) to all players on the server when the first player
+   joins an arena.
+
+waves
+~~~~~
+
+Please go to [[setting up the waves]] for more information.
+
+rewards
+~~~~~~~
+
+The rewards-section denotes which rewards the arena players can win in
+the arena. It uses the exact same item system as the classes-section
+does, so nothing new there. You can also specify monetary rewards if you
+use a major economy plugin (iConomy, BOSEconomy, Essentials Eco) in the
+notation ``$<amount>``.
+
+**Note:** YAML is picky about how you type your items. Make sure you
+read the short [[Item and Reward Syntax]]-page and fully understand it
+before you attempt to modify the config file!
+
+The waves-branch is broken into ``every``- and ``after``-branches. The
+``every``-branch denotes rewards that the players can receive *every* x
+waves (repeated). The ``after``-branch denotes rewards that the player
+can receive *after* wave x (only once) has started. Note that **only one
+reward** is picked at random from the list.
+
+In the following example, players will receive either four arrows or a
+gold bar every 3 waves (3, 6, 9, 12, etc.), and a diamond every 10 waves
+(10, 20, 30, etc.), as well as an iron tool on wave 7 (only on wave 7),
+a diamond sword on wave 19 (only on wave 19), and 200 currency units on
+wave 20:
+
+::
+
+    rewards:
+        waves:
+            every:
+                '3': arrow:4, gold_ingot
+                '10': diamond
+            after:
+                '7': iron_spade, iron_hoe, iron_axe, iron_pickaxe
+                '19': diamond_sword
+                '20': $200
+
+**Note:** The wave numbers **must be enclosed by apostrophes** (e.g.
+``'7':``, not ``7:``), or YAML will throw errors. If you aren't sure how
+to do it, just copy one of the other lines and change the wave number
+and the items.
+
+coords
+~~~~~~
+
+The coords-section does not exist when MobArena first generates the
+config-file. This is because the coordinates need to be set by the user
+*in-game*. See the in-game section for more details on how to set
+everything up. The coords-section consists of five key points, and an
+arbitrary amount of spawnpoints:
+
+-  ``p1`` and ``p2`` - These two points should span the entire arena
+   region (including spectator areas and the lobby associated with the
+   arena, if possible).
+-  ``l1`` and ``l2`` - [OPTIONAL] If the lobby can't properly reside
+   within the arena region for some reason, these two points should span
+   the lobby region.
+-  ``arena`` - This warp is where the players will be teleported upon
+   arena start.
+-  ``lobby`` - Where the players will be teleported upon joining the
+   arena.
+-  ``spectator`` - Where the players will be teleported upon death or
+   spectating.
+-  ``spawnpoints`` - A list of points where monsters can spawn from.
+
+Note that editing these points manually can have some very unhappy
+consequences. Always edit these points from within Minecraft to ensure
+that they are generated properly.

docs/user/setting-up-waves.rst

@@ -0,0 +1,493 @@
+################
+Setting up waves
+################
+
+**On this page:** \* `About
+Modules <./Setting-up-the-waves#wiki-about-modules>`__ \* `Wave
+Branches <./Setting-up-the-waves#wiki-wave-branches>`__ \* `Common
+Nodes <./Setting-up-the-waves#wiki-common-nodes>`__ \*
+```recurrent`` <./Setting-up-the-waves#wiki-recurrent-waves>`__ \*
+```single`` <./Setting-up-the-waves#wiki-single-waves>`__ \* `Wave
+Types <./Setting-up-the-waves#wiki-wave-types>`__ \*
+```default`` <./Setting-up-the-waves#wiki-default-waves>`__ \*
+```special`` <./Setting-up-the-waves#wiki-special-waves>`__ \*
+```swarm`` <./Setting-up-the-waves#wiki-swarm-waves>`__ \*
+```supply`` <./Setting-up-the-waves#wiki-supply-waves>`__ \*
+```upgrade`` <./Setting-up-the-waves#wiki-upgrade-waves>`__ \*
+```boss`` <./Setting-up-the-waves#wiki-boss-waves>`__ \* `A Sample
+Setup <./Setting-up-the-waves#wiki-sample-config-file-setup>`__
+
+**Note: If you are impatient, go to the bottom of this page for an
+example config-file setup to see what the waves could look like. Modify
+them as you please, but make sure to read this page before asking any
+questions!**
+
+Make sure to check out `Agnate's MobArena Bosses and Waves
+Thread <http://forums.bukkit.org/threads/mobarena-boss-and-wave-thread.31797/>`__
+if you need inspiration for adding some cool bosses to your arenas!
+
+About Modules
+-------------
+
+The new MobArena waves-system is extremely modular, meaning every time
+you plug in a new wave, you only have to provide the nodes required by
+the specific modules you are using. The modules can be broken into *wave
+branches* and *wave types*. The structure of the waves-section in
+config-file is the following:
+
+::
+
+        waves:
+            recurrent:                   <-- Wave branch
+                <wave name>:
+                    type: <wave type>    <-- Wave type
+                    frequency: #
+                    priority: #
+            single:                      <-- Wave branch
+                <wave name>:
+                    type: <wave type>    <-- Wave type
+                    wave: #
+
+Wave Branches
+-------------
+
+The waves are split into two branches, ``recurrent`` and ``single``.
+*Recurrent waves* (may) occur more than once (as in, they repeat), given
+a frequency (how often they occur) and a priority (how "important" they
+are, i.e. which wave should spawn if two recurrent waves clash). *Single
+waves* occur just once, on the given wave (and always occur over
+recurrent waves, should they clash).
+
+Common Nodes
+~~~~~~~~~~~~
+
+As you can see, the two branches have one thing in common, the
+``type``-node. Other than that, their other nodes differ. However, there
+are two additional nodes that can be used regardless of branch and type
+(doesn't work for boss waves, though):
+
+``amount-multiplier: <decimal value>`` (optional) minimum value of 0.1,
+this multiplier helps determine how many monsters spawn per wave
+(minimum 1). If 8 mobs are supposed to spawn, and the value is ``0.5``,
+only 4 mobs will spawn. If the value is ``3``, 24 will spawn.
+
+``health-multiplier: <decimal value>`` (optional) minimum value of 0.1,
+this multiplier helps determine the health for each monster in a wave.
+If a zombie spawns with the default of 20 health points and the value is
+``0.5``, the zombie will have 10 health points. If the value is ``4``,
+it will be 80 health points.
+
+These two common nodes can be used to greatly customize the difficulty
+of the monsters in each wave. If you want more monsters, just set the
+amount-multiplier higher than 1, and maybe adjust the health with the
+health-multiplier accordingly. If you want the monsters to be tougher to
+kill, just up the health-multiplier.
+
+An additional node can be used to help determine where enemies will
+spawn:
+
+``spawnpoints: <semi-colon separated list of spawnpoints>``
+
+For example, we can make a swarm wave spawn monsters only on spawns
+``5,53,198``, ``-16,54,185``, and ``-7,53,179`` if players are in range:
+
+::
+
+    swarm3:
+        type: swarm
+        wave: 11
+        monster: zombie_pigman
+        spawnpoints: 5,53,198; -16,54,185; -7,53,179
+
+Note that these spawnpoints must exist in the ``spawnpoints``-list of
+the ``coords``-section to work.
+
+Recurrent Waves
+~~~~~~~~~~~~~~~
+
+``type: [default|special|swarm|supply|upgrade|boss]`` (required)
+determines the wave type. Read the **Wave types** section further down
+for more details.
+
+``frequency: #`` (required) determines how often the wave will/can
+spawn. With a frequency of 1, the wave can potentially spawn on every
+single wave number. The implicit default waves in MobArena have a
+frequency of 1, and the implicit special waves have a frequency of 4,
+which means the default waves (can) spawn every wave, and the special
+waves (can) spawn every 4th wave.
+
+``priority: #`` (required) determines how "important" the wave is. If
+two recurrent waves clash, the wave with the highest priority will
+spawn. The implicit default waves in MobArena have a priority of 1, and
+the implicit special waves have a priority of 2, which means if the
+default and special waves clash, the special waves will spawn because
+their priority is higher.
+
+``wave: #`` (optional) determines the first wave number on which this
+wave can/will spawn. This is useful for offsetting waves with similar
+frequencies. Note that if no wave is specified, it will default to the
+value of the (required) frequency-node. The implicit default waves in
+MobArena have wave value of 1, and the implicit special waves have a
+wave value of 4 (same as the frequency), which means the default waves
+may begin spawning from wave 1, and the special waves may begin spawning
+from wave 4.
+
+Single Waves
+~~~~~~~~~~~~
+
+``type: [default|special|swarm|supply|upgrade|boss]`` (required)
+determines the wave type. Read the **Wave types** section further down
+for more details.
+
+``wave: #`` (required) determines the wave on which this wave *will*
+spawn. No matter what priority a recurrent wave have, if it clashes with
+a single wave, the single wave will always spawn instead of the
+recurrent waves. Single waves are good for extraordinary waves like
+"swarm" waves, "boss" waves or even normal waves with specific monster
+types, for instance.
+
+Wave Types
+----------
+
+All MobArena waves must specify a *wave type*, which must be either
+``default``, ``special``, ``swarm``, ``supply``, ``upgrade`` or
+``boss``. These different wave type modules introduce some new required
+and optional nodes. Note that no matter what the wave type is, any wave
+*must* adhere to the requirements of the wave branch (read above).
+
+Default Waves
+~~~~~~~~~~~~~
+
+Default waves are waves that spawn an amount of monsters picked
+semi-randomly from an optional list of monsters. The amount of monsters
+grow at a configurable (but optional) rate. If no growth or monster-list
+is specified, default waves will consist of 5 different monster types
+(zombie, skeleton, spider, creeper, wolf), all equally likely to spawn,
+spawned at the "old" growth rate (player count + wave number). Nodes:
+
+``growth: [old|slow|medium|fast|psycho]`` (optional) determines how fast
+the monster count grows with every wave. ``old`` means (player count +
+wave number), but the other four use a mathematical function to
+determine the monster count, also based on player count and wave number.
+See [[Formulas]] for more info.
+
+``monsters: <list of <monster>: <probability>>`` (optional) determines
+[[monster types]], and their individual probabilities of spawning on
+each wave. Note that the probabilities are just that, probabilities.
+They do not specify exact amounts, but only chance of spawning. The
+following sample will statistically spawn twice as many zombies as
+skeletons:
+
+::
+
+        monsters:
+            zombies: 10
+            skeletons: 5
+
+``fixed: [true|false]`` (optional) the probability values in the
+monsters list becomes amount values instead, such that the above wave
+will spawn exactly 10 zombies and 5 skeletons, regardless of player
+count and wave number.
+
+Special Waves
+~~~~~~~~~~~~~
+
+Special waves are waves that spawn *one type* of monster, and always a
+fixed amount. Unlike with *default waves*, the (optional) monster list
+with probabilities determines which monster out of the entire list
+should spawn. The monsters-node's notation is identical to that of
+*default waves*.
+
+``monsters: <list of <monster>: <probability>>`` (optional) determines
+[[monster types]], and their probabilities of spawning on each wave. The
+following sample will statistically spawn powered-creepers twice as
+often as slimes:
+
+::
+
+        monsters:
+            powered-creepers: 4
+            slimes: 2
+
+Swarm Waves
+~~~~~~~~~~~
+
+Like *special waves*, swarm waves spawn just *one type* of monster, but
+in a configurable (but optional) amount. The swarm wave monsters only
+have *1 health point*, meaning they will die with just one blow from
+anything. Their numbers are vast compared to default and special waves,
+however, so they may be a bit hard on some servers. Use with caution!
+
+``monster: <monster>`` (required) which [[monster types]] the swarm
+consists of. Note that this is different from special waves, in that
+only one type is specified, and no probability value.
+
+``amount: [low|medium|high|psycho]`` (optional) how many monsters should
+spawn. Defaults to low (which is still a lot). See [[Formulas]] for more
+info.
+
+Supply Waves
+~~~~~~~~~~~~
+
+These waves spawn one monster per player, and will drop a random item
+from a customized drop list (same notation as the class items). The
+monster list notation is identical to that of default and special waves.
+
+::
+
+        drops: grilled_pork, cooked_chicken, cooked_beef, cooked_fish:2
+
+Upgrade Waves
+~~~~~~~~~~~~~
+
+These waves don't spawn any monsters, but will give or upgrade items.
+The class names are optional (you don't have to give items to all
+classes), and it is possible to use the ``all`` identifier to specify
+items that will be given to all players regardless of class. The
+``give-all-items`` flag determines if all items in the list should be
+given, or just a random item off the list (like with rewards and supply
+waves).
+
+**Legacy setup**: In the following example, all players get a healing
+potion, and on top of that, all Archers get 64 arrows, and all Oddjobs
+get either 2 TNT or a Netherrack:
+
+::
+
+            upgrades:
+              all: potion:8197:1
+              Archer: arrow:64
+              Oddjob: tnt:2, netherrack
+            give-all-items: false
+
+**Advanced setup**: Since MobArena v0.95, the Upgrade Waves can be set
+up to upgrade/replace certain weapons and armor, as well as add/remove
+permissions. The setup follows the setup of the classes-section. In the
+following example, the Knight class gets its diamond sword enchanted and
+its iron chestplate replaced with a diamond chestplate. The Archer just
+gets some more arrows (legacy setup) while the Wizard class gets the
+permission to cast the Forcepush spell from MagicSpells:
+
+::
+
+    classes:
+      Knight:
+        armor: iron_helmet, iron_chestplate, iron_leggings, iron_boots
+        items: diamond_sword
+
+    ...
+
+    arenas:
+      ...
+        waves:
+          ...
+            upgrades:
+              Archer: arrow:64
+              Knight:
+                armor: diamond_chestplate
+                items: diamond_sword 16:2
+              Wizard:
+                permissions:
+                - magicspells.cast.forcepush
+            give-all-items: true
+
+Explanation: Items listed in the ``armor`` node will be considered
+armor, and (if valid) will replace any item currently in the armor slots
+of the players. Items in the ``items`` node will be checked if they are
+weapons or not; if they are weapons, then MobArena will search through
+the players' inventories for weapons with the same ID, and then replace
+the first weapon that matches it (automatic upgrades). If no weapon is
+found, it will default to a generic item, which will just be added to
+the inventory.
+
+Boss Waves
+~~~~~~~~~~
+
+Boss waves consist of *one monster* with a configurable (but optional)
+amount of health, and a configurable (but optional) list of special
+abilities. The health of a boss monster is significantly higher than
+that of normal monsters, and thus take much longer to kill. The special
+abilities help increase the difficulty (and fun!) of a boss wave.
+
+``monster: <monster>`` (required) the boss [[monster types]]. Note that
+only one monster will spawn.
+
+``name: <name>`` (optional) the name of the boss. Shows the given name
+in a name tag above the boss' head.
+
+``health: <amount>|[verylow|low|medium|high|veryhigh|psycho]``
+(optional) how much health the boss has. Can be either a flat value,
+e.g. 40 or 800, or one of the scaling values. Defaults to the scaling
+value medium. See [[Formulas]] for more info about the scaling values.
+
+``reward: <item>`` (optional) a reward for getting the killing blow on
+the boss. This reward will only be given to one player (the killer, if
+any).
+
+``drops: <item list>`` (optional) a comma-separated list of items
+dropped by the boss when killed. The boss will drop exactly the items
+listed. This could be used to have the boss drop a "key" to advance in
+the arena, or to gain access to a shed full of weapon chests or
+something wonderful like that. The item syntax is the same as the one
+for Supply Waves.
+
+``potions: <potion list>`` (optional) a comma-separated list of potion
+effects that will be applied to the boss when it spawns. Use this to
+slow down or speed up bosses that don't move at quite the speed you
+want, or perhaps to give a boss the wither effect to limit the amount of
+time it will stay alive. The potion syntax is
+``<effect>:<amplifier>:<seconds>``. The amplifier and duration are
+optional, and will default to 0 (level 1) and pseudo-infinity,
+respectively. Note that ``slow``, ``slow:0``, and ``slow:0:600`` are
+identical, except the last one will only last 10 minutes (600 seconds).
+Check the sample config-file at the bottom for more examples.
+
+``abilities: <comma-separated list of boss abilities>`` (optional)
+determines which (if any) boss abilities this boss has. The boss can
+have several abilities; just separate each ability with a comma (e.g.
+``arrows, fire-aura, throw-target``). Note that the abilities happen in
+a cycle every few seconds, so the more abilities, the longer it takes
+before each ability is used again. Here is an overview of the different
+abilities bosses can have:
+
+::
+
+        NAME                DESCRIPTION
+        arrows              Shoots arrows
+        fireballs           Hurls fireballs
+        fire-aura           Burns all nearby (5 blocks radius) players
+        lightning-aura      Strikes lightning 4 places around itself (3-block radius)
+        living-bomb         A random player is set on fire, and explodes after 3 seconds
+        obsidian-bomb       Spawns an Obsidian block which explodes after 4 seconds
+        chain-lightning     Lightning strikes the target and jumps to a nearby player
+        disorient-target    Spins the target around 45-315 degrees
+        disorient-nearby    Spins all nearby (5 blocks radius) players
+        disorient-distant   Spins all distant (8+ blocks) players
+        root-target         Locks the target in place for a couple of seconds
+        warp-to-player      Picks a random player in the arena to warp to
+        shuffle-positions   Swaps everyone's (including the boss) positions around
+        flood               Places a water block on a random player's location
+        throw-target        Throws the target backwards (if in distance)
+        throw-nearby        Throws all nearby (5 blocks radius) players
+        throw-distant       Throws all distant (8+ blocks) players
+        pull-target         Pulls the target towards the boss' location
+        pull-nearby         Pulls all nearby (5 blocks radius) players towards the boss' location
+        pull-distant        Pulls all distant (8+ blocks) players towards the boss' location
+        fetch-target        Warps the target to the boss' location
+        fetch-nearby        Warps all nearby (5 blocks radius) players to the boss' location
+        fetch-distant       Warps all distant (8+ blocks) players to the boss' location
+
+``ability-announce: [true|false]`` (optional) should boss abilities be
+announced to arena players? Defaults to true.
+
+``ability-interval: <seconds>`` (optional) time between each ability.
+Defaults to 3.
+
+Sample config-file setup
+------------------------
+
+If you want to try a sample setup, here's one that you can use. Simply
+copy this block of text, and paste it into your own config-file,
+replacing the waves-section.
+
+::
+
+            waves:
+                recurrent:
+                    def1:
+                        type: default
+                        priority: 1
+                        frequency: 1
+                        monsters:
+                            zombies: 10
+                            skeletons: 4
+                            exploding_sheep: 5
+                    def2:
+                        type: default
+                        priority: 2
+                        frequency: 1
+                        wave: 5
+                        monsters:
+                            zombies: 10
+                            skeletons: 6
+                            creepers: 4
+                    spec1:
+                        type: special
+                        priority: 5
+                        frequency: 4
+                        wave: 4
+                        monsters:
+                            powered_creepers: 10
+                            angry_wolves: 10
+                            zombie_pigmen: 10
+                    upgrade1:
+                        type: upgrade
+                        priority: 7
+                        frequency: 10
+                        wave: 10
+                        upgrades:
+                            all: potion:8197:2
+                            Archer: arrow:64
+                            Oddjob: tnt:2, netherrack
+                        give-all-items: true
+                single:
+                    swarm1:
+                        type: swarm
+                        wave: 7
+                        monster: slimes
+                        amount: medium
+                    boss1:
+                        type: boss
+                        wave: 9
+                        monster: spider
+                        health: medium
+                        abilities: fire-aura, disorient-target, fireballs, throw-nearby
+                        potions: speed:3:20, wither, increase_damage:1
+                        ability-interval: 5
+                    boss2:
+                        type: boss
+                        wave: 13
+                        monster: zombie_pigman
+                        health: high
+                        abilities: root-target, arrows, fetch-distant, fire-aura
+                        drops: lever, stone_button
+                    upgrade2:
+                        type: upgrade
+                        wave: 14
+                        upgrades:
+                            all: potion:8197:2
+                            Knight:
+                                armor: diamond_helmet
+                                items: diamond_sword 16:2;19:1
+                            Tank:
+                                items: iron_sword 19:3
+                            Oddjob:
+                                armor: iron_chestplate, iron_leggings
+                            Wizard:
+                                permissions:
+                                - magicspells.cast.ChainLightning
+                        give-all-items: true
+                    boss3:
+                        type: boss
+                        wave: 16
+                        monster: wolf
+                        health: psycho
+                        abilities: warp-to-player, fire-aura, throw-nearby, fireballs, fetch-target, arrows
+                        potions: slow:1
+                        ability-interval: 1
+                        reward: diamond_chestplate
+                    supply1:
+                        type: supply
+                        wave: 19
+                        monsters:
+                            cows: 10
+                            pigs: 5
+                        drops: grilled_pork, cooked_chicken, cooked_beef, cooked_fish:2
+                    boss4:
+                        type: boss
+                        wave: 20
+                        monster: blaze
+                        health: low
+                        abilities: fire-aura, throw-nearby
+                        potions: speed
+                        reward: diamond_helmet

docs/user/using-mobarena.rst

@@ -0,0 +1,137 @@
+##############
+Using MobArena
+##############
+
+**On this page:** \* `Overview <#overview>`__ \* `Joining <#joining>`__
+\* `Getting a list of arenas <#getting-a-list-of-arenas>`__ \* `Picking
+a class <#the-class-command>`__ \* `Finding out who isn't
+ready <#finding-out-who-isnt-ready>`__ \* `Leaving <#leaving>`__ \*
+`Spectating <#spectating>`__ \* `A note on
+inventories <#a-note-on-inventories>`__
+
+Overview
+~~~~~~~~
+
+This page briefly describes the usage-commands of MobArena. Make sure to
+check out the [[MobArena Commands]] page for a list of all the commands.
+Remember that typing ``/ma help`` will get you a list of all available
+commands in-game, along with a (very) brief description of what the
+command does.
+
+The commands covered on this page pertain to the usage-commands only,
+i.e. the commands that the players will use to interact with MobArena.
+The most basic commands are:
+
+-  ``/ma join`` - for `joining <#joining>`__ arenas to start playing
+-  ``/ma leave`` - for `leaving <#leaving>`__ lobbies or arenas
+-  ``/ma spec`` - for `spectating <#spectating>`__ arenas in progress
+-  ``/ma arenas`` - for getting a `list of
+   arenas <#getting-a-list-of-arenas>`__
+
+Additionally, there are a few commands that might prove useful:
+
+-  ``/ma class`` - for `picking classes <#the-class-command>`__ in the
+   lobby instead of punching signs
+-  ``/ma notready`` - for finding out `who isn't ready
+   yet <#finding-out-who-isnt-ready>`__
+
+Joining
+~~~~~~~
+
+To join an arena, use the ``/ma join`` command. If you have more than
+one arena, you will also need to specify an arena name. Let's say we
+have arenas ``cave`` and ``ship``. To join the Ship arena, simply type
+``/ma join ship``.
+
+Upon joining, you will be taken to the lobby of the given arena. In the
+lobby, you will have to pick a class, which is traditionally done by
+punching a sign with a class name on it. You can also `use a
+command <#the-class-command>`__ directly to manually pick a class if you
+know its name, or indirectly via buttons powering command blocks, or
+perhaps something more complex (like NPCs).
+
+Once you've picked a class, you will need to ready up, which is
+traditionally done by punching an iron block. However, there is also a
+per-arena config-file setting that automatically flags you as ready once
+you've picked a class (check the [[Setting up the config-file]] page).
+
+Getting a list of arenas
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+To get a list of available arenas, you simply type ``/ma arenas``.
+Arenas that have been set up and are ready for use will be green, and
+unavailable arenas (disabled or not yet set up) will be gray. Note that
+you won't see arenas for which you don't have permission, just like you
+won't be able to actually join an arena for which you don't have
+permission. Check the [[Permissions]] page for more information.
+
+The class command
+^^^^^^^^^^^^^^^^^
+
+Normally, you would punch class signs to pick classes, but MobArena also
+supports picking a class with the ``/ma class`` command. If you want to
+pick the Knight class, for example, simply type ``/ma class knight``.
+Forcing manual class selection like this is not recommended, because
+it's unintuitive and there is no way of listing available classes.
+Instead, this command is useful if you want to set up command blocks or
+something more advanced like NPCs wearing the class items and armor, and
+allowing players to pick the class by interacting with the NPCs.
+
+Finding out who isn't ready
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes it's hard to keep track of who hit the iron block and who
+didn't. To figure out which of the players in the lobby have not yet
+readied up, you can use the ``/ma notready`` command. This is useful if
+everyone thinks they've readied up and are waiting for everyone else,
+but in fact one or more people haven't readied up yet.
+
+Leaving
+~~~~~~~
+
+When you're done playing in the arena, you have to leave it with the
+``/ma leave`` command (unless the ``spectate-after-death`` setting in
+the config-file is set to ``false``, in which case the command will be
+executed for you). You may also leave the lobby of an arena you didn't
+actually want to join, or if you just don't want to play anymore, and
+you don't want to wait for death.
+
+Leaving an arena in progress has no consequences other than missing out
+on the fun! You'll still be given the rewards you earned up to this
+point. If you don't want your players to be able to leave arenas in
+progress, you can revoke the permission on a per-class basis. See the
+[[Setting up the config-file]] page for more information.
+
+Spectating
+~~~~~~~~~~
+
+If you want to spectate an arena already in progress, use the
+``/ma spec`` command, just like you would use the ``/ma join`` command.
+Spectating an arena means you will be taken to the spectator area of the
+arena so you have a great overlook of the arena.
+
+Spectators cannot interact with the arena players or the monsters in the
+arena, nor with each other, so there should be no hooligan fights
+whatsoever.
+
+Note that when you die in an arena, you will automatically become a
+spectator, unless ``spectate-after-death`` is set to ``false``.
+
+A note on inventories
+~~~~~~~~~~~~~~~~~~~~~
+
+Once you have joined an arena, either for playing or for spectating, you
+are considered as *in the arena*. What this means is that MobArena will
+hold on to your inventory until you leave. You leave by typing
+``/ma leave``, either from the lobby or the arena, or after you've died.
+If the ``spectate-after-death`` option in the config-file is ``false``,
+you are automatically kicked out of the arena when you die, so in that
+case, you won't have to do anything.
+
+Inventories are stored on a per-player basis until they leave. Joining a
+new arena (or the same arena again) after finishing a session will not
+cause your inventory to be overwritten, even though it seems like you
+have no items. When you leave with the ``/ma leave`` command, all of
+your earned rewards from all sessions since you first joined will be
+granted. Of course, with ``spectate-after-death`` set to ``false``, you
+will automatically leave after every session.

docs/user/wave-forumulas.rst

@@ -0,0 +1,92 @@
+#############
+Wave formulas
+#############
+
+This page holds an overview of all the formulas used in the MobArena
+waves system. Customizing the different properties of the waves should
+be somewhat easier if they can be calculated, so here they all are!
+
+About notation: Each variable used in the formulas will have its own
+name. A variable that starts with a ``#`` denotes "number (of)", so
+``#players`` means "number of players", and ``#wave`` means "wave
+number". The function ``min(a,b)`` returns the lowest of the values
+``a`` and ``b``, and ``max(a,b)`` returns the highest.
+
+Wave growth
+~~~~~~~~~~~
+
+The wave growth node ``growth``, used in default waves, denotes how fast
+monster amounts grow over time. The base is calculated by half of the
+number of players, but at most 13 (i.e. there is no difference between
+25 and 50 players). The amounts can be altered further using the
+``amount-multiplier`` (see the [[wave setup page\|Setting up the
+waves]]).
+
+::
+
+    #monsters = base * #wave^exp
+    base = min(#players/2 + 1 , 13)
+
+The ``exp`` variable is defined by the growth node, and has the
+following values:
+
+::
+
+    slow   = 0.5
+    medium = 0.65
+    fast   = 0.8
+    psycho = 1.2
+
+Note that with the node value ``old`` (which is the default), the
+monster count is ``#wave + #players``.
+
+Swarm Amount
+~~~~~~~~~~~~
+
+The swarm amount node ``amount``, used in swarm waves, denotes how many
+monsters should spawn in the swarm waves. There will always be at least
+10 monsters due to the max function and the lowest multiplier value
+being 10, however this can be further customized with the
+``amount-multiplier`` (see the [[wave setup page\|Setting up the
+waves]]).
+
+::
+
+    #monsters = max(1, #players/2) * multiplier
+
+The ``multiplier`` variable is defined by the amount node, and has the
+following values:
+
+::
+
+    low    = 10
+    medium = 20
+    high   = 30
+    psycho = 60
+
+Boss Health
+~~~~~~~~~~~
+
+The boss health node ``health``, used in boss waves, denotes how much
+health the boss has. Note that the ``health-multiplier`` node (see the
+[[wave setup page\|Setting up the waves]]) **does NOT** affect boss
+waves at all, so these are the only values that can be used. The minimum
+health a boss can have is 320 health points (~160 hearts), which is with
+``low`` health and only 1 player fighting. With 10 players and ``high``
+health, the boss will have 5500 health points (~2750 hearts).
+
+::
+
+    health = (#players + 1) * 20 * multiplier
+
+The ``multiplier`` variable is defined by the health node, and has the
+following values:
+
+::
+
+    verylow   = 4
+    low       = 8
+    medium    = 15
+    high      = 25
+    veryhigh  = 40
+    psycho    = 60