# KBlackBox Game Manual

Robert
Cimrman

    cimrman3@students.zcu.cz

10/02/1998
0.02.03

This document contains the installation guide and a brief description of the KBlackBox game.

KBlackBox is a superb graphical logical game, inspired by emacs' blackbox.

KDE
KBlackBox
play
kde
blackbox
game

## What is KBlackBox?

KBlackBox is a superb :-) graphical logical game, inspired by emacs' blackbox. Copying policy is GPL. Major part of this help file is based on the original emacs's help.

KBlackBox is a game of hide and seek played on an grid of boxes. Your opponent (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.

## Installation

KBlackBox is a KDE application. Therefore you need to have KDE installed on your computer - at least kdesupport, kdelibs and kdebase packages. The actual installation is very easy:

           cd somewhere
           gunzip kblackbox-x.y.z.tgz
           tar -xvf kblackbox-x.y.z.tar
           cd kblackbox-x.y.z
           # This is for generating the configure script. It will be probably removed,
           # when kblackbox is a part of kdegames.
           make -f Makefile.dist
           #
           ./configure
           make
           make install

You may need to be root when doing make install.

## GUI description

- Menus

  - File

    - Quit - Well, it's difficult to explain. Let's skip it.

  - Game

    - New - Starts a new game (and abandons the current, if any).

    - Give up - Shows you positions of the balls.

    - Done - 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 middle mouse button has the same function.

    - Resize - Resizes the main window, so that it fits perfectly its contents. This is useful, when you accidentaly change the size of the window...

  - Options

    - Size - Sets the size of the game field (black box).

    - Balls - Sets the number of balls in the black box.

    - Tutorial - Switches on/off the tutorial mode (i.e you can see, where the balls actually are).

  - Help

    - Help - Displays this help.

    - About - Displays the "About" dialog.

    - About Qt - Displays the information dialog about the Qt GUI library.

- Tool bar: The tool bar offers some of the most useful menu functions, namely, in the mentioned order:

  - Quit

  - New

  - Give up

  - Done

- Status bar: It shows you some useful information.

## Game description

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.

### Game board descritpion

The folloving types of fields are found on the game board:

- "gray" - The black box. Here you mark the fields, where the balls probably are.

- "green" - These are lasers, shooting rays of light when switched on.

- "white" - Nothing of interest - it's just a border.

- "blue" - "There must be one!", you think.

- "cyan" - Correct positions of balls are indicated by this type.

- "red" - Wrong positions of balls are indicated by this type.

- "brown" - Marking colour.

NOTE: The names of colours are used just for identifying the different types of the fields in this text. They might not 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 :-).

### User Interaction

The cursor (a circle) can be moved around the box with the standard cursor movement keys. Switching of lasers or marking of black boxes is done by the left mouse button, or by pressing "Return" or "Enter" keys. You can mark the fields, where a ball can't be, too. Just press the right 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 left 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 right mouse button.

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.

### Game rules

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:

- Detour - 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.

- Reflection - The ray is reflected and emerges in the same place it was sent in. On the playfield, reflections are denoted by the letter `R'.

- Hit 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 `H'.

The rules for how balls deflect rays are simple and are best shown by example.

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 "Detour" above. Note that the entrance and exit points are always interchangeable. "*" denotes the path taken by the ray.

Note carefully the relative positions of the ball and the ninety degree deflection it causes.

               1
             - * - - - - - -         - - - - - - - -         - - - - - - - -
             - * - - - - - -         - - - - - - - -         - - - - - - - -
           1 * * - - - - - -         - - - - - - - -         - O - - - - O -
             - - O - - - - -         - - O - - - - -         - - * * * * - -
             - - - - - - - -         - - - * * * * * 2     3 * * * - - * - -
             - - - - - - - -         - - - * - - - -         - - - O - * - -
             - - - - - - - -         - - - * - - - -         - - - - * * - -
             - - - - - - - -         - - - * - - - -         - - - - * - O -
                                           2                         3

As mentioned above, a reflection occurs when a ray emerges from the same point it was sent in. This can happen in several ways:

             - - - - - - - -         - - - - - - - -          - - - - - - - -
             - - - - O - - -         - - O - O - - -          - - - - - - - -
           R * * * * - - - -         - - - * - - - -          O - - - - - - -
             - - - - O - - -         - - - * - - - -        R - - - - - - - -
             - - - - - - - -         - - - * - - - -          - - - - - - - -
             - - - - - - - -         - - - * - - - -          - - - - - - - -
             - - - - - - - -       R * * * * - - - -          - - - - - - - -
             - - - - - - - -         - - - - O - - -          - - - - - - - -

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.

A hit occurs when a ray runs straight into a ball:

             - - - - - - - -         - - - - - - - -          - - - - - - - -
             - - - - - - - -         - - - - - - - -          - - - - O - - -
             - - - - - - - -         - - - - O - - -        H * * * * - - - -
             - - - - - - - -       H * * * * O - - -          - - - * - - - -
             - - - - - - - -         - - - - O - - -          - - - O - - - -
           H * * * O - - - -         - - - - - - - -          - - - - - - - -
             - - - - - - - -         - - - - - - - -          - - - - - - - -
             - - - - - - - -         - - - - - - - -          - - - - - - - -

Be sure to compare the second example of a hit with the first example of a reflection.

## Epilogue

### Author

Robert Cimrman, cimrman3@students.zcu.cz

### Copyright

KBblackBox is released under the GPL License.