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.
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:
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'.
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.
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 competition-mode the robot will rapidly run out of CPU-time and die.
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.
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.
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).
Current name of the robot, don't change it if you don't have very good reasons.
Current colour of the robot, change it if you find it ugly. All robots in a team will have the same colour.
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.
This message is sent when the game starts (surprise!)
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.
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.
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.
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.
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.
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.
At the beginning of the game and when a robot is killed the number of remaining robots is broadcasted to all living robots.
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.
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.
Robot died. Do not try to send more messages to the server until the end of the game, the server doesn't read them.
Current game is finished, get prepared for the next!
Exit from the program immediately! Otherwise it will be killed forcefully.
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.
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.
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.
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.
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.
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!
As Rotate, but will rotate relative to the current angle.
As rotate, but sets the radar and/or the cannon (not available for the robot itself) in a sweep mode.
Set the robot acceleration. Value is bounded by Robot max/min acceleration.
Set the brake. Full brake (portion = 1.0) means that the friction in the robot direction is equal to Slide friction.
Shoot with the given energy. The shot options give more information.
Print message on the message window.
Print message on the message window if in debug-mode.
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.
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.