  RealTimeBattle User Manual, version 1.0.8
  Erik Ouchterlony and Ragnar Ouchterlony, Johannes Nicolai
  (jonico@users.sourceforge.net)
  4 October 2005
  ____________________________________________________________

  Table of Contents


  1. Introduction
     1.1 More information
     1.2 Requirements
     1.3 Background
     1.4 License
     1.5 Bug reports

  2. Usage
     2.1 Command line options
     2.2 Control window
     2.3 Start new tournament window
     2.4 Robots and arena directories
     2.5 Arena window
     2.6 Score window
     2.7 Message window
     2.8 Options window
     2.9 Statistics window
     2.10 Running without graphics
     2.11 Tournament files
     2.12 Log files
     2.13 Replaying
     2.14 Statistics files

  3. Structure
     3.1 Robot motion
     3.2 Energy
     3.3 The radar
     3.4 The robots position
     3.5 Shooting
     3.6 Collisions
     3.7 Cookies and Mines
     3.8 Time
     3.9 A game
     3.10 A sequence
     3.11 A tournament

  4. Robot construction
     4.1 Reading messages
     4.2 Messagetypes.h
     4.3 Cheating
     4.4 Messages to robots
     4.5 Messages from robots

  5. Options
     5.1 Environmental options
     5.2 Robot options
     5.3 Shot options
     5.4 Extras options
     5.5 Time options
     5.6 Window sizes
     5.7 Miscellaneous options

  6. Arena construction
     6.1 Arena commands



  ______________________________________________________________________

  [1m1.  Introduction[0m

  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.


  [1m1.1.  More information[0m

  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.


  [1m1.2.  Requirements[0m

  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
  ``competition-mode'' 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.



  [1m1.3.  Background[0m

  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.


  [1m1.4.  License[0m

  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.


  [1m1.5.  Bug reports[0m

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



  [1m2.  Usage[0m

  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.



  [1m2.1.  Command line options[0m

  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     |
  +----------------------------------+-------+--------+-------------+
  ______________________________________________________________________



  [1m2.2.  Control window[0m


     [1mNew tournament:[0m
        This will start a new tournament. Section ``Start new tournament
        window'' will give more information.


     [1mReplay tournament:[0m
        ``Replay a game''. It will ask you to select a ``log file'' of
        the game you want to study.


     [1mPause:[0m
        Pauses the game, in ``competition-mode'' the pausing will be
        postponed until the end of the current game.


     [1mEnd:[0m
        Stops the current tournament.


     [1mOptions:[0m
        Brings up the ``options window''.


     [1mStatistics:[0m
        Displays the ``statistics window''.


     [1mShow arena window:[0m
        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''.


     [1mQuit:[0m
        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.


     [1mStep:[0m
        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.


     [1mEnd game:[0m
        This will finish the current game. It has the same effect as a
        ``timeout'' would have.


     [1mKill marked robot:[0m
        In debug-mode, you can mark a robot in the ``score window''.
        That robot will die if you press this button.


     [1mDebug level:[0m
        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''.


  [1m2.3.  Start new tournament window[0m

  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.


  [1m2.4.  Robots and arena directories[0m

  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.


  [1m2.5.  Arena window[0m

  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.


  [1m2.6.  Score window[0m

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


  [1m2.7.  Message window[0m

  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.


  [1m2.8.  Options window[0m

  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.


  [1m2.9.  Statistics window[0m

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


    statistics on individual [1mRobot[22ms,

    the result of a [1mgame[22m,

    the [1msequence total [22mor

    the [1mtotal [22mof 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.


  [1m2.10.  Running without graphics[0m

  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.



  [1m2.11.  Tournament files[0m


  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.


     [1mGames/Sequence or g/s:[0m
        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.


     [1mRobots/Sequence or r/s:[0m
        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.


     [1mSequences or seq:[0m
        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.


     [1mRobots or r:[0m
        Takes one or more robot files as its argument.


     [1mArenas or a:[0m
        Takes one or more arena files as its argument.

  File arguments can be one of the following:

     [1mJust the file:[0m
        This searches the path for the file

        Example: Robot: empty.robot


     [1mFull path to the file:[0m
        This takes the given file
        Example: Arena:
        /usr/local/games/RealTimeBattle/Arenas/Circle.arena


     [1mAll files in path:[0m
        This searches the whole path and takes all files found.

        Example: Arena: *


     [1mOne specific directory:[0m
        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: *


  [1m2.12.  Log files[0m

  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:

     [1mHeader:[0m
        H [games/sequence] [robots/sequence] [sequences] [robots]

     [1mArena info:[0m
        A [line from the arena file]

     [1mGame start:[0m
        G [sequence number] [game number]

     [1mOption:[0m
        O [option:value]

     [1mList of robot properties:[0m
        L [robot id] [robot colour] [robot name]

     [1mRobot position info:[0m
        R [robot id] [x] [y] [cannon angle] [radar angle] [energy]

     [1mTime:[0m
        T [time elapsed]

     [1mPrint message:[0m
        P [robot id] [message to print]

     [1mCookie:[0m
        C [cookie id] [x] [y]

     [1mMine:[0m
        M [mine id] [x] [y]
     [1mShot:[0m
        S [shot id] [x] [y] [dx/dt] [dy/dt]

     [1mDie:[0m
        D [type of object killed] [object id] (if robot: [points
        received] [position])


  [1m2.13.  Replaying[0m

  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.



  [1m2.14.  Statistics files[0m

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



  [1m3.  Structure[0m

  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.


  [1m3.1.  Robot motion[0m

  The robot behaves like a vehicle with wheels, it rolls in the forward
  direction with a small ``roll friction'' and slides sideways with a
  much higher ``sliding friction''. The third slowing down effect is
  ``air resistance'', 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, ``acceleration'',
  ``rotation'' and ``braking''.

  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.


  [1m3.2.  Energy[0m

  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.


  [1m3.3.  The radar[0m

  The principal method to get information on the surroundings is via the
  radar. Every time the robot is updated it will get a ``radar
  message'', 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 ``maneuver the radar'' well, to make it
  collect useful data.


  [1m3.4.  The robots position[0m

  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
  ``robot coordinates''. The behavior is controlled by the option ``Send
  robot coordinates''.


  [1m3.5.  Shooting[0m

  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 speed'' 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 ``minimal energy'' forbids very low energy shots, e.g. you want to
  remove mines. The ``maximal energy'' 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, ``proportional to the shot energy''.

  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.


  [1m3.6.  Collisions[0m

  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, ``the bounce
  coefficient, the hardness coefficient and the protection
  coefficient''. On the ``front'', 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.


  [1m3.7.  Cookies and Mines[0m

  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
  ``options''.


  [1m3.8.  Time[0m

  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 ``competition-mode''. The
  ``corresponding 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
  ``timescale'' 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 ``max timestep'', the game time will be
  slown down accordingly.



  [1m3.9.  A game[0m

  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 ``potential shot-energy'' 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 is up''.



  [1m3.10.  A sequence[0m

  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 ``number of games'' are played and finally the robot
  processes are killed.



  [1m3.11.  A tournament[0m

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



  [1m4.  Robot construction[0m

  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.



  [1m4.1.  Reading messages[0m

  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:


     [1mStandard in blocks:[0m
        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
        [4mas[24m [4msoon[24m [4mas[24m [4mthe[24m [4mprogram[24m [4mis[24m [4mstarted[24m:

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


     [1mSelect:[0m
        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 [4mas[0m
        [4msoon[24m [4mas[24m [4mthe[24m [4mprogram[24m [4mis[24m [4mstarted[24m:

        cout << "RobotOption " << USE_NON_BLOCKING << " " << 1 << endl;


     Note that this is strictly c++ code.


     [1mSignals:[0m
        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 [4mas[0m
        [4msoon[24m [4mas[24m [4mthe[24m [4mprogram[24m [4mis[24m [4mstarted[24m:

        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 ``competition-mode'' the robot will
  rapidly run out of CPU-time and die.



  [1m4.2.  Messagetypes.h[0m

  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.


  [1m4.3.  Cheating[0m

  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 ``competition-mode'' 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 report''. By the way, it is up
  to the organizer of a tournament to make sure that the rules are
  followed.



  [1m4.4.  Messages to robots[0m



     [1mInitialize [first? (int)][0m
        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 ``Name and Colour'' to the server, otherwise it
        should wait for YourName and YourColour messages (see below).


     [1mYourName [name (string)][0m
        Current name of the robot, don't change it if you don't have
        very good reasons.



     [1mYourColour [colour (hex)][0m
        Current colour of the robot, change it if you find it ugly.  All
        robots in a team will have the same colour.


     [1mGameOption [optionnr (int)] [value (double)][0m
        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 chapter'' you can get
        more detailed information on each option. The ``debug level'' is
        also sent as a game option even though it is not in the options
        list.


     [1mGameStarts[0m
        This message is sent when the game starts (surprise!)


     [1mRadar [distance (double)] [observed object type (int)] [radar angle[0m
        [1m(double)][0m
        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.
     [1mInfo [time (double)] [speed (double)] [cannon angle (double)][0m
        The [1mInfo [22mmessage does always follow the [1mRadar [22mmessage. 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
        scale'' and ``max timestep''.


     [1mCoordinates [x (double)] [y (double)] [angle (double)][0m
        Tells you the current robot position. It is only sent if the
        option ``Send robot coordinates'' 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.



     [1mRobotInfo [energy level (double)] [teammate? (int)][0m
        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.


     [1mRotationReached [what has reached(int)][0m
        When the robot option ``SEND_ROTATION_REACHED'' 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.  ``Rotate''.


     [1mEnergy [energy level(double)][0m
        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 ``energy levels''.


     [1mRobotsLeft [number of robots (int)][0m
        At the beginning of the game and when a robot is killed the
        number of remaining robots is broadcasted to all living robots.



     [1mCollision [colliding object type (int)] [angle relative robot (dou-[0m
        [1mble)][0m
        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.


     [1mWarning [warning type (int)] [message (string)][0m
        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 ``CPU warning
        percentage''. Only in ``competition-mode''.

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

        UNKNOWN_OPTION: The robot sent a ``robot option'' 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 ``robot startup time'' 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.


     [1mDead[0m
        Robot died. Do not try to send more messages to the server until
        the end of the game, the server doesn't read them.


     [1mGameFinishes[0m
        Current game is finished, get prepared for the next!


     [1mExitRobot[0m
        Exit from the program immediately! Otherwise it will be killed
        forcefully.



  [1m4.5.  Messages from robots[0m

  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.



     [1mRobotOption [option nr (int)] [value (int)][0m
        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
        ``RotationReached'' 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.


     [1mName [name (string)][0m
        When receiving the ``Initialize'' 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>.


     [1mColour [home colour (hex)] [away colour (hex)][0m
        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.


     [1mRotate [what to rotate (int)] [angular velocity (double)][0m
        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 (cannon/radar) max rotate speed''.



     [1mRotateTo [what to rotate (int)] [angular velocity (double)] [end[0m
        [1mangle (double)][0m
        As [1mRotate[22m, 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 [1mRotateAmount[0m
        instead!


     [1mRotateAmount [what to rotate (int)] [angular velocity (double)][0m
        [1m[angle (double)][0m
        As [1mRotate[22m, but will rotate relative to the current angle.



     [1mSweep [what to rotate (int)] [angular velocity (double)] [right[0m
        [1mangle (double)] [left angle (double)][0m
        As [1mrotate[22m, but sets the radar and/or the cannon (not available
        for the robot itself) in a sweep mode.


     [1mAccelerate [value (double)][0m
        Set the robot acceleration.  Value is bounded by ``Robot max/min
        acceleration''.


     [1mBrake [portion (double)][0m
        Set the brake. Full brake (portion = 1.0) means that the
        friction in the robot direction is equal to ``Slide friction''.


     [1mShoot [shot energy (double)][0m
        Shoot with the given energy.  ``The shot options'' give more
        information.
     [1mPrint [message (string)][0m
        Print message on the ``message window''.


     [1mDebug [message (string)][0m
        Print message on the ``message window'' if in ``debug-mode''.


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


     [1mDebugCircle [center angle (double)] [center radius (double)] [cir-[0m
        [1mcle radius (double)][0m
        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.



  [1m5.  Options[0m

  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.



  [1m5.1.  Environmental options[0m



     [1mGravitational Constant:[0m
        The acceleration due to gravitation. It is about 9.8 on the
        earth. An increase will increase the friction, thereby slow down
        the robots.


     [1mAir resistance:[0m
        As it sounds. Increases with speed.


     [1mRoll friction:[0m
        The friction in the direction of the robot if not braking.


     [1mSlide friction:[0m
        The friction orthogonal to the robot direction. Also the maximum
        friction if braking.


     [1mSend robot coordinates:[0m
        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



  [1m5.2.  Robot options[0m



     [1mRobot max acceleration:[0m
        Robots are not allowed to accelerate faster than this and ...


     [1mRobot min acceleration:[0m
        ... slower than this.


     [1mRobot radius:[0m
        Determines the size of the robot.


     [1mRobot mass:[0m
        Large robot mass will increase the impact of collisions.


     [1mRobot bounce coefficient:[0m
        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.


     [1mRobot hardness coefficient:[0m
        Determines how seriously damaged the robots will be when
        colliding. The lower the value, the softer the material.


     [1mRobot protection coefficient:[0m
        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.


     [1mRobot frontszie:[0m
        The front of the robot is a section with different materials,
        usually harder and more protective, so robots can injure each
        other by ramming.


     [1mRobot front bounce coefficient:[0m
        See previous four items.


     [1mRobot front hardness coefficient:[0m
        See previous five items.


     [1mRobot front protection coefficient:[0m
        See previous six items.


     [1mRobot start energy:[0m
        The amount of energy the robots will have at the beginning of
        each game.


     [1mRobot max energy:[0m
        By eating a cookie, the robot can increase its energy; not more
        than this, though.


     [1mRobot max rotate speed:[0m
        How fast the robot itself may rotate. Unit: radians/s .


     [1mRobot cannon max rotate speed:[0m
        Maximum cannon rotate speed.  Note that the cannon and the radar
        move relative to the robot, so the actual rotation speed may be
        higher.


     [1mRobot radar max rotate speed:[0m
        Maximum radar rotate speed.  See note above.


     [1mRobot energy levels:[0m
        The robot will only know its energy approximately. This will
        decide how many discretation levels will be used.



  [1m5.3.  Shot options[0m


     [1mShot radius:[0m
        Size of shots. Should be less than ``robot radius''.


     [1mShot speed:[0m
        Shots are moving with this speed in the direction of the cannon
        plus the velocity of the robot.


     [1mShooting penalty:[0m
        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).


     [1mShot min energy:[0m
        The lowest shot energy allowed. A robot trying to shoot with
        less energy will fail to shoot.


     [1mShot max potential energy:[0m
        The robots have a shot energy, which increases with time, but
        will never exceed this value.


     [1mShot potential energy increase speed:[0m
        Determines how fast the robots shot energy noted above, will
        increase. Unit: energy/s .



  [1m5.4.  Extras options[0m


     [1mCookie max energy:[0m
        The cookie energy is a random number between cookie max energy
        and cookie min energy.


     [1mCookie min energy:[0m
        See above.


     [1mCookie frequency:[0m
        The number of cookie per second that will appear in average.


     [1mCookie radius:[0m
        Size of cookie.


     [1mMine max energy:[0m
        The mine energy is a random number between mine max energy and
        mine min energy.


     [1mMine min energy:[0m
        See above.


     [1mMine frequency:[0m
        The number of mine per second that will appear in average.


     [1mMine radius:[0m
        Size of mine.


     [1mCookie colour:[0m
        Cookie colour in hexadecimal red-green-blue form.


     [1mMine colour:[0m
        As above.



  [1m5.5.  Time options[0m



     [1mTimeout:[0m
        This is the longest time a game will take. When the time is up
        all remaining robots are killed, without getting any more
        points.


     [1mMax timestep:[0m
        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.


     [1mTime scale:[0m
        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.



     [1mUpdate interval:[0m
        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).


     [1mRobot startup time:[0m
        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.


     [1mStart CPU time:[0m
        In ``competition-mode'' a robot's CPU usage is limited. At the
        beginning of a sequence a robot will get this amount of CPU time
        to spend.


     [1mExtra CPU time:[0m
        When the start CPU time is spent, the robot will get this amount
        of extra CPU time.


     [1mExtra CPU period:[0m
        The extra CPU time must last an entire CPU period, otherwise the
        robot will die in the current game.


     [1mCPU warning percentage:[0m
        When the robot has used up this amount of its CPU time it will
        receive a warning message.


     [1mProcess check interval:[0m
        In ``competition-mode'' this will decide how often the program
        will check for CPU usage.


     [1mLogging frequency:[0m
        To reduce the size of ``log files'' you can increase this
        option. With this option, ``robot position info'' are only
        logged every n:th ``update interval''.



  [1m5.6.  Window sizes[0m

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


  [1m5.7.  Miscellaneous options[0m



     [1mArena scale:[0m
        Overall scale of the arena. A value of 2 gives double
        sidelength, i.e., a four times larger area.


     [1mFast forward factor:[0m
        Determines, when ``replaying'', the speed when the fast forward
        button or the rewind button is pressed.


     [1mMax robots allowed simultaneously:[0m
        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).


     [1mBackground colour:[0m
        Background colour and ...


     [1mForeground colour:[0m
        ... foreground colour for the arena.


     [1mColour for RTB messages:[0m
        Colour for the text when RTB sends messages.


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


     [1mArena search path:[0m
        Same as above, but for arena files instead of robots. Here the
        subdirectory is Arenas.



  [1m6.  Arena construction[0m

  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.



  [1m6.1.  Arena commands[0m

  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.


     [1mscale [value][0m
        This value times the ``arena scale'' 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.


     [1mangle_unit [unit][0m
        Switches to the selected angle unit, which can be either of
        degrees or radians. Default is radians.


     [1mboundary [left] [up] [right] [down][0m
        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.


     [1minner_circle [bounce] [hardness] [center_x] [center_y] [radius][0m
        Robots are limited to the inside of this circle.


     [1mcircle [bounce] [hardness] [center_x] [center_y] [radius][0m
        Circle shaped wall.


     [1mline [bounce] [hardness] [thickness] [start_x][0m
        [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.


     [1marc [bnc] [hardn] [thickn] [center_x] [ctr_y][0m
        [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.



     [1mpolygon [bounce] [hardn] [thickn] [number of vertices] ([center_x][0m
        [1m[center_y])...[0m
        This will create a number of circles, connected by lines.



     [1mclosed_polygon [bounce] [hardn] [thickn] [number of vertices][0m
        ([center_x] [center_y])..."  As a polygon, but the first and the
        last vertices are also connected by a line.


     [1mpoly_curve [bnc] [hardn] [thickn] [start_x][0m
        [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.


        [1mL [length][0m
           Draw a line with given length in the current direction.

        [1mT [angle][0m
           Turn the current dircetion.

        [1mA [angle] [radius][0m
           Draw an arc.

        [1mC  [22mFinish by connecting with the starting point.

        [1mQ  [22mQuit.



     [1mexclusion_point [position_x] [position_y][0m
        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.



