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 * * *