** ** ****** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** *** *** ******** * *** **** *** * **** **** ** ** ****** ** ** ** ** *** ** ** ** ** *** ** ** ** ** ** ** ** ** ** ** ****** ** ** **** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ******* ** **** *** * ** ** **** **** ** Written by: James W. Garacci (BS Computer Engineering) " " at: Milwaukee School of Engineering " " on: April 20, 1995 Last updated: September 20, 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 James Garacci at "garacci@ttd.teradyne.com". My current location is: Teradyne, Inc. 1405 Lake Cook Rd. Deerfield, IL 60015 Making Modifications ==================== I hereby grant permission to modify and distribute xbreakout-1.0 as freeware only, given that I am notified of the modification and/or distribution. I may also grant permission to release xbreakout-1.0 as shareware or in some form of tangible medium, given that I am again notified. Final Comments ============== I hope you enjoy playing. Until Version 2.0...