Next Previous Contents

2. Usage

In this chapter it is described 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.

2.1 Command line options

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 determine 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:

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
Robots may start child processes Yes No No
Robot CPU time unlimited Yes Yes No

2.2 Control window

New tournament:

This will start a new tournament. Section Start new tournament window will give more information.

Pause:

Pauses for game, in competition-mode the pausing will be postponed until the end of the current game.

End:

Stops the current tournament.

Options:

Brings up the options window.

Statistics:

Displays the statistics window.

Quit:

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.

Step:

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.

End game:

This will finish the current game. It has the same effect as an timeout would have.

Kill marked robot:

In debug-mode, you can mark a robot in the score window. That robot will die if you press this button.

Debug level:

Changing debug level is a way of telling robots how 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.

2.3 Start new tournament window

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 game. The reason is to avoid restarting of the robot processes which can take a while, especially if the number of robots is large.

You have to select at least two robots and one arena to be able to start.

2.4 Robots and arena directories

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 directory INSTALLDIR (default: /usr/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.

2.5 Arena window

This is where the battle takes place. If you want to watch the game in more detailed, use the zoom buttons!

2.6 Score window

In this window the robots playing in the current sequence are listed.

2.7 Message window

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.

2.8 Options window

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.

2.9 Statistics window

You can study the statistics of the current tournament in some different ways. You can either display

Pressing the arrowed buttons will move you to the first, back one, forward one or to the last element respectively. The middle bar will show what is display and pressing this will update the statistics if the game is in progress. If you are using gtk+1.1.x, it is also possible to sort with respect to different columns by clicking on the corresponding title box.

2.10 Running without graphics

If you want, you can run RealTimeBattle without any graphics at all. This can 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 lounging 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.

2.11 Tournament files

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.

Games/Sequence or g/s:

Takes a number or a * as an argument. The number is how many games should be played per tournament. The star means that the program takes the exact amount of arenas and uses this as the argument. The default value is 1.

Robots/Sequence or r/s:

Takes a number or a * as an argument. The number is how many robots is playing in each sequence. The star means that the program takes the exact amount of robots and uses this as the argument. The default value is 2.

Sequences or seq:

Takes a number or a * as an argument. The number is how many sequences that shall be played in the tournament. The star means that the program takes the exact amount of robots and the robots per sequence do a binomial calculation to determine the number of sequence for all robots to meet each other exactly one time and uses this number as the argument. The default value is 1.

Robots or r:

Takes one or more robot files as its argument.

Arenas or a:

Takes one or more arena files as its argument.

File arguments can be one of the following:

Just the file:

This searches the path for the file

Example: Robot: empty.robot

Full path to the file:

This takes the given file

Example: Arena: /usr/Games/RealTimeBattle/Arenas/Circle.arena

All files in path:

This searches the whole path and takes all files found.

Example: Arena: *

One specific directory:

This searches the specified directory and takes all files found.

Example: Robot: /usr/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: *

2.12 Log files

Sometimes it can be useful to analyze a game 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:

Header:

H [games/sequence] [robots/sequence] [sequences] [robots]

Arena info:

A [line from the arena file]

Game start:

G [sequence number] [game number]

Option:

O [option:value]

List of robot properties:

L [robot id] [robot colour] [robot name]

Robot position info:

R [robot id] [x] [y] [cannon angle] [radar angle] [energy]

Time:

T [time elapsed]

Print message:

P [robot id] [message to print]

Cookie:

C [cookie id] [x] [y]

Mine:

M [mine id] [x] [y]

Shot:

S [shot id] [x] [y] [dx/dt] [dy/dt]

Die:

D [type of object killed] [object id] [if robot: points received]

2.13 Statistics files

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.


Next Previous Contents