2009-08-15T06:40:57Z

Bulldozer:

=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 testbot.dll

===Windows: LUA [.lua]===
# cd bzflag
# bzrobots.exe -team red luabot@localhost bots\lua\bzbot.lua

=See Also=
[[BZRobots/API]] - A description the BZRobots API

[[BZRobots/Ideas]] - Community suggestions for and enhancements changes for BZRobots

[[BZRobots/RoboCode_Changes]] - For those coming from RoboCode, a list of differences between the RoboCode and BZRobots API

[[BZRobots/History]] - Some of the history behind BZRobots

BZRobots/API

2009-08-14T10:25:47Z

Bulldozer: fixed links

BZRobots/API

2009-08-14T10:21:52Z

Bulldozer: Added Y/N colors

=Overview=
This page describes 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 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 [http://robocode.sourceforge.net/|robocode] compatibility)
* AdvancedRobot (Similar to BZAdvancedRobot - for [http://robocode.sourceforge.net/|robocode] compatibility)

The main control loop is created by overriding the class method ''run'', and then using the methods shown below to control the robot. These control methods fit into two categories 'blocking', and 'non-blocking'. A blocking function, once called, will not return until either the requested action has completed, or the amount of time allotted for a "turn" or "tick" has passed - whichever comes later. Non-blocking functions will return immediately, allowing for additional processing, but their actions do not take effect immediately; rather, they will take place when the ''execute'' method is called. After a blocking function has been called, various "events" that have been generated during that turn may be processed by the various event methods, if they have been overridden.

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

=See Also=

[[BZRobots/Ideas]] - Ideas for a possible future release

2009-08-04T06:10:55Z

Bulldozer: Undo revision 6589 by Bulldozer (Talk)

=Overview=
This page is to collaborate on ideas for the [[BZRobots]] Programmable Computer Player Client

= Implementation ideas =
* [[BZRobots/ShotsAndEnemies]]

= Suggested ideas =
==Scripting==
* Be able to load multiple modules.

==API functions==
* Provide an API for visual targets based on the same rules a player would see.
* Provide global, team, admin, and report chat APIs so bots can communicate just like players, perhaps with some parsing helper functions.
* Have methods to compute travel paths to desired locations, with updates for moving targets.
* Add a getTank(callsign) function

== Input ==
* Allows input of coordinates/properties from stdin, so info from other apps, gps, etc. can be pumped into the bot

= Accepted ideas =
* Add support for getShots() in BZAdvancedRobot - return a list of shots (class Shot)
* Add support for a Shot class
** getPosition(dt) -return position after dt seconds as is assumed
** getType() - normal? gm? laser? ...
** getHeading() - which way is the shot heading?
** getShooter() - who shot it? at least own shots should be distinguished because on no-rico servers we could just throw them away when doing collision forecasts
** unique identifier so that frontend and backend can refer to individual shots: can be composed using player id and shot id
* Add support for getPlayers() in BZAdvancedRobot - return a list of players (class Tank)
* Add support for a Tank class
** getPosition(dt) - return position after dt seconds as is assumed
** getVelocity() - return current velocity
** getAngularVelocity() - return current angular velocity, i.e. how fast it is turning
** getHeading() - which way the bot is heading?
** unique identifier so that frontend and backend can refer to individual shots: can be composed using player id and shot id

= 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)

BZRobots/Ideas

2009-08-04T06:09:47Z

Bulldozer: Removing all content from page

BZRobots/Ideas

2009-08-04T06:03:19Z

Bulldozer: /* Accepted ideas */