Dies ist RealTimeBattle.info, hergestellt von Makeinfo Version 4.7 aus
/tmp/linuxdoc-dir-20850/sgmltmp.RealTimeBattle.info.2.

   \input texinfo

RealTimeBattle User Manual, version 1.0.8
*****************************************

     Erik Ouchterlony and Ragnar Ouchterlony, Johannes Nicolai (jonico@users.sourceforge.net)
     4 October 2005

1 Introduction
**************

This is the user manual for RealTimeBattle. Here you should find how to
run the program, how the program works, how to create your own robots
and how to construct arenas.

   RealTimeBattle is a programming game for Unix, in which robots
controlled by programs are fighting each other. The goal is to destroy
the enemies, using the radar to examine the environment and the cannon
to shoot.

   Even though the environment the robots are moving in is fairly
simple, it is far from easy to construct an intelligent robot-program.
RealTimeBattle is constructed to be easy to use, flexible and fast. The
intention is that the program could be used as a test for intelligent
algorithms, as well as just a game to play and enjoy.

   Features include:

   *  Game progresses in real time, with the robot programs running as
     child processes to RealTimeBattle.

   *   The robots communicate with the main program using the standard
     input and output.

   *  Robots can be constructed in almost any programming language.

   *  Up to 120 robots can compete simultaneously.

   *  A simple messaging language is used for communication, which
     makes easy to start constructing robots.

   *  Robots behave like real physical object.

   *  You can create your own arenas.

   *  Highly configurable.

   *  Possibility to plug in external clients.

   *  Basic team support directly integrated in the game, sophisticated
     team play available due to team frameworks.

1.1 More information
====================

More information can be found in the `INSTALL', `AUTHORS', `BUGS',
`TODO', `README', `FAQ' and `ChangeLog' files in the distribution. More
updated information is available on the RealTimeBattle homepage
(http://realtimebattle.sf.net), where you can also find robots, news on
tournaments as well as this manual in different formats.

1.2 Requirements
================

The hardware requirements are very much dependent on what you do.
Running a few robots should be possible to do on any computer on which
GNU/Linux or any other Unixes can be run. The demand on hardware will,
however, grow with the number of robots you want on the battlefield
simultaneously; running 120 advanced robots is certainly demanding for
any personal computer.

   RealTimeBattle is only available on Unix.  It is developed on a
Linux-machine, but it should compile on other Unix dialects too.
Running in Command line options  is currently only possible on
Linux with the '/proc'-directory enabled, because of the need to get
the cpu usage of child processes.

   The only software requirement is gtk+ (http://www.gtk.org), which is
used for the graphical user interface.

1.3 Background
==============

The project started in August 1998. Inspiration came from RobotBattle
(http://www.robotbattle.com/), a very interesting game we used to enjoy
some years earlier. That version of RobotBattle, however, had some
drawbacks: It was only available on Windows and the robots were written
in an own language, which restricts the possibilities to write
intelligent robots. RobotBattle has since then been under development,
but it still lack support for other operative systems.

   We therefore decided to construct a Unix robot programming game,
which makes use of features of a modern OS.

1.4 License
===========

RealTimeBattle is distributed under the GNU General Public License
(http://www.gnu.org/copyleft/gpl.html), in the spirit of the Linux
community. Official versions of RealTimeBattle will be released by the
authors.

   Copyright (C) 1998-2000  Erik Ouchterlony and Ragnar Ouchterlony,
see the `AUTHORS' file for further developers.

   This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

   This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

   You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

1.5 Bug reports
===============

If you find anything in this package which doesn't work, appears
strange, is missing, is spellt wrong or is just confusing, don't
hesitate to send in a bug report to the Sourceforge Bug Tracker
(http://sourceforge.net/tracker/?group_id=561=100561).

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:'
     See Replaying . It will ask you to select a Log files
     of the game you want to study.

`Pause:'
     Pauses the game, in Command line options  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 Command line options  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 Control window  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
     Time options  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 A tournament  consists of a number of A sequence
of A game . 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 Miscellaneous options  and Arena construction .
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 Messages from robots
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  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 `Robot's,

   *  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 options .
When specified a tournament will automatically begin and end. To save
the statistics see section Statistics files  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 Replaying  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 files  either by giving the
Command line options

   `"-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 Miscellaneous options .

   *  Step forward and step backward can be used to study what happens
     in detail. First, however, the game should be Control window
     .

   *  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 files
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 .

3 Structure
***********

In this section we will describe the structure of the program, how the
robots are moving, shooting and controlling the radar, when points are
given and how a tournament is built up.

3.1 Robot motion
================

The robot behaves like a vehicle with wheels, it rolls in the forward
direction with a small Environmental options  and slides
sideways with a much higher Environmental options . The third
slowing down effect is Environmental options , which is applied
in the direction opposite to the robot velocity and is increasing with
speed.

   There are three ways to affect the robot motion, see Messages from robots
, Messages from robots  and Messages from robots
.

   The acceleration is used to increase the robots speed in the
direction the robot faces; you cannot control the speed directly,
acceleration is the only way to get the robot moving.

   By rotating the robot you can make it turn. Note that rotation does
not directly affect the direction of motion, only the direction the
robot is facing. The sliding friction, together with acceleration, will
eventually carry out the actual turning of the robot.

   Braking will increase the roll friction up to a maximal value. This
is when the wheel are locked and the robot is sliding instead of
rolling. Don't forget to release the brake when you want to speed up
again.

3.2 Energy
==========

The robot health is measured by its energy. There are several ways for
the robot to lose energy, it can
   *  be hit by a shot,

   *  collide with another robot or a wall,

   *  spring a mine or

   *  fire a shot.

   However, there is only one possibility to gain energy: to eat a
cookie.

3.3 The radar
=============

The principal method to get information on the surroundings is via the
radar. Every time the robot is updated it will get a Messages to robots
, giving information on the closest object in the current
radar direction, i.e. distance and type of object. If it is a robot,
that robots energy level will be revealed as well.

   Since the radar information is almost all the robot will know about
the environment, it is crucial to make use of it as well as possible.
It is also important to Messages from robots  well, to make it
collect useful data.

3.4 The robots position
=======================

From v1.0.5 of RTB it is possible to get the robots position more
directly. Instead of having to analyze the surroundings with the radar
and find your position from that, you can configure RTB to send the
Messages to robots . The behavior is controlled by the option
Environmental options .

3.5 Shooting
============

Shooting is the number one method to eliminate other robots. In
RealTimeBattle a shot is moving with constant velocity, calculated as
the sum of the robot velocity and the Shot options  in the
direction the cannon is pointing. It will move until it collides with
an object.

   When the shot is fired it is given an energy, which determines the
injuries robots will suffer when hit. The energy is, however, limited;
the Shot options  forbids very low energy shots, e.g. you want
to remove mines. The Shot options  is restricted by the amount
of the robot's current potential shot-energy, which increases with time.

   Shooting is, however, not without any risk, since a firing robot
itself will lose energy, see Shot options .

   If a cookie or mine is hit, it is destroyed, regardless of the
energy of the shot. Therefore you should use a minimal amount of energy
to shoot mines.

   Shots colliding will not immediately be destroyed, instead their
velocities and energies will be superposed, so that if two colliding
shots are traveling in the same direction, their energies will be added
and, in case of a head on collision, their energies will cancel.

3.6 Collisions
==============

Robots are fragile objects, which get damaged by colliding with walls
and other robots. When colliding, the robots act like bouncing balls,
with three factors that influences the behavior, see Robot options
. On the Robot options , the robots are made of different
materials, usually harder and more protective. This can be used to ram
other robots, giving much more damage than it receives.

3.7 Cookies and Mines
=====================

Cookies and mines are essentially equal objects, with the only
difference that robots will gain energy by taking cookies and lose
energy on mines. These objects are randomly placed in the arena during
the game. Their energy and frequency can be controlled with the
Extras options .

3.8 Time
========

As the name of the program indicates, the time used is the real time.
It is entirely up to the robots to respond quickly enough to the events
in the game. The game progresses by calling the update function in
regular intervals. Between these, the robots have to share the
remaining CPU time. To prevent robots from using too much of the
processor, their CPU time is limited in Command line options .
The Time options  give more details.

   The real-timeness can, however, be violated under some
circumstances. You can speed up or slow down the game speed by changing
the Time options  option and there is a method to prevent
disruption of the game , when the system load is too high. If the time
between two updates is longer than the Time options , the game
time will be slown down accordingly.

3.9 A game
==========

At the beginning of a game, the robots are given a random position on
the arena, with random orientation. The radar and the cannon are both
pointing forward and the Shooting  is set to zero. The goal for
the robots is now to survive as long as possible and at the same time
to destroy the other robots. A robot will get one point for each of the
enemy robot it outlives. One extra point is, however, given to all the
participating robots. Robots dying at the same time will share the
points fairly (or in other words, they get half a point for each of the
other dying at the same time).

   A game is finished if either the number of living robots is less than
two or the Time options .

3.10 A sequence
===============

A sequence is a series of games, where the same robots are fighting.
At the beginning of a sequence the robot processes are started. The
number of robots in a sequence is limited to 120, due to the limit of
256 open file descriptors in Linux. For every robot two pipes are
opened as communication channels to the robot.

   Thereafter a Start new tournament window  are played and
finally the robot processes are killed.

3.11 A tournament
=================

A tournament is a collection of sequences.

   The number of robots in a tournament is (theoretically) unlimited.

   Any number of sequences is allowed, but to make the tournament fair,
you should choose a number of sequences, such that all robots will play
the same number of games (i.e. #sequence = #robots per game / GCD(
#robots per game, #robots in the tournament)).

4 Robot construction
********************

This chapter will describe what you need to know in order to build your
own robots. Most important to know is the messaging language, which is
a set of about 35 commands used to communicate with the server program.
It is also instructive to study the example robots in the `Robots/'
directory.

4.1 Reading messages
====================

At the beginning of each sequence the robot processes are launched by
the server program and assigned two pipes, one for input and the other
for output. These are connected to the `stdin' and `stdout', so that
from the robot's point of view, it is communicating with the server via
the standard input and standard output.

   This approach means that the robots can be written in any programming
languages. However, the robot must be able to know when it has received
a new message. To achieve this there are (at least) three different
methods to choose from:

`Standard in blocks:'
     This is the simplest method, when reading from stdin, the program
     is blocked until the next message arrives. You can therefore make
     the program as if there is always a message waiting. The drawback
     is that you cannot do any calculations while waiting for new
     messages.

     To choose the blocking method, send the following robot option `as
     soon as the program is started': cout << "RobotOption " <<
     USE_NON_BLOCKING << " " << 0 << endl; Note that this is strictly
     c++ code. If you don't use c++ just print the given information to
     stdout. endl is equal to 'end of line'.

`Select:'
     Using the Unix libc function `select' makes it possible for the
     robot to have better control over when to look for new messages.
     It enables you, for example, to read all messages available, do
     some calculations, send commands and thereafter wait for more
     messages. To learn more of `select', please read its Unix
     documentation ( e.g. man pages or emacs info ).

     To choose the select method, send the following robot option `as
     soon as the program is started': cout << "RobotOption " <<
     USE_NON_BLOCKING << " " << 1 << endl; Note that this is strictly
     c++ code.

`Signals:'
     If you want, you can tell RealTimeBattle to send the robot a
     signal whenever a new set of messages is sent. This method makes it
     possible for the robot to be continuously updated with information
     from the server program also when the robot is busy doing
     calculations. If you feel you don't know how to use signals, look
     in the Unix documentation to or study other robots to learn more.

     To choose the signal method, send the following robot option `as
     soon as the program is started': cout << "RobotOption " <<
     USE_NON_BLOCKING << " " << 1 << endl; cout << "RobotOption " <<
     SIGNAL << " " << SIGUSR1 << endl; Note that this is strictly c++
     code.

     You can of course choose any signal you want instead of `SIGUSR1'.

   As a help to implement these methods, the robot `rotate_and_fire'
has been written in three different, but functionally equivalent,
versions. Feel free to study and copy to use in your own robots.

   Note that it is not a good idea to do "busy wait", i.e., to
repeatedly look for a message until you get one. This will slow things
down considerably and, worse, in Command line options  the
robot will rapidly run out of CPU-time and die.

4.2 Messagetypes-h
==================

The file `Messagetypes.h' is a good source of information on the
messaging language. It is a c/c++ include file, but you can easily
rewrite it to use with other languages. There you can find listing of
messages, warning types, objects, game options and robot options.

4.3 Cheating
============

Since the battle is progressing in real-time with real processes, it
may be possible to write programs which are 'cheating' in one way or
another. For example by examining other robots or even RealTimeBattle
itself to get more information, by using up a lot of resources to drain
the other robots and so on. This is, of course, not the intended method
to beat opponents, so we try to inhibit it as much as possible.

   In Command line options  robots have limited CPU usage, so
that one robot can't use up all the CPU. It could be possible to fiddle
with this by launching child processes. But since the time used by the
child process will be counted for as soon as the process dies, it
should be very easy to detect if a robot does anything suspicious.

   It is not possible to prevent all ways of cheating within RTB. It is
e.g. permitted to read and write to files, but remember that organizers
of competitions can forbid this if they wish. By setting permissions
and ownerships of the robot executables and directories this can be
done satisfactory.

   It may still be possible to find ways round these restrictions; if
you detect such a way, please send a Bug reports . By the way,
it is up to the organizer of a tournament to make sure that the rules
are followed.

4.4 Messages to robots
======================

`Initialize [first? (int)]'
     This is the very first message the robot will get. If the argument
     is one, it is the first sequence in the tournament and it should
     send Messages from robots  to the server, otherwise it
     should wait for YourName and YourColour messages (see below).

`YourName [name (string)]'
     Current name of the robot, don't change it if you don't have very
     good reasons.

`YourColour [colour (hex)]'
     Current colour of the robot, change it if you find it ugly.  All
     robots in a team will have the same colour.

`GameOption [optionnr (int)] [value (double)]'
     At the beginning of each game the robots will be sent a number of
     settings, which can be useful for the robot. For a complete list
     of these, look in the file Messagetypes-h

     for the `game_option_type' enum. In the Options  you can
     get more detailed information on each option. The Control window
     is also sent as a game option even though it is not in
     the options list.

`GameStarts'
     This message is sent when the game starts (surprise!)

`Radar [distance (double)] [observed object type (int)] [radar angle (double)]'
     This message gives information from the radar each turn. Remember
     that the radar-angle is relative to the robot front; it is given in
     radians.

`Info [time (double)] [speed (double)] [cannon angle (double)]'
     The `Info' message does always follow the `Radar' message. It
     gives more general information on the state of the robot.  The
     time is the game-time elapsed since the start of the game. This is
     not necessarily the same as the real time elapsed, due to
     Time options  and Time options .

`Coordinates [x (double)] [y (double)] [angle (double)]'
     Tells you the current robot position. It is only sent if the option
     Environmental options  is 1 or 2. If it is 1 the
     coordinates are sent relative the starting position, which has the
     effect that the robot doesn't know where it is starting, but only
     where it has moved since.

`RobotInfo [energy level (double)] [teammate? (int)]'
     If you detect a robot with your radar, this message will follow,
     giving some information on the robot. The opponents energy level
     will be given in the same manner as your own energy (see below).
     The second argument is only interesting in team-mode, 1 means a
     teammate and 0 an enemy.

`RotationReached [what has reached(int)]'
     When the robot option Messages from robots  is set
     appropriately, this message is sent when a rotation (with RotateTo
     or RotateAmount) has finished or the direction has changed (when
     sweeping). The argument corresponds to 'what to rotate' in e.g.
     See Messages from robots .

`Energy [energy level(double)]'
     The end of each round the robot will get to know its energy level.
     It will not, however, get the exact energy, instead it is
     discretized into a number of Robot options .

`RobotsLeft [number of robots (int)]'
     At the beginning of the game and when a robot is killed the number
     of remaining robots is broadcasted to all living robots.

`Collision [colliding object type (int)] [angle relative robot (double)]'
     When a robot hits (or is hit by) something it gets this message.
     In the file Messagetypes-h  you can find a list of the
     object types.  You get the angle from where the collision occurred
     (the angle relative the robot) and the type of object hitting you,
     but not how severe the collision was. This can, however, be
     determined indirectly (approximately) by the loss of energy.

`Warning [warning type (int)] [message (string)]'
     A warning message can be sent when robot has to be notified on
     different problems which have occured. Currently seven different
     warning messages can be sent, namely

     `UNKNOWN_MESSAGE:' The server received a message it couldn't
     recognize.

     `PROCESS_TIME_LOW:' The CPU usage has reached the Time options
     . Only in Command line options .

     `MESSAGE_SENT_IN_ILLEGAL_STATE:' The message received couldn't be
     handled in this state of the program. For example Messages from robots
     is sent before the game has started.

     `UNKNOWN_OPTION:' The robot sent a Messages from robots
     with either illegal option name or illegal argument to that option.

     `OBSOLETE_KEYWORD:' The keyword sent is obsolete and should not be
     used any more, see the `ChangeLog' file for information on what to
     use instead.

     `NAME_NOT_GIVEN:' The robot has not sent its name before the game
     begins. This happens if the Time options  is too short or
     the robot does not send its name early enough.

     `COLOUR_NOT_GIVEN:' The robot has not sent its colour before the
     game begins.

`Dead'
     Robot died. Do not try to send more messages to the server until
     the end of the game, the server doesn't read them.

`GameFinishes'
     Current game is finished, get prepared for the next!

`ExitRobot'
     Exit from the program immediately! Otherwise it will be killed
     forcefully.

4.5 Messages from robots
========================

When you send messages to RealTimeBattle make shure that they are not
longer than 128 chars, otherwise RealTimeBattle will cut them in two
parts and may report an unknown message.

`RobotOption [option nr (int)] [value (int)]'
     Currently only two options are available:

     `SIGNAL:' Tells the server to send a signal when there is a
     message waiting. The argument will determine which signal. Send
     this message (with argument e.g. SIGUSR1) as soon as you are
     prepared to receive the signal.  Default is 0, which means don't
     send any signals.

     `SEND_SIGNAL:' Tells the server to send SIGUSR1 when there is a
     message waiting. Send this message (with argument 1 (= true)) as
     soon as you are prepared to receive the signal.  Default is false.

     `SEND_ROTATION_REACHED:' If you want the server to send a
     Messages to robots

     message when a rotation is finished, you should set this option.
     With a value of 1, the message is sent when a RotateTo or a
     RotateAmount is finished, with a value of 2, changes in sweep
     direction are also notified. Default is 0, i.e. no messages are
     sent.

     `USE_NON_BLOCKING:' Selects how to Reading messages

     works. This option should be sent exactly once as soon as the
     program starts. Since it should always be given, there is no
     default value.

`Name [name (string)]'
     When receiving the Messages to robots  message with
     argument 1, indicating that this is the first sequence, you should
     send both your name and your colour. If your name ends with the
     string `Team: teamname', you will be in the team `teamname'.  For
     example "Name foo Team: bar" will assign you to the team `bar' and
     your name will be `foo'.  All robots in a team will have the same
     colour and will recognize them over the RobotInfo message.  For a
     more sophisticated possibilities, please take a look onto the
     RealTimeBattle Team Framework (http://rtb-team.sf.net).

`Colour [home colour (hex)] [away colour (hex)]'
     See above. The colours are like normal football shirts, the home
     colour is used unless it is already used. Otherwise the away
     colour or, as a last resort, a non-occupied colour is selected
     randomly.

`Rotate [what to rotate (int)] [angular velocity (double)]'
     Set the angular velocity for the robot, its cannon and/or its
     radar.  Set 'what to rotate' to 1 for robot, 2 for cannon, 4 for
     radar or to a sum of these to rotate more objects at the same
     time. The angular velocity is given in radians per second and is
     limited by Robot options .

`RotateTo [what to rotate (int)] [angular velocity (double)] [end angle (double)]'
     As `Rotate', but will rotate to a given angle. Note that radar and
     cannon angles are relative to the robot angle. You cannot use this
     command to rotate the robot itself, use `RotateAmount' instead!

`RotateAmount [what to rotate (int)] [angular velocity (double)] [angle (double)]'
     As `Rotate', but will rotate relative to the current angle.

`Sweep [what to rotate (int)] [angular velocity (double)] [right angle (double)] [left angle (double)]'
     As `rotate', but sets the radar and/or the cannon (not available
     for the robot itself) in a sweep mode.

`Accelerate [value (double)]'
     Set the robot acceleration.  Value is bounded by Robot options
     .

`Brake [portion (double)]'
     Set the brake. Full brake (portion = 1.0) means that the friction
     in the robot direction is equal to Environmental options .

`Shoot [shot energy (double)]'
     Shoot with the given energy.  See Shot options  give more
     information.

`Print [message (string)]'
     Print message on the Message window .

`Debug [message (string)]'
     Print message on the Message window  if in Command line options
     .

`DebugLine [angle1 (double)] [radius1 (double)] [angle2 (double)] [radius2 (double)]'
     Draw a line direct to the arena. This is only allowed in the
     highest debug level(5), otherwise a Messages to robots  is
     sent. The arguments are the start and end point of the line given
     in polar coordinates relative to the robot.

`DebugCircle [center angle (double)] [center radius (double)] [circle radius (double)]'
     Similar to DebugLine above, but draws a circle.  The first two
     arguments are the angle and radius of the central point of the
     circle relative to the robot. The third argument gives the radius
     of the circle.

5 Options
*********

RealTimeBattle is configurable with a bunch of options, collected in
different groups. The philosophy is to give you full freedom to set up
the game in the way you like. This does mean, however, that some
settings of the options may give bad combination, which can cause
troubles for the program.

5.1 Environmental options
=========================

`Gravitational Constant:'
     The acceleration due to gravitation. It is about 9.8 on the earth.
     An increase will increase the friction, thereby slow down the
     robots.

`Air resistance:'
     As it sounds. Increases with speed.

`Roll friction:'
     The friction in the direction of the robot if not braking.

`Slide friction:'
     The friction orthogonal to the robot direction. Also the maximum
     friction if braking.

`Send robot coordinates:'
     Determines how coordinates are send to the robots. The following
     options are available:
        *  0 - don't send any coordinates (default)

        *  1 - send the coordinates relative the starting position

        *  2 - send absolute coordinates

5.2 Robot options
=================

`Robot max acceleration:'
     Robots are not allowed to accelerate faster than this and ...

`Robot min acceleration:'
     ... slower than this.

`Robot radius:'
     Determines the size of the robot.

`Robot mass:'
     Large robot mass will increase the impact of collisions.

`Robot bounce coefficient:'
     Affects how well the robots will bounce. If zero the robots will
     cling together when colliding, if the value is one they will act
     like perfect billiard balls.

`Robot hardness coefficient:'
     Determines how seriously damaged the robots will be when
     colliding. The lower the value, the softer the material.

`Robot protection coefficient:'
     Influences how well protected the robot is. This factor is to be
     multiplied with the damaging energy to get how much to reduce the
     robot's energy.

`Robot frontszie:'
     The front of the robot is a section with different materials,
     usually harder and more protective, so robots can injure each
     other by ramming.

`Robot front bounce coefficient:'
     See previous four items.

`Robot front hardness coefficient:'
     See previous five items.

`Robot front protection coefficient:'
     See previous six items.

`Robot start energy:'
     The amount of energy the robots will have at the beginning of each
     game.

`Robot max energy:'
     By eating a cookie, the robot can increase its energy; not more
     than this, though.

`Robot max rotate speed:'
     How fast the robot itself may rotate. Unit: radians/s .

`Robot cannon max rotate speed:'
     Maximum cannon rotate speed.  Note that the cannon and the radar
     move relative to the robot, so the actual rotation speed may be
     higher.

`Robot radar max rotate speed:'
     Maximum radar rotate speed.  See note above.

`Robot energy levels:'
     The robot will only know its energy approximately. This will
     decide how many discretation levels will be used.

5.3 Shot options
================

`Shot radius:'
     Size of shots. Should be less than Robot options .

`Shot speed:'
     Shots are moving with this speed in the direction of the cannon
     plus the velocity of the robot.

`Shooting penalty:'
     When shooting the robot itself gets damaged. This is the factor,
     by which the shot energy is multiplied, to get the damaging
     energy. If the number of robots is large, this number is reduced,
     so that you never lose in average by shooting (if you hit).

`Shot min energy:'
     The lowest shot energy allowed. A robot trying to shoot with less
     energy will fail to shoot.

`Shot max potential energy:'
     The robots have a shot energy, which increases with time, but will
     never exceed this value.

`Shot potential energy increase speed:'
     Determines how fast the robots shot energy noted above, will
     increase. Unit: energy/s .

5.4 Extras options
==================

`Cookie max energy:'
     The cookie energy is a random number between cookie max energy and
     cookie min energy.

`Cookie min energy:'
     See above.

`Cookie frequency:'
     The number of cookie per second that will appear in average.

`Cookie radius:'
     Size of cookie.

`Mine max energy:'
     The mine energy is a random number between mine max energy and
     mine min energy.

`Mine min energy:'
     See above.

`Mine frequency:'
     The number of mine per second that will appear in average.

`Mine radius:'
     Size of mine.

`Cookie colour:'
     Cookie colour in hexadecimal red-green-blue form.

`Mine colour:'
     As above.

5.5 Time options
================

`Timeout:'
     This is the longest time a game will take. When the time is up all
     remaining robots are killed, without getting any more points.

`Max timestep:'
     If the computer is temporarily slowed down, the time between
     updates can be to long. Setting this option will make the program
     artificially slow down the clock in those cases and therefore
     violate the realtimeness.

`Time scale:'
     Increasing time scale to more than one means that the game clock
     will go faster than an ordinary clock. Changing this value can be
     usefull if you either want to give the robots more time or if you
     have a fast computer you may want to speed the game up.

`Update interval:'
     This option determines the time between robot updates, i.e., how
     often the robot states are changed. It is not influenced by the
     'Time Scale' and cannot be altered when the program is running.
     The accuracy is 1/100 s (depending of the precision of the system
     that RealTimeBattle is running on).

`Robot startup time:'
     Determines the time between the robot processes are executed and
     the sequence begins. If robots are black and have no name, you may
     need to increase the startup time from the default of one second.
     This can happen if, for example, the robots are many, large or you
     are running on a slow or remote computer.

`Start CPU time:'
     In Command line options  a robot's CPU usage is limited.
     At the beginning of a sequence a robot will get this amount of CPU
     time to spend.

`Extra CPU time:'
     When the start CPU time is spent, the robot will get this amount
     of extra CPU time.

`Extra CPU period:'
     The extra CPU time must last an entire CPU period, otherwise the
     robot will die in the current game.

`CPU warning percentage:'
     When the robot has used up this amount of its CPU time it will
     receive a warning message.

`Process check interval:'
     In Command line options  this will decide how often the
     program will check for CPU usage.

`Logging frequency:'
     To reduce the size of Log files  you can increase this
     option. With this option, see Log files  are only logged every
     n:th Time options .

5.6 Window sizes
================

Here you can set the initial sizes for some windows, namely the
Arena window , the Message window , the Score window
and the Statistics window . You can also set the position for
the first three and the Control window .

5.7 Miscellaneous options
=========================

`Arena scale:'
     Overall scale of the arena. A value of 2 gives double sidelength,
     i.e., a four times larger area.

`Fast forward factor:'
     Determines, when Replaying , the speed when the fast
     forward button or the rewind button is pressed.

`Max robots allowed simultaneously:'
     Allows the user to change the maximum amount of robots allowed in
     a sequence. If there are too many, the system might complain (how
     many depends on the system).

`Background colour:'
     Background colour and ...

`Foreground colour:'
     ... foreground colour for the arena.

`Colour for RTB messages:'
     Colour for the text when RTB sends messages.

`Robot search path:'
     This is a colon-separated list of directories which will be
     searched for robots when a Start new tournament window  is
     started. The subdirectory `Robots' in the rtb install directory
     (default: `/usr/local/games/RealTimeBattle') is always searched.

`Arena search path:'
     Same as above, but for arena files instead of robots. Here the
     subdirectory is `Arenas'.

6 Arena construction
********************

In RealTimeBattle, it is very simple to construct your own arenas. The
language consists of only eleven commands, and there are essentially
four building blocks: line, circle, inner_circle and arc. This is mainly
because of speed reason, for circles and lines it is very easy to check
if a collision has occured. Circle and inner_circle prevents robots
from entering into a circle or getting out of a circle respectively.
The line and the arc stop the robots from entering through the long
side ( the curved for the arc ), but no check is made on the short
side, so you have to put circles at each end of the line to make it a
solid object. The commands `polygon', `closed_polygon' and `poly_curve'
are intended to simplify this procedure, always giving a proper object.

   All angles are by default in radians but can be changed to degrees
by the command `angle_unit degrees'.

   Note that RealTimeBattle does not check whether the arena file gives
a correct arena, it is entirely up to you. However, it will complain if
there are violations to the language rules.

   Arena files should be given the postfix `.arena' and be stored in
the arena directory for RealTimeBattle to find them.

   The `bounce coefficient' and `hardness' argument given to all wall
creating commands, determines the material of the wall. They are both
values between 0 and 1. Harder walls will injure colliding robots more
and higher bounce coefficient make them bounce better.

   You are also encouraged to study the arenas included and learn from
the examples.

6.1 Arena commands
==================

A command consists of the command name and the arguments separated by
whitespace. Be sure to give the right number of arguments!

   In the command list, the arguments are given in square brackets.

`scale [value]'
     This value times the Miscellaneous options

     will give the scale factor, by which all coordinates are
     multiplied. This command must be, if it exists, the very first in
     the file, default is 1.0.

`angle_unit [unit]'
     Switches to the selected angle unit, which can be either of
     `degrees' or `radians'. Default is radians.

`boundary [left] [up] [right] [down]'
     The boundary encloses the area, in which robot, cookies and mines
     are placed. It also determines the visible area in the Arena window
     . This command is required and may only be preceded by
     `scale'.

`inner_circle [bounce] [hardness] [center_x] [center_y] [radius]'
     Robots are limited to the inside of this circle.

`circle [bounce] [hardness] [center_x] [center_y] [radius]'
     Circle shaped wall.

`line [bounce] [hardness] [thickness] [start_x]'
     [start_y] [end_x] [end_y] Creates a line. It only prevents the
     robot from passing through to long side, so remember to put
     circles at the short ends.

`arc [bnc] [hardn] [thickn] [center_x] [ctr_y]'
     [inner_radius] [outer_rds] [angle1] [angle2] An arc is a sector of
     a ring within two angles. Like the line, it needs circles at both
     the ends.

`polygon [bounce] [hardn] [thickn] [number of vertices] ([center_x] [center_y])...'
     This will create a number of circles, connected by lines.

`closed_polygon [bounce] [hardn] [thickn] [number of vertices]'
     ([center_x] [center_y])...  As a `polygon', but the first and the
     last vertices are also connected by a line.

`poly_curve [bnc] [hardn] [thickn] [start_x]'
     [start_y] [dir_x] [dir_y] ([command args ...]) ...  The
     `poly_curve' is the most powerful of the arena commands. It is
     used to build walls with lines and arcs. At each step you have a
     current position and direction, which are affected by the
     subcommands. The last subcommand must be `C' or `Q'.

    `L [length]'
          Draw a line with given length in the current direction.

    `T [angle]'
          Turn the current dircetion.

    `A [angle] [radius]'
          Draw an arc.

    `C'
          Finish by connecting with the starting point.

    `Q'
          Quit.

`exclusion_point [position_x] [position_y]'
     When the arena inside the boundary consists of several separated
     areas, you should exclude all but one by inserting exclusion
     points. All points from which you can draw a straight line to an
     exclusion point without crossing a wall, are considered to be
     outside the arena.