\documentclass[12pt]{article}
\usepackage{a4wide}
\usepackage{fancyvrb}
\usepackage{url}

\newcommand{\hexValue}[1]{\texttt{#1}}
\newcommand{\xmlNode}[1]{\texttt{#1}}
\newcommand{\xmlProp}[1]{\texttt{#1}}
\newcommand{\xmlPropValue}[1]{\texttt{"#1"}}

\DefineVerbatimEnvironment{Code}{Verbatim}{frame=single, framesep=2mm, numbers=left, fontsize=\small}

\begin{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{abstract}
This document describes the map and level file format for MOAGG.
If you want to create own levels,
download moaggedit from \url{http://moagg.sourceforge.net/}
and take a closer look at section~\ref{sec:level},
since the XML-part of a level has to be written by hand.
\end{abstract}

%=============================================================================
\section{Introduction}
\label{sec:intro}

A level consists of a map file and an XML-file,
describing decorative and game-specific items
(obstacles, landing platforms, crates).
Further, the XML-file contains a \xmlNode{gamecontrol} node that describes,
what has to be done to complete the level.
The map data is seperated from the level data.
This way, a map file can be reused in different levels.

%=============================================================================
\section{Map File}
\label{sec:map}

The map of each level is divided into tiles, 16x16 pixel each.
Tiles are grouped into categories, which are listed in a category index file.

%-----------------------------------------------------------------------------
\subsection{Category Index File Format}

The category index file is an ASCII file,
mapping a particular category index to a tile index file.
Empty lines or lines starting with a \texttt{\#} are ignored.

\begin{Code}
# The categories file.
xx file
xx file
...
\end{Code}

\begin{description}
\item[xx]
  The category index as hex-code (\hexValue{00} - \hexValue{ff}).
  Thus, there are 256 possible categories.
\item[file]
  The name of the tile index file.
\end{description}

For version 1 of the map format,
the category \hexValue{00} (background) is reserved for background tiles.
All these tiles will be blitted like the tiles in all other categories,
but the game's collision detection will handle them as "transparent".
For version 2 (or higher), the category \hexValue{00} shall not be used
for compatibility reasons.

The category \hexValue{ff} (transparent) is reserved for tiles,
that will be handled like background tiles, but blitted half transparent.
It also shall not be used for version 2 (or higher).

%-----------------------------------------------------------------------------
\subsection{Tile Index File Format}

The tile index file is an ASCII file,
mapping a particular tile index to an image file.
Empty lines or lines starting with a \texttt{\#} are ignored.

\begin{Code}
# The tiles file for one category.
xx file
xx file
...
\end{Code}

\begin{description}
\item[xx]
  The tile index as hex-code (\hexValue{00} - \hexValue{ff}).
  Thus, each category can contain 256 tiles.
\item[file]
  The name of the image file for the tile.
\end{description}

%-----------------------------------------------------------------------------
\subsection{Map File Format}

Each map is stored as binary file.
Meanwhile, there are two versions of the map file format.
which will be described in the following subsections,
where each character represents one octet in the file.

%-----------------------------------------------------------------------------
\subsubsection{Version 1}

\begin{Code}
vxxyylcttt...cttt...
\end{Code}

\begin{description}
\item[v]
  The file version (must be \hexValue{0x01}).
\item[xx]
  A big-endian uint16\_t defining the number of tiles in the x axis.
\item[yy]
  A big-endian uint16\_t defining the number of tiles in the y axis.
\item[l]
  The number of layers (must be greater or equal than \hexValue{0x01}).
\item[c]
  The tile category of the current layer.
\item[ttt...]
  The indices of the tiles, starting from the upper left corner
  to the lower right corner line by line.
  Each layer must contain exactly \(xx \cdot yy\) t-octets.
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Version 2}

\begin{Code}
vxxyylcBabttt...cBabttt...
\end{Code}

\begin{description}
\item[v]
  The file version (must be \hexValue{0x02}).
\item[xx]
  A big-endian uint16\_t defining the number of tiles in the x axis.
\item[yy]
  A big-endian uint16\_t defining the number of tiles in the y axis.
\item[l]
  The number of layers (must be greater or equal than \hexValue{0x01}).
\item[c]
  The tile category of the current layer.
\item[B]
  \hexValue{0x01} if the current layer shall be handled as background
  (and thus is ignored for the collision handling), else \hexValue{0x00}.
\item[a]
  The alpha value of the current layer,
  reaching from \hexValue{0x00} (fully transparent)
  to \hexValue{0xff} (fully opaque).
\item[b]
  The brightness of the current layer,
  reaching from \hexValue{0x00} (all non-background pixels are black)
  over \hexValue{0x80} (normal brightness level)
  to \hexValue{0xff} (all non-background pixels are white).
\item[ttt...]
  The indices of the tiles, starting from the upper left corner
  to the lower right corner line by line.
  Each layer must contain exactly \(xx \cdot yy\) t-octets.
\end{description}


%=============================================================================
\pagebreak
\section{XML Level File}
\label{sec:level}

This section describes the XML format used for all levels.

%-----------------------------------------------------------------------------
\subsection{Common Content}

\begin{Code}
<level>
  <description>
...
  </description>

  <bonus .../>

  <playground map="level.map">
    <gravity>
      ...
    </gravity>
    <decorations>
      ...
    </decorations>
  </playground>

  <startposition .../>

  <gamecontrol>
    ...
  </gamecontrol>
</level>
\end{Code}

%-----------------------------------------------------------------------------
\subsubsection{The description node}

When starting a level, the text within the \xmlNode{description} node
will be shown in a pop-up window.
If this node is omitted, the level will start immediately.
Note, that newlines and leading spaces in the text will be displayed as is.

%-----------------------------------------------------------------------------
\subsubsection{Properties for the bonus node}

\begin{description}
\item[initial:] The initial bonus, when starting the level.
\item[decrement:] The bonus decrement amount.
\item[delay (opt):] The delay between two decrements 
  in tenth of a seconds (default = 10).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Structure of the playground node}

\begin{description}
\item[map:] Define the map file to use for this level.
\item[gravity (opt):] The child nodes of the optional \xmlNode{gravity} node
  are used to override the default settings of the gravity field.
\item[decorations:] This mandatory node contains all decoration objects,
  that shall be part of the level.
\end{description}

%-----------------------------------------------------------------------------
\subsection{Structure of the gravity node}

The optional \xmlNode{gravity} node has no properties.
The meaning and content of the possible child nodes
(which are all optional too) are described in the following subsections.

%-----------------------------------------------------------------------------
\subsubsection{Global gravity fields}

\begin{Code}
  <global .../>
\end{Code}

The \xmlNode{global} node defines the gravity settings
for the whole playground.
There should be only one \xmlNode{global} node
and it should be given as first node.

\begin{description}
\item[gx (opt):] The gravity in x direction (default = 0).
\item[gy (opt):] The gravity in y direction (default = 100).
\item[vx (opt):] The stream velocity in x direction (default = 0).
\item[vy (opt):] The stream velocity in y direction (default = 0).
\item[friction (opt):] The friction (default = 50).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Relative gravity fields}

\begin{Code}
  <relative .../>
\end{Code}

The \xmlNode{relative} node represents a local gravity field
within a rectangular area, which values will be added
to the currently existing gravity settings in this area.

\begin{description}
\item[x:] The x position of the local gravity field.
\item[y:] The y position of the local gravity field.
\item[w:] The width of the local gravity field.
\item[h:] The height of the local gravity field.
\item[gx (opt):] The gravity in x direction (default = 0).
\item[gy (opt):] The gravity in y direction (default = 0).
\item[vx (opt):] The stream velocity in x direction (default = 0).
\item[vy (opt):] The stream velocity in y direction (default = 0).
\item[friction (opt):] The friction (default = 0).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Absolute gravity fields}

\begin{Code}
  <absolute .../>
\end{Code}

The \xmlNode{absolute} node represents a local gravity field
similar to the \xmlNode{relative} node.
The only difference is, that the \xmlNode{absolute} node
will overwrite the current values of the gravity field
inside the given rectangular area.

%-----------------------------------------------------------------------------
\subsection{List of decoration objects}

This section describes all decoration objects,
that can be used inside the \xmlNode{decorations} node of the playground.
Every object listed here may have a unique \xmlProp{id} property,
which value must lie between 1 and 1023.
This \xmlProp{id} can then be referred in the content
of the \xmlNode{gamecontrol} node to define particular objectives,
that must be solved by the player.
If the \xmlProp{id} property is omitted,
an \xmlProp{id} with a value greater or equal than 1024
will be generated automatically.
However, these objects cannot be refered by the \xmlNode{gamecontrol}.

Further, every declared object can define the \xmlProp{hide} property.
If set to \xmlPropValue{true}, the object will be invisible at startup
of the level.
It then may be activated during the game using the \xmlProp{show} event
of an event handler (see section~\ref{sec:eventhandlers}).

%-----------------------------------------------------------------------------
\subsubsection{Platforms}

\begin{Code}
  <platform .../>
\end{Code}

\begin{description}
\item[x:] The x position of the platform.
\item[y:] The y position of the platform.
\item[w:] The width of the platform.
\item[left (opt):] The type of the left edge
  (\xmlPropValue{red}, \xmlPropValue{yellow}, \xmlPropValue{green},
  \xmlPropValue{cyan}, \xmlPropValue{blue}, \xmlPropValue{magenta},
  \xmlPropValue{fuel},
  or a number between \xmlPropValue{0} and \xmlPropValue{9}).
  If omitted, no edge will be drawn on the left side.
\item[right (opt):] The type of the right edge
  (\xmlPropValue{red}, \xmlPropValue{yellow}, \xmlPropValue{green},
  \xmlPropValue{cyan}, \xmlPropValue{blue}, \xmlPropValue{magenta},
  \xmlPropValue{fuel},
  or a number between \xmlPropValue{0} and \xmlPropValue{9}).
  If omitted, no edge will be drawn on the right side.
\item[fuel (opt):] If \xmlPropValue{true}, the platform is a fuel platform.
  If omitted, a default value of \xmlPropValue{false} is used.
\item[fuel_cost (opt):] If the platform is a fuel platform,
  refueling the ship will cost this amount of points per second.
  If omitted, a default value of \xmlPropValue{20} is used.
\end{description}

If the \xmlProp{fuel} property is set to \xmlPropValue{true}
or the \xmlProp{right} or \xmlProp{left} property is set to 
\xmlPropValue{fuel}, the platform is declared as fuel platform.
If the player's ship lands on it, it's fuel will be refilled.
However, refilling will cost a particular amount of points per second.

%-----------------------------------------------------------------------------
\subsubsection{Magnets}

\begin{Code}
  <magnet .../>
\end{Code}

\begin{description}
\item[orientation:] The orientation of the magnet
  (\xmlPropValue{top}, \xmlPropValue{bottom},
  \xmlPropValue{left}, or \xmlPropValue{right}).
\item[x:] The x position of the magnet.
\item[y:] The y position of the magnet.
\item[w/h:] The width/height of the magnet.
  Depending on the orientation of the magnet,
  only the \xmlProp{w} or \xmlProp{h} property shall exist.
\item[on (opt):] The time in seconds, the magnet is activated.
\item[off (opt):] The time in seconds, the magnet is deactivated.
\item[delay (opt):] The initial delay time in seconds,
  before the magnet is activated.
\item[activated (opt):] If given, the properties \xmlProp{on}, \xmlProp{off}
  and \xmlProp{delay} are ignored and the given bool value indicates,
  if the magnet is activated or deactivated.
  This property only makes sense together with the \xmlProp{activate}
  and \xmlProp{deactivate} event described in section~\ref{sec:eventhandlers}.
\item[strength (opt):] The strength of the magnetic field (default = 100).
\item[distance (opt):] The distance of the field (default = 5).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Particle Fountains}

\begin{Code}
  <fountain .../>
\end{Code}

\begin{description}
\item[orientation:] The orientation of the fountain
  (\xmlPropValue{top}, \xmlPropValue{bottom},
  \xmlPropValue{left}, or \xmlPropValue{right}).
\item[x:] The x position of the fountain.
\item[y:] The y position of the fountain.
\item[on (opt):] The time in seconds, the fountain is activated.
\item[off (opt):] The time in seconds, the fountain is deactivated.
\item[delay (opt):] The initial delay time in seconds,
  before the fountain is activated.
\item[speed (opt):] The initial particle speed (default = 40).
\item[lifetime (opt):] The particle lifetime in seconds (default = 1).
\item[scatter (opt):] The particle scatter factor (default = 20).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Turrets}

\begin{Code}
  <turret ...>
    <barrel .../>
    ...
  </turret>
\end{Code}

\begin{description}
\item[orientation:] The orientation of the turret
  (\xmlPropValue{top}, \xmlPropValue{bottom},
  \xmlPropValue{left}, or \xmlPropValue{right}).
\item[x:] The x position of the turret.
\item[y:] The y position of the turret.
\item[type:] The type of the turret
  (\xmlPropValue{tube} or \xmlPropValue{dome}).
\item[hitpoints (opt):] The number of shots needed
  to destroy this turret (default = 10).
\item[preset (opt):] A preset for this turret (see below).
\end{description}

Each turret must contain at least one \xmlNode{barrel}.
Each \xmlNode{barrel} contains the following properties:
\begin{description}
\item[type:] The type of the barrel:
  \begin{description}
  \item[fixed:] Always shoot at a fixed angle.
    The \xmlProp{angle} property is mandatory here.
  \item[sweep:] Sweep the angle to shoot.
    The \xmlProp{step} property is mandatory here.
  \item[random:] Fire at a random angle.
  \item[smart:] Fire directly to the player's ship.
  \end{description}
\item[angle (opt):] The relative angle to shoot for fixed barrels
  (default = 0).
\item[step (opt):] The angle step for sweep barrels (default = 0).
\item[speed (opt):] The projectile speed (default = 200).
\item[delay (opt):] The delay between two shots in tenth of a second
  (default = 20).
\end{description}

Optionally, the properties and barrels of a \xmlNode{turret} can be defined
to hard-coded values using the \xmlProp{preset} property.
The following values are defined:
\begin{description}
\item[mark1:] Defines \xmlProp{type}=\xmlPropValue{tube}
  and a single \xmlNode{barrel} with \xmlProp{type}=\xmlPropValue{fixed}.
\item[mark1b:] Defines \xmlProp{type}=\xmlPropValue{tube}
  and a single \xmlNode{barrel} with \xmlProp{type}=\xmlPropValue{fixed},
  \xmlProp{speed}=\xmlPropValue{250} and \xmlProp{delay}=\xmlPropValue{15}.
\item[mark1c:] Defines \xmlProp{type}=\xmlPropValue{tube}
  and a single \xmlNode{barrel} with \xmlProp{type}=\xmlPropValue{fixed},
  \xmlProp{speed}=\xmlPropValue{300} and \xmlProp{delay}=\xmlPropValue{10}.
\item[dome1:] Defines \xmlProp{type}=\xmlPropValue{dome}
  and a single \xmlNode{barrel} with \xmlProp{type}=\xmlPropValue{smart}.
\item[dome1b:] Defines \xmlProp{type}=\xmlPropValue{dome}
  and a single \xmlNode{barrel} with \xmlProp{type}=\xmlPropValue{smart},
  \xmlProp{speed}=\xmlPropValue{250} and \xmlProp{delay}=\xmlPropValue{15}.
\item[dome1c:] Defines \xmlProp{type}=\xmlPropValue{dome}
  and a single \xmlNode{barrel} with \xmlProp{type}=\xmlPropValue{smart},
  \xmlProp{speed}=\xmlPropValue{300} and \xmlProp{delay}=\xmlPropValue{10}.
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Mortars}

\begin{Code}
  <mortar ...>
    <barrel .../>
    ...
  </mortar>
\end{Code}

\begin{description}
\item[orientation:] The orientation of the mortar
  (\xmlPropValue{top}, \xmlPropValue{bottom},
  \xmlPropValue{left}, or \xmlPropValue{right}).
\item[x:] The x position of the mortar.
\item[y:] The y position of the mortar.
\item[hitpoints (opt):] The number of shots needed
  to destroy this mortar (default = 10).
\end{description}

Each mortar must contain at least one \xmlNode{barrel}.
Each \xmlNode{barrel} contains the following properties:
\begin{description}
\item[type:] The type of the barrel:
  \begin{description}
  \item[fixed:] Always shoot to a fixed angle.
    The \xmlProp{angle} property is mandatory here.
  \item[random:] Fire to a random angle.
  \item[smart:] Fire directly to the player's ship.
  \end{description}
\item[warhead:] The type of warhead for the grenades:
  \begin{description}
  \item[none:] After the exploder delay,
    the grenade will explode without creating any projectiles.
  \item[starburst:] After the exploder delay, the grenade will explode,
    unleashing several projectiles flying in all directions.
  \end{description}
\item[angle (opt):] The relative angle to shoot for fixed barrels
  (default = 0).
\item[speed (opt):] The grenade speed (default = 200).
\item[delay (opt):] The delay between two shots in tenth of a second
  (default = 20).
\item[exploderdelay (opt):] The delay after a grenade will explode
  in tenth of a second (default = 10).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Black Holes}

\begin{Code}
  <blackhole .../>
\end{Code}

\begin{description}
\item[x:] The x position of the black hole.
\item[y:] The y position of the black hole.
\item[gavity (opt):] The gravity of the black hole (default = 2000).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Laser Barriers}

\begin{Code}
  <barrier .../>
\end{Code}

\begin{description}
\item[x:] The x position of the barrier.
\item[y:] The y position of the barrier.
\item[w/h:] The width/height of the barrier.
  Only the \xmlProp{w} or \xmlProp{h} property shall exist.
\item[on (opt):] The time in seconds, the barrier is activated.
\item[off (opt):] The time in seconds, the barrier is deactivated.
\item[delay (opt):] The initial delay time in seconds,
  before the barrier is activated.
\item[activated (opt):] If given, the properties \xmlProp{on}, \xmlProp{off}
  and \xmlProp{delay} are ignored
  and the given bool value indicates,
  if the barrier is activated or deactivated.
  This property only makes sense together with the \xmlProp{activate}
  and \xmlProp{deactivate} event described in section~\ref{sec:eventhandlers}.
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{SAM Batteries}

\begin{Code}
  <sam .../>
\end{Code}

\begin{description}
\item[orientation:] The orientation of the SAM battery
  (\xmlPropValue{top}, \xmlPropValue{bottom},
  \xmlPropValue{left}, or \xmlPropValue{right}).
\item[x:] The x position of the SAM battery.
\item[y:] The y position of the SAM battery.
\item[hitpoints (opt):] The number of shots needed
  to destroy this SAM battery (default = 10).
\item[delay (opt):] The time between two missile launches in seconds
  (default = 5).
\item[fuel (opt):] The fuel for each missile in seconds (default = 5).
\item[heading:] The type of heading for the missiles:
  \begin{description}
  \item[direct:] The missile always heads directly to the player's ship.
  \item[smart:] Same as \xmlPropValue{direct}, but additionally the missile
    tries to compensate the effect of gravity.
  \end{description}
\item[warhead:] The type of warhead for the missiles:
  \begin{description}
  \item[normal:] The missile will explode only if it hits something.
  \item[coneburst:] The missile will explode near the player's ship,
    unleashing several projectiles flying inside an angle of 90 degrees.
  \item[starburst:] The missile will explode near the player's ship,
    unleashing several projectiles flying in all directions.
  \end{description}
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Switches}

\begin{Code}
  <switch .../>
\end{Code}

\begin{description}
\item[orientation:] The orientation of the switch
  (\xmlPropValue{top}, \xmlPropValue{bottom},
  \xmlPropValue{left}, or \xmlPropValue{right}).
\item[x:] The x position of the switch.
\item[y:] The y position of the switch.
\item[toggle:] A comma-seperated list of object \xmlProp{id}s to toggle.
  The list may also contain id-ranges (e.g. \xmlPropValue{10-15}).
\end{description}

Switches can be used to toggle the given objects,
when they are hit by a missile, grenade or projectile.
Note, that only barriers and magnets can be toggled.

%-----------------------------------------------------------------------------
\subsubsection{Crates}

\begin{Code}
   <crate type="small" x="5" y="10"/>
\end{Code}

\begin{description}
\item[type:] The type of the crate:
  \begin{description}
  \item[small, medium, or big:] Types for crates to be rescued.
  \item[bonus:] When picked up, add bonus points to the score.
  \item[fuel:] When picked up, refill the player's fuel.
  \end{description}
\item[x:] The x position of the crate.
\item[y:] The y position of the crate.
\item[value (opt):] The bonus score, only for bonus crates (default = 100).
\item[amount (opt):] The fuel capacity in seconds to add, only for fuel crates
  (default = 0, which will recharge the fuel completely).
\end{description}

You have to keep sure, that all defined crates lie on a \xmlProp{platform}.
Otherwise, the player won't be able to pick them up.

%-----------------------------------------------------------------------------
\subsubsection{Grinders}

\begin{Code}
  <grinder ...>
    <waypoint .../>
    <waypoint .../>
    ...
  </grinder>
\end{Code}

\begin{description}
\item[velocity (opt):]
  The velocity of the grinder in pixels per second (default = 100).
\end{description}

Each \xmlNode{grinder} must contain at least two \xmlNode{waypoint} nodes.
The first \xmlNode{waypoint} is used as initial position.
Each \xmlNode{waypoint} must contain the following properties:
\begin{description}
\item[x:] The x position of the waypoint.
\item[y:] The y position of the waypoint.
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Tanks}

\begin{Code}
  <tank .../>
\end{Code}

\begin{description}
\item[x:] The x position of the tank's left margin.
\item[y:] The y position of the tank (which keeps constant).
\item[w:] The width of the tank's margin, relative to the left margin.
\item[type:] The type of shooting:
  \begin{description}
  \item[random:] Fire to a random angle.
  \item[smart:] Fire directly to the player's ship.
  \end{description}
\item[hitpoints (opt):] The number of shots needed
  to destroy this tank (default = 10).
\item[speed (opt):] The projectile speed (default = 200).
\end{description}

%-----------------------------------------------------------------------------
\subsubsection{Thorns}

\begin{Code}
  <thorn .../>
\end{Code}

\begin{description}
\item[orientation:] The orientation of the thorn
  (\xmlPropValue{top}, \xmlPropValue{bottom},
  \xmlPropValue{left}, or \xmlPropValue{right}).
\item[x:] The x position of the thorn's base.
\item[y:] The y position of the thorn's base.
\item[w/h:] The width/height, the thorn will rise out of the wall.
  Depending on the orientation of the thorn,
  only the \xmlProp{w} or \xmlProp{h} property shall exist.
\end{description}

%-----------------------------------------------------------------------------
\subsection{Properties for the startposition node}

The \xmlNode{startposition} node contains the following properties:
\begin{description}
\item[platform or x/y:]
  The start position of the player's ship must be given
  either via the \xmlProp{id} of the home platform
  or via an \xmlProp{x} and \xmlProp{y} coordinate.
\item[fuel (opt):]
  A \xmlProp{fuel} parameter can be given,
  containing the ship's fuel capacity in seconds (default = 100).
\end{description}

%-----------------------------------------------------------------------------
\subsection{Structure of the gamecontrol node}

With the content of the \xmlNode{gamecontrol} node
you are able to define different objectives,
that must be solved to complete the level.
If multiple objectives are given, they must be solved in the given order.

%-----------------------------------------------------------------------------
\subsubsection{Landing on platforms}

\begin{Code}
  <land platform="1,2"/>
\end{Code}

The \xmlNode{land} node contains the following properties:
\begin{description}
\item[platform:]
  A comma-seperated list of platform \xmlProp{id}s,
  where the ship has to land.
  The list may also contain id-ranges (e.g. \xmlPropValue{1-5}).
\end{description}

If multiple ids are given in the \xmlProp{platform} property,
the ship must land on all platforms in the given order.

%-----------------------------------------------------------------------------
\subsubsection{Picking up crates}

\begin{Code}
  <pickup id="10,11" platform="1"/>
\end{Code}

The \xmlNode{pickup} node contains the following properties:
\begin{description}
\item[id:]
  A comma-seperated list of crate \xmlProp{id}s to rescue.
  If multiple \xmlProp{id}s are given,
  the appropriate crates can be picked up in any order.
  The list may also contain id-ranges (e.g. \xmlPropValue{10-15}).
\item[platform:]
  The id of the target platform, where all crates must be brought to.
  This id usually is equal to the home platform
  defined in the \xmlNode{startposition} node.
\end{description}

If multiple \xmlNode{pickup} nodes are defined,
all crates given in the first node must be rescued,
before any crate given in the other nodes can be picked up.

%-----------------------------------------------------------------------------
\subsubsection{Destroying targets}

\begin{Code}
  <destroy id="10,11"/>
\end{Code}

The \xmlNode{destroy} node contains the following properties:
\begin{description}
\item[id:]
  A comma-seperated list of object \xmlProp{id}s to destroy.
  The list may also contain id-ranges (e.g. \xmlPropValue{10-15}).
\end{description}

Although multiple \xmlNode{destroy} nodes can be given,
it's not possible to define a particular order on how the objects
have to be destroyed (this wouldn't be useful anyway).

Further you must not use \xmlNode{destroy} as last objective node,
because it doesn't make much sense adding the remaining fuel to the score
and ending the level while still flying around.
So the last objective node of the \xmlNode{gamecontrol} has to be
either a \xmlNode{land} or a \xmlNode{pickup} node.

%-----------------------------------------------------------------------------
\subsubsection{Event handlers}
\label{sec:eventhandlers}

Every objective node can define event handlers
to enable a more dynamic game flow.
The following event handlers can be used:
\begin{description}
\item[onpickup:]
  Handled for \xmlNode{pickup} objectives when a crate is picked up.
  If multiple \xmlNode{onpickup} handlers are defined,
  the first one will be handled and removed from the current objective,
  when picking up a crate.
\item[onreached:]
  Handled if the containing objective node is reached
  and thus removed from the \xmlNode{gamecontrol} node.
\end{description}

Every event handler can define the following events:
\begin{description}
\item[show:]
  A comma-seperated list of previously hidden object \xmlProp{id}s to show.
\item[status:]
  A new text that shall be shown in the status bar.
\item[deactivate:]
  A comma-seperated list of object \xmlProp{id}s to deactivate.
\item[activate:]
  A comma-seperated list of object \xmlProp{id}s to activate.
\item[toggle:]
  A comma-seperated list of object \xmlProp{id}s to toggle.
\end{description}

All comma-seperated lists may contain id-ranges (e.g. \xmlPropValue{10-15}).
Note, that only barriers and magnets can be activated, deactivated or toggled.

%-----------------------------------------------------------------------------
\subsubsection{Examples for objectives and event handlers}

The following example will show the objects with the id 12 and 13,
if the crates 10 and 11 were rescued to platform 1:
\begin{Code}
  <pickup id="10,11" platform="1">
    <onreached show="12,13"/>
  </pickup>
\end{Code}

The following example will show the crate 11,
after the crate 10 was picked up.
Both crates must be brought to platform 1:
\begin{Code}
  <pickup id="10,11" platform="1">
    <onpickup show="11"/>
  </pickup>
\end{Code}

The following example shows the usage of multiple \xmlNode{onpickup} handlers.
The text of the status bar will be changed for every picked up crate:
\begin{Code}
  <pickup id="10-12" platform="1">
    <onpickup status="Two crates remaining."/>
    <onpickup status="Good. Only one crate remaining."/>
  </pickup>
\end{Code}

The following example will change the text of the status bar,
if the targets with the object id 10 and 11 are destroyed.
Further, the object with the id 20 will be deactivated:
\begin{Code}
  <destroy id="10,11">
    <onreached status="Well done!" deactivate="20"/>
  </destroy>
\end{Code}

\end{document}