Using robots

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/Removing Robots To A Level

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

/Addbot <team> <robot file> [parameters]

(Use /addbots for more then 1 bot.)

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.

 If you want to remove a bot use /kickbot and this will remove the most recently added bot.

If you use /kickbots it will remove all bots from the game.

(Note there is not a way to remove a certain amount of bots from play yet.)

You can also add bots when you are testing a level in the level editor.

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. Note that any variable not declared with the local keyword will be treated as global.

For example:

function abc() 
   local x       -- OK --> Local can be declared in a function
   y = 20        -- OK --> Global declared in main block
   a = nil       -- Error --> Global declared in function
end
 
local x          -- OK --> Declare local variable "x"
y = 10           -- OK --> Declare global variable "y" in main body 
z = nil          -- OK --> Declare global variable "z", but give it no value
print(z)         -- Error --> Use of undeclared variable

robot_helper_functions.lua

Before the robot code is loaded, Bitfighter first loads the file robot_helper_functions.lua. Files from various functions and remappings are needed to support the robot API. It is required for your robots to operate correctly.

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.