GarBots v1.6

HaresWARE Development
Copyright 2003 All rights reserved
http://www.hares.net/scott/bot.htm


DESCRIPTION:

GarBots is a robot programming game. A subset of the BASIC language is used to program your GarBot for battle. Program GarBots and hold tournaments to optimize your best GarBot. Then you can use GarBots Beam or Export features to exchange your best GarBots (in secure mode) for battle with a friend. Use available commands to make your GarBot move around the arena, search for opponents, and take offensive and defensive action to win the battle. 

The term - 'the interpreter' is used in this document, and refers to the internal modules of GarBots that interpret GarBot code and execute instructions. The GarBots BASIC interpreter is referred to as 'BASIC like' because of its extremely limited implementation compared to versions of BASIC that many people are familiar with. But, the interpreters functionality should be at least minimally suitable for developing quality GarBots. 

Demo:

Updates - Bug fixes and minor improvements will be downloadable at no extra cost when available.

Requirements  

Contents

    General programming rules
    Language reference
    GarBot functions
    Battle Arena
    User interface

 

General programming rules:

top



Language Reference
    Variables
    Constants
    REM
    PRINT
    GOTO
    IF THEN ELSE ENDIF
    WHILE NEXT
    FOR TO NEXT
    GOSUB RETURN
    END
    MIN MAX ABS
    RAND
    Math functions
    RTOP PTOR

top




Variables
- You are limited to 26 variables, and they are restricted to labels A thru Z.
- Only integer type variables are supported. No floating point or string variable assignments are supported.

top
language reference



Constants
ARENAX - Size of the arena in the X direction, with left representing 0
ARENAY - Size of the arena in the Y direction, with top representing 0
DAMAGERAD - Damage Radius - When a shell explodes, any GarBot within DAMAGERAD from the bomb will incur damage. The damage imposed is a factor of the bots distance from the explosion (but still within DAMAGERAD distance)
SCANRAD - Scan Radius - The range of a scan, i.e. a scan will not see another GarBot or drone that is > than SCANRAD distance away.
MAXLIFE - This is the amount of life that all bots involved in a battle are granted.
DRIVESTEP - DRIVE commands which specify a distance greater than DRIVESTEP are broken into multiple commands that fit within the DRIVESTEP value.


Example:
 

r = SCANRAD
x = (ARENAX / 2) ' sets x to one half of ARENAX

top
language reference



REM - represents a program comment. A comment can also be done with a simple quote or (') mark. Any text that appears after the REM or ' will be ignored by the interpreter, up to the next linefeed.


Example:
  

 REM this is a comment

top
language reference



PRINT - prints a message to the output area of the arena. Variables, and constants can be appended to the print statement with a comma


Example:


    PRINT "variable a = ", a

Constraints:

    Printing the return value of a function must be done in a two step process. First assign the return value to a variable, and then use the variable in PRINT statement as shown in the example. Mathematical expressions are permitted provided that they are bracketed in parentheses.

top
language reference



GOTO - Causes execution to jump to the specified label


Example:

    x = 1
    100
    PRINT "x = ", x
    x = x + 1
    GOTO 100

This example would obviously result in an endless loop which does nothing but print the value of x and increment.

top
language reference



IF cond THEN ELSE ENDIF

Notes:
- Must end with ENDIF
- Conditional operators include
> Greater than
< Less than
= Equal
>= Greater than or equal
<= Less than or equal
!= Not equal

Example:

    IF x > 0 THEN
        f = FIRE 45 x
    ELSE
        DRIVE 180 20
    ENDIF

    or

    IF x = 1 THEN
        REM do something
    ENDIF

top
language reference



WHILE cond NEXT

Notes:
- Must end with NEXT
- Conditional operators include
> Greater than
< Less than
= Equal
true
false
>= Greater than or equal
<= Less than or equal
!= Not equal

Example:

    x = POSX()
    WHILE x < SCANRAD
        DRIVE 180 10
        x = x - 10
    NEXT

    or

    WHILE true
        ' Your instructions go here
    NEXT

This last WHILE example should be used as the main instruction loop of your GarBot so that it will continue to run until the end of the game.

top
language reference



FOR cond TO NEXT

Notes:
- Must end with NEXT
- Conditional operators include
> Greater than
< Less than
= Equal


Example:

    FOR x = 0 TO 10
        FOR y = 0 TO 10
            PRINT "x ", x, " y ", y
        NEXT
    NEXT

top
language reference

------------------------
GOSUB RETURN - Causes program execution to branch to the specified label. Execution will resume from the point of the branch upon RETURN statement

Example:

IF x > 0 THEN 
    PRINT "Before GOSUB"
    GOSUB 100
    PRINT "After GOSUB"
ENDIF

100
    PRINT "Reached GOSUB 100"
    s = SCAN 0 90
    f = s
    WHILE f > 0
        f = FIRE 30 s
        IF f = 0 THEN
            f = FIRE 60 s
        ENDIF
    NEXT
    PRINT "Returning from GOSUB 100"
RETURN

This example would print the following:

Before GOSUB
Reached GOSUB 100
Returning from GOSUB 100
After GOSUB

top
language reference



END - Causes your GarBot to terminate execution. You probably shouldn't use this statement, or if you do, do it at the very end of your program.

top
language reference



Math functions - The following math functions are supported but are not implemented as floating point values at this time, and are therefore of limited use. Values returned as in degrees.
COS - Cosine
SIN - Sine
SQRT - Square Root
TAN - Tangent
ATAN - Arctangent
ASIN - Arc-sine
ACOS - Arc-cosine

Example:

    x = SQRT 9

top
language reference


MIN - Returns the smaller value of two arguments

Example:

    x = POSX()
    x = x + 10
    x = MIN x ARENAX

This example would set x to which ever value is smaller, x or ARENAX

top
language reference


MAX - Returns the larger  value of two arguments

Example:

    x = POSX()
    x = x - 10
    x = MAX x ARENAX

This example would set x to which ever value is larger, x or ARENAX

top
language reference

 


ABS - Returns the absolute value of an argument. In other words, negative values are converted to positive.

Example:

    x = SCAN 80 100 ' for example, scan detects a wall and returns -10
    IF x < 0 THEN
   
     x = ABS x
        DRIVE 90 x
    ENDIF

This example would convert x from -10 to 10, and then drive right up against the southern wall of the arena

top
language reference


RAND - Returns a random value no larger than the argument supplied.

Example

    x = RAND ARENAX

This example would set x to a random value between 0 and ARENAX

top
language reference

 


RTOP - Rectangular To Polar - Converts rectangular coordinates into polar coordinates. Upon return, the two variables passed in to RTOP will contain the angle in the first argument, and the distance in the second argument. Because results are returned in the variables that are passed in, It is required that arguments to RTOP be passed in as variables rather than constants. It is also important to understand that the variables passed in to RTOP will no longer contain their original values, so if they are important to your program, you will have to save those values before calling RTOP.

Example

    x = RAND ARENAX
    y = RAND ARENAY
    RTOP x y
    DRIVE x y

This example establishes an absolute position inside the arena, and then uses RTOP to calculate the required angle and distance from the GarBots current location to the absolute position specified.

top
language reference


PTOR - Polar To Rectangular - Converts polar coordinates into rectangular coordinates. Upon return, the two variables passed in to PTOR will contain the X position in the first argument, and the Y position in the second argument. Because results are returned in the variables that are passed in, It is required that arguments to PTOR be passed in as variables rather than constants. It is also important to understand that the variables passed in to PTOR will no longer contain their original values, so if they are important to your program, you will have to save those values before calling PTOR.

Example

    a = RAND 360
    d = RAND ARENAY
    PTOR a d

PTOR is probably of limited use in GarBots, but is implemented for completeness.

top
language reference



GarBot Functions - The following functions are for controlling your robot

    POSX, POSY
    POWER
    DAMAGE
    DRIVE
    SCAN
    FIRE

 

top


 


POSX - Obtain your X coordinate in the arena
POSY - Obtain your Y coordinate in the arena


Example:

    x = POSX()
    y = POSY()

top
GarBot functions


POWER - Returns the amount of power a GarBot has. 

Example - This example would return how much power a GarBot has

    p = POWER()


top
GarBot functions


DAMAGE - This function should no longer be used, but is maintained for backwards compatibility.

top
GarBot functions


 

DRIVE - Causes your GarBot to move according to specified angle and distance.

Example - The following example would cause your GarBot to move in the Zero direction (East) by 20 miles.

    DRIVE 0 20

top
GarBot functions


 

SCAN - Scans between a specified start and end angle for any opponent GarBots. 

Constraints
- You can scan for a maximum of 90 degrees in any one scan. If needed, the end angle will be adjusted to conform.

Notes:
- The insertion point of all GarBots is the GarBot upper left corner. A scan will only find an opponent GarBot if the opponents insertion point falls within the scan area. While watching this can be deceptive since a GarBot who gets part of its visible area scanned will not return a hit unless its insertion point is within the scan.

Example:

    s = SCAN 30 60
    IF s > 0 THEN
        FIRE 45 s
    ENDIF

    REM Note that ELSEIF is not supported

    IF s < 0 THEN
        REM Change direction
    ENDIF

top
GarBot functions


 

FIRE - Fires a shell at a specified angle and distance.

Returns the amount of damage imposed on the target GarBot. The more direct a hit, the more damage is imposed.

Note that there may be more than one GarBot within DAMAGERAD of the explosion (Including the GarBot delivering the shot), and the value returned represents the damage imposed on only one of those GarBots even though all GarBots within DAMAGERAD of the shell will receive damage. A GarBot FIRE-ing can impose damage on itself if it fires at a range less than DAMAGERAD.

Examples:

    f = FIRE 45 s
    FIRE 180 (DAMAGERAD + 10)



top
GarBot functions


 

BATTLE ARENA
Arena - The arena size is defined by the constants ARENAX and ARENAY, with top left representing 0,0 and bottom right representing ARENAX, ARENAY
Angles - Angles are oriented as follows

225    270      315
    \       |       / 
      \     |     /
180 --- o --- 0 (East)
      /     |     \
    /       |       \ 
135      90       45

top



USER INTERFACE
There are four main screens of GarBots. They are:

    Main Screen
    Edit
    Preferences
    Configuration
    Arena
    Log View
    Statistics View
    Debugger

top


Main Screen - Prepare for battle

This screen has a table displaying all of your GarBots, with some extra information. 

    Table Columns

    Other controls

    Menu

        File

        View

        Setup

        Help

 

top
user interface


Edit Screen - Edit your GarBot code.

    Shift Indicator / Line number / Cut / Copy / Paste / Undo / Toggle Bookmark / Goto Bookmark / Insert Tab / Close

    For detailed description, open the editor, and navigate the menu system to Help / Toolbar  

 

top
user interface

 


Preferences - There are several preferences you can set - Menu Setup / Preferences

Small Editor Font - Just as it says, the editor uses a small font, allowing you to see more of your code at one time.

Collect Battle Stats - When checked, statistics will be collected for battles. After a battle is over, navigate the menu to View / Stats to view the statistics.

Wandering Drones - When checked, drones will wander aimlessly around the arena, providing a slightly greater challenge.

Battle Time Limit - Zero here indicates no time limit is imposed. Values of between 1 and 255 indicate how many minutes a battle should last in the event that there is no 'last GarBot standing'

 

top
user interface

 


Configuration - After pressing the 'Lets get it on' button, you will have a chance to configure certain aspects of the battle. In fact, by tapping on the screen at any time during a battle, you have a change to make changes to the configuration. (Available only from the battle field screen, at the start of a battle or by taping the screen during a battle)

Popup kill message - During a battle, a message will popup notifying the user of a kill only if this checkbox is checked.

Disable Auto Off - Blocks the device  auto off feature. Allows you to watch the match without the device turning off. This always defaults to off since it can drain your devices power if left unattended. Note that if you have Popup kill message checked, then the device might turn off while a popup is open

Power transfer - If checked, GarBots will gain in power by the amount of damage the inflict on opponents. A GarBot damaging itself will still lose power.

Battle Speed - Choose an execution speed between 1 and 255. The lower the number, the faster the Battle runs.

DAMAGERAD - This indicates how large of an area an explosion will damage. Any value between 1 and 40 can be used, and the larger the number, the bigger the explosion. But be careful, you can easily wind up getting caught in your own explosion.

SCANRAD - This controls how far ahead a SCAN command can see. Any value between 1 and 150 is valid, and the higher the number, the farther your scans will see.

MAXLIFE - This value controls how much 'life' the GarBots receive when the battle begins. Valid range between 1 and 64000. The higher the value, the more life your GarBots start with. If you change this value in the middle of a battle, all GarBots life will be reset with the new value. Note that due to the Power transfer feature, that a GarBot can actually accumulate more power than specified by MAXLIFE.

top
user interface

 


Arena Screen - This is where the battle takes place.

Upon entering the arena, you will see all the participating GarBots and drone GarBots drawn on the screen and a Dialog box giving the options Go, Cancel, Configure (See Configure section). Pressing the Go button starts the battle. Taping on the screen will give you the choice of terminating the match early, resuming, or Configure..

There is a small area at the bottom of the arena where messages are printed as a result of a PRINT statement in any GarBot source code. 

When the battle ends due to user intervention or because only one GarBot remains standing, the program will return to the Setup Screen 

top
user interface

 


Log View Screen - View the output (PRINT statements) that GarBots produced during a battle, including syntax error messages from the interpreter. Menu - View / Log

The Log View is cleared from the previous battle at the beginning of each battle.

top
user interface

 


Statistics View Screen - View the statistics from a battle. Note that you must enable the collection of statistics by navigating the menu system to Setup / Preferences and toggle the Collect Battle Stats checkbox. Menu - View / Stats

After a battle is complete, navigate the menu to View / Stats to view statistics.

Battle statistics are ranked in the following order:

In the vent of a timeout or a user-quit, the rankings are calculated using the following fields in order of priority.



For example - If, by the end of a timed game, there are two GarBots alive with 2 kills each, Power Remaining is used to decide rank. In the unlikely event that there is still a tie for a rank, Shot-to-hit ratio is used.

The Statistics View is cleared from the previous battle at the beginning of each battle.

top
user interface

 


Debugger - The built in interactive debugger allows you to step through your program, one line at a time, examine values, and even modify values. Menu - Setup / Debugger

 

Setup

    In order to debug a GarBot, you must first set up the debugger. Navigate the menu system to Setup / Debugger. The debugger setup dialog will appear. This dialog consists of a drop down list where you can select the GarBot you want to debug. Note that only GarBots marked as a battle participant will appear in the drop down list.

    Below the drop down list, you will find a checkbox marked Enable Debugger. This checkbox must be checked for debugging to work.

    Finally, a field marked Breakpoint Line allows you to set which line of code you want the debugger to break on during execution. Figure out which line you want to start examining your code, and enter the line number in this field. Remember that in the editor, you can see what line your cursor is on, so you don't have to count lines or anything.

Notes:

 

Debugging

    Having setup the debugger, you can now start the battle. When your GarBots code execution reaches the line you specified, the debugger dialog will popup, pausing the battle. Note that if you set the break point on a line that never gets executed, the debugger dialog will never pop up. Once the debugger dialog pops up, you will notice several buttons.

    Edit field / Watch / Update / Step / Run / Quit / Help

top
user interface