Difference between revisions of "Using robots"

Latest revision as of 06:32, 19 March 2013

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

To specify the team, use the team number. 0 is for team 1, 1 is for team 2, 2 is for team 3, and so on.

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.

Adding robots in a match

• /addbot :: Adds 1 bot. It typically joins the team with less players.
• /addbots # :: Adds multiple bots, you'll have to specify the amount. There does not appear to be a maximum amount, but beware that adding 9000 bots may result in a server crash. Thus, some servers have capped this amount at 10 bots.
• /addbots # s_bot :: s_bot is the default bot, so this command is worthless. However, it's good for understanding commands.
• /addbots # s_bot team :: You can choose to add bots by teams using this command. Type the team name or number (hint: team numbers begin at 0).

Try replacing s_bot with Eliza or orbitbot for a fun surprise!

• /kickbot :: Kicks 1 bot.
• /kickbots :: Kicks all bots.

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

The bot Object

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.