summaryrefslogtreecommitdiffstats
path: root/doc/kblackbox/index.docbook
blob: 39687f3149d1d39182a441e94ea15e3660cebc07 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
 <!ENTITY kappname "&kblackbox;">
 <!ENTITY package "tdegames">
 <!ENTITY % addindex "IGNORE">
 <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
<title>&kblackbox; Game Manual</title>
    
<authorgroup>
<author>
&Robert.Cimrman; &Robert.Cimrman.mail;
</author>

<author>
&Philip.Rodrigues; &Philip.Rodrigues.mail;
</author>

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

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

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>1998</year><year>2000</year>
<holder>&Robert.Cimrman;</holder>
</copyright>

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

<legalnotice>&FDLNotice;</legalnotice>

<date>2005-12-10</date>
<releaseinfo>0.3.0</releaseinfo>

<abstract><para>&kblackbox; is a superb graphical logical game, inspired
by the <application>emacs</application> blackbox game.</para></abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>KBlackBox</keyword>
<keyword>tdegames</keyword>
<keyword>blackbox</keyword>
<keyword>game</keyword>
</keywordset>

</bookinfo>

<chapter id="what-is-kblackbox">
<title>What is &kblackbox;?</title>

<para>&kblackbox; is a superb :-) graphical logical game, inspired by
the <application>emacs</application> blackbox game. A major part of this help
file is based on the original <application>emacs</application>
help. </para>

<para>&kblackbox; is a game of hide and seek played on a 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 better
(the lower) your score.</para>

</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 Description</title>

<para>The following types of field 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 Gray 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><quote>There must be one there!</quote> 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 color</para></listitem>
</varlistentry>
</variablelist>

<note><para>The names of colors 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 color of the
fields. Simply said: the black box is in the center, around are the
lasers and around them is the border. Remap the colors yourself
:-). </para></note>

</sect1>

<sect1 id="user-interaction">
<title>User Interaction</title>

<para>The cursor 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 with the &LMB;, or by pressing the
<keycap>Return</keycap> or &Enter; key.</para>

<para>You can mark the fields where you think a ball cannot be, too. Just press
the &RMB;. It often helps you to find an area where a ball could possibly
be. To clear any marks (blue or brown) press the
&LMB;. Brown marks cannot overwrite blue
marks. This way you cannot erase the blue marks (guessed balls) by accident when
playing with the &RMB;. </para>

<para>When you think the configuration of balls you have placed is
correct, press the &MMB;. 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 <guilabel>O</guilabel>
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. <guilabel>*</guilabel> 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>&GUI; description</title>

<sect1 id="game-menu">
<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>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 its contents fit perfectly. This is useful when you accidentally change the size of the
window...</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>Quits &kblackbox;</para></listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="settings-menu">
<title>The <guimenu>Settings</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Show/Hide Toolbar</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Shows or hides the &kblackbox; toolbar.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Show/Hide Statusbar</guimenuitem>
</menuchoice></term>
<listitem>
<para>Shows or hides the &kblackbox; status bar at the base of the screen.</para>
</listitem>
</varlistentry>

<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), <guimenuitem>6</guimenuitem>
or <guimenuitem>8</guimenuitem>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Tutorial</guimenuitem></menuchoice></term>
<listitem><para>Switches the tutorial mode on or off.  In tutorial mode,
you can see where the balls actually are. Note that you have to start a new
game for this change to take effect.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term>
<listitem><para>Displays a standard &kde; shortcut configuration dialog, in
which you can change the keyboard shortcuts used by &kblackbox;.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem>
</menuchoice></term>
<listitem>
<para>Brings up the standard &kde; toolbar configuration dialog to customize the &kblackbox; toolbar.</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

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

&help.menu.documentation;

</sect1>

<sect1 id="toolbar">
<title>The Toolbar</title>

<screenshot>
<screeninfo>&kblackbox;'s toolbar</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kblackboxtbar.png" format="PNG"/>
</imageobject>
</mediaobject>
</screenshot>

<para>The &kblackbox; toolbar offers quick access to the most commonly used
&kblackbox; functions. From left to right, the icons are:</para>

<variablelist>

<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>&kblackbox;</para>

<para>Program Copyright 1998-2000 &Robert.Cimrman; &Robert.Cimrman.mail;</para>

<para>Documentation by &Robert.Cimrman;.  Updated and converted to Docbook
for &kde; 2.0 by &Lauri.Watts; &Lauri.Watts.mail;</para>

<para>
Current maintainer &Philip.Rodrigues; &Philip.Rodrigues.mail;
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>


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

&install.intro.documentation;

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

&install.compile.documentation;

</sect1>
</appendix>

</book>