
/*  @(#)README 1.7 91/09/05
 *
 *  Screen design and original implementation
 *               Copyright (C) 1981, 1982, 1983 - Brad A. Myers
 *
 *  Current implementation
 *               Copyright (C) 1991 Rich Burridge
 *
 *  Permission is given to distribute these sources, as long as the
 *  copyright messages are not removed, and no monies are exchanged.
 *
 *  No responsibility is taken for any errors on inaccuracies inherent
 *  either to the comments or the code of this program, but if reported
 *  to me, then an attempt will be made to fix them.
 */

Sidtool - README - September - 1991.

--------------------------------------------------------------------------
CONTENTS:

1. What is Sidtool?
2. Getting started.
3. Creating a different maze.
4. Sidtool history.
5. Acknowledgements.
--------------------------------------------------------------------------

1. What is Sidtool?
-------------------

This is version 3.0.3 of sidtool (a pacman like game). It's the third major
release of the software. The first two versions were written in SunWindows
(1985) and SunView (1987) respectively for Sun workstations. Sidtool has now
been converted to XView (an X11 toolkit). Although the software has only been
tested on Suns, I hope it should be fairly easy to port to other systems
running Unix, C and XView.

See the manual pages or the online help for more details of how to play
the game.

The graphics user interface has been designed using Suns' devGuide. This
automatically generates the sidtool_ui.c and sidtool_ui.h files, and the
stubs for the notify procedures have been added into the xview.c file. I
can generate stubs and ui files for OLIT and tNt if anybody is interested
in creating versions of sidtool using those toolkits.

---------

There is a mailing list for people interested in sidtool. It is:

  sidtool@Aus.Sun.COM

To get added to the list, send a request to:

  sidtool-request@Aus.Sun.COM

This list will primarily be used for sending out patches, rather than bother
the net in general, but could also be used for discussion on possible
enhancements to the game.


2. Getting started.
-------------------

Initially there is no Makefile file present in the sidtool source directory.
You will need to copy Makefile.dist to Makefile, then adjust accordingly.

You need to do a "make" followed by a "make install". You might need
super-user permission to do the latter successfully.
 
The Makefile compilation details are setup to default to compiling on a
Sun running SunOS v4.1.1 with OpenWindows V3.

Note that there are various compilation definitions that might need
adjusting if you are trying to compile and run it on any other machine
or operating system.
 
These are:

SUNARROW     - Sun specific: uncomment to use the arrow keys for movement.
XVIEWINCDIR  - location of the XView #include files.
XVIEWLIBDIR  - location of the XView libraries.

See the Makefile for a more detailed description of each of these definitions.

-----

As sidtool is ported to other machines, I expect this list to grow. New
entries will be added to the Makefile.dist, and summarised here.

If you need to make changes in order to get sidtool to compile and run
on your system, please let me know the details (see email address below),
and I will try to include them into a future version.

See the TODO file for the list of known problems and ideas for future
enhancements.

Note: This software was developed and tested on a Sun SS1+, and the speed
      feels correct for this machine. Running sidtool or other machine might
      require some tuning of the pause routines.

WARNING.
--------
Sometimes there are problems with the colors used by sidtool, after
something like xlock has been run. A workaround (when using Open Windows)
is to run "reservercolors -svmono", which prevents the last two colormap
entries being compromised by xlock.


3. Creating a different maze.
-----------------------------

Sidtool has been designed to allow you to specify alternate mazes. You can
use this new maze layout with sidtool, with the -maze command line option.
The maze layout should be contained in an ASCII file, and conform to the
following requirements:

 *  The maze size is fixed at 26 by 28.
 *  The maze is not allowed to have any dead ends.
 *  All boxes in the maze are defined by paths.
 *  The upper left corner of each box is signified by a small s.
 *  Use the letters r,d,l,u to signify the direction to travel around boxes.
 *  Corners must be signified by changing the letter.
 *  The tunnel start must be signified by a capital S.
 *  The exit box must have the opening at the top.
 *  The ghost number 0 must be started directly above this exit.
 *  The exit should be signified by capital R's.
 *  All ghosts except for one must start in the box.
 *  The amount of time spent in the box is specified by the number which
    shows where the ghost goes.
 *  Small dots in the maze are signified by periods '.';
 *  Large dots in the maze are signified by asterisks '*';
 *  Tunnels may be on left and right.
 *  All tunnels must have exits at both sides.
 *  There must be a row around the entire maze defining the border.
 *  All non-tunnel parts of the border must be 'x's
 *  The area in the tunnel in which the ghosts go slowly is defined as the
    area between the exit and the first non-space character.  Thus a '.'
    causes the ghosts to speed up.

The default maze (which is hard-wired in) looks like this:

rrrrrrrrrrrrrdxrrrrrrrrrrrrd
u............d u....0......d
u.sd.srrrrrd.d u.srRRrd.sd.d
u*ud.udlllll.rru.u   8d.ud*d
u.ul.ud..........u98  d.ud.d
u....ud.sd.sd.sd.ulllll.ul.d
ulll.ud.ul.ud.ud...........d
x  u.ud....ud.ud.srrrrrd.dll
Srru.ul.rrrud.ud.u dllll.rrx
    ....ullll.ul.ull....    
Srrrrrd..............sd.rrrx
dllllll.srrrrrrrd.rd.ud.ulll
d.......udlllllll*ud.ud....u
d.sd.sd.ud........ud.ud.sd.u
d.ud.ul.ud.srrrrd.ud.ul.ud.u
d.ud....ud.ulllll.ud....ul.u
d.urrrd.ud        ud.sd....u
d.ullld.urrrrrrrrrud.ud.sd.u
d....ud.ulllllllllll.ud.ud.u
d.sd.ud..............ud.ud*u
d*ud.urd.srrrrrrrrrd.ud.ud.u
d.ul.uld.ullllllllll.ul.ul.u
d.....ud.....  ............u
rrrrd.urrrd.srrrrd....srd.ru
xllll.ullld.ulll d....ull.uT
   ......ud....uld.sd.....  
Srd.srrd.ud.rd..ud.ul.srd.rx
x d.ulll.ul.urd.ul....ull.ux
x d.........u d....rd.....ux
xxrrrrrrrrrruxrrrrrurrrrrrux


4. Sidtool history.
-------------------

Sidtool is based on the Perq Interactive debugger program, written by
Brad A. Myers when he was at ThreeRivers Inc., back in the early 1980's.
At that time it was written in Pascal for the POS operating system. About
1985 I converted it to run under Unix and C on Sun's using SunWindows. This
first version of sidtool was actually two programs "talking" to each other
via a pipe. One program updated the screen, the other program read input
from the mouse and the keyboard. This was required because at that time,
SunWindows could not do explicit dispatching of events.

The second version of sidtool, was a "port" to SunView in 1987, and the
program was modified to use a timer routine and a state machine, which
listed all the possible states the program could be in. The graphics were
simple, and in fact only used drawing to a graphics canvas.

This third version has again been "ported" to the latest flavour-de-jour in
window systems, with the graphics interface being rewritten using Suns'
devGuide. It therefor now makes use of a control panel with buttons, sliders,
popup windows, scrolling list, a property sheet and the works. It's been
written in the XView toolkit, but versions could easily be generated for
OLIT or tNt.


5. Acknowledgements.
--------------------

Thanks go to Brad Myers for the original game.

To Dan Heller for the basis of the joystick interface which was introduced
in the second release back in 1987.

To Stuart Marks for the code to handle the Sun arrow keys.

Thanks also to Jeff Blows, Yingchun Guo, Neeta Ganguly and Stan Ken Tazuma
for various bug reports/fixes and suggestions for enhancement.

Suggestions for furthur improvement would be most welcome, plus bugs,
comments and flames. Please address all correspondence on sidtool to
Rich Burridge at the address below.
 
Brad A. Myers                              Rich Burridge
School of Computer Science                 Sun Microsystems Australia,
Carnegie Mellon University                 495 Victoria Avenue,
5000 Forbes Avenue                         Chatswood, NSW 2067.
Pittsburgh, PA  15213-3890                 AUSTRALIA.
TEL: (412) 268-5150                        TEL: +61 2 413 2666
FAX: (412) 681-5739                        FAX: +61 2 413 3869
bam@a.gp.cs.cmu.edu                        richb@aus.sun.com
