 
        
                        ROBOT BATTLE REFERENCE MANUAL                 
                                                                    
                    Thank you for playing robot battle!               
                                                                        
               COPYRIGHT (C) 1996 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.

The contents of this file have been reduced from previous versions. This 
is partially to conserve space and partially to preserve my sanity. This 
file now provides a printable version of all robot commands, special 
sections, operators, and variables. All other information about Robot
Battle can be easily found in the on-line help.


Table of Contents

        Chapter 1.0             Scripting Language Functions
        Chapter 2.0             Special Sections
        Chapter 3.0             Math Operators
        Chapter 4.0             Logical Operators 
        Chapter 5.0             Robot Variables




                                Chapter 1.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.


Function Summary

=                  Assigns a value to a user defined variable
Abs                Calculates an absolute value
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 missiles
GetHitStr          Determines the average damage done by the robot's 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 robot's gun and radar
Name               Sets the robot's name
Max                Determines the smaller of two values
Min                Determines the larger of two values
Print              Adds a string to the output display window
Print              Adds a variable to the output display window
RadarLeft          Turns the robot's radar to the left
RadarRight         Turns the robot's 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 robot's 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


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


Function Details


lvalue = rvalue

     lvalue    - User declared variable
     rvalue    - Numerical value to be copied **
     
     
     The assignment command does not follow the standard Robot Battle 
     command syntax. The non-standard format is more natural and 
     matches the syntax of other computer languages.
     
     The assignment command copies a value into a user defined 
     variable. This is the only way to change the value of a user variable. 
     Variables are automatically defined by placing them on the left side 
     of the assignment command. All variables have an initial value of 
     zero until explicitly assigned a different value.
     

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. Use the CoreEvents command to 
     deactivate the event handler.
     

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. Use the AscanEvents command to 
     deactivate the event handler.
     

RegCldRobot( 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 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. Use the CldRobotEvents command to 
     deactivate the event handler.
     

RegCldMissile( 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 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. Use the CldMissileEvents command to 
     deactivate the event handler.


RegCldCookie( 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 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. Use the CldCookieEvents command 
     to deactivate the event handler.
     

RegCldMine( 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 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. Use the CldMineEvents command to 
     deactivate the event handler.
     

RegDtcRobot( 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 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. Use the DtcRobotEvents command to 
     deactivate the event handler.
     
     
RegDtcCookie( 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 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. Use the DtcCookieEvents command 
     to deactivate the event handler.
     
     
RegDtcMine( 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 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. Use the DtcMineEvents command to 
     deactivate the event handler.
     

RegCustom( section, priority, expression )

     section    - Name of a section in the robot script
     priority   - Importance of 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. Use the CustomEvents command to 
     deactivate the event handler.
     

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. Therefore, this 
     value approximately represents a robot's speed.  This function 
     changes the accel variable described below.  If this function is never 
     called, 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.
     

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.
     
     
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.
     
     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, causing 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 robot's 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.
     
     
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 robot's 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.
     
     
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 robot's 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.
     
     
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 robot's 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.
     
     
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 robot's 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.
     
     
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 robot's 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.
     
     
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.
     

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

Abs( value  )
     
     value     - Numerical value whose sign will be dropped **
     
     The sign of the specified value is dropped and copied to the result 
     variable. The absolute value of any number has the same 
     magnitude as the original and a positive sign.
     
     
Max( value1, value2  )
          
     value1    - Numerical value that will be tested for maximum **
     value2    - Numerical value that will be tested for maximum **
     
     The two values are compared to determine which is the largest. The 
     number which has the greatest value is copied to the result variable. 
     
     Note: Negative numbers close to zero are larger than negative 
     numbers far from zero.
     

Min( value1, value2  )
     
     value1    - Numerical value that will be tested for minimum **
     value2    - Numerical value that will be tested for minimum **
     
     The two values are compared to determine which is the smallest. 
     The number which has the least value is copied to the result 
     variable. 
     
     Note: Negative numbers far from zero are smaller than negative 
     numbers close to zero.
     

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. This 
     command is very useful for debugging purposes.
     
     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 2.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 3.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. Calculation 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
Modulus         %                       integral value
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 command.  All variables have an initial value of zero 
      until explicitly assigned a different value.




                               Chapter 4.0

                             Logical Operators
______________________________________________________________________________


These operators are commonly used in If statements and custom events, but 
may be used anywhere an expression is valid.  Several operators 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 5.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
result             Generic computation results buffer
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.
     
     
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.
