## 2. Usage

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.

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

## 2.2 Control window

New tournament:

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

Replay tournament:

  Replay a game. It will ask you to select a log file of the game you want to study.

Pause:

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

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

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

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

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

## 2.5 Arena window

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.

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

- statistics on individual Robots,
- the result of a game,
- the sequence total or
- the total of the tournament.

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 displayed and pressing it 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 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.

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

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/local/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/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: *`

## 2.12 Log files

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:

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] [position])

## 2.13 Replaying

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 slidebar at the top shows how far the current game has progressed. You can jump wherever you want in the game by dragging the handle.
- Fast forward and rewind work as expected. You can alter the speed by changing the option fast forward factor.
- Step forward and step backward can be used to study what happens in detail. First, however, the game should be paused.
- With the four bottom buttons you can jump between games and sequences.

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