Amiga Life, The Compleat Intuition Example Copyright (c) 1987,1988 McManis & McManis Software All Rights Reserved. 1.0 OVERVIEW This is an implementation of Life for the Amiga. It incorporates a number of features that are unique to this implementation, including user settable rules, and multiple species support. The binary is freely distributable, use it and enjoy it. The code for this program is a very complete example of how to use all of the calls to Intuition as well as many tricks and techniques that are not documented anywhere. This aspect of the program is not free. See the section below for more details. 1.1 The Package First off, you should note that this program is not public domain. That is, you cannot sell it for a profit without both my permission and giving me a cut, however you can give the executable away free or as part of a library collection if you include this file and don't modify it or the executable in any way. If you are a user of the Amiga and just like playing with this stuff then enjoy this program with my blessings, no further effort on your part is required. If you are a developer of software, or would just like to know how this program works, then have I got a deal for you! :-) You can buy the source and a description of how it works, right down to the last gritty detail. What you get when you buy it are a non-exclusive license to use the code in your programs if you choose to, assuming you don't use it to write a Life program, and a lot of useful information on how to write well behaved tools that cooperate with the system. The code is written to be easy to understand and easily modified. Using it as a framework for your next project can save you hours. It will save you even more time when it comes to modifying your program because it adapts easily and automatically to many aspects of the system environment. Ordering information is in the appendix. Something to look for are the various things that this program can do and ask yourself, "How does he do that?", or "I've been meaning to write code that did that." Anyway, as they say on the Ragu commercials "It's in there!" 1.2 Life and Cellular Automata What is "Life" you ask? Well originally it was a mathematical amusement that John Conway figured out to demonstrate a Cellular Automaton. A Cellular Automaton is a bunch of cells that relate to each other through a fixed set of rules. The system as a whole can be made to accomplish some task by setting the rules and the patterns appropriately. And while I can't go into any great detail in this file, double click on the menu button while running the program and flip to page 3 of the About ... requester for some reference works, The terminology used in this document and throughout the program is all 'life' oriented. Each blob on the screen is a Cell, a group of cells are a growth, and all the cells on the screen constitute a colony. In general the area on the screen is referred to as the "world" and separate off screen area where growths are held temporarily is called "limbo." 2.0 STARTUP AND OPTIONS There are two ways you can start Life, via the CLI and via the workbench. When you start up Life there are several options you may wish to pass it. How you pass it options depends on how you start it up. But before you start it you need to know just what the heck you can specify as options. There are five options that can be specified, these are resolution, world type, screen font, rules type, and loop limits. If you start Life from the workbench you can set the various options by modifying the TOOLTYPES field of the Life icon. Select the icon on the workbench and then select the "Info" option from the workbench menu. There will be a line called ToolTypes with an up and down arrow. If there are no ToolTypes set, nothing will happen when you click on these arrows, if there are some ToolTypes then they will scroll by when you click on these arrows. To add one click on the "ADD" box next to the tool type. The line will be cleared. Now click on the line and your cursor will be placed into it. Now type in your option, for example you could type in "RESOLUTION=HIGH", without the quotes, which would indicate your preference that Life come up in a high resolution screen. The tool type options are as follows, (brackets indicate you should pick one choice or the other) ... RESOLUTION=[HIGH,MEDIUM,LOW] FONT=fontname/size WORLD=[TORUS,PATCH] RULES=[SINGLE,DOUBLE] LOOPLIMIT=num On the other hand, if you start Life from the CLI you will can specify these options with command line switches. The syntax from the command line is : 1> Life -h -L 6 Where in this case you would be selecting high resolution and a loop limit of 6 generations. The command line switches are as follows : -h for High resolution -m for Medium resolution -l for Low resolution -L nnn to set the Loop limit to 'nnn' -t for a Torus world -p for a Patch world -f name size to use font 'name' and size 'size' -d to use dual species rules -s to use single species rules In both cases it is possible to select a colony file to load initially. From the workbench, click on the icon of the colony file, hold down the shift key and double click on the Life icon. From the command line, simply specify the colony file as the last parameter on the line. 3.0 OPERATING THE PROGRAM After you have started up the program and are looking at a blank grey screen you may be wondering what to do next. Well the answer is start creating cells. Cells are placed in a square grid on the screen that is 8 pixels on a side. To place a cell, position the pointer over the place you want it to appear and press the left button. A blue cell will appear. This is referred to as a "Type A" cell. Positioning the pointer over a Type A cell and pressing the left mouse button will change it into a "Type B" cell. Note that the type of the cell is only important if you are using Type II rules, see the section on the Misc menu below for how to set the rules and what it means. Finally, if you position the mouse over a Type B cell and press the left button it will be removed. In this way you can add and remove cells anywhere in the world. After you have some cells you can move the next generation by pressing the return key, or by selecting Iterate from the control menu. If you want the program to run continuous generations you can press the STOP gadget in the title bar (which will turn in to a Run gadget), or select "Begin" from the control menu. 4.0 THE MENUS OF LIFE This program has several menu selectable options that are organized into four main groups. These groups appear at the top of your screen when you press the Menu button. They are labeled, "Project", "Edit", "Misc", and "Control". I will cover each group in this section. 4.1 The Project Menu The project menu controls the loading and saving of growth and colony patterns. It also contains other commands that are related to the environment of this tool. The first group of options are "New", "Open Colony", "Save Colony", and "Save As Colony." The New command will clear out the current life array and intialize internal population counters to 0. "Open Colony" will bring up a file requester asking you to select a colony file to load. You can move around in the Amiga file system with only the mouse if you choose or you can go directly to the directory of interest with the string gadgets. You may enter a file name in the 'File :' box or double click on the name in the display below. After you are satisfied, click on the Accept button to leave the requester or the Cancel! button to abort the operation. "Save Colony" is the opposite of "Open Colony". It will save the current array into the current Colony name, if no name has been selected or you choose the "Save As" option, the file requester will be brought up again and a new name can be chosen. The next group are the growth group. These two options, "Open Growth" and "Save Growth" will load or save selected portions of the world. When you choose "Open Growth", the file requester will appear and you will be asked to select a growth file to load. After it has been loaded, you will have to select one of the "Paste" options in the Edit menu to actually place it into the world. Similarly, before you can save a growth you must have clipped it using one of the "Cut" options in the "Edit" menu. The "Edit" menu is described in the next section. The final group of choices, "Save Defaults", "About ...", and "Quit" affect the environment. When you choose "Save Defaults" the settings of all the variable Life parameters are saved to the file Life.Def in the directory where life resides. When you restart life it will automatically read these settings and pre-initialize the system appropriately. The second option "About ..." brings up a requester that describes the program a bit and lets you play with some mutually excluded gadgets. Note that you can also bring up this requester by clicking the menu button twice quickly. The final option "Quit" is pretty self explanatory. 4.1 The Edit Menu The Edit menu is where all the manipulations of growths happens. It has several familiar functions, and some not so familiar. The first group put cells from the world into growth limbo. When you use "Cut" the cells you select will be removed from the world, when you use "Copy" a copy of that section will be created in limbo. The next two options put the growth in limbo back into the world. The "Paste" option is opaque, in that the resulting patch is put into the world looking like it came out. Cells that were living there that aren't in the growth get removed. The "Insert" option uses an OR function to place the growth down into the world. Cells that are already in the world remain if they are not overlayed by cells from the growth in limbo. All four of these options cause the cursor to change to a giant 'G' when they are active. The next option is "Undo" and restores the world to the state it was in on the previous generation. Note that it is only a single level undo function and repeated calls will have no effect. The final option on this menu is "Transform" and it has three suboptions. These options operate on the growth that is currently in limbo. The three operations are "Mirror X", "Mirror Y", and "Rotate 90". The mirror options simply flip the growth along a centerline in the indicated direction. In this program "Mirror X" flips the growth along the vertical axis, and "Mirror Y" flips it along the horizontal axis. The last suboption "Rotate 90" will rotate the growth 90 degrees clockwise, effectively swapping the X and Y axis. Note that in all cases the growth remains 'square'. 4.2 The Misc Menu Clearly this the menu that got all the options that I couldn't think of a better place to put them. It could also be called preferences because all but one of the control parameters are set here. The first option is "Adjust Colors". This option will bring up a color palette that will let you adjust the colors on the screen. Note that what it actually does is fork the Palette program that is in the life directory and that changes the colors. Ah the joys of multitasking. Anyway, the color palette is saved as part of the preferences so if you prefer green cells to blue ones this is the place to set that up. The second option is "Rules Type." As life programs go this one is fairly unique in that can handle two separate species, and the user is allowed to experiment with different sets of rules. As far as I know this is the only one that offers these two features, I know it is the only one that use matrices to let you set them up. This option actually has three suboptions, "Type I" and "Type II" rules, and "Set the Rules". Note that the type of rules are mutually exclusive, selecting one disables the other and vice versa. Also, if you are displaying a low resolution screen you will not be able to adjust the type II rules because the requester won't fit. Type I rules are the traditional rules of life that operate with only one species. The default setup sets new cells to be blue, and 'old' cells that survive a generation to be red. The default type II rules sets up 'Conway' rules for both the red and blue species but does not allow the two to intermingle, which brings us to the third suboption "Set the Rules". This allows you to determine who will die and who will live on to the next generation. The format looks strange at first but will become clear after thinking about it for a minute or two. Essentially when each iteration of a loop occurs a cell at a given co-ordinate can either be occupied or empty, and it has some number of neighbor cells that are occupied or empty. In the type I case the calculation is very simple, the default rules show that if a cell is unoccupied and has exactly three neighbors, a new cell is born. If the cell is occupied and has two or three neighbors the cell lives on to the next generation (getting sunburn in the process). If an occupied cell has only one or no neighbors it dies of lonelyness, and if it has more than three neighbors it commits hari keri because it doesn't have enough space. Of course you can change this. You can make crowded cells turn blue again by adding blue cells in these crowded spots, you can create spontaneous generation by adding a blue cell to the unoccupied with zero neighbors spot. (Pretty boring though to see the screen whoosh full of cells.) Type II rules use exactly the same principles except expanded to differentiate between Type A and Type B neighbors. Now each cell can either be empty, have a Type A cell, or a Type B cell in it. The possibilities are staggering (actually there are 3^81 possible sets of rules for Type II life, I've looked at 5). The next option is more mundane, it is the 'type' of world. You see the original paper by Conway used an "infinite" plane of cells. Well we don't have "infinite" memory so we make do with what we have. The two suboptions are "Patch" and "Torus" and describe how a cell at the edge of the screen is treated. In "Patch" mode the edge of the screen is dead, that is it doesn't change. By default there are no cells there but you can put cells there if you so choose. They will be exempt from the rules and continue to exist from generation to generation. The other option is "Torus", which is the shape you would get if you took a square piece of paper and made all of the opposite edges touch. Basically, if a glider goes off one side of the screen it will reappear in the other side in short order. This is because the torus world wraps around at all the edges. What goes off the top comes in off the bottom and what goes off to the side comes in on the other side. If you want to warp your brain consider that all four corners of the screen are neighbors of each other, strange but true. Option four is "debugging" and in general you won't care to use this option. When the "Debugging On" suboption is selected lots of debugging messages a spewed about like political rhetoric. If you do buy the source however they are invaluable in figuring out what is going on where sometimes. To enable these items you need the source. Option five is the Status Window. Selecting this option will bring up a separate window that contains statistics on the birth and death rate of the two species and has a generation meter to tell you how fast the generations are being calculated and displayed. It also has a run/stop button to let you control the simulation from there. (I know it is redundant but it serves to demonstrate a technique in the source.). Option six lets you turn the workbench screen on and off. Since Life runs in a custom screen, you can choose to free up some memory by turning off the workbench. Note that this only works if you have started Life from the workbench. If you start it from a CLI it can't close down the workbench screen. Option seven lets you change the resolution of the Screen. This function has some interesting interactions with the menus and such. When life is started it builds the menus and requesters it needs. If you then change the screen resolution to a lower resolution some things may break. I've tried to keep these to a minimum. The suboption list shows the resolutions available. These options are nominally 320 X 200, 640 X 400 etc, however if you are running morerows this menu will reflect the actual size of the screen it will open. The last option is "Show Pointer", selecting this option will cause the mouse pointer to disappear. Sometimes this is preferable to pulling it down to the lower right hand corner of the screen. Note that it has a shortcut key (Amiga-M), remember this because if the mouse is invisible it can make selecting menu items problematic at best. 4.3 The Control Menu The Control Menu is probably the simplest menu to explain. It will control the operation of the simulation while the program is waiting for input. This menu has four options, "Begin", "End", "Iterate", and "Autostop". The first two will start and stop continuous generations. At the end of each generation the input queue is check for messages and if found they are responded to. The third option, "Iterate" simply moves the simulation forward one generation. As described in the operation section you can also start a generation by pressing the key on your keyboard. The final option "Autostop" controls the detection of loops. Life will stop iterating as soon as the population of both species goes to 0, but there are often cases where the current colony is stable and not 0. In these cases it is preferable to stop iterating after a set number of generations where the population stays the same. Note that this shouldn't be '1' because that would preclude gliders and other moving objects from possibly colliding and continuing the excitement. The default is 8 generations, you can of course set it to whatever you chose with the tooltype or command line switch. APPENDIX A - The License Agreement The Compleat Intuition Example, Source License. The following agreement is entered into between McManis and McManis Software, the licensor, and _______________________________________, the licensee, on _______________________, 19__. This agreement supercedes all previous agreements between licensee and licensor. This agreement is not transferable. This agreement is non-exclusive. In consideration of the $75 the licensee has paid to the licensor, the liscensor conveys the following rights and privledges upon the licensee : Use of all or part of the source code in the Compleat Intuition example, in the development or production of the licensees product without any further royalty or consideration. The licensee agrees to abide by the following conditions : The source code will be kept in confidence and not disclosed to any other person or company who does not also have in their possession a source license with the liscensor. Allow the source code to come into the possession of unlicensed parties through either deliberate or inadvertent action. _________________________________ _________________________________ Chuck McManis, (Date) Liscensee (Date) McManis and McManis Software _________________________________ Licencee (Printed) APPENDIX B - Ordering the Source Code To order the source code you will need to print out the license agreement in appendix A twice, sign both copies and send them with a check or money order for $75 plus $5 postage and handling to : McManis & McManis Software, 1141 Vasquez Ave Sunnyvale CA, 94086 (408) 749-8815 Your $75 will get you a 3-ring binder containing : o A laser printed copy of the source listing. o An index indicating where each Intuition call is used. o A description of the operation of the source. o A year of updates to the source. o A disk with the code on it as well. o And a license to use the source in your own programs. The code uses nearly every call that is supported under Intuition in version 1.2 or version 1.3 of the OS. It also details many techniques that are either not documented or documented poorly. It identifies several bugs in the current version of Intuition and shows you how to work around them. And it has been written with ease of use in mind, specifically, routines are coded such that they can be extracted and placed into your code quickly. Gadget building routines, a file requester, the EZMenus(*) package, and a variety of other useful tidbits. I have spent a couple of hundred hours putting this stuff together. I believe that you can save ten to twenty hours by using the framework in your program. So if you are serious about writing tools for the Amiga this can be a real time saver. I have also tried to use every type of object Intuition deals with in terms of requesters, gadgets, windows, and menus. --Chuck McManis Electronic addresses : BIX - cmcmanis Usenet - {any backbone}!sun!cmcmanis Arpanet - cmcmanis@sun,com APPENDIX C - Warranty McManis and McManis Software makes no warranty or representation, either express or implied with respects to this software, its quality, performance, merchantibility, or fitness or a particular purpose. As a result, this software is sold on an "as is" basis. The entire risk as to its quality and performance is with you, the user and not McManis and McManis software. In no event shall McManis and McManis Software be liable for direct, indirect, special, incidental, or consequential damages resulting from any defect in the software or its documentation, even if advised of the possibility of such damages.