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: Difference between revisions

From BZFlagWiki
Jump to navigation Jump to search
← Older edit
Bulldozer (talk | contribs)
58 edits
Zehra (talk | contribs)
968 edits
→API Methods: completed conversion to templates
 
(7 intermediate revisions by 2 users not shown)
Line 29: Line 29:
  # cd bzflag/src/bzrobots
  # cd bzflag/src/bzrobots
  # ./bzrobots -team red luabot@localhost ../../bots/lua/bzbot.lua
  # ./bzrobots -team red luabot@localhost ../../bots/lua/bzbot.lua


===Windows: Shared Library [.dll]===
===Windows: Shared Library [.dll]===
  # cd bzflag
  # cd bzflag
  # bzrobots.exe -team red dllbot@localhost testbot.dll
  # bzrobots.exe -team red dllbot@localhost TestRobot.dll


===Windows: LUA [.lua]===
===Windows: LUA [.lua]===
  # cd bzflag
  # cd bzflag
  # bzrobots.exe -team red luabot@localhost bots\lua\bzbot.lua
  # bzrobots.exe -team red luabot@localhost bots\lua\bzbot.lua
=Developing Robots=
* [[BZRobots/API]] - A description the BZRobots API
* [[BZRobots/API_BZRobots_vs_Robocode]] - For those coming from RoboCode, a list of differences between the RoboCode and BZRobots


=See Also=
=See Also=
[[BZRobots/API]] - A description the BZRobots API
=BZRobots/Ideas=
This page is to collaborate on ideas for the [[BZRobots]] Programmable Computer Player Client
 
= Suggested ideas =
==API functions==
* Provide an API for visual targets based on the same rules a player would see.
** This would only apply to maps using flags
* Provide global, team, admin, and report chat APIs so bots can communicate just like players, perhaps with some parsing helper functions.


[[BZRobots/API_BZRobots_vs_Robocode]] - For those coming from RoboCode, a list of differences between the RoboCode and BZRobots
== Input ==
* Allows input of coordinates/properties from stdin, so info from other apps, gps, etc. can be pumped into the bot
** What to do when multiple bots are running in the same client?


[[BZRobots/Ideas]] - Community suggestions for and enhancements changes for BZRobots
= Accepted ideas =
==Scripting==
* Be able to load multiple modules.
** A small amount of work in bzrobots client should make this happen
 
= Rejected ideas =
==API functions==
* Have methods to compute travel paths to desired locations, with updates for moving targets.
** (Rejected as it defeats the purpose of BZRobots as an AI learning tool)
* Add a getTank(callsign) function
** (Rejected due because BZRobots now supports the onScannedPlayer event)
 
 
=History=
The BZRobots Programmable Computer Player Client was originally developed by Brigham Young University as a project called [http://bzrc.cs.byu.edu/ BZRC]
 
In 2007 it was further developed by Jørgen Pedersen Tjernø (AKA daxxar) as part of the [[Google_Summer_of_Code#Programmable_Computer_Player_Client|Google Summer of Code]]. Information about his work can be found on his GSoC blog at http://gsoc.daxxar.com
 
This work was continued in 2009 by Mathew Eis (AKA Bulldozer and KingRobot), again as part of  [[Google_Summer_of_Code#Programmable_Computer_Player_Client|Google Summer of Code]].
 
The current BZRobots code can be found in the [[BZFlag_SVN| BZFlag subversion system]] at http://bzflag.svn.sourceforge.net/svnroot/bzflag/trunk/bzflag/src/bzrobots
 
=BZRobots API=
 
The API for the BZRobots Programmable Computer Player Client.
 
 
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:
* 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''
 
{| cellpadding=4 {{Prettytable}}
|-
! colspan=7 {{Hl3}} | ==Robot/AdvancedRobot Methods==
|-
| {{Hl3}} |'''Method'''
| {{Hl3}} |'''Description'''
| {{Hl3}} |'''Blocking''' 
| {{Hl3}} |'''Robot'''
| {{Hl3}} |'''Advanced<br>Robot'''
| {{Hl3}} |'''Robocode<br>Compatible'''
| {{Hl3}} |'''Functional<br>Status'''
|-
| void ahead(double distance)
| Moves the robot ahead by ''distance''
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void back(double distance)
| Moves the robot back by ''distance''
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void clearAllEvents()
| Clears the event queue; any events will be disgarded
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void doNothing()
| Clears the event queue; any events will be disgarded
! {{Red}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void execute()
| Causes any action queued by setAhead, setTurnRight, etc. to take place, ending the "turn"
! {{Green}} | Y
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void fire(double power)
| Fires a single shot
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Green}} | 100%
|-
| Bullet *fireBullet(double power)
| Fires a single shot, returning a reference to the fired shot
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Yellow}} | 50%
|-
| list<Event> getAllEvents()
| Returns a list of all events currently in the queue
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 5%
|-
| double getBattleFieldLength()
| Returns the length of the battle field
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
! {{Green}} | 100%
|-
| double getBattleFieldWidth()
| Returns the width of the battle field
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| list<Event> getBulletHitBulletEvents()
| Returns a list of BulletHitBulletEvent currently in the queue
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 5%
|-
| list<Event> getBulletHitEvents()
| Returns a list of BulletHitEvent currently in the queue
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 5%
|-
| list<Event> getBulletMissedEvents()
| Returns a list of all BulletMissedEvent currently in the queue
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 5%
|-
| double getDistanceRemaining()
| Returns the distance remaining from a setAhead/setBack
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getEnergy()
| For robocode compatibly - robot's current "energy" (Always 16)
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| double getGunCoolingRate()
| Returns the time it takes to reload a single shot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Green}} | 100%
|-
| double getGunHeading()
| For robocode compatibly - robot's gun heading (Always matches robot heading)
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getGunHeadingRadians()
| For robocode compatibly - robot's gun heading (Always matches robot heading)
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getGunHeat()
| Returns the time until the gun will be ready to fire
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Green}} | 100%
|-
| double getGunTurnRemaining()
| For robocode compatibly - (Always returns 0)
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| double getGunTurnRemainingRadians()
| For robocode compatibly - (Always returns 0)
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| double getHeading()
| Returns the current heading of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getHeadingRadians()
| Returns the current heading of the robot in radians
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getHeight()
| Returns the height (Z-size) of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | N
! {{Green}} | 100%
|-
| double getLength()
| Returns the length (Y-size) of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
! {{Green}} | 100%
|-
| string getName()
| Returns the name (Callsign) of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| int getNumRounds()
| For robocode compatibly - number of battle rounds (Always '''1''')
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| int getOthers()
| Returns the number of other robots/tanks currently in the battle
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getRadarHeading()
| For robocode compatibly - robot's radar heading (Always matches robot heading)
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getRadarHeadingRadians()
| For robocode compatibly - robot's radar heading (Always matches robot heading)
! {{Red}} | N
! {{Green}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getRadarTurnRemaining()
| For robocode compatibly - (Always returns 0)
! {{Red}} | N
! {{Green}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| double getRadarTurnRemainingRadians()
| For robocode compatibly - (Always returns 0)
! {{Red}} | N
! {{Green}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| list<Event> getRobotDeathEvents()
| Returns a list of all RobotDeathEvent currently in the queue
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 5%
|-
| int getRoundNum()
| For robocode compatibly - current battle round (Always '''1''')
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| list<Event> getScannedRobotEvents()
| Returns a list of all ScannedRobotEvent currently in the queue
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 5%
|-
| list<Event> getStatusEvents()
| Returns a list of all StatusEvent currently in the queue
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 5%
|-
| double getTime()
| Returns the current game time
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Green}} | 100%
|-
| double getTurnRemaining()
| Returns the distance remaining from a setTurnLeft/setTurnRight
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getTurnRemainingRadians()
| Returns the distance remaining from a setTurnLeft/setTurnRight in radians
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getVelocity()
| Returns the speed of the robot (excluding the Z-speed)
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getWidth()
| Returns the width (X-size) of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getX()
| Returns the current X coordinate of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getY()
| Returns the current Y coordinate of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| double getZ()
| Returns the current Z coordinate of the robot
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| bool isAdjustGunForRobotTurn
| For robocode compatibility - always true
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| bool isAdjustRadarForGunTurn
| For robocode compatibility - always true
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| bool isAdjustRadarForRobotTurn
| For robocode compatibility - always true
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| void resume()
| Resumes any movements saved by a previous call to ''stop''
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void scan()
| Prompts a radar scan, resulting in onScannedRobot events
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void setAdjustGunForRobotTurn(bool independent)
| For robocode compatibly - but has no effect when false
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void setAdjustRadarForGunTurn(bool independent)
| For robocode compatibly - but has no effect when false
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void setAdjustRadarForRobotTurn(bool independent)
| For robocode compatibly - but has no effect when false
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void setAhead(double distance)
| Specifies that the robot should move forward by ''distance'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void setBack(double distance)
| Specifies that the robot should move backwad by ''distance'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void setFire(double power)
| Specifies that the robot should fire a bullet of ''power'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Green}} | 100%
|-
| Bullet *setFireBullet(double power)
| Specifies that the robot should fire a bullet of ''power'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Yellow}} | 50%
|-
| void setMaxTurnRate(double maxTurnRate)
| Sets a limit on the maximum turn rate of the robot at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void setMaxVelocity(double maxVelocity)
| Sets a limit on the maximum speed of the robot at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void setResume()
| Immediately resumes any motion halted by setStop
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void setStop(bool overwrite = false)
| Immediately stops any motion until resumed by setResume
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void void setTurnGunLeft(double degrees)
| For robocode compatablity - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnGunLeftRadians(double radians)
| For robocode compatablity - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnGunRight(double degrees)
| For robocode compatablity - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnGunRightRadians(double radians)
| For robocode compatablity - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnLeft(double degrees)
| Sets the robot to turn left by ''degrees'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void void setTurnLeftRadians(double radians)
| Sets the robot to turn left by ''radians'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void void setTurnRadarLeft(double degrees)
| For robocode compatibility - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnRadarLeftRadians(double radians)
| For robocode compatibility - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnRadarRight(double degrees)
| For robocode compatibility - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnRadarRightRadians(double radians)
| For robocode compatibility - has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void void setTurnRight(double degrees)
| Sets the robot to turn right by ''degrees'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void void setTurnRightRadians(double radians)
| Sets the robot to turn right by ''radians'' at the next execute()
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void stop(bool overwrite = false)
| Stops the robot, saving any current movements
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void turnGunRight(double degrees)
| For robocode compatibly - but has no effect
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void turnGunLeft(double degrees)
| For robocode compatibly - but has no effect
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void turnLeft(double degrees)
| Turns the robot left ''degrees'' degrees
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void turnLeftRadians(double radians)
| Turns the robot left ''radians'' radians
! {{Green}} | Y
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void turnRadarRight(double degrees)
| For robocode compatibly - but has no effect
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void turnRadarLeft(double degrees)
| For robocode compatibly - but has no effect
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void turnRadarLeftRadians(double radians)
| For robocode compatibly - but has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void turnRadarRight(double degrees)
| For robocode compatibly - but has no effect
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void turnRadarRightRadians(double radians)
| For robocode compatibly - but has no effect
! {{Red}} | N
! {{Red}} | N
! {{Green}} | Y
! {{Yellow}} | Y
! {{Grey}} | N/A
|-
| void turnRight(double degrees)
| Turns the robot right ''degrees'' degrees
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void turnRightRadians(double radians)
| Turns the robot right ''radians'' radians
! {{Green}} | Y
! {{Red}} | N
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
! colspan=7 {{Hl3}} | ==Robot/AdvancedRobot Event Handlers==
|-
| {{Hl3}} |'''Method'''
| {{Hl3}} |'''Description'''
| {{Hl3}} |'''Blocking''' 
| {{Hl3}} |'''Robot'''
| {{Hl3}} |'''Advanced<br>Robot'''
| {{Hl3}} |'''Robocode<br>Compatible'''
| {{Hl3}} |'''Functional<br>Status'''
|-
| void onBattleEnded(BattleEndedEvent e)
| Called at the end of a league match, or the server shutting down
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 10%
|-
| void onBulletFired(BulletFiredEvent e)
| Called when another robot/tank fires a bullet
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
! {{Red}} | 10%
|-
| void onBulletHit(BulletHitEvent e)
| Called when a bullet fired by the robot hits another robot
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | 80%
|-
| void onBulletHitBullet(BulletHitBulletEvente)
| For robocode compatibility - will never take place
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| void onBulletMissed(BulletMissedEvent e)
| Called when a bullet fired by the robot expires or hits a wall
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 10%
|-
| void onDeath(DeathEvent e)
| Called when the robot dies
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void onHitByBullet(HitByBulletEvent e)
| Called when the robot is hit by a bullet
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Red}} | 25%
|-
| void onHitRobot(HitRobotEvente)
| For robocode compatibility - will never be called
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
|-
| void onHitWall(HitWallEvent e)
| Called when the robot runs into a wall or object
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! bgcolor="#22BB00" | 90%
|-
| void onRobotDeath(RobotDeathEvent e)
| Called when the robot is killed
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void onScannedRobot(ScannedRobotEvent e)
| Called each turn as the robot's radar "sees" another robot
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 100%
|-
| void onSpawn(SpawnEvent e)
| Called when the robot spawns
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Grey}} | N/A
! {{Green}} | 100%
|-
| void onStatus(StatusEvent e)
| Called at the beginning of each "turn", before the main loop is run
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | Y
! {{Green}} | 95%
|-
| void onWin(WinEvent e)
| Called when the robot (or it's team) wins a league match
! {{Grey}} | N/A
! {{Green}} | Y
! {{Green}} | Y
! {{Yellow}} | Y
! {{Red}} | 10%
|-
|}
 
=See Also=


[[BZRobots/History]] - Some of the history behind BZRobots
* [[BZRobots/API_BZRobots_vs_Robocode]] - Differences between Robocode and BZRobots

Latest revision as of 01:57, 7 December 2025

About BZRobots

(Note that the following information applies to the BZRobots in the upcoming BZFlag 3.0 release)

BZRobots is a programmable computer player client that is compatible with the BZFS server. It is designed to be an artificial intelligence training and development tool that operates under the BZFlag platform.

BZRobots requires that you have already configured and are running an instance of BZFS, that allows one or more bots (using the -botsPerIP setting). Also, BZRobots is a "headless" client (i.e. there are no graphics, it is only text-based), so if you want to watch your bots in action, you will also need to join as an observer or player using the BZFlag client.

Quick Start: Building

Linux/OS X

The BZRobots client (and support for C++ bots) will by default as a standard part of the bzflag trunk build. However, if you want to build Python bots, you will need to run ./configure with the option --enable-bzrobots-python (and of course have the necessary dependencies)

Windows

Open the bzrobots solution, then build the bzrobots and testbot projects.

Quick Start: Running

(Note: This quick start assumes that you will be testing bzrobots from within the build directory, have already run 'autogen.sh', 'configure', and 'make' and have not run 'make install')

Linux/OS X: Shared Library [.so]

(Due to the use of libtool, the binary TestRobot.so is in the .libs directory) 

# cd bzflag/src/bzrobots
# ./bzrobots -team red sobot@localhost .libs/TestRobot.so

Linux/OS X: Python [.py]

# cd bzflag/src/bzrobots
# ln -s .libs/bzrobot_pyext.so ./bzrobot_pyext.so
# ./bzrobots -team red pybot@localhost ../../bots/python/TestRobot.py

Linux/OS X: LUA [.lua]

# cd bzflag/src/bzrobots
# ./bzrobots -team red luabot@localhost ../../bots/lua/bzbot.lua

Windows: Shared Library [.dll]

# cd bzflag
# bzrobots.exe -team red dllbot@localhost TestRobot.dll

Windows: LUA [.lua]

# cd bzflag
# bzrobots.exe -team red luabot@localhost bots\lua\bzbot.lua

Developing Robots

See Also

BZRobots/Ideas

This page is to collaborate on ideas for the BZRobots Programmable Computer Player Client

Suggested ideas

API functions

  • Provide an API for visual targets based on the same rules a player would see.
    • This would only apply to maps using flags
  • Provide global, team, admin, and report chat APIs so bots can communicate just like players, perhaps with some parsing helper functions.

Input

  • Allows input of coordinates/properties from stdin, so info from other apps, gps, etc. can be pumped into the bot
    • What to do when multiple bots are running in the same client?

Accepted ideas

Scripting

  • Be able to load multiple modules.
    • A small amount of work in bzrobots client should make this happen

Rejected ideas

API functions

  • Have methods to compute travel paths to desired locations, with updates for moving targets.
    • (Rejected as it defeats the purpose of BZRobots as an AI learning tool)
  • Add a getTank(callsign) function
    • (Rejected due because BZRobots now supports the onScannedPlayer event)


History

The BZRobots Programmable Computer Player Client was originally developed by Brigham Young University as a project called BZRC

In 2007 it was further developed by Jørgen Pedersen Tjernø (AKA daxxar) as part of the Google Summer of Code. Information about his work can be found on his GSoC blog at http://gsoc.daxxar.com

This work was continued in 2009 by Mathew Eis (AKA Bulldozer and KingRobot), again as part of Google Summer of Code.

The current BZRobots code can be found in the BZFlag subversion system at http://bzflag.svn.sourceforge.net/svnroot/bzflag/trunk/bzflag/src/bzrobots

BZRobots API

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

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