Realtimebattle-Team-Framework Manual
Author: David Tibbe and Tino Truppel

# Chapter 1.1.1 - What is the Realtimebattle-Server?

RealTimeBattle is a programming game, 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.

Here is a list of features of RealTimeBattle:

- 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.
- Any number of robots can compete simultaneously if allowed by your operating system.
- A simple messaging language is used for communication, which makes it easy to start constructing robots.
- Robots behave like real physical object.
- You can create your own arenas.
- Highly configurable.
- It is distributed under the General Public License (GPL).

Before your work with the RTB-Framework, you should be familiar with the RealTimeBattle Server. You can find the documentation on the RealTimeBattle Homepage.

At the beginning of each sequence (each will take 10ms) 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.

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

`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. The 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 time scale and max timestep.

`Coordinates [x (double)] [y (double)] [angle (double)]`

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.

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

`RotationReached [what has reached(int)]`

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.

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

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

## Messages from robots

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

`Name [name (string)]`

When receiving the Initialize message with argument 1, indicating that this is the first sequence, you should send both your name and your colour.

`Colour [home colour (hex)] [away colour (hex)]`

See above. The colours are like normal football shirts, the home colour is used unless it is already used. Otherwise the away colour or, as a last resort, a non-occupied colour is selected randomly.

`Rotate [what to rotate (int)] [angular velocity (double)]`

Set the angular velocity for the robot, its cannon and/or its radar. Set 'what to rotate' to 1 for robot, 2 for cannon, 4 for radar or to a sum of these to rotate more objects at the same time. The angular velocity is given in radians per second and is limited by Robot (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 (dbl)] [left angle (dbl)] [right angle (dbl)]`

As rotate, but sets the radar and/or the cannon (not available for the robot itself) in a sweep mode.

`Accelerate [value (double)]`

Set the robot acceleration. Value is bounded by Robot 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 Slide friction.

`Shoot [shot energy (double)]`

Shoot with the given energy. The shot options give more information.

`Print [message (string)]`

Print message on the message window.

`Debug [message (string)]`

Print message on the message window if in 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 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.