This wiki was in read-only mode for many years, but can now be edited again. A lot of information will need to be updated.
BZRobots/API: Difference between revisions
Jump to navigation
Jump to search
m partial move to templates |
partial move to templates |
||
| Line 1: | Line 1: | ||
=Overview= | =Overview= | ||
This page describes the API for the BZRobots Programmable Computer Player Client. | This page describes the API for the BZRobots Programmable Computer Player Client. | ||
| Line 51: | Line 52: | ||
| void clearAllEvents() | | void clearAllEvents() | ||
| Clears the event queue; any events will be disgarded | | Clears the event queue; any events will be disgarded | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 59: | Line 60: | ||
| void doNothing() | | void doNothing() | ||
| Clears the event queue; any events will be disgarded | | Clears the event queue; any events will be disgarded | ||
! | ! {{Red}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 68: | Line 69: | ||
| Causes any action queued by setAhead, setTurnRight, etc. to take place, ending the "turn" | | Causes any action queued by setAhead, setTurnRight, etc. to take place, ending the "turn" | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 91: | Line 92: | ||
| list<Event> getAllEvents() | | list<Event> getAllEvents() | ||
| Returns a list of all events currently in the queue | | Returns a list of all events currently in the queue | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 5% | ||
|- | |- | ||
| double getBattleFieldLength() | | double getBattleFieldLength() | ||
| Returns the length of the battle field | | Returns the length of the battle field | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 107: | Line 108: | ||
| double getBattleFieldWidth() | | double getBattleFieldWidth() | ||
| Returns the width of the battle field | | Returns the width of the battle field | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 115: | Line 116: | ||
| list<Event> getBulletHitBulletEvents() | | list<Event> getBulletHitBulletEvents() | ||
| Returns a list of BulletHitBulletEvent currently in the queue | | Returns a list of BulletHitBulletEvent currently in the queue | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 5% | ||
|- | |- | ||
| list<Event> getBulletHitEvents() | | list<Event> getBulletHitEvents() | ||
| Returns a list of BulletHitEvent currently in the queue | | Returns a list of BulletHitEvent currently in the queue | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 5% | ||
|- | |- | ||
| list<Event> getBulletMissedEvents() | | list<Event> getBulletMissedEvents() | ||
| Returns a list of all BulletMissedEvent currently in the queue | | Returns a list of all BulletMissedEvent currently in the queue | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 5% | ||
|- | |- | ||
| double getDistanceRemaining() | | double getDistanceRemaining() | ||
| Returns the distance remaining from a setAhead/setBack | | Returns the distance remaining from a setAhead/setBack | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 147: | Line 148: | ||
| double getEnergy() | | double getEnergy() | ||
| For robocode compatibly - robot's current "energy" (Always 16) | | For robocode compatibly - robot's current "energy" (Always 16) | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 155: | Line 156: | ||
| double getGunCoolingRate() | | double getGunCoolingRate() | ||
| Returns the time it takes to reload a single shot | | Returns the time it takes to reload a single shot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 163: | Line 164: | ||
| double getGunHeading() | | double getGunHeading() | ||
| For robocode compatibly - robot's gun heading (Always matches robot heading) | | For robocode compatibly - robot's gun heading (Always matches robot heading) | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 171: | Line 172: | ||
| double getGunHeadingRadians() | | double getGunHeadingRadians() | ||
| For robocode compatibly - robot's gun heading (Always matches robot heading) | | For robocode compatibly - robot's gun heading (Always matches robot heading) | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 179: | Line 180: | ||
| double getGunHeat() | | double getGunHeat() | ||
| Returns the time until the gun will be ready to fire | | Returns the time until the gun will be ready to fire | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 187: | Line 188: | ||
| double getGunTurnRemaining() | | double getGunTurnRemaining() | ||
| For robocode compatibly - (Always returns 0) | | For robocode compatibly - (Always returns 0) | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 195: | Line 196: | ||
| double getGunTurnRemainingRadians() | | double getGunTurnRemainingRadians() | ||
| For robocode compatibly - (Always returns 0) | | For robocode compatibly - (Always returns 0) | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 203: | Line 204: | ||
| double getHeading() | | double getHeading() | ||
| Returns the current heading of the robot | | Returns the current heading of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 211: | Line 212: | ||
| double getHeadingRadians() | | double getHeadingRadians() | ||
| Returns the current heading of the robot in radians | | Returns the current heading of the robot in radians | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 219: | Line 220: | ||
| double getHeight() | | double getHeight() | ||
| Returns the height (Z-size) of the robot | | Returns the height (Z-size) of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | N | ||
! {{Green}} | 100% | ! {{Green}} | 100% | ||
|- | |- | ||
| double getLength() | | double getLength() | ||
| Returns the length (Y-size) of the robot | | Returns the length (Y-size) of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 235: | Line 236: | ||
| string getName() | | string getName() | ||
| Returns the name (Callsign) of the robot | | Returns the name (Callsign) of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 243: | Line 244: | ||
| int getNumRounds() | | int getNumRounds() | ||
| For robocode compatibly - number of battle rounds (Always '''1''') | | For robocode compatibly - number of battle rounds (Always '''1''') | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 251: | Line 252: | ||
| int getOthers() | | int getOthers() | ||
| Returns the number of other robots/tanks currently in the battle | | Returns the number of other robots/tanks currently in the battle | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 259: | Line 260: | ||
| double getRadarHeading() | | double getRadarHeading() | ||
| For robocode compatibly - robot's radar heading (Always matches robot heading) | | For robocode compatibly - robot's radar heading (Always matches robot heading) | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 267: | Line 268: | ||
| double getRadarHeadingRadians() | | double getRadarHeadingRadians() | ||
| For robocode compatibly - robot's radar heading (Always matches robot heading) | | For robocode compatibly - robot's radar heading (Always matches robot heading) | ||
! | ! {{Red}} | N | ||
! {{Green}} | N | ! {{Green}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 275: | Line 276: | ||
| double getRadarTurnRemaining() | | double getRadarTurnRemaining() | ||
| For robocode compatibly - (Always returns 0) | | For robocode compatibly - (Always returns 0) | ||
! | ! {{Red}} | N | ||
! {{Green}} | N | ! {{Green}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 283: | Line 284: | ||
| double getRadarTurnRemainingRadians() | | double getRadarTurnRemainingRadians() | ||
| For robocode compatibly - (Always returns 0) | | For robocode compatibly - (Always returns 0) | ||
! | ! {{Red}} | N | ||
! {{Green}} | N | ! {{Green}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 291: | Line 292: | ||
| list<Event> getRobotDeathEvents() | | list<Event> getRobotDeathEvents() | ||
| Returns a list of all RobotDeathEvent currently in the queue | | Returns a list of all RobotDeathEvent currently in the queue | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 5% | ||
|- | |- | ||
| int getRoundNum() | | int getRoundNum() | ||
| For robocode compatibly - current battle round (Always '''1''') | | For robocode compatibly - current battle round (Always '''1''') | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 307: | Line 308: | ||
| list<Event> getScannedRobotEvents() | | list<Event> getScannedRobotEvents() | ||
| Returns a list of all ScannedRobotEvent currently in the queue | | Returns a list of all ScannedRobotEvent currently in the queue | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 5% | ||
|- | |- | ||
| list<Event> getStatusEvents() | | list<Event> getStatusEvents() | ||
| Returns a list of all StatusEvent currently in the queue | | Returns a list of all StatusEvent currently in the queue | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 5% | ||
|- | |- | ||
| double getTime() | | double getTime() | ||
| Returns the current game time | | Returns the current game time | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 331: | Line 332: | ||
| double getTurnRemaining() | | double getTurnRemaining() | ||
| Returns the distance remaining from a setTurnLeft/setTurnRight | | Returns the distance remaining from a setTurnLeft/setTurnRight | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 339: | Line 340: | ||
| double getTurnRemainingRadians() | | double getTurnRemainingRadians() | ||
| Returns the distance remaining from a setTurnLeft/setTurnRight in radians | | Returns the distance remaining from a setTurnLeft/setTurnRight in radians | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 347: | Line 348: | ||
| double getVelocity() | | double getVelocity() | ||
| Returns the speed of the robot (excluding the Z-speed) | | Returns the speed of the robot (excluding the Z-speed) | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 355: | Line 356: | ||
| double getWidth() | | double getWidth() | ||
| Returns the width (X-size) of the robot | | Returns the width (X-size) of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 363: | Line 364: | ||
| double getX() | | double getX() | ||
| Returns the current X coordinate of the robot | | Returns the current X coordinate of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 371: | Line 372: | ||
| double getY() | | double getY() | ||
| Returns the current Y coordinate of the robot | | Returns the current Y coordinate of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 379: | Line 380: | ||
| double getZ() | | double getZ() | ||
| Returns the current Z coordinate of the robot | | Returns the current Z coordinate of the robot | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 387: | Line 388: | ||
| bool isAdjustGunForRobotTurn | | bool isAdjustGunForRobotTurn | ||
| For robocode compatibility - always true | | For robocode compatibility - always true | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 395: | Line 396: | ||
| bool isAdjustRadarForGunTurn | | bool isAdjustRadarForGunTurn | ||
| For robocode compatibility - always true | | For robocode compatibility - always true | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 403: | Line 404: | ||
| bool isAdjustRadarForRobotTurn | | bool isAdjustRadarForRobotTurn | ||
| For robocode compatibility - always true | | For robocode compatibility - always true | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 411: | Line 412: | ||
| void resume() | | void resume() | ||
| Resumes any movements saved by a previous call to ''stop'' | | Resumes any movements saved by a previous call to ''stop'' | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 427: | Line 428: | ||
| void setAdjustGunForRobotTurn(bool independent) | | void setAdjustGunForRobotTurn(bool independent) | ||
| For robocode compatibly - but has no effect when false | | For robocode compatibly - but has no effect when false | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 435: | Line 436: | ||
| void setAdjustRadarForGunTurn(bool independent) | | void setAdjustRadarForGunTurn(bool independent) | ||
| For robocode compatibly - but has no effect when false | | For robocode compatibly - but has no effect when false | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 443: | Line 444: | ||
| void setAdjustRadarForRobotTurn(bool independent) | | void setAdjustRadarForRobotTurn(bool independent) | ||
| For robocode compatibly - but has no effect when false | | For robocode compatibly - but has no effect when false | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 451: | Line 452: | ||
| void setAhead(double distance) | | void setAhead(double distance) | ||
| Specifies that the robot should move forward by ''distance'' at the next execute() | | Specifies that the robot should move forward by ''distance'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 459: | Line 460: | ||
| void setBack(double distance) | | void setBack(double distance) | ||
| Specifies that the robot should move backwad by ''distance'' at the next execute() | | Specifies that the robot should move backwad by ''distance'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 467: | Line 468: | ||
| void setFire(double power) | | void setFire(double power) | ||
| Specifies that the robot should fire a bullet of ''power'' at the next execute() | | Specifies that the robot should fire a bullet of ''power'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 475: | Line 476: | ||
| Bullet *setFireBullet(double power) | | Bullet *setFireBullet(double power) | ||
| Specifies that the robot should fire a bullet of ''power'' at the next execute() | | Specifies that the robot should fire a bullet of ''power'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 483: | Line 484: | ||
| void setMaxTurnRate(double maxTurnRate) | | void setMaxTurnRate(double maxTurnRate) | ||
| Sets a limit on the maximum turn rate of the robot at the next execute() | | Sets a limit on the maximum turn rate of the robot at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 491: | Line 492: | ||
| void setMaxVelocity(double maxVelocity) | | void setMaxVelocity(double maxVelocity) | ||
| Sets a limit on the maximum speed of the robot at the next execute() | | Sets a limit on the maximum speed of the robot at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 499: | Line 500: | ||
| void setResume() | | void setResume() | ||
| Immediately resumes any motion halted by setStop | | Immediately resumes any motion halted by setStop | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 507: | Line 508: | ||
| void setStop(bool overwrite = false) | | void setStop(bool overwrite = false) | ||
| Immediately stops any motion until resumed by setResume | | Immediately stops any motion until resumed by setResume | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 515: | Line 516: | ||
| void void setTurnGunLeft(double degrees) | | void void setTurnGunLeft(double degrees) | ||
| For robocode compatablity - has no effect | | For robocode compatablity - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 523: | Line 524: | ||
| void void setTurnGunLeftRadians(double radians) | | void void setTurnGunLeftRadians(double radians) | ||
| For robocode compatablity - has no effect | | For robocode compatablity - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 531: | Line 532: | ||
| void void setTurnGunRight(double degrees) | | void void setTurnGunRight(double degrees) | ||
| For robocode compatablity - has no effect | | For robocode compatablity - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 539: | Line 540: | ||
| void void setTurnGunRightRadians(double radians) | | void void setTurnGunRightRadians(double radians) | ||
| For robocode compatablity - has no effect | | For robocode compatablity - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 547: | Line 548: | ||
| void void setTurnLeft(double degrees) | | void void setTurnLeft(double degrees) | ||
| Sets the robot to turn left by ''degrees'' at the next execute() | | Sets the robot to turn left by ''degrees'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 555: | Line 556: | ||
| void void setTurnLeftRadians(double radians) | | void void setTurnLeftRadians(double radians) | ||
| Sets the robot to turn left by ''radians'' at the next execute() | | Sets the robot to turn left by ''radians'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 563: | Line 564: | ||
| void void setTurnRadarLeft(double degrees) | | void void setTurnRadarLeft(double degrees) | ||
| For robocode compatibility - has no effect | | For robocode compatibility - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 571: | Line 572: | ||
| void void setTurnRadarLeftRadians(double radians) | | void void setTurnRadarLeftRadians(double radians) | ||
| For robocode compatibility - has no effect | | For robocode compatibility - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 579: | Line 580: | ||
| void void setTurnRadarRight(double degrees) | | void void setTurnRadarRight(double degrees) | ||
| For robocode compatibility - has no effect | | For robocode compatibility - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 587: | Line 588: | ||
| void void setTurnRadarRightRadians(double radians) | | void void setTurnRadarRightRadians(double radians) | ||
| For robocode compatibility - has no effect | | For robocode compatibility - has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 595: | Line 596: | ||
| void void setTurnRight(double degrees) | | void void setTurnRight(double degrees) | ||
| Sets the robot to turn right by ''degrees'' at the next execute() | | Sets the robot to turn right by ''degrees'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 603: | Line 604: | ||
| void void setTurnRightRadians(double radians) | | void void setTurnRightRadians(double radians) | ||
| Sets the robot to turn right by ''radians'' at the next execute() | | Sets the robot to turn right by ''radians'' at the next execute() | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 611: | Line 612: | ||
| void stop(bool overwrite = false) | | void stop(bool overwrite = false) | ||
| Stops the robot, saving any current movements | | Stops the robot, saving any current movements | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 619: | Line 620: | ||
| void turnGunRight(double degrees) | | void turnGunRight(double degrees) | ||
| For robocode compatibly - but has no effect | | For robocode compatibly - but has no effect | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 627: | Line 628: | ||
| void turnGunLeft(double degrees) | | void turnGunLeft(double degrees) | ||
| For robocode compatibly - but has no effect | | For robocode compatibly - but has no effect | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 644: | Line 645: | ||
| Turns the robot left ''radians'' radians | | Turns the robot left ''radians'' radians | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 651: | Line 652: | ||
| void turnRadarRight(double degrees) | | void turnRadarRight(double degrees) | ||
| For robocode compatibly - but has no effect | | For robocode compatibly - but has no effect | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 659: | Line 660: | ||
| void turnRadarLeft(double degrees) | | void turnRadarLeft(double degrees) | ||
| For robocode compatibly - but has no effect | | For robocode compatibly - but has no effect | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 667: | Line 668: | ||
| void turnRadarLeftRadians(double radians) | | void turnRadarLeftRadians(double radians) | ||
| For robocode compatibly - but has no effect | | For robocode compatibly - but has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 675: | Line 676: | ||
| void turnRadarRight(double degrees) | | void turnRadarRight(double degrees) | ||
| For robocode compatibly - but has no effect | | For robocode compatibly - but has no effect | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 683: | Line 684: | ||
| void turnRadarRightRadians(double radians) | | void turnRadarRightRadians(double radians) | ||
| For robocode compatibly - but has no effect | | For robocode compatibly - but has no effect | ||
! | ! {{Red}} | N | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
| Line 700: | Line 701: | ||
| Turns the robot right ''radians'' radians | | Turns the robot right ''radians'' radians | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | N | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
| Line 721: | Line 722: | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 10% | ||
|- | |- | ||
| void onBulletFired(BulletFiredEvent e) | | void onBulletFired(BulletFiredEvent e) | ||
| Line 729: | Line 730: | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#555555" | N/A | ! bgcolor="#555555" | N/A | ||
! | ! {{Red}} | 10% | ||
|- | |- | ||
| void onBulletHit(BulletHitEvent e) | | void onBulletHit(BulletHitEvent e) | ||
| Line 753: | Line 754: | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 10% | ||
|- | |- | ||
| void onDeath(DeathEvent e) | | void onDeath(DeathEvent e) | ||
| Line 769: | Line 770: | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! | ! {{Red}} | 25% | ||
|- | |- | ||
| void onHitRobot(HitRobotEvente) | | void onHitRobot(HitRobotEvente) | ||
| Line 825: | Line 826: | ||
! {{Green}} | Y | ! {{Green}} | Y | ||
! bgcolor="#BBBB00" | Y | ! bgcolor="#BBBB00" | Y | ||
! | ! {{Red}} | 10% | ||
|- | |- | ||
|} | |} | ||
Revision as of 17:03, 29 November 2025
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 doNothing() | Clears the event queue; any events will be disgarded | Y | Y | 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 fire(double power) | Fires a single shot | Y | Y | Y | Y | 100% |
| Bullet *fireBullet(double power) | Fires a single shot, returning a reference to the fired shot | Y | Y | Y | Y | 50% |
| list<Event> getAllEvents() | Returns a list of all events currently in the queue | N | N | Y | Y | 5% |
| 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% |
| list<Event> getBulletHitBulletEvents() | Returns a list of BulletHitBulletEvent currently in the queue | N | N | Y | Y | 5% |
| list<Event> getBulletHitEvents() | Returns a list of BulletHitEvent currently in the queue | N | N | Y | Y | 5% |
| list<Event> getBulletMissedEvents() | Returns a list of all BulletMissedEvent currently in the queue | N | N | Y | Y | 5% |
| double getDistanceRemaining() | Returns the distance remaining from a setAhead/setBack | N | N | Y | Y | 100% |
| double getEnergy() | For robocode compatibly - robot's current "energy" (Always 16) | 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 getGunHeadingRadians() | For robocode compatibly - robot's gun heading (Always matches robot heading) | N | N | Y | Y | 100% |
| double getGunHeat() | Returns the time until the gun will be ready to fire | N | Y | Y | Y | 100% |
| double getGunTurnRemaining() | For robocode compatibly - (Always returns 0) | N | N | Y | Y | N/A |
| double getGunTurnRemainingRadians() | For robocode compatibly - (Always returns 0) | N | N | Y | Y | N/A |
| double getHeading() | Returns the current heading of the robot | N | Y | Y | Y | 100% |
| double getHeadingRadians() | Returns the current heading of the robot in radians | N | N | 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 | 100% |
| double getRadarHeading() | For robocode compatibly - robot's radar heading (Always matches robot heading) | N | Y | Y | Y | 100% |
| double getRadarHeadingRadians() | For robocode compatibly - robot's radar heading (Always matches robot heading) | N | N | Y | Y | 100% |
| double getRadarTurnRemaining() | For robocode compatibly - (Always returns 0) | N | N | Y | Y | N/A |
| double getRadarTurnRemainingRadians() | For robocode compatibly - (Always returns 0) | N | N | Y | Y | N/A |
| list<Event> getRobotDeathEvents() | Returns a list of all RobotDeathEvent currently in the queue | N | N | Y | Y | 5% |
| int getRoundNum() | For robocode compatibly - current battle round (Always 1) | N | Y | Y | Y | 100% |
| list<Event> getScannedRobotEvents() | Returns a list of all ScannedRobotEvent currently in the queue | N | N | Y | Y | 5% |
| list<Event> getStatusEvents() | Returns a list of all StatusEvent currently in the queue | N | N | Y | Y | 5% |
| double getTime() | Returns the current game time | N | Y | Y | Y | 100% |
| double getTurnRemaining() | Returns the distance remaining from a setTurnLeft/setTurnRight | N | N | Y | Y | 100% |
| double getTurnRemainingRadians() | Returns the distance remaining from a setTurnLeft/setTurnRight in radians | N | N | 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% |
| bool isAdjustGunForRobotTurn | For robocode compatibility - always true | N | N | Y | Y | N/A |
| bool isAdjustRadarForGunTurn | For robocode compatibility - always true | N | N | Y | Y | N/A |
| bool isAdjustRadarForRobotTurn | For robocode compatibility - always true | N | N | Y | Y | N/A |
| 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 setTurnGunLeft(double degrees) | For robocode compatablity - has no effect | N | N | Y | Y | N/A |
| void void setTurnGunLeftRadians(double radians) | For robocode compatablity - has no effect | N | N | Y | Y | N/A |
| void void setTurnGunRight(double degrees) | For robocode compatablity - has no effect | N | N | Y | Y | N/A |
| void void setTurnGunRightRadians(double radians) | For robocode compatablity - has no effect | N | N | Y | Y | N/A |
| void void setTurnLeft(double degrees) | Sets the robot to turn left by degrees at the next execute() | N | N | Y | Y | 100% |
| void void setTurnLeftRadians(double radians) | Sets the robot to turn left by radians at the next execute() | N | N | Y | Y | 100% |
| void void setTurnRadarLeft(double degrees) | For robocode compatibility - has no effect | N | N | Y | Y | N/A |
| void void setTurnRadarLeftRadians(double radians) | For robocode compatibility - has no effect | N | N | Y | Y | N/A |
| void void setTurnRadarRight(double degrees) | For robocode compatibility - has no effect | N | N | Y | Y | N/A |
| void void setTurnRadarRightRadians(double radians) | For robocode compatibility - has no effect | N | N | Y | Y | N/A |
| void void setTurnRight(double degrees) | Sets the robot to turn right by degrees at the next execute() | N | N | Y | Y | 100% |
| void void setTurnRightRadians(double radians) | Sets the robot to turn right by radians 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 turnLeftRadians(double radians) | Turns the robot left radians radians | Y | N | 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 turnRadarLeftRadians(double radians) | For robocode compatibly - but has no effect | N | N | Y | Y | N/A |
| void turnRadarRight(double degrees) | For robocode compatibly - but has no effect | N | Y | Y | Y | N/A |
| void turnRadarRightRadians(double radians) | For robocode compatibly - but has no effect | N | N | Y | Y | N/A |
| void turnRight(double degrees) | Turns the robot right degrees degrees | Y | Y | Y | Y | 100% |
| void turnRightRadians(double radians) | Turns the robot right radians radians | Y | N | 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 | 100% |
| 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 | 95% |
| void onWin(WinEvent e) | Called when the robot (or it's team) wins a league match | N/A | Y | Y | Y | 10% |
See Also
- BZRobots/API_BZRobots_vs_Robocode - Differences between Robocode and BZRobots
- BZRobots/Ideas - Ideas for a possible future release