<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
 <!ENTITY kappname "&kfouleggs;">
 <!ENTITY package "tdegames">
 <!ENTITY % addindex "IGNORE">
 <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
<title>The &kfouleggs; Handbook</title>
    
<authorgroup>
<author>
&Philip.Rodrigues; &Philip.Rodrigues.mail;
</author>

<othercredit role="developer">
&Nicolas.Hadacek; &Nicolas.Hadacek.mail;
<!-- Uncomment this when xslt is fixed
<contrib>Developer</contrib>
-->
</othercredit>

<othercredit role="reviewer">
&Lauri.Watts; &Lauri.Watts.mail;
<!-- Uncomment this when xslt is fixed
<contrib>Reviewer</contrib>
-->
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2000-2003</year>
<holder>&Philip.Rodrigues;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2006-06-19</date>
<releaseinfo>2.1.11</releaseinfo>

<abstract><para>&kfouleggs; is a clone of the Japanese PuyoPuyo game for
the Trinity Desktop Environment.</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>tdegames</keyword>
<keyword>KFoulEggs</keyword>
<keyword>PuyoPuyo</keyword>
</keywordset>

</bookinfo>

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

<para>&kfouleggs; is a clone of the Japanese PuyoPuyo game, with advanced
features such as multiplayer games against human or <acronym>AI</acronym>.
If you have played <application>Tetris</application>, or one of
its many clones, you will find &kfouleggs; easy to learn.</para>

</chapter>


<chapter id="gameplay">
<title>Game Play</title>

<sect1 id="starting-a-new-game">
<title>Starting a New Game</title>

<para>When you start &kfouleggs;, just click on the <guibutton>Start
</guibutton> button, or select <guimenuitem>New</guimenuitem> from the
<guimenu>Game</guimenu> menu at any time to start a new game.</para>

</sect1>

<sect1 id="aim-of-the-game">
<title>Aim of the Game</title>

<para>The aim of the game is to achieve the highest score possible by
moving the falling tiles in such a way that tiles of the same color are
adjacent, and disappear. The more tiles you remove, the higher your
score.</para>

</sect1>

<sect1 id="playing-the-game">
<title>Playing the Game</title>

<para>Use the <keycap>Left</keycap> and <keycap>Right</keycap> arrow
keys to move the falling tile in the relevant direction, and the
<keycap>Up</keycap> arrow and <keycap>Return</keycap> keys to rotate the
tile left and right respectively. The <keycap>Shift</keycap> key drops
the tile down one line, and the <keycap>Down</keycap> key drops the tile
all the way down - use it as a way of saving time. </para>

<para>All of these shortcuts can be customized by selecting
<guimenuitem>Configure Shortcuts...</guimenuitem> from the
<guimenu>Settings</guimenu> menu.</para>

<para>If two or more tiles of the same color come to rest horizontally
or vertically next to each other, they become <quote>glued</quote>. If
four or more pieces of the same color come to be <quote>glued</quote>,
they disappear, and any pieces above them fall down according to the law
of gravity ;-). If this causes four or more pieces to become
<quote>glued</quote>, then they will also disappear, and so on.</para>

<para>Every time you remove 100 tiles, you advance to the next level,
where the tiles fall faster, and the game is more difficult.</para>

<para>The game ends when the central column fills with tiles, and no
more can fall.</para>

</sect1>

<sect1 id="game-screen">
<title>The Game Screen</title>

<para>
<screenshot>
	<mediaobject>
	   <imageobject>
	    <imagedata fileref="gamescreen.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>&kfouleggs; in Action</phrase>
	  </textobject>
	</mediaobject>
</screenshot>

A quick explanation of what each of the parts of the game screen are for...
</para>

<para>
Along the left hand side, from top to bottom:

<variablelist>

<varlistentry>
<term><guilabel>Score</guilabel></term>
<listitem><para>Shows your current score.</para>
</listitem>
</varlistentry>

<!-- If you can think of a better way to describe this below, please change it :-) -->
<varlistentry>
<term><guilabel>Puyos</guilabel></term>
<listitem><para>Shows the number of removed sets of pieces.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Level</guilabel></term>
<listitem><para>Shows the number of the level you are currently on. The first,
easiest level is level one, progressing to the last, hardest level, 20.</para>
</listitem>
</varlistentry>

</variablelist>
</para>

<para>
In the center is the area  where the action takes place. The tiles fall through
the rectangle (whose properties can be changed in
<menuchoice><guimenu>>Settings</guimenu><guimenuitem>Configure KFoulEggs...</guimenuitem>
</menuchoice>, see <xref linkend="game-config"/>) until reaching the
bottom. The two small black rectangles under the main one are the tile's
<quote>shadow</quote> which show where it will land. You can toggle the tile's
shadow in <xref linkend="game-config"/>.
</para>

<para>
On the right hand side, the <guilabel>Next Tile</guilabel> box shows what the
next tile to fall will be, if you have enabled it in <xref
linkend="game-config"/>.
</para>

</sect1>


</chapter>

<chapter id="preferences">
<title>&kfouleggs; Configuration and Default Shortcuts</title>

<sect1 id="game-configuration">
<title>Configuring Gameplay</title>
<para>
The &kfouleggs; configuration is accessed from
<menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Configure &kfouleggs;...</guimenuitem></menuchoice>. The
options are as follows:
</para>

<sect2 id="game-config">
<title>Game Configuration</title>

<variablelist>

<varlistentry>
<term><guilabel>Initial level:</guilabel></term>
<listitem><para>Set the level which you will play at startup, from 1 (easiest)
to 20 (hardest). Default is level one.</para>
</listitem>
</varlistentry>

<varlistentry><term><guilabel>Direct drop down</guilabel></term>
<listitem><para>If checked, pressing the <keysym>Down Arrow</keysym> will cause
a tile to immediately fall to the bottom of the screen. If unchecked, pressing
the <keysym>Down Arrow</keysym> only causes the piece to fall until the key is released.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="appearance-config">
<title>Appearance Configuration</title>

<variablelist>

<varlistentry>
<term><guilabel>Enable animations</guilabel></term>
<listitem><para>If checked, pieces are shown with an
animation (a small rebound effect), when they touch the bottom.</para></listitem>
</varlistentry>

<varlistentry><term><guilabel>Show piece's shadow</guilabel></term>
<listitem><para>If checked, a shadow is placed beneath the game board
showing where the piece will fall.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Show next piece</guilabel></term>
<listitem><para>If checked, shows the next tile that will fall onto the
game board.</para></listitem>
</varlistentry>

<varlistentry><term><guilabel>Show detailed "removed lines"
field</guilabel></term>
<listitem><para>If checked, the <guilabel>Puyos</guilabel> counter on the left
of the screen shows how many times each number of Puyos have been removed. If
unchecked, just the total number removed is shown.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Background</guilabel></term>
<listitem><para>Select the color and the opacity for &kfouleggs; background. 
An opacity of zero makes the &kfouleggs; background
completely transparent, and a setting of one makes the &kfouleggs; background
completely opaque.</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="colors-config">
<title>Colors Configuration</title>
<para>Here you can select the colors used for the tiles in &kfouleggs;.</para>
</sect2>

<sect2 id="ai-config">
<title>A.I. Configuration</title>
<para>Here you can configure the A.I. in &kfouleggs;.</para>
</sect2>
</sect1>

<sect1 id="highscore-configuration">
<title>Configuring Highscores</title>
<para>
The configuration is accessed from
<menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Configure Highscores...</guimenuitem></menuchoice>. The
options are as follows:
</para>

<sect2 id="highscore-main-config">
<title>The <guilabel>Main</guilabel> Tab</title>

<variablelist>

<varlistentry>
<term><guilabel>Nickname:</guilabel></term>
<listitem><para>Displays your current nickname and allows you to change it.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Comment</guilabel></term>
<listitem><para>A comment about yourself. You choose...</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>World-wide highscores enabled</guilabel></term>
<listitem><para>If checked and if you are connected to the Internet, 
&kfouleggs; will send your score automatically at the end of the game 
to the highscore web server (kfouleggs.sf.net).</para></listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="highscore-advanced-config">
<title>The <guilabel>Advanced</guilabel> Tab</title>

<para>This tab displays your <guilabel>Registration Data</guilabel>
on kfouleggs.sf.net:</para>

<variablelist>
<varlistentry>
<term><guilabel>Nickname:</guilabel></term>
<listitem><para>Displays your current nickname from the <guilabel>Main</guilabel> tab.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Key:</guilabel></term>
<listitem><para>This key was generated when you registered on kfouleggs.sf.net by 
selecting <guilabel>World-wide highscores enabled</guilabel> the first time.
The registration key is used in conjunction with the 
nickname to identify uniquely users, but users cannot have the same nickname.
Click on the <guibutton>Remove</guibutton> button to delete you from the world highscores
list.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

</sect1>

<sect1 id="default-keybindings">
<title>Default Shortcuts</title>

<para>The default shortcuts for &kfouleggs; in all player modes are as
follows:</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>New</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>N</keysym></keycombo></entry>
</row>
<row>
<entry>Pause</entry>
<entry><keysym>P</keysym></entry>
</row>
<row>
<entry>Quit</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>Q</keysym></keycombo></entry>
</row>
<row>
<entry>Zoom In</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>+</keysym></keycombo></entry>
</row>
<row>
<entry>Zoom Out</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>-</keysym></keycombo></entry>
</row>
<row>
<entry>Show Highscores</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>H</keysym></keycombo></entry>
</row>
<row>
<entry>Show Menubar</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>M</keysym></keycombo></entry>
</row>
<row>
<entry>&kfouleggs; Handbook</entry>
<entry><keysym>F1</keysym></entry>
</row>
<row>
<entry>What's This?</entry>
<entry><keycombo action="simul">&Shift;<keysym>F1</keysym></keycombo></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>The default shortcuts for &kfouleggs; in one-player mode are as
follows:</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>Rotate Left</entry>
<entry><keysym>Up Arrow</keysym></entry>
</row>
<row>
<entry>Rotate Right</entry>
<entry><keysym>Return</keysym></entry>
</row>
<row>
<entry>Move Left</entry>
<entry><keysym>Left Arrow</keysym></entry>
</row>
<row>
<entry>Move Right</entry>
<entry><keysym>Right Arrow</keysym></entry>
</row>
<row>
<entry>Move to Left Column</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>Left Arrow</keysym></keycombo></entry>
</row>
<row>
<entry>Move to Right Column</entry>
<entry><keycombo action="simul">&Ctrl;<keysym>Right Arrow</keysym></keycombo></entry>
</row>
<row>
<entry>Drop Down</entry>
<entry><keysym>Down Arrow</keysym></entry>
</row>
</tbody>
</tgroup>
</informaltable>

</sect1>
</chapter>

<chapter id="multiplayer-play">
<title>Multiplayer Play</title>

<sect1 id="general-multiplayer">
<title>General Information</title>

<para>&kfouleggs; supports two local multiplayer types - Human vs. Human
and Human vs. Computer. To play either of these, select it from the
<guimenu>Multiplayer</guimenu> menu.</para>

<sect2 id="local-multiplayer">
<title>Multiplayer Games</title>

<para>In Human vs. Human or Human vs. Computer mode, two gameboards are
shown, one for the first player and one for the second. Each has its own
<guilabel>Score</guilabel>, <guilabel>Puyos</guilabel> and
<guilabel>Level</guilabel> indicator. The keys for the first human
player become, by default:</para>

<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry>Rotate Left</entry>
<entry><keycap>E</keycap></entry>
</row>
<row>
<entry>Rotate Right</entry>
<entry>C</entry>
</row>
<row>
<entry>Move Left</entry>
<entry><keycap>F</keycap></entry>
</row>
<row>
<entry>Move Right</entry>
<entry><keycap>G</keycap></entry>
</row>
<row>
<entry>Move to Left Column</entry>
<entry><keycombo action="simul">&Shift;<keycap>F</keycap></keycombo></entry>
</row>
<row>
<entry>Move to Right Column</entry>
<entry><keycombo action="simul">&Shift;<keycap>G</keycap></keycombo></entry>
</row>
<row>
<entry>Drop Down</entry>
<entry><keycap>D</keycap></entry>
</row>
<row>
<entry>Drop One Line</entry>
<entry><keysym>Space</keysym></entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>The keys for the second human player are the same as for the
player in single player mode. </para>

<para>To return to single player mode, select
<guimenu>Multiplayer</guimenu> and <guimenuitem>Single
Human</guimenuitem>.</para>

</sect2>
<!-- network gaming was disabled 
<sect2 id="network-games">
<title>Network Multiplayer Games</title>

<para>Multiplayer network games are set up by selecting
<menuchoice><guimenu>Multiplayer</guimenu>
<guimenuitem>More...</guimenuitem></menuchoice></para>

<para>Multiplayer games of &kfouleggs; use the model of a hosted game
which other players join.</para>

</sect2>

<sect2 id="hosting-a-game">
<title>Hosting a game</title>

<para>To host a game, select <guilabel>Create a network game</guilabel>
in the Multiplayer option dialog, set the port you want to use, and
click on the <guibutton>Next</guibutton> button.You then have the option
of changing local players' settings, if there are more than one local
players.  Clicking the <guibutton>Finish</guibutton> button advances the
dialog to the waiting for clients stage. When enough clients have
joined, <guibutton>Start Game</guibutton> starts the multiplayer
game.</para>

</sect2>

<sect2 id="joining-a-game">
<title>Joining a game</title>

<para>To join a game, select <guimenuitem>Join a network
game</guimenuitem> in the Multiplayers option dialog. Select the host
(<guilabel>Server address</guilabel>) and <guilabel>Port</guilabel> you
want to connect to.</para>

<tip><para>Make sure that the port you set when joining a game is the
same as the port that was set by the host of the game!</para></tip>

<para>Clicking <guibutton>Next</guibutton> takes you to the
<guilabel>Local players settings</guilabel> dialog (see above), and then
<guibutton>Finish</guibutton> connects to the remote game. The game
starts when the host chooses - the client has no choice.</para>

</sect2>
-->
</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="kfouleggs-mainwindow">
<title>The Main &kfouleggs; window</title>

<sect2>
<title>The <guimenu>Game</guimenu> Menu</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.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>P</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu>
<guimenuitem>Pause</guimenuitem>
</menuchoice></term>
<listitem><para><action>Pauses or resumes the game</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu>
<guimenuitem>Show Highscores</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a dialog</action> that displays different high score tables. 
Clicking on the links below the tables downloads world-wide scores.</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</action> &kfouleggs;</para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>View</guimenu> Menu</title>

<variablelist>

<varlistentry>
<term><menuchoice><shortcut><keycombo action="simul">
&Ctrl;<keycap>+</keycap></keycombo></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Zoom In</guimenuitem>
</menuchoice></term>
<listitem><para><action>Enlarges the game board
</action></para></listitem>
</varlistentry> 

<varlistentry>
<term><menuchoice><shortcut><keycombo action="simul">
&Ctrl;<keycap>-</keycap></keycombo></shortcut>
<guimenu>View</guimenu>
<guimenuitem>Zoom Out</guimenuitem>
</menuchoice></term>
<listitem><para><action>Reduces the game board size
</action></para></listitem>
</varlistentry> 

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Multiplayer</guimenu> Menu</title>

<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>Multiplayer</guimenu>
<guimenuitem>Single Human</guimenuitem>
</menuchoice></term>
<listitem><para><action>Sets the multiplayer mode to single
player</action></para></listitem>
</varlistentry> 

<varlistentry>
<term><menuchoice>
<guimenu>Multiplayer</guimenu>
<guimenuitem>Human vs Human</guimenuitem>
</menuchoice></term>
<listitem><para><action>Sets the multiplayer mode to two player with two human
players.</action></para></listitem>
</varlistentry> 

<varlistentry>
<term><menuchoice>
<guimenu>Multiplayer</guimenu>
<guimenuitem>Human vs Computer</guimenuitem>
</menuchoice></term>
<listitem><para><action>Sets the multiplayer mode to two player with one human
and one computer player.</action></para></listitem>
</varlistentry> 

<varlistentry>
<term><menuchoice>
<guimenu>Multiplayer</guimenu>
<guimenuitem>More...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the multiplayer
settings dialog.</action></para></listitem> 
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo>
</shortcut>
<guimenu>Settings</guimenu>
<guimenuitem>Show Menubar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Shows or hides the Menubar.</action>To return the
menubar, right-click anywhere on the gameboard and select <guimenuitem>Show
Menubar</guimenuitem>. </para></listitem>
</varlistentry> 

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays a standard &kde; key bindings
configuration dialog to change the keyboard shortcuts for &kfouleggs;.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Notifications...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays a standard &kde; notifications
configuration dialog to change the audio and visual notifications for &kfouleggs;.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Highscores...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays</action> the <link linkend="highscore-configuration">high score configuration dialog</link>,
in which you can change several settings that affect how &kfouleggs; treats highscores.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure &kfouleggs;...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays</action> the <link linkend="game-config">&kfouleggs;
configuration dialog</link>.</para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="help">
<title>The <guimenuitem>Help</guimenuitem> Menu</title>

&help.menu.documentation;

</sect2>

</sect1>

</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>&kfouleggs;</para>

<para>Program core engine copyright 1995 Eirik End.</para>
<para>Program copyright 1996-2001 &Nicolas.Hadacek; &Nicolas.Hadacek.mail;.</para>

<para>Documentation copyright 2000-2003 &Philip.Rodrigues; &Philip.Rodrigues.mail;.</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;

&underGPL;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kfouleggs">
<title>How to obtain &kfouleggs;</title>

&install.intro.documentation;

<sect2 id="compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

<para>Should you run into problems please report them to the &kde;
mailing list, or the program maintainer, &Nicolas.Hadacek;, at
&Nicolas.Hadacek.mail;.</para>

</sect2>

</sect1>

</appendix>

&documentation.index; 

</book>

<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
sgml-indent-step:0
sgml-indent-data:f
End:
-->