@database AntiMatter.guide
@$VER: AntiMatter.guide $Revision: 1.17 $ $Date: 95/01/25 22:29:14 $
@(C) Copyright © 1995 Adam Levin-Delson.  All Rights Reserved
@author Adam Levin-Delson

@wordwrap
@node Main "AntiMatter User Manual"

    @{b}AntiMatter@{ub}


Copyright © 1988-1995 Adam Levin-Delson  All Rights Reserved

Permission is hereby granted to distribute the @{b}AntiMatter@{ub} executable and documentation via electronic means and in @{b}Amiga@{ub} software collections for which no charge or only a small amount of money more than production costs is charged.


@{b}AntiMatter@{ub} is a single-player strategy game in which the computer hides a number of @{i}atoms@{ui} in a @{i}chamber@{ui}.  You must determine the locations of the atoms by firing plasma @{i}rays@{ui} into the chamber and observing where the rays (which are influenced by the atoms) emerge.


    @{" Features         " link "Features"} - Features of this implementation.

    @{" Instructions     " link "Instructions"} - How to play @{b}AntiMatter@{ub}.

    @{" Bug reports      " link "Bug reports"} - How to report bugs to the author.

    @{" Source code      " link "Source code"} - How to obtain the Source code.

    @{" Acknowledgements " link "Acknowledgements"} - Acknowledgements and credits.

    @{" Release history  " link "Release history"} - Describes the various versions of @{b}AntiMatter@{ub}.


Documentation is available during gameplay at the press of the @{i}Help@{ui} key.  To enable this feature, assign "AM:" to the directory where AntiMatter.doc can be found.

@endnode


@node "Features"

    @{b}AntiMatter@{ub} Features


@{b}Stereo sound@{ub}
- Four-channel stereo sound follows the action!
- Conforms to the Amiga's "channel-locking" convention, allowing channels to be stolen by higher @{" priority " link "Startup Priority"} requests, and later returned to the original owner.

@{b}Animated Pointer@{ub}
- 30fps animated pointer using a proprietary vertical-blank interrupt handler.
- Multiple instantiations of @{b}AntiMatter@{ub} share the animating routine.

@{b}Configurable@{ub}
- The player can choose how large a chamber to use (6x6 through 14x14) as well as how many atoms will be hidden (3 through 8). (See @{" Preferences " link "Prefs menu"}.)

@{b}OS-sensitive@{ub}
- Runs under AmigaOS 1.3, 2.x and 3.x and on all 680x0 processors.

@{b}Low memory usage@{ub}
- Opens a low-res screen and uses a "shading" pattern to extend the color palette.
- Chip RAM audio samples are shared for the various sound effects.

@{b}Well tested@{ub}
- Developed using Enforcer and Mungwall.

@endnode


@node "Instructions"

    @{b}AntiMatter@{ub} Instructions


A new game is set up when @{b}Antimatter@{ub} is first invoked.  Changing the configuration of the board (see @{" Preferences " link "Prefs menu"}) will also set up a new game, as will selecting "New game" from the "Project" menu.


    @{" Starting Antimatter " link "Starting Antimatter"}

    @{" Firing rays         " link "Firing rays"}

    @{" Ray travel          " link "Ray travel"}

    @{" Marking choices     " link "Marking choices"}

    @{" Scoring             " link "Scoring"}

    @{" Menus               " link "Menus"}

    @{" Online Help         " link "Help"}

    @{" Tips                " link "Tips"}

@endnode


@node "Starting Antimatter"

    Instructions - Starting Antimatter


@{b}Antimatter@{ub} can be started from either the Workbench (by double-clicking on the @{b}Antimatter@{ub} icon) or from the shell.  Game preferences can be specified from either interface.

    @{" Workbench startup " link "Startup WB"}

    @{" Shell startup     " link "Startup Shell"}


@endnode


@node "Startup WB"

    Starting @{b}AntiMatter@{ub} - Workbench


The number of atoms and size of the chamber can be set in @{b}AntiMatter@{ub}'s icon (using "Information" from the Workbench) with "ATOMS=" and "SIZE=" tooltypes.  An additional ToolType parameter, "SOUNDPRI=" can be used to set the @{" priority " link "Startup Priority" } of @{b}AntiMatter@{ub}'s sound effects.  If SOUNDPRI is set to the special value "999", @{b}AntiMatter@{ub} will not generate any sounds.

Valid numbers of atoms range from 3 to 8; chamber size from 6 (6x6) to 14 (14x14).

The default values for the tooltypes are as follows:

    ATOMS=4

    SIZE=8

    SOUNDPRI=127

@endnode


@node "Startup Shell"

    Starting @{b}AntiMatter@{ub} - Shell


The number of atoms and size of the chamber can be specified when starting @{b}AntiMatter@{ub} from the Command Line (Shell).  An additional argument can be used to set the @{" priority " link "Startup Priority" } of @{b}AntiMatter@{ub}'s sound effects.  If SOUNDPRI is set to the special value "999", @{b}AntiMatter@{ub} will not generate any sounds.

Valid numbers of atoms range from 3 to 8; chamber size from 6 (6x6) to 14 (14x14).

The syntax of the command depends upon the version of the operating system installed on your Amiga.


Newer versions of AmigaDOS (specifically, version 2.04 and later) use the "ReadArgs" syntax:

    Antimatter ATOMS=4 SIZE=8 SOUNDPRI=127

Older versions use a Unix-style syntax:

    AntiMatter -a4 -s8 -p127


Both formats shown above illustrate the default @{b}AntiMatter@{ub} values.

@endnode


@node "Startup Priority"
    Starting @{b}AntiMatter@{ub} - Sound Priority


  @{b}AntiMatter@{ub} allocates all four Amiga audio channels to create action-specific stereo sound.  A priority level of 127 will prevent any other application from stealing @{b}AntiMatter@{ub}'s audio channels.  Anything less than 127 (down to -128) will allow applications with a higher audio priority to steal the channels.  @{b}AntiMatter@{ub} will attempt to reallocate stolen channels as soon as they are freed.

@endnode


@node "Firing Rays"

    Instructions - Firing Rays


Fire a ray by positioning the laser (cursor) at one of the chamber entrances (the squares along the chamber edges) and clicking the left mouse button.

The entrance (and exit, if the ray ultimately exited the chamber) will then be indicated with a colored marker (described in @{" Ray travel " link "Ray travel"}) determined by how the chamber's atoms influenced the ray.


@endnode


@node "Ray travel"

    Instructions - Ray travel


A ray will normally travel in a straight line (an @{" Unimpeded flight " link "Unimpeded flight"}, the ray passes straight through the chamber) unless acted upon by one or more atoms.

There are two primary ways in which a ray can be effected by atoms:

@{" Absorption " link "Absorption"} - The ray is absorbed by an atom in the chamber.

@{" Deflection " link "Deflection"} - The ray is caused to veer 90° from a straight line.
                There are two special cases of Deflections known as @{" Reflections " link "Reflection" }.


Note that the influence of multiple atoms in the chamber can combine to yield complex results.

@endnode

@node "Unimpeded flight"

    Ray travel - Unimpeded flight


If there are no atoms directly in the ray's path, nor along the left or right of the path, the ray will pass straight through the chamber, exiting on the opposite side.

The entrance and exit locations will be indicated with like-color markers.

@endnode


@node "Absorption"

    Ray travel - Absorption


If a ray is fired directly into an atom, it is absorbed, and does not exit the chamber.

The square where the ray entered the chamber will be indicated with a black marker.

@endnode


@node "Deflection"

    Ray travel - Deflection


If a ray would pass immediately alongside an atom the ray will be deflected away from the atom at a right angle to its original path.

If the ray would have passed the atom on the atom's right side, the ray is deflected to the right.

If the ray would have passed on the atom's left side, it is deflected to the left.


Note that the deflection occurs one square *before* the ray and the atom would be next to each other.  The entrance and exit locations will be indicated with like-color markers.


There are two important conditions that result in a special type of deflection known as a @{" Reflection " link "Reflection"}.

@endnode


@node "Reflection"

    Ray travel - Reflection


If the deflecting atom is alongside the square at which the ray would enter the chamber, the ray is unable to be deflected, and is instead reflected directly back out.

This reflection is indicated with a white marker at the attempted entrance point.


A reflection also occurs if there are two atoms straddling the ray's path (ie they are exactly one square apart and the ray is traveling down the path between them).  The ray is deflected both right and left at the same time, but cannot overcome either atom, and is instead reflected back along the path from which it came.

The ray emerges from the same location it entered, and the reflection is indicated with a white marker.

@endnode


@node "Marking choices"

    Instructions - Marking choices


As you fire rays into the chamber, and observe the results, you will start to form an idea of where the hidden atoms are.

You can mark your suspected locations by positioning the cursor over the desired location in the center grid of the chamber and clicking the left mouse button, creating a white marker.

Clicking on the same location again will remove the marker.  While you may place as many markers in the center grid of the chamber as you like, you will not be able to @{" score " link "Scoring"} your guesses if you have more markers than there are atoms hidden in the chamber.

@endnode


@node "Scoring"

    Instructions - Scoring


During game play, you may place as many @{" markers " link "Marking choices"} in the center grid of the chamber as you like.  In order to calculate your score, however, you may have no more markers than there are atoms hidden in the chamber.

Once you believe that you have correctly guessed the location of all the atoms in the chamber, (as indicated by your white markers in the center grid), choose the menu item "Guess/How did I do?".

If the "How did I do?" menu choice is ghosted (disabled), you have too many markers on the center grid of the chamber.  Simply click on the unneeded markers until you have as many (or fewer) markers as there are atoms hidden in the chamber.

To calculate your score, the actual locations of the atoms will be displayed.  Atoms which you correctly guessed will be marked with a checkerboard marker, atoms which you missed will be solid red, and atoms which you thought existed but didn't are left in white.

Your score is @{" calculated " link "Score calculation" } from the number of rays fired, and the number of atoms correctly guessed.  The lower your score the better.

@endnode


@node "Score calculation"

    Instructions - Score calculation


The formula used for calculating the score is:


    ( 5 * ( A - C ) ) + R


    where


    A is the number of atoms embedded in the chamber.

    C is the number of atoms correctly identified
      with markers in the center of the chamber.

    R is the number of ray markers along the edges
      of the chamber.

@endnode


@node "Menus"

    Instructions - Menus


    @{b}AntiMatter@{ub} has three main menus:


    @{" Project menu " link "Project menu"}

    @{" Prefs menu   " link "Prefs menu"}

    @{" Guess menu   " link "Guess menu"}

@endnode


@node "Project menu"

    Menus - Project Menu


The "Project/New Game" menu item (Keyboard shortcut "Right-Amiga N") will begin a new game with the selected game parameters of chamber size and number of atoms.

The "Project/About..." menu item ("Right-Amiga A") gives credit for the @{" original board game " link "Acknowledgements"} upon which @{b}AntiMatter@{ub} is based.

The "Project/Quit" menu item ("Right-Amiga Q") will exit the game.

@endnode


@node "Prefs menu"

    Menus - Prefs Menu


There are several menu selections that will help you tailor @{b}AntiMatter@{ub} to your desired level of difficulty.  The "Prefs/Atoms" and "Prefs/Size of Chamber" menu items will allow you to set the number of atoms and the size of the chamber.  The currently selected values are displayed in a "ghosted" or dimmed manner.  As soon as you change one of these parameters, a new game will be created using the new value(s).  You can choose from both the "Atoms" and "Size of Box" menus without releasing the "menu" (right) mouse button in between.  This is known as extended-selecting the items.

These preferences can also be specified when @{b}AntiMatter@{ub} is invoked from either the @{" Workbench " link "Startup WB"} or @{" Shell " link "Startup Shell"}.

@endnode


@node "Guess menu"

    Menus - Guess Menu


The "Guess/Clear Markers" and "Guess/Set Markers" menu items (Keyboard shortcuts "Right-Amiga C" and "Right-Amiga S", respectively) will allow you to clear or set all the center grid markers at once.

The "Guess/How did I do?" menu item ("Right-Amiga T") will tally up your score.  You will be unable to select this item if there are too many "guess" markers on the center grid.

@endnode


@node "Tips"

    Instructions - Tips


    @{" Preferences     " link "Tips preferences"}

    @{" Beginner games  " link "Tips beginner games"}

    @{" Deflections     " link "Tips deflections"}

    @{" Impossibilities " link "Tips impossibilities"}

@endnode

@node "Tips preferences"

    Tips - Preferences


The default size of 8x8 and 4 atoms is a good starting point, but feel free to make the chamber smaller or the atoms fewer when learning how the rays are effected by the atoms.

@endnode


@node "Tips beginner games"

    Tips - Beginner Games


To help in understanding how rays are effected by the atoms, you may choose to fire rays into @{i}all@{ui} possible entrances, then select the "Guess/How did I Do" menu to see the locations of the atoms, and then study the path of all the rays.

@endnode


@node "Tips deflections"

    Tips - Deflections


Keep in mind that @{" Deflections " link "Deflection"} occur one square @{i}before@{ui} the ray would be alongside an atom.

@endnode


@node "Tips impossibilities"

    Tips - Impossibilities


There are configurations of atoms ("@{i}molecules@{ui}") which cannot be completely determined even if rays are fired into all chamber entrances.

The likelihood of such molecules increases with the number of atoms embedded in the chamber.

@endnode


@node "Help"

    Instructions - Online Help


Pressing the "Help" key during game play will interrupt the action and call up "AmigaGuide" to display this documentation.

AmigaGuide will be instructed to look in the same directory that @{b}AntiMatter@{ub} is located in for "AntiMatter.guide".

Should either AmigaGuide or the guide file not be found, @{b}AntiMatter@{ub} will attempt to call up "More" (actually Sys:Utilities/More) on "AM:AntiMatter.doc".

@endnode


@node "Bug reports"

    Bug reports

Bug Reports are encouraged, and may be sent electronically or by mail to the @{" author " link "Contacting the author" }.

The first person to report each reproducible bug will receive a corrected copy as soon as it is available.

@endnode


@node "Source code"

    Source code

SAS 'C' (v6.51) source code for @{b}AntiMatter@{ub} is available from the @{" author " link "Contacting the author" } for US$10 (this includes postage in the United States; peoples of all other countries [unite!] must include appropriate postage to pay for the shipment of one diskette from the US to your country).

680x0 assembler source code for @{b}AnimPtr@{ub}, the sharable vertical-interrupt handler for pointer animation is available for US$5.

Note that the source code for @{b}AntiMatter@{ub} and @{b}AnimPtr@{ub} are @{b}@{i}not@{ui}@{ub} redistributable.  They may, however, be used as the basis for other programs, which may be distributed as you see fit, so long as an acknowledgement of my original source is clearly given.

@endnode


@node "Contacting the author"

    @{b}AntiMatter@{ub} - Contacting the author


Contact me to report bugs found in @{b}AntiMatter@{ub}, or to obtain a copy of the source code.

My mail address is:

    Adam Levin-Delson
    22325 53rd Ave SE
    Bothell, WA  98021  USA

My E-Mail address is:  aklevin@bix.com

@endnode


@node "Acknowledgements"

    @{b}AntiMatter@{ub} - Acknowledgements


@{b}AntiMatter@{ub} is based upon the board game "@{b}Black Box@{ub}", by Eric Solomon.  It was originally produced by Waddingtons House of Games in the United Kingdom, and then by Parker Brothers in the United States of America.

@{b}AntiMatter@{ub} is Copyright © 1988-1995 Adam Levin-Delson  All Rights Reserved


Many thanks to the following people:

Bernie Cosell and Bruce Barnett, for their kind help in providing information and materials pertaining to the two board-game versions of "Black Box".

Michael Sinz, Peter Cherna, Spencer Shanson and Carolyn Scheppner, all of (at the time) Commodore Business Machines.

Peter Kunath for audio channel-sharing example code.

Boyd & Gian Edmondson for beta-testing.

Toby Douglass for bug-reporting.

@endnode


@node "Release history"

    @{b}AntiMatter@{ub} - Release history


@{b}AntiMatter@{ub}'s version number can be found in the information provided by the "About..." menu selection as well as from the AmigaDOS "Version" command.

    Version     Date            Comments
    1.0                1988     Working (audioless) version.  Not distributed.
    1.XX        1993 - 1994     Took advantage of AmigaOS 2.x/3.x features.
                                Added animated pointer.
                                Added sound routines.
    2.0         06 Jan 1995     First full release.
    2.1         25 Jan 1995     Fixed bug preventing Euro36 screens from opening.  (Toby Douglass found this.)

@endnode