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
(Update with current API reference)
Line 2: Line 2:
 
This page describes the API for the BZRobots Programmable Computer Player Client.
 
This page describes the API for the BZRobots Programmable Computer Player Client.
  
'''Steady State'''
 
The backend has something called a ''steady-state'' - this is basically when the backend is idle, and the tank likewise. Some commands will only work in this steady-state (because they will only make sense when the bot is not doing anything), and if one of these commands are sent when the bot is in ''active-state'' the backend will '''not reply''' until the backend has entered ''steady-state'' (and any commands sent after the first command are queued for handling until the ''blocking'' command has been handled). These commands are marked with "'''Yes'''" in the "Steady-state required?"-column.
 
  
==Available Methods==
+
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:
{| cellspacing="0" border="1"
+
* BZRobot (An easy-to-use robot with a simplified API, e.g. degree units, etc.)
!Method
+
* BZAdvancedRobot (A robot with more advanced features in the API, e.g. radian units, etc.)
!Description
+
* Robot (Similar to BZRobot - for [http://robocode.sourceforge.net/|robocode] compatibility)
!Steady-state required?
+
* 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.
 +
 
 +
 
 +
'''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.''
 +
 
 +
{| cellpadding=4 {{Prettytable}}
 
|-
 
|-
|Execute
+
! colspan=8 {{Hl3}} |==BZRobot Methods==
|Runs a tick of the 'planned actions', and perhaps fires a shot (see SetFire).
+
|'''Yes'''
+
 
|-
 
|-
|GetBattleFieldSize
+
! rowspan=2 {{Hl3}} |'''Method'''
|Gives a 'BattleFieldSize'-reply with the size of the map in "units". (the map is size x size, and coordinates run from -size/2 to size/2)
+
! rowspan=2 {{Hl3}} |'''Description'''
|No
+
! rowspan=2 {{Hl3}} |'''Blocking'''
 +
! colspan=4 {{Hl3}} |'''Available In'''
 +
! rowspan=2 {{Hl3}} |'''Functional'''
 
|-
 
|-
|GetDistanceRemaining
+
| {{Hl3}} |'''BZR'''
|Gives a 'DistanceRemaining'-reply with how much is left of the currently planned movement.
+
| {{Hl3}} |'''BZAR'''
|'''Yes'''
+
| {{Hl3}} |'''R'''
 +
| {{Hl3}} |'''AR'''  
 
|-
 
|-
|GetGunHeat
+
| void ahead(double distance)
|Gives a 'GunHeat'-reply with how many seconds are left of the gun cooldown.
+
| Moves the robot ahead by ''distance''
|'''Yes'''
+
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetHeading
+
| void back(double distance)
|Gives a 'Heading'-reply with heading of the tank.
+
| Moves the robot back by ''distance''  
|'''Yes'''
+
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetHeight
+
| void doNothing()
|Gives a 'Height'-reply with height of the tank.
+
| Does nothing (equivalent of a short sleep)
|No
+
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetLength
+
| void fire()
|Gives a 'Length'-reply with height of the tank.
+
| Fires a single shot
|No
+
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetTickDuration
+
| double getBattleFieldSize()
|Gives a 'TickDuration'-reply with how many seconds makes up one tick.
+
| Returns the size of the battle field
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetTickRemaining
+
| double getGunCoolingRate()
|Gives a 'TickRemaining'-reply with how many seconds are left of this tick.
+
| Returns the time it takes to reload a single shot
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| N
 
|-
 
|-
|GetTurnRemaining
+
| double getGunHeat()
|Gives a 'TurnRemaining'-reply with how much is left of the currently planned turn.
+
| Returns the time until the gun will be ready to fire
|'''Yes'''
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetWidth
+
| double getHeading()
|Gives a 'Width'-reply with width of the tank.
+
| Returns the current heading of the robot
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetX
+
| double getHeight()
|Gives a 'X'-reply with x-coordinate of the tank. (0, 0) is "lower left" corner.
+
| Returns the height (Z-size) of the robot
|'''Yes'''
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetY
+
| double getLength()
|Gives a 'Y'-reply with y-coordinate of the tank. (0, 0) is "lower left" corner.
+
| Returns the length (Y-size) of the robot
|'''Yes'''
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetZ
+
| const char * getName()
|Gives a 'Z'-reply with z-coordinate of the tank. 0 is ground level.
+
| Returns the name (Callsign) of the robot
|'''Yes'''
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|IdentifyFrontend <version>
+
| double getTime()
|Greets the backend. (specifying protocol-version <version>, under development: 0001)
+
| Returns the current game time
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|SetAhead <distance>
+
| double getWidth()
|Sets planned movement (for next 'execute'-s) that moves 'distance' units.
+
| Returns the width (X-size) of the robot
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|SetFire
+
| double getVelocity()
|Sets a planned shot (for next 'execute')
+
| Returns the speed of the robot
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|SetResume
+
| double getX()
|Overwrites and restores the bots current actions (distance and turn) from a previous call to SetStop. This will fail if there are no previous SetStop-calls. Will not restore until you 'execute'. (If you call SetAhead, SetTurn etc before this, they will be overwritten unless SetResume fails)
+
| Returns the current X coordinate of the robot
|'''Yes'''
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|SetStop <overwrite>
+
| double getY()
|Stores and clears the bots current actions (distance and turn). If you've previously called SetStop and not SetResume, this will fail unless you've Set overwrite to true. Does not store & clear until you call 'execute'. (You can call SetAhead, SetTurn etc after this, and they will become the 'new' values, instead of 0.)
+
| Returns the current Y coordinate of the robot
|'''Yes'''
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|SetSpeed <factor>
+
| double getZ()
|Sets next actions speed, value between 0 and 1.0. (for future 'execute'-s)
+
| Returns the current Z coordinate of the robot
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|SetTickDuration <seconds>
+
| void resume()
|Sets the duration of a tick, in seconds.
+
| Resumes any movements saved by a previous call to ''stop''
|No
+
| N
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| N
 
|-
 
|-
|SetTurnLeft <degrees>
+
| void scan()
|Sets planned turn (for next 'execute'-s) that turns 'degrees' degrees to the left.
+
| Prompts a radar scan, resulting in onScannedRobot events
|No
+
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|SetTurnRate <factor>
+
| void stop(bool overwrite = false)
|Sets next actions turnrate, value between 0 and 1.0. (for next 'execute'-s)
+
| Stops the robot, saving any current movements
|No
+
| N
 
+
| Y
|}
+
| Y
 
+
| Y
==Upcoming Methods==
+
| Y
{| cellspacing="0" border="1"
+
| N
!Message syntax
+
!Description
+
!Steady-state required?
+
 
|-
 
|-
|GetConstants
+
| void turnLeft(double degrees)
|<explain>
+
| Turns the robot left ''degrees'' degrees
|No
+
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetFlags
+
| void turnRight(double degrees)
|<explain>
+
| Turns the robot right ''degrees'' degrees
|No
+
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetMyTanks
+
! colspan=7 {{Hl3}} |==BZRobot Event Methods==
|<explain>
+
|No
+
 
|-
 
|-
|GetNumRounds
+
! rowspan=2 {{Hl3}} |'''Method'''
|To be defined (or removed?)
+
! rowspan=2 {{Hl3}} |'''Description'''
|No
+
! rowspan=2 {{Hl3}} |'''Blocking'''
 +
! colspan=4 {{Hl3}} |'''Available In'''
 +
! rowspan=2 {{Hl3}} |'''Functional'''
 
|-
 
|-
|GetObstacles
+
| {{Hl3}} |'''BZR'''
|<explain>
+
| {{Hl3}} |'''BZAR'''
|No
+
| {{Hl3}} |'''R'''
 +
| {{Hl3}} |'''AR'''
 
|-
 
|-
|GetOtherTanks
+
| void onBattleEnded(BattleEndedEvent e)
|<explain>
+
| Called at the end of a league match, or the server shutting down
|No
+
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| N
 
|-
 
|-
|GetRoundNum
+
| void onBulletHit(BulletHitEvent e)
|Returns the number of times the bot has died (or?).
+
| Called when a bullet fired by the robot hits another robot
|No
+
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| N
 
|-
 
|-
|GetShots
+
| void onBulletMissed(BulletMissedEvent e)
|<explain>
+
| Called when a bullet fired by the robot expires or hits a wall
|No
+
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| N
 
|-
 
|-
|GetSpeed
+
| void onDeath(DeathEvent e)
|Returns the current velocity, as per default - or as per last SetSpeed.
+
| Called when a bullet fired by the robot dies
|No
+
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 
|-
 
|-
|GetTeams
+
| void onHitByBullet(HitByBulletEvent e)
|<explain>
+
| Called when the robot is hit by a bullet
|No
+
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| N
 
|-
 
|-
|GetTime
+
| void onHitWall(HitWallEvent e)
|RoboCode: "Returns the game time of the current round, where the time is equal to the current turn in the round." - Will most likely return number of times you've 'execute'-d. Alternatively; return elapsed seconds / tickDuration (but tickDuration can change), or elapsed seconds.
+
| Called when the robot runs into a wall or object
|'''Yes'''
+
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
|-
 +
| void onRobotDeath(RobotDeathEvent e)
 +
| Called when the robot is killed
 +
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
|-
 +
| void onScannedRobot(ScannedRobotEvent e)
 +
| Called each turn as the robot's radar "sees" another robot
 +
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
|-
 +
| void onSpawn(SpawnEvent e)
 +
| Called when the robot spawns
 +
| N/A
 +
| Y
 +
| 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
 +
| Y
 +
| Y
 +
| N
 +
|-
 +
| void onWin(WinEvent e)
 +
| Called when the robot (or it's team) wins a league match
 +
| N/A
 +
| Y
 +
| Y
 +
| Y
 +
| Y
 +
| N
 
|-
 
|-
|GetBases
 
|<explain>
 
|No
 
 
 
|}
 
|}
  

Revision as of 10:17, 14 August 2009

Overview

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


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

  • BZRobot (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.)
  • Robot (Similar to BZRobot - for [2] compatibility)
  • AdvancedRobot (Similar to BZAdvancedRobot - for [3] 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.


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.

==BZRobot Methods==
Method Description Blocking Available In Functional
BZR BZAR R AR
void ahead(double distance) Moves the robot ahead by distance Y Y Y Y Y Y
void back(double distance) Moves the robot back by distance Y Y Y Y Y Y
void doNothing() Does nothing (equivalent of a short sleep) Y Y Y Y Y Y
void fire() Fires a single shot Y Y Y Y Y Y
double getBattleFieldSize() Returns the size of the battle field N Y Y Y Y Y
double getGunCoolingRate() Returns the time it takes to reload a single shot N Y Y Y Y N
double getGunHeat() Returns the time until the gun will be ready to fire N Y Y Y Y Y
double getHeading() Returns the current heading of the robot N Y Y Y Y Y
double getHeight() Returns the height (Z-size) of the robot N Y Y Y Y Y
double getLength() Returns the length (Y-size) of the robot N Y Y Y Y Y
const char * getName() Returns the name (Callsign) of the robot N Y Y Y Y Y
double getTime() Returns the current game time N Y Y Y Y Y
double getWidth() Returns the width (X-size) of the robot N Y Y Y Y Y
double getVelocity() Returns the speed of the robot N Y Y Y Y Y
double getX() Returns the current X coordinate of the robot N Y Y Y Y Y
double getY() Returns the current Y coordinate of the robot N Y Y Y Y Y
double getZ() Returns the current Z coordinate of the robot N Y Y Y Y Y
void resume() Resumes any movements saved by a previous call to stop N Y Y Y Y N
void scan() Prompts a radar scan, resulting in onScannedRobot events Y Y Y Y Y Y
void stop(bool overwrite = false) Stops the robot, saving any current movements N Y Y Y Y N
void turnLeft(double degrees) Turns the robot left degrees degrees Y Y Y Y Y Y
void turnRight(double degrees) Turns the robot right degrees degrees Y Y Y Y Y Y
==BZRobot Event Methods==
Method Description Blocking Available In Functional
BZR BZAR R AR
void onBattleEnded(BattleEndedEvent e) Called at the end of a league match, or the server shutting down N/A Y Y Y Y N
void onBulletHit(BulletHitEvent e) Called when a bullet fired by the robot hits another robot N/A Y Y Y Y N
void onBulletMissed(BulletMissedEvent e) Called when a bullet fired by the robot expires or hits a wall N/A Y Y Y Y N
void onDeath(DeathEvent e) Called when a bullet fired by the robot dies N/A Y Y Y Y Y
void onHitByBullet(HitByBulletEvent e) Called when the robot is hit by a bullet N/A Y Y Y Y N
void onHitWall(HitWallEvent e) Called when the robot runs into a wall or object N/A Y Y Y Y Y
void onRobotDeath(RobotDeathEvent e) Called when the robot is killed N/A Y Y Y Y Y
void onScannedRobot(ScannedRobotEvent e) Called each turn as the robot's radar "sees" another robot N/A Y Y Y Y Y
void onSpawn(SpawnEvent e) Called when the robot spawns N/A Y 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 Y Y N
void onWin(WinEvent e) Called when the robot (or it's team) wins a league match N/A Y Y Y Y N

See Also

BZRobots/Ideas - Ideas for a possible future release