This chapter describes how to use the program itself. If you find it boring to read it through, feel free to use trial and error as usual, and return here if you stumble upon something confusing in the user interface. It is, however, a good idea to read the short section on command line options below. Note also that there is no built-in help in the program - here is where you should search for help.
On the command line, there are two options to set which control the overall behaviour of
RealTimeBattle. Here you can choose the option file, which determines the default values of
the
options. You can also select in which game-mode the program
will run: debug, normal or competition mode.
Usage: RealTimeBattle [options]
Options:
--debug_mode, -d debug mode
--debug_level [0-5], -D sets the initial debug level. implies -d
--normal_mode, -n normal mode (default)
--competition_mode, -c competition mode
--no_graphics, -g no graphics will be displayed
--option_file [file], -o selects option-file (default: $HOME/.rtbrc)
--log_file [file], -l make log file, if 'file' is '-'
the log is sent to STDOUT
--tournament_file [file], -t specify a tournament file to
autostart a tournament
--statistics_file [file], -s file to print the statistics to
when autostarting
--message_file [file], -m redirect messages to 'file'.
'-' as 'file' is equivalent to STDOUT.
If both log and messages are send
to STDOUT, '-m' will be ignored
--replay [file] -r a log file to replay.
if '-' is specified as file,
input is taken from STDIN
--help, -h prints this message
--version, -v prints the version number
--port_number -p specifies the port for remote clients (default is 32134)
The port_number option is only available, if you chose to compile RealTimeBattle with the --enable-network option.
See the INSTALL file for more information.
The differences between the three competition modes are shown in the following
table
| Mode | Debug | Normal | Competition |
| Debug command available | Yes | No | No |
| Pause in game | Yes | Yes | No |
| Step through game | Yes | No | No |
| Robot CPU time unlimited | Yes | Yes | No |
This will start a new tournament. Section Start new tournament window will give more information.
Replay a game. It will ask you to select a log file of the game you want to study.
Pauses the game, in competition-mode the pausing will be postponed until the end of the current game.
Stops the current tournament.
Brings up the options window.
Displays the statistics window.
This box can be used to show and hide the three windows used when a game is running, i.e., the arena window, the score window and the message window.
Terminates the program.
In
debug-mode there is another set of buttons available. They
are intended to help with debugging of robots. Note that you can debug a running process; if you use
gdb the command is gdb robot-name process-number.
In a paused game this will move one time step forward. This is very useful when running the robot in a debugger, since otherwise the robot will be flooded with messages.
This will finish the current game. It has the same effect as a timeout would have.
In debug-mode, you can mark a robot in the score window. That robot will die if you press this button.
Changing debug level is a way of telling robots which messages they should send. The range is between 0 and 5, where 0 means no debugging and 5 is the highest level of debugging, i.e. all debug-messages should be send.
When you are replaying a logfile (not from stdout) there are a number of widgets to control the replaying. See further in the chapter about replaying.
To select robots and arenas for the tournament, mark the files to the
right and press the add button. Selected files are shown to
the left and can be removed correspondingly.
A tournament consists of a number of sequences of games. In each sequence the same robots are playing in all games. Here you select the number of games and sequences as well as the number of robots in each sequence. If you intend to play with all robots every game you are advised to choose only one sequence and instead increase the number of games. The reason is to avoid restarting of the robot processes which can take a while, especially if the number of robots is large.
It is also possible to load a tournament file or save the current tournament. The last tournament played is stored in /tmp/rtb/tmp.tour and is always displayed when this window opens. If it is not available an empty tournament is displayed.
You have to select at least two robots and one arena to be able to start.
In order for the program to find the robots and arenas you have set two options
Robot search path and
Arena search path.
The subdirectories Robots and Arenas in the rtb installl
directory (default: /usr/local/games/RealTimeBattle), specified at compile-time in the
main Makefile, are always searched, regardless of the
options, but if you create a new directory, or if you installed RealTimeBattle in some other
directory, you need to set these options.
This is where the battle takes place. If you want a more detailed view, use the zoom buttons or press +, - or 0. The robots are visualized as coloured circles with an angle shape showing the radar direction, the thick line is the cannon and the thin line points in the front direction.
In this window the robots playing in the current sequence are listed.
Here are messages sent by the robots using Print and Debug displayed. The most recent messages are displayed at the top. You can clean the window and choose to only see new messages from a particular robot.
Here you can change a number of options. In the
Options chapter you can
get detailed information on each option. The changes are not applied until either the apply
button or the OK button is pressed.
You can save your options to a file: Save options will save the options to a file of your
choice and Save as default will save them to .rtbrc in your home directory.
The Default button will reset all options to their default values.
You can study the statistics of the current tournament in some different ways. You can either display
If you want, you can run RealTimeBattle without any graphics at all. This can be
especially useful when currying out a long series of tests or running a competition. To
use this option you have two choices: Either you add the flag -g when
launching the program, or you disable the graphics at compile time (see the
INSTALL file for more information). The latter alternative is useful as the
executable gets smaller and therefore faster on low memory machines. It also enables
you to run RealTimeBattle on machines which haven't got gtk+ installed.
When running without graphics you have to give a tournament file, otherwise nothing at all will happen. It is also a good idea to create a log file and/or a statistics file if you want to know the result.
The tournament file is specified as a command line option. When specified a tournament will automatically begin and end. To save the statistics see section statistics file for more information.
A tournament file consists of five keywords. All of these keywords can be written several times, but keep in mind that only the last one of the keywords that takes a number as argument is counted. All keywords should be followed by a semicolon.
Takes a number or a * as an argument. The
number is how many games should be played per tournament. The asterisk means that the
program takes the exact amount of arenas and uses this as the argument. The default
value is 1.
Takes a number or a * as an argument. The
number is how many robots is playing in each sequence. The asterisk means that the
program takes the exact amount of robots and uses this as the argument. The default
value is 2.
Takes a number or a * as an argument. This
number tells how many sequences shall be played in the tournament. The asterisk means
that the program takes the exact amount of robots and the robots per sequence, does a
binomial calculation to determine the number of sequence for all robots to meet each
other exactly once, and uses this number as the argument. The default value is 1.
Takes one or more robot files as its argument.
Takes one or more arena files as its argument.
File arguments can be one of the following:
This searches the path for the file
Example: Robot: empty.robot
This takes the given file
Example: Arena: /usr/local/games/RealTimeBattle/Arenas/Circle.arena
This searches the whole path and takes all files found.
Example: Arena: *
This searches the specified directory and takes all files found.
Example: Robot: /usr/local/games/RealTimeBattle/Robots/*
It is possible to write files more than one time. So if you want three rotate_and_fire.robot. Just
write rotate_and_fire.robot three times. This is also true for *.
Example tournament file:
R: * Arenas: Circle.arena Square.arena G/S: 2 r/s: 3 Sequences: *
Sometimes it can be useful to
replay a game
and analyze it in detail or just to store for future reference, in this
case log files can be useful. Add the flag -l, when starting
RealTimeBattle, with the filename as argument to enable this feature and
with argument '-', the log is printed to stdout.
The format of the log file is as follows: Each line consist of a letter, determining the type of information, followed by a whitespace-separated list of arguments. The following information is given:
H [games/sequence] [robots/sequence] [sequences] [robots]
A [line from the arena file]
G [sequence number] [game number]
O [option:value]
R [robot id] [x] [y] [cannon angle] [radar angle] [energy]
T [time elapsed]
P [robot id] [message to print]
C [cookie id] [x] [y]
M [mine id] [x] [y]
S [shot id] [x] [y] [dx/dt] [dy/dt]
D [type of object killed] [object id] (if robot: [points received] [position])
You can replay a game from its
log file either
by giving the
command line option
"-r" or from the
control window.
Note that if the log is coming from standard input (command line option
"-r -"), you cannot do much but watch the game, but otherwise
you can influence the flow of the game:
The statistics file is a file used only when a
tournament file is specified. The statistics will be
saved to this file when the tournament ends. Otherwise you can save it by hand using
the save button in the
statistics window.