This wiki is archived and useful information is being migrated to the main bzflag.org website

Difference between revisions of "BZRobots/API"

From BZFlagWiki
Jump to: navigation, search
(fixed links)
Line 3: Line 3:
  
  
−
The [[BZRobots]] API is based heavily on the [http://robocode.sourceforge.net/ robocode] project. It is class-based, meaning that a robot is built by extending from one of the following four classes:
+
The [[BZRobots]] API is based heavily on the [http://robocode.sourceforge.net/ robocode] project. It is class-based, meaning that a robot is built by extending from one of the following two classes:
−
* BZRobot (An easy-to-use robot with a simplified API, e.g. degree units, etc.)
+
* Robot (An easy-to-use robot with a simplified API, e.g. degree units, etc.)
−
* BZAdvancedRobot (A robot with more advanced features in the API, e.g. radian units, etc.)
+
* AdvancedRobot (A robot with more advanced features in the API, e.g. radian units, etc.)
−
* Robot (Similar to BZRobot - for [http://robocode.sourceforge.net/ robocode] compatibility)
+
−
* AdvancedRobot (Similar to BZAdvancedRobot - for [http://robocode.sourceforge.net/ robocode] compatibility)
+
  
  
−
The main control loop is created by overriding the class method ''run'', and then using the methods shown below to control the robot. These control methods fit into two categories 'blocking', and 'non-blocking'. A blocking function, once called, will not return until either the requested action has completed, or the amount of time allotted for a "turn" or "tick" has passed - whichever comes later. Non-blocking functions will return immediately, allowing for additional processing, but their actions do not take effect immediately; rather, they will take place when the ''execute'' method is called. After a blocking function has been called, various "events" that have been generated during that turn may be processed by the various event methods, if they have been overridden.
+
The main control loop is created by overriding the class method ''run'', and then using the methods shown below to control the robot. These control methods fit into two categories 'blocking', and 'non-blocking'. A blocking function, once called, will not return until either the requested action has completed, or the amount of time allotted for a "turn" or "tick" has passed - whichever comes later.  
  
 +
Non-blocking functions will return immediately, allowing for additional processing, but their actions do not take effect immediately; rather, they will take place when the ''execute'' method is called. After a blocking function has been called, various "events" that have been generated during that turn may be processed by the various event methods, if they have been overridden.
  
−
'''Note:''' ''As BZRobots currently supports bot scripts written in three different languages, the following is a language independent description of the methods available for bot development.''
+
 
 +
'''Note:''' ''As BZRobots currently supports bot scripts written in three different languages, the following is a C-style, but language independent description of the methods available for bot development.''
  
 
{| cellpadding=4 {{Prettytable}}
 
{| cellpadding=4 {{Prettytable}}
 
|-
 
|-
−
! colspan=8 {{Hl3}} |==BZRobot Methods==  
+
! colspan=7 {{Hl3}} |==BZRobot Methods==  
 
|-
 
|-
−
! rowspan=2 {{Hl3}} |'''Method'''  
+
| {{Hl3}} |'''Method'''  
−
! rowspan=2 {{Hl3}} |'''Description'''  
+
| {{Hl3}} |'''Description'''  
−
! rowspan=2 {{Hl3}} |'''Blocking'''  
+
| {{Hl3}} |'''Blocking'''
−
! colspan=4 {{Hl3}} |'''Available In'''
+
| {{Hl3}} |'''Robot'''
−
! rowspan=2 {{Hl3}} |'''Functional'''  
+
| {{Hl3}} |'''Advanced<br>Robot'''  
−
|-
+
| {{Hl3}} |'''Robocode<br>Compatible'''  
−
| {{Hl3}} |'''BZR'''
+
| {{Hl3}} |'''Functional<br>Status'''  
−
| {{Hl3}} |'''BZAR'''
+
−
| {{Hl3}} |'''R'''
+
−
| {{Hl3}} |'''AR'''  
+
 
|-
 
|-
 
| void ahead(double distance)  
 
| void ahead(double distance)  
Line 36: Line 33:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| void back(double distance)  
 
| void back(double distance)  
Line 45: Line 41:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| void doNothing()
 
| void doNothing()
Line 54: Line 49:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| void fire()
 
| void fire()
Line 63: Line 57:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 +
! bgcolor="#00BB00" | 100%
 +
|-
 +
| double getBattleFieldLength()
 +
| Returns the length of the battle field
 +
! bgcolor="#BB0000" | N
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 +
! bgcolor="#555555" | N/A (*)
 +
! bgcolor="#00BB00" | 100%
 
|-
 
|-
−
| double getBattleFieldSize()
+
| double getBattleFieldWidth()
−
| Returns the size of the battle field
+
| Returns the width of the battle field
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getGunCoolingRate()
 
| double getGunCoolingRate()
Line 80: Line 80:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 +
! bgcolor="#BBBB00" | Y (*)
 +
! bgcolor="#BB0000" | 100%
 +
|-
 +
| double getGunHeading()
 +
| Returns the heading of the gun (Will always be the same as the robot's heading)
 +
! bgcolor="#BB0000" | N
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#BB0000" | N
+
! bgcolor="#00BB00" | Y
 +
! bgcolor="#BB0000" | 100%
 
|-
 
|-
 
| double getGunHeat()
 
| double getGunHeat()
Line 89: Line 96:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y  
+
! bgcolor="#BBBB00" | Y (*)
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getHeading()
 
| double getHeading()
Line 99: Line 105:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getHeight()
 
| double getHeight()
Line 107: Line 112:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#BB0000" | N (*)
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getLength()
 
| double getLength()
Line 116: Line 120:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#555555" | N/A (*)
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
−
| const char * getName()
+
| string getName()
 
| Returns the name (Callsign) of the robot  
 
| Returns the name (Callsign) of the robot  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
Line 126: Line 129:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getTime()
 
| double getTime()
Line 134: Line 136:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y  
+
! bgcolor="#BBBB00" | Y (*)
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getWidth()
 
| double getWidth()
Line 143: Line 144:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y  
+
! bgcolor="#00BB00" | Y (*)
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getVelocity()
 
| double getVelocity()
−
| Returns the speed of the robot  
+
| Returns the speed of the robot (excluding the Z-speed)
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getX()
 
| double getX()
Line 162: Line 161:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getY()
 
| double getY()
Line 171: Line 169:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| double getZ()
 
| double getZ()
Line 180: Line 177:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| void resume()
 
| void resume()
Line 189: Line 185:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#BB0000" | N
+
 
|-
 
|-
 
| void scan()
 
| void scan()
Line 198: Line 193:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| void stop(bool overwrite = false)
 
| void stop(bool overwrite = false)
Line 207: Line 201:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#BB0000" | N
+
 
|-
 
|-
 
| void turnLeft(double degrees)
 
| void turnLeft(double degrees)
Line 216: Line 209:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
 
| void turnRight(double degrees)
 
| void turnRight(double degrees)
Line 225: Line 217:
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#00BB00" | 100%
−
! bgcolor="#00BB00" | Y
+
 
|-
 
|-
−
! colspan=8 {{Hl3}} |==BZRobot Event Methods==
+
| {{Hl3}} |'''Method'''  
−
|-
+
| {{Hl3}} |'''Description'''  
−
! rowspan=2 {{Hl3}} |'''Method'''  
+
| {{Hl3}} |'''Blocking'''
−
! rowspan=2 {{Hl3}} |'''Description'''  
+
| {{Hl3}} |'''Robot'''
−
! rowspan=2 {{Hl3}} |'''Blocking'''  
+
| {{Hl3}} |'''Advanced<br>Robot'''  
−
! colspan=4 {{Hl3}} |'''Available In'''
+
| {{Hl3}} |'''Robocode<br>Compatible'''  
−
! rowspan=2 {{Hl3}} |'''Functional'''  
+
| {{Hl3}} |'''Functional<br>Status'''  
−
|-
+
−
| {{Hl3}} |'''BZR'''
+
−
| {{Hl3}} |'''BZAR'''
+
−
| {{Hl3}} |'''R'''
+
−
| {{Hl3}} |'''AR'''  
+
 
|-
 
|-
 
| void onBattleEnded(BattleEndedEvent e)
 
| void onBattleEnded(BattleEndedEvent e)
 
| Called at the end of a league match, or the server shutting down
 
| Called at the end of a league match, or the server shutting down
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
 +
! bgcolor="#BB0000" | 0%
 
|-
 
|-
 
| void onBulletHit(BulletHitEvent e)
 
| void onBulletHit(BulletHitEvent e)
 
| Called when a bullet fired by the robot hits another robot
 
| Called when a bullet fired by the robot hits another robot
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
 +
! bgcolor="#BB0000" | 0%
 
|-
 
|-
 
| void onBulletMissed(BulletMissedEvent e)
 
| void onBulletMissed(BulletMissedEvent e)
 
| Called when a bullet fired by the robot expires or hits a wall
 
| Called when a bullet fired by the robot expires or hits a wall
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
 +
! bgcolor="#BB0000" | 0%
 
|-
 
|-
 
| void onDeath(DeathEvent e)
 
| void onDeath(DeathEvent e)
−
| Called when a bullet fired by the robot dies
+
| Called when the robot dies
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 +
! bgcolor="#00BB00" | 100%
 
|-
 
|-
 
| void onHitByBullet(HitByBulletEvent e)
 
| void onHitByBullet(HitByBulletEvent e)
 
| Called when the robot is hit by a bullet
 
| Called when the robot is hit by a bullet
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
−
! bgcolor="#00BB00" | Y
+
! bgcolor="#BB0000" | Y  
−
! bgcolor="#00BB00" | Y  
+
! bgcolor="#BB0000" | 0%
−
! bgcolor="#BB0000" | N
+
 
|-
 
|-
 
| void onHitWall(HitWallEvent e)
 
| void onHitWall(HitWallEvent e)
 
| Called when the robot runs into a wall or object
 
| Called when the robot runs into a wall or object
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 +
! bgcolor="#22BB00" | 90%
 
|-
 
|-
 
| void onRobotDeath(RobotDeathEvent e)
 
| void onRobotDeath(RobotDeathEvent e)
 
| Called when the robot is killed
 
| Called when the robot is killed
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 +
! bgcolor="#BB0000" | N
 +
! bgcolor="#BB0000" | 0%
 
|-
 
|-
 
| void onScannedRobot(ScannedRobotEvent e)
 
| void onScannedRobot(ScannedRobotEvent e)
 
| Called each turn as the robot's radar "sees" another robot
 
| Called each turn as the robot's radar "sees" another robot
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 +
! bgcolor="#BBBB00" | Y (*)
 +
! bgcolor="#22BB00" | 90%
 
|-
 
|-
 
| void onSpawn(SpawnEvent e)
 
| void onSpawn(SpawnEvent e)
 
| Called when the robot spawns
 
| Called when the robot spawns
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
Line 324: Line 301:
 
| void onStatus(StatusEvent e)
 
| void onStatus(StatusEvent e)
 
| Called at the beginning of each "turn", before the main loop is run
 
| Called at the beginning of each "turn", before the main loop is run
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
 +
! bgcolor="#BB3300" | 20%
 
|-
 
|-
 
| void onWin(WinEvent e)
 
| void onWin(WinEvent e)
 
| Called when the robot (or it's team) wins a league match
 
| Called when the robot (or it's team) wins a league match
−
! bgcolor="#555555" | N /A  
+
! bgcolor="#555555" | N/A  
−
! bgcolor="#00BB00" | Y
+
−
! bgcolor="#00BB00" | Y
+
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#00BB00" | Y  
 
! bgcolor="#BB0000" | N  
 
! bgcolor="#BB0000" | N  
 +
! bgcolor="#BB0000" | 0%
 
|-
 
|-
 
|}
 
|}

Revision as of 07:11, 15 August 2009

Overview

This page describes the API for the BZRobots Programmable Computer Player Client.


The BZRobots API is based heavily on the robocode project. It is class-based, meaning that a robot is built by extending from one of the following two classes:

  • Robot (An easy-to-use robot with a simplified API, e.g. degree units, etc.)
  • AdvancedRobot (A robot with more advanced features in the API, e.g. radian units, etc.)


The main control loop is created by overriding the class method run, and then using the methods shown below to control the robot. These control methods fit into two categories 'blocking', and 'non-blocking'. A blocking function, once called, will not return until either the requested action has completed, or the amount of time allotted for a "turn" or "tick" has passed - whichever comes later.

Non-blocking functions will return immediately, allowing for additional processing, but their actions do not take effect immediately; rather, they will take place when the execute method is called. After a blocking function has been called, various "events" that have been generated during that turn may be processed by the various event methods, if they have been overridden.


Note: As BZRobots currently supports bot scripts written in three different languages, the following is a C-style, but language independent description of the methods available for bot development.

==BZRobot Methods==
Method Description Blocking Robot Advanced
Robot 		Robocode
Compatible 		Functional
Status
void ahead(double distance) Moves the robot ahead by distance Y Y Y Y 100%
void back(double distance) Moves the robot back by distance Y Y Y Y 100%
void doNothing() Does nothing (equivalent of a short sleep) Y Y Y Y 100%
void fire() Fires a single shot Y Y Y Y 100%
double getBattleFieldLength() Returns the length of the battle field N Y Y N/A (*) 100%
double getBattleFieldWidth() Returns the width of the battle field N Y Y Y 100%
double getGunCoolingRate() Returns the time it takes to reload a single shot N Y Y Y (*) 100%
double getGunHeading() Returns the heading of the gun (Will always be the same as the robot's heading) N Y Y Y 100%
double getGunHeat() Returns the time until the gun will be ready to fire N Y Y Y (*) 100%
double getHeading() Returns the current heading of the robot N Y Y Y 100%
double getHeight() Returns the height (Z-size) of the robot N Y Y N (*) 100%
double getLength() Returns the length (Y-size) of the robot N Y Y N/A (*) 100%
string getName() Returns the name (Callsign) of the robot N Y Y Y 100%
double getTime() Returns the current game time N Y Y Y (*) 100%
double getWidth() Returns the width (X-size) of the robot N Y Y Y (*) 100%
double getVelocity() Returns the speed of the robot (excluding the Z-speed) N Y Y Y 100%
double getX() Returns the current X coordinate of the robot N Y Y Y 100%
double getY() Returns the current Y coordinate of the robot N Y Y Y 100%
double getZ() Returns the current Z coordinate of the robot N Y Y Y 100%
void resume() Resumes any movements saved by a previous call to stop N Y Y Y 100%
void scan() Prompts a radar scan, resulting in onScannedRobot events Y Y Y Y 100%
void stop(bool overwrite = false) Stops the robot, saving any current movements N Y Y Y 100%
void turnLeft(double degrees) Turns the robot left degrees degrees Y Y Y Y 100%
void turnRight(double degrees) Turns the robot right degrees degrees Y Y Y Y 100%
Method Description Blocking Robot Advanced
Robot 		Robocode
Compatible 		Functional
Status
void onBattleEnded(BattleEndedEvent e) Called at the end of a league match, or the server shutting down N/A Y Y N 0%
void onBulletHit(BulletHitEvent e) Called when a bullet fired by the robot hits another robot N/A Y Y N 0%
void onBulletMissed(BulletMissedEvent e) Called when a bullet fired by the robot expires or hits a wall N/A Y Y N 0%
void onDeath(DeathEvent e) Called when the robot dies N/A Y Y Y 100%
void onHitByBullet(HitByBulletEvent e) Called when the robot is hit by a bullet N/A Y Y Y 0%
void onHitWall(HitWallEvent e) Called when the robot runs into a wall or object N/A Y Y Y 90%
void onRobotDeath(RobotDeathEvent e) Called when the robot is killed N/A Y Y N 0%
void onScannedRobot(ScannedRobotEvent e) Called each turn as the robot's radar "sees" another robot N/A Y Y Y (*) 90%
void onSpawn(SpawnEvent e) Called when the robot spawns N/A Y Y Y Y
void onStatus(StatusEvent e) Called at the beginning of each "turn", before the main loop is run N/A Y Y N 20%
void onWin(WinEvent e) Called when the robot (or it's team) wins a league match N/A Y Y N 0%

See Also

BZRobots/Ideas - Ideas for a possible future release

Retrieved from "https://wiki.bzflag.org/index.php?title=BZRobots/API&oldid=6627"