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

BZRobots/API

From BZFlagWiki
Revision as of 18:28, 15 August 2009 by Bulldozer (Talk | contribs) (Overview)

Jump to: navigation, search

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.


If you are new to BZRobots, but have Robocode experience, you may want to take a look at BZRobots/API_BZRobots_vs_Robocode


Unless otherwise specified, all units are in map units (distance), degrees (angles), and seconds (time)

API Methods

Note: As BZRobots currently supports bot scripts written in three different languages, the following is language independent description of the methods available for bot development. Actual usage will vary depending on the language used

==Robot/AdvancedRobot 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 clearAllEvents() Clears the event queue; any events will be disgarded N N Y Y 100%
void execute() Causes any action queued by setAhead, setTurnRight, etc. to take place, ending the "turn" Y N 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%
Bullet *fireBullet() Fires a single shot, returning a reference to the fired shot Y Y Y Y 50%
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 getDistanceRemaining() Returns the distance remaining from a setAhead/setBack N N Y Y 100%
double getTurnRemaining() Returns the distance remaining from a setTurnLeft/setTurnRight N N Y Y 100%
double getEnergy() For robocode compatibly - robot's current "energy" (Always 100) N Y Y Y (*) N/A
double getGunCoolingRate() Returns the time it takes to reload a single shot N Y Y Y (*) 100%
double getGunHeading() For robocode compatibly - robot's gun heading (Always matches robot 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%
int getNumRounds() For robocode compatibly - number of battle rounds (Always 1) N Y Y Y 100%
int getOthers() Returns the number of other robots/tanks currently in the battle N Y Y Y 0%
double getRadarHeading() For robocode compatibly - robot's radar heading (Always matches robot heading) N Y Y Y 100%
int getRoundNum() For robocode compatibly - current battle round (Always 1) N Y Y Y 100%
double getTime() Returns the current game time N Y Y Y (*) 100%
double getVelocity() Returns the speed of the robot (excluding the Z-speed) N Y Y Y 100%
double getWidth() Returns the width (X-size) of the robot 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 setAdjustGunForRobotTurn(bool independent) For robocode compatibly - but has no effect when false N Y Y Y N/A
void setAdjustRadarForGunTurn(bool independent) For robocode compatibly - but has no effect when false N Y Y Y (*) N/A
void setAdjustRadarForRobotTurn(bool independent) For robocode compatibly - but has no effect when false N Y Y Y (*) N/A
void setAhead(double distance) Specifies that the robot should move forward by distance at the next execute() N N Y Y 100%
void setBack(double distance) Specifies that the robot should move backwad by distance at the next execute() N N Y Y 100%
void setFire(double power) Specifies that the robot should fire a bullet of power at the next execute() N N Y Y (*) 100%
Bullet *setFireBullet(double power) Specifies that the robot should fire a bullet of power at the next execute() N N Y Y (*) 50%
void setMaxTurnRate(double maxTurnRate) Sets a limit on the maximum turn rate of the robot at the next execute() N N Y Y 100%
void setMaxVelocity(double maxVelocity) Sets a limit on the maximum speed of the robot at the next execute() N N Y Y 100%
void setResume() Immediately resumes any motion halted by setStop N N Y Y 100%
void setStop(bool overwrite = false) Immediately stops any motion until resumed by setResume N N Y Y 100%
void void setTurnLeft(double degrees) Sets the robot to turn left by degress at the next execute() N N Y Y 100%
void void setTurnRate(double turnRate) Sets the maximum turn rate for the robot at the next execute() N N Y Y (*) 100%
void void setTurnRight(double degrees) Sets the robot to turn right by degress at the next execute() N N Y Y 100%
void stop(bool overwrite = false) Stops the robot, saving any current movements N Y Y Y 100%
void turnGunRight(double degrees) For robocode compatibly - but has no effect N Y Y Y N/A
void turnGunLeft(double degrees) For robocode compatibly - but has no effect N Y Y Y N/A
void turnLeft(double degrees) Turns the robot left degrees degrees Y Y Y Y 100%
void turnRadarRight(double degrees) For robocode compatibly - but has no effect N Y Y Y N/A
void turnRadarLeft(double degrees) For robocode compatibly - but has no effect N Y Y Y N/A
void turnRight(double degrees) Turns the robot right degrees degrees Y Y Y Y 100%
==Robot/AdvancedRobot Event Handlers==
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 Y 10%
void onBulletFired(BulletFiredEvent e) Called when another robot/tank fires a bullet N/A Y Y N/A 10%
void onBulletHit(BulletHitEvent e) Called when a bullet fired by the robot hits another robot N/A Y Y Y 80%
void onBulletHitBullet(BulletHitBulletEvente) For robocode compatibility - will never take place N/A Y Y Y N/A
void onBulletMissed(BulletMissedEvent e) Called when a bullet fired by the robot expires or hits a wall N/A Y Y Y 10%
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 25%
void onHitRobot(HitRobotEvente) For robocode compatibility - will never be called N/A Y Y Y N/A
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 Y 100%
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 N/A 100%
void onStatus(StatusEvent e) Called at the beginning of each "turn", before the main loop is run N/A Y Y Y 20%
void onWin(WinEvent e) Called when the robot (or it's team) wins a league match N/A Y Y Y 10%

See Also