Difference between revisions of "Using robots"
(→The Lua Environment) |
Watusimoto (Talk | contribs) (→The Lua Environment) |
||
| Line 22: | Line 22: | ||
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'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. | + | 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: | For example: | ||
<source lang="lua"> | <source lang="lua"> | ||
| − | |||
| − | |||
| − | |||
| − | |||
function abc() | function abc() | ||
local x -- OK --> Local can be declared in a function | 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 | 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 | ||
| + | |||
</source> | </source> | ||
Revision as of 04:41, 21 September 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.
Contents
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. 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. 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.
