RealTimeBattle User Manual, version 1.0.8

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

Contents

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

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

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

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

5 Options 17 5.1 Environmental options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.2 Robot options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.3 Shot options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.4 Extras options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.5 Time options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.6 Window sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.7 Miscellaneous options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6 Arena construction 22 6.1 Arena commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

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

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 2.1 (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 5 (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 2.3 (Start new tournament window) will give more information.

Replay tournament:

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

Pause:

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

End:

Stops the current tournament.

Options:

Brings up the 2.8 (options window).

Statistics:

Displays the 2.9 (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 2.5 (arena window), the 2.6 (score window) and the 2.7 (message window).

Quit:

Terminates the program.

In 2.1 (debug-mode) there is another set of buttons available. They are intended to help with debugging of robots. Note that you can debug a running process; if you use gdb the command is gdb robot-name

process-number.

Step:

In a 2.2 (paused) game this will move one time step forward. This is very useful when running the robot in a debugger, since otherwise the robot will be flooded with messages.

End game:

This will finish the current game. It has the same effect as a 5.5 (timeout) would have.

Kill marked robot:

In debug-mode, you can mark a robot in the 2.6 (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 2.13 (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 3.11 (tournament) consists of a number of 3.10 (sequences) of 3.9 (games). In each sequence the same robots are playing in all games. Here you select the number of games and sequences as well as the number of robots in each sequence. If you intend to play with all robots every game you are advised to choose only one sequence and instead increase the number of games. The reason is to avoid restarting of the robot processes which can take a while, especially if the number of robots is large.

It is also possible to load a tournament file or save the current tournament. The last tournament played is stored in /tmp/rtb/tmp.tour and is always displayed when this window opens. If it is not available an empty tournament is displayed.

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

2.4 Robots and arena directories

In order for the program to find the robots and arenas you have set two options 5.7 (Robot search path) and 5.7 (Arena search path). The subdirectories Robots and Arenas in the rtb installl directory (default: /usr/local/games/RealTimeBattle), specified at compile-time in the main Makefile, are always searched, regardless of the options, but if you create a new directory, or if you installed RealTimeBattle in some other directory, you need to set these options.

2.5 Arena window

This is where the battle takes place. If you want a more detailed view, use the zoom buttons or press +, - or 0. The robots are visualized as coloured circles with an angle shape showing the radar direction, the thick line is the cannon and the thin line points in the front direction.

2.6 Score window

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

2.7 Message window

Here are messages sent by the robots using 4.5 (Print and Debug) displayed. The most recent messages are displayed at the top. You can clean the window and choose to only see new messages from a particular robot.

2.8 Options window

Here you can change a number of options. In the 5 (Options chapter) you can get detailed information on each option. The changes are not applied until either the apply button or the OK button is pressed.

You can save your options to a file: Save options will save the options to a file of your choice and Save as default will save them to .rtbrc in your home directory.

The Default button will reset all options to their default values.

2.9 Statistics window

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

• statistics on individual Robots,

• the result of a game,

• the sequence total or

• the total of the tournament.

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

2.10 Running without graphics

If you want, you can run RealTimeBattle without any graphics at all. This can be especially useful when currying out a long series of tests or running a competition. To use this option you have two choices: Either you add the flag -g when launching the program, or you disable the graphics at compile time (see the INSTALL file for more information). The latter alternative is useful as the executable gets smaller and therefore faster on low memory machines. It also enables you to run RealTimeBattle on machines which haven’t got gtk+ installed.

When running without graphics you have to give a tournament file, otherwise nothing at all will happen. It is also a good idea to create a log file and/or a statistics file if you want to know the result.

2.11 Tournament files

The tournament file is specified as a 2.1 (command line option). When specified a tournament will automatically begin and end. To save the statistics see section 2.14 (statistics file) for more information. A tournament file consists of five keywords. All of these keywords can be written several times, but keep in mind that only the last one of the keywords that takes a number as argument is counted. All keywords should be followed by a semicolon.

Games/Sequence or g/s:

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

Robots/Sequence or r/s:

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

Sequences or seq:

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

Robots or r:

Takes one or more robot files as its argument. Arenas or a:

Takes one or more arena files as its argument.

File arguments can be one of the following:

Just the file:

This searches the path for the file

Example: Robot:  empty.robot

Full path to the file:

This takes the given file

Example: Arena:  /usr/local/games/RealTimeBattle/Arenas/Circle.arena

All files in path:

This searches the whole path and takes all files found. Example: Arena: *

One specific directory:

This searches the specified directory and takes all files found.

Example: Robot:  /usr/local/games/RealTimeBattle/Robots/*

It is possible to write files more than one time. So if you want three rotate_and_fire.robot. Just write rotate_and_fire.robot three times. This is also true for *. Example tournament file:

R: * Arenas:  Circle.arena Square.arena G/S: 2 r/s:  3 Sequences:  *

2.12 Log files

Sometimes it can be useful to 2.13 (replay) a game and analyze it in detail or just to store for future reference, in this case log files can be useful. Add the flag -l, when starting RealTimeBattle, with the filename as argument to enable this feature and with argument '-', the log is printed to stdout. The format of the log file is as follows: Each line consist of a letter, determining the type of information, followed by a whitespace-separated list of arguments. The following information is given:

Header:

H [games/sequence] [robots/sequence] [sequences] [robots] Arena info:

A [line from the arena file] Game start:

G [sequence number] [game number] Option:

O [option:value] List of robot properties:

L [robot id] [robot colour] [robot name] Robot position info:

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

T [time elapsed] Print message:

P [robot id] [message to print] Cookie:

C [cookie id] [x] [y] Mine:

M [mine id] [x] [y] Shot:

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

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

2.13 Replaying

You can replay a game from its 2.12 (log file) either by giving the 2.1 (command line option) "-r" or from the 2.2 (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 5.7 (fast forward factor).

• Step forward and step backward can be used to study what happens in detail. First, however, the game should be 2.2 (paused).

• With the four bottom buttons you can jump between games and sequences.

2.14 Statistics files

The statistics file is a file used only when a 2.11 (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 2.9 (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 5.1 (roll friction) and slides sideways with a much higher 5.1 (sliding friction). The third slowing down effect is 5.1 (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, 4.5 (acceleration), 4.5 (rotation) and 4.5 (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.

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 4.4 (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 4.5 (maneuver the radar) 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 4.4 (robot coordinates). The behavior is controlled by the option 5.1 (Send robot coordinates).

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 5.3 (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 5.3 (minimal energy) forbids very low energy shots, e.g. you want to remove mines. The 5.3 (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, 5.3 (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.

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, 5.2 (the bounce coefficient, the hardness coefficient and the protection coefficient). On the 5.2 (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.

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 5.4 (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 2.1 (competition-mode). The 5.5 (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 5.5 (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 5.5 (max timestep), 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 3.5 (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 5.5 (time is up).

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 2.3 (number of games) 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 2.1 (competition-mode) 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 2.1 (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 1.5 (bug report). 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 4.5 (Name and Colour) 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 4.2 (Messagetypes.h) for the game_option_type enum. In the 5 (options chapter) you can get more detailed information on each option. The 2.2 (debug level) 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 5.5 (time scale) and 5.5 (max timestep).

Coordinates [x (double)] [y (double)] [angle (double)] Tells you the current robot position. It is only sent if the option 5.1 (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.

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 4.5 (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. 4.5 (Rotate).

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 5.2 (energy levels).

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 4.2 (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 5.5 (CPU warning percentage). Only in 2.1 (competition-mode). MESSAGE_SENT_IN_ILLEGAL_STATE: The message received couldn’t be handled in this state of the program. For example 4.5 (Rotate) is sent before the game has started. UNKNOWN_OPTION: The robot sent a 4.5 (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 5.5 (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.

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 4.4 (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 4.1 (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 4.4 (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 .

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 5.2 (Robot (cannon/radar) max rotate speed).

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 5.2 (Robot max/min acceleration). Brake [portion (double)]

Set the brake. Full brake (portion = 1.0) means that the friction in the robot direction is equal to 5.1 (Slide friction).

Shoot [shot energy (double)]

Shoot with the given energy. 5.3 (The shot options) give more information. Print [message (string)]

Print message on the 2.7 (message window). Debug [message (string)]

Print message on the 2.7 (message window) if in 2.1 (debug-mode). 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 4.4 (warning message) 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 5.2 (robot radius). 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 2.1 (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.

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 2.1 (competition-mode) this will decide how often the program will check for CPU usage. Logging frequency:

To reduce the size of 2.12 (log files) you can increase this option. With this option, 2.12 (robot position info) are only logged every n:th 5.5 (update interval).

5.6 Window sizes

Here you can set the initial sizes for some windows, namely the 2.5 (arena window), the 2.7 (message window), the 2.6 (score window) and the 2.9 (statistics window). You can also set the position for the first three and the 2.2 (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 2.13 (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 2.3 (new tournament) 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 5.7 (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.

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