        ͻ
                      ROBOT BATTLE REFERENCE MANUAL                 
                                                                    
                     Thank you playing robot battle!                
                                                                        
             COPYRIGHT (C) 1994 BRAD SCHICK ALL RIGHTS RESERVED     
        ͼ


This reference manual is provided so robot battle information may be printed
as a whole. All of this information, and more, is included in on-line help.
The on-line help is much more convenient for quick references. It provides
searchable keywords, cross references, and is printable topic by topic.


Table of Contents
-----------------
        Chapter 1.0             About Robot Battle
        Chapter 2.0             The Contest
        Chapter 3.0             How To Contact Me
        Chapter 4.0             Creating a Robot
        Chapter 5.0             Description of Robot Events
        Chapter 6.0             Sample Robot
        Chapter 7.0             Scripting Language Functions
        Chapter 8.0             Special Sections
        Chapter 9.0             Math Operators
        Chapter 10.0            Logical Operators 
        Chapter 11.0            Robot Variables
        Chapter 12.0            User Defined Variables
        Chapter 13.0            Damage Summary 
        Chapter 14.0            Points Calculation 
        Chapter 15.0            Tips and Techniques 




                                Chapter 1.0

                            About Robot Battle


Can you design a robot to best all challengers? To survive, your robot
must have better tactics, intelligence, and adaptability than all others.
Can you out think and out gun your opponents? This is the place to find out!
Build a robot and match your wits against up to five other robots in head
to head battles to the death. Watch your ANIMATED robots come to life with
stunning sound effects in matches of 1 to 65,500 games.

Robot creation starts by dreaming. How can your robot stay alive in an
open arena with five other deadly robots hunting it down? How can you
find and destroy the enemy before they find you? Of course the only way
to answer these questions is trial by fire. Build a few robots and watch
them get crushed by the simple sample robots provided with this game.
Eventually, you will be able to match wits with other skilled robot
designers.



                                Chapter 2.0

                                The Contest


This is your chance to determine how good your robots actually are. Send in
your robots to compete in a tournament against robots written by others from
all over the world. Your robot will fight in hundred of games, steadily 
facing tougher and tougher competition.  

The contest will be a round robin tournament. At each level, your robot will
fight in many thirty game matches against various competitors. At the end of
each level, total points will be tallied. Only the top one third high
scoring robots will proceed to the next level of competition. 

Six robots will make it to the final level. These six robots will fight in
one sixty game match to decide the overall champion. All six finalist will
receive a substantial cash prize. Prize amounts will be a given percentage
of total the entrance fees collected. Actual amounts will change as the
number of entrants change.

        Place           Percentage      Sample Prize (assuming 200 entrants)
        -----           ----------      ------------------------------------
        Winner          35%                     $700
        2nd Place       6%                      $120
        3rd Place       6%                      $120
        4th Place       6%                      $120
        5th Place       6%                      $120
        6th Place       6%                      $120

All contestants will receive final results. These results will contain
overall contest information such as the number of contestants, the number
of levels in the tournament, finalists names, champions name, and prize
details. Contestant will also receive individual results. These will
include the highest level your robot reached, the number of wins and loses
during each level, score at each level, and final tournament standing.

The currently scheduled contest dates are listed below. If there is enough
demand, additional contest dates will be scheduled.

        -March 1st, 1995
        -November 1st, 1995

Send in as many robots as you like. Each robot has a 10$ registration fee.
Remember, you do not have to Register the game itself to enter the contest.
Anyone may enter! All robots must be properly prepared before entry. To
prepare a robot for contest entry, run the 'contest.exe' program included
with the game.

Once your have prepared your robots for entry, you must send them in. See 
Chapter 3.0 for more information about getting your robots to me. Also, let 
me know if you would like contests with other formats in the future. For 
example, I could also organize one-on-one tournaments.




                                Chapter 3.0

                             How to Contact Me


The following is a list of way to contact me if you need to do any of the
following:
        - Enter robots in The Contest
        - Give suggestions for Version 2
        - Report problems
        - Get technical support
        - Ask other questions.

Additional Contest Information:
        To enter The Contest using CompuServe, America Online, or the
        Internet, send an email containing your prepared robots. To enter
        using the Robot Battle BBS, simple upload your prepared robots.
        Before sending in your robots, they must be prepared using the
        'contest.exe' program included with this game. If you are paying
        the entrance fee using VISA or MasterCard, prepared robots are all
        you need to send. If you are paying the entrance fee with a check
        or money order, you must send the payment separately via Standard
        Mail.


Standard Mail
        Brad Schick
        PO Box 14056
        Chicago, IL 60614-0056

Robot Battle BBS (BBS Info)
        Robot Battle BBS:               (312) 975-9392
        Max. BPS                        14.4K
        Data                            8
        Parity                          None
        Stop Bits                       1
        Terminal Type                   ANSI

CompuServe
        75573,1112

America Online
        robotbtl

The Internet
        robotblt@aol.com
        75573.1112@compuserve.com




                                Chapter 4.0

                              Creating a Robot


Robots are created using a simple scripting language. All you need is
an ASCII text editor and an imagination. Although helpful, no previous
programming knowledge is required. In fact, Robot Battle is a great way
to start learning how to program. Most modern computer systems are based
on event driven techniques very similar to those you will learn playing
Robot Battle.  

To create your own robot, start by looking at the Sample Robot below. Do
not worry about the specific commands, they are described in Scripting 
Lanuguage chapter. Just get the feel for the layout of a robot's
instructions.

Once you have looked over the Sample Robot, move on to the Scripting 
Lanuguage chapter. It provides detailed explanations of all robot 
operations. Again, do not get too hung up on the specifics. The best way
to learn is by examining prefabricated robots and actually playing the
game. Robot Battle comes with many thoroughly commented sample robots. Use
a text editor to view their instructions, then start the game and watch
them slug it out in the arena!



                                Chapter 5.0

                         Description of Robot Events


The most important concept to robot design is event driven behavior. Event
driven means that robots behave by responding to things (events) that
happen to them. Designing an event driven robot involves deciding what
events a robot should respond to and how it will respond. Responding to an
event is commonly referred to as handling an event.

A robot is divided into a number of sections. Each section has a name and
instructions associated with that name. Sections are grouped by curly
brackets {}. See the sample robot below, to see actual sections. Sections
are used to handle events. Events are associated with sections by various
registration functions described below.

The sections used to handle events define how a robot will behave. Events
may be re-registered to new handler sections at any time. This allows for
extremely flexible robots. At any time during a game, a robot may
re-register its event handlers, completely changing its behavior. Once
registered, events may also be individually turned on or off.

Events also have a priority associated with them. Since a robot can only
do one thing a time, it handles higher priority events first. When an event
occurs, and no higher priority events are occurring, the section registered
to handle that event is called.

When a handler section is called, it always executes to either the last line
of code in that section or until a Return statement is hit. This does not
mean execution will always go directly from the first to the last line of a
handler section, however. Handlers may always be preempted by higher
priority events. If an event with a higher priority than the current event
happens, its event handler will be called immediately. The lower priority
handler will not continue execution until the higher priority event handler
completes.

The sample robot called event.prg should be very helpful. Look at its
instructions, then run it in a game. Look at its output in the Robot
Information Dialog to verify that all events have occurred as expected.



                                Chapter 6.0

                                Sample Robot


Notice that capitalization is not important. A variable named "VARIABLE"
will be that same as "variable" or "Variable". This is also true for robot
functions and section names.


Init                                    # Init section 
{
        Name( "Sample" )                # Sets robots name

        RegCore( Core )                 # Registers core event handler
        RegCldMissile( MissileHit,1 )   # Registers missile hit handler
        RegDtcRobot( FoundRobot, 2 )    # Registers robot detection handler

        fire_engy = 1                   # User defined variable: fire_engy
        LockGun( ON )                   # Locks gun and radar together
}

Core                                    # Core section
{
        Scan( )                         # Looks for other objects
        RadarRight( 5 )                 # Turns radar (and gun) right
}  

MissileHit                              # MissileHit section
{
        Ahead( 20 )                     # Moves robot ahead
}

FoundRobot                              # FoundRobot section
{
        fire( fire_engy )               # Fires energy missile
        Scan()                          # Looks for other objects
}



                                Chapter 7.0

                        Scripting Language Functions


These functions make up the robot scripting language. They are used to tell 
a robot what it should do.  Parameters are the values that are passed into a 
function.  Different functions take different numbers of parameters. No robot
functions return values.  The functions below are grouped roughly by the 
services they provide. Remember, capitalization is used for clarity only, 
Robot Battle does not recognized capitalization.

** Parameters marked with two stars may be any valid expression. Expressions 
   are composed of variables, numeric values, math operators, and logical 
   operators.


Function Summary
----------------
Ahead                   Moves the robot ahead
AscanEvents             Turns on or off auto scanning events
Back                    Moves the robot back
Blocking                Turns command blocking on or off
BodyLeft                Turns the robot to the left
BodyRight               Turns the robot to the right
CldCookieEvents         Turns on or off cookie collision events
CldMineEvents           Turns on or off mine collision events
CldMissileEvents        Turns on or off missile collision events
CldRobotEvents          Turns on or off robot collision events
Continue                Continues previously aborted movement
CoreEvents              Turns on or off core events
CustomEvents            Turns on or off custom events
DtcCookieEvents         Turns on or off cookie detection events
DtcMineEvents           Turns on or off mine detection events
DtcRobotEvents          Turns on or off robot detection events
Else                    Evaluated when previous the If() or ElseIf() is false
ElseIf                  Evaluated when previous the If() is false
Endif                   Marks the end of a logical the If() block
Fire                    Fires an energy missile
GetHitsOther            Determines the number of times the robot has hit another robot
GetHitsSelf             Determines the number of times the robot has been hit by energy missles
GetHitStr               Determines the average damage done by the robots missiles
GetOthers               Counts the number of other robots left in a game
GetRandom               Generates a random number
GetShots                Determines the number of energy missiles fired by the robot
GetTurns                Determines the number of turns the robot has had
Gosub                   Causes execution to continue in another section
GunLeft                 Turns the robots gun to the left
GunRight                Turns the robots gun to the right
If                      Starts a logical If block
LockAll                 Turns rotation locking on for all robot components
LockGun                 Turns rotation locking on for the robots gun and radar
Name                    Sets the robots name
Print                   Adds a string to the output display window
Print                   Adds a variable to the output display window
RadarLeft               Turns the robots radar to the left
RadarRight              Turns the robots radar to the right
RegAscan                Registers an event handler for auto scanning
RegCldCookie            Registers an event handler for collision with energy cookies
RegCldMine              Registers an event handler for collision with energy mines
RegCldMissile           Registers an event handler for collision with energy missiles
RegCldRobot             Registers an event handler for collision with other robots
RegCore                 Registers an event handler for the robots core behavior
RegCustom               Registers an event handler for custom defined events
RegDtcCookie            Registers an event handler for detection of energy cookies
RegDtcMine              Registers an event handler for detection of energy mines
RegDtcRobot             Registers an event handler for detection of other robots
Return                  Causes current section to end at the current line
Round                   Rounds the specified value
Scan                    Sends out a radar ping to search for other objects
SetAccel                Sent the robots lateral acceleration
Stall                   Causes robot to freeze
Stop                    Causes robot to abort further movement
Store                   Stores values for retrieval in later games
SyncAll                 Aligns the robot's body and gun to its radar
SyncGun                 Aligns the robot's gun to its radar
Truncate                Truncates the specified value
WaitFor                 Creates a user defined block


Function Details
----------------
RegCore( section )
     
     section   - Name of a section in the robot script
     
     Registers an event handler for the robot's core
     behavior.  Core events occur when no other events are
     happening.  In other words, this section is called
     repeatedly until the robot dies.  The core section may
     be re-registered at any time during a game to change
     the robot's core behavior.  All other registered events
     have higher priorities that the core event.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegAscan( section, priority )

     section    - Name of a section in the robot script
     priority   - Importance of event relative to others 
                  (lower numbers have higher priority) **

     Registers an event handler for auto scanning. Auto 
     scanning events occurs only when a robot is moving. 
     Auto scanning provides robots an opportunity to 
     continue searching for other objects while moving.  
     When an auto scan event handler is registered, it 
     will be called repeatedly while the robot is moving 
     and no higher priority events are occurring. The 
     priority value should be a whole number, decimals
     will be dropped. If two events registered with the 
     same priority occur at the same time, it is unspecified 
     which event handler will be called. This applies to 
     lateral movement only, not rotation. Both the Ahead 
     and Back functions have no meaning in a section 
     handling auto scan events.  

     Auto scan events are triggered by the moving variable. 
     This variable is always true while a robot is moving 
     laterally and false while it is stationary or only 
     rotating.

     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegCldRobot( section, priority )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     
     Registers an event handler for collisions with other
     robots.  The section specified above will be called
     whenever the robot runs into another robot and no other
     higher priority events are occurring. The priority
     value should be a whole number, decimals will be
     dropped.  If two events registered with the same
     priority occur at the same time, it is unspecified
     which event handler will be called. Hitting another
     robot will result in an energy loss of 1 point to each
     robot.
     
     Robot collision events are triggered by the cldrobot
     variable.  When a robot collision event handler
     returns, the cldrobot variable is automatically set to
     false causing the event to end.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegCldMissile( section, priority )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     
     Registers an event handler for collisions with energy
     missiles fired by other robots.  The section specified
     above will be called whenever the robot is hit by an
     energy missile and no other higher priority events are
     occurring. The priority value should be a whole number,
     decimals will be dropped.  If two events registered
     with the same priority occur at the same time, it is
     unspecified which event handler will be called. The
     amount of damage done by an energy missile depends upon
     both the amount of energy put into it and the distance
     it has traveled.
     
     Missile collision events are triggered by the
     cldmissile variable. When a missile collision event
     handler returns, the cldmissile variable is
     automatically set to false causing the event to end.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegCldCookie( section, priority )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     
     Registers an event handler for collisions with energy
     cookies.  The section specified above will be called
     whenever the robot runs into an energy cookie and no
     other higher priority events are occurring. The
     priority value should be a whole number, decimals will
     be dropped.  If two events registered with the same
     priority occur at the same time, it is unspecified
     which event handler will be called.  Hitting an energy
     cookie will result in an energy gain of 20 point.
     
     Cookie collision events are triggered by the cldcookie
     variable.  When a cookie collision event handler
     returns, the cldcookie variable is automatically set to
     false causing the event to end.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegCldMine( section, priority )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     
     Registers an event handler for collisions with energy
     mines.  The section specified above will be called
     whenever the robot runs into an energy mine and no
     other higher priority events are occurring. The
     priority value should be a whole number, decimals will
     be dropped.  If two events registered with the same
     priority occur at the same time, it is unspecified
     which event handler will be called. Hitting an energy
     mine will result in an energy loss of 20 point.
     
     Mine collision events are triggered by the cldmine
     variable.  When a mine collision event handler returns,
     the cldmine variable is automatically set to false
     causing the event to end.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegDtcRobot( section, priority )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     
     Registers an event handler for detection of another
     robot.  The section specified above will be called
     whenever another robot is detected by a call to Scan()
     and no other higher priority events are occurring. The
     priority value should be a whole number, decimals will
     be dropped. If two events registered with the same
     priority occur at the same time, it is unspecified
     which event handler will be called.
     
     Robot detection events are triggered by the dtcrobot
     variable.  When a robot detection event handler
     returns, the dtcrobot variable is automatically
     decremented by one potentially causing the event to
     end.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     
     
RegDtcCookie( section, priority )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     
     Registers an event handler for detection of energy
     cookies.  The section specified above will be called
     whenever an energy cookie is detected by a call to
     Scan() and no other higher priority events are
     occurring. The priority value should be a whole number,
     decimals will be dropped. If two events registered with
     the same priority occur at the same time, it is
     unspecified which event handler will be called.
     
     Cookie detection events are triggered by the dtccookie
     variable.  When a cookie detection event handler
     returns, the dtccookie variable is automatically
     decremented by one potentially causing the event to
     end.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegDtcMine( section, priority )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     
     Registers an event handler for detection of energy
     mines.  The section specified above will be called
     whenever an energy mine is detected by a call to Scan()
     and no other higher priority events are occurring. The
     priority value should be a whole number, decimals will
     be dropped. If two events registered with the same
     priority occur at the same time, it is unspecified
     which event handler will be called.
     
     Mine detection events are triggered by the dtcmine
     variable.  When a mine detection event handler returns,
     the dtcmine variable is automatically decremented by
     one potentially causing the event to end.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     

RegCustom( section, priority, expression )
     
     section   - Name of a section in the robot script
     priority  - Importance of this event relative to others
                 (lower numbers have higher priority)**
     expression - Expression that evaluates to True 
                  (non-zero) or False (zero)**
     
     Registers an event handler for a custom defined event.
     The custom event occurs whenever the provided
     expression evaluates to true and no other higher
     priority events are occurring.  The expression may be
     composed of any legal variables, math operators, or
     logical statements.  Any expression that is legal
     inside an If() statement may also be used as a custom
     event. The priority value should be a whole number,
     decimals will be dropped.  If two events registered
     with the same priority occur at the same time, it is
     unspecified which event handler will be called.
     
     Each section may only have one custom event attached to
     it.  There may be any combination of standard events,
     but only one custom event per section.  When two custom
     events need to use the same section, the events may be
     combined into one with an OR statement.  Alternatively,
     two small helper sections could be created that both
     use Gosub() calls to share the same logic.  When
     multiple custom events are registered to one section,
     only the last one will apply.
     
     Unlike "standard" events, custom events are not ended
     automatically.  For example, when a section registered
     to handle collision events returns, the collision
     variable is reset to false ending the event.  When a
     custom event handler returns, is has no effect on the
     state of the custom event.  If events are not ended
     somehow, the handler section will execute continuously.
     
     Note: When an event handler is registered or re-
     registered, it becomes immediately active.
     
     
CoreEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of core events
     (core events occur when no other events are occurring).
     This function does not effect which section handles
     core events, only whether the events are handled or
     ignored.  The event handler section may be changed by
     another call to RegCore().
     

AscanEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of auto scan
     events.  This function does not effect which section
     handles auto scan events, only whether the events are
     handled or ignored.  The event handler section may be
     changed by another call to RegAscan().
     

CldRobotEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of robot
     collision events.  This function does not effect which
     section handles robot collision events, only whether
     the events are handled or ignored.  The event handler
     section may be changed by another call to
     RegCldRobot().
     

CldMissileEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of missile
     collision events.  This function does not effect which
     section handles missile collision events, only whether
     the events are handled or ignored.  The event handler
     section may be changed by another call to
     RegCldMissile().
     

CldCookieEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of energy cookie
     collision events.  This function does not effect which
     section handles cookie collision events, only whether
     the events are handled or ignored.  The event handler
     section may be changed by another call to
     RegCldCookie().
     

CldMineEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of energy mine
     collision events.  This function does not effect which
     section handles mine collision events, only whether the
     events are handled or ignored.  The event handler
     section may be changed by another call to RegCldMine().
     

DtcRobotEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of robot
     detection events.  This function does not effect which
     section handles robot detection events, only whether
     the events are handled or ignored.  The event handler
     section may be changed by another call to
     RegDtcRobot().


DtcCookieEvents( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of energy cookie
     detection events.  This function does not effect which
     section handles cookie detection events, only whether
     the events are handled or ignored.  The event handler
     section may be changed by another call to
     RegDtcCookie().


DtcMineEvents( bool )

     bool - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of energy mine
     detection events.  This function does not effect which
     section handles mine detection events, only whether the
     events are handled or ignored.  The event handler
     section may be changed by another call to RegDtcMine().


CustomEvents( section, bool )
     
     section - Name a section in the robot script
     bool    - True (non-zero) or False (zero) value **
     
     Used to either turn on or off handling of a specific
     custom event.  Since there may be many registered
     custom events, the specific event must be identified by
     its handler section.  This function does not effect
     which section handles the custom event, only whether
     the event is handled or ignored.  Custom events may not
     really be re-registered.  To move a custom event to a
     different handler, turn off the custom event using this
     function (or register a new custom event to the
     section) then call RegCustom() to register a different
     handler.
     

SetAccel( accel )
     
     accel     - Acceleration value **
     
     Sets the robot's lateral acceleration to a value
     between 1 and 5.  While moving robots are constantly
     accelerating, so this value approximately represents a
     robot's speed.  This function changes the accel
     variable described below.  If this function is never
     called, a robot's acceleration defaults to 3.
     

Ahead( dist )
     
     dist - Distance to move **
     
     Moves the robot ahead the specified amount.  If the
     amount is negative, the robot will move backward.
     Running into another robot will cause damage to both
     robots in the collision.  Each robot will lose one
     energy point per collision.  Hitting a wall will stop a
     robot, but causes no damage.
     
     Note:  The playing arena is a square measuring 400 unit
     in both directions while robots measure 33 units in
     both directions. Ahead() requires multiple turns to complete, 
     therefore causing command blocking (see command blocking).


Back( dist )
     
     dist - Distance to move **
     
     Moves the robot back the specified amount.  If the
     amount is negative, the robot will move forward.
     Running into another robot will cause damage to both
     robots in the collision.  Each robot will lose one
     energy point per collision.  Hitting a wall will stop a
     robot, but causes no damage.
     
     Note:  The playing arena is a square measuring 400 unit
     in both directions while robots measure 33 units in
     both directions. Back() requires multiple turns to complete, 
     therefore causing command blocking (see command blocking).
     

Stop( )

     Causes the robot to abort further movement. This includes 
     both lateral and rotational movement. This function is useful 
     during an event handling routine. When a new event occurs, 
     all movement will continue unless Stop or a new movement 
     function is called. 

     This function stores both the incomplete lateral movement 
     and rotations from the aborted movement in a continue buffer.
     This continue buffer is used by the Continue() function 
     described below.  

     Note:  If Stop() is called when no motion is occurring, the 
     continue buffer is left unchanged. Each time Stop() aborts 
     movement, however, the previous continue buffer is overwritten.


Continue( )

     Continues all movement previously aborted by a call to 
     Stop(). This includes both lateral movement and rotations. 
     Calling Continue() also resets the continue buffer.

     This function only continues aborted movement, it does not 
     restore location. For example, if a robot rotates or moves 
     laterally between calls to Stop() and Continue(), movement 
     will be continued from the new location and orientation.

     Note:  Just like other commands that cause movement, 
     Continue() requires multiple turns to complete, therefore 
     causing command blocking (see command blocking).


BodyLeft( degrees )
     
     degrees   - Degrees to rotate body **
     
     Turns the robot's body counter-clockwise by the amount
     specified. Negative values will cause clockwise
     rotation. The maximum rotation rate of a robots body is
     5 degrees per turn.
     
     Note: Rotation speeds of a robot's body, gun, and radar
     differ.  A robot's body rotates the slowest, its gun
     rotates twice as fast as its body, and its radar
     rotates three times as fast as its body. BodyLeft() 
     requires multiple turns to complete, therefore causing 
     command blocking (see command blocking).
     

BodyRight( degrees )
     
     degrees   - Degrees to rotate body **
     
     Turns the robot's body clockwise by the amount
     specified. Negative values will cause counter-clockwise
     rotation. The maximum rotation rate of a robots body is
     5 degrees per turn.
     
     Note: Rotation speeds of a robot's body, gun, and radar
     differ.  A robot's body rotates the slowest, its gun
     rotates twice as fast as its body, and its radar
     rotates three times as fast as its body. BodyRight() 
     requires multiple turns to complete, therefore causing 
     command blocking (see command blocking).


GunLeft( degrees )
     
     degrees   - Degrees to rotate gun **
     
     Turns the robot's gun counter-clockwise by the amount
     specified. Negative values will cause clockwise
     rotation. The maximum rotation rate of a robots gun 
     is 10 degrees per turn.
     
     Note: Rotation speeds of a robot's body, gun, and radar
     differ.  A robot's body rotates the slowest, its gun
     rotates twice as fast as its body, and its radar
     rotates three times as fast as its body. GunLeft() 
     requires multiple turns to complete, therefore causing 
     command blocking (see command blocking).
     

GunRight( degrees )
     
     degrees   - Degrees to rotate gun **
     
     Turns the robot's gun clockwise by the amount
     specified. Negative values will cause counter-clockwise
     rotation. The maximum rotation rate of a robots gun 
     is 10 degrees per turn.
     
     Note: Rotation speeds of a robot's body, gun, and radar
     differ.  A robot's body rotates the slowest, its gun
     rotates twice as fast as its body, and its radar
     rotates three times as fast as its body. GunRight() 
     requires multiple turns to complete, therefore causing 
     command blocking (see command blocking).
     

RadarLeft( degrees )
     
     degrees   - Degrees to rotate radar **
     
     Turns the robot's radar counter-clockwise by the amount
     specified. Negative values will cause clockwise
     rotation. The maximum rotation rate of a robots radar 
     is 15 degrees per turn.
     
     Note: Rotation speeds of a robot's body, gun, and radar
     differ.  A robot's body rotates the slowest, its gun
     rotates twice as fast as its body, and its radar
     rotates three times as fast as its body. RadarLeft() 
     requires multiple turns to complete, therefore causing 
     command blocking (see command blocking).
     

RadarRight( degrees )
     
     degrees   - Degrees to rotate radar **
     
     Turns the robot's radar clockwise by the amount
     specified. Negative values will cause counter-clockwise
     rotation. The maximum rotation rate of a robots radar 
     is 15 degrees per turn.
     
     Note: Rotation speeds of a robot's body, gun, and radar
     differ.  A robot's body rotates the slowest, its gun
     rotates twice as fast as its body, and its radar
     rotates three times as fast as its body. RadarRight() 
     requires multiple turns to complete, therefore causing 
     command blocking (see command blocking).
     

LockAll( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Turns on or off rotational locking of all robot
     components (body, radar, and gun).  Turning locking on
     causes all components to rotate together at body
     rotation speeds.  For example, with locking on, calling
     the RadarLeft() function will cause the entire robot to
     turn left by the specified amount.  Remember, both the
     gun and radar are forced to rotate at slower body
     rotation speeds.
     

LockGun( bool )
     
     bool - True (non-zero) or False (zero) value **
     
     Turns on or off rotational locking of a robot's gun and
     radar.  Turning locking on causes the gun and radar to
     rotate together at gun rotation speeds.  For example,
     with locking on, calling the RadarLeft() function will
     cause both the gun and radar turn left by the specified
     amount.  Remember, the radar is forced to rotate at
     slower gun rotation speeds.


SyncAll()
     
     Synchronizes both the robot's body and gun to the
     current radar angle.  This function will temporarily
     override any rotation locks established by previous
     calls to LockAll() and LockGun().
     
     Note: SyncAll() requires multiple turns to complete, 
     therefore causing command blocking (see command blocking).
     

SyncGun()
     
     Synchronizes the robot's gun to the current radar
     angle.  This function will temporarily override any
     rotation locks established by previous calls to
     LockAll() and LockGun().
     
     Note: SyncGun() requires multiple turns to complete, 
     therefore causing command blocking (see command blocking).
     

Scan()
     
     Sends out a radar "ping" in the direction of the radar.
     The ping travels in a straight line away from the
     robot.  The distance of the first obstacle encountered
     is placed in the scandist variable described below.
     Distance is measured from the robot's boundary to the
     boundary of the other object or wall.  If the first
     obstacle is another robot, mine, or cookie the
     dtcrobot, dtcmine, or, dtccookie variable will be
     incremented respectively.  This may cause event
     handlers to be called. Every time Scan() is called,
     both the dtcenergy and dtcbearing variables are changed
     as well.
     

Fire( energy )
     
     energy    - Amount of energy to use **
     
     Fires an energy missile in the direction of the robot's
     gun.  The amount of damage done by an energy missile is
     directly proportional to the amount of energy used to
     fire it and the distance the missile travels.  Energy
     used to fire a missile is removed from the robot's
     overall energy store.  Valid firing values are from 1
     to 7.  Zero is ignored, negative numbers cause an
     error, and values greater that 7 are simply reduced to
     7.  Remember, energy missiles lose energy as they
     travel.  Hitting targets at a great distance has a
     smaller effect than hitting close targets.
     
     After firing an energy missile, a robot's gun requires 
     time to cool down. Fire() may be called continuously, but 
     nothing will happen until the gun cools down. Although 
     most robots just ignore this and call Fire() as often as 
     required, the gunheat variable can be used to determine 
     the current heat of the gun.
     
     Note: An energy missile's total energy is the amount of
     energy put into a missile multiplied by 4. Although a
     missile loses energy as it travels, its strength will
     never go below 4.  The damage done to another robot
     will never go below 5 since 1 point is also lost due to
     the collision.
     

If( expression )
     
     expression - Expression that evaluates to True 
                  (non-zero) or False (zero)**
     
     Used to start a logical if block based upon the value
     of an expression.  If() blocks may be nested, but there
     should only be one If() statement opening each block.
     The expression may contain any legal variable, numeric
     value, logical operator, or math operator.
     

Elseif( expression )
     
     expression - Expression that evaluates to True 
                  (non-zero) or False (zero)**
     
     Evaluated if the opening If() or previous Elseif()
     statement in a logical If() block evaluates to false.
     Behaves exactly like an If() statement, but may not be
     the first statement in a logical if block.  There may
     be multiple Elseif() statements in a single block. The
     expression may contain any legal variable, numeric
     value, logical operator, or math operator.


Else
     
     Evaluated when the all previous If() and Elseif()
     statements in a logical If() block have evaluated to
     false.  If() blocks may be nested, but there may only
     be one Else statement in each block.


Endif

     Marks the end of a logical If() block.  If() blocks may
     be nested, but there may only be one Endif statement
     ending each block.
     

Gosub( section )
     
     section   - Name of a section in the robot script
     
     Causes execution to continue at the first line of the
     specified section.  When the called section finishes
     its last line or hits a Return statement, execution
     continues at the line after the Gosub() call.
     
     Note: Sections that are executed with a Gosub() command 
     inherit the priority of their callers. This implies 
     that sections executed with the Gosub() command have
     no unexpected effect on events; they behave exactly as 
     their callers behave. 
     

Return
     
     Causes the current section to end at the current line,
     returning to the caller.  If there was no explicit
     caller, then next event will be processed.
     

Round( value, decimals )

     value - Numerical value that should be rounded **
     range - Number of decimal places to which value should be rounded **
     
     The first argument is rounded to the number of decimal
     places specified by the second parameter. The resulting
     number is placed in the result variable. The decimals
     argument must be an integral number in the range of 0
     to 38 inclusive.
     

Truncate( value )

     value - Numerical value that should be truncated **

     The decimal portion of the specified value is removed. The 
     resulting whole number is placed in the result variable.


GetRandom( range )

     range - Limiting range for random number generation **
     
     Fills the result variable with a pseudo-random number.
     The generated number will be between 0 and the
     specified range.  Valid ranges are from -32767 to 32767
     inclusive.  Zero of course, is not a valid range.  For
     example, a random rotational value might be generated
     by using a range of 359.  The resulting random number
     would be between 0 and 359 inclusive.
     

GetHitStr()
     
     Fills the result variable with the average damage done
     by this robot to all other robots in the current game.
     This is only damage done by missile hits, not
     collisions.  Missed shots do not affect this number.
     This information might be used to adjust firing
     tactics.
     

GetHitsOther()
     
     Fills the result variable with the number of times the
     robot has hit other robots with an energy missile.
     This number is often combined with the results of
     GetShots() to modify firing tactics.
     

GetShots()
     
     Fills the result variable with  the number of energy
     missiles the robot has fired.  This number does not
     reflect whether or not these shots hit something.  This
     number is often combined with the results of
     GetHitsOther() to modify firing tactics.
     

GetOthers()
     
     Fills the result variable with the number of other
     robots left in the current game not including the robot
     calling this function.  This number is often used to
     gauge a robot's performance.
     

GetTurns()
     
     Fills the result variable with the number of turns the
     robot has had in the current game.
     

GetHitsSelf()
     
     Fills the result variable with the number of time the
     robot has been hit by other robot's energy missiles.
     
     
Store( variable )
     
     variable  - Variable name
     
     This function allows a robot that is fighting in a
     multiple game match to pass values from one game to the
     next.  This function stores the specified variable in
     permanent storage for the current match.  When the next
     game starts, all stored variables will be automatically
     restored.  Stored variables will have the same values
     they contained the last time Store() was called in a
     previous game.  This may be useful for robots that
     "learn" during a match, changing behavior dynamically.
     This function can not be used to store variables across
     multiple matches.
     

Name( string )
     
     string    - Text surrounded by quotation marks
     
     Sets the robot's name.  The string will be used to
     reference the robot during game play.  If this function
     is not called anywhere in a robot's script, a name will
     be automatically assigned.
     

Print( string )
     
     string    - Text surrounded by quotation marks
     
     Adds the specified string to the output display in a
     robot's information window. Also, a time stamp is
     prepended to the output display. At any given point in
     a game, this time stamp will have the same value for
     all robots. The output display is limited to 200
     entries.  When Print() is called more than 200 times,
     the oldest entries will be removed first. This function
     is useful primarily when debugging a robot.  During
     game play, click on a robot's name button to display
     its information window.
     

Print( variable )
     
     variable  - Variable name or numeric value **
     
     Adds the specified value to the output display in a
     robot's information window. Numerical values have 7
     digits of precision, but 3 decimal places are always
     displayed for clarity. Also, a time stamp is prepended
     to the output display. At any given point in a game,
     this time stamp will have the same value for all
     robots. The output display is limited to 200 entries.
     When Print() is called more than 200 times, the oldest
     entries will be removed first. This function is useful
     primarily when debugging a robot.  During game play,
     click on a robot's name button to display its
     information window.
     

Stall( time )
     
     time - Amount of time to stall **
     
     Causes the robot to freeze for the specified amount of
     time.
     
     Note:  The robot will not even respond to events. This
     function completely disables a robot.
     

Blocking( bool )

     bool    - True (non-zero) or False (zero) value **

     This is an advanced feature. Use of the Blocking command 
     is not required to play robot battle.

     This function allows command blocking to be turned on or 
     off. When blocking is turned off, it remains off for the 
     entire robot script until explicitly turned back on.

     The default behavior is for blocking to be on. When blocking 
     is on, calls to commands that require multiple turns block. 
     This means that within a section, execution will pause on 
     the multi-turn command. Code following the multi-turn command 
     will not be executed until the multi-turn command completes. 
     In other words, all function calls are synchronous.  When 
     blocking is turned off, multi-turn commands do not block. 
     Code following the multi-turn command executes immediately. 
     In other words, all function calls are asynchronous.

     Blocking should be turned off with great care. A robot's 
     body, gun, and radar can perform only one multi-turn command 
     (i.e. movement) at a time. Only the last command on each body 
     part takes effect. For example, when blocking is off, if a 
     call to BodyLeft is followed immediately by a call to Ahead, 
     the original BodyLeft will be ignored while the robot moves 
     ahead. When blocking is turned off, all previously blocked 
     commands remain blocked.  Likewise, when blocking is turned 
     on, all previously unblocked commands remain unblocked. Only 
     commands that are called after a change in blocking are 
     effected by the change.

     Turning blocking off is used primarily with the Continue 
     command. When an event handler is called, for example, 
     movement may be stopped and continued without blocking on 
     the Continue command.  This allows the event handler to 
     be ended while restricting blocking to the section and 
     line that initiated to original movement.

     Note: This command is not related to and has no effect on 
     events or event registration.
     

WaitFor( expression )

     expression - Expression that evaluates to True **
                  (non-zero) or False (zero)

     This is an advanced feature. Use of the WaitFor() command is
     not required to play robot battle.

     This command provides a means of creating a user defined 
     command block. This means that within a section, execution 
     will pause on the WaitFor() command until expression becomes 
     true. Code following the WaitFor() command will not be 
     executed until expression becomes true. Generally, blocks 
     are created using expressions that change over time. Blocks 
     that are based on constant value expressions either block 
     permanently or never block.

     This command is generally used as a synchronization method. 
     This is particularly useful when normal command blocking 
     has been turned off with the Blocking() command. 

     The WaitFor() command has no effect on events. All events 
     will be handled normally. If a higher priority event occurs
     while blocking, for example, its event handler will be called. 
     When the higher priority event handler ends, control will again 
     return to the WaitFor().


Command Blocking
----------------
    Command blocking is an advanced feature. Unless the Blocking()
    or WaitFor() functions are being used, this information should
    not be needed.

    Command blocking occurs when a robot function requires multiple
    turns to execute. Only commands that cause movement require 
    multiple turn to execute. These include Ahead(), Back(), 
    BodyLeft(), BodyRight(), GunLeft(), GunRight(), RadarLeft(), 
    RadarRight(), SyncAll(), SyncGun(), and Continue().

    When a command blocks, execution will pause on that command.  
    Code following the multi-turn command will not be executed until 
    the multi-turn command completes. In other words, the function 
    call is synchronous. Since each robot component can only perform 
    one multi-turn command at a time, blocking greatly simplifies the 
    conrol of a robot.

    When blocking is turned off, for example, a GunLeft(20) call 
    followed by another GunLeft(20) will only move the gun left 20 
    degrees. Since the first call does not block, the second call 
    immediately supersedes the first call. 




                                Chapter 8.0

                              Special Sections


These sections are considered "special" because both of them handle events 
without being registered.  The game will automatically call these sections 
when their pre-defined events occur.


Init
     
     This section handles game startup events.  It is
     automatically called at the start of every game.  It is
     always the first section to be executed, and will only
     be called automatically once.  Most robots use this
     section to register other event handlers.  Although
     Init is only called once automatically, it may be
     called "manually" at any time by either registering
     events to it, or by using the Gosub() command.
     
     Note:  Robots are required to have an Init section.


Dead
     
     This section handles robot death events.  It is
     automatically called when a robot is killed.  Robots
     are killed either when their energy reaches zero or
     when the game they are playing in ends.  Even if a
     robot wins a game, its dead section will be called.
     Since the robot is dead, only a subset of the robot
     functions listed above have meaning.  Most robots use
     the dead section to perform some type of calculation
     then call the Store() function to save information for
     future games.  When called "manually", a dead section
     behaves like any other section.
     
     Note:  Robots are not required to have a Dead section.
     


                                Chapter 9.0

                              Math Operators


Standard math operators.  Operator precedence follows that of standard 
scientific calculations.  Brackets () may be used to manually change the 
order of evaluation.  Results are also the same as those produced by a 
standard scientific calculator.

Description     Usage Format            Output Range
-----------     ------------            ------------
Cosine          cos( degrees )          -1 <= result <= 1
Sine            sin( degrees )          -1 <= result <= 1
Tangent         tan( degrees )          NA
ArcCosine       acos( value )*          0  <= result <= 180
ArcSine         asin( value )*          -90 <= result <= 90
ArcTangent      atan( value )           -90 <= result <= 90
Raise to power  ^                       -3.4e  38 <= result <= 3.4e  38
Multiplication  *                       -3.4e  38 <= result <= 3.4e  38
Division        /                       -3.4e  38 <= result <= 3.4e  38
Addition        +                       -3.4e  38 <= result <= 3.4e  38
Subtraction     -                       -3.4e  38 <= result <= 3.4e  38
Assignment      =                       NA
Numeric values   3.4e  38 (6 digits)  NA


* Value must be greater than or equal to -1 and less than or equal to 1.

Note: Variables are automatically defined by placing them on the left side of 
      the assignment operator.  All variables have an initial value of zero 
      until explicitly assigned a different value.




                               Chapter 10.0

                             Logical Operators


These operators are commonly used in If() statements and custom events, but 
may be used anywhere an expression is valid.  Several operator have two 
definitions.  The second definition is provided for `C' programmers who are 
stuck in their ways (like me).

Description                     Usage Format
-----------                     ------------
Equality comparison                ==
Not equal to                       <>, !=
Greater than or equal to           >=
Less than or equal to              <=
Greater than                       >
Less than                          <
Logical AND                        and, &&
Logical OR                         or, ||




                                Chapter 11.0

                              Robot Variables


These variables describe a robot's state during game play. They may be used 
in any expression in a robot's script.  The only restriction is that these 
variables are read only. Their values are for informational purposes only 
and are maintained by the game itself.  They may not be changed directly by 
assignment. Remember, capitalization is not important.  A variable named
"VARIABLE" will be that same as "variable" or "Variable".


Variable Summary
----------------
accel                   The robot's current acceleration
bodyaim                 Current angle of robot's body
bodyrmn                 Angular rotation remaining in the robot's body
cldbearing              Bearing to the last object the robot collided with
cldcookie               Cookie collision indicator
cldenergy               Energy of the last object the robot collided with
cldmine                 Mine collision indicator
cldmissile              Missile collision indicator
cldrobot                Robot collision indicator
death                   Indicates that another robot has died
distrmn                 Distance remaining in the robot's lateral movement
dtcbearing              Bearing to the last object the robot detected
dtccookie               Cookie detection indicator
dtcenergy               Energy of the last object the robot detected
dtcmine                 Mine detection indicator
dtcrobot                Robot detection indicator
energy                  The robot's remaining energy level
false                   Constant zero value
gamenbr                 Current game number
games                   Number of games in the current match
gunaim                  Angle of the robot's gun
gunheat                 Heat of the robot's gun
gunrmn                  Angular rotation remaining in the robot's gun
moving                  Lateral movement indicator
off                     Constant zero value
on                      Constant non-zero value
radaraim                Angle of robot's radar
radarrmn                Angular rotation remaining in the robot's radar
rotating                Rotation indicator
scandist                Distance to the nearest detected object
true                    Constant non-zero value



Variable Details
----------------
scandist
     
     Each time the Scan() function is called, this variable
     is filled with the distance to the nearest object.
     This may be the distance to a wall, another robot, a
     cookie, or a mine.  Energy missiles are ignored.  
     Distance is measured from the robot's boundary to the 
     boundary of the other object or wall. Also, if another 
     robot, cookie, or mine is detected, the appropriate 
     detection variable will be incremented and the section 
     registered to handle the event will be called.
     

cldrobot
     
     Set to true when the robot collides with another robot.
     When the collision occurs, the section registered by
     RegCldRobot() will also be called. Collision indicators
     are mutually exclusive. When cldrobot is true all other
     collision variables will be false. This variable is
     reset to false automatically when the robot collision
     event handle returns. If no section has been registered
     to handle robot collision events, this value will
     remain true until a collision with a different object
     occurs.
     

cldmissile
     
     Set to true when the robot collides with an energy
     missile.  When the collision occurs, the section
     registered by RegCldMissile() will also be called.
     Collision indicators are mutually exclusive. When
     cldmissile is true all other collision variables will
     be false. This variable is reset to false automatically
     when the missile collision event handle returns. If no
     section has been registered to handle missile collision
     events, this value will remain true until a collision
     with a different object occurs.
     

cldcookie
     
     Set to true when the robot collides with an energy
     cookie.  When the collision occurs, the section
     registered by RegCldCookie() will also be called.
     Collision indicators are mutually exclusive. When
     cldcookie is true all other collision variables will be
     false. This variable is reset to false automatically
     when the cookie collision event handle returns. If no
     section has been registered to handle cookie collision
     events, this value will remain true until a collision
     with a different object occurs.
     

cldmine
     
     Set to true when the robot collides with an energy
     mine.  When the collision occurs, the section
     registered by RegCldMine() will also be called.
     Collision indicators are mutually exclusive. When
     cldmine is true all other collision variables will be
     false. This variable is reset to false automatically
     when the mine collision event handle returns. If no
     section has been registered to handle mine collision
     events, this value will remain true until a collision
     with a different object occurs.
     

cldenergy
     
     When a robot collides with any other object, this
     variable is filled with the energy of that object.
     Robots may collide with energy missiles, other robots,
     cookies, and mines. All objects, including mines,
     return positive energy values. There is no such thing
     as negative energy. The value of cldenergy will not
     change until another collision occurs.  This variable
     is often used to judge an enemy robot's relative
     strength.
     

cldbearing
     
     When a robot collides with any other object, this
     variable is filled with the bearing to that object.
     Robots may collide with energy missiles, other robots,
     cookies, and mines. This variable is a bearing from the
     robot's current heading to that object, not an absolute
     heading.  Values are in degrees ranging from -180 to
     179.  A cldbearing of zero is always directly ahead of
     the robot.
     
     For example, if a robot were heading 135 degrees and an
     energy missile hit the robot's body at an absolute
     angle of 90 degrees (3 o-clock), the cldbearing
     variable would be set to -45.  In other words, the
     robot was hit 45 degrees left of its current heading.
     
     Remember, cldbearing says nothing about the direction
     an object was traveling when it collided with the
     robot, only where it hit the robot.  This should be
     evident since the other object may not have even been
     moving. The value of cldbearing will not change until
     another collision occurs.
     

dtcrobot
     
     This variable is incremented by one when another robot
     is detected by a call to Scan().  It is set to zero
     when a call to Scan() does not detect another robot.
     When robot detection occurs, the section registered by
     RegDtcRobot() will be called.  This variable is
     decremented by one automatically when the robot
     detection event handle returns.  For this reason, many
     robots call Scan() at the end of their detection event
     handlers.  If no section has been registered to handle
     robot detection events, this value will remain non-zero
     until a call to Scan() detects no other robots.
     

dtccookie
     
     This variable is incremented by one when an energy
     cookie is detected by a call to Scan().  It is set to
     zero when a call to Scan() does not detect a cookie.
     When an energy cookie is detected, the section
     registered by RegDtcCookie() will also be called.  This
     variable is decremented by one automatically when the
     cookie detection event handle returns.  If no section
     has been registered to handle cookie detection events,
     this value will remain non-zero until a call to Scan()
     detects no energy cookies.
     

dtcmine
     
     This variable is incremented by one when an energy mine
     is detected by a call to Scan().  It is set to zero
     when a call to Scan() does not detect a mine.  When an
     energy mine is detected, the section registered by
     RegDtcMine() will also be called.  This variable is
     decremented by one automatically when the mine
     detection event handle returns.  If no section has been
     registered to handle mine detection events, this value
     will remain non-zero until a call to Scan() detects no
     mines.
     

dtcenergy
     
     When a robot detects any other object, this variable is
     filled with the energy of that object.  Robots may
     detect other robots, cookies, and mines. All objects,
     including mines, return positive energy values.  There
     is no such thing as negative energy.  If no objects are
     detected by Scan(), dtcenergy is set to zero.  This
     variable is often used to judge an enemy robot's
     relative strength.
     
     Every time Scan() is called, dtcenergy will change. It
     will either be set to the detected object's energy or
     zero if no object was detected. This is true even when
     the detected object does not have a detection event
     handler registered.


dtcbearing
     
     When a robot detects any other object, this variable is
     filled with the bearing to that object.  Robots may
     detect other robots, cookies, and mines. This variable
     is a bearing from the robot's current heading to that
     object, not an absolute heading.  Values are in degrees
     ranging from -180 to 179.  A dtcbearing of zero is
     always directly ahead of the robot.
     
     This variable is provided primarily for consistence
     with collision variables.  Since objects may only be
     detected by a radar ping, dtcbearing always matches the
     bearing of the robot's radar at the time Scan() was
     called.  See cldbearing for more details about bearing.
     
     Every time Scan() is called, dtcbearing will change.
     It will always reflect the bearing of the robot's
     radar, even if no objects were detected.


death
     
     When another robot in the current game dies, the death
     variable is set to true. This variable is an exception
     to the read only rule.  Since the game never resets
     death to false, this must be done by the robot.  This
     variable can be used for custom events, just remember
     to change it to false at some point to end the event.
     It is easiest to think of the death variable as an
     automatically provided user variable.
     

energy
     
     The robot's remaining energy level.  This number always
     starts at 100 and is changed by various events during
     game play.  When this value reaches zero, the robot is
     out of the game.  This value will always match that
     shown on the game's playing field.  Please see Damage
     Summary for more detail.
     

accel
     
     Current setting of the robot's acceleration.  While
     moving laterally, robots are constantly accelerating.
     Therefore, this value approximately represents a
     robot's movement speed.   This value is changed by
     calling the SetAccel() function and defaults to 3.
     

moving

     True while the robot is moving laterally and false while 
     the robot is stationary or rotating only.


rotating

     True while any part of the robot is rotating and false 
     while the robot is stationary or moving laterally only.


gunheat

     Current heat of the robot's gun. Every time a robot calls 
     Fire() its gun heats up. As time passes, the gun cools down. 
     A robot may only fire another energy missile when gunheat 
     reaches zero. Most robots simply ignore this variable and 
     call Fire() as often as possible.


distrmn

     When a robot is moving laterally, this variable contains 
     the distance remaining until the movement is complete. This 
     information is useful when a robot needs to store or test 
     the amount of lateral movement remaining. If the robot is 
     not moving, this variable will be zero. Do not confuse this 
     variable with the internal "continue buffer" described in 
     the Stop() and Continue() functions, they are similar but 
     independent.

bodyrmn

     When a robot's body is rotating, this variable contains 
     the amount of rotation remaining until the rotation is 
     complete. This information is useful when a robot needs 
     to store or test the amount of body rotation currently 
     remaining. If the robot's body is not rotating, this variable 
     will be zero. Do not confuse this variable with the internal 
     "continue buffer" described in the Stop() and Continue() 
     functions, they are similar but independent.

gunrmn

     When a robot's gun is rotating, this variable contains 
     the amount of rotation remaining until the rotation is 
     complete. This information is useful when a robot needs 
     to store or test the amount of gun rotation currently 
     remaining. If the robot's gun is not rotating, this variable 
     will be zero. Do not confuse this variable with the internal 
     "continue buffer" described in the Stop() and Continue() 
     functions, they are similar but independent.

radarrmn

     When a robot's radar is rotating, this variable contains 
     the amount of rotation remaining until the rotation is 
     complete. This information is useful when a robot needs 
     to store or test the amount of radar rotation currently 
     remaining. If the robot's radar is not rotating, this variable 
     will be zero. Do not confuse this variable with the internal 
     "continue buffer" described in the Stop() and Continue() 
     functions, they are similar but independent.

bodyaim
     
     Current angle of the robot's body.  Values are in
     degrees ranging from 0 - 359.  A bodyaim of zero is
     towards the top of the arena, or map north.  This value
     is changed by the various rotation functions.
     

radaraim
     
     Current angle of the robot's radar.  Values are in
     degrees ranging from 0 - 359.  A radaraim of zero is
     towards the top of the arena, or map north.  This value
     is changed by the various rotation functions.
     

gunaim
     
     Current angle of the robot's gun.  Values are in
     degrees ranging from 0 - 359.  A gunaim of zero is
     towards the top of the arena, or map north.  This value
     is changed by the various rotation functions.
     

result
     
     This is a generic results buffer.  Since robot
     functions do not return values, any function that
     generates a number fills this variable with its
     results.  This value may therefore change often.  It
     should only be used immediately after calling a
     function that fills it.  If the value is needed at a
     later time, it should be assigned to a user defined
     variable.  All functions that use this variable mention
     it in their description (usually a GetSomething()
     function).
     

gamenbr

     Current game number. Robot Battle matches have from 1 to 
     65,500 games. This variable is set to 1 for the first 
     game of a match and incremented by one for each successive  
     game. The gamenbr variable will be 2 for the second game 
     of a match, 3 for the third, and so on.


games

     Number of games in the current match. This variable does 
     not change from game to game, only from match to match. 
     It always contains the total number of planned games in 
     a match. Robot Battle matches have from 1 to 65,500 games.


on
     
     Evaluates to a non-zero value.


true
     
     Evaluates to a non-zero value.
     

off
     
     Evaluates to a zero value.


false
     
     Evaluates to a zero value.
     


                                Chapter 12.0

                           User Defined Variables


User defined variables are the primary means of storing information about a 
robot. As the designer of a robot, you decide how many user variables you 
need and what their names should be. All variables are global. Global means 
that a variable can be accessed and changed from anywhere in a script file.

User variables must start with a letter (A-Z) or an underscore (_). Variables 
may contain numbers (1-9), but they may not start with a number. Any name may 
be used for variables except section names. In other words, round is a valid 
variable name, but init is not.
                               

User variables are automatically defined by placing them on the left side of 
the assignment operator. This may be done anywhere in a robot's script. At 
the start of a game, user defined variables are initialized to zero. The only
exception to this rule are variables stored with a previous call to the 
Store() function. The following line defines a user variable called fire_engy:

     fire_engy = 1

Assuming Store() has not been called for fire_engy in a previous game, the 
variable fire_engy is created and assigned a value of zero at the start of a 
game. Not until the line above is actually executed will the variable contain 
a value of one. If this line is never reached during a game, fire_engy will 
always contain a value of zero.

Variables that where stored in a previous game with the Store() function do 
not default to values of zero. When these variables are created at the start 
of a game, they are assigned the values they contained when Store() was last 
called for each variable. This allows variables to be passed from one game to 
the next in a match.

Variables may contain values in the range of  3.4e  38 with a precision of 
6 digits. As with most computer languages, floating point (real number) math 
is not perfectly accurate. Testing for equality after performing calculations 
may produce unexpected results. For example, acos( cos(20) )  may yield 
19.9999 instead of 20. Use the Round() function if this problem arises.


Example:
--------

     test1 = variable
     variable = -10.5
     test2 = variable
     print( test1 )
     print( test2 )

Assuming Store() has not been called, what are the values of test1 and test2? 
When the game starts, test1, variable, and test2 are all created and assigned 
values of zero. Line 1 therefore assigns test1 to a value of zero (which it 
already was).  Line 2 changes variable from a value of 0 to a value of -10.5.  
Line 3 then changes test2 from a value of 0 to a value of -10.5.

Thus, the Print() functions display:
     0
    -10.5



                                Chapter 13.0

                               Damage Summary


The following summarizes the events that can change a robot's energy store.  
When a robot collides with any other object, it loses 1 energy point.  The 
"obtained from" description below is provided to illustrate this. All objects 
contain positive energy. There is no such thing as negative energy. The 
difference between objects is whether they add or subtract their energy from 
a robot.


Action                          Energy Change
------                          -------------
Firing energy missile           -1 to -7
Collision with energy missile   -5 to -29  obtained from: (-4 to -28 -1)
Collision with another robot    -1         obtained from: (-1)
Collision with energy mine      -20        obtained from: (-19 - 1)
Collision with energy cookie    +20        obtained from: (21 - 1)




                                Chapter 14.0

                             Points Calculation


Points calculation is straight forward.  When a robot is eliminated from a 
game, all surviving robots receive a single point.  The winner of a game also 
receives one bonus point for winning.  In a six player game, for example, the
winner receives 6 points, second place receives 4, third gets 3, fourth gets 
2, fifth gets 1, and the loser gets nothing.  Points are displayed at the end 
of each match.  In a multiple game match, points from all games in the match
are tallied for the final standings.




                                Chapter 15.0

                            Tips and Techniques


- Organize robots into small sections (subroutines) the perform specific 
    tasks.  These section enhance robot clarity, are often reusable within a 
    single robot, and make great cut and paste candidates for new robots.
  
- Check out the sample robots (fire.prg in particular) for some useful 
    subroutines that can be copied immediately.
  
- Use the Print() statements to help debugging.  It can display both 
    strings surrounded by quotations and expressions.

- Write special purpose debugging robots to help figure out how normal 
    robots will behave.  Debugging robots behave in a predictable manner 
    (such as driving to the center of the arena) helping to isolate a 
    particular feature or problem in another robot.
  
- When using a debugging robot, use the Stall() function in the normal robot. 
    This will give the debugging robot time to start it predetermined 
    activities.
  
- Use comments liberally in robot scripts.  Comments act as helpful reminders 
    when examining robot scripts. Any text after a # or a // is considered a 
    comment. Comments are completely ignored by Robot Battle.
  
- Use indentation with If() statements.  Indenting lines between If(), 
    Elseif(), Else, and Endif statements greatly increases a robot script's 
    readability.
  
- Be careful when using variables that are changed often during game play. 
    These include result, cldbearing, cldenergy, dtcbearing, and dtcenergy. 
    If needed at any time other than immediately after they are filled, 
    assign their values to user defined variables.
  
- The arena measures 400 unit in each direction, robots measure 33 units in 
    each direction, cookies and mines have diameters of 9 units, and energy 
    missiles are 3 units square.
  
- As with most computer languages, floating point (real number) math is not 
    perfectly accurate. Particularly after trigonometric functions, testing 
    for equality without calling Round() will not always work.  For example, 
    acos( cos(20) ) may yield 19.9999 instead of 20.
  
- The amount of time it takes for a game with no activity to be automatically 
    ended may be changed. The default value is 10,000 turns.  To make this 
    value smaller or larger, open the winrob.ini file in an ASCII text editor.  
    Change the value of the entry under [WinRob] called auto_end_turns. If 
    auto_end_turns does not exist, add it under [WinRob] with the desired 
    time-out value.

- Large robots that respond to many events can become quite complicated. 
    Complexities often arise from the need to remember where a robot is and 
    what it is doing before and after each event. Designing robots as state 
    machines can simplify this problem. A robot's behavior can be modeled as 
    transitions from one state to the next, allowing easy state recovery 
    during and after an event.
