Difference between revisions of "Using robots"

Revision as of 22:00, 24 June 2009

Bitfighter robots are written in the Lua scripting language. We are currently using Lua 5.1.

Robots run only on the host machine, and only the admin of that machine can specify which robots run on a given level. While robots do run in a semi-sandboxed environment, it is not secure, so you must take care before running robots that you did not write to ensure they contain no malicious code.

Adding Robots To A Level

To add a robot to a level file, insert a line near the top of the file like this:

Robot <team> <robot file> [parameters]

Bitfighter will look for the robot file in the Robots folder in the Bitfighter install directory. If the file is not found, an error will be written to the logfile (bitfighter.log).

If you specify any optional parameters, they will be loaded into an table called arg, which will be accessible from any of the robot functions. (e.g. arg[1] is the first parameter, arg[2] the second, etc.) You can find examples of this in some of the robots in the Robot Gallery.

If all goes well, the robot will spawn at one of the team's regular spawn-points.

There is currently no mechanism for adding robots via the level editor, but one will be provided in a future release.

Learning Lua

While it is possible to modify and customize existing robots without a deep understanding of Lua, some knowledge of the language would be beneficial. The book Programming In Lua is an excellent resource to get started, and the Lua Reference Manual is a handy companion.

The Lua Environment

Bitfighter's Lua environment is slightly different from what you would experience running Lua from the command line. The math, table, and debug modules are loaded, while the string, io, and require modules are not.

Bitfighter uses a modified version of the 'strict' module. That means that you are required to declare all of your variables before using them, and globals can only be declared in the main body of the robot.

For example:

local x          -- OK --> Declare local variable
global(y)        -- OK --> Declare global variable in main body 
print(z)         -- Error --> use of undeclared variable
 
function abc() 
   local x       -- OK --> Local can be declared in a function
   global(x)     -- Error --> global declared in function
end

The bot Object

robot_helper_functions.lua

Before the robot code is loaded, Bitfighter first loads the file robot_helper_functions.lua. This file can be found in your Bitfighter install folder, and contains various functions and remappings needed to support the robot API. It is required for your robots to operate correctly. It is possible to modify this file to include, for instance, a function that you use regularly, but note that such modifications are NOT supported, and if you corrupt this file, your robots may stop working.

Finding Problems, Logging, Programming Errors

Tracking down programming errors can be frustrating and challenging. To make the process easier, Bitfighter will log any robot errors it encounters to bitfighter.log (after which the robot will terminate itself).

You can add your own informational messages to the log by using the logprint(msg) function. While logging is invaluable for tracking down problems and optimizing your code, excessive logging will slow your server down. Remove any unnecessary logging when you are finished debugging them.

A final mechanism for figuring out what is going on is the use of the globalMsg() and teamMsg() commands. These will print a message to the chat area of the main game window either for all players or just those on the bot's team respectively. Use this mechanism judiciously, because if your bot prints a message every game cycle, those messages will scroll off the screen before you get a chance to read them. Again, be sure to remove your messages when you put your bot into production!

For details on the logprint(), globalMsg(), and teamMsg() commands, click here.