Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/145.lha/life.readme

Text File | 1986-11-21 | 22KB | 430 lines

        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 <Return> 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
        [phone]

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.