                              ST Life v. 4.1



     0.      Welcome!


     The text you're reading now accompanies a program called ST Life. 
     If you do not know what to expect from a program with that  name, 
     you should start to read paragraph 1; in case you already do know 
     what life's about, continue at paragraph 2.



     1.      The Game of Life


     Life  is  a  0-player  game.  It is  played  in  a  2-dimensional 
     universe,  of  which the opposing edges are  connected.  This  is 
     because it really should be infinitely large,  which in this  way 
     is simulated somewhat.

     The  rules  of  Life are simple;  at a certain  location  in  the 
     universe (called a cell) there is either life (the cell is alive) 
     or not (the cell is dead). The only actions a cell can take is to 
     die  if it is alive and to be born if it's  dead.  These  actions 
     take  place in cycles,  the so-called generations.  Now  the  two 
     rules of standard Life are these:

          * Birth rule:  A  cell that is dead in generation t will  be 
                         alive in generation t+1 if and only if it had 
                         exactly three neighbours in generation t.
          * Death rule:  A cell that is alive in generation t will  be 
                         dead in generation t+1 if and only if  either 
                         it has less than 3 (exposure) or more than  4 
                         neighbours (overcrowding) in generation t.

     The death rule can negatively be stated as a survival rule:

          * Survival rule:    A  cell  that is alive in  generation  t 
                              will  be alive in generation t+1 if  and 
                              only  if  either it has exactly 3  or  4 
                              neighbours in generation t.

     You may wonder what the interest of this game is. It just happens 
     to  be  the case that Life has  interesting  mathematical/logical 
     features: I will mention these briefly (without any proofs).

          -    Life's  behaviour is chaotic;  the question  whether  a 
               given  Life-configuration will stabilise or not is  not 
               decidable.  In short,  the reason for this is that Life 
               can only determine certain configurations - those  that 
               do stabilise in finite time.
          -    Life  is powerful:  it is a system as powerful  as  any 
               computer, since it can be shown to be equivalent to the 
               One-Tape Turing Machine, which in turn is equivalent in 
               force  to any other  Turing  Machine,  lambda-calculus, 
               RAM-based machines etc. etc.

     You  can  get  more  information about  Life  in  a  book  called 
     "The Recursive Universe" by William Poundstone.



     2.      Hardware/Software requirements


     ST Life requires no specific memory size, no specific monitor, no
     hard disk and no specific TOS version.

     However:
          -  ST Life has 'only' been tested on TOS versions 1.0,  1.2, 
             1.4 and (moderately) 3.1;
          -  Only  in TOS versions 1.4 and later you get the  extended 
             fileselector;
          -  The availability of the smaller cell sizes depends on the 
             amount of available memory;
          -  In  ST  Low resolution,  the rightmost menu  is  slightly 
             wrapped around the edge of the screen;
          -  In some resolutions cells may be not exactly square;
          -  ST  Life  runs fine with recent versions of  QuickST  and 
             TurboST, and has no problems with the NewVDI;
          -  ST Life works fine with resolution emulators,  resolution 
             enhancers        (like       BigScreen        [software], 
             (AutoSwitch) Overscan    [hardware]    and    PixelWonder 
             [hardware]),  Two Page (A4) monitors and in all TT screen 
             modes;
          -  For quality printing GDOS may be desirable.


     3.      Manual for ST Life 4.1


     ST  Life interacts with the user as is usual for a  GEM  applica-
     tion,  using the mouse, menus, windows, dialogs, and alert boxes. 
     All menu options are available with key combinations too: the key 
     that  is  assigned to a menu item is represented  in  the  menu's 
     text. In this text, the '^' symbol denotes the [Control] key, the 
     'S'  symbol denotes a [Shift] key and the 'A' symbol denotes  the 
     [Alternate] key.

     At  current  there  exist four  versions  of  the  program,  each 
     basically  the  same program with a different  implementation  of 
     the user interface.  These is the standard ST-version (the  usual 
     GEM-style dialogs),  a bit more sophisticated "Mac-style" version 
     (still  ordinary  GEM,  but with crude 'real' radio  buttons  and 
     check boxes squeezed out of GEM), there is a version that uses an 
     extended dialog-handling library called XGEM,  and finally  there 
     is  a  very  sophisticated version that uses  the  MyDial  dialog 
     handler.
     In  this document,  I will refer to the different versions  using 
     the following names:
          *  ST_LIFE:    plain  GEM,  resource is incorporated in  the 
                         binary;
          *  MC_LIFE:    plain GEM with crude radio buttons and check-
                         boxes,   resource  is  incorporated  in   the 
                         binary;
          *  X_LIFE:     uses an extended dialog handler that provides 
                         movable dialogs and attaches keystrokes  (use 
                         Alternate-Key to select a button of which Key 
                         is underscored) to selectable items (visuali-
                         sed by underscoring), resource is external;
          *  MD_LIFE:    uses a dialog handler that does all the  XGEM 
                         version does,  but can also map the UNDO  key 
                         to  certain  buttons  (in  both  dialogs  and 
                         alerts: if there is only one button in alerts 
                         it   is  selectable  by  its   Alternate-Key, 
                         Return   as  well  as  UNDO  -   furthermore, 
                         'Cancel'  buttons and the like get  the  UNDO 
                         key);  also  more well-behaved than  XGEM  in 
                         many respects.
     Needless to say, these names need not coincide with the filenames 
     in the distribution.  At this moment, writing this documentation, 
     I  am  not  even sure which versions will make it  to  the  final 
     release  -  although  I am somewhat  biased  towards  the  MyDial 
     version right now, so I'll probably name that one simply LIFE.PRG 
     (and its resource LIFE.RSC).

     Printing is performed by GDOS,  when available:  without GDOS, ST 
     Life  performs screen-dumps using the system's routine  (the  one 
     you get when you press Alternate-Help).

     You  can  draw in the window using the  common  mouse-techniques: 
     pressing  the  left button somewhere will force the cell  at  the 
     pointed  location to be born (drawn),  pressing the right  button 
     will kill (undraw) a cell.  While drawing the computation of  the 
     next  generation of cells is paused,  so while there is  a  mouse 
     button  pressed you're in editing mode.  You will be informed  of 
     the  actual editing mode (draw or erase) by the changing  of  the 
     mouse cursor:  the hairline cross indicates drawing,  the  hollow 
     cross erasing.

     Before describing the program's features by touring the menus,  a 
     small  word  on the various ways of starting the  program  first. 
     ST Life will accept a filename as a parameter:  if a parameter is 
     given  to  the  program  (by  calling it  from  a  shell  with  a 
     parameter,  or  by installing it as a GEM  application  accepting 
     '*.LF'  files)  this parameter is interpreted as the  name  of  a 
     Universe file,  which ST Life will then restore (if possible) and 
     run.
     In case no parameter is specified, ST Life will look for the file 
     'LIFE.LF'  in the current directory,  which - if found - will  be 
     loaded,  but not executed.  Since the Universe files contain full 
     configuration details,  this is a way of saving default  settings 
     for ST Life.
     Well, now that's all out of the way let's get down to business.

     The menus are (without the keyboard equivalents):

      LIFE  File  Initialize Settings

          A.   "LIFE"-menu

             In  the  "LIFE"-menu  there  is (as far  as  ST  Life  is 
             concerned)  only the option "The Facts  of  Life",  which 
             tells  you the current version number,  and the names  of 
             the programmers and contributors.

             Note  that the desk accessory entries are disabled  while 
             ST Life is updating the screen.

          B.   "File"-menu

             "Load..." loads,  and "Run" runs,  the universe  selected 
             using  the  fileselector.  Note  that  ST Life  uses  the 
             extended  fileselector  whenever possible (TOS  >=  1.4). 
             Settings are restored to the ones saved;  Incorrect files 
             are  not  loaded.  A hidden feature:  if a  modifier  key 
             (Alternate,  Control,  Shift  L  or R) is  pressed  while 
             loading,  or  Caps  Lock  is on,  X-  and  Y-offsets  and 
             transformations  can be specified (see "Change  Universe" 
             below).
             Because  of this feature,  it could be very  inconvenient 
             for a user to accidentally enter ST Life while Caps  Lock 
             is active.  For this reason,  ST Life resets the state of 
             the Caps Lock key to "not pressed" when starting.

             The  option  "Save..." allows you to  save  the  universe 
             currently on screen to a file, for which you will have to 
             choose a name using the fileselector first.

             The  command  "Merge XLIFE file..." loads  a  XLIFE  file  
             without  clearing the universe first:  the user is  given 
             the  opportunity to select operations on these files  and 
             (possibly negative) offsets first.  Negative offsets  are 
             selected by clicking the box containing the '-' sign next 
             to the field where the number is specified.

             "Load XLIFE file..." does the same as "Merge",  but clears 
             the universe before interpreting the file.

             "Save XLIFE file" saves a XLIFE coordinate  file.  Saving 
             is performed in the RELATIVE file format (see below).  An 
             'owner'  line is inserted to let the world know the  file 
             was written by ST Life.

             "XLIFE file info..." informs you of the type of the  file 
             and the ranges the coordinates in the file are in.

             The currently supported XLIFE file formats are  described 
             in Appendix III.

             Next  is the "Print"-command,  which first lets you  pick 
             out a magnification factor for printing,  then prints the 
             currently  shown universe to the printer as installed  by 
             GDOS.  If  GDOS  is not installed an  alert  will  appear 
             stating that sad fact and the option is given to  perform 
             a  screen  dump instead.  The program will in  that  case 
             then  change the menu entry from 'Print  Universe...'  to 
             'Print  Screen'.  Next times you issue this  command  the 
             screen  is  dumped right away.  The screen dump  that  is 
             performed  is  the  same thing  you  get  after  pressing 
             [Alternate]-[Help], with one subtle difference: the mouse 
             is switched off while printing the screen.

             See Appendix I for more information about GDOS.

             The  last  entry  in this  menu  is  "Quit  Life",  which 
             (surprise!) quits ST Life.

          C.   "Initialize"-menu
     
             The  first entry here is "Random";  you can initialize  a 
             universe randomly by choosing this.

             "Clear Universe" empties the universe totally.

             "Fill Universe" fills the universe completely.

             "Change  Universe..."  lets the user select a  number  of 
             transformations to be applied to the  universe.  Included 
             are  X<->Y swapping and X- and Y-mirrorring,  as well  as 
             'shifting'  the universe in X- and  Y-direction.  Offsets 
             may  be  entered by typing in a value (in which  case  it 
             should be noted that the minus sign will (naturally) only 
             be accepted as the first character of the number) or  set 
             by  clicking  the adjacent '-'  or  '+'  buttons.  Double 
             clicking  these  buttons will decrease  or  increase  the 
             value by 10, single clicking will add or subtract a value 
             of  one.  These  action will be repeated as long  as  the 
             mouse button is held down on the selected button.
             Note that when holding down the mouse button on a '-'  or 
             '+'  button will result in relatively slow  modifications 
             at first;  as the mouse button is held down for a  longer 
             the changing gets more rapid.

             "Go!" toggles computing and drawing generations.

          D.   "Settings"-menu

             "Invert Screen" inverts the screen.

             "Connect Edges" toggles between connected and unconnected 
             edges.

             "Step  On Keypress" (if checked) waits for a keypress  to 
             compute the next generation.

             "Random  Factor" selects the probability of a cell to  be 
             alive if a universe is initialized randomly, indicated by 
             a percentage.

             "Delay" lets you specify a time to wait between  consecu-
             tive generations;  it is checked if a delay time  unequal 
             to zero is selected.

             "Cell  Border" allows you to select whether there  should 
             be  space inbetween cells when drawing them.  More  cells 
             fit  without  a border,  but,  especially at  small  cell 
             sizes,  it  can get very hard to get an accurate view  of 
             the state of affairs.

             "Cell Size" selects the cell size to use:  images of  the 
             sizes you are allowed to choose from are selectable.

             The  "Set  Rules" menu item(s) allows you to  change  the 
             rules of the game. You select the cases in which you want 
             birth respectively survival to take place.

          E.   "Help"-menu

             The  "Help" menu has only one item to select -  and  that 
             item offers help,  kind and generous help.  The Life help 
             system  is  an adaptation of a generic  interactive  help 
             system:   read  the  documentation  to  README.PRG  -  by 
             doubleclicking README - and you'll understand.
             You could of course just hit the [HELP]-key in  Life,  or 
             select the menu, and see how far you'll get.


     Appendix I - GDOS

     GDOS  is a part of the ST's Operating System that (alas) was  not 
     incorporated  in  the ROMs;  for certain system  routines  to  be 
     available it must be loaded at boot time.
     GDOS is loaded by putting GDOS.PRG (from Atari) or an alternative 
     GDOS implementation (i.e. G+PLUS, AMCGDOS, NVDI, FSM-GDOS) in the 
     AUTO  folder of your boot disk,  and a configuration  file  named 
     ASSIGN.SYS in the top level of your boot disk.  The following  is 
     an example of a (minimal) ASSIGN.SYS file:

          Path = C:\GEMSYS\
          01p SCREEN.SYS  ; Default screen
          02p SCREEN.SYS  ; Low-rez screen
          03p SCREEN.SYS  ; Med-rez screen
          04p SCREEN.SYS  ; High-rez screen
          21 DJET300.SYS  ; Printer driver filename

     This  is all ST Life needs;  you don't even have to install  GDOS 
     fonts.  For your information:  the marvellous program NVDI,  that 
     replaces the ST's VDI screen driver with a much better one,  also 
     contains GDOS support.
     More detailed information about GDOS and ASSIGN.SYS files can  be 
     found  in  "Everything you ever wanted to know  about  GDOS  (and 
     more)"  by  Douglas N. Wheeler,  which  is  available  on  a  few 
     Internet sites and possibly on some bulletin boards as well.



     Appendix II - ST Life Change History

     Version 4.1:

          -  Based  on an old on-line documentation reader patched  up 
             by  me  and a friend (see the included  documentation  to 
             HELPLIB)  I managed to integrate an on-line  hierarchical 
             help system into the Life program.

     Version 4.0:

          -  A   new   and  very  sophisticated  user   interface   is 
             implemented, alongside with more ordinary ones, amounting 
             to  a total of four programs that are  different-yet-the-
             same  -  different  in  look  and  feel,   the  same   in 
             functionality;
          -  A  change  that  appears  in  all  versions:  the  incre-
             ment/decrement  buttons  in the Change-dialog  now  react 
             with a little repeat-delay initially; this delay vanishes 
             quickly  if  the mouse is  held  down.  This  facilitates 
             accurate control over small adjustments;
          -  There  is now visual feedback of the  editing  mode:  the 
             thin cross draws, the outline cross erases;
          -  Except  for  the  MC_LIFE  variation  all  versions  have 
             (again) two menu items for the two sets of rules. This is 
             done to make full keyboard control possible: if there are 
             two  boxes  in one dialog that each  contain  nine  radio 
             buttons labelled '0' to '8',  only one of these sets  can 
             get  proper  key  bindings,  but if  only  a  single  box 
             containing  buttons  labelled  '0' to '8'  appears  in  a 
             dialog   these   buttons  simply  get   Alternate-0   ... 
             Alternate-8 as keyboard equivalents;
          -  The key equivalents of the menu items are now (using  the 
             Normalized Key Code Converter written by Harald Siegmund) 
             independent  of the actual TOS country-version.  Even  if 
             the keyboard layout differs greatly from the US keyboard, 
             the  keys  should work.  For  instance,  since  selection 
             (before  4.0) was done by comparing  SCAN  codes,  typing 
             Control-Z on my keyboard yields the same effect as typing 
             Control-Y on a german keyboard. Not anymore!
          -  A few very tiny anomalies are removed: when informing the 
             user  of  being busy the mouse also turns into  the  busy 
             bee, when shifting a universe 'out of bounds' it possibly 
             wasn't redrawn correctly (if at all).

     Version 3.2:

          -  The user-interface has been changed somewhat:  the selec-
             ting  radio buttons of the various 'Set' dialogs now  are 
             more Macintosh-like; the same goes for check boxes in the 
             Rules and Change dialogs.  These dialogs now contain real 
             check boxes.
             As a result of these aesthetic changes it became possible 
             to  integrate the setting of the two sets of  rules  into 
             one dialog box,  which in its turn results in one  lesser 
             menu entry.
          -  A  very  minor flaw in the printing  mechanism  has  been 
             corrected,  which  could cause the print  scaling  dialog 
             not  to  respond to carriage returns if this  dialog  had 
             previously been exited by way of the cancel button.

     Version 3.1:

          -  An  unforeseen  error in TOS 1.2 has given rise  to  this 
             version:  it  fixes a bug in the file I/O connected  with 
             TOS 1.2's "feature" of permanently forgetting its DTA;
          -  Another  weird  bug connected to TOS  1.2  appeared:  the 
             computer  froze  (AES  never  succeeded  in  closing  the 
             window)  after pressing ^C,  although the  code  executed 
             after  pressing  that  key was identical  to  that  after 
             selecting  'Quit'  in the 'File'  menu.  So,  instead  of 
             performing  the desired action after a command  has  been 
             initiated  by  a keypress,  ST Life now  sends  itself  a 
             message that a menu was selected. Kinda neat, right?
          -  A  general revision to the source has been made:  Line  A 
             support  is  dropped,  and so is the support  for  static 
             memory allocation.

     Version 3.0:

          -  Keyboard control added;
          -  Without  GDOS,  printing can now be performed by  dumping 
             the screen;
          -  Reading of all current XLIFE file formats supported;  the 
             descriptive  format,  dropped in version 1.5,  is one  of 
             them;
          -  Transforming  universes  (mirrorring,   X<->Y   swapping) 
             implemented;
          -  Offsets  specifiable when loading a universe (hidden  for 
             'LF' universes,  available with Ctrl,  Alt,  Shft or Caps 
             pressed);
          -  Cell border can now be disabled;
          -  Cell size 1 added;
          -  Cell  size  2 added (again,  dropped  before  because  of 
             slowness);
          -  Disconnectable edges added;
          -  Time delay setting added;
          -  Step mode added;
          -  Printing enlargement 1:1,  1:2, 1:3 and 1:4 selectability 
             added;
          -  Much faster changes-dependant generation of next  genera-
             tions;
          -  Life now runs in ALL resolutions;
          -  Drawing\erasing while running now possible for more  than 
             a single cell;
          -  File  format  extended (all relevant settings  are  saved 
             now);  the 'old' file format of Life 2.4 is not supported 
             anymore,  so  the  program  LF2LF  came  into  existence, 
             translating 'old' format to 'new' format;
          -  Default universe 'LIFE.LF' loaded on startup if existent;
          -  Universe-file  passed as a parameter loaded and  executed 
             on startup, so Life can be installed as a GEM application 
             for *.LF files.


     Version 2.4 (First public release):

          -  Added user-selectability of the rules.
          -  Extended the file format to contain cell size.


     Version 2.2:

          -  Added screen inversion,  selectable cell sizes and random 
             factors.
          -  Dropped  Metafile creation support (what was it good  for 
             anyway?).
          -  Added (source-level,  selectable at compile-time) Line  A 
             support.
          -  Added  (source-level)  support of resource  inclusion  in 
             program.


     Version 2.0:

          -  Rewrite  to GEM user interface,  with output in  windows, 
             user  control  by  use  of menus  and  GDOS  printer  and 
             Metafile support.


     Version 1.5:

          -  Mouse-based drawing routine built in, file format changed 
             to a less space-consuming one.


     Version 1.4:

          -  Output is now in graphics (Yeah!).


     Version 1.3:

          -  Pascal version 1.2 ported to Turbo C.


     Version 1.2:

          -  Loading  and  saving  of files  (descriptive  ASCII  file 
             format) implemented.


     Version 1.1:

          -  Randomizer built in.


     Version 1.0:

          -  The  Game  Of Life implemented on  the  ST,  in  Personal 
             Pascal, using character output, with a rather clumsy user 
             interface  of consecutive alert boxes,  and a  predefined 
             universe consisting of a single blinker only.



     Appendix III - file formats


     The ST Life File Format

     The  ST Life custom file format (which has  remained  essentially 
     the  same  -  apart from the Version field -  from  3.0  onwards) 
     starts with a header of the following type:

     struct
          {
               LONG   Magic;       /* $4C696665  =  "Life" */
               WORD   Version;     /* $3431 = "41", for  4.1 */
               struct
                    { /* Config items are bitflags, so either 0 or 1 */
                         unsigned Colour      :1;
                         unsigned Wrap        :1;
                         unsigned Step        :1;
                         unsigned Border      :1;
                         unsigned BigUniverse :1;
                    } Config;
               BYTE   RandomFactor;     /* 3  ...  6 */                 
               BYTE   CellSize;         /* 1, 2, 4, 6, 8, 10, 12 or 14 */
               BYTE   Speed;            /* 1 ... 6 */
               Conditions Birth;
               Conditions Survival;
          } FileHeaders;

     Here  Speed and RandomFactor fields encode the object numbers  of 
     items in the configuring dialogs, as follows:

     RandomFactor:       Means:           Speed:      Means:

          3               25%               1         No delay
          4               20%               2         Wait 500 ms.
          5               10%               3         Wait 1 sec.
          6               15%               4         Wait 2 sec.
                                            5         Wait 4 sec.
                                            6         Wait 8 sec.

     Colour is either black (0) or white (1);  Wrap,  Step, Border and 
     BigUniverse are boolean values, that is: either true (1) or false 
     (0).  The BigUniverse flag determines how to read the part of the 
     file  following  the  header:  if the  largest  coordinate  of  a 
     universe is smaller than 256,  then the coordinates are saved  as 
     (8-bit)  unsigned  chars,  and BigUniverse is  set  to  0.  Else, 
     coordinates  were  saved  as (16-bit)  integers  and  BigUniverse 
     equals 1.
     The  "Conditions"-items  Birth  and  Survival  are  arrays  of  9 
     boolean  values,  in  which  for each  number  of  neighbours  is 
     specified whether or not birth respectively survival occurs  with 
     that number of neighbours. For example, if Birth[3] equals 1 then 
     birth occurs for cells with three neighbours.

     Dependent on the value of BigUniverse,  the fileheader is  either 
     followed  by a number of bytes or by a number of  words,  forming 
     the data part of the file. This part consists of pairs of X and Y 
     coordinates,  with X and Y occurring in consecutive order (so the 
     data  part contains X0,Y0,X1,Y1,...,Xn,Yn if the  coordinates  of 
     n+1 cells were saved).


     The XLIFE File Formats

     There are three types of XLIFE files:

          ABSOLUTE, consisting  of lines containing X and Y  coordina-
                    tes.  This  is the default XLIFE file  format,  so 
                    there  is no need to set it explicitly:  but  "#A" 
                    starting  the  first  line  selects  this   format 
                    anyway.

               Example (a blinker):
                    3 0
                    3 1
                    3 2

          RELATIVE, which  is the same as ABSOLUTE,  but but with  all 
                    coordinates  written relative to an offset  speci-
                    fied in the first line, following a "#R" indicator 
                    for determining the file type.  This is the format 
                    that Life uses to write XLIFE files.

               Example (a blinker):
                    #R 3 0
                    0 0
                    0 1
                    0 2

          PICTURE,  in which a line number codes an Y coordinate,  and 
                    positions on lines marked with '*' code X  coordi-
                    nates.  The  first line starts  with  "#R",  after 
                    which offsets are optionally specified.

               Example (a blinker):
                    #P
                    ...*...
                    ...*...
                    ...*...

               Or:
                    #P 3 0
                    *
                    *
                    *
