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 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.

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

Logging

While logging is invaluable for tracking down problems and optimizing your code, excessive logging will slow your server down. Removing unnecessary logging in production robots is highly recommended!