<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book id="killbots" lang="&language;">

<bookinfo>
  <title>The &killbots; Handbook</title>

  <authorgroup>
    <author>
      <personname>
        <firstname>Parker</firstname>
        <surname>Coates</surname>
      </personname>
      <email>parker.coates@kdemail.net</email>
    </author>

    <!-- TRANS:ROLES_OF_TRANSLATORS -->
  </authorgroup>

  <copyright>
    <year>2008&ndash;2009</year>
    <holder>Parker Coates</holder>
  </copyright>

  <legalnotice>&FDLNotice;</legalnotice>

  <date>2021-07-05</date>
  <releaseinfo>KDE Gear 21.04</releaseinfo>

  <abstract>
    <para>&killbots; is a &kde; port of the classic &BSD; console game <command>robots</command>.</para>
  </abstract>

  <keywordset>
    <keyword>KDE</keyword>
    <keyword>kdegames</keyword>
    <keyword>game</keyword>
    <keyword>Killbots</keyword>
    <keyword>Strategy</keyword>
    <keyword>One player</keyword>
    <keyword>Single player</keyword>
    <keyword>robots</keyword>
    <keyword>robot</keyword>
    <keyword>fastbot</keyword>
    <keyword>junkheap</keyword>
    <keyword>teleport</keyword>
    <keyword>vaporize</keyword>
    <keyword>vaporizer</keyword>
    <keyword>energy</keyword>
  </keywordset>

</bookinfo>

<chapter id="introduction">
  <title>Introduction</title>

  <note>
    <title>Game type:</title>
    <para>Strategy</para>
  </note>

  <note>
    <title>Number of players:</title>
    <para>One</para>
  </note>

  <para>&killbots; is a simple game of evading killer robots. Who created the robots and why they have been programmed to destroy, no one knows. All that is known is that the robots are numerous and their sole objective is to destroy you. Fortunately for you, their creator has focused on quantity rather than quality and as a result the robots are severely lacking in intelligence. Your superior wit and a fancy teleportation device are your only weapons against the never-ending stream of mindless automatons.</para>

  <note>
    <title>Note:</title>
    <para>This documentation frequently refers to <quote>robots</quote>, <quote>junkheaps</quote>, &etc;, but &killbots; is fully themeable. That means the game sprites you see while playing might not match the futuristic themed ones described here. The game play and strategies, however, will remain the same, even if your hero is a carrot being chased through a garden patch by ravenous rabbits.</para>
  </note>

  <note>
    <title>Note:</title>
    <para>&killbots; supports multiple game types which control the game parameters and determine which game features are included. This documentation attempts to be generic and not specific to any one game type. Check the description and details of your current game type in the <guilabel>Configure - &killbots;</guilabel> dialog for more detailed information on game mechanics with respect to grid size, rounds, scoring, energy, &etc;</para>
  </note>

</chapter>

<chapter id="howto">
  <title id="howto-title">How to Play</title>

  <sect1 id="gameplay-basics">
    <title>Basics of Gameplay</title>

    <note>
      <title>Objective:</title>
      <para>Survive successive rounds of enemies while accumulating a high score.</para>
    </note>

    <para><screenshot><mediaobject>
      <imageobject><imagedata fileref="grid.png" format="PNG"/></imageobject>
      <textobject><phrase>Screenshot of the game grid</phrase></textobject>
    </mediaobject></screenshot></para>

    <para>&killbots; is a turn-based game, played on a rectangular <firstterm>grid</firstterm>. The number of <firstterm>cells</firstterm> in each row and column in the grid is determined by the game type being played. Each cell can contain one of the following:
      <variablelist>
        <varlistentry>
          <term><firstterm>Hero</firstterm> <inlinemediaobject><imageobject><imagedata fileref="hero.png" format="PNG"/></imageobject></inlinemediaobject></term>
          <listitem>
            <para>The hero is the unfortunate soul stuck in a room with a bunch of killer robots. As the player, it is your job to ensure that he remains alive for as long possible.</para>
            <para>At the beginning of each <firstterm>turn</firstterm>, the hero can perform one of three types of actions: he can stay where he is, he can move to an unoccupied adjacent cell, or he can perform a special action. See <link linkend="movement-controls" endterm="movement-controls-title"/> and <link linkend="special-actions" endterm="special-actions-title"/>.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><firstterm>Robot</firstterm> <inlinemediaobject><imageobject><imagedata fileref="enemy.png" format="PNG"/></imageobject></inlinemediaobject></term>
          <listitem>
            <para>Robots are mechanical thugs desiring only to crush the hero with their metallic girth. They have never heard of the <quote>Three Laws of Robotics</quote> and would probably crush anyone who tried to explain them.</para>
            <para>Each robot will take a single step toward the hero on every turn. If the robot is above the hero, it will step down. If the robot is to the left of the hero, it will step right. If the robot is below and right of the hero, it will step diagonally, up and left. Should a robot manage to reach the hero's cell, the hero will be killed and the game will end.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><firstterm>Fastbot</firstterm> <inlinemediaobject><imageobject><imagedata fileref="fastenemy.png" format="PNG"/></imageobject></inlinemediaobject></term>
          <listitem>
            <para>Fastbots are a much speedier version of the basic robot. For each move the hero makes, they take two steps. Fortunately, their increased mobility was not paired with increased intelligence; they often only succeed in destroying themselves twice as quickly as their slower brethren.</para>
            <para>Not all game types include fastbots.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><firstterm>Junkheap</firstterm> <inlinemediaobject><imageobject><imagedata fileref="junkheap.png" format="PNG"/></imageobject></inlinemediaobject></term>
          <listitem>
            <para>When two or more robots collide, they are destroyed and the resulting debris produces a junkheap. Enemies blindly ignore any junkheaps in their path and are destroyed upon crashing into them. You will find junkheaps to be extremely valuable, as they can serve as barricades between the hero and his attackers.</para>
            <para id="pushing-junkheaps">Some game types permit the hero to <firstterm>push</firstterm> junkheaps around the grid. The hero can then use junkheaps to construct <quote>bunkers</quote> that offer protection on multiple sides. Junkheaps can even be used offensively in some game types. Pushing a junkheap on top of an enemy squashes it and can even result in a bonus.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
  </sect1>

  <sect1 id="rounds-scoring-energy">
    <title>Rounds, Scoring and Energy</title>

    <para><screenshot><mediaobject>
      <imageobject><imagedata fileref="status.png" format="PNG"/></imageobject>
      <textobject><phrase>The in-game status indicators</phrase></textobject>
    </mediaobject></screenshot></para>

    <sect2>
      <title>Rounds</title>
      <para>Gameplay in &killbots; is divided into <firstterm>rounds</firstterm>. Each round begins with the hero in the middle of the grid and with enemies placed randomly around him. The round ends when all enemies have been destroyed. As each round is completed, the number of enemies increases. The number and type of the enemies added is game type dependent.</para>
      <para>The grid will continue to fill with enemies until one of two things occurs: enemies occupy more than 50 percent of the cells or a safe teleport is attempted, but there are no safe cells in the grid. Once either of these occurs, the current round is abandoned and the enemy counts are reset to those used in the first round.</para>
    </sect2>

    <sect2>
      <title>Scoring</title>
      <para>There really is no such thing as winning in &killbots;; the hero attempts to survive as long as possible, but the depressing reality is that, in the end, his luck will run out. Therefore, the goal in &killbots; is to accumulate the highest <firstterm>score</firstterm> possible before the inevitable occurs. The ten highest scores (along with the round reached) are recorded in the high score dialog.</para>
      <para>Points are awarded for destroying enemies. Fastbots are usually worth more than regular robots. Bonus points may also be awarded for enemies destroyed while <link linkend="pushing-junkheaps">pushing a junkheap</link> or <link linkend="wait-out-round">waiting out the round</link>.</para>
    </sect2>

    <sect2 id="energy">
      <title>Energy</title>
      <para>In addition to points, the hero can also collect <firstterm>energy</firstterm> as the game progresses. Energy allows the hero to perform <link linkend="teleport-safely">safe teleports</link> and/or use the <link linkend="vaporizer">vaporizer</link>. Depending on the game type, energy can be awarded for a variety of reasons including completing a round, <link linkend="pushing-junkheaps">pushing a junkheap</link> or destroying enemies while <link linkend="wait-out-round">waiting out the round</link>.</para>
      <para>The amount of energy that the hero can store is capped at a game type determined maximum. In some game types the maximum increases as rounds are completed. The energy status display is only visible if the current game type includes energy and safe teleports.</para>
    </sect2>
  </sect1>

  <sect1 id="special-actions">
    <title id="special-actions-title">Special Actions</title>
    <para>In addition to simple movement from cell to cell, the hero has up to four special actions at his disposal.</para>

    <sect2 id="teleport">
      <title>Teleport</title>
      <para>The hero somehow managed to get his hands on a personal teleporter. Unfortunately, when operated without an energy source, it is not very reliable. Activating the teleporter causes the hero to be transported to a randomly selected cell anywhere on the grid. There is no limit to the number of teleports the hero can perform.</para>
      <para>The destination cell is guaranteed to be unoccupied, but there is a very real chance that it will be adjacent to an angry robot. Due to the risk inherent in teleporting, it should generally be reserved as a last ditch maneuver, when there are no longer any safe moves available.</para>
    </sect2>

    <sect2 id="teleport-safely">
      <title>Teleport Safely</title>
      <para>The teleporter has a secondary operating mode that will transport the hero to a randomly selected, but safe cell. Safe teleporting requires <link linkend="energy">energy</link> though, and energy is generally in short supply. Obviously, the ability to teleport safely at key moments can greatly extend the hero's lifespan.</para>
      <para>Not all game types allow safe teleports and the amount of energy required to teleport safely varies between game types.</para>
    </sect2>

    <sect2 id="vaporizer">
      <title>Use the Vaporizer</title>
      <para>The third use for the teleporter device doesn't actually teleport the hero at all. This somewhat uncommon operating mode teleports all robots in cells adjacent to the hero. No one knows exactly where the robots are teleported to, but it seems to be sufficiently far away that they bother the hero again. Because the robots disappear into thin air without leaving a junkheap, this mode is nicknamed the <quote>vaporizer</quote> and enemies dispatched through vaporisation are considered as killed for scoring purposes.</para>
      <para>Like teleporting safely, using the vaporizer requires <link linkend="energy">energy</link>. Not all game types include the vaporizer and the amount of energy required to use it varies between game types.</para>
    </sect2>

    <sect2 id="wait-out-round">
      <title>Wait Out Round</title>
      <para>There may come a time when the grid is laid out such that all the robots can be destroyed without the hero having to move at all. In such a situation, you have the option to wait out the round.</para>
      <example>
        <title>An Opportunity to Wait Out the Round</title>
        <para><screenshot><mediaobject>
          <imageobject><imagedata fileref="waitoutround.png" format="PNG"/></imageobject>
        </mediaobject></screenshot></para>
      </example>
      <para>Waiting out the round causes the hero to freeze in place while the enemies continue their regular movement. This continues until one of two things happen: the enemies destroy themselves and the round finishes, or an enemy manages to reach the hero and the game ends. Once a wait out round command has been issued, it cannot be canceled, so one must be certain that the hero is, in fact, safe.</para>
      <para>So why would one take an action that eliminates the opportunity to change one's mind? Well, it adds a bit of flourish and drama to the end of a round, but more importantly, there is a bonus awarded for each enemy destroyed while waiting out the round. The size and type (points or energy) of the bonus is determined by the game type.</para>
    </sect2>
  </sect1>

</chapter>

<chapter id="interface-overview">
  <title>Interface Overview</title>

  <sect1 id="movement-controls">
    <title id="movement-controls-title">Movement Controls</title>
    <para>The player has the option of using either the keyboard, the mouse or both to control the hero.</para>
    <sect2 id="keyboard-movement">
      <title id="keyboard-movement-title">Keyboard Movement Controls</title>
      <para>There are nine different movement actions: left, right, up, down, the four diagonals, and stand still. Each of these actions can be assigned to two different keyboard keys. By default these nine actions are assigned to the nine number keys of the numeric keypad and to a 3 by 3 block of letters at the left end of a QWERTY keyboard. Of course, users using a different keyboard layout or one lacking a numeric keypad can modify these key assignments using the shortcuts configuration dialog.</para>
      <para>Each of the special movement commands (such as teleport) can also be issued from the keyboard. See <link linkend="move-menu">Move</link>.</para>
    </sect2>
    <sect2 id="mouse-movement">
      <title id="mouse-movement-title">Mouse Movement Controls</title>
      <para>The mouse (or any other pointing device) can be used to navigate in a more natural, intuitive way. As the pointer moves over the main game area, the cursor will change to indicate the direction of the pointer relative to the hero. For example, moving the pointer to the space above the hero will change the cursor to an up arrow. If the pointer is placed immediately over the hero, the cursor changes to indicate no movement.</para>
      <para>A single left-click will cause the hero to step in the indicated direction (provided such a step is permitted). For convenience, one can assign additional actions to the right and middle mouse buttons in the <link linkend="configure-killbots">Configure - &killbots; dialog</link>. These actions include those found in the <link linkend="move-menu">Move</link> menu, as well as additional option: <guimenuitem>Repeated Step</guimenuitem> performing a repeated step causes the hero to move in the indicated direction for several consecutive turns until an obstruction is reached or continued movement would be unsafe. One can also halt a repeated step by clicking again while the move is in progress.</para>
      <para></para>
    </sect2>
  </sect1>

  <sect1 id="game-menu">
    <title>Menu Items</title>

    <variablelist>
      <varlistentry>
        <term><menuchoice>
          <shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut>
          <guimenu>Game</guimenu>
          <guimenuitem>New</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Starts a new game, discarding any game that may currently be in progress.</action></para></listitem>
      </varlistentry>
      <varlistentry>
        <term><menuchoice>
          <shortcut><keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo></shortcut>
          <guimenu>Game</guimenu>
          <guimenuitem>Show High Scores</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Shows the high score dialog, containing past scores.</action></para></listitem>
      </varlistentry>
      <varlistentry>
        <term><menuchoice>
          <shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></shortcut>
          <guimenu>Game</guimenu>
          <guimenuitem>Quit</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Quits &killbots;.</action></para></listitem>
      </varlistentry>

      <varlistentry id="move-menu">
        <term><menuchoice>
          <shortcut><keycap>R</keycap></shortcut>
          <guimenu>Move</guimenu>
          <guimenuitem>Teleport</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Teleports the hero to a random, empty cell anywhere within the playing field.</action> See <link linkend="teleport" endterm="special-actions-title"/>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><menuchoice>
          <shortcut><keycap>T</keycap></shortcut>
          <guimenu>Move</guimenu>
          <guimenuitem>Teleport Safely</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Teleports the hero to a random, empty cell that is guaranteed to be safe from attack on that turn.</action> See <link linkend="teleport-safely" endterm="special-actions-title"/>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><menuchoice>
          <shortcut>&Space;</shortcut>
          <guimenu>Move</guimenu>
          <guimenuitem>Teleport (Safely if Possible)</guimenuitem>
        </menuchoice></term>
        <listitem><para>A convenience action. <action>Teleports the hero safely if there is enough energy available, otherwise just teleports randomly.</action></para></listitem>
      </varlistentry>
      <varlistentry>
        <term><menuchoice>
          <shortcut><keycap>F</keycap></shortcut>
          <guimenu>Move</guimenu>
          <guimenuitem>Vaporizer</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Destroys all robots in cells adjacent to the hero</action>. See <link linkend="vaporizer" endterm="special-actions-title"/>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><menuchoice>
          <shortcut><keycap>V</keycap></shortcut>
          <guimenu>Move</guimenu>
          <guimenuitem>Wait Out Round</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Causes the hero to freeze in place until the end of the round.</action> See <link linkend="wait-out-round" endterm="special-actions-title"/>.</para></listitem>
      </varlistentry>

      <varlistentry id="configure-killbots">
        <term><menuchoice>
          <guimenu>Settings</guimenu>
          <guimenuitem>Configure &killbots;...</guimenuitem>
        </menuchoice></term>
        <listitem><para><action>Displays the &killbots; configuration dialog</action>, where one can adjust gameplay parameters, choose a different set of game rules, or change the game theme.</para></listitem>
      </varlistentry>
    </variablelist>

<para>
Additionally &killbots; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
menu items, for more information read the sections about the <ulink url="help:/fundamentals/menus.html#menus-settings"
>Settings Menu</ulink> and <ulink url="help:/fundamentals/menus.html#menus-help">Help Menu</ulink>
of the &kde; Fundamentals.
</para>

  </sect1>

</chapter>


<chapter id="developers">
  <title>Developer's Guide to &killbots;</title>
  <para>Interested individuals can customize &killbots; in two major ways: themes and rulesets.</para>

  <sect1 id="creating-themes">
    <title>Creating Custom &killbots; Themes</title>
    <para>Like most other &kde; games, a &killbots; theme consists of three files.</para>

    <sect2>
      <title>The Desktop File</title>
      <para>The desktop file follows standard <acronym>INI</acronym> syntax. The key-value pairs store information about the theme and point to the other files included in the theme. The following example is taken from the default theme.</para>
      <example>
        <title>An Example Theme Desktop File</title>
        <programlisting>
[KGameTheme]
Name=Example Theme
Description=An example theme used to demonstrate theme creation. This one features pirates.
Author=Mr. Artist
AuthorEmail=mrartist@example.com
Type=SVG
FileName=example.svg
Preview=example.png
        </programlisting>
      </example>
      <para>The first four parameters contain metadata about the theme and are straight forward enough. For &killbots; themes, the <varname>Type</varname> parameter should always be set to &SVG;. The final two parameters contain the file names of the two other theme files. While it's not strictly necessary, it is highly recommended that, for consistency's sake, all three files share the same base file name.</para>
    </sect2>

    <sect2>
      <title>The Preview File</title>
      <para>The preview file is simply a <acronym>PNG</acronym> file containing a preview of the theme. The preview image should be 240 by 140 pixels and match layout of the default theme's preview as closely as possible, as this makes it easier to compare themes in the theme selector.</para>
    </sect2>

    <sect2>
      <title>The &SVG; File</title>
      <para>The &SVG; file is a scalable vector graphics image that contains the actual graphical elements used to make up the theme. The file may be either in uncompressed <literal role="extension">.svg</literal> or compressed <literal role="extension">.svgz</literal> format. Each game element is identified by a unique id in the &SVG; file.  When creating a new theme, it is generally easiest to start with an existing theme and replace the elements one by one until the theme is complete. The &SVG; file <emphasis>must</emphasis> contain the following elements.</para>
      <variablelist>
        <varlistentry>
          <term><varname>background</varname></term>
          <listitem><para>The image displayed behind the grid in the main game area.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>status</varname></term>
          <listitem><para>The box used to display the current round, score, enemy count and energy.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>textcolor</varname></term>
          <listitem><para>This element should be a rectangle of a single color. Its color is used to for the text in the status boxes.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cell</varname></term>
          <listitem><para>An individual grid cell.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>hero</varname></term>
          <listitem><para>The character controlled by the player.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>enemy</varname></term>
          <listitem><para>The basic enemy.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>fastenemy</varname></term>
          <listitem><para>The faster enemy.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>junkheap</varname></term>
          <listitem><para>The remains of a collision between enemies.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor0</varname></term>
          <listitem><para>A cursor indicating movement to the right.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor1</varname></term>
          <listitem><para>A cursor indicating diagonal movement up and to the right.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor2</varname></term>
          <listitem><para>A cursor indicating movement up.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor3</varname></term>
          <listitem><para>A cursor indicating diagonal movement up and to the left.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor4</varname></term>
          <listitem><para>A cursor indicating movement to the left.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor5</varname></term>
          <listitem><para>A cursor indicating diagonal movement down and to the left.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor6</varname></term>
          <listitem><para>A cursor indicating movement down.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor7</varname></term>
          <listitem><para>A cursor indicating movement down and to the right.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>cursor8</varname></term>
          <listitem><para>A cursor indicating staying in place.</para></listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2>
      <title>Installing Custom Themes</title>
      <para>In order for &killbots; to detect and use a new theme, the files must be moved to an appropriate directory. To install the theme for only the current user, copy the desktop, preview and &SVG; files to <filename class="directory">killbots/themes</filename> in the local folder in <userinput><command>qtpaths</command> <option>--paths GenericDataLocation </option></userinput>. To make the theme available system wide, move the files to <filename class="directory">killbots/themes</filename> in the system folder (from the previous command, possibly <filename class="directory">/usr/share</filename> or similar). Note that this will likely require administrative privileges.</para>
    </sect2>
  </sect1>

  <sect1 id="creating-rulesets">
    <title>Creating Custom Game Types</title>

    <sect2>
      <title>The Ruleset Desktop File</title>
      <para>Creating new game types is incredibly simple for &killbots;, especially when starting from an existing ruleset file. Rulesets are stored as a single desktop file where the parameters and metadata are stored as simple key-value pairs.</para>
      <example>
        <title>The Default &killbots; Game Type</title>
        <programlisting width="80">
[KillbotsRuleset]
Name=Killbots
Name[gl]=Robots asasinos
Author=Parker Coates
AuthorContact=parker.coates@kdemail.net
Description=&lt;qt&gt;&lt;p&gt;The default Killbots game type.&lt;/p&gt;&lt;p&gt;Includes a medium size grid, safe teleports, fast enemies and pushable junkheaps.&lt;/p&gt;&lt;/qt&gt;
Description[gl]=&lt;qt&gt;&lt;p&gt;O xogo tipo Killbots por omisión.&lt;/p&gt;&lt;p&gt;Inclúe unha grella mediana, teleportacións seguras, enemigos rápidos e chatarra que se pode empurrar.&lt;/p&gt;&lt;/qt&gt;
Rows=16
Columns=16
EnemiesAtGameStart=8.0
EnemiesAddedEachRound=4.0
FastEnemiesAtGameStart=-2.0
FastEnemiesAddedEachRound=2.0
EnergyEnabled=true
EnergyAtGameStart=0
EnergyAddedEachRound=0
MaxEnergyAtGameStart=12.0
MaxEnergyAddedEachRound=0.0
SafeTeleportEnabled=true
CostOfSafeTeleport=1
VaporizerEnabled=false
CostOfVaporizer=0
PushableJunkheaps=Many
SquaskKillsEnabled=true
JunkheapsAtGameStart=0.0
JunkheapsAddedEachRound=0.0
PointsPerEnemyKilled=5
PointsPerFastEnemyKilled=10
WaitKillPointBonus=0
WaitKillEnergyBonus=1
SquashKillPointBonus=0
SquashKillEnergyBonus=1</programlisting>
      </example>
      <para>Note that all text parameters should be entered in American English. As seen in the example above, translations can be added to the desktop file by repeating the key and appending the language code between square brackets. Also note that rich text can be given to the <varname>Description</varname> field by wrapping the value in &lt;qt&gt; tags.</para>
      <para>A ruleset file should contain all of the following parameters.</para>
      <variablelist>
        <varlistentry>
          <term><varname>Name</varname></term>
          <listitem><para>The name of the ruleset as it will appear in the ruleset selector and the high score dialog.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Author</varname></term>
          <listitem><para>The creator of the ruleset.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>AuthorContact</varname></term>
          <listitem><para>The contact information of the creator. This is usually an email address.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Description</varname></term>
          <listitem><para>A description of the ruleset. This should give a decent overview of the game type, but it doesn't need to list the value of each parameter as this information can been seen in the Details dialog.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Rows</varname></term>
          <listitem><para>The number of rows in the game grid.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>Columns</varname></term>
          <listitem><para>The number of columns in the game grid.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>EnemiesAtGameStart</varname></term>
          <listitem><para>The number of regular enemies added to the grid at the start of the first round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>EnemiesAddedEachRound</varname></term>
          <listitem><para>The number of additional regular enemies added to the grid at the start of each round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>FastEnemiesAtGameStart</varname></term>
          <listitem><para>The number of fast enemies added to the grid at the start of the first round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>FastEnemiesAddedEachRound</varname></term>
          <listitem><para>The number of additional fast enemies added to the grid at the start of each round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>EnergyEnabled</varname></term>
          <listitem><para>If set to <quote><constant>false</constant></quote> the hero will be enable to earn or spend energy.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>EnergyAtGameStart</varname></term>
          <listitem><para>The amount of energy awarded to the hero at the start of the first round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>EnergyAddedEachRound</varname></term>
          <listitem><para>The amount of energy awarded to the hero at the start of each round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>MaxEnergyAtGameStart</varname></term>
          <listitem><para>The maximum energy capacity of the hero at the start of the first round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>MaxEnergyAddedEachRound</varname></term>
          <listitem><para>The change in maximum energy capacity at the start of each round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>SafeTeleportEnabled</varname></term>
          <listitem><para>If set to <quote><constant>false</constant></quote> the safe teleport action will be disabled.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>CostOfSafeTeleport</varname></term>
          <listitem><para>The amount of energy consumed by teleporting safely.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>VaporizerEnabled</varname></term>
          <listitem><para>If set to <quote><constant>false</constant></quote> the vaporizer action will be disabled.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>CostOfVaporizer</varname></term>
          <listitem><para>The amount of energy consumed by using the vaporizer.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>PushableJunkheaps</varname></term>
          <listitem><para>The number of junkheaps that can be moved with a single push. Possible values are <quote><constant>None</constant></quote>, <quote><constant>One</constant></quote> and <quote><constant>Many</constant></quote>.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>SquaskKillsEnabled</varname></term>
          <listitem><para>If true, the hero can squash enemies by pushing junkheaps onto them.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>JunkheapsAtGameStart</varname></term>
          <listitem><para>The number of junkheaps placed on the grid at the start of the first round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>JunkheapsAddedEachRound</varname></term>
          <listitem><para>The number of additional junkheaps placed on the grid at the start of each round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>PointsPerEnemyKilled</varname></term>
          <listitem><para>The number of points awarded for destroying a regular enemy.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>PointsPerFastEnemyKilled</varname></term>
          <listitem><para>The number of points awarded for destroying a fast enemy.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>WaitKillPointBonus</varname></term>
          <listitem><para>The number of bonus points awarded for destroying an enemy while waiting out the round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>WaitKillEnergyBonus</varname></term>
          <listitem><para>The number of bonus energy units awarded for destroying an enemy while waiting out the round.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>SquashKillPointBonus</varname></term>
          <listitem><para>The number of bonus points awarded for squashing an enemy with a junkheap.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term><varname>SquashKillEnergyBonus</varname></term>
          <listitem><para>The number of bonus energy units awarded for squashing an enemy with a junkheap.</para></listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2>
      <title>Installing Custom Game Types</title>

      <para>In order for &killbots; to detect and use a new game type, the ruleset file must be moved to an appropriate directory. To install the game type for only the current user, copy the file to <filename class="directory">killbots/rulesets</filename> in the local folder in <userinput><command>qtpaths</command> <option>--paths GenericDataLocation </option></userinput>. To make the game type available system wide, move the file to <filename class="directory">killbots/rulesets</filename> in the system folder (from the previous command, possibly <filename class="directory">/usr/share</filename> or similar). Note that this will likely require administrative privileges.</para>
    </sect2>

  </sect1>
</chapter>

<chapter id="credits">
  <title>Credits and License</title>

  <para>&killbots;</para>
  <para>Program copyright 2007&ndash;2009 Parker Coates <email>parker.coates@kdemail.net</email></para>
  <para>Documentation Copyright &copy; 2008&ndash;2009 Parker Coates <email>parker.coates@kdemail.net</email></para>

  <!-- TRANS:CREDIT_FOR_TRANSLATORS -->

  &underFDL;
  &underGPL;
</chapter>

&documentation.index;

</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
kate: space-indent on; indent-width 2; tab-width 2; indent-mode none;
-->
