This chapter will describe what you need to know in order to build
your own robot. 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 robots point of view, it is
communicating with the server via the standard input and output ports.
This approach mean that the robots can be written in any programming
languages. However, there is one catch, the robot must be able to know
when it has received a message. One solution is to tell the server to
send a signal after sending the message. This requires the robot
program to be able to handle signals. This can be done in many languages including c, c++ and
perl. Another method is to use the libc function select()
to wait until a message has
arrived.
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, there may be possible to make 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 robot 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 are not allowed to spawn child processes and their CPU usage is limited. In this way one robot cannot use up all the CPU.
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 if you find it ugly.
At the beginning of each game the robots
will be sent a number of settings, which can be useful to 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 given information each turn from the radar. 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.
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 (which current isn't implemented), 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.
A warning message can be sent when robot has to be notified on different problems which have occured. Currently five 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.
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.
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.
When receiving the Initialize message with argument 1, indicating that this is the first sequence, you should send both your name and your colour.
See above.
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 is 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 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.