  **       **       ******                        **   
   **     **       **    **                       **   
    **   **        **     **                      **  **
     ** **         **     **                      ** **                  **
      ***     ***  ********   * ***  ****   *** * ****    ****  **  ** ******
     ** **         **     **  ***   **  ** **  ** ***    **  ** **  **   **
    **   **        **     **  **    ****** **  ** ****   **  ** **  **   **
   **     **       **     **  **    **     **  ** ** **  **  ** **  **   **
  **       **       *******   **     ****   *** * **  **  ****   ****    **

Written by:   James W. Garacci (BS Computer Engineering)
"     " at:   Milwaukee School of Engineering
"     " on:   April 20, 1995
Last updated: May 12, 1995


				Abstract

	This document describes the X-Breakout game.  This is done by giving
a brief explanation of the game concept, a description of how to use the game,
and a breakdown of the programs modular hierarchy.  It also provides a means
by which users can give suggestions for further work to the designer.


Contents
========

   Introduction
   Usage
   Programming
   Further Work
   Contacting Designer
   Final Comments   


Introduction
============

	This game is based on the classic game 'Breakout'.  The game is
comprised of a playing field bounded by side walls and the top.  It also
contains a set of bricks that are always located near the top of the playing
field, a ball that can be used to destroy the bricks, and a paddle that can be
moved from left to right at the bottom of the playing field.  The object of the
games is to as many bricks on as many levels as possible before all of the 
available balls are lost.  To do this the player must keep the ball from 
hitting the bottom of the playing field by moving the paddle to repel the ball
back towards the top of the playing field.  If a ball touches the bootom of the
playing field then it is lost and another ball must be used.  Once all of the
available balls are used the game is over.  Extra balls can be obtained as the
player's score increases.


Usage
=====

	The application was written using the X Window System and Motif, in C
and UIL.  Therefore, the application will only compile if X and Motif are 
available.  The "xbreakout-1.0.tar" file should be about 145,000 bytes.
It should also include the following directory structure:

	breakout (source, and executable after compilation)
	 |
         +-data  (breakout data files)
         |
         +-obj   (object files after compilation)

The following files should also be included in the "xbreakout-1.0.tar" file:

	breakout/store_color.c		breakout/file_load_level.c 
	breakout/add_node_to_dll.c 	breakout/breakout.var
	breakout/init_breakout.c 	breakout/breakout.ext
	breakout/motif.var 		breakout/save_widget_info.c
	breakout/cb_create.c 		breakout/set_gc_color.c
	breakout/cb_new.c 		breakout/cb_input.c 
	breakout/cb_exit.c 		breakout/popup_dialog.c
	breakout/cb_redraw.c 		breakout/cb_sound.c
	breakout/update_display.c	breakout/cb_about.c
	breakout/dll.h 			breakout/move_paddle.c
	breakout/init_headnode.c 	breakout/cb_help.c
	breakout/breakout.uil		breakout/MODIFICATIONS
	breakout/makefile 		breakout/data/level.007
	breakout/motif.ext 		breakout/data/help.hlp
	breakout/motif.h 		breakout/data/level.005
	breakout/breakout.c 		breakout/data/breakout.img
	breakout/add_a_color.c 		breakout/data/level.002
	breakout/breakout.h 		breakout/data/level.003
	breakout/cb_pause.c 		breakout/data/level.001
	breakout/README			breakout/data/level.004
	breakout/retrieve_widget_id.c 	breakout/data/breakout.hlp
	breakout/remove_node_from_dll.c	breakout/data/level.006
					breakout/data/level.008

Making the executable
---------------------

	The Makefile provided with this application will most likely not work
properly on all machines.  It can be easily modified by changing lines 4, 6, 7,
and 10 such that the appropriate paths for the machine are specified.

Game Play
---------

	The application is started in the end of game state, therefore to
begin playing a new game must be started.

Starting a New Game:

	To start a new game the New option must be selected from the Game menu.

Pausing the game:

	The game can be paused or unpaused at any time by pressing the 'P' key 
as long as focus is in the playing field, or by selecting the Pause option from
the Game menu.  This is very useful when making modifications to the code.

Sound:

	The sound can be turned on or off at any time by pressing the 'S' key
as long as focus is in the playing field, or by selecting the Sound option from
the Game menu.  This feature was added because many of my co-students were 
complaining about the constant beeping the terminal makes every time a brick 
is destroyed.

Adding Levels:

	New files can be added as follows:

        1) Create an ASCII text file with the standard name

        2) Follow the file format

        3) Make the file read access to all

1) Creating an ASCII text file

        This can be done using "vi", or "edt".  The file should be
named according to the following:

        The files should be numbered using the standard of level.###,
where ### starts at 001 and goes incrementally up to some maximum
number 999.

For Example:

        level.001
        level.002
        level.003
        level.004
        level.005

Since "level.005" is the last level, "level.001" will be used again
in order to allow continuation of the game.

2) Following the file format

        The first integer in the file indicates the number of rows
for the current level.  This must be between 1 and 10 or the program
will output an error message and terminate.

Next, the file must list the contents of the specified rows of 10
characters each.  The valid characters are described below:

        1-9 are values of bricks in 100 point units.
        0 is a space
        # is an unmovable brick.

The colors corresponding to the values are listed below:

                0 - Black       5 - Violet
                1 - Red         6 - Yellow
                2 - Green       7 - Brown
                3 - Blue        8 - Olive
                4 - Turqoise    9 - Grey
                # - White

The file may also contain any desired comments, as long as they
appear after the row descriptions.

* Note:  Watch out for using too many unmovable bricks.  This may lead
         to trapped balls.

3) Making the file read access to all

        This can be done using the "chmod" command.

For Example:

        chmod a+r level.###

where ### is the number of the level to be given global read access.


Programming
===========

Modular Breakout :)
-------------------

	The hierarchy of the modules used in the program is shown below.

main
 |
 +---------------+---------------------+
 |               |                     | 
 +-popup_dialog	 +-retrieve_widget_id  +-XtAppMainLoop
    |                                     |
    +-retrieve_widget_id                  +-cb_about
    |                                     |
    +-save_widget_info                    +-cb_create
                                          |
cb_about                                  +-cb_exit
 |                                        |
 +-popup_dialog                           +-cb_help
 |  |                                     |
 |  +-retrieve_widget_id                  +-cb_input
 |  |                                     |
 |  +-save_widget_info                    +-cb_new
 |                                        |
 +-retrieve_widget_id                     +-cb_pause
                                          |
cb_create                                 +-cb_redraw
 |                                        |
 +-save_widget_info                       +-cb_sound
                                          |
cb_help                                   +-move_paddle
 |                                        |
 +-popup_dialog                           +-update_display
 |  |                                     
 |  +-retrieve_widget_id                  update_display
 |  |                                      |
 |  +-save_widget_info                     +-retrieve_widget_id
 |                                         |
 +-retrieve_widget_id                      +-set_GC_color
                                           |
cb_input                                   +-remove_node_from_dll
 |                                         |
 +-cb_pause                                +-file_load_level
                                           |
cb_new                                     +-cb_redraw
 |                                        
 +-retrieve_widget_id                     file_load_level
 |                                         |
 +-remove_node_from_dll                    +-init_headnode
 |                                         |
 +-file_load_level                         +-add_node_to_dll
 |                                         
 +-update_display                         init_breakout
                                           |
cb_redraw                                  +-retrieve_widget_id
 |                                         |
 +-init_breakout                           +-add_a_color
                                           |
add_a_color                                +-set_GC_color
 |
 +-store_color                                           

The purpose of each module is described below:

main:   This module initializes the Mrm and sets up the XtAppEventHandlers.  It
	also displays the main window.

popup_dialog:  This module retrieves and displays the specified dialog box.

retrieve_widget_id:  This module retrieves the Widget identification number of
    	the specified named widget, as long as the widget was saved in the
	global widget list.

save_widget_info:  This module stores the information about the specified
	widget into the global widget list.

XtAppMainLoop:  This X Toolkit function is given control of the application.
	It calls the appropriate modules specified to handle events.

cb_about:  This module displays the about dialog box.

cb_create:  This module calls save_widget_info when a widget to be stored is
	created.

cb_help:  This module displays the help dialog box.

cb_input:  This module processes the input from the keyboard when focus is on
	the playing field.

cb_new:  This module initializes the game by deallocating any previously used
	memory, loading the first level, and starting the update event cycle.

remove_node_from_dll:  This module removes a specified node from a double
	linked list.

file_load_level:  This module loads a level of Breakout from a level data file.

init_headnode:  This module initializes the headnode of a double linked list.

add_node_to_dll:  This module adds a node to a double linked list.

update_display:  This module updates the position of the ball, the state of any
 	bricks in the playing field, and the score of the player.  It then
        draws the playing field and sets another update event to occur.

set_GC_color:  This module sets the color of a specified graphics context.

cb_redraw:  This module redraws the playing field by copying a pixmap to the
    	Breakout window.

init_breakout:  This module initializes the colors, the pixmap, and the basic
  	playing field.

add_a_color:  This module adds a specified color to the system colormap.

store_color:  This module stores a specified color into the system colormap.


Further Work
============

	In the next release of the game I hope to make a number of
enhancements.  These include more realistic ball motion, expanded playing
field size, and bricks containing special items (e.g. gun, extra ball/player,
next level, large paddle, split (forked) ball, etc.)

	Feel free to make any modifications to the program.  If you do, please
indicate what modifications were made in the "MODIFICATIONS" log file.


Contacting Designer
===================

	If you have any questions, concerns, or suggestions for 
enhancements/maintenance, please contact Brian Peschel at 
"peschelb@warp.msoe.edu".  He will be able to contact me.  This is necessary
because I am graduating from MSOE and as a result will be losing my account.


Final Comments
==============

	I hope you enjoy playing.  Until Version 2.0...
