<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
<!ENTITY kapp "<application>KBlackBox</application>">
<!ENTITY kappname "&kapp;" -- this only *seems* redundant -->
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE" -- change language only here -->
<!ENTITY % ents PUBLIC "-//KDE//ENTITIES Application-Variable Entities V1.0//EN">
%ents;
]>
<book lang="&language;">
<bookinfo>
<title>&kapp; Game Manual</title>
<authorgroup>
<author>
<firstname>Robert</firstname>
<surname>Cimrman</surname>
<affiliation>
<address><email>cimrman3@students.zcu.cz</email></address>
</affiliation>
</author>
<othercredit>
<firstname>Robert</firstname>
<surname>Cimrman</surname>
<affiliation>
<address><email>cimrman3@students.zcu.cz</email></address>
</affiliation>
<contrib>Developer</contrib>
</othercredit>
<othercredit>
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation><address><email>vampyr@atconnex.net</email></address></affiliation>
<contrib>Reviewer</contrib>
</othercredit>
</authorgroup>
<copyright>
<year>1998</year><year>2000</year>
<holder>Robert Cimrman</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>02/10/2000</date>
<releaseinfo>0.03.00</releaseinfo>
<abstract><para>&kapp; is a superb graphical logical game, inspired by the
<application>emacs</application>emacs> blackbox.</para></abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>KBlackBox</keyword>
<keyword>kdegames</keyword>
<keyword>blackbox</keyword>
<keyword>game</keyword>
</keywordset>
</bookinfo>
<chapter id="what-is-kblackbox">
<title>What is &kapp;?</title>
<para>&kapp; is a superb :-) graphical logical game, inspired by the
<application>emacs</application> blackbox. Major part of this help file is based
on the original emacs's help. </para>
<para>&kapp; is a game of hide and seek played on an grid of boxes. Your
opponent (the Random number generator, in this case) has hidden several balls
within this box. By shooting rays into the box and observing where they emerge
it is possible to deduce the positions of the hidden balls. The fewer rays you
use to find the balls, the lower your score.</para>
</chapter>
<chapter id="installation">
<title>Installation</title>
<para>
&kapp; is part of the KDE project
<ulink url="http://www.kde.org">http://www.kde.org</ulink>.
&kapp; can be found in the kdeutils package on
<ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the
main ftp site of the KDE project. </para>
<sect1 id="compilation">
<title>Compilation and installation</title>
<para>
In order to compile and install &kapp; on your system, type the following in the base
directory of the kdegames distribution:</para>
<screen width="40">
<prompt>%</prompt> <command>./configure</command>
<prompt>%</prompt> <command>make</command>
<prompt>%</prompt> <command>make install</command>
</screen>
<para>Since &kapp; uses <application>autoconf</application> and
<application>automake</application> you should have not trouble compiling
it. Should you run into problems please report them to the KDE mailing
lists.</para>
</sect1>
</chapter>
<chapter id="game-description">
<title>Game description</title>
<para>In the first part of this section a description of the game board will be
given. The second part deals with user interaction with the game board and
finally in the third part the actual game rules are explained.</para>
<sect1 id="game-board-descritpion">
<title>Game board descritpion</title>
<para>The folloving types of fields are found on the game board: </para>
<variablelist>
<varlistentry>
<term><interface>Black squares</interface></term>
<listitem><para>The black box. Here you must mark the squares you think a ball
is in.</para></listitem>
</varlistentry>
<varlistentry>
<term><interface>Green squares</interface></term>
<listitem><para>These are the lasers, shooting rays of light when switched
on.</para></listitem>
</varlistentry>
<varlistentry>
<term><interface>Light Grey squares</interface></term>
<listitem><para>Nothing here of interest, this is just a
border.</para></listitem>
</varlistentry>
<varlistentry>
<term><interface>Blue balls</interface></term>
<listitem><para>"There must be one!" you think. These mark where you
suspect a ball is placed in the black box.</para></listitem>
</varlistentry>
<varlistentry>
<term><interface>Cyan balls</interface></term>
<listitem><para>Show where the balls actually are.</para></listitem>
</varlistentry>
<varlistentry>
<term><interface>Red balls</interface></term>
<listitem><para>Incorrectly positioned balls you have marked are indicated in
red.</para></listitem>
</varlistentry>
<varlistentry>
<term><interface>Brown squares</interface></term>
<listitem><para>Marking colour</para></listitem>
</varlistentry>
</variablelist>
<note><para>The names of colours are used just for identifying the different
types of the fields in this text. They <emphasis>might not</emphasis> be in any
relation with the actual colour of the fields. Simply said: the black box is in
the centre, around are the lasers and around them is the border. Remap the
colours yourself :-). </para></note>
</sect1>
<sect1 id="user-interaction">
<title>User Interaction</title>
<para>The cursor (a circle) can be moved around the box with the standard cursor
movement keys or the mouse. Switching of lasers or marking of black boxes is
done by the <mousebutton>left</mousebutton> mouse button, or by pressing
<keycap>Return</keycap> or <keycap>Enter</keycap> keys.</para>
<para>You can mark the fields, where a ball can't be, too. Just press the
<mousebutton>right</mousebutton> mouse button. It often helps you to find an
area, where a ball could possibly be. To clear any marks (blue or brown) press
the <mousebutton>left</mousebutton> mouse button. Brown marks can't overwrite
blue marks. This way you can't erase the blue marks (guessed balls) by accident
when playing with the <mousebutton>right</mousebutton> mouse button. </para>
<para>When you think the configuration of balls you have placed is correct,
press the middle mouse button. You will be informed whether you are correct or
not, and be given your score. Your score is the number of letters and numbers
around the outside of the box plus five for each incorrectly placed ball. If you
placed any balls incorrectly, they will be indicated with red fields, and their
actual positions indicated with cyan fields.</para>
</sect1>
<sect1 id="game-rules">
<title>Game rules</title>
<para>You have to find balls hidden in the black box. Your means are limited -
you can just fire lasers which are around the box. There are three possible
outcomes for each ray you send into the box: </para>
<anchor id="detour">
<variablelist>
<varlistentry>
<term>Detour</term>
<listitem><para>The ray is deflected and emerges somewhere other than where
you sent it in. On the playfield, detours are denoted by matching pairs
of numbers - one where the ray went in, and the other where it came
out.</para></listitem>
</varlistentry>
<varlistentry>
<term>Reflection</term>
<listitem><para>The ray is reflected and emerges in the same place it was sent
in. On the playfield, reflections are denoted by the letter
<guilabel>R</guilabel>.</para></listitem>
</varlistentry>
<varlistentry>
<term>Hit</term>
<listitem><para>The ray strikes a ball directly and is absorbed. It does not
emerge from the box. On the playfield, hits are denoted by the letter
<guilabel>H</guilabel>.</para></listitem>
</varlistentry>
</variablelist>
<para>The rules for how balls deflect rays are simple and are best shown by
example.</para>
<para>As a ray approaches a ball it is deflected ninety degrees. Rays can be
deflected multiple times. In the diagrams below, the dashes represent empty box
locations and the letter "O" represents a ball. The entrance and exit
points of each ray are marked with numbers as described under <link
linkend="detour">Detour</link> above. Note that the entrance and exit points
are always interchangeable. "*" denotes the path taken by the
ray.</para>
<para>Note carefully the relative positions of the ball and the ninety degree
deflection it causes.</para>
<screen>
1
- * - - - - - - - - - - - - - - - - - - - - - -
- * - - - - - - - - - - - - - - - - - - - - - -
1 * * - - - - - - - - - - - - - - - O - - - - O -
- - O - - - - - - - O - - - - - - - * * * * - -
- - - - - - - - - - - * * * * * 2 3 * * * - - * - -
- - - - - - - - - - - * - - - - - - - O - * - -
- - - - - - - - - - - * - - - - - - - - * * - -
- - - - - - - - - - - * - - - - - - - - * - O -
2 3</screen>
<para>As mentioned above, a reflection occurs when a ray emerges from the same
point it was sent in. This can happen in several ways:</para>
<screen>
- - - - - - - - - - - - - - - - - - - - - - - -
- - - - O - - - - - O - O - - - - - - - - - - -
R * * * * - - - - - - - * - - - - O - - - - - - -
- - - - O - - - - - - * - - - - R - - - - - - - -
- - - - - - - - - - - * - - - - - - - - - - - -
- - - - - - - - - - - * - - - - - - - - - - - -
- - - - - - - - R * * * * - - - - - - - - - - - -
- - - - - - - - - - - - O - - - - - - - - - - -</screen>
<para>In the first example, the ray is deflected downwards by the upper ball,
then left by the lower ball, and finally retraces its path to its point of
origin. The second example is similar. The third example is a bit anomalous but
can be rationalized by realizing the ray never gets a chance to get into the
box. Alternatively, the ray can be thought of as being deflected downwards and
immediately emerging from the box.</para>
<para>A hit occurs when a ray runs straight into a ball:</para>
<screen>
- - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - O - - -
- - - - - - - - - - - - O - - - H * * * * - - - -
- - - - - - - - H * * * * O - - - - - - * - - - -
- - - - - - - - - - - - O - - - - - - O - - - -
H * * * O - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - -</screen>
<para>Be sure to compare the second example of a hit with the first example of a
reflection.</para>
</sect1>
</chapter>
<chapter id="gui-description">
<title><abbrev>GUI</abbrev> description</title>
<sect1 id="game-menu">
<title>The <guimenu>Game</guimenu> menu</title>
<variablelist>
<varlistentry>
<term><menuchoice><guimenu>Game</guimenu>
<guimenuitem>New</guimenuitem></menuchoice></term>
<listitem><para>Starts a new game (and abandons the current, if
any.)</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Game</guimenu>
<guimenuitem>Give Up</guimenuitem></menuchoice></term>
<listitem><para>Shows you positions of the balls.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Game</guimenu>
<guimenuitem>Done</guimenuitem></menuchoice></term>
<listitem><para>Checks whether all balls are placed. If yes, it terminates
the current game, computes the final score and indicates real positions of
the balls. The <mousebutton>middle</mousebutton> mouse button has the same
function. </para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Game</guimenu>
<guimenuitem>Resize</guimenuitem></menuchoice></term>
<listitem><para>Resizes the main window, so that it fits perfectly its
contents. This is useful, when you accidentaly change the size of the
window...</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Game</guimenu>
<guimenuitem>Quit</guimenuitem></menuchoice></term>
<listitem><para>Quit's &kapp;</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="settings-menu">
<title>The <guimenu>Settings</guimenu> menu</title>
<variablelist>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu>
<guisubmenu>Size</guisubmenu></menuchoice></term>
<listitem><para>Sets the size of the game field (black box.) You may choose
between <guimenuitem>8 x 8</guimenuitem>, <guimenuitem>10 x 10</guimenuitem> and
<guimenuitem>12 x 12</guimenuitem>. The default is <guimenuitem>8 x
8</guimenuitem></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu>
<guisubmenu>Balls</guisubmenu></menuchoice></term>
<listitem><para>Sets the number of balls in the black box. You may choose
between <guimenuitem>4</guimenuitem> (the default) </para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Tutorial</guimenuitem></menuchoice></term>
<listitem><para>Switches on or off the tutorial mode. In tutorial mode, you can
see where the balls actually are.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="help">
<title>The <guimenuitem>Help</guimenuitem> Menu</title>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut><keycombo><keycap>F1</keycap></keycombo></shortcut>
<guimenu>Help</guimenu><guimenuitem>Contents</guimenuitem></menuchoice></term>
<listitem>
<para>This invokes the KDE help system starting at the &kapp; help pages (this
document).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut><keycombo><keycap>Shift</keycap><keycap>F1</keycap></keycombo></shortcut>
<guimenu>Help</guimenu><guimenuitem>What's This?</guimenuitem></menuchoice></term>
<listitem>
<para>This changes the mouse cursor to a combination arrow and question mark.
Clicking on items within &kapp; with this arrow will open a help window (if
one exists for the particular item) explaining the item's function.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Help</guimenu>
<guimenuitem>Report Bug</guimenuitem></menuchoice></term>
<listitem><para>Report a bug or a wishlist item to &kapp;'s
authors.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu><guimenuitem>About KBlackBox</guimenuitem></menuchoice></term>
<listitem>
<para>This will displays version and author information</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Help</guimenu><guimenuitem>About KDE</guimenuitem></menuchoice></term>
<listitem>
<para>This displays the KDE version and other basic information.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="toolbar">
<title>The Tool bar</title>
<variablelist>
<varlistentry>
<term><guiicon>Quit</guiicon></term>
<listitem><para>Quits &kapp;</para></listitem>
</varlistentry>
<varlistentry>
<term><guiicon>New</guiicon></term>
<listitem><para>Starts a new game.</para></listitem>
</varlistentry>
<varlistentry>
<term><guiicon>Give Up</guiicon></term>
<listitem><para>Shows you positions of the balls.</para></listitem>
</varlistentry>
<varlistentry>
<term><guiicon>Done</guiicon></term>
<listitem><para>Checks whether all balls are placed. If yes, it terminates
the current game, computes the final score and indicates real positions of
the balls. The <mousebutton>middle</mousebutton> mouse button has the same
function. </para></listitem>
</varlistentry>
</variablelist>
</sect1>
</chapter>
<chapter id="credits-and-license">
<title>Credits and License</title>
<para>&kapp;</para>
<para>Copyright 1998-2000 Robert Cimrman,
<email>cimrman3@students.zcu.cz</email></para>
<para>Documentation by Robert Cimrman. Updated and converted to Docbook for KDE
2.0 by Lauri Watts <email>vampyr@atconnex.net</email></para>
&gpllicense-links;
</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
