BBox Documentation
------------------

Black Box Game for the HP-48SX
==============================

This program is copyright (C) 1991 Chris Tham.
Permission is given to copy, use or modify this program, as long as the
original author is given credit.

Game Description
----------------

The Black Box is a large square containing grid of squares.  There are 8
by 8 or 64 squares within the Black Box.  Four of these squares contain
atoms.  You do not know where the four atoms are located within the
black box.  Your task, should you decide to accept it, is to find the
locations of the atoms within the Black Box.

Each square within the Black Box can be labelled by its coordinate
position, as in Figure 1.

         1 2 3 4 5 6 7 8
        +-+-+-+-+-+-+-+-+
       1| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       2| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       3| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       4| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       5| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       6| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       7| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       8| | | | | | | | |
        +-+-+-+-+-+-+-+-+

       Figure 1: Coordinate labelling of squares in the black box

Hence the square on the upper left hand corner of the black box is
labelled (1,1), the square on the upper right hand corner of the black
box is labelled (1,8) and so on.

You can determine the location of atoms in the black box by firing rays
into the black box from its sides.  Rays always enter the black box
perpendicular to the side from which it is fired from.  Rays normally
travel in a straight line whilst in the black box.  Depending on the
location of atoms within the black box, the following may happen to a
ray:
1. The ray may pass straight through on the other side of the box.
   This usually (but not always!) means that the ray did not encounter
   any atoms within or adjacent to its path.

               Ray leaves box here
         1 2 3 ^ 5 6 7 8
        +-+-+-+^+-+-+-+-+
       1| | | |^| | | | |            Figure 2: Ray passing straight through
        +-+-+-+^+-+-+-+-+
       2| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       3| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       4| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       5| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       6| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       7| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       8| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
               ^
               Ray enters from here

2. The ray may be absorbed.
   A ray is absorbed if it collides with an atom in its path.

         1 2 3 4 5 6 7 8
        +-+-+-+-+-+-+-+-+
       1| | | | | | | | |            Figure 3: Ray absorption
        +-+-+-+-+-+-+-+-+
       2| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       3| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       4| | | |X| | | | |
        +-+-+-+^+-+-+-+-+
       5| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       6| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       7| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       8| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
               ^
               Ray enters from here

3. The ray may be reflected back to the side it came from.
   A ray is reflected if it encounters two atoms in front of it, one to
   the left and the other to the right.

         1 2 3 4 5 6 7 8
        +-+-+-+-+-+-+-+-+
       1| | | | | | | | |            Figure 4: Ray reflection
        +-+-+-+-+-+-+-+-+
       2| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       3| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       4| | |X| |X| | | |
        +-+-+-+^+-+-+-+-+
       5| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       6| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       7| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       8| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
               ^
               Ray enters and leaves here

4. The ray may be refracted and emerge on a different side of the black
   box.
   A ray is refracted when it encounters an atom in front of it, either
   to the left or to the right.  Note that refractions are reflexive,
   i.e. if you fire a ray and it gets refracted, you can fire a ray into
   the location where the original ray emerged and it will emerge where
   you had fired the original ray.

         1 2 3 4 5 6 7 8
        +-+-+-+-+-+-+-+-+
       1| | | | | | | | |            Figure 5: Ray refraction
        +-+-+-+-+-+-+-+-+
       2| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       3| | | | | | | | |
        +-+-+-+-+-+-+-+-+
       4| | |X| | | | | |
        +-+-+-+-+-+-+-+-+
       5| | | |>>>>>>>>>> Ray emerges here
        +-+-+-+^+-+-+-+-+
       6| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       7| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
       8| | | |^| | | | |
        +-+-+-+^+-+-+-+-+
               ^
               Ray enters from here

Of course, a ray may get refracted, then absorbed, and so on.  By firing
rays at strategic locations into the black box, you should be able to
deduce the correct locations of the four atoms.

At the start of the game, the program will draw the black box on the
screen and choose the locations of the four atoms randomly.  The object
of the game is to be able to guess correctly the location of all four
atoms within the black box by firing less than or equal to eight rays.
Each time you fire a ray, the program traces its progress in the black
box and informs you what happened to the ray (where it emerges or has
been absorbed).  You may submit a guess of an atom's location at any
time in the game.  If your guess is correct, the program will plot the
atom on the black box.  If your guess is wrong, you lose immediately. 
You win if you manage to guess all four atom locations correctly.  You
lose if you run out of rays.

How to download the game into the HP-48SX
-----------------------------------------

Download the file, enter into the directory, press the VAR key
to get a list of variables.  Press the softkey corresponding
'INIT' to execute the initialization routine.
[Warning: this will take a while].  After executing INIT, the game will
be properly set up on the HP-48SX.

How to play the game
--------------------

Press the soft key corresponding to 'PLAY'.  The HP-48SX screen will
show a blank black box together with game credits.  The numeral `4' at
the bottom side of the black box should be inversed.  This is where the
cursor defaults to at the start of the game.  You can move the cursor by
using the arrow keys on the keyboard.  The cursor always inverses
whatever is lying underneath it.  You can move the cursor into the box
as well as any location on the side of the box except at the corners. 

Pressing the ENTER key when the cursor is at the side of the box will
fire a ray into the box from the location of the cursor.  Rays are
labelled from A to H.  The program will trace the movement of the ray
and label the location where the ray emerges with the same letter.

Pressing the ENTER key when the cursor is within the box will cause the
program to check whether the square underneath the cursor contains an
atom.  If it does, the program informs you, draws a cross at the
location of the atom and lets the game continue. 
If it doesn't, you lose immediately.

Pressing the <- key (the one next to the DEL key) causes the game to
exit immediately.

Program description
-------------------

The program uses two global variables which you can change to customise
the game.  'NATOMS' contains the number of atoms that the program puts
into the black box and consequently the number of atoms that you have
to guess.  The default value of 'NATOMS' is 4.  'MAXRAYS' contains the
maximum number of rays that you can fire into the black box.  The
default value of 'MAXRAYS' is 8.  The INIT program generates the cursor
mask grob (using the program GENMASK) and the cross grob (using the
program GENCROS) as well as generating the PICT for the playing screen 
(using the program GENBOX).  It then creates some global variables
needed by the program and then reorders the variables in the directory.
Finally, it deletes the initialization programs that are no longer
needed during game play, including itself, in order to conserve memory.

The main program PLAY calls GENATOMS to generate NATOMS worth of atoms
on the screen.  The atom locations are stored as complex numbers in a
list called ATOMS.  GENATOMS does make sure that each atom occupies a
position in the black box not occupied by any other atom.

PLAY then calls DBOX to put the playing screen PICT (stored in SCREEN) up. 
Finally, PLAY calls MAIN which actually plays the game.

MAIN initializes two variables called NRAYS (containing the number of
rays that the user has fired) and NGUESS (containing the number of
guesses that the user has entered which are correct).  MAIN also does
keyboard processing.  If the user presses the ENTER key, MAIN calls
PROCESS which calls TRACERAY if the ENTER key was pressed whilst the
cursor was on a side rather than within the black box.  If the user
loses or quits the game, DRAWATOMS draws the locations of all atoms on
the screen by marking them with crosses.

Helper routines are NRAND, WRITE1, WRITE2, PUTSTR, PUTCROS, GETPOS and
PUTMASK.

Bugs
----

If you managed to make one correct atom guess, you can win the game by
repeatedly guessing at the same location until NATOMS reaches MAXATOMS.
The program does not check that you have already guessed at that location.
However, if you did that, you are merely cheating yourself.

Author
------
Chris Tham
30th of March 1991

Author's comments
-----------------
BBOX is my first non trivial programming project on the HP-48SX, so
please excuse me for any stupid coding styles or inefficiencies.
